Visão geral do agrupamento de conexões gerenciado

Nesta página, descrevemos o que é o pool de conexões gerenciadas e como usá-lo para otimizar o gerenciamento de conexões de banco de dados para suas instâncias do Cloud SQL usando o pool.

O pool de conexões gerenciadas permite escalonar suas cargas de trabalho otimizando o uso de recursos e a latência de conexão para suas instâncias do Cloud SQL usando o pool. O pooling de conexões gerenciado atribui dinamicamente conexões de servidor a solicitações recebidas quando possível. Isso oferece melhorias significativas de desempenho, especialmente para conexões escalonadas, ao absorver picos repentinos de conexão e reutilizar conexões de banco de dados existentes. Em vez de se conectar a um banco de dados específico, o Managed Connection Pooling se conecta a um cluster de poolers, que oferecem tempos de conexão mais curtos e escalonabilidade para suas cargas de trabalho.

Cada pool está associado a um banco de dados e um usuário exclusivos. Depois que um cliente é autenticado, o pool tenta reutilizar uma das conexões de servidor ociosas no pool para conectar o banco de dados ao servidor. Se uma conexão de servidor não estiver disponível, ela vai criar uma nova conexão no pool para conectar o banco de dados. O número de poolers usados se baseia no número de núcleos de vCPU da instância.

Embora seja possível usar o pool de conexões gerenciado para qualquer carga de trabalho transacional, ele oferece o maior benefício de capacidade e latência para aplicativos que contêm conexões de curta duração ou que resultam em um aumento repentino de conexões.

Para conexões de longa duração, o desempenho da conexão usando o pooling de conexões gerenciadas pode ser um pouco menor do que ao usar uma conexão direta. Nesse caso, o pooling de conexões gerenciado oferece escalonamento de conexões quando o número de conexões é muito alto. No entanto, para aplicativos que normalmente estabelecem conexões de longa duração, talvez seja melhor evitar o uso do pool de conexões.

É possível usar o Identity and Access Management para proteger conexões, dependendo da porta. Para mais informações sobre como o IAM funciona no Cloud SQL e as restrições dele, consulte Autenticação do IAM.

Para mais informações sobre como ativar o pool de conexões gerenciadas, consulte Configurar o pool de conexões gerenciadas.

Requisitos

Para usar o pool de conexões gerenciado, sua instância precisa atender aos seguintes requisitos:

  • Sua instância precisa ser da edição Cloud SQL Enterprise Plus.
  • Você precisa se conectar à instância usando apenas uma conexão direta ou o proxy do Cloud SQL Auth.
  • A instância precisa ser configurada para acesso a serviços privados, usar IP público ou ser uma nova instância com o Private Service Connect ativado.
  • Sua instância precisa usar a nova arquitetura de rede do Cloud SQL.
  • O pooling de conexões gerenciado requer um número de versão de manutenção mínima de POSTGRES_$version.R20250727.00_14. Para mais informações sobre como fazer a manutenção de autoatendimento, consulte Fazer a manutenção de autoatendimento.

Portas usadas pelo pool de conexões gerenciadas para instâncias do Cloud SQL

Quando você ativa o pool de conexões gerenciado, as portas usadas pelas instâncias do Cloud SQL para veicular o tráfego do banco de dados mudam. É possível usar o Identity and Access Management para proteger conexões, dependendo da porta.

Confira abaixo as portas usadas pelo pool de conexões gerenciado e as opções de IAM disponíveis:

Opções de pooling

Com o pooling de conexões gerenciado, é possível controlar como as conexões são agrupadas usando o parâmetro pool_mode. Você pode usar as seguintes opções de agrupamento:

  • transaction (padrão): agrupa conexões no nível da transação. As conexões são retornadas ao pool após a conclusão de cada transação. O Cloud SQL recomenda o uso do modo de pool transaction para conexões de curta duração.
  • session: agrupa conexões no nível da sessão. Cada sessão usa uma conexão de servidor dedicada que mantém um estado de sessão. Isso reduz a eficiência do agrupamento. Quando um cliente se desconecta, o servidor retorna ao pool de conexões.

Opções de configuração avançada

Você pode personalizar o pool de conexões gerenciadas usando as seguintes opções de configuração:

Nome da configuração Descrição
max_pool_size O número máximo de conexões de servidor permitidas para um par de banco de dados e usuário em cada pool de conexões. O valor padrão é 50 conexões.
min_pool_size O número mínimo de conexões de servidor disponíveis a qualquer momento em cada pool de conexões.

Se o número de conexões de servidor for menor que min_pool_size, essa configuração adiciona mais conexões de servidor ao pool. Isso ajuda a gerenciar aumentos repentinos na carga do banco de dados após períodos de inatividade e garante que as conexões estejam disponíveis e prontas para uso.

O valor padrão é 0 conexões.
max_client_connections O número máximo de conexões permitidas para sua instância ao usar o pool de conexões gerenciado. O valor padrão é de 5.000 conexões.
max_prepared_statements O número máximo de instruções preparadas nomeadas no nível do protocolo compatíveis no modo de pool transaction.

Definir essa opção como 0 desativa o suporte a instruções preparadas. Para um desempenho ideal, esse valor precisa exceder o número de comandos preparados usados com frequência no banco de dados. Um grande número de instruções preparadas no pool de conexões gerenciadas pode causar um aumento no uso da memória.

O valor padrão é 0 declarações.
client_connection_idle_timeout O tempo que uma conexão de cliente permanece inativa antes de atingir o tempo limite. Esse valor pode variar de 0 a 2.147.483 segundos, e o valor padrão é 0 segundo.
server_connection_idle_timeout O tempo que uma conexão de servidor permanece inativa antes de atingir o tempo limite. Esse valor pode variar de 0 a 2.147.483 segundos, e o valor padrão é de 600 segundos.
query_wait_timeout O tempo que uma consulta aguarda uma conexão de servidor em um pool antes de atingir o tempo limite.

Definir essa opção como 0 a desativa, o que permite o enfileiramento indefinido de clientes. Ativar essa opção impede que servidores sem resposta mantenham conexões.

Esse valor pode variar de 0 a 2.147.483 segundos, e o valor padrão é de 120 segundos.
ignore_startup_parameters Os parâmetros que você quer ignorar e que não são rastreados nos pacotes de inicialização do pool de conexões gerenciadas por padrão.
server_lifetime O tempo máximo que uma conexão de servidor fica sem uso antes de ser fechada pelo pool de conexões gerenciado. Se o valor for definido como 0 segundos, a conexão será fechada imediatamente após o uso.

O valor padrão é de 3.600 segundos.

Limitações

Ao usar o pool de conexões gerenciadas com suas instâncias do Cloud SQL Enterprise Plus, considere estas limitações:

  • Ativar o pool de conexões gerenciado em uma instância atual resulta em uma reinicialização do banco de dados.
  • Quando você usa a API Cloud SQL para ativar, desativar ou configurar o pool de conexões gerenciadas, a API instance.update não pode conter outras atualizações de configuração de instância.
  • O pool de conexões gerenciado só pode ser usado com o proxy de autenticação do Cloud SQL versão 2.15.2 e mais recentes.
  • Se você estiver usando o conector de linguagem Go do Cloud SQL, recomendamos uma versão mínima do Go de 1.24. Se você usa o Go versão 1.23 ou anterior, pode haver limitações de performance ao usar o pool de conexões gerenciadas.

  • Se você estiver usando o pool de conexões gerenciadas no modo de pool transaction, os seguintes recursos do SQL não serão compatíveis:

    • SET/RESET
    • LISTEN
    • WITH HOLD CURSOR
    • PREPARE/DEALLOCATE
    • PRESERVE/DELETE ROW tabelas temporárias
    • LOAD
    • Bloqueios consultivos no nível da sessão

  • Se você estiver usando a biblioteca de interface de banco de dados asyncpg para o pooler de pool de conexões gerenciadas nas portas 3307 e 6432, atualize o max_prepared_statements para um valor maior que 0 e ative o suporte a instruções preparadas no pooler de pool de conexões gerenciadas.

  • Se você estiver usando o Cloud SQL para PostgreSQL versão 17, a opção sslnegotiation=direct não será compatível.

  • O rastreamento de IP do cliente não é compatível com o pool de conexões gerenciadas. Se você ativar a opção Armazenar endereços IP do cliente em Insights de consultas, os endereços IP do cliente vão aparecer como local em vez do endereço IP em si.

  • Se a instância estiver usando o proxy de autenticação do Cloud SQL e tiver o pool de conexões gerenciadas ativado, a autenticação manual do banco de dados do IAM não será compatível. Só é possível usar a autenticação automática do IAM.

Conexões de servidor usadas pelo pooling de conexões gerenciado

A configuração do banco de dados max_connections limita o número máximo de conexões de servidor que um pooler no Managed Connection Pooling pode usar. O Cloud SQL recomenda ajustar esse valor com base nos requisitos de carga de trabalho da instância e no tamanho da instância de banco de dados. Durante o pico de carga, o número de conexões para autenticação pode ficar muito alto.

Se você estiver usando o max_pool_size padrão de 50 pools na sua instância, recomendamos reservar pelo menos 15 conexões de servidor por CPU para o pool de conexões gerenciado ao definir a flag max_connections para seu banco de dados. Para mais informações sobre a flag max_connections, consulte Máximo de conexões simultâneas. Para modificar a flag max_connections da sua instância, consulte Configurar flags do banco de dados.

A seguir