23P01 exclusion_violation

排除约束冲突

ERROR 已实测详解实测通过

类别: Class 23 完整性约束冲突
严重等级: ERROR
条件名: exclusion_violation
宏名称: ERRCODE_EXCLUSION_VIOLATION
启用版本: 9.0
状态: 活跃

版本覆盖

速览

23P01 表示排除约束发现已有行与新行在所有配置运算符上冲突。本案例使用 && 检查范围重叠，因此拒绝的是重叠而不只是相等值。

含义

排除约束结合索引访问方法和运算符；[5,12) 与 [1,10) 重叠，而半开范围 [10,12) 在 10 处不重叠。运算符类和约束配置的运算符组合决定冲突；DEFERRABLE 会改变检查时点。

诊断

记录约束名、DETAIL 中的键值，以及约束是否延迟。按相同运算符检查现有行，不能只做相等比较。立即约束在语句边界报错，DEFERRABLE 约束可能在 SET CONSTRAINTS 或 COMMIT 时才报错。本案例是立即检查、自动提交，错误后连接为 IDLE。

处理

选择不冲突的值，或按应用并发策略协调冲突的预订或资源。自动提交时，失败语句结束自己的事务边界，连接可以继续使用。显式事务中，无论立即检查还是延迟检查报错，都可能使事务进入失败状态；重试前应执行 ROLLBACK，若应用刻意用保存点隔离该操作，则可执行 ROLLBACK TO SAVEPOINT 保留外层事务。DEFERRABLE 冲突可能在 SET CONSTRAINTS 或 COMMIT 才报告，因此应从该检查时点要求的干净边界重做完整操作；只有冲突确实可能消失且操作安全时才重试。不要脱离业务规则随意改范围端点。

可复现案例

在一次性实例上执行过的场景。其中 1 个附有可执行 SQL，正文相应小节里给出。

overlapping_range_exclusion PG 10 / 18 有 SQL

前置条件

A range column has a GiST exclusion constraint using &&
The second range overlaps the committed first range

触发

Insert an overlapping range.

断言

SQLSTATE is 23P01
The exclusion constraint is identified
A non-overlapping range can be inserted afterward

处置

Choose a non-overlapping interval or resolve the conflicting reservation according to business rules; do not treat exclusion as a generic duplicate-key check.

清理

Drop the case schema with an owner connection.

实测诊断

18.6 (Homebrew) / latest：SQLSTATE 23P01；primary conflicting key value violates exclusion constraint "bookings_no_overlap"；DETAIL Key (during)=([5,12)) conflicts with existing key (during)=([1,10)).；status_after_error IDLE。 10.21 (Debian 10.21-1.pgdg90+1) / pg10：SQLSTATE 23P01；primary conflicting key value violates exclusion constraint "bookings_no_overlap"；DETAIL Key (during)=([5,12)) conflicts with existing key (during)=([1,10)).；status_after_error IDLE。

报文模板

源码里的格式串，不是某一次运行的输出。%s 之类是占位符，实际报文会填入对象名与取值。适用范围一栏是核验时留下的原始英文记录，未经翻译。

主消息 conflicting key value violates exclusion constraint "%s"

DETAIL Key %s conflicts with existing key %s.

来源：src/backend/executor/execIndexing.c @ REL_18_6

适用范围：The detail is dynamically built from the conflicting key values; the fallback is “Key conflicts with existing key.”

代表案例

本例第二个预订与已有范围重叠；把下界移到已有范围的上界即可修复。完整 setup、断言与清理见案例导出：

-- create
CREATE TABLE bookings(id integer PRIMARY KEY, during int4range NOT NULL, CONSTRAINT bookings_no_overlap EXCLUDE USING gist (during WITH &&));
-- seed
INSERT INTO bookings VALUES (1, int4range(1, 10));
-- trigger
INSERT INTO bookings VALUES (2, int4range(5, 12));
-- repair
INSERT INTO bookings VALUES (2, int4range(10, 12));
-- verify
SELECT id, during::text FROM bookings ORDER BY id;

本案例对应的 SQLSTATE、诊断、事务状态和修复断言均来自经核对的案例 registry；见结构化证据和案例导出。

作者证据 ID：identity, mechanism, runtime。选定运行记录：runtime.23P01-batch1-latest-20260909.latest, runtime.23P01-batch1-pg10-20260909.pg10。

版本与边界

锁定目录从 9.0.0 起观察到 23P01，并在列出的正式快照中均存在。选定的立即范围案例在 18.6 与 10.21 通过；未测试延迟或并发排除检查。

来源

上游源码 doc/src/sgml/rangetypes.sgml 第 540–573 行 REL_18_6 724edf9bd cfeffb13
上游源码 src/backend/utils/errcodes.txt REL_18_6 724edf9bd 6e8de346
上游源码 src/backend/executor/execIndexing.c 第 917–937 行 REL_18_6 724edf9bd 24c80553
核验材料 raw/calls/REL_18_6.jsonl 9ee8a0e8

证据

断言

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

23P01 is exclusion_violation in Class 23.

核实方式Read the fixed errcodes row.

不覆盖The exclusion operator may compare more than equality; the operator class and constraint definition determine the conflict.

来源src/backend/utils/errcodes.txt
An exclusion constraint rejects a row when the configured operator comparisons are all true against an existing row; the range example uses && for overlap.

核实方式Trace check_exclusion_or_unique_constraint and the range exclusion documentation.

不覆盖A half-open range [10,12) does not overlap [1,10); changing bounds is a business rule, not a blanket retry.

来源src/backend/executor/execIndexing.c · doc/src/sgml/rangetypes.sgml · raw/calls/REL_18_6.jsonl
The selected immediate GiST range case returned 23P01 on PG18.6 and PG10.21, identified bookings_no_overlap, stayed IDLE, and committed a non-overlapping [10,12) range.

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

不覆盖This case does not test DEFERRABLE exclusion constraints, concurrent waits, or every operator class.

运行记录

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

同类 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
排除约束发现新行与已有行冲突，如范围重叠。				活跃

快速链接