4. PgBouncer 介绍：定位、三种模式与适用场景
PgBouncer 是 PostgreSQL 生态中最成熟、最轻量的连接池中间件。它位于应用与 PostgreSQL 服务器之间，核心职责是复用后端连接，解决“大量短连接导致数据库进程膨胀、内存飙升、性能抖动”的经典问题。本章从定位、三种工作模式、适用场景三个维度，帮助你建立对 PgBouncer 的完整认知。
4.1 PgBouncer 的定位
PgBouncer 是一个单进程、事件驱动的连接池代理，设计目标极简：
- 轻量：自身内存占用极低（通常几十 MB），不依赖外部库。
- 高效：使用 libevent 实现异步 I/O，单机可承载数万客户端连接。
- 透明：对应用层仅暴露标准 PostgreSQL 协议，应用无需修改代码。
- 专注：只做连接复用，不做查询路由、读写分离、负载均衡（这些由上层中间件如 Pgpool-II 或应用层处理）。
定位口诀：PgBouncer 是“连接复用器”，不是“查询分发器”。它解决的是连接数膨胀问题，而不是 SQL 性能问题。
4.2 三种工作模式
PgBouncer 提供三种连接复用模式，核心区别在于连接归还时机和事务绑定策略。下表从关键维度进行对比：
| 模式 | 连接归还时机 | 事务绑定 | 会话级功能支持 | 典型场景 |
|---|---|---|---|---|
| Session | 客户端断开连接后 | 整个会话期间独占后端连接 | 完全支持（临时表、会话变量、LISTEN/NOTIFY） | 长连接、ORM 持久会话、需要会话状态的场景 |
| Transaction | 事务提交/回滚后立即归还 | 仅事务期间绑定后端连接 | 不支持（临时表、会话变量在事务结束后失效） | 短事务、Web 应用、API 服务（推荐默认模式） |
| Statement | 每条语句执行后立即归还 | 无事务绑定，每条语句独立 | 不支持（无事务上下文） | 极少使用，仅用于特殊测试或无状态查询 |
4.2.1 Session 模式（会话级复用）
客户端连接 PgBouncer 后，PgBouncer 立即从池中分配一个后端 PostgreSQL 连接，并在整个客户端会话期间保持绑定。客户端断开后，后端连接才归还池中。
- 优点：完全兼容 PostgreSQL 会话特性，支持临时表、
SET语句、LISTEN/NOTIFY、游标等。 - 缺点：连接复用率低，一个客户端会话始终占用一个后端连接，无法应对大量短连接场景。
- 适用：需要保持会话状态的遗留应用、管理工具（如 psql）、ORM 长连接。
4.2.2 Transaction 模式（事务级复用）
客户端连接后，PgBouncer 仅在事务开启期间分配后端连接；事务提交或回滚后，后端连接立即归还池中，供下一个事务使用。客户端会话可能在不同事务中复用不同的后端连接。
- 优点：连接复用率极高，一个后端连接可服务多个客户端会话的事务，显著降低数据库连接数。
- 缺点：不支持会话级状态（临时表、会话变量、未提交事务中的游标等）。
- 适用：Web 应用、微服务、API 网关、短事务为主的 OLTP 场景。这是生产环境最推荐的模式。
4.2.3 Statement 模式（语句级复用）
每条 SQL 语句执行后，后端连接立即归还池中。即使在一个事务内，多条语句也可能使用不同的后端连接。
- 优点：连接复用率最高，几乎不占用后端连接。
- 缺点：破坏事务原子性，不支持多语句事务、不支持
BEGIN/COMMIT、不支持PREPARE等。 - 适用：极少使用。仅用于无状态查询、测试环境或特殊场景（如连接数极度受限）。
生产警告：Statement 模式会破坏事务语义，绝大多数应用不应使用。如果应用依赖事务，请使用 Transaction 模式。
4.3 三种模式架构对比（SVG）
下图直观展示三种模式下客户端连接与后端连接的绑定关系：
4.4 适用场景速查表
| 场景 | 推荐模式 | 原因 |
|---|---|---|
| Web 应用 / REST API | Transaction | 短事务、高并发、无需会话状态，复用率最高 |
| ORM 框架（Hibernate、SQLAlchemy） | Session 或 Transaction | ORM 通常维护长连接，Session 模式兼容性最好；若 ORM 支持连接池，可改用 Transaction 模式提升复用 |
| 管理工具（psql、pgAdmin） | Session | 需要临时表、会话变量、交互式事务 |
| 微服务 / Serverless | Transaction | 函数实例频繁创建销毁，事务级复用可大幅降低数据库连接数 |
| ETL / 批处理 | Session | 长事务、大量数据操作，需要稳定连接 |
| 连接数极度受限（如 RDS 小规格） | Transaction | 最大化连接复用，避免连接数耗尽 |
4.5 配置示例（Transaction 模式）
以下是一个生产级 Transaction 模式配置片段：
# pgbouncer.ini
[databases]
* = host=127.0.0.1 port=5432 dbname=mydb
[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = md5
auth_file = /etc/pgbouncer/userlist.txt
# 核心模式设置
pool_mode = transaction
# 连接池大小
default_pool_size = 25
max_client_conn = 500
max_db_connections = 50
# 超时与清理
server_idle_timeout = 300
client_idle_timeout = 600
query_timeout = 30
# 日志
logfile = /var/log/pgbouncer/pgbouncer.log
pidfile = /var/run/pgbouncer/pgbouncer.pid
关键参数说明：
pool_mode = transaction：启用事务级复用，生产首选。default_pool_size：每个数据库池的后端连接上限，建议设为数据库max_connections的 1/10 ~ 1/5。max_client_conn：PgBouncer 允许的最大客户端连接数，受系统文件描述符限制。server_idle_timeout：后端连接空闲超时，避免长时间占用。
4.6 选型建议
- 新项目默认选 Transaction 模式：绝大多数 OLTP 场景的最佳实践，连接复用率高，资源消耗低。
- Session 模式用于兼容性兜底：当应用依赖会话级特性（临时表、
SET、LISTEN/NOTIFY）且无法改造时，退而求其次。 - Statement 模式仅用于特殊测试：生产环境几乎不应使用。
- 监控先行：无论选择哪种模式，部署后务必监控
avg_wait_time、total_server_connections、client_connections等指标，及时调整池大小。