23502 not_null_violation

非空约束冲突

ERROR 已实测详解实测通过

类别: Class 23 完整性约束冲突
严重等级: 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

DETAIL 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 REL_18_6 724edf9bd ce1919d9
上游源码 src/backend/utils/errcodes.txt REL_18_6 724edf9bd 6e8de346
上游源码 src/backend/executor/execMain.c 第 2213–2219 行 REL_18_6 724edf9bd 33b97337
上游源码 src/backend/commands/tablecmds.c 第 6465–6490 行 REL_18_6 724edf9bd 422dc8e8
上游源码 src/backend/commands/typecmds.c 第 3199–3204 行 REL_18_6 724edf9bd 60d1e975
核验材料 raw/calls/REL_18_6.jsonl 9ee8a0e8

证据

断言

每条断言都写明了是怎么核实的，以及它不覆盖什么。这一层是核验时留下的原始英文记录，照原样呈现，未经翻译。

23502 is not_null_violation in Class 23.

核实方式Read the fixed errcodes row.

不覆盖The code says that a NOT NULL rule failed; it does not by itself distinguish DML from schema validation.

来源src/backend/utils/errcodes.txt
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.

核实方式Trace ReportNotNullViolationError and its errtablecol metadata.

不覆盖The DETAIL can be omitted or vary with row-description settings; use structured column/table diagnostics.

来源src/backend/executor/execMain.c · raw/calls/REL_18_6.jsonl
ALTER TABLE validation and domain NOT NULL validation use separate 23502 source templates; domain CHECK validation is a 23514 path.

核实方式Compare the tablecmds and executor report groups.

不覆盖A repair must satisfy the actual schema rule; adding a default or relaxing NOT NULL is a migration decision, not a generic retry.

来源src/backend/commands/tablecmds.c · raw/calls/REL_18_6.jsonl · src/backend/commands/typecmds.c
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.

核实方式Read the selected summaries and raw diagnostics.

不覆盖The case covers one INSERT path and not ALTER TABLE, domains, partitions, or trigger-generated NULLs.

运行记录

目标	服务器版本	结果	覆盖案例
latest	18.6 (Homebrew)	passed	not_null_insert
pg10	10.21 (Debian 10.21-1.pgdg90+1)	passed	not_null_insert

同类 SQL 状态码

状态码	条件名	宏名称	严重等级	版本
Class 23 完整性约束冲突 Integrity Constraint Violation 7 个 ↗
23000	integrity_constraint_violation	`ERRCODE_INTEGRITY_CONSTRAINT_VIOLATION`	ERROR	7.4
完整性约束冲突的类别码，应使用具体子码。				活跃
23001	restrict_violation	`ERRCODE_RESTRICT_VIOLATION`	ERROR	7.4
外键 RESTRICT 动作拒绝删除仍被引用的父行。				活跃
23502	not_null_violation	`ERRCODE_NOT_NULL_VIOLATION`	ERROR	7.4
向 NOT NULL 列写入了 NULL 值。				活跃
23503	foreign_key_violation	`ERRCODE_FOREIGN_KEY_VIOLATION`	ERROR	7.4
外键约束冲突，子行找不到匹配的父键。				活跃
23505	unique_violation	`ERRCODE_UNIQUE_VIOLATION`	ERROR	7.4
行或索引违反唯一约束，常见于重复键插入。				活跃
23514	check_violation	`ERRCODE_CHECK_VIOLATION`	ERROR	7.4
CHECK 约束计算为假，写入的行不满足条件。				活跃
23P01	exclusion_violation	`ERRCODE_EXCLUSION_VIOLATION`	ERROR	9.0
排除约束发现新行与已有行冲突，如范围重叠。				活跃

快速链接