Hold connections during maintenance with PgBouncer (PAUSE/RESUME) and reload configuration (RELOAD)

Command

psql -h 127.0.0.1 -p 6432 -U pgbouncer -d pgbouncer -X
RELOAD;            -- apply pgbouncer.ini and auth_file changes without dropping connections
PAUSE <db>;        -- closes server connections once running queries/transactions finish; new requests are queued
-- ... maintenance: switchover, PostgreSQL restart, etc. ...
RESUME <db>;
-- If the host in [databases] was changed (after RELOAD), gradually refresh server connections:
RECONNECT <db>;

What it does

PAUSE drains connections on the PostgreSQL side without dropping client connections and queues new queries; RESUME lets the queue flow again. A short primary restart or switchover thus appears to the application as a brief delay rather than errors.

When to use it

During short maintenance windows (switchover, minor version restart, parameter restart) and when applying pgbouncer.ini/userlist changes.

Caution

PAUSE returns only after all active transactions finish; a long-running query holds PAUSE (terminate that session in PostgreSQL if needed). Waiting clients get an error when query_wait_timeout (default 120 s) expires; finish the maintenance within that time. Forgetting RESUME after PAUSE is a full outage. Some settings (listen_addr, listen_port, etc.) do not change with RELOAD and require a restart.