HV000 — fdw_error（外部数据包装器错误）

速览 {#at-a-glance}

HV000 是 SQL/MED 外部数据包装器（FDW）的通用错误条件，只说明错误位于 FDW 边界，不对应某一种远端故障、回调或重试策略。PostgreSQL 18.6 核心/contrib 扫描没有解析出直接的 ERRCODE_FDW_ERROR 报告组，具体触发方式取决于安装的实现。

包装器回调可以报告自己的 SQLSTATE，访问另一系统的包装器也可能转发远端诊断。解释 HV000 前，应保留完整诊断、外部表、外部服务器、包装器名称与版本以及操作阶段。

含义与范围 {#meaning}

18.6 定义为 SQL/MED 专用 Class HV 中的 HV000 E ERRCODE_FDW_ERROR fdw_error。FDW API 提供规划、扫描、修改、导入和解释回调；执行器通过安装的包装器提供的 FDW routine 调用这些回调。条件集中定义而具体实现位于扩展，正是这个边界的结果。

postgres_fdw、file_fdw 和第三方 FDW 实现 FDW 回调 API。dblink 是独立的 contrib 客户端 API，访问另一 PostgreSQL 服务器时也可能使用 Class HV 代码，但它不是 FDW 回调实现。远端 SQLSTATE、libpq 连接错误和包装器本地错误可能出现在一次操作中，但不能互相替代。

报文与诊断 {#messages}

归档的 18.6 调用扫描没有解析出 HV000 的稳定核心报文变体。尽可能保留 C/SQLSTATE、S、V、M、D、H、W、F、L、R，以及包装器回调或远端命令；不能用“FDW error”概括实际报文。

诊断 {#diagnosis}

先确定阶段：规划、扫描初始化、取数、增删改、提交/回滚、模式导入或 EXPLAIN。再检查外部表和服务器选项、用户映射、包装器版本及远端日志。若是远端 PostgreSQL 包装器，要分别记录远端和本地 SQLSTATE；它们描述的是同一故障的不同层。

本次扫描覆盖 PostgreSQL 18.6 核心及自带 contrib 源码，不覆盖所有外部包装器、驱动、远端数据库或用户回调。

处理 {#response}

根据已确认的层次修复外部服务器或用户映射、包装器选项/回调契约、远端操作，或安装兼容的包装器版本。只有确认包装器是否已访问远端以及写操作是否可能提交后才重试；单独的 HV000 不能证明这两点。

版本 {#versions}

锁定目录在 9.1.0 已观察到 HV000，并存在于截至 18.6 的正式快照及 19 Beta 3 预览快照。pre-9 扫描的 7.4–8.4 定义文件未观察到它，这只是资料边界，不是精确引入版本。

相关 {#related}

比较 HV001 — fdw_out_of_memory、HV002 — fdw_dynamic_parameter_value_needed 和 HV00B — fdw_invalid_handle。远端条件应按远端系统的 SQLSTATE 和诊断解释。

来源 {#sources}

• errcodes.txt — 18.6 固定定义，SHA-256 6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba。
• fdwapi.h — 回调边界。
• nodeForeignscan.c — 执行器回调分发。
• 结构化证据 — 固定来源和有界调用扫描结果。

来源

• 上游源码 src/backend/utils/errcodes.txt REL_18_6 724edf9bd 6e8de346
• 上游源码 src/include/foreign/fdwapi.h REL_18_6 724edf9bd 572ba892
• 上游源码 src/backend/executor/nodeForeignscan.c REL_18_6 724edf9bd 37b85b68
• 核验材料 raw/calls/REL_18_6.jsonl 9ee8a0e8