PgBouncer 交易池解释

PgBouncer 提供了三种模式，其区别仅在于 Postgres 服务器连接何时返回公共池。官方文档将它们命名为 session、 transaction 和 statement （pgbouncer.org/features.html，“池化模式”部分，2026 年 8 月 24 日访问）。

会话模式是最宽松的，但在可扩展性方面效率最低：只要客户端保持连接，Postgres 连接就会保留给客户端，即使它在两个请求之间不执行任何操作。语句模式是为非常特殊的情况（只读代理、健康检查）保留的，甚至会破坏经典的显式事务。事务模式是 REST API 实践中占主导地位的折衷方案：每个 HTTP 请求通常对应于单个短 Postgres 事务。

在事务模式下，PgBouncer 仅在客户端打开事务时将服务器连接附加到客户端，并在 COMMIT 或 ROLLBACK 时将其返回到池中。在两个事务之间，同一个客户端可能会发现自己被重新分配到完全不同的服务器连接。

具体来说，当 default_pool_size 为 20 时，PgBouncer 可以同时吸收数百个客户端，这些客户端在任何给定时间实际上只有少数交易正在进行。正是这个比率证明了具有高流量但短事务的 REST API 的事务模式是合理的：稀有资源（Postgres 连接，服务器端内存昂贵）仅在严格必要的时间内被占用。

[pgbouncer]
listen_port = 5432

; La connexion serveur est libérée dès la fin de chaque transaction
pool_mode = transaction

default_pool_size = 80
max_client_conn = 1000

; Ne pas utiliser avec des sessions stateful (SET, advisory locks, LISTEN/NOTIFY)

最后一条评论总结了要点：事务模式之所以有效，是因为它故意破坏了“我的应用程序会话”和“我的 Postgres 连接”之间的链接。基于此链接的所有内容都会中断。下一节将详细列出内容。

PgBouncer 官方文档明确列出了 PostgreSQL 功能，一旦服务器连接可以在来自同一客户端的两个请求之间回收，这些功能就失去了意义。

大多数现代 Postgres 驱动程序默认在协议端准备命名请求，而无需应用程序代码显式请求它。这正是这个陷阱难以预料的原因。

协议准备语句在 Parse时命名并缓存在特定服务器连接上。在事务模式下，可以在来自同一逻辑客户端的两个请求之间将该连接重新分配给另一个客户端。如果驱动程序随后在从未准备好的连接上重播相同的语句名称，则 Postgres 会以显式错误进行响应，对于 sqlx 客户端，通常为 prepared statement "sqlx_s_N" does not exist 。该行为是间歇性的：它取决于连接在负载下的执行情况，而不取决于每次调用时可重现的确定性错误。

无论语言如何，客户端更正都是相同的：对于在事务模式下跨越池化器的任何池，禁用命名准备语句的缓存，或强制未命名查询。在带有 sqlx 的 Rust 中，它通过连接选项上的 statement_cache_capacity(0) 。

let connect_options = url
    .parse::<PgConnectOptions>()?
    .statement_cache_capacity(0);

// 等价物：asyncpg -> statements_cache_size=0, pgjdbc ->prepareThreshold=0

从版本 1.21 开始，PgBouncer 缓解了服务器端的部分问题：它可以在事务模式下遵循协议准备好的语句，并在分配的连接上动态准备它们，每个连接都有一个 LRU 缓存，其大小可通过 max_prepared_statements调整。这减少了未命中的次数，但并不能免除您在多租户池中禁用客户端缓存的情况，其中 search_path 从一个请求更改为另一个请求：缓存的计划会在 Parse时冻结已解析表的内部标识符 (OID)，并且在另一个架构下重播它可能会从错误的租户返回数据，而不是简单的错误。

Aurabase 存储库将 PgBouncer 部署为共享数据平面 (deploy/helm/aurabase/templates/infra/pgbouncer.yaml) 前面的 pool_mode=transaction ，并在租户的每个专用 Postgres 实例 (deploy/cnpg/tenant-pooler.yaml) 前面部署相同配置的 Pooler CNPG。两条路径都应用上述相同的规则。

源代码记录了这种选择的特定安全原因，而不仅仅是稳定性原因。租户之间共享的 Postgres 池在重用连接上为每个项目放置不同的 search_path 。缓存的准备好的语句会在 Parse时冻结已解析表的 OID；在同一连接上为另一个租户重播它会针对第一个租户的架构运行查询，这是一种隔离绕过，而不仅仅是应用程序错误。 因此，毫无例外地应用 statement_cache_capacity(0)，包括在事务模式下也通过 CNPG Pooler 的专用实例上。

第二个会话卫生措施：当每个连接返回池时，挂钩执行 DISCARD ALL （重置设置、在服务器端取消分配准备好的语句、释放咨询锁、清除游标和临时表）。如果没有此钩子，先前请求所造成的会话残留可能会在来自不同租户的下一个请求中泄漏，从而重用相同的回收连接。

Exception accepted: dedicated PostgREST instances remain in direct connection to the primary, without going through the pooler. PostgREST schema reloading relies on LISTEN/NOTIFY, which assumes a persistent connection, exactly the functionality that transaction mode breaks (detail already documented in our article on PostgREST compatibility at Aurabase). RLS settings per request are passed to SET LOCAL within an explicit transaction, the only way to remain compatible with a pool that can change server connections at any COMMIT (see our article onmulti-tenant RLS isolation).

一个简短的清单，适用于在事务模式下从直接 Postgres 连接转移到 PgBouncer 的任何后端。

1. 审核应用程序代码。 查找非事务 SET、 LISTEN/NOTIFY、会话咨询锁、 WITH HOLD 游标和查询之间重用的临时表。
2. 在显式事务中将会话集替换为本地 集。这是唯一能够在连接回收后正常存在的设​​置，因为它在 COMMIT/ROLLBACK 时被清除，而不是在下一个连接时泄漏。
3. 如果您的池遍历池程序并且模式或角色从一个请求更改为另一请求，则 禁用驱动程序端准备好的语句缓存。性能成本是真实但可衡量的，并且远低于租户之间泄漏的风险。
4. 将真正需要 会话模式（迁移、管理脚本、任何依赖于 LISTEN/NOTIFY 的内容）的连接隔离到直接非池化连接，而不是放弃所有其他流量的事务模式。
5. 大小 default_pool_size 和 max_client_conn 相对于 Postgres 的实际 max_connections，而不是从另一个项目复制的任意数字。
6. 在实际负载下进行测试，而不仅仅是冒烟测试。 准备好的语句错误和会话设置泄漏几乎不会出现在单个本地连接上。
7. 一旦投入生产，就从 PgBouncer 管理控制台监控 SHOW POOLS 和 SHOW STATS，以便在客户端可见之前发现池饱和情况。

不，但它是绝大多数 REST API 的正确默认选择。对于严重依赖于无法快速重构的会话功能的遗留应用程序，或者对于池增益无法补偿迁移工作的低流量，会话模式仍然是首选。

PgBouncer 也不是该池模型的唯一实现：Supavisor (Supabase) 和 PgCat 是最近的两个替代方案，在负载分配和集群方面有不同的权衡。请参阅我们的详细比较 PgBouncer vs Supavisor vs PgCat，根据您的拓扑在三者之间进行选择。

在生产中激活交易模式后最常出现的问题。