Usar o pool de conexões do PgBouncer

Visualização — AlloyDB Omni

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. É possível processar dados pessoais para esse recurso conforme descrito no Adendo sobre processamento de dados do Cloud, sujeito às obrigações e restrições descritas no contrato em que você acessa o Google Cloud. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

As informações nesta página se aplicam apenas a implantações do AlloyDB Omni baseadas no Kubernetes. Ele não se aplica a implantações de servidor único do AlloyDB Omni.

Esta página descreve como ativar e usar o pool de conexões do PgBouncer para o AlloyDB Omni usando o operador do AlloyDB Omni Kubernetes.

Muitos aplicativos, especialmente os da Web, abrem e fecham conexões de banco de dados com frequência, o que pode sobrecarregar a instância do banco de dados. O PgBouncer ajuda a reduzir a carga de instâncias gerenciando as conexões de maneira mais eficiente. Ao reutilizar conexões, o PgBouncer minimiza o número de conexões com a instância do banco de dados, liberando recursos na instância.

Criar um serviço PgBouncer

O operador AlloyDB Omni Kubernetes permite criar um serviço PgBouncer dedicado para seu banco de dados. Em seguida, é possível acessar o banco de dados pelo serviço do PgBouncer para aproveitar o pool de conexões.

Há uma definição de recurso personalizada (CRD) dedicada para configurar o serviço PgBouncer conforme necessário.

Para criar um serviço PgBouncer para seu banco de dados, siga estas etapas:

1. Crie um recurso personalizado PgBouncer no cluster do Kubernetes da seguinte maneira:

   apiVersion: alloydbomni.dbadmin.goog/v1
   kind: PgBouncer
   metadata:
     name: PGBOUNCER_NAME
   spec:
     dbclusterRef: DB_CLUSTER_NAME
     allowSuperUserAccess: true
     podSpec:
       resources:
         memory: 1Gi
         cpu: 1
       image: "gcr.io/alloydb-omni/operator/pgbouncer:1.23.1"
     parameters:
       pool_mode: POOL_MODE
       ignore_startup_parameters: IGNORE_STARTUP_PARAMETERS
       default_pool_size: DEFAULT_POOL_SIZE
       max_client_conn: MAXIMUM_CLIENT_CONNECTIONS
       max_db_connections: MAXIMUM_DATABASE_CONNECTIONS
     serviceOptions:
       type: "ClusterIP"

   Substitua:

   • PGBOUNCER_NAME: o nome do recurso personalizado do PgBouncer.
   • DB_CLUSTER_NAME: o nome do cluster de banco de dados do AlloyDB Omni. É o mesmo nome do cluster de banco de dados que você declarou ao criar.
   • POOL_MODE: especifica quando uma conexão de banco de dados pode ser reutilizada por outros clientes. Defina o parâmetro como um dos seguintes:
     • session: a conexão do banco de dados é liberada de volta para o pool depois que o cliente se desconecta. Usado por padrão.
     • transaction: a conexão do banco de dados é liberada de volta ao pool após o término da transação.
     • statement: a conexão do banco de dados é liberada de volta para o pool após a conclusão da consulta. Transações que abrangem várias instruções não são permitidas nesse modo.
   • IGNORE_STARTUP_PARAMETERS: especifica parâmetros que o PgBouncer não permite para que sejam ignorados durante a inicialização, por exemplo, extra_float_digits. Para mais informações, consulte Configuração do PgBouncer.
   • DEFAULT_POOL_SIZE: o número de conexões de banco de dados permitido por par de usuário-banco de dados, por exemplo, 8.
   • MAXIMUM_CLIENT_CONNECTIONS: o número máximo de conexões de cliente, por exemplo, 800.
   • MAXIMUM_DATABASE_CONNECTIONS: o número máximo de conexões de banco de dados. Por exemplo, 160.

2. Aplique o manifesto:

   kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE

   Substitua PATH_TO_MANIFEST pelo caminho do arquivo de manifesto, por exemplo, /fleet/config/pgbouncer.yaml.

3. Para verificar se o objeto PgBouncer que você criou está pronto, execute a consulta a seguir:

   kubectl get pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME  -n NAMESPACE -w
   

   Substitua NAMESPACE pelo nome do namespace do Kubernetes para o objeto PgBouncer.

   O resultado será assim:

   NAMESPACE   NAME          ENDPOINT        STATE
   dbv2        mypgbouncer
   dbv2        mypgbouncer
   dbv2        mypgbouncer
   dbv2        mypgbouncer                   WaitingForDeploymentReady
   dbv2        mypgbouncer                   Acquiring IP
   dbv2        mypgbouncer   10.138.15.231   Ready
   

Conectar-se ao endpoint do pooler de conexões

É possível se conectar ao pooler de conexões do PgBouncer dentro ou fora de um cluster do Kubernetes.

Conectar-se em um cluster do Kubernetes

Para se conectar ao endpoint do pooler de conexões usando o cliente psql, siga estas etapas:

1. Crie um pod da seguinte maneira:

   apiVersion: v1
   kind: Pod
   metadata:
     name: postgres
   spec:
     containers:
     - image: "docker.io/library/postgres:latest"
       command:
        - "sleep"
        - "604800"
       name: db-client
   

2. Aplique o manifesto:

   kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE
   

3. Conecte-se ao aplicativo contêinerizado:

   kubectl exec -it postgres -n NAMESPACE -- bash
   

4. Verifique a conexão SSL com o endpoint do PgBouncer usando o cliente psql:

   export PGSSLMODE="require"; psql -h HOST -d postgres -U postgres -p PORT
   

   Substitua:

   • HOST: o endpoint do pool de conexões que você recebe usando o comando kubectl get pgbouncers.alloydbomni.dbadmin.goog -n NAMESPACE. Se o PgBouncer não estiver exposto como um serviço, use o endereço IP dele.
   • PORT: a porta em que o PgBouncer está detectando.

   A janela do terminal mostra o texto de login psql que termina com uma solicitação postgres=#.

Conectar-se de fora de um cluster do Kubernetes

Para acessar o pooler de conexões do PgBouncer de fora de um cluster do Kubernetes, defina o campo type no atributo serviceOptions como LoadBalancer, que cria um serviço loadbalancer.

1. Crie um recurso personalizado PgBouncer no cluster do Kubernetes da seguinte maneira:

   apiVersion: alloydbomni.dbadmin.goog/v1
   kind: PgBouncer
   metadata:
   name: PGBOUNCER_NAME
   spec:
   dbclusterRef: DB_CLUSTER_NAME
   allowSuperUserAccess: true
   replicaCount: 2
   parameters:
     pool_mode: POOL_MODE
     ignore_startup_parameters: IGNORE_STARTUP_PARAMETERS
     default_pool_size: DEFAULT_POOL_SIZE
     max_client_conn: MAXIMUM_CLIENT_CONNECTIONS
     max_db_connections: MAXIMUM_DATABASE_CONNECTIONS
   podSpec:
     resources:
       memory: 1Gi
       cpu: 1
     image: "gcr.io/alloydb-omni/operator/pgbouncer:1.23.1"
   serviceOptions:
     type: "LoadBalancer"

2. Aplique o manifesto:

   kubectl apply -f PATH_TO_MANIFEST

3. Para verificar se o objeto PgBouncer que você criou está pronto, execute a consulta a seguir:

   kubectl get pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME  -n NAMESPACE -w

   O resultado será assim:

   NAME          ENDPOINT       STATE
   mypgbouncer   10.138.15.207   Ready
   

Definir as configurações do PgBouncer

Use os seguintes parâmetros para configurar as configurações do PGBouncer:

Parâmetro	Descrição	Valor padrão
pool_mode	Especifica quando uma conexão de banco de dados pode ser reutilizada por outros clientes. Os valores permitidos são os seguintes: session: a conexão do banco de dados é liberada de volta para o pool depois que o cliente se desconecta. transaction: a conexão do banco de dados é liberada de volta para o pool após o término da transação. statement: a conexão do banco de dados é liberada de volta ao pool após a conclusão da consulta. Neste modo, não são permitidas transações que abrangem várias instruções.	session
ignore_startup_parameters	Especifica parâmetros que o PgBouncer não permite para que sejam ignorados durante a inicialização.
default_pool_size	O número de conexões de banco de dados permitidas por par de usuário-banco de dados.	20
max_client_conn	O número máximo de conexões de cliente.	100
max_db_connections	O número máximo de conexões de banco de dados.	0

Personalizar a implantação do PgBouncer

O AlloyDB Omni usa recursos personalizados para gerenciar os componentes. Para personalizar a implantação do PgBouncer no AlloyDB Omni no Kubernetes, modifique o recurso personalizado PgBouncer da seguinte maneira:

1. Liste os recursos personalizados PgBouncer:

   kubectl get pgbouncers -n NAMESPACE

   Substitua NAMESPACE pelo namespace em que você implantou o AlloyDB Omni.

2. Para modificar o recurso, abra o arquivo de declaração do recurso PgBouncer no editor padrão:

   kubectl edit pgbouncers PGBOUNCER_NAME -n NAMESPACE

3. No arquivo de declaração, encontre a seção podSpec que contém a configuração e modifique qualquer um dos seguintes campos conforme necessário:

   • resources: o cpu e o memory definidos para o contêiner:

     apiVersion: alloydbomni.dbadmin.goog/v1
     kind: PgBouncer
     metadata:
       name: PGBOUNCER_NAME
     spec:
       dbclusterRef: DB_CLUSTER_NAME
       replicaCount: 2
       parameters:
         pool_mode: POOL_MODE
         ignore_startup_parameters: IGNORE_STARTUP_PARAMETERS
         default_pool_size: DEFAULT_POOL_SIZE
         max_client_conn: MAXIMUM_CLIENT_CONNECTIONS
         max_db_connections: MAXIMUM_DATABASE_CONNECTIONS
       podSpec:
         resources:
           memory: 1Gi
           cpu: 1
     ...
     

   • image: o caminho para a tag de imagem do PgBouncer:

     ...
       podSpec:
         resources:
           memory: 1Gi
           cpu: 1
         image: IMAGE
     ...
     

   • schedulingconfig: inclua a seção nodeaffinity para controlar onde os pods do PgBouncer são programados:

     ...
       podSpec:
         resources:
           memory: 1Gi
           cpu: 1
         image: IMAGE
         schedulingconfig:
           nodeaffinity:
             NODE_AFFINITY_TYPE:
               nodeSelectorTerms:
               - matchExpressions:
                 - key: LABEL_KEY
                   operator: OPERATOR_VALUE
                   values:
                   - pgbouncer
     ...
     

     Substitua:

     • NODE_AFFINITY_TYPE: defina o parâmetro como um dos seguintes:
       • requiredDuringSchedulingIgnoredDuringExecution: o Kubernetes programa o pod com base exatamente nas regras definidas.
       • preferredDuringSchedulingIgnoredDuringExecution: o programador do Kubernetes tenta encontrar um nó que atenda à regra definida para a programação. No entanto, se não houver esse nó, o Kubernetes vai programar um nó diferente no cluster.
     • LABEL_KEY: o rótulo do nó para a chave que serve como um indicador de local e facilita a distribuição uniforme de pods no cluster, por exemplo, nodetype.
     • OPERATOR_VALUE: representa a relação de uma chave com um conjunto de valores. Defina o parâmetro como um dos seguintes:
       • In: o array de valores não pode estar vazio.
       • NotIn: o array de valores não pode estar vazio.
       • Exists: a matriz de valores precisa estar vazia.
       • DoesNotExist: a matriz de valores precisa estar vazia.
       • Gt: a matriz de valores precisa ter um único elemento, que é interpretado como um número inteiro.
       • Lt: a matriz de valores precisa ter um único elemento, que é interpretado como um número inteiro.

4. Depois de fazer as alterações, salve o arquivo de declaração. O operador AlloyDB Omni Kubernetes aplica automaticamente as mudanças à sua implantação do PgBouncer.

Excluir o recurso PgBouncer

Para excluir um recurso personalizado do PgBouncer, execute o seguinte comando:

kubectl delete pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME -n NAMESPACE

O resultado será assim:

pgbouncer.alloydbomni.dbadmin.goog "mypgbouncer" deleted

Conferir os registros do PgBouncer

É possível conferir e analisar os registros de qualquer instância de réplica do PgBouncer na implantação do AlloyDB Omni no Kubernetes da seguinte maneira:

1. Confira uma lista de todos os pods do PgBouncer no seu namespace:

   kubectl get pods -n NAMESPACE

   O resultado será assim:

   NAME                                          READY   STATUS    RESTARTS   AGE
   al-092d-dbcluster-sample-0                    3/3     Running   0          3d1h
   mypgbouncer-pgb-deployment-659869f95c-4kbgv   1/1     Running   0          27m
   

2. Confira os registros de um pod específico:

   kubectl logs -f POD_NAME -n NAMESPACE

   Observação: para transmitir continuamente os registros em tempo real, use a opção -f.

   O resultado será assim:

   2025-01-21 06:57:39.549 UTC [7] LOG kernel file descriptor limit: 1048576 (hard: 1048576); max_client_conn: 800, max expected fd use: 812
   2025-01-21 06:57:39.550 UTC [7] LOG listening on 0.0.0.0:6432
   2025-01-21 06:57:39.550 UTC [7] LOG listening on [::]:6432
   2025-01-21 06:57:39.550 UTC [7] LOG listening on unix:/tmp/.s.PGSQL.6432
   2025-01-21 06:57:39.550 UTC [7] LOG process up: PgBouncer 1.23.0, libevent 2.1.12-stable (epoll), adns: evdns2, tls: OpenSSL 3.0.13 30 Jan 2024
   2025-01-21 06:58:17.012 UTC [7] LOG C-0x55f2b1b322a0: (nodb)/(nouser)@10.138.15.215:48682 registered new auto-database: alloydbadmin
   2025-01-21 06:58:17.012 UTC [7] LOG S-0x55f2b1b4ecb0: alloydbadmin/alloydbpgbouncer@10.138.0.48:5432 new connection to server (from 10.12.1.113:53156)
   2025-01-21 06:58:17.042 UTC [7] LOG S-0x55f2b1b4ecb0: alloydbadmin/alloydbpgbouncer@10.138.0.48:5432 SSL established: TLSv1.3/TLS_AES_256_GCM_SHA384/ECDH=prime256v1
   2025-01-21 06:58:17.052 UTC [7] LOG C-0x55f2b1b322a0: pgbouncer/statsuser@10.138.15.215:48682 login attempt: db=pgbouncer user=statsuser tls=TLSv1.3/TLS_AES_256_GCM_SHA384 replication=no
   2025-01-21 06:58:19.526 UTC [7] LOG C-0x55f2b1b322a0: pgbouncer/statsuser@10.138.15.215:48682 closing because: client close request (age=2s)
   2025-01-21 06:58:20.344 UTC [7] LOG C-0x55f2b1b322a0: pgbouncer/statsuser@10.138.15.215:46796 login attempt: db=pgbouncer user=statsuser tls=TLSv1.3/TLS_AES_256_GCM_SHA384 replication=no
   

Monitorar a performance e a atividade do PgBouncer

É possível conferir as métricas do pool de conexões do PgBouncer usando apenas um statsuser dedicado para acessar o banco de dados de estatísticas internas do PgBouncer. O statsuser é usado para autenticação ao se conectar ao banco de dados do PgBouncer.

1. Conecte-se ao AlloyDB Omni como superusuário ou usuário com o privilégio CREATE ROLE usando o cliente psql:

   export PGPASSWORD="ChangeMe123"; export PGSSLMODE="require"; psql -h HOST -d postgres -U postgres -p PORT
   

   O resultado será assim:

   psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 15.7)
   SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
   Type "help" for help.
   

2. Crie o statsuser no AlloyDB Omni:

   postgres=# CREATE USER "statsuser" WITH PASSWORD 'tester';
   

   O resultado será assim:

   CREATE ROLE
   postgres=#
   

3. Conecte-se ao banco de dados do PgBouncer como statsuser:

   export PGPASSWORD="ChangeMe123"; export PGSSLMODE="require"; psql -h HOST -d pgbouncer -U statsuser -p PORT
   

   O resultado será assim:

   psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 1.23.0/bouncer)
   WARNING: psql major version 16, server major version 1.23.
   Some psql features might not work.
   SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
   Type "help" for help.
   

4. Execute o comando SHOW STATS para conferir a performance do PgBouncer e identificar possíveis problemas:

   pgbouncer=# SHOW STATS;
   

   O resultado será assim:

        database   | total_server_assignment_count | total_xact_count | total_query_count | total_received | total_sent | total_xact_time | total_query_time | total_wait_time | avg_server_assignment_count | avg_xact_count | avg_query_count | avg_recv | avg_sent | avg_xact_time | avg_query_time | avg_wait_time
      -------------+-------------------------------+------------------+-------------------+----------------+------------+-----------------+------------------+-----------------+-----------------------------+----------------+-----------------+----------+----------+---------------+----------------+---------------
      alloydbadmin |                             1 |                0 |                 0 |              0 |        330 |               0 |                0 |           41730 |                           0 |              0 |               0 |        0 |        2 |             0 |              0 |         41730
      pgbouncer    |                             0 |                5 |                 5 |              0 |          0 |               0 |                0 |               0 |                           0 |              0 |               0 |        0 |        0 |             0 |              0 |             0
      (2 rows)
   

Desativar o pooler de conexões do PgBouncer

Se você precisar desativar ou reverter o pooler de conexões do PgBouncer, siga estas etapas:

1. Verifique o status do pooler de conexões:

   kubectl get deployment fleet-controller-manager --namespace alloydb-omni-system  -o json | jq '.spec.template.spec.containers[0].args'

   Esse comando mostra o manifesto de implantação do controlador principal para gerenciar a frota do AlloyDB Omni. Encontre a opção --enable-pgbouncer na seção args da matriz containers:

   ...
    spec:
     containers:
     - name: fleet-controller-manager
       image:...
       args:
       --health-probe-bind-address=:8081",
       --metrics-bind-address=127.0.0.1:8080",
       --leader-elect",
       --image-registry=gcr.io",
       --data-plane-image-repository=alloydb-omni-staging",
       --control-plane-agents-image-repository=aedi-gbox",
       --control-plane-agents-tag=jan19v3",
       --additional-db-versions-for-test-only=latest",
       --enable-multiple-backup-solutions=true",
       --enable-pgbouncer=true
   

2. Edite a configuração da implantação do controlador para desativar o pooler de conexão:

   kubectl edit deployment fleet-controller-manager --namespace alloydb-omni-system

3. No manifesto de implantação, mude o valor da opção --enable-pgbouncer de true para false:

   ...
   --enable-pgbouncer=false
   

4. Salve o arquivo e saia do editor. kubectl aplica a mudança automaticamente.

A seguir

• Gerenciar e monitorar o AlloyDB Omni