使用 PgBouncer 连接池

本页介绍了如何使用 AlloyDB Omni Kubernetes 操作符为 AlloyDB Omni 启用和使用 PgBouncer 连接池。

许多应用（尤其是 Web 应用）会频繁打开和关闭数据库连接，这可能会给数据库实例带来巨大的负载。PgBouncer 可更高效地管理连接，从而帮助减少实例负载。通过重复使用连接，PgBouncer 可最大限度地减少与数据库实例的连接数，从而释放实例上的资源。

创建 PgBouncer 服务

借助 AlloyDB Omni Kubernetes 操作器，您可以为数据库创建专用 PgBouncer 服务。然后，您可以通过 PgBouncer 服务访问数据库，从而受益于连接池。

有一个专用的自定义资源定义 (CRD)，可根据需要配置 PgBouncer 服务。

如需为数据库创建 PgBouncer 服务，请按以下步骤操作：

  1. 在 Kubernetes 集群中创建 PgBouncer 自定义资源，如下所示：

    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"

    替换以下内容：

    • PGBOUNCER_NAME：您的 PgBouncer 自定义资源的名称。
    • DB_CLUSTER_NAME：您的 AlloyDB Omni 数据库集群的名称。该名称与您在创建数据库集群时声明的名称相同。
    • POOL_MODE：指定何时可以由其他客户端重复使用数据库连接。将该参数设置为以下任一项：
      • session：客户端断开连接后，数据库连接会释放回连接池。默认使用。
      • transaction：事务完成后，数据库连接会释放回连接池。
      • statement：查询完成后，数据库连接会释放回连接池。在此模式下，不允许跨多个语句的事务。
    • IGNORE_STARTUP_PARAMETERS：指定 PgBouncer 不允许的参数，以便在启动期间忽略这些参数，例如 extra_float_digits。如需了解详情，请参阅 PgBouncer 配置。
    • DEFAULT_POOL_SIZE：每个用户-数据库对允许的数据库连接数，例如 8。
    • MAXIMUM_CLIENT_CONNECTIONS：客户端连接数上限，例如 800。
    • MAXIMUM_DATABASE_CONNECTIONS：数据库连接的数量上限，例如 160。

  2. 应用清单：

    kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE

    将 PATH_TO_MANIFEST 替换为清单文件的路径，例如 /fleet/config/pgbouncer.yaml。

  3. 如需验证您创建的 PgBouncer 对象是否已准备就绪，请执行以下查询：

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

    将 NAMESPACE 替换为 PgBouncer 对象的 Kubernetes 命名空间的名称。

    输出类似于以下内容：

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

连接到连接池程序端点

您可以从 Kubernetes 集群的内部或外部连接到 PgBouncer 连接池。

从 Kubernetes 集群内连接

如需使用 psql 客户端连接到连接池终端，请按以下步骤操作：

  1. 创建一个 Pod，如下所示：

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

  2. 应用清单：

    kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE

  3. 连接到容器化应用：

    kubectl exec -it postgres -n NAMESPACE -- bash

  4. 使用 psql 客户端验证与 PgBouncer 端点的 SSL 连接：

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

    替换以下内容：

    • HOST：您使用 kubectl get pgbouncers.alloydbomni.dbadmin.goog -n NAMESPACE 命令获取的连接池端点。如果 PgBouncer 未作为服务公开，请使用其 IP 地址。
    • PORT：PgBouncer 监听的端口。

    终端窗口会显示以 postgres=# 提示结尾的 psql 登录文本。

从 Kubernetes 集群外部连接

如需从 Kubernetes 集群外部访问 PgBouncer 连接池，请将 serviceOptions 属性中的 type 字段设置为 LoadBalancer，这会创建一个 loadbalancer 服务。

  1. 在 Kubernetes 集群中创建 PgBouncer 自定义资源，如下所示：

    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. 应用清单：

    kubectl apply -f PATH_TO_MANIFEST

  3. 如需验证您创建的 PgBouncer 对象是否已准备就绪，请执行以下查询：

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

    输出类似于以下内容：

    NAME          ENDPOINT       STATE
mypgbouncer   10.138.15.207   Ready

配置 PgBouncer 设置

使用以下参数配置 PGBouncer 设置：

参数 说明 默认值
pool_mode 指定其他客户端何时可以重复使用数据库连接。
允许的值如下：
  • session：客户端断开连接后，数据库连接会释放回连接池。
  • transaction：事务完成后，数据库连接会释放回连接池。
  • statement：查询完成后，数据库连接会释放回连接池。
    在此模式下，不允许跨多个语句的事务。
 session
ignore_startup_parameters 指定 PgBouncer 不允许的参数，以便在启动期间忽略这些参数。
default_pool_size 每个用户-数据库对允许的数据库连接数。 20
max_client_conn 客户端连接数上限。 100
max_db_connections 数据库连接数上限。 0

自定义 PgBouncer 部署

AlloyDB Omni 使用自定义资源来管理其组件。如需在 Kubernetes 上的 AlloyDB Omni 中自定义 PgBouncer 部署，请按如下方式修改 PgBouncer 自定义资源：

  1. 列出 PgBouncer 自定义资源：

    kubectl get pgbouncers -n NAMESPACE

    将 NAMESPACE 替换为您部署 AlloyDB Omni 的命名空间。

  2. 如需修改资源，请在默认编辑器中打开 PgBouncer 资源的声明文件：

    kubectl edit pgbouncers PGBOUNCER_NAME -n NAMESPACE

  3. 在声明文件中，找到包含配置的 podSpec 部分，并根据需要修改以下任一字段：

    • resources：为容器定义的 cpu 和 memory：

      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：PgBouncer 图片标记的路径：

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

    • schedulingconfig：添加 nodeaffinity 部分，以控制 PgBouncer Pod 的调度位置：

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

      替换以下内容：

      • NODE_AFFINITY_TYPE：将此参数设置为以下其中一项：
        • requiredDuringSchedulingIgnoredDuringExecution：Kubernetes 会完全根据定义的规则调度 Pod。
        • preferredDuringSchedulingIgnoredDuringExecution：Kubernetes 调度器会尝试找到符合所定义调度规则的节点。不过，如果没有这样的节点，Kubernetes 会将 Pod 调度到集群中的其他节点。
      • LABEL_KEY：节点的键标签，该键用作位置指示器，有助于在集群中均匀分配 Pod，例如 nodetype。
      • OPERATOR_VALUE：表示键与一组值的关系。将该参数设置为以下任一项：
        • In：值数组不得为空。
        • NotIn：值数组不得为空。
        • Exists：值数组必须为空。
        • DoesNotExist：值数组必须为空。
        • Gt：值数组必须包含一个元素，该元素会被解读为整数。
        • Lt：值数组必须包含一个元素，该元素会被解读为整数。

  4. 进行更改后，保存声明文件。AlloyDB Omni Kubernetes Operator 会自动将更改应用于您的 PgBouncer 部署。

删除 PgBouncer 资源

如需删除 PgBouncer 自定义资源，请运行以下命令：

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

输出类似于以下内容：

pgbouncer.alloydbomni.dbadmin.goog "mypgbouncer" deleted

查看 PgBouncer 日志

您可以按如下方式查看和分析 Kubernetes 上 AlloyDB Omni 部署中的任何 PgBouncer 副本实例的日志：

  1. 获取命名空间中所有 PgBouncer Pod 的列表：

    kubectl get pods -n NAMESPACE

    输出类似于以下内容：

    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. 查看特定 Pod 的日志：

    kubectl logs -f POD_NAME -n NAMESPACE

    输出类似于以下内容：

    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

监控 PgBouncer 性能和活动

您可以仅使用专用 statsuser 访问 PgBouncer 内部统计数据库，从而查看 PgBouncer 连接池指标。statsuser 用于在连接到 PgBouncer 数据库时进行身份验证。

  1. 使用 psql 客户端以超级用户或具有 CREATE ROLE 权限的用户身份连接到 AlloyDB Omni：

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

    输出类似于以下内容：

    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. 在 AlloyDB Omni 中创建 statsuser：

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

    输出类似于以下内容：

    CREATE ROLE
postgres=#

  3. 以 statsuser 身份连接到 PgBouncer 数据库：

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

    输出类似于以下内容：

    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. 运行 SHOW STATS 命令以查看 PgBouncer 性能并发现潜在问题：

    pgbouncer=# SHOW STATS;

    输出类似于以下内容：

         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)

停用 PgBouncer 连接池

如果您需要停用或回滚 PgBouncer 连接池，请按以下步骤操作：

  1. 检查连接池的状态：

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

    此命令会显示用于管理 AlloyDB Omni 车队的主控制器的部署清单。在 containers 数组的 args 部分中找到 --enable-pgbouncer 选项：

    ...
 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. 修改控制器部署的配置以停用连接池：

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

  3. 在部署清单中，将 --enable-pgbouncer 选项的值从 true 更改为 false：

    ...
--enable-pgbouncer=false

  4. 保存文件并退出编辑器。 kubectl 会自动应用更改。

后续步骤