// PostgreSQL 错误参考

PostgreSQL 23P01:排他约束冲突

在 EXCLUDE 约束下,一行与现有行冲突,通常是相同房间、资源或人员的时间范围重叠。

SQLSTATE
23P01
名称
exclusion_violation
类别
违反完整性约束
错误信息
conflicting key value violates exclusion constraint "bookings_room_during_excl"
DETAIL:  Key (room_id, during)=(4, ["2026-05-01 10:00:00","2026-05-01 11:00:00")) conflicts with existing key (room_id, during)=(4, ["2026-05-01 10:30:00","2026-05-01 12:00:00")).

它的意思

排他约束是唯一性的推广:不能有两行同时满足所有列出的比较条件。经典用法是 EXCLUDE USING gist (room_id WITH =, during WITH &&),这意味着相同房间的两次预订不可以有重叠时间段。

23P01 表示新插入或更新的行与现有行冲突,该行显示在 DETAIL 行。

常见原因

  • 双重预订:新时间段与同一键的现有时间段重叠。
  • 上界包含在内的范围([a,b])涉及的: [10:00,11:00] 和 [11:00,12:00] 在 11:00 重叠。默认的半开区间形式 [a,b) 可以避免这种情况。
  • 两个并发事务插入重叠的范围;第一个提交后,第二个就会失败。

如何修复它

  1. 在写入之前找到冲突的行,或者向用户显示哪个预订有冲突。

    SELECT * FROM bookings
    WHERE room_id = 4
      AND during && tstzrange('2026-05-01 10:00', '2026-05-01 11:00');
  2. 使用半开区间,相邻的预订就不会重叠。

    INSERT INTO bookings (room_id, during)
    VALUES (4, tstzrange('2026-05-01 11:00', '2026-05-01 12:00', '[)'));
  3. 跳过冲突的行,使用 ON CONFLICT DO NOTHING,它适用于排他约束(DO UPDATE 则不支持)。

    INSERT INTO bookings (room_id, during)
    VALUES (4, tstzrange('2026-05-01 10:00', '2026-05-01 11:00'))
    ON CONFLICT ON CONSTRAINT bookings_room_during_excl DO NOTHING;

安全地复现它

这 btree_gist 扩展允许 GiST 索引将普通整数与 =.

CREATE EXTENSION IF NOT EXISTS btree_gist;
CREATE TEMP TABLE b (room int, during tstzrange,
    EXCLUDE USING gist (room WITH =, during WITH &&));
INSERT INTO b VALUES (1, tstzrange('2026-01-01 10:00', '2026-01-01 11:00'));
INSERT INTO b VALUES (1, tstzrange('2026-01-01 10:30', '2026-01-01 12:00'));  -- ERROR: conflicting key value violates exclusion constraint

相关错误

更多完整性约束冲突错误

代码和消息文本来自 PostgreSQL 文档,附录 A:PostgreSQL 错误代码。浏览完整的 PostgreSQL 错误列表 或者 搜索每个数据库错误.

// 错误更少,修复更快

在 SQLly 中使用 PostgreSQL

适用于 macOS、Windows 和 Linux 的原生 SQL 客户端,智能感知能理解你的数据库模式,高危语句有防护,错误信息清晰,支持 PostgreSQL 以及你使用的其他数据库。