소개
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를 무시하고 단순 삽입만 할 경우 중복이 발생할 수 있습니다.
적절한 매핑 전략이 이를 막아줍니다.
6. 수동으로 데이터베이스를 조작할 때
직접 SQL 삽입은 ORM 검증을 우회하지만 데이터베이스 수준의 고유 제약은 여전히 작동합니다.
Odoo 중복 키 제약 오류 해결 방법
1단계 – 제약 이름 파악
오류 메시지는 어떤 제약이 걸렸는지 알려줍니다:
duplicate key value violates unique constraint "res_partner_email_uniq"
이를 통해 어느 필드에 중복이 있는지 추적할 수 있습니다.
2단계 – 중복 레코드 찾기
해당 모델에서 중복 값을 검색하세요.
예시:
res.partner에서 문제가 된 이메일을 찾아봅니다.
다음 중 하나를 결정합니다:
- 기존 레코드를 업데이트할지
- 레코드를 병합할지
- 잘못된 항목을 삭제할지
3단계 – 연동 로직 조정
API 연동 때문에 발생했다면:
- “생성 전에 검색(search-before-create)” 로직을 구현하세요.
- 검색으로 기존 레코드를 찾고
- 새로 만들지 말고 업데이트합니다.
이로써 반복적 실패를 막을 수 있습니다.
4단계 – 마이그레이션 전에 중복 데이터 정리
마이그레이션이 중복 때문에 실패했다면:
- 중복 레코드를 식별하고
- 중복 항목을 병합하거나 삭제한 뒤
- 마이그레이션을 다시 실행합니다.
데이터를 정리하지 않고 제약을 제거해서는 안 됩니다.
5단계 – 데이터 동기화에 외부 ID 사용
내부 데이터베이스 ID에 의존하지 말고:
- 외부 ID를 사용하세요.
- 일관된 매핑을 유지하고
- 무분별한 삽입을 피합니다.
구조화된 동기화 전략은 중복 키 오류를 크게 줄여줍니다.
6단계 – 직접 SQL 삽입 피하기
레코드 생성 시 항상 Odoo ORM을 사용하세요.
ORM은 수동 SQL보다 검증을 안전하게 처리합니다.
중복 키 오류 예방 방법
- 삽입 전에 데이터를 검증하세요.
- ‘생성 전에 검색’ 패턴을 구현하세요.
- 외부 ID를 일관되게 사용하세요.
- 레거시 데이터를 정기적으로 정리하세요.
- 연동 로그를 모니터링하세요.
- ORM 우회를 피하세요.
고유 제약은 데이터 무결성을 지키기 위한 장치입니다. 제약을 비활성화하기보다는 중복을 올바르게 해결하는 게 목표입니다.
Dasolo가 대규모 데이터 중복을 막는 방식
중복 키 제약 오류는 보통 데이터 생성 워크플로우에 안전장치가 없음을 알려줍니다. 수동 입력, 가져오기, API 연동 등 어디에서나 발생할 수 있으며, 본질적으로는 반복 가능한(idempotent) 로직 부재나 사전 검증 부족에 기인합니다.
Dasolo에서는 중복 위험을 최소화하기 위해 다음에 집중합니다:
- 명확한 고유 필드 전략 수립
- 연동에서의 검색-후-생성(search-before-create) 로직 적용
- 통제된 외부 ID 관리
- 구조화된 가져오기 검증 프로세스
- 동기화 흐름에 대한 지속적 모니터링
엄격한 데이터 거버넌스가 통제되지 않은 중복을 막고 데이터베이스 일관성을 지킵니다.
결론
Odoo의 “Duplicate Key Value Violates Unique Constraint” 오류는 고유해야 할 값으로 레코드를 만들거나 업데이트하려 할 때 발생합니다. 데이터베이스가 무결성을 보호하기 위해 작업을 차단하지만, 근본 원인은 보통 검증이나 동기화 로직의 약점에 있습니다.
생성 전 검색 패턴을 구현하고, 기존 중복을 정리하며, 고유성 전략을 일관되게 적용하면 반복적인 제약 위반을 예방할 수 있습니다. 고유 필드를 보호하는 것은 신뢰 가능하고 확장 가능한 Odoo 환경을 유지하는 데 필수적입니다.