pgbouncer: Validate the Connection Pooler Config
PgBouncer does not offer a pure config-test flag, so the reliable check is to start it once and confirm it parses pgbouncer.ini and binds cleanly.
PgBouncer is the Postgres connection pooler that often fronts a database behind a load balancer. It has no nginx -t equivalent, so CI validates by launching it briefly.
What it does
pgbouncer reads pgbouncer.ini at startup and fails to start if the file is malformed or references a missing auth file or userlist. There is no dedicated config-test flag; the practical validation is starting pgbouncer (in the foreground) and checking it loads without error, then stopping it. A running instance also accepts RELOAD via the admin console.
Common usage
# start in the foreground; a bad config exits non-zero immediately
pgbouncer pgbouncer.ini
# quiet, and reload a running instance from a signal
pgbouncer -R pgbouncer.ini # online restart, reuse sockets
# reload config live via the admin console
psql -p 6432 pgbouncer -c "RELOAD;"Options
| Flag | What it does |
|---|---|
| -d, --daemon | Run in the background as a daemon |
| -R, --reboot | Online restart, take over sockets from a running instance |
| -q, --quiet | Do not log to stdout |
| -v, --verbose | Increase verbosity |
| -u <user> | Switch to this user after binding |
In CI
Since there is no -t, launch pgbouncer in the foreground with a short timeout (timeout 3 pgbouncer pgbouncer.ini) and treat a clean parse plus successful bind as a pass. Point it at a throwaway userlist.txt. For live changes on a running pooler, prefer RELOAD; over a full restart to avoid dropping pooled connections.
Common errors in CI
FATAL: cannot open config file: pgbouncer.ini: No such file or directory means a wrong path. FATAL: syntax error in connection string or "invalid value for parameter" flags a malformed pgbouncer.ini line. FATAL: cannot load auth_file means auth_file or the userlist is missing or unreadable. "bind(): Address already in use" means port 6432 is taken.