Modos do PgBouncer
O pool_mode do PgBouncer decide quando uma conexão de servidor retorna para o pool. O pooling por transação maximiza a densidade; o pooling por sessão maximiza a compatibilidade no PostgreSQL 18.4.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
; pgbouncer.ini
[databases]
appdb = host=127.0.0.1 port=5432 dbname=appdb
[pgbouncer]
pool_mode = transaction
default_pool_size = 50
max_client_conn = 2000Quando usar isso: Escolhendo o modo de pool para um novo serviço ou depurando erros de prepared statement already exists.
Exemplo de Trabalho
-- Modo de sessão: SET e tabelas temporárias persistem pelo tempo de vida da conexão do cliente
SET search_path = app, public;
CREATE TEMP TABLE staging (id int);
-- OK no pooling por sessão até a desconexão
-- Modo de transação: a conexão do servidor pode mudar após COMMIT
BEGIN;
SET LOCAL statement_timeout = '5s';
SELECT count(*) FROM orders;
COMMIT;
-- SET LOCAL é seguro; SET em nível de sessão sem LOCAL é arriscadoVerifique o modo com o administrador do PgBouncer: SHOW CONFIG; -> pool_mode.
O que isso demonstra:
SET LOCALcom escopo de transação vsSETde sessão- Tabelas temporárias exigem modo de sessão (ou evite)
- Por que as suposições padrão dos ORMs importam
Análise Detalhada
Como Funciona
- session - Backend do servidor fixado ao cliente até a desconexão. Maior compatibilidade, menor multiplexação.
- transaction - Backend atribuído por transação; retornado em COMMIT/ROLLBACK. Padrão para OLTP web.
- statement - Backend por instrução (raro); quebra transações multi-instrução e a maioria dos ORMs.
Comparação de Modos
| Modo | Multiplexação | Tabelas temporárias | Instruções preparadas |
|---|---|---|---|
| session | Baixa | Sim | Sim |
| transaction | Alta | Não | Complicado |
| statement | Mais Alta | Não | Quebrado |
Notas SQL
-- Padrão seguro no pooling por transação
BEGIN;
SET LOCAL lock_timeout = '2s';
SELECT * FROM orders WHERE id = 1 FOR UPDATE;
COMMIT;Armadilhas
- LISTEN/NOTIFY em modo de transação - Não confiável entre trocas de backend. Correção: Pool de sessão ou conexão de listener dedicada.
- Locks consultivos entre requisições - Devem usar modo de sessão. Correção: Pool separado para workers de jobs que precisam de locks.
- Migrações de schema via pooler - DDL pode precisar de persistência de sessão. Correção: Conexão de administração direta contornando o pooler.
- Modo statement com Hibernate - Transações quebradas. Correção: Nunca use o modo statement para ORMs.
DEALLOCATE ALLesquecido no checkout - Alguns drivers precisam deserver_reset_query. Correção: Configureserver_reset_query = DISCARD ALLonde apropriado.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| pooling por sessão | ETL pesado com tabelas temporárias no app | Milhares de clientes ociosos |
| RDS Proxy | Multiplexação gerenciada pela AWS | K8s on-premise |
| Conexão direta (sem pool) | Apenas desenvolvimento local | Frota de produção |
FAQs
Modo padrão para APIs web?
transaction com SET LOCAL e sem tabelas temporárias.
O pooling por transação quebra SET do RLS?
Use SET LOCAL dentro da transação ou inicialização da conexão via parâmetros de inicialização.
server_reset_query?
DISCARD ALL limpa o estado da sessão entre transações no modo de transação.
instruções preparadas?
Veja a página dedicada; frequentemente desabilite no ORM para o modo de transação.
múltiplos bancos de dados?
Stanza de banco de dados do PgBouncer por alvo; pools isolados por db/usuário.
TLS para Postgres?
Pooler conecta TLS upstream; clientes TLS para pooler.
query de autenticação?
userlist.txt ou auth_query para SCRAM com PostgreSQL 18.
pooling por transação e COPY?
COPY em transação geralmente OK dentro de um único bloco de transação.
failover?
Atualização de configuração do Pooler ou DNS para o novo primário; apps reconectam ao pooler.
Próximo?
Armadilhas de instruções preparadas em modo de transação.
Relacionados
- Instruções Preparadas e Pooling - Correções de ORM
- Noções Básicas de Pooling - Por que fazer pool
- Papel e Tempo Limite por Pool - Separação de pools
- Melhores Práticas de Pooling - Operações
Versões da Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, e PostGIS 3.5+.