Odooでの「duplicate key value violates unique constraint」エラーを完全解説 — 対処法まとめ

はじめに

Odooで表示される「Duplicate Key Value Violates Unique Constraint（重複キー値が一意制約に違反しています）」エラーは、データベースの一意性ルールを破るレコードの挿入・更新を試みたときに発生します。

このエラーはPostgreSQLレベルで発生するデータベース制約エラーで、主に次の箇所で確認されます：

• サーバーログ
• インポート失敗の画面
• APIレスポンス
• モジュールのアップグレード時
• データ移行スクリプト実行時

典型的なエラーメッセージの例は次の通りです：

psycopg2.errors.UniqueViolation:
duplicate key value violates unique constraint "res_partner_email_uniq"
DETAIL: Key (email)=(john@example.com) already exists.

本ガイドでは、このエラーが発生する理由を解説し、データ整合性を損なわずに適切に対処する方法を示します。

Odooでの一意制約とは何か？

一意制約は、特定のフィールドに同じ値が二度登録されるのを防ぐ仕組みです。

Odooでは一意性を確保するために次の方法が使われます：

• SQL制約
• モデル定義内の _sql_constraints
• データベースレベルのユニークインデックス

例を挙げると：

_sql_constraints = [
    ('email_unique', 'unique(email)', 'Email must be unique.')
]

この設定があると、同じメールアドレスを持つレコードが二つ存在することは許されません。

もし重複するレコードを挿入しようとすると、PostgreSQLがその操作を拒否します。

重複キー制約エラーが起きる主な原因

1. 既存と同じ内容のレコードを作成しようとした

次のようなケースではエラーが出ます：

• 既に存在するメールを持つ取引先を作成する
• 既存の内部参照と同じ型番の製品を登録する
• 既存のログイン名を持つユーザーを追加する

Odooはこれらをブロックします。

2. APIや外部連携が重複レコードを作成している

外部システムが次のような動作をすると問題になります：

• 既存の顧客を再登録してしまう
• 同じ受注を繰り返し送信する
• 製品データを重複して投入する

既存レコードの存在確認を行わないまま挿入してしまうことが多いです。

これは典型的な連携トラブルです。

3. CSVなどのインポートで重複行が混入している

ユニーク指定されたフィールドに重複値があるとインポートは失敗します。

例を挙げると：

同じメールや外部参照を持つ複数行が含まれる場合などです。

4. マイグレーションで新たに一意制約を追加した

モジュール更新で新しい一意制約が導入され、既存データに重複があると移行処理は失敗します。

5. 外部IDの扱いが不適切

連携で外部IDを無視して単純な挿入だけ行うと重複が発生します。

外部IDを正しくマッピングする戦略が重要です。

6. データベースを直接操作した

直接SQLで挿入するとORMの検証をすり抜けますが、データベースの一意制約には引っかかります。

Odooの「重複キー制約」エラーを解消する方法

ステップ1 — 制約名を特定する

エラーメッセージにはどの制約が原因かが書かれています：

duplicate key value violates unique constraint "res_partner_email_uniq"

これでどのフィールドが重複しているかが分かります。

ステップ2 — 重複レコードを見つける

該当モデル内で重複値を検索します。

例を挙げると：

例えばres.partnerテーブルでそのメールアドレスを検索します。

見つかったら次を検討してください：

• 既存レコードを更新する
• 重複レコードをマージする
• 誤ったエントリを削除する

ステップ3 — 連携ロジックを見直す

原因がAPI連携にある場合：

• 「作成前に検索する」ロジックを実装する
• 検索で既存レコードを特定する
• 見つかれば更新し、なければ作成する

これにより同じ失敗を繰り返すのを防げます。

ステップ4 — マイグレーション前に重複をクリーンアップする

移行処理が重複で失敗する場合は：

• 重複レコードを特定する
• 不要なエントリをマージまたは削除する
• その後、移行を再実行する

データを掃除せずに制約だけ外すのは避けてください。

ステップ5 — データ同期に外部IDを活用する

内部IDに頼る代わりに：

• 外部IDを使う
• 一貫したマッピングを維持する
• 盲目的な挿入を避ける

構造化された同期戦略は重複キーエラーを大幅に減らします。

ステップ6 — 直接SQLでの挿入を避ける

レコード作成には常にOdooのORMを使いましょう。

ORMは手動SQLより安全にバリデーションを行います。

重複キーエラーを未然に防ぐ方法

• 挿入前にデータを検証する
• 「作成前に検索」パターンを実装する
• 外部IDを一貫して使う
• レガシーデータを定期的に整理する
• 連携ログを監視する
• ORMを回避しない

一意制約はデータ整合性を守るための仕組みであり、制約を無効化するのではなく、適切に重複を解消することが目的です。

Dasoloが大規模データで重複を防ぐ仕組み

重複キー制約エラーは、多くの場合データ作成ワークフローにおける安全策の欠如を示しています。手動入力、インポート、API連携のいずれで発生しても、冪等性（同じ操作を何度行っても結果が変わらない性質）を担保するロジックや十分な事前検証が不足していることが原因です。

Dasoloでは、重複リスクを最小化するために次の点に注力しています：

• 一意フィールドの明確な設計方針
• 連携側での作成前検索（search-before-create）ロジックの実装
• 外部ID管理の厳格な運用
• インポート時の構造的なバリデーション
• 同期フローの継続的な監視

こうした規律あるデータガバナンスにより、制御不能な重複を防ぎ、データベースの一貫性を保ちます。

まとめ

Odooの「Duplicate Key Value Violates Unique Constraint」エラーは、本来一意であるべき値が重複しようとしたときに発生します。データベースは整合性を守るためにその操作を拒否しますが、根本原因はしばしば検証や同期ロジックの甘さにあります。

作成前検索パターンの導入、レガシーデータの重複解消、一貫した一意性戦略の運用を行えば、再発する制約違反を未然に防げます。重要なフィールドの一意性を守ることが、信頼性とスケーラビリティの高いOdoo環境を維持する鍵です。