PgBouncer com Node.js adiciona um pooler leve entre a aplicação e o PostgreSQL. Ele reduz o número de conexões reais abertas no banco e ajuda ambientes com muitas réplicas de aplicação, funções ou deploys frequentes.
Por que usar
Cada processo Node.js pode manter seu próprio pool. Com dezenas de pods, a soma cresce rapidamente e pode exceder max_connections. O PgBouncer multiplexa conexões de clientes sobre um conjunto menor de conexões do servidor.
Modos de pooling
- session: uma conexão do servidor fica associada ao cliente durante toda a sessão;
- transaction: a conexão é devolvida após cada transação;
- statement: devolvida após cada statement, com restrições maiores.
Transaction pooling é comum, mas muda suposições sobre estado de sessão.
Configuração do node-postgres
const pool = new Pool({
connectionString: process.env.PGBOUNCER_URL,
max: 10,
connectionTimeoutMillis: 2_000,
idleTimeoutMillis: 30_000
});Ainda mantenha um pool pequeno na aplicação. PgBouncer não elimina a necessidade de limites locais.
Transações
Uma transação deve usar o mesmo client adquirido do pool até commit ou rollback.
const client = await pool.connect();
try {
await client.query('BEGIN');
await client.query('UPDATE accounts SET ...');
await client.query('COMMIT');
} catch (error) {
await client.query('ROLLBACK');
throw error;
} finally {
client.release();
}Estado de sessão
No modo transaction, não dependa de estado persistente entre transações, como SET de sessão, temporary tables ou advisory locks de sessão. Prefira SET LOCAL dentro de transação quando aplicável.
Prepared statements
Verifique compatibilidade da versão e do driver com prepared statements no modo escolhido. Nomes fixos e estado de conexão podem exigir configuração específica.
Tamanho dos pools
Considere:
- conexões máximas do PostgreSQL;
- reservas administrativas;
- quantidade de bancos e usuários;
- concorrência real de queries;
- tempo médio de transação.
Fila no PgBouncer
Quando não há conexão de servidor disponível, clientes esperam. Monitore tempo de espera e defina timeouts para evitar filas invisíveis.
Timeouts
Configure prazo de aquisição no cliente, query_timeout quando necessário e limites do PgBouncer. Um timeout em uma camada não substitui os demais.
Multi-tenancy
Um banco ou usuário por tenant pode multiplicar pools internos do PgBouncer. Avalie o modelo e evite milhares de combinações ociosas. Veja Multi-Tenancy no Node.js.
Observabilidade
Use os comandos administrativos para acompanhar clientes ativos, conexões do servidor, espera e pools. Correlacione com métricas do PostgreSQL e da aplicação.
Alta disponibilidade
PgBouncer não decide sozinho qual servidor é primário. Combine com DNS, proxy ou mecanismo de failover e teste reconexão após troca de primário.
Erros comuns
- manter pool enorme na aplicação e no PgBouncer;
- usar estado de sessão no transaction pooling;
- não limitar espera;
- não reservar conexões administrativas;
- ignorar prepared statements;
- transações longas;
- não monitorar fila.
Conclusão
PgBouncer com Node.js protege PostgreSQL do excesso de conexões e melhora eficiência em ambientes com muitas instâncias. Use pools locais pequenos, transações curtas e código compatível com o modo de pooling.
Consulte a documentação oficial do PgBouncer, a documentação do node-postgres e Connection Pooling no Node.js.
