PostgreSQL 连接错误排查
按 DNS、网络、TLS、认证、database 和连接数顺序诊断常见连接失败
连接失败发生在 SQL 执行之前时，客户端不一定能得到 SQLSTATE。保留完整错误文本、时间、客户端版本和目标 host/port，但不要记录密码。
固定诊断顺序
DNS 解析
→ TCP 路由/防火墙/监听端口
→ TLS 协商与证书身份
→ pg_hba.conf 匹配
→ 用户认证
→ database 与 CONNECT 权限
→ 连接数/池容量
→ 会话初始化参数跳过前一层直接重置密码或放宽权限，通常会掩盖真实问题。
高频错误
| 错误 | 含义 | 验证 |
|---|---|---|
could not translate host name | DNS/主机名无法解析 | getent hosts、nslookup，核对拼写和私网 DNS |
connection refused | 目标地址没有接受该端口 | 服务状态、listen_addresses、端口和容器映射 |
connection timed out | 网络路径或防火墙丢弃 | 从同一应用环境测试 TCP，不从个人电脑代替 |
no pg_hba.conf entry | 没有匹配来源/database/user/TLS 的 HBA 规则 | 查看服务端日志和规则顺序；修改后 reload |
password authentication failed | 凭据或认证方式不匹配，常见 SQLSTATE 28P01 | 确认目标实例和 user，安全轮换密码 |
database ... does not exist | 目标实例中没有该 database，SQLSTATE 3D000 | 连接 postgres 后查询 pg_database |
too many connections | 实例/角色/数据库连接上限耗尽，SQLSTATE 53300 | pg_stat_activity、连接池与保留管理连接 |
certificate verify failed | CA、主机名、有效期或证书链错误 | 检查 sslmode、URI host、CA 和平台轮换通知 |
客户端验证
psql --version
psql -X "postgresql://app_reader@db.example.com:5432/commerce?sslmode=verify-full"连接成功后立即运行：
\conninfo
SELECT current_database(), current_user,
inet_server_addr(), inet_server_port(),
current_setting('server_version');服务端最小检查
SELECT datname, datallowconn, datconnlimit
FROM pg_database
ORDER BY datname;
SELECT usename, application_name, client_addr, state, count(*)
FROM pg_stat_activity
GROUP BY usename, application_name, client_addr, state
ORDER BY count(*) DESC;需要操作系统权限时再检查监听 socket、防火墙和 PostgreSQL 日志。云数据库没有主机权限，应使用平台连接诊断、网络流日志和审计日志。
不要用 trust 验证密码问题
把 pg_hba.conf 改为 trust 会移除认证边界，并且不能证明原密码为何失败。应在受控渠道轮换凭据，核对匹配到的 HBA 规则和服务端日志。
成功连接的安全配置见 psql 与 SSL；SQL 执行错误见 SQLSTATE 速查。
Last updated on