PgBouncer 1.26.1 常用 CLI 命令与工具详解
PgBouncer 1.26.1 运维命令全量实测：pgbouncer 命令行、admin console 全部 SHOW/RELOAD/PAUSE/RESUME/DISABLE/ENABLE/KILL 等命令回显、1.26 移除命令对照（SUSPEND/SHOW FDS）、systemd 与系统层排查工具及组合实战。
PgBouncer 1.26.1 常用 CLI 命令与工具详解
目标：系统整理 PgBouncer 1.26.1 的全部日常运维命令——pgbouncer 命令行参数、管理控制台（admin console）全量 SHOW/运维命令、systemd 与系统级排查工具，并附真实环境实测回显。文中全部命令与回显均在「Ubuntu 22.04.5 LTS + PgBouncer 1.26.1 + PostgreSQL 18.6 后端」环境实测通过。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（pgb-server 10.89.56.3 作为 PgBouncer 服务器，pg18-server 10.89.56.2 作为 PostgreSQL 服务器）
- 系统架构：x86_64
- PgBouncer：1.26.1（源码编译安装于 /usr/local，systemd 托管，单元文件 /etc/systemd/system/pgbouncer.service）
- PostgreSQL：18.6（后端，业务库 appdb / 管理库 admindb，账号 appuser / postgres，密码 q1w2e3r4）
- psql 客户端：psql (PostgreSQL) 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1)
- 管理控制台入口：
PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -p 6432 -U postgres pgbouncer - 日志：/var/log/pgbouncer/pgbouncer.log
二、前置条件
- PgBouncer 运行中，业务链路可用：
systemctl is-active pgbouncer && PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -p 6432 -U appuser appdb -c "SELECT 1 AS ok;"
实测回显：
active
ok
----
1
(1 row)
- 管理控制台可达（postgres 属于 admin_users）：
PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -p 6432 -U postgres pgbouncer -c "SHOW VERSION;"
实测回显：
version
------------------
PgBouncer 1.26.1
(1 row)
三、CLI 工具总览
PgBouncer 的运维面由三层构成，本文按此组织：
| 层 | 工具/入口 | 用途 |
|---|---|---|
| 进程层 | pgbouncer 命令行 | 启动、版本查看、前台/后台运行 |
| 协议层 | 管理控制台（虚拟库 pgbouncer） | 全部在线观测与运维动作（SHOW/RELOAD/PAUSE/...） |
| 系统层 | systemctl / journalctl / ss / tail | 服务托管、日志、端口排查 |
四、pgbouncer 命令行
4.1 版本与帮助
/usr/local/bin/pgbouncer -V
实测回显：
PgBouncer 1.26.1
libevent 2.1.12-stable
adns: evdns2
tls: OpenSSL 3.0.2 15 Mar 2022
systemd: yes
版本信息行解读：libevent 是事件循环后端；adns 行显示异步 DNS 实现（evdns2 为 libevent 内置，装 c-ares 编译后可升级为 cares）；tls 行显示编译链接的 OpenSSL 版本；systemd: yes 表示支持 Type=notify。
/usr/local/bin/pgbouncer -h
实测回显（官方用法说明）：
Usage: pgbouncer [OPTION...] config.ini
-d, --daemon Run in background (as a daemon)
-R, --restart Do an online restart
-q, --quiet Run quietly
-v, --verbose Increase verbosity
-u, --user=USERNAME Assume identity of USERNAME
-V, --version Show version
-h, --help Show this help and exit
参数解读：-d 后台运行；-u 指定运行身份（systemd 场景由 unit 的 User= 承担）；-v 提高日志详细度（可叠加 -vv）；-q 压低输出。注意：-R（在线重启/takeover）在 1.26.0 起已移除，本系列所有实测均在 1.26.1 上进行，滚动发布请改用 so_reuseport 多实例方案。
4.2 启动方式
前台运行（调试用，Ctrl+C 退出）：
/usr/local/bin/pgbouncer /etc/pgbouncer/pgbouncer.ini
后台运行（无 systemd 场景，postgres 用户执行）：
su postgres -c "/usr/local/bin/pgbouncer -d /etc/pgbouncer/pgbouncer.ini"
启动成功的日志尾行（实测回显）：
2026-10-19 16:38:56.621 UTC [11323] LOG listening on 0.0.0.0:6432
2026-10-19 16:38:56.621 UTC [11323] LOG listening on unix:/var/run/pgbouncer/.s.PGSQL.6432
2026-10-19 16:38:56.621 UTC [11323] LOG process up: PgBouncer 1.26.1, libevent 2.1.12-stable (epoll), adns: evdns2, tls: OpenSSL 3.0.2 15 Mar 2022
生产环境统一走 systemd 托管，日常不需要手工执行 pgbouncer 命令行。
五、管理控制台命令全解
5.1 连接方式与权限
管理控制台是"连接到名为 pgbouncer 的虚拟库"：
PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -p 6432 -U postgres pgbouncer
权限规则：admin_users 列表中的用户可执行全部命令；stats_users 用户只能执行 SHOW 类；普通业务用户连接 pgbouncer 虚拟库会被拒绝。切勿把 admin_users 暴露给业务账号。
5.2 SHOW HELP——命令总索引
带分号执行（SHOW HELP;）实测回显（1.26.1 全量）：
NOTICE: Console usage:
NOTICE: SHOW HELP | VERSION | CONFIG | DATABASES | POOLS | CLIENTS | SERVERS | USERS
NOTICE: SHOW LISTS | MEM | STATE | STATS | STATS_TOTALS | STATS_AVERAGES | TOTALS
NOTICE: SHOW ACTIVE_SOCKETS | DNS_HOSTS | DNS_ZONES | DNS_ARGS | PEERS | PEER_POOLS
NOTICE: RELOAD | PAUSE [<db>] | RESUME [<db>] | DISABLE <db> | ENABLE <db>
NOTICE: RECONNECT [<db>] | KILL <db> | KILL_CLIENT <client_id>
NOTICE: WAIT_CLOSE [<db>] | SHUTDOWN | SHUTDOWN WAIT_FOR_SERVERS | SHUTDOWN WAIT_FOR_CLIENTS
NOTICE: SET verbose = 0 | 1
⚠️ 注意（实测发现）：HELP 文本中列出了
DNS_ARGS，但实际执行SHOW DNS_ARGS会报错——实测回显：ERROR: invalid command 'SHOW DNS_ARGS', use SHOW HELP;即 1.26.1 的 HELP 提示与实现存在不一致，DNS 相关可用命令实测只有
SHOW DNS_HOSTS与SHOW DNS_ZONES。这属于真实踩坑点：以 HELP 文本为线索、以实际执行为准。
与 1.25.2 的 HELP 对照：SHOW FDS 与 SUSPEND 已消失（1.26.0 移除），新增 SHOW SOCKETS / ACTIVE_SOCKETS 与 SHOW PEERS / PEER_POOLS。
5.3 SHOW 类命令（观测）
SHOW VERSION——版本确认。 回显见前置条件 2。
SHOW DATABASES——库映射与各库状态。 实测回显：
name | host | port | database | force_user | pool_size | min_pool_size | reserve_pool_size | server_lifetime | pool_mode | load_balance_hosts | max_connections | current_connections | max_client_connections | current_client_connections | paused | disabled
-----------+-------------+------+-----------+------------+-----------+---------------+-------------------+-----------------+-----------+--------------------+-----------------+---------------------+------------------------+----------------------------+--------+----------
admindb | pg18-server | 5432 | admindb | | 20 | 0 | 2 | 3600 | | | 50 | 0 | 0 | 0 | 0 | 0
appdb | pg18-server | 5432 | appdb | | 20 | 0 | 2 | 3600 | | | 50 | 0 | 0 | 0 | 0 | 0
pgbouncer | | 6432 | pgbouncer | pgbouncer | 2 | 0 | 0 | 3600 | statement | | 50 | 0 | 0 | 1 | 0 | 0
(3 rows)
要点：虚拟库 pgbouncer 自身固定为 statement 池模式、force_user=pgbouncer；paused/disabled 列非 0 即该库处于维护态。
SHOW POOLS——池状态总览（排障第一命令）。 实测回显（一个客户端在线、空闲，1 条物理连接已分配给它）：
database | user | cl_active | cl_waiting | cl_active_cancel_req | cl_waiting_cancel_req | sv_active | sv_active_cancel | sv_being_canceled | sv_idle | sv_used | sv_tested | sv_login | maxwait | maxwait_us | pool_mode | load_balance_hosts
----------+-----------+-----------+------------+----------------------+-----------------------+-----------+------------------+-------------------+---------+---------+-----------+----------+---------+------------+-----------+--------------------
appdb | appuser | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | session |
pgbouncer| pgbouncer | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | statement |
(2 rows)
核心读法：cl_active=有连接并持有分配或正等结果、cl_waiting=在排队等物理连接、sv_* 为物理连接状态机（active 运行/idle 空闲/used 待回收/tested 校验中/login 建连中）、maxwait=最长排队秒数。PAUSE 期间排队快照（实测，maxwait=2 秒 + 1979 微秒）：
appdb | appuser | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 2 | 1979 | session |
SHOW CLIENTS——客户端明细。 实测回显（两个客户端：业务客户端 id=47、控制台 id=48，均空闲）：
type | user | database | replication | state | addr | port | local_addr | local_port | connect_time | request_time | wait | wait_us | close_needed | ptr | link | remote_pid | tls | application_name | prepared_statements | id
------+----------+-----------+-------------+-------+-----------+-------+------------+------------+-------------------------+-------------------------+------+---------+--------------+----------------+------+------------+-----+------------------+---------------------+----
C | appuser | appdb | none | idle | 127.0.0.1 | 41294 | 127.0.0.1 | 6432 | 2026-10-19 16:54:02 UTC | 2026-10-19 16:54:02 UTC | 0 | 0 | 0 | 0x590dbff7d220 | | 0 | | psql | 0 | 47
C | postgres | pgbouncer | none | idle | 127.0.0.1 | 41298 | 127.0.0.1 | 6432 | 2026-10-19 16:54:04 UTC | 2026-10-19 16:54:04 UTC | 0 | 0 | 0 | 0x590dbff7cf38 | | 0 | | psql | 0 | 48
(2 rows)
要点：id 列即 KILL_CLIENT 的取值来源；state=idle 是 1.25.0 起的新语义（"已连接但空闲"不再显示为 active）；ptr/link 互为对方指针，link 非空表示客户端与物理连接绑定中；prepared_statements 列统计该客户端登记的协议级预编译语句数。
SHOW SERVERS——物理连接明细。 有活动查询时实测回显（物理连接指向后端 10.89.56.2:5432）：
type | user | database | replication | state | addr | port | local_addr | local_port | connect_time | request_time | wait | wait_us | close_needed | ptr | link | id | remote_pid | tls | application_name
------+---------+----------+-------------+------------+------------+------+------------+------------+------------------------+------------------------+------+---------+--------------+----------------+----------------+----+------------+-----+------------------
S | appuser | appdb | none | active | 10.89.56.2 | 5432 | 10.89.56.3 | 39558 | 2026-10-19 16:52:29 | 2026-10-19 16:52:30 | 0 | 0 | 0 | 0x55eab2868650 | 0x55eab28697b0 | 42 | 0 | |
(1 row)
（1.26.1 的 SHOW SERVERS 与 SHOW CLIENTS 同构，多了 srv 版的 state 取值：active/idle/used/tested/login；close_needed=1 表示该物理连接将在用完后关闭——RECONNECT 后会出现。）
SHOW USERS——用户角色。 实测回显：
name | role
----------+-------
appuser | (none)
postgres | admin
(2 rows)
SHOW LISTS——内部列表计数。 实测回显：
list | items
---------------+-------
databases | 3
users | 3
peers | 0
pools | 2
peer_pools | 0
free_clients | 49
used_clients | 1
login_clients | 0
free_servers | 50
used_servers | 0
dns_names | 1
dns_zones | 0
dns_queries | -1
dns_pending | 0
(14 rows)
（dns_queries=-1 为实测原样输出，表示该计数器在 evdns 后端下未启用。）
SHOW CONFIG——全量参数。 98 行参数，每行 key/value/default/changeable 四列（节选，详见配置篇）：
key | value | default | changeable
-----------------------------+-----------------------------------------------+----------------------------------------------------+------------
admin_users | postgres | | yes
auth_file | /etc/pgbouncer/userlist.txt | | yes
auth_type | scram-sha-256 | md5 | yes
listen_addr | 0.0.0.0 | localhost | no
listen_port | 6432 | 6432 | no
max_client_conn | 100 | 100 | yes
pool_mode | session | session | yes
server_idle_timeout | 600 | 600 | yes
changeable=no 的参数（listen_addr/listen_port 等）修改后必须重启进程，yes 的参数 RELOAD 即生效。
SHOW MEM——内存分配器视图。 实测回显（节选前 10 类）：
name | size | used | free | memtotal
---------------------------------+-------+------+------+----------
user_cache | 65928 | 3 | 47 | 3296400
credentials_cache | 65816 | 1 | 49 | 3290800
db_cache | 280 | 3 | 55 | 16240
peer_cache | 280 | 0 | 0 | 0
peer_pool_cache | 744 | 0 | 0 | 0
pool_cache | 744 | 2 | 48 | 37200
outstanding_request_cache | 40 | 0 | 409 | 16360
server_cache | 744 | 0 | 50 | 37200
client_cache | 744 | 1 | 49 | 37200
iobuf_cache | 4112 | 1 | 49 | 205600
(27 rows, 只列出前 10 行)
观测要点：used 持续增长而业务量不变，通常是连接/请求对象泄漏；memtotal 反映预分配池总占。
SHOW STATE——进程态。 实测回显（key/value 两行）：
key | value
--------+-------
active | yes
paused | no
(2 rows)
SHOW STATS——周期统计（核心监控源）。 实测回显（一轮简单查询后，列较多分两段展示）：
database | total_server_assignment_count | total_xact_count | total_query_count | total_received | total_sent | total_xact_time | total_query_time | total_wait_time | total_client_parse_count | total_server_parse_count | total_bind_count | total_client_login_count
-----------+-------------------------------+------------------+-------------------+----------------+------------+-----------------+------------------+-----------------+--------------------------+--------------------------+------------------+--------------------------
appdb | 1 | 1 | 1 | 15 | 154 | 285 | 285 | 7764 | 0 | 0 | 0 | 2
pgbouncer | 0 | 27 | 27 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 27
(2 rows)
database | avg_server_assignment_count | avg_xact_count | avg_query_count | avg_recv | avg_sent | avg_xact_time | avg_query_time | avg_wait_time | avg_client_parse_count | avg_server_parse_count | avg_bind_count | avg_client_login_count
-----------+-----------------------------+----------------+-----------------+----------+----------+---------------+----------------+---------------+------------------------+------------------------+----------------+------------------------
appdb | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
pgbouncer | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
(2 rows)
total_client_login_count 为 1.26.0 新增——数值远超业务连接数即说明有客户端在频繁重连（应用侧池未生效的典型信号）；avg_* 列为按 stats_period（默认 60 秒）折算的每秒均值，周期刚重置时为 0 属正常。
SHOW STATS_TOTALS / STATS_AVERAGES——当期累计与平均。 实测回显：
-- SHOW STATS_TOTALS --
database | server_assignment_count | xact_count | query_count | bytes_received | bytes_sent | xact_time | query_time | wait_time | client_parse_count | server_parse_count | bind_count | client_login_count
-----------+-------------------------+------------+-------------+----------------+------------+-----------+------------+-----------+--------------------+--------------------+------------+--------------------
appdb | 1 | 1 | 1 | 15 | 154 | 285 | 285 | 7764 | 0 | 0 | 0 | 2
pgbouncer | 0 | 33 | 33 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 33
(2 rows)
-- SHOW STATS_AVERAGES --
database | server_assignment_count | xact_count | query_count | bytes_received | bytes_sent | xact_time | query_time | wait_time | avg_client_parse_count | avg_server_parse_count | avg_bind_count | avg_client_login_count
-----------+-------------------------+------------+-------------+----------------+------------+-----------+------------+-----------+------------------------+------------------------+----------------+------------------------
appdb | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
pgbouncer | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
(2 rows)
STATS_TOTALS 是当前统计周期累计，STATS_AVERAGES 是折算均值口径；两者与 SHOW STATS 的 total_/avg_ 列同源。
SHOW TOTALS——进程级累计键值。 实测回显（节选）：
name | value
-------------------------------+-------
total_server_assignment_count | 1
total_xact_count | 29
total_query_count | 29
total_client_bytes | 15
total_server_bytes | 154
total_xact_time | 285
total_query_time | 285
total_wait_time | 7764
total_ps_client_parse_count | 0
total_ps_server_parse_count | 0
total_ps_bind_count | 0
total_client_login_count | 30
avg_server_assignment_count | 0
avg_xact_count | 0
avg_query_count | 0
avg_client_bytes | 0
avg_server_bytes | 0
avg_xact_time | 0
avg_query_time | 0
avg_wait_time | 0
avg_ps_client_parse_count | 0
avg_ps_server_parse_count | 0
avg_ps_bind_count | 0
(25 rows)
SHOW SOCKETS / SHOW ACTIVE_SOCKETS——句柄级视图（1.26.0 起替代 SHOW FDS）。 实测回显（SHOW SOCKETS 前 2 行，列集合为 CLIENTS 全列 + 缓冲区 8 列）：
type | user | database | replication | state | addr | port | local_addr | local_port | connect_time | request_time | wait | wait_us | close_needed | ptr | link | remote_pid | tls | application_name | prepared_statements | id | recv_pos | pkt_pos | pkt_remain | send_pos | send_remain | pkt_avail | send_avail
------+----------+-----------+-------------+-----------+-----------+-------+------------+------------+-------------------------+-------------------------+------+---------+--------------+----------------+------+------------+-----+------------------+---------------------+----+----------+---------+------------+----------+-------------+-----------+------------
C | appuser | appdb | none | cl_active | 127.0.0.1 | 41294 | 127.0.0.1 | 6432 | 2026-10-19 16:54:02 UTC | 2026-10-19 16:54:02 UTC | 0 | 0 | 0 | 0x590dbff7d220 | | 0 | | psql | 0 | 47 | 0 | 0 | 0 | 0 | 0 | 0 | 0
C | postgres | pgbouncer | none | cl_active | 127.0.0.1 | 41358 | 127.0.0.1 | 6432 | 2026-10-19 16:54:04 UTC | 2026-10-19 16:54:04 UTC | 0 | 0 | 0 | 0x590dbff7cf38 | | 0 | | psql | 0 | 54 | 19 | 0 | 0 | 0 | 0 | 19 | 0
(2 rows)
ACTIVE_SOCKETS 仅返回有活动 I/O 的套接字（结构同上），排障"哪个连接的缓冲在积压"用。
SHOW DNS_HOSTS / DNS_ZONES。 DNS_HOSTS 实测回显（pg18-server 解析缓存）：
hostname | ttl | addrs
-------------------+-----+------------------
pg18-server | 0 | 10.89.56.2:0
(1 row)
DNS_ZONES 实测回显（未配 SOA 检查时为空）：
zonename | serial | count
----------+--------+-------
(0 rows)
（SHOW DNS_ARGS 虽出现在 HELP 文本中但实测报 invalid command，见 5.2 节实测发现。）
SHOW PEERS / PEER_POOLS——对等转发视图。 实测回显（未配置 peer 时为空表，属正常态）：
-- SHOW PEERS --
peer_id | host | port | pool_size
---------+------+------+-----------
(0 rows)
-- SHOW PEER_POOLS --
peer_id | cl_active_cancel_req | cl_waiting_cancel_req | sv_active_cancel | sv_login
---------+----------------------+-----------------------+------------------+----------
(0 rows)
5.4 运维动作类命令（实测）
RELOAD——配置在线生效。
PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -p 6432 -U postgres pgbouncer -c "RELOAD;"
实测回显：
RELOAD
行为：重读 ini，changeable=yes 参数即时生效；活动连接与事务不受影响。
PAUSE / RESUME——库级暂停与恢复。 PAUSE 等所有该库服务器连接空闲收编后返回，期间新查询排队。实测 PAUSE：
PAUSE
PAUSE 期间新客户端查询被挂起 2 秒的 SHOW POOLS 快照见 5.3（cl_waiting=1、maxwait=2）。RESUME 恢复后挂起查询立即返回 42（实测）：
paused_test
-------------
42
(1 row)
💡 技术拓展：PAUSE 的标准用法是配合后端维护——「PAUSE → systemctl restart postgresql → RESUME」，事务边界处收线，客户端只感知排队而非报错。PAUSE 完成后 SHOW STATE 的 paused 归 no（暂停是收线过程的瞬时态）。
DISABLE / ENABLE——库级连接闸。 DISABLE 后新客户端连接被拒（已连上的不受影响），实测拒绝回显：
psql: error: connection to server at "127.0.0.1", port 6432 failed: FATAL: database "appdb" is disabled
ENABLE 后连接恢复（SELECT 1 正常）。典型用途：切换 [databases] 映射目标前先 DISABLE 观察流量清零。
RECONNECT——物理连接平滑重建。
RECONNECT
行为：现有物理连接标记 close_needed（用过即关），客户端无感，新事务使用新建连接。适合后端主备切换、白名单变更后强制换线；SHOW SERVERS 中可观察到 close_needed=1 的过渡态。
KILL——库级全断。 客户端正在执行 pg_sleep 时执行 KILL appdb;，客户端侧实测收到：
FATAL: database removed
⚠️ 注意：KILL 后该库处于内部 paused 状态，紧接的全局挂起类操作会报错（实测回显）：
ERROR: cannot suspend with paused databases恢复手段是执行
RESUME appdb;。KILL 是破坏性命令，仅用于连接泄漏/僵尸会话的强制清理。
KILL_CLIENT——精确杀单个客户端。 取 SHOW CLIENTS 的 id（样例 id=47）：
KILL_CLIENT
目标客户端连接立即断开。该命令 1.25.2 起有权限收紧（CVE-2026-6667 修复），仅 admin 可用。
WAIT_CLOSE——等待库连接全部收线。
WAIT_CLOSE
阻塞至该库所有物理连接关闭，常与 PAUSE、后端维护串联。
SHUTDOWN 系列——优雅停机。 SHOW HELP 中三种形态：
SHUTDOWN | SHUTDOWN WAIT_FOR_SERVERS | SHUTDOWN WAIT_FOR_CLIENTS
裸 SHUTDOWN 立即退出；WAIT_FOR_SERVERS 等物理连接空闲后退出；WAIT_FOR_CLIENTS 等客户端全部断开（可能长时间阻塞，适合滚动发布收尾）。systemd 托管下由 KillSignal=SIGINT 驱动同一逻辑，手工等价 kill -INT <pid>。
SET verbose——运行时日志级别。
SET verbose=1
排障时临时开 1，结束 SET verbose = 0; 还原。
5.5 1.26 已移除的命令（升级对照）
| 移除项 | 1.25 及以前用途 | 1.26 替代方案 |
|---|---|---|
| SUSPEND | 全局挂起所有连接（配合 -R takeover） | so_reuseport 多实例滚动重启 |
| SHOW FDS | 导出句柄（takeover 数据面） | SHOW SOCKETS / ACTIVE_SOCKETS |
| pgbouncer -R | 老进程接管（不停服重启） | 多实例 + SHUTDOWN WAIT_FOR_CLIENTS |
从 1.25.x 升级后，旧运维脚本中引用以上命令会报 ERROR: invalid command 'SUSPEND', use SHOW HELP;，需同步改造。
六、系统层运维命令
服务托管（systemd）。
systemctl start pgbouncer
systemctl status pgbouncer --no-pager -l
systemctl reload pgbouncer # SIGHUP，等价控制台 RELOAD
systemctl restart pgbouncer
systemctl enable pgbouncer # 开机自启
journalctl -u pgbouncer -n 50 --no-pager
status 实测回显（节选）：
● pgbouncer.service - connection pooler for PostgreSQL
Loaded: loaded (/etc/systemd/system/pgbouncer.service; enabled; vendor preset: enabled)
Active: active (running) since Mon 2026-10-19 16:41:29 UTC; 3min 12s ago
Main PID: 11502 (pgbouncer)
Tasks: 3 (limit: 5753)
Memory: 8.4M
reload/restart 后 systemctl is-active pgbouncer 均回显 active，systemctl is-enabled pgbouncer 回显 enabled。
端口与连接数核查。
ss -ltnp | grep 6432
实测回显：
LISTEN 0 128 0.0.0.0:6432 0.0.0.0:* users:(("pgbouncer",pid=11502,fd=7))
统计当前经 PgBouncer 的 TCP 连接数：
ss -tn state established '( dport = :6432 or sport = :6432 )' | wc -l
日志实时跟踪与轮转。
tail -f /var/log/pgbouncer/pgbouncer.log
周期统计摘要示例（stats_period=60 实测节选）：
2026-10-19 16:59:03.891 UTC [11502] LOG stats: 0 xacts/s, 0 queries/s, in 0 B/s, out 0 B/s, xact 0 us, query 0 us, wait 0 us
logrotate 片段（/etc/logrotate.d/pgbouncer；PgBouncer 收到 USR1 信号即重开日志文件）：
/var/log/pgbouncer/pgbouncer.log {
daily
rotate 14
compress
missingok
postrotate
/bin/kill -USR1 $(cat /var/run/pgbouncer/pgbouncer.pid)
endscript
}
七、常用组合实战
组合一：后端维护窗口（最常用流水线，逐条执行）
PGPASSWORD=... psql ... pgbouncer -c "PAUSE appdb;" # 1. 事务边界收线，新查询排队
systemctl restart postgresql # 2. 后端维护（另一台机器）
PGPASSWORD=... psql ... pgbouncer -c "RESUME appdb;" # 3. 放行排队查询
组合二：连接泄漏排查
SHOW POOLS; # cl_active 与 sv_active 是否同步异常增长
SHOW CLIENTS; # 按 addr 聚合定位来源；application_name_add_host=1 后更直观
SHOW STATS; # total_client_login_count 异常升高 = 有客户端在反复重连
KILL_CLIENT <id>; # 精确摘除异常连接
组合三：发布后健康巡检
SHOW DATABASES; # paused/disabled 全 0、current_connections 符合预期
SHOW POOLS; # cl_waiting=0、maxwait=0、无 sv_login 堆积
SHOW STATE; # paused=no
SHOW STATS; # 各库 query_count 恢复流量
八、常见问题（FAQ）
Q1：连接 pgbouncer 虚拟库被拒绝？ 普通业务用户连接虚拟库会被拒。把运维账号加入 admin_users（只读观测可入 stats_users，其只能执行 SHOW 类命令）。
Q2：PAUSE 卡住不返回？ PAUSE 要等所有事务结束。先看 SHOW POOLS 的 sv_active：有长事务就不返回。用 SHOW CLIENTS 定位 client，到后端 pg_stat_activity 确认长事务；紧急情况 KILL appdb 兜底（记得 RESUME appdb 恢复）。
Q3：KILL_CLIENT 报 ERROR: invalid client id？ id 来自 SHOW CLIENTS 的 id 列，连接断开后 id 失效即报此错——重新执行 SHOW CLIENTS 取最新 id。
Q4：执行 SUSPEND 报 ERROR: invalid command 'SUSPEND'？ 1.26.0 已移除 SUSPEND（连同 SHOW FDS 与 -R takeover），见 5.5 对照表；滚动发布改用 so_reuseport 多实例方案。
Q5：SHOW DNS_ARGS 报 ERROR: invalid command？ HELP 文本包含 DNS_ARGS 但 1.26.1 实测无法执行（见 5.2 实测发现），DNS 观测用 SHOW DNS_HOSTS 与 SHOW DNS_ZONES。
Q6：RELOAD 后 SHOW CONFIG 的 value 没变？ 确认三件事：改的是否为对应段（[pgbouncer] 与 [databases] 均需 RELOAD）；RELOAD 是否执行成功（控制台回显 RELOAD）；参数 changeable 是否为 no（为 no 则需 restart，SHOW CONFIG 第三列为权威）。
Q7：SHOW STATS 的 avg 列全是 0？ 统计周期刚重置（RELOAD/重启）或周期内确无流量；等满一个 stats_period（默认 60 秒）再看，累计口径看 STATS_TOTALS 与 total_* 列。
九、参考链接
- 官方使用文档（管理控制台一节）：https://www.pgbouncer.org/usage.html
- 官方配置文档：https://www.pgbouncer.org/config.html
- 1.26.0 Release（SUSPEND/SHOW FDS 移除说明）：https://github.com/pgbouncer/pgbouncer/releases/tag/pgbouncer_1_26_0
- 1.26.1 Release：https://github.com/pgbouncer/pgbouncer/releases/tag/pgbouncer_1_26_1
- 本站延伸阅读：《PgBouncer 1.26.1 介绍与选型指南》、《Ubuntu 22.04 安装 PgBouncer 1.26.1 指南》、《PgBouncer 1.26.1 配置参数详解》、《PostgreSQL 18 常用 CLI 命令与工具详解》