Uso de agrupamento de conexões

O Lakebase inclui um pooler de conexões PgBouncer interno que mantém um pool de conexões de servidor e as compartilha em muitas conexões de cliente. O pooler dá suporte a até 10.000 conexões simultâneas de cliente, tornando-o uma boa opção para funções sem servidor, APIs Web e outros aplicativos que abrem muitas conexões de curta duração.

O pool de conexões requer autenticação de senha nativa do Postgres. Ele não está disponível para funções OAuth.

Como funciona o pool de conexões

Cada conexão do Postgres consome recursos do servidor porque o Postgres cria um processo separado para cada cliente. À medida que as conexões simultâneas crescem, elas podem esgotar rapidamente o limite de conexão do servidor.

O pooler de conexões fica entre seu aplicativo e o Postgres. Os clientes se conectam ao pooler e o pooler encaminha consultas para um pool menor de conexões de servidor reais. O Lakebase executa o PgBouncer no modo de transação, portanto, uma conexão de servidor é mantida somente durante uma única transação e retornada ao pool. Isso permite que muitos clientes compartilhem um pequeno pool de conexões de servidor.

Pools de conexões

O PgBouncer cria um pool separado para cada combinação de banco de dados e usuário. Dois usuários que se conectam ao mesmo banco de dados obtêm pools independentes. O tamanho de cada pool é de aproximadamente 90% do limite de Postgres max_connections , que varia de acordo com o tamanho da computação.

Quando todas as conexões em um pool estão em uso, novas solicitações de cliente esperam em uma fila. Se uma conexão de servidor não estiver disponível dentro de 2 minutos, o cliente receberá um erro de tempo limite.

O diagrama mostra como várias conexões de cliente de diferentes usuários roteiam por meio de pools PgBouncer separados (uma por combinação de usuário/banco de dados), que compartilham um número limitado de conexões postgres reais.

Limites de conexão

Três limites regem o pool de conexões:

Limite	Value	O que controla
Conexões de cliente (max_client_conn)	10.000	Máximo de conexões do seu aplicativo para o PgBouncer
Tamanho do pool (default_pool_size)	~90% de max_connections	Conexões de servidor ativo por par (usuário, banco de dados)
Conexões diretas (max_connections)	Varia de acordo com o tamanho da computação	Máximo de conexões diretas do Postgres

O limite de conexão direta depende do tamanho da computação. Por exemplo, uma unidade de computação de 8 (UC) dá suporte a 1,678 conexões diretas e uma unidade de computação de 16 (UC) dá suporte a 3,357. Para obter a lista completa, consulte especificações de computação.

O limite de 10.000 conexões de cliente não significa 10.000 resultados de consulta simultânea. Ele representa o número máximo de conexões de cliente aceitas pelo PgBouncer. O número de transações ativas simultâneas é limitado pelo tamanho do pool, que é aproximadamente 90% de max_connections.

Habilitar o pool de conexões

Pré-requisitos

• Seu projeto Lakebase Autoscaling deve estar ativo.
• Você deve ter uma função de senha do Postgres nativa no projeto. Para obter instruções, consulte Criar uma função de senha nativa do Postgres.
• Para usar o agrupamento de conexões com instâncias de computação somente leitura, você deve ter um endpoint de alta disponibilidade com Permitir acesso a instâncias de computação somente leitura habilitada. Consulte Alta disponibilidade.

Steps

1. No Aplicativo Lakebase, acesse seu projeto e clique em Conectar.
2. Selecione a ramificação e a computação à qual você deseja se conectar.
3. Na lista suspensa Função , selecione uma função de senha nativa do Postgres. O comutador de pool de conexões só fica visível quando uma função de senha é selecionada. Ele está oculto para funções OAuth.
4. Ative o pool de conexões.
5. Copie o cadeia de conexão e use-o em seu aplicativo.

Formatos de cadeia de conexão

As cadeias de conexão do pooler usam um nome de host diferente das conexões de banco de dados diretas. O nome do host inclui -pooler após o ID do endpoint para computação de leitura e gravação, ou -ro-pooler para computação somente de leitura:

Tipo de computação	Formato do nome do host	Quando usar
Computação de leitura/gravação	<endpoint-id>-pooler.<region>.<cloud>.databricks.com	Todo o tráfego de gravação e leitura
Processamento somente leitura	<endpoint-id>-ro-pooler.<region>.<cloud>.databricks.com	Apenas leitura do tráfego. Requer um endpoint de alta disponibilidade com acesso de leitura ativado.

Ambos usam a porta 5432.

Observação

Copie a string de conexão do pooler diretamente da caixa de diálogo Connect no Aplicativo Lakebase para obter o nome de host correto do seu ponto de extremidade, região e nuvem.

Configuração do PgBouncer

O Lakebase gerencia o PgBouncer com as seguintes configurações. Essas configurações são corrigidas e não podem ser personalizadas.

[pgbouncer]
pool_mode=transaction
max_client_conn=10000
default_pool_size=0.9 * max_connections
max_prepared_statements=1000
query_wait_timeout=120

Configurações	Description
pool_mode=transaction	As conexões de servidor retornam ao pool após cada transação. Consulte o modo transação.
max_client_conn=10000	Máximo de conexões de cliente simultâneas aceitas pelo PgBouncer.
default_pool_size=0.9 * max_connections	Conexões de servidor ativo por par (usuário, banco de dados). Varia de acordo com o tamanho da computação.
max_prepared_statements=1000	Permite instruções preparadas no nível do protocolo no modo de transação. Limita as instruções rastreadas a 1.000 por conexão de cliente.
query_wait_timeout=120	Número de segundos que um cliente aguarda uma conexão com o servidor antes de receber um erro de tempo limite.

Modo de transação

O modo de transação melhora a eficiência da conexão, mas restringe determinados recursos do Postgres que exigem uma conexão de servidor persistente. Os seguintes recursos não estão disponíveis ao usar o pooler de conexões:

• Instruções preparadas no nível do SQL: PREPARE e DEALLOCATE instruções não têm suporte no modo de transação. As instruções preparadas no nível do driver (usadas internamente por psycopg, node-postgres, JDBC e bibliotecas semelhantes) funcionam corretamente por meio do suporte do PgBouncer em nível de protocolo. Para o JDBC, se você observar erros relacionados às declarações preparadas, defina prepareThreshold=0 para desabilitar o cache de declarações preparadas nomeadas no lado do servidor.

• Configurações de nível de sessão: SET os comandos não persistem entre transações porque cada transação pode usar uma conexão de servidor diferente. Por exemplo:

  BEGIN;
  SET search_path TO myschema;
  SELECT * FROM mytable; -- works in this transaction
  COMMIT;
  -- connection returns to pool after COMMIT
  SELECT * FROM mytable; -- ERROR: relation "mytable" does not exist
  

  Para aplicar uma configuração permanentemente, use ALTER ROLE em vez disso:

  ALTER ROLE myrole SET search_path TO myschema, public;
  

• Tabelas temporárias mantidas em sessão: tabelas temporárias que persistem entre transações não estão disponíveis. Uma conexão retornada ao pool pode ser atribuída a um cliente diferente na próxima transação.

• WITH HOLD cursores: os cursores declarados com WITH HOLD exigem uma conexão persistente e não têm suporte.

• Bloqueios consultivos: o PgBouncer não dá suporte a bloqueios consultivos. Os bloqueios consultivos exigem uma conexão persistente com o servidor, que não está disponível no modo de transação.

• LISTEN/NOTIFY: sem suporte. Use uma conexão direta (não compartilhada) para aplicativos que necessitam de mensagens pub/sub.

• pg_dump e migrações de esquema: use uma conexão direta para pg_dump, migrações de esquema e outras ferramentas que dependem do estado a nível de sessão.

Observação

Para aplicativos que exigem recursos do Postgres no nível da sessão, use uma string de conexão direta da caixa de diálogo Connect sem habilitar a opção pool de conexões.