百科 / 错误代码 / Class 23 完整性约束冲突
23502 not_null_violation
非空约束冲突
ERROR 已实测 详解 实测通过
- 条件名
not_null_violation- 宏名称
ERRCODE_NOT_NULL_VIOLATION- 启用版本
- 7.4
- 状态
- 活跃
版本覆盖
速览
23502 表示 NULL 到达了 NOT NULL 规则。本案例识别出列 label 和关系 items；18.6 与 10.21 的英文主报文关系措辞略有差异，但 SQLSTATE 和结构化对象一致。
含义
执行器检查元组的 NOT NULL 属性并带出列、关系及可选的失败行 DETAIL。模式校验和域的 NOT NULL 校验也会使用该码，但源码模板不同；域 CHECK 失败属于 23514 路径。默认值、显式值、生成表达式或模式变更的选择取决于 NULL 的来源。
诊断
保存 column_name、table_name 和 DETAIL。选定案例中，18.6 主报文包含 of relation "items"，10.21 则省略该短语；应使用结构化字段，不要匹配完整英文报文。沿参数、类型转换、生成列、触发器和 INSERT ... SELECT 追踪值。自动提交案例错误后仍为 IDLE；外层显式事务需要回滚或处理器。
处理
填入合法值、明确采用默认值，或在检查既有数据和下游读取方后调整约束。不要为了掩盖缺失值而删除 NOT NULL，或把它换成更弱的 CHECK；NULL 能否出现必须是有意的数据契约。新增 NOT NULL 的迁移要先校验既有数据，保持模式变更事务边界显式。
可复现案例
在一次性实例上执行过的场景。其中 1 个附有可执行 SQL，正文相应小节里给出。
not_null_insert PG 10 / 18 有 SQL
前置条件
- The target column is declared NOT NULL
- The insert supplies a NULL value
触发
Insert a row with NULL in the NOT NULL column.
断言
- SQLSTATE is 23502
- The column and relation are identified
- A valid row can be inserted after the error
处置
Provide a valid value or change the schema only after confirming the data contract; do not silently coerce a missing value without business meaning.
清理
Drop the case schema with an owner connection.
实测诊断
18.6 (Homebrew) / latest：SQLSTATE 23502；primary null value in column "label" of relation "items" violates not-null constraint；DETAIL Failing row contains (2, null).；status_after_error IDLE。
10.21 (Debian 10.21-1.pgdg90+1) / pg10：SQLSTATE 23502；primary null value in column "label" violates not-null constraint；DETAIL Failing row contains (2, null).；status_after_error IDLE。
报文模板
源码里的格式串，不是某一次运行的输出。%s 之类是占位符，实际报文会填入对象名与取值。适用范围一栏是核验时留下的原始英文记录，未经翻译。
null value in column "%s" of relation "%s" violates not-null constraint
Failing row contains %s.
来源：src/backend/executor/execMain.c @ REL_18_6
适用范围：The %s substitutions are the column, relation, and optional row description.
column "%s" of relation "%s" contains null values
来源：src/backend/commands/tablecmds.c @ REL_18_6
适用范围：This validation template reports existing rows while a relation schema is being validated.
column "%s" of table "%s" contains null values
来源：src/backend/commands/typecmds.c @ REL_18_6
适用范围：This template is used while validating a domain NOT NULL rule against columns that use the domain.
代表案例
运行器从 verify/cases/23502/snippets.json（SHA-256 f701e32a0e9214d6c88deabcda99981c288cae0f176d1dcaf383863c3942f8e0）读取下列片段，并为临时 schema 替换表名；完整 setup、断言与清理见 案例导出。
-- create
CREATE TABLE items(id integer PRIMARY KEY, label text NOT NULL);
-- seed
INSERT INTO items VALUES (1, 'seed');
-- trigger
INSERT INTO items VALUES (2, NULL);
-- repair
INSERT INTO items VALUES (2, 'valid');
-- verify
SELECT id, label FROM items ORDER BY id;
本案例对应的 SQLSTATE、诊断、事务状态和修复断言均来自上述共享 registry；结构化证据 · 案例导出。
作者证据 ID：identity, dml-path, schema-path, runtime。选定运行记录：runtime.23502-batch1-latest-20260909.latest, runtime.23502-batch1-pg10-20260909.pg10。
版本与边界
锁定目录在 7.4 已观察到该条件，并在列出的正式快照中均存在。选定运行只覆盖 18.6 与 10.21 的普通 INSERT，不覆盖 ALTER TABLE 校验、域、分区或触发器生成 NULL。
来源
- 上游源码 doc/src/sgml/ddl.sgml
- 上游源码 src/backend/utils/errcodes.txt
- 上游源码 src/backend/executor/execMain.c 第 2213–2219 行
- 上游源码 src/backend/commands/tablecmds.c 第 6465–6490 行
- 上游源码 src/backend/commands/typecmds.c 第 3199–3204 行
- 核验材料 raw/calls/REL_18_6.jsonl
证据
断言
每条断言都写明了是怎么核实的，以及它不覆盖什么。这一层是核验时留下的原始英文记录，照原样呈现，未经翻译。
-
23502 is not_null_violation in Class 23.
-
The executor reports 23502 when a tuple has a NULL value for a NOT NULL column, with column/relation fields and an optional failing-row DETAIL.
-
ALTER TABLE validation and domain NOT NULL validation use separate 23502 source templates; domain CHECK validation is a 23514 path.
-
The selected insert case returned 23502 on PG18.6 and PG10.21, identified label/items, stayed IDLE in autocommit mode, and then inserted a valid row.
运行记录
| 目标 | 服务器版本 | 结果 | 覆盖案例 |
|---|---|---|---|
| latest | 18.6 (Homebrew) | passed | not_null_insert |
| pg10 | 10.21 (Debian 10.21-1.pgdg90+1) | passed | not_null_insert |
同类错误代码
Class 23 完整性约束冲突 下的其他成员。