# 01000 — warning（警告）

> PostgreSQL 使用 SQLSTATE 01000 表示通用警告（warning）条件。应先区分目录分类与实际 WARNING 或 NOTICE 严重级别，再按产生该消息的子系统诊断。
---

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

`01000` 是类别 01 `Warning` 中的通用警告（`warning`）条件。它只是目录分类，不对应某一个固定子系统或固定报文。PostgreSQL 源码目录明确说明，不应把这个类别用于失败条件。

这个五字符代码必须和协议严重级别及完整诊断一起读取。在 `ErrorResponse` 或 `NoticeResponse` 中，`S` 是可能经过本地化的严重级别，`V` 是未本地化的严重级别。因此，当产生消息的代码显式提供了该代码时，SQLSTATE 仍可以是 `01000`，而消息严重级别可能是 `WARNING`、`NOTICE`、`INFO` 或其他提示级别。

在常见的默认路径中，PostgreSQL 将 `ereport(WARNING, ...)` 映射为 `01000`，将不低于 `ERROR` 的级别映射为 `XX000`，将更低的级别映射为 `00000`。显式的 `errcode()` 可以覆盖这个默认值。因此，目录中的 `W` 标记有参考价值，但单凭它不能证明线上协议消息一定是实际的 `WARNING`。

代表性案例 `generic_warning_boundary` 在 PostgreSQL 18.6 和 10.21 上均通过。它用 PL/pgSQL `RAISE WARNING` 核验默认的 `01000` 分发，实际收到 `WARNING` 提示，并保持自动提交连接可继续使用。它没有实测异步 `NOTIFY`、hstore、XID 或 MultiXact 警告路径。

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `01000` |
| 条件名 | `warning` |
| 状态 | `有效` |
| 已知存在于 | `7.4` |
| 锁定快照 | `9.0.23, 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_WARNING` |
| 别名 | `—` |

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

锁定目录在 PostgreSQL 7.4 的 pre-9.0 正式源码中已经观察到该代码，并确认它存在于 9.0.23 至 18.6 的每个正式快照及 19 Beta 3 预览快照。pre-9.0 源码扫描覆盖 7.4 至 8.4.22；7.0 至 7.3 仍有候选源码缺口。因此，7.4 是已知存在边界，不是精确引入版本。

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

锁定的 18.6 定义是在类别 01 下的 `01000 W ERRCODE_WARNING warning`。默认严重级别映射位于 `elog.c`：`ERROR` 或更高级别从 `ERRCODE_INTERNAL_ERROR` 开始，`WARNING` 级别从 `ERRCODE_WARNING` 开始，更低级别从 `ERRCODE_SUCCESSFUL_COMPLETION` 开始。随后构造错误消息时还可以替换这个初始代码。

若干真实路径会使用通用警告（`warning`）代码：

- 异步通知队列会报告 `NOTIFY queue is %.0f%% full`。如果找到最老的监听事务，还会附带指出 PID 的详细信息，并提示结束该事务。这是队列压力警告，不是数组、权限或约束失败。
- 事务 ID 和 MultiXact 回卷保护会报告某个数据库必须在剩余多少事务或 MultiXact ID 用完前执行 `VACUUM`。提示会指向全库 `VACUUM`，以及旧预备事务或陈旧复制槽。
- SPI 清理路径会显式提供 `ERRCODE_WARNING`，报告非空 SPI 栈，并提示检查遗漏的 `SPI_finish`。这里的代码是显式指定的，即使严重级别同样是 `WARNING`。

这些源码确认的例子说明，报文、详细信息、提示、源码上下文和操作比单独的 `01000` 更有行动价值。其他类别 01 条件（如 `01003` 或 `0100C`）拥有自己的 SQLSTATE，不应全部折叠成这个通用代码。

## 报文与诊断 {#messages}

可执行的代表性案例是注册表中的 `generic_warning_boundary`：

<!-- BEGIN SQLSTATE SNIPPET: generic_warning_boundary -->
```sql
DO $$ BEGIN RAISE WARNING 'calibration warning'; END $$;
SELECT 1;
```
<!-- END SQLSTATE SNIPPET -->

PostgreSQL 18.6 和 10.21 都通过提示通道送出这条警告，得到 `SQLSTATE 01000`、严重级别 `WARNING` 和主报文 `calibration warning`。后续的 `SELECT 1` 成功，连接状态为 `IDLE`。这是实际的 `RAISE WARNING` 分发核验，不是上面分别列出的 `NOTIFY` 队列、hstore 兼容、事务 ID 或 MultiXact 路径的运行时证据。

## 诊断 {#diagnosis}

从驱动或协议中记录 `C`/`sqlstate`、`S`、`V`、`M`、`D`、`H`，并同时记录语句、数据库、后端 PID 和时间戳。带有提示处理器的客户端还应记录提示，而不只是异常：`WARNING` 级别的 `NoticeResponse` 可以在不抛出语句异常的情况下送达。若有 `V`，请保留本地化严重级别与未本地化值。

当客户端或服务器日志中看不到消息时，检查 `SHOW client_min_messages` 和 `SHOW log_min_messages`。这些设置控制送达与记录阈值，不会改变根因。对于重复出现的警告（`warning`），使用 SQLSTATE 和稳定的报文模板搜索日志，再检查对应子系统：

- `NOTIFY queue ... full` 应检查长期存活的监听事务及 `DETAIL` 中的 PID。
- XID 或 MultiXact 回收警告应在回卷保护变成真实失败之前检查事务年龄、预备事务和复制槽。
- 非空 SPI 栈应指向扩展或服务器端 SPI 生命周期管理。

不能仅凭 `01000` 推断事务已经中止、连接已经损坏或数据已经损坏。代表性警告让会话保持可用，但后续语句可能因独立原因失败，函数或客户端操作也可能施加自己的控制流。

## 处理 {#response}

以报文中的子系统和提示作为修复目标。结束或修复占住通知队列或旧事务回收边界的事务；检查复制槽和预备事务后执行提示的全库维护；或者修复扩展的 SPI 所有权。调查时保留原始诊断。

实际的 `WARNING` 或更低级别提示本身不会把显式事务置为中止，通常也会让连接保持可继续使用。应验证下一条命令及事务状态，不要从代码本身猜测结果。如果随后出现 `ERROR`，请按照那个错误的 SQLSTATE 处理，并根据其事务契约使用 `ROLLBACK` 或合适的保存点恢复。

提高 `client_min_messages` 或 `log_min_messages` 可以减少噪声，但不会修复队列、事务回收边界或 SPI 生命周期。只有理解了底层信号后才应考虑抑制它。

## 版本 {#versions}

目录记录 `01000` 存在于锁定的 7.4–8.4.22 pre-9.0 正式源码，以及 9.0.23 至 18.6 的所有正式目录快照和 19 Beta 3 预览快照。同 tag 的 `REL8_1_4` `errcodes.sgml` 表已经用较早的 `1000` 写法列出条件名 `warning`，因此至少可以确认 8.1.4 已有该条件名。7.0–7.3 仍有候选源码缺口，因此 7.4 观察结果只是存在边界，不是精确引入版本。18.6 源码快照固定在 commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`。

协议严重级别字段以及 `client_min_messages`/`log_min_messages` 控制项以 PostgreSQL 18 文档为依据。上面的代表性源码路径是 18.6 观察结果，不表示每个旧版本中的所有报文模板都完全不变。

## 相关 {#related}

[`00000` — `successful_completion`](../00000/) 是低级别完成消息的默认代码。[`01003` — `null_value_eliminated_in_set_function`](../01003/) 和 [`0100C` — `dynamic_result_sets_returned`](../0100c/) 是更具体的类别 01 条件。[`XX000` — `internal_error`](../xx000/) 是没有显式代码的 `ERROR` 的默认代码，不能与 warning 混用。[`25P02` — `in_failed_sql_transaction`](../25p02/) 描述的是前一个错误已经中止事务后拒绝后续命令，不能把它当成每个 `01000` 消息的后果。

## 来源 {#sources}

本页的结构化证据记录在[公开证据 JSON](../../data/evidence/01000.json)中。源码和文档记录均使用固定 PostgreSQL commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`；运行记录保留通过的提示注册表和精确 run ID。

- `src.errcodes.18.6` — [`errcodes.txt`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L81-L84)
- `src.elog.18.6` — [`elog.c`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/error/elog.c#L442-L454)
- `src.async.18.6` — [`async.c`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/commands/async.c#L1518-L1559)
- `src.varsup.18.6` 与 `src.multixact.18.6` — 事务回收边界警告路径
- `src.spi.18.6` — SPI 清理路径中的显式警告代码
- `doc.protocol.18` 与 `doc.logging.18` — [Error and Notice Message Fields](https://www.postgresql.org/docs/18/protocol-error-fields.html) 与 [When to Log](https://www.postgresql.org/docs/18/runtime-config-logging.html)