08001 sqlclient_unable_to_establish_sqlconnection

速览

SQLSTATE 08001 是 Class 08 中的 sqlclient_unable_to_establish_sqlconnection。08001 是服务器端无法建立客户端连接时使用的 SQLSTATE。选定的 dblink_connect 路径 ERROR 主报文为 could not establish connection，拒绝端口原因放在动态 DETAIL 中；这与 dblink 句柄不存在的 08003，以及启动阶段的 28000、28P01、3D000 不同。

含义

服务器端 dblink_connect 路径在 libpq 无法打开目标远端端点时发出此码。固定诊断为 ERROR，主报文是 could not establish connection，端点和操作系统原因放在动态 DETAIL 中。它描述的是建立命名远端句柄，与句柄不存在的 08003，以及会话尚未建立就被拒绝的 28000 或 3D000 不同。

源码并不自行格式化 DETAIL：dblink.c 通过 errdetail_internal("%s", msg) 传递 libpq 已经组装好的错误字符串。因此，下面选定运行中的 18.6 拒绝端口文本（含主机、端口和 Connection refused）以及 10.21 的 libpq 文本都只是运行观察，不是 PostgreSQL 固定的 08001 模板。

诊断

记录目标主机、端口、认证参数和完整 DETAIL。选定的 18.6/10.21 运行中，拒绝连接后本地自动提交会话保持 IDLE；随后用真实 dblink 句柄连到运行器实例，执行远端 SELECT 1，再显式断开。它证明本地恢复和句柄清理，不证明任何远端业务事务已经完成。

先判断失败阶段再重试。TCP 拒绝、DNS/TLS 失败和认证拒绝都可能由 libpq 通过这个 dblink 路径返回，必须查看动态 DETAIL，不能只按代码分类。若调用位于显式本地事务中，ERROR 可能使事务在 ROLLBACK（或 ROLLBACK TO SAVEPOINT）前不可继续；选定案例中的自动提交 IDLE 不能推广到显式事务。dblink 句柄属于创建它的后端，应在同一会话或同一个连接池成员中检查和修复。

处理

修正端点或连接参数，建立新句柄并先验证无副作用的远端探针，再发送业务操作。若失败请求可能已经越过远端边界，重试前先对账；单凭 08001 不能重放非幂等操作。

自动提交时，修正端点后可以把建连当作新的语句重试，所有者会话仍可能可用。显式事务中应先恢复本地事务，再建立并探测新句柄；只有周围工作明确设计为可继续时，保存点才适合使用。若远端操作可能已经到达目标而本地只收到错误，重放前先核对结果。

实测诊断

固定的 dblink_connect 路径以 ERROR 发出主报文 could not establish connection，并通过 errdetail_internal("%s", msg) 传递动态 libpq 字符串。选定的 18.6 运行中该值为 connection to server at "127.0.0.1", port 1 failed: Connection refused 及 libpq 的后续提示；10.21 运行中则以 could not connect to server: Connection refused 开头。这些是运行特定值，不是固定 SQLSTATE 模板。其他 producer 可能使用不同文本；只有客户端异常而没有服务器诊断，不能据此认定此 SQLSTATE。

这个 dblink 路径的严重级别固定为 ERROR。选定本地会话使用自动提交，所以错误后仍为 IDLE；不要把这个状态推广到外层显式事务，或推广到未能确认结果的远端事务。

代表案例

此 SQL 块创建 dblink，尝试连接运行器本地的拒绝端口，然后探测所有者会话。触发点是服务器端 dblink 建连，不会在远端事务中执行工作。

runner_host、runner_port、runner_db 和 runner_user 是运行器占位参数，手工复制时不能照字面使用。应替换为可访问的目标和有权连接它的登录角色；安装/使用 dblink 以及远端登录都需要相应权限。若要复现选定的恢复观察，应在同一个所有者后端中按案例的自动提交边界执行这些语句。

CREATE EXTENSION IF NOT EXISTS dblink;
SELECT dblink_connect('missing_remote', 'host=127.0.0.1 port=1 dbname=postgres connect_timeout=1');
SELECT dblink_connect('working_remote', 'host=runner_host port=runner_port dbname=runner_db user=runner_user connect_timeout=5');
SELECT * FROM dblink('working_remote', 'SELECT 1') AS result(value integer);
SELECT dblink_disconnect('working_remote');
SELECT 1;

18.6 运行记录 SQLSTATE 为 08001，主报文 could not establish connection；错误后所有者会话为 IDLE。修复打开句柄返回 OK，远端返回 1，断开返回 OK；最终探针返回 1，状态 IDLE。10.21 也通过同样断言。

可下载的案例与证据投影分别是 08001 案例 JSON 和 作者证据。运行器清单为 verify/cases/08001/cases.json；发布前会将页面 SQL 与共享注册表比对。

版本

上面的生成事实表记录锁定的目录快照和最早观察到的定义。本页自然运行范围是 PostgreSQL 18.6 与 10.21，不能据此推断所有中间版本的行为。

相关

• 08000 — connection_exception
• 08003 — connection_does_not_exist
• 28000 — invalid_authorization_specification
• 3D000 — invalid_catalog_name

来源

• 上游源码 doc/src/sgml/xact.sgml PG18-docs 724edf9bd b48fbe8b
• 上游源码 contrib/dblink/dblink.c 第 299–302 行 REL_10_23 02991e79f 2d542cc7
• 上游源码 contrib/dblink/dblink.c 第 335–338 行 REL_18_6 724edf9bd e4cfaec3
• 上游源码 src/backend/utils/errcodes.txt REL_18_6 724edf9bd 6e8de346
• 核验材料 verify/cases/08001/cases.json workspace d1310bef
• 核验材料 verify/cases/08001/snippets.json workspace 8227f1b7
• 核验材料 raw/calls/REL_10_23.jsonl REL_10_23 00d16d3e
• 核验材料 raw/calls/REL_18_6.jsonl REL_18_6 9ee8a0e8