Configuration overview¶

PgDog uses the TOML configuration language for its two configuration files:

Both files are required for PgDog to run, but most settings are optional and have reasonable defaults, so a basic PgDog deployment requires very little work to configure:

pgdog.tomlusers.toml

[[databases]]
name = "pgdog"
host = "127.0.0.1"

[[users]]
name = "pgdog"
password = "pgdog"
database = "pgdog"

By default, PgDog looks for both configuration files in the current working directory ($PWD). Alternatively, you can pass the --config=<path> and --users=<path> arguments on startup.

Hot reload¶

Most settings can be reloaded without restarting PgDog. This allows to tweak PgDog at runtime without breaking client or server connections. For settings that require a restart, a note is added to the documentation.

Hot reload can be triggered by sending SIGHUP to the pgdog process or by connecting to the admin database and running the RELOAD command.

Process signalAdmin database

kill -HUP pgdog

PGPASSWORD=admin psql -h 127.0.0.1 -p 6432 -U admin admin -c 'RELOAD'

Units¶

To make things simpler, all units of time are in milliseconds. For example, if you want to set the pool checkout timeout to 5 seconds, convert it to 5000ms instead:

[general]
checkout_timeout = 5_000

TOML syntax

Since PgDog uses TOML, both 5000 and 5_000 are valid numbers. Configuration will fail to load if non-integer values are used, e.g. "5s" or "53.5".

Overrides¶

When reading the configuration files, PgDog will apply settings in the following order:

Values in [[users]] section take the highest priority
Values in [[databases]] are read next
Values in [general] are used by default

For example, if pool_size is set on a user, it will be used over the same setting on the database. If none is set on the user, but it is set on a database, that will take priority over default_pool_size configured in general settings.

Overview¶

Configuration is organized in the following sections:

Name	Description
General	General pooler settings like `host`, `port` and various timeouts.
Databases	PostgreSQL databases proxied by PgDog.
Mirroring	Configuration to mirror databases for testing.
Sharded tables	Configuration for sharding databases.
Plugins	Plugins configuration.
Users	List of users (with passwords) that are allowed to connect to PgDog.
Admin	Admin database settings like admin password.