Segurar conexões durante a manutenção com PgBouncer (PAUSE/RESUME) e recarregar a configuração (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>;

O que faz

PAUSE esvazia as conexões do lado do PostgreSQL sem derrubar as conexões dos clientes e enfileira as novas consultas; RESUME libera a fila novamente. Assim, um restart curto do primário ou um switchover aparece para a aplicação como um breve atraso em vez de erros.

Quando usar

Durante janelas de manutenção curtas (switchover, restart de versão minor, restart por parâmetro) e ao aplicar mudanças no pgbouncer.ini/userlist.

Atenção

PAUSE só retorna depois que todas as transações ativas terminam; uma consulta longa segura o PAUSE (encerre essa sessão no PostgreSQL se necessário). Os clientes em espera recebem um erro quando query_wait_timeout (padrão 120 s) expira; conclua a manutenção dentro desse tempo. Esquecer o RESUME após o PAUSE é uma indisponibilidade total. Algumas configurações (listen_addr, listen_port etc.) não mudam com RELOAD e exigem restart.