PgBouncer 连接池调优实战手册 + 慢连接/连接泄漏排查脚本（Bash，覆盖 5 个典型瓶颈场景）

背景

PgBouncer 是 PostgreSQL 生态里最主流的连接池中间件，生产环境里"连接池耗尽""慢连接堆积""事务模式配错导致数据不一致"这三类问题我五年里反复遇到。很多团队把 PgBouncer 当黑盒部署，出了问题只会 kill -9 重启，缺乏系统性的调优方法论和可复现的排查手段。

最终要什么

1. PgBouncer 调优手册（Markdown，≥1500 字）：覆盖 pool_mode（transaction / session / statement）、max_db_connections、server_lifetime、server_idle_timeout、idle_transaction_timeout、query_wait_timeout 等 ≥5 个核心参数的配置策略。每个参数须附"为什么这么配"与"不配 / 配错会怎样"。附 3 种典型业务场景（高并发短查询、长事务批处理、混合负载）的完整推荐配置，配置须带注释。

2. Bash 一键诊断脚本：覆盖 5 个典型瓶颈场景——①连接池耗尽（waiting 队列堆积）②慢连接堆积（server 侧长查询）③事务模式误配（session 模式下的长 idle）④连接泄漏（client 侧连接不释放）⑤服务端连接风暴（频繁 server 重建）。每个场景须有明确的检测逻辑（读 PgBouncer 的 SHOW POOLS / SHOW STATS / SHOW CLIENTS / SHOW SERVERS 输出）和修复建议输出。

3. PostgreSQL 侧配合排查 SQL 查询集（.sql 文件）：≥5 条查询，联合 pg_stat_activity、pg_stat_statements、pg_locks 做交叉分析，每条附预期输出示例与解读。

输入与上下文

• PgBouncer 1.21+，PostgreSQL 14+
• 假设 PgBouncer 已部署且 pg_stat_statements 已启用
• Bash 脚本兼容 Bash 4+（Linux），仅依赖标准工具（psql / awk / grep / curl），不依赖 pip / apt 额外包
• 手册面向有 PostgreSQL 基础但首次接触 PgBouncer 的工程师

交付格式

• 一份 Markdown 手册（调优指南 + 3 种场景配置）
• 一个可执行 Bash 脚本（含 #!/usr/bin/env bash、set -euo pipefail、完整注释）
• 一个 .sql 查询集文件
• 以上 3 个文件作为交付物附件提交