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 further information.

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";
    connections {
        max 10;
        idle-timeout 5m;
        min 2;
        min-timeout 1s;
        min-retry 250ms;
    }
}

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

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

connections {
    max 25;           # Maximum pool size.
    idle-timeout 5m;  # Idle connection timeout.
    min 2;            # Keep two connections ready.
    min-timeout 1s;   # Warm-pool maintenance probe timeout.
    min-retry 250ms;  # Delay between warm-pool maintenance retries.
}

Parameters:

• max: Maximum pool size. Default: 10.
• idle-timeout: Maximum time an idle connection stays in the pool before it is closed. Accepts duration units. Default: 5m.
• min: Minimum number of connections Radiator keeps open at all times. Default: 0.
• min-timeout: Maximum time Radiator waits for a min maintenance probe to establish a connection before the probe is treated as failed. Accepts duration units. Default: 1s.
• min-retry: Delay between min maintenance probe attempts. Accepts duration units. Default: 250ms.

min must not exceed max. min-timeout and min-retry only apply when min is greater than 0.

See connections and Backend Load Balancing.

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 certificates configuration reference for certificate and key setup 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.