debug_connection是PostgreSQL 12+的postmaster级调试参数，用于对指定IP或CIDR客户端连接输出底层协议、SSL、HBA等stderr级调试日志，需在postgresql.conf中配置并重启生效。
debug_connection 是 PostgreSQL 提供的一个服务端配置参数，用于对匹配特定 IP 地址或 CIDR 网段的客户端连接，启用额外的底层调试日志（如协议交互、状态机切换、SSL 握手细节等），而非普通 log_statement 或 log_min_messages 所覆盖的 SQL 级日志。
它不输出到 pg_log 默认日志文件，而是直接打印到服务器标准错误（stderr），因此需配合 PostgreSQL 启动方式（如 pg_ctl -l 指定日志文件，或 systemd 的 StandardError=journal）才能捕获。
确认版本与可用性
仅 PostgreSQL 12 及以上版本支持。低于 12 的版本无此参数。运行以下命令验证：
SELECT version();
若返回类似 PostgreSQL 14.5 (Ubuntu 14.5-1.pgdg22.04+1)，即可继续；否则需升级或改用其他调试手段（如 `tcpdump` + `pg_recvlogical` 分析）。
配置 debug_connection 参数
该参数是 postmaster 级别参数，必须在 `postgresql.conf` 中设置，并重启数据库生效（无法 `SET` 会话级修改）：
- 编辑
postgresql.conf，添加或修改一行：
debug_connection = '192.168.1.100'
- 支持单个 IPv4/IPv6 地址，也支持 CIDR 表示法，例如：
debug_connection = '10.0.0.0/8'
- 允许多个值，用逗号分隔（注意：无空格）：
debug_connection = '192.168.1.100,2001:db8::1'
- 该参数对大小写不敏感，但地址格式必须合法；非法值会导致启动失败。
确保日志能被收集和查看
由于 `debug_connection` 输出到 stderr，需确保 PostgreSQL 的 stderr 有落盘路径：
- 使用
pg_ctl start -l logfile启动时，日志会写入指定logfile； - 若通过 systemd 管理（如 Ubuntu/Debian 的
postgresql@14-main），检查/etc/systemd/system/multi-user.target.wants/postgresql@14-main.service是否设置了StandardError=journal，然后用：journalctl -u postgresql@14-main -f - 临时测试可直接前台启动：
pg_ctl -D /var/lib/postgresql/14/main/ -l /tmp/pg_debug.log start
之后用 tail -f /tmp/pg_debug.log 实时观察匹配连接的日志输出。
触发并识别调试日志
当匹配 IP 的客户端建立连接（含连接池如 pgbouncer 的直连模式）时，日志中会出现形如以下的高密度调试行：
DEBUG: connection received: host=192.168.1.100 port=54322 DEBUG: SSL negotiation failed: error code 0 DEBUG: FE message type 0x71 length 9 DEBUG: processing startup packet DEBUG: pg_hba.conf rejects connection
这些日志包含：
- 连接建立/断开的精确时间点与 socket 信息
- 前端（FE）/后端（BE）协议消息原始类型与长度
- SSL 握手各阶段状态
- HBA 规则匹配过程（如哪条规则被选中或拒绝）
⚠️ 注意：日志量极大，仅用于短时排障；生产环境切勿长期开启，尤其面对高频连接场景。
