Visão geral do agrupamento de conexões gerenciado

Com o pool de conexões gerenciado, é possível escalonar as 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 em execução 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 conectarem diretamente ao servidor de banco de dados. Essa atribuição dinâmica melhora o desempenho, especialmente para conexões escalonadas, absorvendo picos repentinos de conexão e reutilizando as conexões de banco de dados atuais.

Poolers e pools de conexões

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 conectarem diretamente ao servidor de banco de dados. O cluster do pool de conexões consiste em um ou mais pools 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 de servidor de banco de dados reutilizáveis abertas 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 inativa não estiver disponível e o limite do pool (max_pool_size) não tiver sido atingido, o pool 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 passar para um estado de espera até que uma conexão de servidor fique disponível.
  • Quando a solicitação é concluída, a conexão do servidor retorna ao pool de conexões para reutilização.

Relação entre poolers e pools

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

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.

Os recursos de desempenho e escalonamento do pooling de conexões gerenciado operam em vários níveis:

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

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

  • Pooler e escalonamento de 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 em toda a 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 pools de conexões (8 vCPUs), cada pool de conexões 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 como muito baixo pode levar a tempos de espera de conexão mais longos, enquanto defini-lo como 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 pooler de conexão. Os principais parâmetros incluem:

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

Casos de uso e considerações

Ao usar o pooling de conexões gerenciado, lembre-se do seguinte:

  • 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 pool 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 de conexões é muito alto. No entanto, para aplicativos que normalmente estabelecem conexões de longa duração, talvez seja melhor evitar o uso de pools de conexões.
  • É possível usar o Identity and Access Management para proteger as conexões com a 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.
  • É preciso se conectar à instância usando apenas uma conexão direta ou o proxy de autenticação do Cloud SQL.
  • A instância precisa estar configurada para acesso a serviços privados, usar IP público ou ter o Private Service Connect ativado.
  • A instância precisa usar a nova arquitetura de rede do Cloud SQL.
  • O pooling de conexões gerenciado requer um número mínimo de versão de manutenção de POSTGRES_$version.R20250727.00_14. Para mais informações sobre como realizar a manutenção de autoatendimento, consulte Realizar a manutenção de autoatendimento.

Opções de pooling

O pooling de conexões gerenciado permite gerenciar como as conexões são agrupadas usando o parâmetro pool_mode. Você pode usar as seguintes opções de pooling:

  • transaction (padrão): agrupa conexões em um nível de 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 pool. Quando um cliente se desconecta, a conexão do servidor retorna ao pool de conexões.

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

É possível 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 pooler de conexão. Determine esse valor com base nos requisitos de tamanho da instância e do pool.

O valor padrão é de 50 conexões por banco de dados e par de usuários para cada pooler 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 do servidor for menor que o min_pool_size, essa configuração vai adicionar mais conexões 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 pooler 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 é de 5,000 conexões para cada pooler de conexões.
max_prepared_statements O número máximo de instruções preparadas nomeadas no nível do protocolo com suporte por pooler de conexão no modo de pool 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 um desempenho ideal, esse valor precisa exceder o número de instruções preparadas usadas com frequência no banco de dados. Um número alto de instruções preparadas no pool de conexões gerenciado pode causar um aumento no uso da memória.

O valor padrão é de 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 expirar. 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 por 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 que não respondem mantenham as 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 que o pool de conexões gerenciadas a feche. Se o valor for definido como 0 segundos, a conexão será fechada imediatamente após o uso.

O valor padrão é 3600 segundos.

Limitações

Ao usar o pool de conexões gerenciado com as instâncias da edição Cloud SQL Enterprise Plus, considere estas limitações:

  • Ativar o pooling de conexões gerenciado em uma instância resulta na reinicialização do banco de dados.
  • 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 posteriores.
  • Se você estiver usando o conector de linguagem do Cloud SQL para Go, recomendamos a versão mínima 1.24 do Go. Se você usa o Go versão 1.23 ou anterior, pode ter limitações de desempenho ao usar o pool de conexões gerenciadas.

  • Se você estiver usando o pool de conexões gerenciado 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 tabela temporária
    • LOAD
    • Bloqueios consultivos no nível da sessão

  • Se você estiver usando a biblioteca de interface de banco de dados asyncpg para o pool de conexões gerenciadas na porta 3307 e 6432, atualize o max_prepared_statements para um valor maior que 0 para ativar o suporte a instruções preparadas no 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 armazenar endereços IP do cliente no Query Insights, os endereços IP do cliente serão exibidos como local em vez do próprio endereço IP.

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 exibir o tráfego do banco de dados mudam. É possível usar o Identity and Access Management para proteger conexões, dependendo da porta.

As portas usadas pelo pool de conexões gerenciadas e as opções de IAM disponíveis são as seguintes:

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 pool de conexões gerenciadas 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 do banco de dados. Durante o pico de carga, o número de conexões para autenticação pode se tornar 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 gerenciadas ao definir a flag max_connections para o 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 instância, consulte Configurar flags de banco de dados.

A seguir