// 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 客戶端,具備結構描述感知的 IntelliSense、高風險陳述式防護與清楚的錯誤訊息,適用於 PostgreSQL 和你使用的其他資料庫。