Enable the PostgreSQL connection pool - ApsaraDB RDS: Central de Documentação do Alibaba Cloud

Se sua aplicação cria muitas conexões de curta duração ou gera alta rotatividade de conexões, ative o pool de conexões (PgBouncer) para reduzir a carga no servidor de banco de dados e melhorar o tempo de resposta. O PgBouncer atua como intermediário entre sua aplicação e o ApsaraDB RDS for PostgreSQL, reutilizando conexões de backend para atender a múltiplos clientes. Assim, o banco de dados evita abrir e fechar conexões repetidamente.

Quando usar o pool de conexões

Nem toda carga de trabalho se beneficia do PgBouncer. Consulte esta tabela para decidir entre conexão via pool ou direta.

Cenário	Tipo de conexão	Motivo
Funções serverless ou de borda	Via pool	Cada invocação cria uma nova conexão
Aplicações web com muitas requisições simultâneas	Via pool	Reduz a sobrecarga de conexão por requisição
Alta rotatividade de conexões em frameworks ORM	Via pool	Reutiliza conexões de backend
Migrações de schema	Direta	Ferramentas de migração podem usar instruções `SET` ou advisory locks
Consultas analíticas de longa duração	Direta	Evita contenção no pool
`pg_dump` ou `pg_restore`	Direta	Usa instruções `SET` no nível de sessão
Replicação lógica	Direta	Exige sessão persistente
Prepared statements (no modo transação)	Direta	Incompatível com pool de transações

Pré-requisitos

Antes de começar, verifique se sua instância do ApsaraDB RDS for PostgreSQL atende aos seguintes requisitos:

Versão principal do mecanismo: PostgreSQL 11 ou posterior
Série do produto: Basic Edition ou High-availability Edition
Método de faturamento: assinatura ou pagamento conforme o uso
Versão secundária do mecanismo: 20240830 ou posterior, sem o sufixo babelfish

Para visualizar ou atualizar a versão secundária do mecanismo, consulte Atualizar a versão secundária do mecanismo de uma instância do ApsaraDB RDS for PostgreSQL.

Faturamento

Este recurso é gratuito.

Como funciona

O PgBouncer atua como middleware entre sua aplicação e o banco de dados. Os clientes conectam-se ao PgBouncer na porta 6432 (padrão). O PgBouncer mantém um pool de conexões de backend com o PostgreSQL na porta 5432 (padrão) e as atribui aos clientes conforme o modo de pool configurado.

Ao ativar o PgBouncer:

O sistema aloca uma nova porta do PgBouncer (padrão: 6432). As conexões existentes pela porta original do banco de dados (5432) permanecem inalteradas.
O sistema instala os plugins pgbouncer_fdw e dblink no banco de dados postgres para fornecer métricas do pool de conexões. Não é possível desinstalar esses plugins.

Ativar ou desativar o pool de conexões

Acesse a página Instances. Na barra de navegação superior, selecione a região da instância RDS. Localize a instância e clique em seu respectivo ID.
No painel de navegação à esquerda, clique em Database Connection.
Clique em Enable PgBouncer ou Disable PgBouncer.
Na caixa de diálogo exibida, clique em OK.

Após ativar o PgBouncer, a porta correspondente (padrão: 6432) aparece na página Database Connection. Para alterar a porta, clique em Modify Endpoint, selecione um tipo de endpoint e atualize o campo PgBouncer Port.

Nota

Ao desativar o PgBouncer, aplicações ainda configuradas para usar a porta 6432 perdem a conectividade. Reconfigure-as para a porta original do banco de dados (padrão: 5432) antes de desativar o recurso.

Conectar-se pelo pool de conexões

Depois de ativar o PgBouncer, atualize a porta de conexão da aplicação de 5432 para 6432. Os demais parâmetros de conexão (endpoint, nome de usuário e senha) permanecem inalterados.

Antes (conexão direta):

postgresql://<username>:<password>@<endpoint>:5432/<database>

Depois (conexão via pool):

postgresql://<username>:<password>@<endpoint>:6432/<database>

Para mais informações, consulte Conectar-se a uma instância do ApsaraDB RDS for PostgreSQL.

Configurar parâmetros do pool de conexões

Após ativar o PgBouncer, use o recurso Parameter Settings para ajustar o comportamento do pool de conexões.

Nota

O Parameter Settings exibe os parâmetros do PgBouncer somente após a ativação do recurso. Para modificar parâmetros em lote com um

modelo de parâmetro

, ative primeiro o PgBouncer e depois aplique o modelo.

O modelo de parâmetro padrão é PostgreSQL_PgBouncer_Default Parameter Template (rpg-sys-pgsql-pgbouncer).

Modo de pool

O parâmetro pgbouncer.pool_mode define quando o PgBouncer devolve uma conexão de backend ao pool.

Modo	Padrão	Funcionamento	Quando usar
`transaction`	Sim	Devolve a conexão após cada transação	Maioria das aplicações. Oferece maior reutilização de conexões.
`session`	Não	Devolve a conexão ao desconectar o cliente	Aplicações que usam recursos no nível de sessão (`SET`, `LISTEN`, prepared statements, advisory locks)
`statement`	Não	Devolve a conexão após cada instrução. Apenas para cargas de trabalho com autocommit. Incompatível com transações de múltiplas instruções.	Cargas de trabalho exclusivamente com autocommit

Limites de conexão

Os parâmetros a seguir controlam quantas conexões o PgBouncer aceita e encaminha ao banco de dados. max_client_conn e default_pool_size operam em camadas diferentes: max_client_conn limita as conexões de entrada dos clientes, enquanto default_pool_size restringe as conexões de saída para o backend. Vários clientes podem compartilhar um pool menor de conexões de backend; esse é o principal benefício do pool de conexões.

Parâmetro	Tipo	Padrão	Função
`pgbouncer.max_client_conn`	int	100	Número máximo de conexões de cliente aceitas pelo PgBouncer
`pgbouncer.default_pool_size`	int	20	Quantidade padrão de conexões permitidas no pool
`pgbouncer.min_pool_size`	int	0	Quantidade mínima de conexões de cliente permitidas no pool

Outros parâmetros

Parâmetro	Tipo	Padrão	Descrição
`pgbouncer.query_wait_timeout`	int	120	Tempo máximo, em segundos, de espera de uma consulta na fila. Ao atingir o timeout, o sistema desconecta o cliente. Defina como `0` para espera indefinida.
`pgbouncer.ignore_startup_parameters`	string	`"extra_float_digits"`	Lista separada por vírgulas de parâmetros de inicialização ignorados pelo PgBouncer. Por padrão, o PgBouncer processa apenas parâmetros essenciais (`client_encoding`, `datestyle`, `timezone`, `standard_conforming_strings`) e rejeita conexões com parâmetros desconhecidos. Adicione aqui quaisquer parâmetros extras. Mantenha sempre o `extra_float_digits` para preservar a compatibilidade com drivers JDBC (Java Database Connectivity) do PostgreSQL.
`pgbouncer.stats_users`	string	`""`	Lista separada por vírgulas de usuários autorizados a conectar-se ao banco de dados virtual do PgBouncer e executar consultas somente leitura.

Para a referência completa de parâmetros, consulte a documentação oficial do PgBouncer.

Visualizar métricas do pool de conexões

Use o Enhanced Monitoring para monitorar a atividade do pool de conexões. As métricas ficam disponíveis apenas após a ativação do PgBouncer.

Métrica	Descrição
`db.pgbouncer.client_connections.active`	Conexões de cliente ativas
`db.pgbouncer.client_connections.waiting`	Conexões de cliente aguardando conexão de backend
`db.pgbouncer.server_connections.active`	Conexões de backend ativas
`db.pgbouncer.server_connections.idle`	Conexões de backend ociosas
`db.pgbouncer.total_pooled_connections`	Total de conexões no pool
`db.pgbouncer.num_pools`	Quantidade de pools de conexões

Limitações

O tempo máximo de ociosidade de uma conexão no pool é de 10 minutos. O sistema fecha automaticamente conexões ociosas que ultrapassam esse limite. Não é possível alterar esse valor.
Ao ativar a criptografia SSL na instância, o PgBouncer também ativa o SSL. O PgBouncer não oferece suporte à autenticação de conexão com Access Control List (ACL) definida como verify-ca ou verify-full, nem a arquivos de revogação de certificado de cliente.

Referência de API

Chame a operação ModifyDBInstanceConfig para ativar ou desativar o PgBouncer programaticamente.

Parâmetro	Descrição	Exemplo
`DBInstanceId`	ID da instância do RDS for PostgreSQL	`pgm-****`
`ConfigName`	Nome do item de configuração	`pgbouncer`
`ConfigValue`	`true` para ativar, `false` para desativar	`true`

ApsaraDB RDS:Enable or disable the connection pool (PgBouncer)