# HV001 — fdw_out_of_memory（外部数据包装器内存不足）

> PostgreSQL SQLSTATE HV001 表示 FDW 路径的内存分配失败。PostgreSQL 自带的 dblink 和 postgres_fdw 在获取 libpq 连接选项时会使用它。
---

# HV001 — fdw_out_of_memory（外部数据包装器内存不足）

## 速览 {#at-a-glance}

`HV001` 是 FDW 内存不足条件。PostgreSQL 18.6 的 `postgres_fdw` 和 `dblink` 在 `PQconndefaults()` 没有返回选项数组时使用它，`postgres_fdw` 复制选项的分配失败路径也使用它。固定源码报文是 `out of memory`，有些路径附带 `Could not get libpq's default connection options.`。它是 `ERROR`，远端操作是否已执行取决于阶段。

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `HV001` |
| 条件名 | `fdw_out_of_memory` |
| 状态 | `有效` |
| 已知存在于 | `9.1.0` |
| 锁定快照 | `9.1.24, 9.2.24, 9.3.25, 9.4.26, 9.5.25, 9.6.24, 10.23, 11.22, 12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| 宏 | `ERRCODE_FDW_OUT_OF_MEMORY` |
| 别名 | `—` |

<!-- source facts: data/errcodes/HV001.json -->
<!-- END SQLSTATE FACTS -->

## 含义与触发路径 {#meaning}

`postgres_fdw` 在构建选项列表时调用 `PQconndefaults()`；空结果被视为分配失败并报告 `HV001`。随后为复制选项分配内存失败时也使用该码。dblink 有两个对应的选项发现路径。这是包装器实现细节，不能把所有 `HV001` 都解释为后端全局耗尽内存。

## 报文与诊断 {#messages}

18.6 的已确认变体包括：dblink `1972–1974` 和 `2908–2910`、`postgres_fdw/option.c:317–319` 的 `ERROR: out of memory` 加 detail；`option.c:340–341` 只有主报文。应同时保留函数阶段和包装器名称；该报文不是远端服务器响应。

## 诊断 {#diagnosis}

记录所有诊断字段，确认是在读取 FDW/服务器选项还是建立 dblink/postgres_fdw 连接时失败。检查后端内存压力、进程限制、包装器与 libpq 版本；detail 指向 libpq 默认选项时，先区分 `PQconndefaults()` 分配失败与 libpq 安装或配置问题，再把本地库路径/版本作为辅助证据，最后排查远端 SQL。

## 处理 {#response}

降低并发内存压力并检查后端进程或容器限制，理解分配失败后再重试选项发现。若服务器实际报告的是 `53200`，应按该代码的诊断处理；若已确认是 `HV001`，不能仅因发生分配失败就改标为 `53200`。写操作要结合回调阶段和远端日志确认是否已发命令；单独的 `HV001` 不是整事务重试信号。

## 版本 {#versions}

目录从 9.1.0 观察到该码，并延续到 18.6 与 19 Beta 3。上述 18.6 路径和大小写固定到 commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`；旧版本措辞可能不同。

## 相关 {#related}

[`HV000`](../hv000/) 是通用 FDW 条件；[`HV002`](../hv002/) 是缺少包装器参数；[`53200`](../53200/) 是后端通用内存不足，只有确认后端而非 FDW 报错时才使用它。

## 来源 {#sources}

- [`errcodes.txt`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L477) — 定义，SHA-256 `6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba`。
- [`postgres_fdw/option.c`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/postgres_fdw/option.c#L313-L341) 与 [`dblink.c`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/dblink/dblink.c#L1968-L1974) — 选项路径。
- [结构化证据](../../data/evidence/hv001.json) — 报文变体与源码摘要。