PostgreSQL / 系统课时
排查数据库连接失败
排查数据库连接失败
数据库连接失败时,最容易犯的错是直接改密码或防火墙。本课按“服务进程→监听端口→网络→pg_hba.conf→认证参数”的顺序收集证据,让你能从错误现象快速定位失败层,并在修复后用同一连接参数完成验证。
学习目标
- 根据典型错误判断连接失败发生在哪一层
- 检查 PostgreSQL 服务、监听地址、端口和认证规则
- 用可重复的命令验证网络、认证和数据库可达性
先判断连接在哪一层失败
一次 PostgreSQL 连接会依次经过客户端参数、TCP 网络、服务端监听、pg_hba.conf 规则和身份认证。只有前一层通过,后一层才有机会执行,因此排查时应从最外层证据逐步向内收敛,而不是同时修改多个配置。

常见报错可以先做第一轮归类:connection refused 通常表示目标地址上没有进程监听或端口写错;超时更像路由、防火墙或安全组问题;no pg_hba.conf entry 已经到达服务端,但没有匹配的认证规则;password authentication failed 则说明网络和监听基本已经通过,问题进入认证阶段。
从服务状态和监听端口开始
如果主机由 systemd 管理 PostgreSQL,可先在数据库服务器上执行以下命令。发行版可能使用带版本或集群名的服务单元,实际单元名以本机为准。
systemctl is-active postgresql
ss -ltnp | grep ':5432'
pg_isready -h 127.0.0.1 -p 5432 -d postgres预期输出
active
LISTEN 0 244 127.0.0.1:5432 0.0.0.0:* users:(("postgres",pid=<PID>,fd=<ID>))
127.0.0.1:5432 - accepting connections<PID>、<ID> 以及监听地址会随环境变化。如果服务是 active,但 ss 只显示 127.0.0.1:5432,远程客户端就无法通过服务器外网或内网 IP 连接;此时应继续检查 listen_addresses,而不是先改用户密码。
能本机登录时,可以直接从数据库读取生效配置和文件路径,避免修改了错误的配置文件。
SELECT current_setting('listen_addresses') AS listen_addresses,
current_setting('port') AS port,
current_setting('hba_file') AS hba_file;预期输出
listen_addresses | port | hba_file
------------------+------+----------------------
localhost | 5432 | <PATH>/pg_hba.conf
(1 row)修改 listen_addresses 或 port 后需要重启 PostgreSQL 才会生效;单独修改 pg_hba.conf 通常只需重新加载配置。
检查 pg_hba.conf 是否命中正确规则
pg_hba.conf 按文件顺序匹配,命中第一条符合连接类型、数据库、用户和来源地址的规则后就停止继续查找。能以管理员身份连接时,优先查看数据库解析后的规则,而不是只凭肉眼检查文本文件。
SELECT line_number, type, database, user_name, address, auth_method, error
FROM pg_hba_file_rules
ORDER BY line_number;
SELECT pg_reload_conf();预期输出
line_number | type | database | user_name | address | auth_method | error
-------------+------+----------+-------------+--------------+----------------+-------
<ID> | host | {appdb} | {app_user} | 10.0.0.0/24 | scram-sha-256 |
(1 row)
pg_reload_conf
----------------
t
(1 row)error 非空表示某条规则无法被正常解析。还要确认客户端真实来源 IP 落在 address 范围内,并检查是否有更靠前的拒绝规则先被命中。若报错明确指出某个用户、数据库和来源地址没有 HBA 条目,就应针对这三个实际值配置规则。
用原始连接参数做端到端验证
服务端检查通过后,回到出错客户端,用与应用相同的主机、端口、数据库和用户验证。不要把密码直接写进 shell 历史,交互验证可用 -W,自动化环境则应使用受保护的密钥注入方式或 .pgpass。
psql "host=db.example.internal port=5432 dbname=appdb user=app_user connect_timeout=5" -W -Atqc "SELECT 1"预期输出
Password:
1如果这里仍然超时,优先检查客户端到服务器 <PORT> 的路由、防火墙和云安全规则;如果返回认证错误,则保留网络配置不动,转而核对用户、密码和 HBA 认证方式。修复后应重复同一条端到端命令,只有应用使用的完整连接参数能稳定返回 1,连接故障才算真正闭环。