Visão geral do agrupamento de conexões gerenciado

Com o pool de conexões gerenciado, é possível escalonar suas cargas de trabalho otimizando o uso de recursos e a latência de conexão das instâncias do Cloud SQL. O PostgreSQL cria um novo processo para cada conexão, o que gera uso da memória e sobrecarga de configuração de conexão. Em arquiteturas que estabelecem com frequência muitas conexões de curta duração, como microsserviços ou aplicativos sem servidor executados no Cloud Run, essa sobrecarga pode afetar o desempenho e a escalonabilidade do banco de dados.

Com o pooling de conexões gerenciado ativado, os clientes se conectam a um cluster de pool de conexões intermediário em vez de se conectar diretamente ao servidor de banco de dados. Essa atribuição dinâmica melhora o desempenho, principalmente para conexões escalonadas, absorvendo picos repentinos de conexão e reutilizando conexões de banco de dados atuais.

Poolers e pools de conexão

Quando os aplicativos cliente se conectam a uma instância com o pool de conexões gerenciado ativado, eles se conectam a um cluster de pool de conexões intermediário em vez de se conectar diretamente ao servidor de banco de dados. O cluster de pool de conexões consiste em um ou mais poolers de conexões. Um pooler de conexões é um serviço de proxy de banco de dados que gerencia e encaminha conexões de banco de dados entre aplicativos cliente e o servidor de banco de dados.

Um pooler de conexões mantém pools de conexões como um grupo de conexões abertas e reutilizáveis do servidor de banco de dados por banco de dados e par de usuários.

Quando um aplicativo cliente autenticado se conecta a um banco de dados como um usuário específico, o pooler de conexões encaminha a solicitação para o pool de conexões correspondente:

  • Se uma conexão de servidor inativa estiver disponível no pool, o pooler de conexões a atribuirá à solicitação do cliente.
  • Se uma conexão de servidor ociosa não estiver disponível e o limite do pool (max_pool_size) não tiver sido atingido, o pooler de conexões vai criar uma nova conexão de servidor no pool.
  • Se todas as conexões de servidor no pool estiverem em uso e o limite do pool tiver sido atingido, o cliente vai entrar em um estado de espera até que uma conexão de servidor fique disponível.
  • Quando a solicitação termina, a conexão do servidor retorna ao pool de conexões para ser reutilizada.

Relação entre poolers e pools

Um único pooler de conexões pode gerenciar vários pools simultaneamente, com um pool para cada par exclusivo de banco de dados e usuário que se conecta por ele.

Se a instância executar vários poolers de conexão, cada um deles vai manter de forma independente o próprio conjunto separado de pools de conexão para os pares de banco de dados e usuário roteados para ele.

A performance e os recursos de escalonamento do pooling de conexões gerenciado operam em vários níveis:

  • Escalonamento do cluster de pool de conexões:o número de poolers de conexões no cluster é escalonado automaticamente com base no número de núcleos de vCPU provisionados para a instância (dividindo a contagem de vCPU por 4, com um mínimo de 1 pooler de conexões). Isso garante que o pool de conexões não se torne um gargalo. As conexões de clientes recebidas são distribuídas entre os poolers de conexão disponíveis. Exemplo:

    • Uma instância com 2 ou 4 vCPUs executa um pooler de conexões.
    • Uma instância com 8 vCPUs executa dois poolers de conexão.
    • Uma instância com 16 vCPUs executa quatro poolers de conexão.
    • Uma instância com 32 vCPUs executa 8 poolers de conexão.
    • Uma instância com 64 vCPUs executa 16 poolers de conexão.

  • Pooler e escalonamento do pool:como os poolers de conexão operam de forma independente, todas as opções de configuração são aplicadas por pooler de conexão, e não globalmente na instância. As conexões de servidor são criadas sob demanda até um limite máximo definido por max_pool_size para cada pool gerenciado em cada pooler de conexões. Por exemplo, se max_pool_size estiver definido como 50 em uma instância que executa dois poolers de conexão (8 vCPUs), cada pooler poderá abrir até 50 conexões de servidor para um banco de dados e um par de usuários específicos, permitindo um total de até 100 conexões de servidor na instância para esse pool. O dimensionamento preciso do pool é vital para o desempenho: definir esse valor muito baixo pode levar a tempos de espera de conexão mais longos, enquanto definir um valor muito alto pode desperdiçar recursos do servidor de banco de dados.

  • Configurações de conexão do cliente:os limites de conexão do cliente e o comportamento de tempo limite também são configurados por pool de conexões. Os principais parâmetros incluem:

    • max_client_connections: limita o número máximo de conexões de cliente permitidas por pool de conexões. O valor padrão é de 5.000 conexões para cada pool.
    • client_connection_idle_timeout: controla o tempo que uma conexão de cliente pode ficar inativa antes de atingir o tempo limite.
    • query_wait_timeout: controla a duração que uma consulta aguarda uma conexão de servidor disponível no pool antes de atingir o tempo limite.

Casos de uso e considerações

Considere o seguinte ao usar o pool de conexões gerenciado:

  • 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 de processamento e latência para aplicativos que contêm conexões de curta duração ou que resultam em um aumento 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 pool de conexões gerenciado oferece escalonamento de conexões quando o número delas é 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.
  • Você pode usar o Identity and Access Management para proteger as conexões com sua instância, dependendo da porta usada pelo pool de conexões gerenciado. Para mais informações sobre como o IAM funciona no Cloud SQL e as limitaçõ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 de autenticação do Cloud SQL.
  • 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 exige 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.

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 pooling. Quando um cliente se desconecta, a conexão do 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. Essa configuração é aplicada por agrupador de conexões. Determine esse valor com base nos requisitos de tamanho da instância e do pool.

O valor padrão é 50 conexões por banco de dados e par de usuários para cada pool de 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. Essa configuração é aplicada por pooler de conexão. Determine esse valor com base nos requisitos de tamanho da instância e do pool.

Se o número de conexões de servidor for menor que o min_pool_size, essa configuração vai adicionar 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 de cliente permitidas por pool de conexões ao usar o pool de conexões gerenciado. Determine esse valor com base nos requisitos de tamanho da instância e do pool.

O valor padrão é 5,000 conexões para cada pooler de conexão.
max_prepared_statements O número máximo de instruções preparadas nomeadas no nível do protocolo compatíveis por pooler de conexões no modo de pooling transaction. Determine esse valor com base nos requisitos de tamanho da instância e do pool.

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

O valor padrão é 0 instruçõ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 segundos.
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 é 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 é 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 o pool de conexões gerenciado a fechar. Se o valor for definido como 0 segundos, a conexão será fechada imediatamente após o uso.

O valor padrão é de 3600 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 existente resulta em uma reinicialização do banco de dados.
  • O pool de conexões gerenciadas 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 ter 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
    • Tabelas temporárias PRESERVE/DELETE ROW
    • 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.

Portas usadas pelo pool de conexões gerenciado

Quando você ativa o pool de conexões gerenciadas, 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:

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 conexões por pool, 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