// 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 客戶端,具備結構描述感知的 IntelliSense、高風險陳述式防護與清楚的錯誤訊息,適用於 PostgreSQL 和你使用的其他資料庫。