PgBouncer pool de transações explicado

O PgBouncer oferece três modos, que diferem apenas quando a conexão do servidor Postgres retorna ao pool comum. A documentação oficial os nomeia session, transaction e statement (pgbouncer.org/features.html, seção “Modos de pooling”, acessado em 24 de agosto de 2026).

O modo de sessão é o mais permissivo, mas o menos eficaz em escalabilidade: uma conexão Postgres permanece reservada para um cliente enquanto permanecer conectado, mesmo que não faça nada entre duas solicitações. O modo de instrução é reservado para casos muito específicos (proxy somente leitura, verificações de integridade) e até quebra transações explícitas clássicas. O modo de transação é o compromisso que domina na prática para uma API REST: cada solicitação HTTP geralmente corresponde a uma única transação curta do Postgres.

No modo de transação, o PgBouncer apenas conecta uma conexão de servidor a um cliente quando este abre uma transação e a retorna ao pool após COMMIT ou ROLLBACK. Entre duas transações, o mesmo cliente pode ser transferido para uma conexão de servidor completamente diferente.

Concretamente, com um default_pool_size de 20, o PgBouncer pode absorver várias centenas de clientes simultâneos que, a qualquer momento, têm apenas algumas transações em andamento. É esta relação que justifica o modo de transação para uma API REST com alto tráfego, mas transações curtas: o recurso raro (uma conexão Postgres, cara em memória do lado do servidor) só é ocupado pelo tempo estritamente necessário.

[pgbouncer]
listen_port = 5432

; La connexion serveur est libérée dès la fin de chaque transaction
pool_mode = transaction

default_pool_size = 80
max_client_conn = 1000

; Ne pas utiliser avec des sessions stateful (SET, advisory locks, LISTEN/NOTIFY)

Este último comentário resume a essência: o modo de transação funciona porque quebra deliberadamente o link entre "minha sessão de aplicativo" e "minha conexão Postgres". Tudo baseado neste link quebra. A próxima seção lista exatamente o quê.

A documentação oficial do PgBouncer lista explicitamente os recursos do PostgreSQL que perdem seu significado assim que uma conexão de servidor pode ser reciclada entre duas solicitações do mesmo cliente.

A maioria dos drivers Postgres modernos prepara solicitações nomeadas no lado do protocolo por padrão, sem que o código do aplicativo solicite explicitamente. Isto é precisamente o que torna esta armadilha difícil de prever.

Uma instrução preparada por protocolo é nomeada e armazenada em cache em uma conexão de servidor específica, no momento de Parse. No modo transação, esta conexão pode ser reatribuída a outro cliente entre duas solicitações do mesmo cliente lógico. Se o driver reproduzir o mesmo nome de instrução em uma conexão onde nunca foi preparado, o Postgres responderá com um erro explícito, normalmente prepared statement "sqlx_s_N" does not exist para um cliente sqlx. O comportamento é intermitente: depende do desempenho das conexões sob carga, e não de um bug determinístico reproduzível em cada chamada.

A correção do lado do cliente é a mesma, independentemente do idioma: desabilite o cache de instruções preparadas nomeadas ou force consultas não nomeadas para qualquer pool que cruze um pooler no modo de transação. No Rust com sqlx, passa por statement_cache_capacity(0) nas opções de conexão.

let connect_options = url
    .parse::<PgConnectOptions>()?
    .statement_cache_capacity(0);

// Equivalentes: asyncpg -> Statement_cache_size=0, pgjdbc -> prepareThreshold=0

Desde a versão 1.21, o PgBouncer alivia parte do problema do lado do servidor: ele pode seguir instruções preparadas por protocolo em modo de transação e prepará-las dinamicamente na conexão atribuída, com um cache LRU por conexão cujo tamanho é ajustado via max_prepared_statements. Isso reduz o número de falhas, mas não o isenta de desabilitar o cache do cliente em um pool multilocatário onde o search_path muda de uma solicitação para outra: um plano em cache congela o identificador interno (OID) da tabela resolvida no momento de Parse, e reproduzi-lo sob outro esquema pode retornar dados do locatário errado em vez de um simples erro.

O repositório Aurabase implanta PgBouncer como pool_mode=transaction na frente do plano de dados compartilhado (deploy/helm/aurabase/templates/infra/pgbouncer.yaml) e um Pooler CNPG configurado de forma idêntica na frente de cada instância Postgres dedicada de um locatário (deploy/cnpg/tenant-pooler.yaml). Ambos os caminhos aplicam a mesma disciplina descrita acima.

O código-fonte documenta um motivo de segurança específico para esta escolha, não apenas um motivo de estabilidade. Os pools Postgres compartilhados entre locatários posicionam um search_path diferente por projeto em conexões reutilizadas. Uma instrução preparada em cache congela o OID da tabela resolvida no momento de Parse; reproduzi-lo para outro locatário na mesma conexão executaria a consulta no esquema do primeiro locatário, um desvio de isolamento, não apenas um erro de aplicativo. statement_cache_capacity(0) é, portanto, aplicado sem exceção, inclusive em instâncias dedicadas que também passam por um Pooler CNPG em modo de transação.

Medida de higiene da segunda sessão: quando cada conexão retorna ao pool, um gancho executa DISCARD ALL (redefinindo configurações, desalocando instruções preparadas no lado do servidor, liberando bloqueios de aconselhamento, limpando cursores e tabelas temporárias). Sem esse gancho, um resíduo de sessão colocado por uma solicitação anterior poderia vazar na próxima solicitação de um locatário diferente, reutilizando a mesma conexão reciclada.

Exceção aceita: instâncias PostgREST dedicadas permanecem em conexão direta com o primário, sem passar pelo pooler. O recarregamento do esquema PostgREST depende de LISTEN/NOTIFY, que assume uma conexão persistente, exatamente a funcionalidade que o modo de transação quebra (detalhe já documentado em nosso artigo sobre Compatibilidade do PostgREST no Aurabase). As configurações de RLS por solicitação são passadas para SET LOCAL dentro de uma transação explícita, a única maneira de permanecer compatível com um pool que pode alterar as conexões do servidor em qualquer COMMIT (consulte nosso artigo sobreisolamento RLS multilocatário).

Uma pequena lista de verificação, aplicável a qualquer back-end que esteja mudando de uma conexão direta do Postgres para um PgBouncer no modo de transação.

1. Audite o código do aplicativo. Procure SET, LISTEN/NOTIFY, bloqueios de aconselhamento de sessão, cursores WITH HOLD e tabelas temporárias reutilizadas entre consultas.
2. Substitua SETs de sessão por SETs LOCAL em uma transação explícita. Esta é a única configuração que sobrevive adequadamente à reciclagem de conexão, porque ela é limpa em COMMIT/ROLLBACK em vez de vazar na próxima conexão.
3. Desative o cache de instruções preparadas do lado do driver se o seu conjunto atravessar o pooler e o esquema ou a função mudar de uma solicitação para outra. O custo do desempenho é real, mas mensurável, e muito inferior ao risco de fuga entre inquilinos.
4. Isole as conexões que realmente precisam do modo de sessão (migrações, scripts administrativos, qualquer coisa que dependa de LISTEN/NOTIFY) para uma conexão direta sem pooler, em vez de renunciar ao modo de transação para todos os outros tráfegos.
5. Tamanho default_pool_size e max_client_conn em relação ao max_connectionsreal do Postgres, não por uma figura arbitrária copiada de outro projeto.
6. Teste sob carga real, não apenas teste de fumaça. Erros de instrução preparada e vazamentos de configurações de sessão quase nunca aparecem em uma única conexão local.
7. Monitore SHOW POOLS e SHOW STATS no console de administração do PgBouncer uma vez em produção, para detectar a saturação do pool antes que ela se torne visível no lado do cliente.

Não, mas é a escolha padrão correta para a grande maioria das APIs REST. O modo de sessão permanece preferível para um aplicativo legado fortemente dependente de funcionalidades de sessão que você não pode refatorar rapidamente ou para tráfego baixo onde o ganho de pooling não compensa o esforço de migração.

O PgBouncer também não é a única implementação deste modelo de pooling: Supavisor (Supabase) e PgCat são duas alternativas recentes, com diferentes compensações na distribuição de carga e clustering. Veja nossa comparação detalhada, PgBouncer vs Supavisor vs PgCat, para escolher entre os três dependendo de sua topologia.

As perguntas que surgem com mais frequência quando o modo de transação é ativado na produção.