PostgreSQL / 系统课时

配置 PgBouncer 事务池

配置 PgBouncer 事务池

本课完成一个可验证的 PgBouncer 事务级连接池配置:客户端可以建立较多连接,但 PostgreSQL 后端连接受池大小约束,从而把连接峰值隔离在代理层。

学习目标

  • 能配置事务级池化并理解 pool_mode、default_pool_size 与 max_client_conn 的职责
  • 能通过 PgBouncer 管理接口和 PostgreSQL 观察客户端连接与后端连接数量
  • 能识别事务池不能安全承载的会话状态,并为上线验证设置边界

先确定两个连接数量

事务池的核心不是让所有客户端共享同一个数据库连接,而是让一个客户端事务结束后,服务器连接回收到池中供其他事务复用。因此,客户端连接数与 PostgreSQL 后端连接数可以明显分离。

PgBouncer 事务池中客户端连接与数据库连接的数量关系

max_client_conn 控制 PgBouncer 最多接受多少客户端连接;default_pool_size 控制每个用户/数据库池可建立的常规服务器连接数。两者不是一回事:前者主要保护 PgBouncer 自身的客户端连接承载能力,后者主要约束 PostgreSQL 后端并发连接预算。

配置事务池

下面给出一个最小实验配置。应用统一连接到 PgBouncer 的 6432 端口,PgBouncer 再连接 PostgreSQL 的 5432 端口。生产环境应结合数据库实例容量,按用户、数据库等维度细分池大小。

ini
[databases]
appdb = host=127.0.0.1 port=5432 dbname=appdb

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
pool_mode = transaction
max_client_conn = 200
default_pool_size = 20
reserve_pool_size = 5
reserve_pool_timeout = 3
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
admin_users = appuser

预期结果

该配置让 PgBouncer 以事务级方式复用服务器连接。正常情况下,每个用户/数据库池的常规服务器连接上限为 20,客户端连接上限为 200;当客户端等待时间满足 reserve_pool_timeout 条件时,还可启用最多 5 个预留服务器连接。admin_users = appuser 允许该账号访问 PgBouncer 管理数据库;生产环境应使用专门的管理账号并限制访问来源。

让客户端连接进池,而不是直连数据库

假设 PgBouncer 已按上面的配置启动,客户端使用 6432 而不是 PostgreSQL 的 5432。先从 PgBouncer 管理接口查看池状态。

bash
psql "host=127.0.0.1 port=6432 dbname=pgbouncer user=appuser" -c "SHOW POOLS;"

预期输出

text
database | user    | cl_active | cl_waiting | sv_active | sv_idle | maxwait
appdb    | appuser | <N>       | <N>        | <N>       | <N>     | <N>

重点观察 cl_active、cl_waiting、sv_active 与 sv_idle。在事务池模式下,客户端连接数增加时,sv_active 不应无条件按客户端数一比一增长,而会受到池大小和当前事务并发的共同约束。实际数值会随事务持续时间、池是否预热和数据库负载变化。

再从 PostgreSQL 侧观察实际服务器连接:

sql
SELECT usename, application_name, count(*) AS connections
FROM pg_stat_activity
WHERE datname = 'appdb'
GROUP BY usename, application_name
ORDER BY connections DESC;

预期结果

text
 usename | application_name | connections
---------+------------------+------------
 appuser |                  | <N>

这里的 <N> 表示当前实验时刻按用户和应用名聚合后的服务器连接数,实际值可能不同。它应与 PgBouncer 当前已建立的服务器连接规模大致对应,并受池大小约束。若同时存在直连 PostgreSQL 的应用,查询结果还会包含这些非池化连接,因此验收前应先确认所有业务访问路径都经过 PgBouncer。

事务池最容易踩到的边界

事务池只保证事务期间占用同一个服务器连接。事务结束后,该连接可以服务另一个客户端,因此依赖物理连接长期存在的会话状态不能默认认为安全。

常见风险包括临时表、会话级参数、会话级状态,以及其他必须跨多个事务保持的连接上下文。服务端准备语句、驱动连接初始化行为等也应结合实际 PgBouncer 版本和客户端驱动验证,不能因为 SQL 本身可执行,就直接判定兼容。

上线前应做一次“两个事务之间换连接”的测试:事务 A 设置或创建某种会话状态并提交,事务 B 再访问该状态。只要业务语义要求状态一定存在,就不能把它当作普通事务池能力直接上线。

最终验收应同时记录三类数据:应用看到的客户端连接数、PgBouncer 池中的服务器连接数,以及 PostgreSQL pg_stat_activity 中的实际连接数。只有三者关系与容量预算一致,事务池配置才算真正落地。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

配置 PgBouncer 事务池

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通