// PostgreSQL 错误参考

PostgreSQL 08001:无法建立连接

客户端根本无法与服务器建立连接:主机和端口上没有服务在监听,或者存在防火墙、DNS 问题或超时。

SQLSTATE
08001
名称
sqlclient_unable_to_establish_sqlconnection
类别
连接异常
错误信息
connection to server at "db.example.com" (10.0.0.5), port 5432 failed: Connection refused
	Is the server running on that host and accepting TCP/IP connections?

它的意思

08001 是客户端 SQLSTATE:当驱动程序(如 PgJDBC 和 Npgsql)无法建立连接时会报告此状态,基于 libpq 的工具会打印类似上面的消息。服务器从未看到登录尝试,因此问题出在网络路径或服务器未监听,而不是凭证。

末尾的操作系统错误会说明是哪一种: Connection refused 表示主机有响应,但该端口上没有服务监听; timeout expired 或者 Operation timed out 通常表示防火墙丢弃了数据包; could not translate host name 是 DNS 问题。

常见原因

  • PostgreSQL 服务器未运行,或监听在另一个端口上。
  • listen_addresses 是 localhost (默认值),因此服务器只接受本地连接。
  • 防火墙、安全组或 Docker 端口映射挡住了 5432 端口。
  • 主机名错误,或者客户端无法解析的主机名。
  • 连接到 localhost 从容器内部连接时,它指的是容器本身。

如何修复它

  1. 在服务器上,检查 PostgreSQL 是否正在运行以及它监听的地址和端口。

    SHOW listen_addresses;
    SHOW port;
  2. 允许网络连接:设置 listen_addresses = '*' (或服务器的地址)在 postgresql.conf 再重启,然后添加一个 pg_hba.conf 规则,供客户端使用。

  3. 从客户端测试网络路径,例如 pg_isready -h db.example.com -p 5432,并在防火墙或安全组中开放该端口。

  4. 在容器内,应连接数据库容器的服务名或宿主机的地址,而不是 localhost.

相关错误

代码和消息文本来自 PostgreSQL 文档,附录 A:PostgreSQL 错误代码。浏览完整的 PostgreSQL 错误列表 或者 搜索每个数据库错误.

// 错误更少,修复更快

在 SQLly 中使用 PostgreSQL

适用于 macOS、Windows 和 Linux 的原生 SQL 客户端,智能感知能理解你的数据库模式,高危语句有防护,错误信息清晰,支持 PostgreSQL 以及你使用的其他数据库。