Wprowadzenie
Błąd „Duplicate Key Value Violates Unique Constraint” w Odoo pojawia się, gdy system próbuje dodać lub zaktualizować rekord w sposób naruszający regułę unikalności w bazie danych.
To błąd na poziomie bazy danych zgłaszany przez PostgreSQL i zwykle widoczny w:
- logach serwera
- niepowodzeniach importu
- odpowiedziach API
- podczas aktualizacji modułów
- skryptach migracyjnych
Błąd zwykle wygląda tak:
psycopg2.errors.UniqueViolation: duplicate key value violates unique constraint "res_partner_email_uniq" DETAIL: Key (email)=(john@example.com) already exists.
Ten przewodnik wyjaśnia, dlaczego pojawia się ten błąd i jak go poprawnie naprawić, nie narażając spójności danych.
Czym jest ograniczenie unikalności w Odoo?
Ograniczenie unikalności wymusza, by określone pola nie zawierały powtarzających się wartości.
W Odoo ograniczenia unikalności można stosować poprzez:
- konstrainty SQL
- _sql_constraints w definicjach modeli
- unikalne indeksy na poziomie bazy danych
Przykład:
_sql_constraints = [
('email_unique', 'unique(email)', 'Email must be unique.')
]
Oznacza to, że dwa rekordy nie mogą mieć tego samego adresu e‑mail.
Jeśli spróbujesz wstawić duplikat, PostgreSQL odrzuci operację.
Najczęstsze przyczyny błędów „duplicate key constraint”
1. Tworzenie rekordu, który już istnieje
Do bazy próbujesz wstawić:
- kontrahenta z już istniejącym adresem e‑mail
- produkt o tym samym kodzie wewnętrznym
- użytkownika z tym samym loginem
Odoo zablokuje taką operację.
2. Integracja lub API tworzą duplikaty
System zewnętrzny może próbować:
- ponownie utworzyć istniejących klientów
- wysłać ten sam zamówienie wielokrotnie
- dodać powtarzające się produkty
bez weryfikacji, czy rekord już istnieje.
To częsty problem przy integracjach.
3. Importowanie powtarzających się wierszy
Import CSV zawierający powtarzające się wartości w polach unikalnych zakończy się błędem.
Przykład:
Na przykład dwa wiersze z tym samym adresem e‑mail lub referencją zewnętrzną.
4. Migracja wprowadzająca nowe ograniczenie unikalności
Jeśli aktualizacja modułu dodaje nowe ograniczenie, a istniejące dane zawierają duplikaty — migracja nie powiedzie się.
5. Nieprawidłowe operowanie identyfikatorami zewnętrznymi
Jeśli integracje ignorują external_id i wykonują surowe inserty, łatwo o duplikaty.
Prawidłowe mapowanie zapobiega temu problemowi.
6. Ręczne modyfikacje bazy danych
Bezpośrednie inserty SQL mogą ominąć walidacje ORM, ale nadal aktywują ograniczenia unikalności na poziomie bazy.
Jak naprawić błąd duplikatu klucza w Odoo
Krok 1 – Zidentyfikuj nazwę ograniczenia
Treść błędu wskazuje nazwę konstraintu:
duplicate key value violates unique constraint "res_partner_email_uniq"
To pozwala określić, które pole powoduje konflikt.
Krok 2 – Znajdź duplikat
Wyszukaj w modelu wartość, która powoduje konflikt.
Przykład:
Na przykład wyszukaj ten adres e‑mail w tabeli res.partner.
Zdecyduj, czy:
- zaktualizować istniejący rekord
- połączyć rekordy (merge)
- usunąć błędny wpis
Krok 3 – Dostosuj logikę integracji
Jeżeli przyczyną był API/integracja:
- wprowadź logikę „search before create”
- najpierw wyszukuj istniejące rekordy
- aktualizuj je zamiast tworzyć nowe duplikaty
To ograniczy powtarzające się błędy.
Krok 4 – Oczyść duplikaty przed migracją
Gdy migracja zawodzi z powodu duplikatów:
- zidentyfikuj rekordy powtarzające się
- scal je lub usuń zbędne wpisy
- następnie uruchom migrację ponownie
Nigdy nie usuwaj ograniczenia bez oczyszczenia danych.
Krok 5 – Korzystaj z external_id do synchronizacji danych
Zamiast polegać na wewnętrznych identyfikatorach bazy:
- używaj external_id
- utrzymuj spójne mapowanie rekordów
- unikaj ślepych insertów
Ustrukturyzowane strategie synchronizacji znacząco zmniejszają liczbę błędów unikalności.
Krok 6 – Unikaj bezpośrednich insertów SQL
Zawsze używaj ORM Odoo do tworzenia rekordów.
ORM wykonuje dodatkowe walidacje bezpieczniej niż ręczne operacje SQL.
Jak zapobiegać błędom związanym z duplikacją kluczy
- Waliduj dane przed wstawieniem
- stosuj wzorzec „search-before-create”
- konsekwentnie korzystaj z external_id
- regularnie oczyszczaj dane historyczne
- monitoruj logi integracji
- nie omijaj warstwy ORM
Ograniczenia unikalności chronią integralność danych. Kluczowe jest poprawne usuwanie duplikatów zamiast trwałego wyłączania tych ograniczeń.
Jak Dasolo zapobiega duplikacji danych na dużą skalę
Błędy związane z duplikacją kluczy najczęściej ujawniają braki w procesach tworzenia danych. Niezależnie czy powstają przez ręczne wprowadzanie, importy czy API, zwykle wskazują na brak idempotentnej logiki i niewystarczającą walidację przed zapisem.
W Dasolo minimalizujemy ryzyko duplikacji, koncentrując się na:
- jasnych zasadach wyboru pól unikalnych
- logice „search-before-create” w integracjach
- kontrolowanym zarządzaniu external_id
- ustrukturyzowanej walidacji importów
- ciągłym monitoringu procesów synchronizacji
Zdyscyplinowane zarządzanie danymi zapobiega niekontrolowanej duplikacji i utrzymuje spójność bazy.
Podsumowanie
Błąd Odoo „Duplicate Key Value Violates Unique Constraint” pojawia się, gdy próba utworzenia lub aktualizacji rekordu używa wartości, która musi pozostać unikalna. Baza blokuje operację, chroniąc integralność, a źródło problemu zwykle leży w niedostatecznej walidacji lub słabej logice synchronizacji.
Stosując wzorce search‑before‑create, usuwając historyczne duplikaty i konsekwentnie egzekwując zasady unikalności, programiści mogą zapobiegać powtarzającym się naruszeniom ograniczeń. Ochrona pól wymagających unikalności jest niezbędna dla stabilnych i skalowalnych środowisk Odoo.