できない.dev

PostgreSQL「duplicate key value violates unique constraint」の原因と直し方

duplicate key value violates unique constraint は、DETAIL に出た値の重複を除くか、ずれたシーケンスを setval で最大値に合わせれば直る。
id を明示して INSERT したあとの serial 列でよく起きる。

公開: 更新:

症状できない
psql -U postgres -a -f setup.sql
CREATE TABLE users (id serial PRIMARY KEY, email text UNIQUE);
CREATE TABLE
INSERT INTO users (id, email) VALUES (1, 'a@example.com'), (2, 'b@example.com'), (3, 'c@example.com');
INSERT 0 3

2026-11-19 に postgres:17(PostgreSQL 17.12) で実際に打って取った出力。検証環境の詳細

要約

PostgreSQL で INSERT すると、次の 2 行が出て行が入らない。

ERROR:  duplicate key value violates unique constraint "users_pkey"
DETAIL:  Key (id)=(3) already exists.

duplicate key value violates unique constraint は、UNIQUE か PRIMARY KEY の制約が付いた列に、すでにある値を入れようとしたときのエラーである。
DETAIL に出た値の重複を除くか、ずれたシーケンスを setval で最大値に合わせれば直る。
PostgreSQL 17.11 の公式イメージで、id を明示して入れたあとに id を省いて INSERT すると、上のエラーになった。

実行例

id を明示して 3 行入れた users に id を省いて INSERT すると、シーケンスが 1 のままなので users_pkey の重複で失敗し、同じ email を入れても users_email_key で失敗する。
setval で最大値の次に合わせると通り、ON CONFLICT (email) DO NOTHING ではエラーにならず INSERT 0 0 になる。

$ psql -U postgres -a -f setup.sql
CREATE TABLE users (id serial PRIMARY KEY, email text UNIQUE);
CREATE TABLE
INSERT INTO users (id, email) VALUES (1, 'a@example.com'), (2, 'b@example.com'), (3, 'c@example.com');
INSERT 0 3
$ psql -U postgres -a -f bad_seq.sql
INSERT INTO users (email) VALUES ('d@example.com');
psql:bad_seq.sql:1: ERROR:  duplicate key value violates unique constraint "users_pkey"
DETAIL:  Key (id)=(1) already exists.
$ psql -U postgres -a -f bad_email.sql
INSERT INTO users (id, email) VALUES (10, 'a@example.com');
psql:bad_email.sql:1: ERROR:  duplicate key value violates unique constraint "users_email_key"
DETAIL:  Key (email)=(a@example.com) already exists.
$ psql -U postgres -a -f solve_setval.sql
SELECT setval(pg_get_serial_sequence('users', 'id'), COALESCE(MAX(id), 0) + 1, false) FROM users;
 setval 
--------
      4
(1 row)
 
INSERT INTO users (email) VALUES ('d@example.com');
INSERT 0 1
SELECT id, email FROM users ORDER BY id;
 id |     email     
----+---------------
  1 | a@example.com
  2 | b@example.com
  3 | c@example.com
  4 | d@example.com
(4 rows)
$ psql -U postgres -a -f solve_conflict.sql
INSERT INTO users (email) VALUES ('a@example.com') ON CONFLICT (email) DO NOTHING;
INSERT 0 0

— 2026-11-19 時点の出力

検証環境PostgreSQL 17.12 / 2026-11-19 検証
検証日
実行環境
postgres:17 Debian GNU/Linux 13 (trixie)
バージョン
  • PostgreSQL 17.12

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. ずれたシーケンスを最大値の次に合わせる

DETAIL が Key (id)=(...) で、アプリは id を指定していないなら、2 のずれである。

SELECT setval(pg_get_serial_sequence('users', 'id'), COALESCE(MAX(id), 0) + 1, false) FROM users;

pg_get_serial_sequence は、列に結び付いたシーケンスの名前(public.users_id_seq)を返す。
第 3 引数を false にすると、次の nextval は指定した値そのものを返す。
表が空でも COALESCE で 1 に合わせられる。
id 1・2 をシーケンスで入れたあとに id 3 を明示した表では、setval が 4 を返し、続く INSERT は id 4 で入った。
identity 列の表でも同じ文で直る。

2. 重なったときの動きを INSERT に書く

重なった行を新しい値で更新してよいなら ON CONFLICT ... DO UPDATE を付ける(INSERT(新しいタブで開く))。

INSERT INTO users (email) VALUES ('a@example.com')
ON CONFLICT (email) DO UPDATE SET email = EXCLUDED.email
RETURNING id;

EXCLUDED は、入れようとした行を指す。
捨ててよいだけなら ON CONFLICT (email) DO NOTHING にする。
こちらはエラーにならず INSERT 0 0 で終わった。

3. 再実行しても重ならない処理にする

バッチやリトライで同じ行を入れる処理は、2 の ON CONFLICT を付けて、何度実行しても結果が同じになるようにする。
重なりそのものが不正なデータなら、エラーのまま止めて元の値を直す。

よくある原因

  1. 同じ値をもう一度入れている。
    制約名が users_email_key で DETAIL: Key (email)=(a@example.com) already exists. なら、email 列の値が重なっている。
    制約名と列は \d users で確かめられる。
  2. シーケンスが実データより遅れている。
    serial や GENERATED BY DEFAULT AS IDENTITY の列は、値を省くとシーケンスの nextval で番号を取る。
    シードや別のデータベースからの移行で id を明示して入れても、シーケンスは進まない。
    次に id を省いた INSERT が、すでにある番号を引いてぶつかる。
  3. 同じ行を二度入れている。
    バッチの再実行やリトライで、1 回目が成功していたのに同じ値で INSERT し直している。

失敗した INSERT でも、引いたシーケンスの番号は戻らない(シーケンス操作関数(新しいタブで開く))。
番号が飛ぶのは正常な動作である。