08003 connection_does_not_exist

速览

SQLSTATE 08003 是 Class 08 中的 connection_does_not_exist。08003 表示当前 dblink 后端会话中不存在指定名称的连接句柄。它是句柄生命周期错误，不能证明远端服务器无法建立连接（08001）或已有 socket 失败（08006）。选定路径先断开 missing_remote，再证明可以打开、查询并断开真实句柄。

含义

此条件来自 dblink 句柄查找，发生在执行任何远端 SQL 之前：当前后端没有与请求相符的命名连接。主报文按 connection "%s" not available 组装，因此名称指向本地句柄生命周期，而不是远端可达性。句柄缺失与 08001 建连失败、以及已有连接丢失的 08006 是不同问题。

句柄查找只发生在一个 PostgreSQL 后端中。连接池可能让两个客户端使用相同的应用层连接名，但它们的 dblink 句柄表并不共享；在一个后端创建 working_remote，不能修复另一个后端的 missing_remote。固定路径没有 DETAIL 或 HINT，因此首先要保留被引用的句柄名和发起调用的会话。

诊断

检查准确的 dblink 名称以及拥有它的会话或连接池连接。主报文动态组装为 connection "missing_remote" not available；选定自动提交运行中的查找错误后仍为 IDLE，修复句柄返回远端 1，dblink_disconnect 返回 OK。

要把句柄查找失败和 socket 丢失分开。如果当前后端从未打开该名称，检查句柄创建路径和连接池分配；如果它曾打开而后续远端调用失败，则先收集该调用的诊断，再决定是否断开重建。在显式本地事务中，这个 dblink ERROR 遵循通常的事务中止边界，必须回滚或回到有意建立的保存点后才能执行无关语句。选定的 IDLE 是自动提交情形的结果。

处理

在实际使用句柄的同一会话中创建它，或明确将不存在的句柄断开定义为幂等操作。真实远端操作结束后先核对结果，再关闭或重建句柄；不要因为一个会话忘记 dblink 名称就重连整个连接池。

自动提交时，在同一个后端完成打开、探测和断开就是完整生命周期。显式事务中应先恢复本地事务，再在同一后端重建句柄；新句柄成功并不能证明之前的远端操作已经提交。应在连接池诊断中记录句柄名和所有权，避免重连后把工作悄悄移到另一个会话。

实测诊断

固定的句柄查找路径以 ERROR 发出主报文 connection "%s" not available；请求的句柄名称是动态值，没有固定 DETAIL 或 HINT。只有客户端异常而没有这条服务器诊断，不能据此认定 08003。

因此，选定的主报文 connection "missing_remote" not available 是具体的名称查找结果，不是远端可达性测试。固定的 ERROR 在显式事务中可能使事务进入 INERROR；选定所有者为自动提交，所以错误后仍是 IDLE。

代表案例

此 SQL 块要求 dblink 断开从未打开的句柄，然后探测同一会话。

runner_host、runner_port、runner_db 和 runner_user 是运行器占位参数。手工执行时应替换为所有者具有 dblink 和远端连接权限的目标与登录角色。句柄属于当前会话：缺失查找、打开/探测和断开必须在同一后端中执行；选定案例使用自动提交。

CREATE EXTENSION IF NOT EXISTS dblink;
SELECT dblink_disconnect('missing_remote');
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 为 08003，主报文 connection "missing_remote" not available；错误后所有者会话为 IDLE。修复打开句柄返回 OK，远端返回 1，断开返回 OK；最终探针返回 1，状态 IDLE。10.21 也通过同样断言。

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

版本

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

相关

• 08001 — sqlclient_unable_to_establish_sqlconnection
• 08006 — connection_failure

来源

• 上游源码 doc/src/sgml/xact.sgml PG18-docs 724edf9bd b48fbe8b
• 上游源码 contrib/dblink/dblink.c 第 171–173 行 REL_10_23 02991e79f 2d542cc7
• 上游源码 contrib/dblink/dblink.c 第 193–195 行 REL_18_6 724edf9bd e4cfaec3
• 上游源码 src/backend/utils/errcodes.txt REL_18_6 724edf9bd 6e8de346
• 核验材料 verify/cases/08003/cases.json workspace 8ea12e9b
• 核验材料 verify/cases/08003/snippets.json workspace a5f2c896
• 核验材料 raw/calls/REL_10_23.jsonl REL_10_23 00d16d3e
• 核验材料 raw/calls/REL_18_6.jsonl REL_18_6 9ee8a0e8