PostgreSQL数据库服务器如何配置PgBouncer连接池?怎样验证连接复用
首次部署 PgBouncer,可以把它放在应用与 PostgreSQL 之间,让应用连接到 PgBouncer 的监听端口,由 PgBouncer 按连接池策略复用 PostgreSQL 后端连接。以下以使用 systemd 的 Debian/Ubuntu 服务器为例,假设 PostgreSQL 已运行、应用数据库和数据库账号已创建,PgBouncer 与 PostgreSQL 部署在同一台服务器上。

示例采用事务级连接池,并只监听本机回环地址。事务级池适合应用在事务结束后不依赖同一数据库会话的场景;如果应用依赖临时表、会话级设置、会话锁或跨事务保持的预处理语句,应先确认兼容性,必要时改用会话级连接池。
准备条件
开始前确认以下信息,并在配置变更前备份现有 PgBouncer 配置(如果已经存在):
- PostgreSQL 正常运行,且应用账号有目标数据库的登录权限。
- 已知数据库名、应用账号和密码;以下示例使用
appdb和app_user。 - 应用服务器能够访问 PgBouncer 监听地址。本文配置只允许本机连接;若应用在其他主机上,需另行使用内网地址,并限制访问来源。
- 已安装
psql客户端,用于测试连接和查看连接池状态。
先检查 PostgreSQL 服务及本地连接:
sudo systemctl status postgresql --no-pager
psql -h 127.0.0.1 -p 5432 -U app_user -d appdb -c 'SELECT 1;'
预期查询返回一行 1。若服务未运行,或账号无法直连数据库,先解决 PostgreSQL 服务、账号权限或认证问题;PgBouncer 不会替代数据库账号授权。
安装 PgBouncer
更新软件包索引并安装:
sudo apt update
sudo apt install pgbouncer
确认安装版本和服务状态:
pgbouncer --version
systemctl status pgbouncer --no-pager
不同发行版的软件包版本和默认配置可能不同。Debian/Ubuntu 通常将配置放在 /etc/pgbouncer/pgbouncer.ini,但在编辑前应先检查实际服务参数:
systemctl cat pgbouncer
确认服务启动时读取的配置文件路径。若安装后服务未启动,先检查日志,不要在尚未确认配置路径时直接创建另一份配置:
sudo journalctl -u pgbouncer -n 50 --no-pager
配置账号认证与连接池
PgBouncer 的认证文件包含数据库密码或密码校验信息,应限制文件读取权限。以下示例使用 SCRAM 客户端认证,并在认证文件中保存明文密码,因此文件权限和主机访问控制尤其重要。生产环境应使用独立的应用账号,不要把 PostgreSQL 超级用户用于应用连接。
编辑 /etc/pgbouncer/userlist.txt,为应用账号和 PgBouncer 管理控制台账号各添加一行。将示例密码替换为实际密码:
"app_user" "替换为应用账号密码"
"pgbouncer_admin" "替换为管理账号密码"
管理账号只用于查看 PgBouncer 状态,不需要在 PostgreSQL 中创建同名账号。收紧认证文件权限;先检查软件包创建的运行用户和组,再按实际组名执行:
id pgbouncer
sudo chown root:pgbouncer /etc/pgbouncer/userlist.txt
sudo chmod 640 /etc/pgbouncer/userlist.txt
如果系统没有 pgbouncer 组,或服务运行用户与示例不同,应使用 systemctl cat pgbouncer 确认服务身份后再调整属主。不要通过开放为所有用户可读来绕过权限问题。
编辑 /etc/pgbouncer/pgbouncer.ini。保留发行版原有的日志、运行用户等必要设置,只调整或补充以下参数,避免重复定义同一配置项:
[databases]
appdb = host=127.0.0.1 port=5432 dbname=appdb
[pgbouncer]
listen_addr = 127.0.0.1
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
default_pool_size = 20
max_client_conn = 200
admin_users = pgbouncer_admin
这里 default_pool_size 是每个数据库与用户组合连接池的默认后端连接上限,不是 PgBouncer 全局的 PostgreSQL 连接总上限。若有多个数据库或用户组合,后端连接数可能累加。max_client_conn 限制 PgBouncer 接受的客户端连接数,也不等于 PostgreSQL 后端连接数。
保存后核对配置文件内容、账号拼写和密码,并确保应用账号在 PostgreSQL 中使用的密码与认证文件中的密码一致。若 PostgreSQL 的认证策略或账号密码格式不兼容,应先确认 PgBouncer 和 PostgreSQL 的版本及认证配置,不要简单改成弱认证方式。
检查监听范围与端口
示例仅监听 127.0.0.1:6432,适用于应用与 PgBouncer 在同一主机的情况。此时不需要开放公网端口。若应用部署在其他服务器,应将 listen_addr 改为适用的内网地址,并通过主机防火墙或网络访问控制,仅允许应用服务器访问 6432 端口;不要将管理端口暴露给不可信网络。
配置写入后,确认 PostgreSQL 仍在 5432 监听,PgBouncer 使用独立的 6432 端口:
sudo ss -lntp | grep -E ':(5432|6432)\b'
首次启动前,6432 端口应尚未被其他进程占用。若已占用,应先查明进程用途,再决定是否调整端口。
启动并逐步验证
先重启服务使首次配置生效:
sudo systemctl restart pgbouncer
sudo systemctl status pgbouncer --no-pager
预期服务状态为 active (running)。若未启动,查看近期日志:
sudo journalctl -u pgbouncer -n 80 --no-pager
常见原因包括配置项重复或拼写错误、认证文件不可读、监听端口冲突,以及服务运行身份不匹配。修正后再重启,并确认服务状态恢复正常。
随后通过 PgBouncer 连接应用数据库:
psql -h 127.0.0.1 -p 6432 -U app_user -d appdb -c 'SELECT current_database(), current_user;'
预期返回 appdb 和 app_user。这一步验证的是客户端能够通过 PgBouncer 完成认证并访问 PostgreSQL;它本身还不能证明多个客户端连接已经复用同一组后端连接。
验证连接复用
使用管理控制台查看连接池。pgbouncer_admin 需要出现在 admin_users 中,且其密码需写入认证文件:
psql -h 127.0.0.1 -p 6432 -U pgbouncer_admin -d pgbouncer
连接后执行:
SHOW POOLS;
SHOW SERVERS;
SHOW STATS;
重点查看 SHOW POOLS 中目标数据库和用户对应的 cl_active、cl_waiting、sv_active、sv_idle 等列:
cl_active表示正在使用 PgBouncer 的客户端连接数。sv_active表示正在执行请求的 PostgreSQL 后端连接数。sv_idle表示已建立但当前空闲、可供复用的后端连接数。cl_waiting持续大于 0,表示有客户端在等待可用后端连接,需要进一步检查池容量、数据库响应时间和连接使用方式。
验证复用时应制造并发客户端连接,并在测试结束后观察连接池。短时间的串行查询可能看不出连接复用效果。可以用 pgbench 进行一段有限时长的并发测试;测试前确认目标数据库允许执行测试查询,避免在生产高峰期间产生不必要负载:
pgbench -h 127.0.0.1 -p 6432 -U app_user -d appdb -c 30 -j 4 -T 30
测试过程中或结束后,在管理控制台再次运行 SHOW POOLS;。如果客户端数明显高于后端连接数,且 sv_idle 在请求间可见,通常说明连接正在池中等待并被后续请求复用。具体数量会受并发、事务持续时间、数据库用户组合及负载影响,不能只凭一次测试得出固定容量结论。
也可以在 PostgreSQL 侧观察来自本机的数据库连接数。以下查询会统计当前连接到 appdb 的会话:
SELECT usename, application_name, state, count(*)
FROM pg_stat_activity
WHERE datname = 'appdb'
GROUP BY usename, application_name, state
ORDER BY usename, state;
PgBouncer 建立的后端连接数应与客户端并发数区分看待。若测试期间出现连接等待,先对照 SHOW POOLS 的等待数和空闲后端数,再判断是否需要调整连接池,而不是直接大幅增加 PostgreSQL 的 max_connections。
A5idc数据提供中国香港、美国、日本等地区的物理服务器,涵盖Xeon Gold、AMD EPYC等计算平台,部分方案配有较大内存和NVMe存储。这些资源可用于部署PostgreSQL、PgBouncer连接池及业务后台;不同地区的线路与带宽方案,也为面向不同访问人群的数据库应用提供部署选择。
常见失败处理
| 现象 | 优先检查 | 处理方向 |
|---|---|---|
| 服务无法启动 | journalctl -u pgbouncer、配置路径、配置项拼写 | 按日志修正格式或路径,再重启服务 |
| 客户端报认证失败 | 用户名、认证文件权限、密码是否与 PostgreSQL 账号一致 | 修正认证信息;避免通过降低认证强度解决问题 |
| PgBouncer 可连接但数据库拒绝登录 | PostgreSQL 账号状态、数据库权限、pg_hba.conf 规则 | 确认 PostgreSQL 允许来自 PgBouncer 主机的连接,并按变更规范备份和修改认证规则 |
cl_waiting 持续增加 | sv_active、sv_idle、事务是否长时间未提交 | 排查长事务和慢查询,再按容量评估调整池大小 |
| 应用出现会话状态异常 | 是否依赖事务之间保持会话状态 | 评估改用会话级池,或调整应用行为;不要将事务池视为透明的直连替代品 |
若 PgBouncer 与 PostgreSQL 在同一台服务器,PostgreSQL 接收到的连接通常来自本机;若部署在不同主机,则 PostgreSQL 的访问控制还需允许 PgBouncer 所在主机连接。修改 pg_hba.conf 前应备份文件、确认影响范围,并按 PostgreSQL 对应版本的规则格式操作。
事务级池在事务提交或回滚后即可把后端连接交还连接池。应用若在事务之外依赖 SET、临时表、会话级锁等状态,行为可能与直连不同。遇到此类问题,应先确认应用使用的会话特性,再决定是否切换池模式或调整应用逻辑。
验收与回滚
验收时逐项确认:
- PgBouncer 服务处于运行状态,且只监听预期地址和端口。
- 应用账号通过 6432 端口成功连接目标数据库。
- 管理控制台可用,
SHOW POOLS、SHOW SERVERS和SHOW STATS能返回结果。 - 并发测试期间,客户端连接数与 PostgreSQL 后端连接数有明确区分;没有持续增长的等待客户端或异常连接。
- 应用不依赖事务级池无法保持的会话状态,池大小符合数据库连接容量规划。
需要回滚时,先将应用连接地址恢复为原有 PostgreSQL 地址和端口,再确认应用已不再通过 PgBouncer 建立新连接。随后停止并禁用 PgBouncer 服务:
sudo systemctl stop pgbouncer
sudo systemctl disable pgbouncer
若要恢复原配置,先备份当前文件,再从变更前备份恢复 /etc/pgbouncer/pgbouncer.ini 和认证文件,并核对文件权限。确认没有服务依赖该配置后,才考虑卸载软件包;卸载前检查本机是否还有其他应用或服务使用 PgBouncer。回滚完成后,验证应用能够按原连接方式访问 PostgreSQL,并确认 6432 端口不再由 PgBouncer监听。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/6891.html



