Introdução
O erro Odoo “Duplicate Key Value Violates Unique Constraint” surge quando o sistema tenta inserir ou actualizar um registo que viola uma regra de unicidade definida na base de dados.
Trata-se de um erro gerado ao nível da base de dados pelo PostgreSQL e costuma aparecer em várias situações operacionais, tais como:
- Registos de servidor
- Falhas em importações
- Respostas de APIs
- Atualizações de módulos
- Scripts de migração de dados
A mensagem típica do erro é clara e aponta para a restrição violada, indicando que um valor já existe.
psycopg2.errors.UniqueViolation: duplicate key value violates unique constraint "res_partner_email_uniq" DETAIL: Key (email)=(john@example.com) already exists.
Este artigo descreve porque é que este erro acontece e quais as medidas corretas para o resolver sem pôr em risco a integridade dos dados.
O que é uma restrição de unicidade no Odoo?
Uma restrição de unicidade garante que determinados campos não admitam valores repetidos dentro da tabela.
No Odoo, a unicidade pode ser aplicada de várias formas técnicas, por exemplo:
- Restrições SQL
- Declarações _sql_constraints nos modelos
- Índices únicos ao nível da base de dados
Exemplo prático:
_sql_constraints = [
('email_unique', 'unique(email)', 'Email must be unique.')
]
Isto significa que não podem existir dois registos com o mesmo endereço de email na tabela em questão.
Sempre que se tenta inserir um valor duplicado, o PostgreSQL rejeita a operação.
Causas mais comuns do erro de chave duplicada
1. Tentativa de criar um registo já existente
Cenário típico:
- Criar um parceiro com um email que já existe
- Criar um produto com a mesma referência interna
- Criar um utilizador com um login duplicado
Nessas situações, o Odoo impede a operação.
2. Integrações ou APIs que geram duplicados
Sistemas externos podem fazer operações sem verificar o estado actual dos dados, por exemplo:
- Recriar clientes já existentes
- Reenviar o mesmo pedido
- Duplicar itens de catálogo
Tudo isto acontece quando não se valida se o registo já existe antes de inserir.
Trata-se de uma causa muito frequente em integrações.
3. Importações com linhas duplicadas
Importar ficheiros CSV com campos que deveriam ser únicos irá causar falhas.
Exemplo prático:
Por exemplo, duas linhas com o mesmo email ou referência externa geram erro.
4. Migração que adiciona nova restrição de unicidade
Se durante uma actualização se introduzir uma nova restrição e já existirem duplicados, a migração falha.
5. Mau tratamento de External IDs
Integrações que ignoram os external IDs e fazem inserts directos tendem a criar duplicados.
Um mapeamento correcto entre sistemas evita este problema.
6. Manipulação manual da base de dados
Inserções directas via SQL podem contornar validações do ORM mas continuam a ser bloqueadas pelas restrições da base de dados.
Como corrigir o erro de chave duplicada no Odoo
Passo 1 – Identificar o nome da restrição
A própria mensagem de erro indica qual a restrição afectada:
duplicate key value violates unique constraint "res_partner_email_uniq"
A partir daí sabe-se qual o campo em duplicado.
Passo 2 – Localizar o registo duplicado
Procure o valor repetido no modelo correspondente.
Exemplo prático:
Por exemplo, pesquise o email em res.partner.
Decida qual a acção adequada:
- Actualizar o registo existente
- Fundir registos duplicados
- Eliminar entradas incorrectas
Passo 3 – Ajustar a lógica das integrações
Se a causa for uma API ou integração:
- Implemente a lógica de “pesquisar antes de criar”
- Use pesquisas para confirmar se o registo já existe
- Actualize em vez de criar quando apropriado
Isto evita falhas repetidas durante sincronizações.
Passo 4 – Limpar dados duplicados antes de migrar
Quando a migração falha por causa de duplicados:
- Identifique quais os registos repetidos
- Faça merge ou elimine os duplicados desnecessários
- Depois, reexecute a migração
Nunca remova a restrição sem primeiro tratar os dados duplicados.
Passo 5 – Usar External IDs para sincronização de dados
Em vez de depender apenas dos IDs internos da base de dados:
- Utilize external IDs nas integrações
- Mantenha o mapeamento consistente entre sistemas
- Evite inserts “ciegos” sem referência externa
Estratégias de sincronização bem definidas reduzem significativamente erros de chave duplicada.
Passo 6 – Evitar inserts directos via SQL
Prefira sempre o ORM do Odoo quando criar registos.
O ORM aplica validações e regras de forma mais segura do que operações SQL manuais.
Como evitar erros de chave duplicada
- Valide os dados antes de os inserir
- Implemente o padrão “pesquisar antes de criar”
- Use external IDs de forma consistente
- Limpe dados legacy com regularidade
- Monitore os logs das integrações
- Evite contornar o ORM para operações de escrita
As restrições de unicidade existem para proteger a integridade dos dados. O objectivo é resolver duplicados de forma correcta, não desactivar as restrições.
Como a Dasolo evita duplicações de dados em grande escala
Os erros de chave duplicada normalmente revelam lacunas nas regras de criação de dados. Quer venham de entradas manuais, importações ou integrações via API, mostram a ausência de lógica idempotente e validação suficiente antes de criar registos.
Na Dasolo, reduzimos o risco de duplicação apostando em:
- Políticas claras sobre quais os campos que devem ser únicos
- Lógica de “pesquisar antes de criar” nas integrações
- Gestão controlada de External IDs
- Validação estruturada nas importações
- Monitorização contínua dos fluxos de sincronização
Uma governação de dados disciplinada evita duplicações descontroladas e mantém a consistência da base de dados.
Conclusão
O erro Odoo “Duplicate Key Value Violates Unique Constraint” acontece quando uma operação tenta criar ou actualizar um registo com um valor que tem de ser único. A base de dados bloqueia a operação para proteger a integridade; na origem está quase sempre validação fraca ou lógica de sincronização inadequada.
Aplicando padrões como “pesquisar antes de criar”, eliminando duplicados legados e definindo políticas de unicidade consistentes, os desenvolvedores evitam violações recorrentes. Proteger campos únicos é crucial para sistemas Odoo fiáveis e escaláveis.