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 inativas 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 gerenciado, consulte Configurar o pool de conexões gerenciado.

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 de 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.

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 Managed Connection Pooling 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