Retener conexiones durante el mantenimiento con PgBouncer (PAUSE/RESUME) y recargar la configuración (RELOAD)

Comando

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>;

Qué hace

PAUSE drena las conexiones del lado de PostgreSQL sin cortar las conexiones de los clientes y pone en cola las consultas nuevas; RESUME deja fluir de nuevo la cola. Así, un reinicio breve del primario o un switchover se percibe en la aplicación como un breve retraso en lugar de errores.

Cuándo usarlo

Durante ventanas de mantenimiento cortas (switchover, reinicio por versión menor, reinicio por parámetros) y al aplicar cambios en pgbouncer.ini/userlist.

Precaución

PAUSE solo vuelve cuando terminan todas las transacciones activas; una consulta larga retiene PAUSE (termine esa sesión en PostgreSQL si es necesario). Los clientes en espera reciben un error cuando vence query_wait_timeout (120 s por defecto); termine el mantenimiento dentro de ese tiempo. Olvidar RESUME después de PAUSE es una caída total. Algunos ajustes (listen_addr, listen_port, etc.) no cambian con RELOAD y requieren reinicio.