server
This clause defines a PostgreSQL server to connect to. A single backend can have multiple servers configured for high availability. Each server is identified by a unique name.
See Backend Load Balancing for connection pool behavior, timeout interaction, and high availability tuning guidance.
Example configuration of a single server using a connection URL:
server "primary" {
url "postgresql://radiator:secret@db.example.com:5432/radiator";
}
Example configuration using individual connection parameters (useful when credentials come from environment variables or when TLS is needed):
server "primary" {
host "db.example.com";
port 5432;
database "radiator";
username "radiator";
password "secret";
}
Example configuration with TLS:
server "primary" {
host "db.example.com";
port 5432;
database "radiator";
username "radiator";
password "secret";
tls {
server_ca_certificate "PG_CA";
}
}
Server Options
| Option | Required | Description |
|---|---|---|
url "..." | No | Full PostgreSQL connection URL (alternative to individual options) |
host "..." | No | Database server hostname or IP address |
port N | No | Database server port. Default: 5432 |
database "..." | No | Database name to connect to |
username "..." | No | Username for authentication |
password "..." | No | Password for authentication |
connections N | No | Maximum number of connections in the pool. Default: 10. See connections. |
min-connections N | No | Minimum connections kept open at all times (warm floor). Default: 2. Must not exceed connections. See connections. |
idle-timeout N | No | Maximum time an idle connection above min-connections stays in the pool. Default: 5m. See idle-timeout. |
priority N | No | Server selection priority (0 = highest). Default: 0. Range: 0-255 |
tls { ... } | No | TLS configuration for encrypted connections |
service-level-objective { ... } | No | Health monitoring thresholds. See Service Level Objective. |
url
Specifies a complete PostgreSQL connection URL as an alternative to specifying individual connection parameters.
PostgreSQL URL format:
postgresql://[username[:password]@][host][:port][/database][?param1=value1&...]
When url is specified, the other individual connection parameters (host, port, database, username, password) are ignored.
host
Hostname or IP address of the PostgreSQL server. If not set, defaults to the PostgreSQL default (localhost or the value of the PGHOST environment variable).
port
TCP port of the PostgreSQL server.
Default: 5432
database
Name of the database to connect to.
username
Username for database authentication.
password
Password for database authentication.
connections
Maximum number of connections Radiator will maintain in the pool for this server.
Default: 10
See connections and min-connections and Backend Load Balancing.
min-connections
Minimum number of connections Radiator keeps open at all times.
Default: 2
Must not exceed connections.
See connections and min-connections and Backend Load Balancing.
idle-timeout
Maximum time an idle connection stays in the pool before it is closed. Accepts duration units.
Default: 5m
priority
Controls server selection order when multiple servers are configured. Lower values indicate higher priority (0 = highest priority). Servers with equal priority are tried in alphabetical order by name.
Default: 0 Range: 0-255
See Backend Load Balancing for details and examples.
tls
Enables TLS for the connection to the PostgreSQL server. See the TLS configuration article for full details.
service-level-objective
Configures automatic health monitoring for the server. When the failure rate is exceeded, the server is marked as degraded and temporarily skipped during server selection. See the Service Level Objective documentation for details.
service-level-objective {
failure-rate 3/5;
initial-backoff-period 3s;
max-backoff-period 30s;
}
These are the default values. When server-selection is configured, they are applied
automatically to any server without an explicit service-level-objective block.