Infraestrutura
Como configurar PgBouncer em VPS sem gargalos
Aprenda como configurar PgBouncer em VPS, escolher o modo de pool, proteger credenciais, monitorar conexões e evitar limites do PostgreSQL em produção real.
Resposta direta
Para configurar PgBouncer em uma VPS, instale o pacote do sistema, defina o PostgreSQL em [databases], configure autenticação SCRAM, escolha o modo de pool e direcione a aplicação para a porta 6432. O modo transaction costuma ser o ponto de partida para APIs, sites e workers porque devolve a conexão ao pool no fim de cada transação. Uma configuração inicial razoável para um PostgreSQL com max_connections = 100 é limitar o PgBouncer a 500 clientes, manter de 20 a 40 conexões por combinação de banco e usuário e reservar conexões para administração. Esses números não são universais. Eles devem ser ajustados com SHOW POOLS, tempo de espera, uso de CPU, memória e comportamento real das consultas.
Resumo rápido
- O PgBouncer mantém poucas conexões persistentes com o PostgreSQL e atende muitos clientes por meio de um pool.
- A porta padrão do PgBouncer é 6432, enquanto o PostgreSQL normalmente escuta na 5432.
transactionatende a maioria das APIs, mas exige cuidado com estado de sessão, tabelas temporárias e prepared statements.- Autenticação
scram-sha-256é preferível a senhas em texto puro ou hashes MD5 legados. max_client_connnão deve ser confundido com a quantidade de conexões abertas no banco.SHOW POOLS,SHOW STATSe métricas do PostgreSQL ajudam a encontrar filas e pools mal dimensionados.- PgBouncer não substitui backup, réplica, proxy de failover ou monitoramento do servidor.
Como o PgBouncer reduz conexões no PostgreSQL
Abrir uma conexão PostgreSQL tem custo. O servidor autentica o usuário, negocia parâmetros e cria um processo de backend para atender aquele cliente. Em uma API pequena, com 10 ou 20 conexões estáveis, isso raramente vira um problema. O cenário muda quando quatro réplicas da aplicação abrem 30 conexões cada, três workers mantêm outros 20 clientes e tarefas agendadas criam conexões curtas. O total teórico chega a 180 antes de considerar ferramentas administrativas ou picos de deploy.
O PgBouncer fica entre a aplicação e o PostgreSQL. Os clientes se conectam ao PgBouncer na porta 6432, mas o proxy mantém um conjunto menor de conexões reais na porta 5432. Se 300 requisições concorrentes executarem consultas de 50 ms, elas não precisam ocupar 300 backends durante todo o ciclo HTTP. Podem compartilhar, por exemplo, 30 conexões de servidor, desde que a taxa de chegada e a duração das transações não produzam uma fila longa.
O caminho de uma conexão
Em uma instalação na mesma VPS, o fluxo mais simples é aplicação -> 127.0.0.1:6432 -> 127.0.0.1:5432. Esse desenho reduz exposição de rede e evita adicionar latência relevante. Quando banco e aplicações ficam em máquinas separadas, o PgBouncer pode ser executado perto da aplicação ou perto do banco. A decisão depende da topologia, da quantidade de instâncias e do mecanismo de failover.
O pool não torna consultas lentas mais rápidas. Uma transação que leva 12 segundos continuará ocupando uma conexão durante esse período. O ganho aparece na reutilização dos backends e no controle da concorrência. Antes de aplicar o tutorial, compensa revisar o dimensionamento apresentado no conteúdo sobre VPS para banco PostgreSQL, pois memória insuficiente, disco saturado e consultas sem índice não são corrigidos pelo PgBouncer.
Quando o pool começa a fazer diferença
Dois exemplos são comuns. Uma aplicação serverless pode criar centenas de conexões curtas durante um pico, mesmo com poucas consultas por execução. Já um monólito com pool local mal configurado pode manter 100 conexões ociosas por instância. Nos dois casos, o PgBouncer atua como limite central. Ele reduz backends ociosos e coloca clientes excedentes em espera, em vez de deixar o PostgreSQL falhar imediatamente com too many connections.
Como preparar e instalar o PgBouncer na VPS
Para uma instalação pequena, PgBouncer consome poucos recursos em comparação com o PostgreSQL. Uma VPS com 2 vCPUs e 4 GB de RAM pode atender uma aplicação modesta com banco e proxy na mesma máquina, desde que o conjunto de dados e as consultas caibam nesse perfil. Em ambientes com várias aplicações ou tráfego intenso, 4 vCPUs e 8 GB de RAM oferecem mais margem, mas a escolha deve considerar o banco, não apenas o pooler.
Antes da instalação, confirme a versão do sistema e faça backup dos arquivos que serão alterados. Os comandos abaixo atendem distribuições baseadas em Ubuntu e Debian:
sudo apt update
sudo apt install pgbouncer
pgbouncer --version
O pacote normalmente cria /etc/pgbouncer/pgbouncer.ini e /etc/pgbouncer/userlist.txt. Caminhos e usuário do serviço podem variar entre versões da distribuição, então confira systemctl cat pgbouncer antes de mudar permissões. Também confirme se o PostgreSQL responde localmente com sudo -u postgres psql.
Primeira configuração do serviço
Uma base segura para uma única aplicação pode começar assim:
[databases]
appdb = host=127.0.0.1 port=5432 dbname=appdb
[pgbouncer]
listen_addr = 127.0.0.1
listen_port = 6432
unix_socket_dir = /var/run/postgresql
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
max_client_conn = 500
default_pool_size = 30
min_pool_size = 5
reserve_pool_size = 10
reserve_pool_timeout = 5
server_idle_timeout = 600
query_wait_timeout = 120
admin_users = pgbouncer_admin
stats_users = pgbouncer_stats
log_connections = 1
log_disconnections = 1
Nesse exemplo, o PgBouncer aceita somente conexões locais. max_client_conn = 500 representa clientes conectados ao proxy, não 500 backends no PostgreSQL. O default_pool_size = 30 limita o pool padrão de cada combinação entre banco e usuário. Se três usuários acessarem dois bancos, poderão existir vários pools, e não apenas 30 conexões totais.
Valide a sintaxe antes de reiniciar. Depois, acompanhe o log para identificar permissões ou opções incompatíveis com a versão instalada:
sudo systemctl restart pgbouncer
sudo systemctl enable pgbouncer
sudo systemctl status pgbouncer
sudo journalctl -u pgbouncer -n 100 --no-pager
Teste primeiro com psql -h 127.0.0.1 -p 6432 -U app_user appdb. Se a aplicação estiver na mesma máquina, troque a porta da string de conexão de 5432 para 6432 sem alterar o host. Mantenha uma forma restrita de acesso direto à porta 5432 para manutenção. Isso evita ficar bloqueado caso o pooler apresente erro de configuração.
Autenticação, TLS e proteção das credenciais
O arquivo userlist.txt associa usuários a segredos aceitos pelo PgBouncer. Não copie uma senha real para histórico de shell, repositório Git ou imagem Docker. Com PostgreSQL configurado para password_encryption = 'scram-sha-256', é possível usar o segredo SCRAM armazenado pelo próprio banco. Um administrador pode consultar o valor de rolpassword de forma controlada e transferi-lo para o arquivo com permissões restritas.
A estrutura esperada tem usuário e segredo entre aspas:
"app_user" "SCRAM-SHA-256$..."
"pgbouncer_stats" "SCRAM-SHA-256$..."
O trecho com reticências é apenas ilustrativo. Gere credenciais próprias, use um usuário sem privilégios administrativos para a aplicação e proteja o arquivo:
sudo chown postgres:postgres /etc/pgbouncer/userlist.txt
sudo chmod 640 /etc/pgbouncer/userlist.txt
O proprietário correto pode ser diferente se o serviço executar com outro usuário. Confirme a unidade do systemd antes de aplicar chown. Em ambientes com muitos usuários ou rotação frequente, auth_query evita sincronizar manualmente cada segredo. Essa opção consulta uma função controlada no PostgreSQL, mas precisa ser implementada com cuidado para não expor hashes a contas comuns.
Acesso remoto e criptografia
Se somente processos locais usam o pool, listen_addr = 127.0.0.1 é a escolha mais simples. Para receber conexões de outras VPS, prefira uma rede privada, libere a porta 6432 apenas para os IPs das aplicações e mantenha a 5432 fechada ao público. Uma regra genérica de firewall deve permitir SSH a partir de uma origem administrativa conhecida e PgBouncer apenas a partir da sub-rede interna.
Em uma rede que não seja totalmente confiável, configure TLS no lado cliente com client_tls_sslmode = require, certificado e chave do servidor. Para a conexão entre PgBouncer e PostgreSQL, use server_tls_sslmode = verify-full e uma autoridade certificadora válida. require cifra o tráfego, mas verify-full também valida identidade e nome do host.
Dois testes ajudam a evitar surpresas. Primeiro, tente conectar com um usuário inexistente e confirme que a autenticação falha sem revelar detalhes excessivos. Depois, tente acessar a porta 6432 a partir de um IP não autorizado. O firewall deve bloquear a tentativa antes que ela alcance o processo. Segurança aqui depende da combinação entre SCRAM, privilégios mínimos, TLS, rede privada e atualização regular dos pacotes.
Qual modo de pool escolher para cada aplicação
A escolha de pool_mode define quando uma conexão de servidor volta ao conjunto disponível. Essa decisão afeta compatibilidade e capacidade. Alterar o modo sem testar pode causar erros difíceis de reproduzir, principalmente quando frameworks guardam estado na sessão ou usam prepared statements nomeados.
| Modo | Quando libera a conexão | Compatibilidade | Uso mais comum |
|---|---|---|---|
session | Quando o cliente desconecta | Alta, preserva estado de sessão | Sistemas legados, sessões longas e ferramentas administrativas |
transaction | Ao terminar COMMIT ou ROLLBACK | Média, exige aplicação sem dependência de sessão | APIs HTTP, sites, workers e microsserviços |
statement | Ao terminar cada comando SQL | Baixa, não aceita transações com vários comandos | Consultas simples e cenários especializados |
Session pooling
No modo session, cada cliente fica associado ao mesmo backend enquanto permanecer conectado. Ele aceita melhor comandos como SET, tabelas temporárias, bloqueios consultivos de sessão e LISTEN. O custo é uma consolidação menor. Se 150 clientes mantêm conexões abertas, o banco pode precisar de até 150 backends.
Transaction pooling
No modo transaction, o backend é devolvido após cada transação. É comum usar esse modo em Django, Laravel, Rails, Node.js e serviços Java, desde que o comportamento seja validado. Um exemplo problemático ocorre quando a aplicação executa SET search_path uma vez e espera que a configuração permaneça nas consultas seguintes. Outro aparece com tabelas temporárias que precisam sobreviver entre transações.
Versões recentes do PgBouncer oferecem suporte controlado a prepared statements nomeados por meio de max_prepared_statements, mas a compatibilidade depende da versão e do driver. Não presuma que uma configuração usada em uma versão antiga terá o mesmo comportamento após atualização. Teste migrações, ORM, transações e jobs em um ambiente de homologação.
Statement pooling
O modo statement entrega a maior reutilização, porém impede transações com múltiplas instruções. Uma sequência de débito e crédito que precisa ser atômica não deve usá-lo. Para a maioria das aplicações de negócio, transaction é mais equilibrado.
O pool do cliente também precisa de ajuste. Atrás do PgBouncer, configurar 50 conexões em cada uma de dez instâncias apenas move o excesso para a porta 6432. Comece com 5 a 10 conexões por processo. Em SQLAlchemy, NullPool pode delegar o pooling ao PgBouncer. Em Django, CONN_MAX_AGE = 0 reduz sessões persistentes. No driver pg do Node.js, um max entre 5 e 10 por instância costuma ser um ponto inicial, nunca uma garantia universal.
Como dimensionar os pools sem sobrecarregar o banco
O dimensionamento começa no PostgreSQL. Suponha max_connections = 100. Reserve de 10 a 20 conexões para administração, replicação, monitoramento e tarefas de manutenção. O restante, entre 80 e 90, pode ser distribuído entre pools. Se a aplicação usa um banco e um usuário, default_pool_size = 30 mais reserve_pool_size = 10 mantém margem. Se existem quatro usuários independentes, o limite potencial cresce porque cada combinação de banco e usuário forma um pool.
Uma aproximação útil é multiplicar o número de combinações ativas por default_pool_size, somar os pools de reserva e acrescentar conexões diretas. Com três combinações e 20 conexões por pool, o consumo base pode chegar a 60. Mais 10 de reserva e 15 de administração levam o teto planejado a 85. Essa conta precisa ser confrontada com SHOW POOLS e pg_stat_activity, pois nem todos os pools ficam ativos ao mesmo tempo.
Não tente resolver filas elevando o pool indefinidamente. Em uma VPS com 2 vCPUs, permitir 100 consultas pesadas simultâneas pode aumentar troca de contexto, I/O e tempo médio de resposta. Às vezes, 20 conexões terminam mais trabalho por segundo do que 80. Faça um teste de carga com consultas representativas, registre percentis de latência e acompanhe CPU, memória, espera por disco e bloqueios.
max_client_conn também influencia descritores de arquivos. Uma configuração com 2.000 clientes pode exigir mais de 2.000 descritores, somando sockets de clientes, servidores e arquivos internos. Confira ulimit -n no contexto do serviço e, se necessário, defina LimitNOFILE em um override do systemd. Reinicie e valide o limite efetivo com systemctl show pgbouncer -p LimitNOFILE.
Dois cenários ilustram o ajuste. Uma API com 100 requisições por segundo e transações de 20 ms pode funcionar com 20 a 30 backends. Um relatório que mantém cada transação por 15 segundos pode ocupar todo o pool com poucos usuários. Nesse caso, separe relatórios em outro usuário ou banco lógico para criar um pool próprio, aplique timeouts e evite que consultas analíticas bloqueiem o tráfego transacional.
Monitoramento e solução de problemas
O PgBouncer oferece um banco administrativo virtual. Conecte-se usando um usuário listado em admin_users ou stats_users, sem colocar a senha no comando:
psql -h 127.0.0.1 -p 6432 -U pgbouncer_stats pgbouncer
Dentro do console, SHOW POOLS; exibe clientes ativos, clientes em espera, servidores ativos e servidores ociosos. SHOW STATS; apresenta transações, consultas, bytes e tempos médios. SHOW CLIENTS; e SHOW SERVERS; ajudam a localizar conexões antigas. Restrinja essas interfaces, pois elas revelam usuários, bancos, endereços e detalhes operacionais.
O indicador mais direto de saturação é cl_waiting persistente. Um pico curto durante deploy pode ser aceitável. Uma fila contínua, acompanhada de sv_active no limite, indica que o pool está ocupado. Antes de aumentar default_pool_size, procure transações longas, consultas bloqueadas e código que abre uma transação antes de executar operações externas. Uma chamada HTTP de cinco segundos dentro de uma transação segura o backend sem produzir trabalho no banco.
O erro no more connections allowed pode apontar para max_client_conn, enquanto too many connections for role pode vir de um limite no próprio PostgreSQL. Falhas password authentication failed sugerem segredo SCRAM desatualizado, nome de usuário divergente ou regra incompatível em pg_hba.conf. Já desconexões após deploy podem ser investigadas com SHOW CONFIG, logs do systemd e teste direto na porta 5432.
Integre os números do pooler às métricas do sistema. O artigo sobre monitoramento com Grafana e Prometheus ajuda a montar painéis para CPU, memória, disco e alertas. Um alerta prático pode disparar quando cl_waiting permanecer acima de zero por cinco minutos, quando a utilização de servidores ultrapassar 90% ou quando o tempo médio de consulta subir junto com espera de disco.
PgBouncer também não implementa alta disponibilidade do PostgreSQL sozinho. Se o banco primário mudar de endereço, o pooler precisa descobrir o novo destino por DNS, IP virtual ou proxy apropriado. O planejamento descrito em VPS para alta disponibilidade e failover complementa essa camada. Durante uma troca, clientes podem precisar repetir transações interrompidas, então a aplicação deve tratar reconexão e idempotência.
Recomendações por perfil
A configuração inicial deve refletir o número de processos, o comportamento das transações e a capacidade do PostgreSQL. Copiar valores de um servidor maior costuma apenas esconder o gargalo até o próximo pico. Os perfis abaixo servem como ponto de partida para teste, não como promessa de capacidade.
Desenvolvedor solo
Para uma aplicação pequena na mesma VPS do banco, comece com 2 vCPUs, 4 GB de RAM, listen_addr = 127.0.0.1, pool_mode = transaction, max_client_conn = 100 e default_pool_size = 10. Reserve pelo menos cinco conexões diretas para manutenção. Configure o cliente da aplicação com até cinco conexões e teste migrations, jobs e comandos administrativos pela porta 6432. Ferramentas como pg_dump podem acessar a 5432 localmente para evitar incompatibilidades. Mesmo nesse perfil, mantenha backup externo e teste restauração. Um snapshot da VPS não substitui uma cópia consistente do banco.
Equipe com vários serviços
Quando API, workers e rotinas agendadas compartilham o PostgreSQL, use usuários separados para visualizar e limitar cada workload. Uma base com default_pool_size = 20, reserve_pool_size = 5 e max_client_conn = 500 pode atender o primeiro ciclo de testes. Atribua pools ou limites específicos ao serviço de relatórios, que tende a manter consultas abertas por mais tempo. Monitore cl_waiting, duração de transações e bloqueios antes de aumentar conexões. Armazene a configuração em gerenciamento de configuração, mas mantenha segredos fora do repositório. Mudanças devem passar por homologação e incluir um caminho de rollback.
Produção crítica
Em produção crítica, execute ao menos duas instâncias de PgBouncer para evitar um único ponto de falha na camada de conexão. Elas podem ficar nas máquinas das aplicações ou atrás de um endpoint interno, conforme a arquitetura. Use TLS com validação de certificado, autenticação SCRAM, firewall restritivo e monitoramento contínuo. Planeje capacidade com teste de carga, preserve 15% a 20% das conexões do PostgreSQL para operação e defina alertas de fila. O failover do banco deve ser coordenado por uma solução própria, e não pelo PgBouncer isoladamente. Documente como pausar clientes, recarregar configuração, trocar o destino e validar transações após uma mudança de primário.
Continue lendo
Perguntas frequentes
PgBouncer precisa ficar na mesma VPS do PostgreSQL?
Não. O PgBouncer pode rodar na mesma VPS do PostgreSQL, em uma máquina dedicada ou junto de cada instância da aplicação. Colocá-lo no mesmo servidor simplifica a rede e reduz latência, mas cria dependência do mesmo host. Executá-lo perto das aplicações distribui a camada de pool, porém exige controlar vários arquivos de configuração. Para uma implantação pequena, usar `127.0.0.1` é uma opção simples. Em produção distribuída, use rede privada, TLS e um mecanismo claro para atualizar o endereço do banco durante failover.
Qual é o melhor modo de pool do PgBouncer?
O modo `transaction` costuma ser o ponto inicial para APIs, sites e workers porque libera o backend ao fim de cada transação. O modo `session` oferece maior compatibilidade com estado de sessão, tabelas temporárias, `LISTEN` e alguns usos de prepared statements, mas reduz a eficiência do pool. `statement` libera a conexão após cada comando e não aceita transações com múltiplas instruções. A escolha correta depende do driver e do framework. Teste autenticação, migrations, jobs, transações e recursos específicos em homologação antes de alterar o ambiente de produção.
Como calcular o default_pool_size do PgBouncer?
Comece pelo `max_connections` do PostgreSQL e reserve entre 10 e 20 conexões para administração, replicação e monitoramento. Divida o restante pelas combinações ativas de banco e usuário, lembrando que cada combinação pode criar um pool. Com `max_connections = 100`, três combinações e 15 conexões reservadas, um `default_pool_size` entre 20 e 25 deixa alguma margem. Depois, valide com `SHOW POOLS`, `pg_stat_activity` e teste de carga. Aumentar o valor sem medir pode elevar contenção de CPU, memória e disco, piorando a latência.
PgBouncer elimina o erro too many connections?
Ele reduz a probabilidade do erro ao consolidar muitos clientes em menos conexões reais, mas não elimina todas as causas. O PostgreSQL ainda pode atingir limites por usuário, conexões administrativas ou acesso direto à porta 5432. Também pode haver pools demais quando vários bancos e usuários estão configurados. Monitore `cl_waiting`, `sv_active` e `pg_stat_activity`, mantenha conexões reservadas para manutenção e limite pools locais dos clientes. Se transações permanecem abertas por muito tempo, o PgBouncer apenas organiza a fila. O código e as consultas também precisam ser corrigidos.
É seguro guardar o hash SCRAM no userlist.txt?
O segredo SCRAM é preferível a armazenar uma senha em texto puro, mas ainda deve ser tratado como material sensível. Restrinja o arquivo ao usuário do serviço, use permissões como 640 quando compatíveis com a distribuição e nunca faça commit em Git. Evite copiar o conteúdo para tickets, logs ou comandos que fiquem no histórico do shell. Em ambientes com muitos usuários, avalie `auth_query` com uma função cuidadosamente protegida. A rotação da senha no PostgreSQL também exige atualizar o PgBouncer ou o mecanismo de consulta antes que novas autenticações funcionem.
PgBouncer funciona com prepared statements?
A compatibilidade depende do modo de pool, da versão do PgBouncer e do driver. Em `session`, a conexão permanece associada ao cliente, então o comportamento tende a ser mais previsível. Em `transaction`, versões recentes podem gerenciar prepared statements nomeados quando `max_prepared_statements` está configurado, mas há limitações e diferenças em relação a versões antigas. Drivers também podem usar protocolos e caches próprios. Confirme a documentação da versão instalada e execute testes com as consultas reais da aplicação. Se aparecerem erros de statement inexistente, não desative recursos às cegas, investigue driver e pool em conjunto.
Fontes consultadas
- PgBouncer Documentation, Configuration · coletado em 18/10/2026
- PgBouncer Documentation, Usage · coletado em 18/10/2026
- PostgreSQL Documentation, Client Authentication · coletado em 18/10/2026
- PostgreSQL Documentation, Resource Consumption · coletado em 18/10/2026