Skip to content

Database settings

Database settings configure which databases PgDog is managing. This is a TOML list of hosts, ports, and other settings like database roles (primary or replica).

For each database instance, add a [[databases]] entry to pgdog.toml. For example:

[[databases]]
name = "prod"
host = "10.0.0.1"
port = 5432
shard = 0

[[databases]]
name = "prod"
host = "10.0.0.2"
port = 5432
role = "replica"
shard = 0

name

Name of your database. Clients that connect to PgDog will need to use this name to refer to the database. For multiple entries that are part of the same cluster, use the same value.

Default: none (required)

host

IP address or DNS name of the machine where the PostgreSQL server is running. For example:

  • 10.0.0.1
  • localhost
  • prod-primary.local-net.dev

Default: none (required)

port

The port PostgreSQL is running on. More often than not, this is going to be 5432.

Default: 5432

role

Type of role this host performs in your database cluster. This can be primary for primary databases that serve writes (and reads), replica for PostgreSQL replicas that can only serve reads, or auto to let PgDog decide (see failover for more details).

Default: primary

database_name

Name of the PostgreSQL database on the server PgDog will connect to. If not set, this defaults to name.

Default: none (defaults to name)

user

Name of the PostgreSQL user to connect with when creating backend connections from PgDog to Postgres. If not set, this defaults to name in users.toml. This setting is used to override users.toml configuration values.

Default: none (see users.toml)

password

Password to use when creating backend connections to PostgreSQL. If not set, this defaults to password in users.toml. This setting is used to override users.toml configuration values.

Default: none (see users.toml)

shard

The shard number for this database. Only required if your database contains more than one shard. Shard numbers start at 0.

Default: 0

Note

All settings below take priority over values in [general] and [[users]] config sections.

pool_size

Overrides the default_pool_size setting. All connection pools for this database will open at most this many connections to Postgres.

Recommendation

We strongly recommend keeping this value well below the supported connections of the backend database(s) to allow connections for maintenance in high load scenarios.

pooler_mode

Overrides the pooler_mode setting. Connections to this database will use this connection pool mode.

min_pool_size

Overrides the min_pool_size setting. The connection pool will maintain at minimum this many connections.

statement_timeout

This setting configures the statement_timeout connection parameter on all connections to Postgres for this database.

idle_timeout

Overrides the idle_timeout setting. Idle server connections exceeding this timeout will be closed automatically.

read_only

Sets the default_transaction_read_only connection parameter to on on all server connections to this database. Clients can still override it with SET.

server_lifetime

Overrides the server_lifetime setting. Server connections older than this will be closed when returned to the pool.