Introdução
O erro “Odoo ‘Valor de Chave Duplicada Viola a Restrição Única’ ocorre quando o sistema tenta inserir ou atualizar um registro que quebra uma regra de unicidade do banco de dados.
Este é um erro de restrição a nível de banco de dados gerado pelo PostgreSQL e normalmente aparece em:
- Registros do servidor
- Falhas de importação
- Respostas da API
- Atualizações de módulo
- Scripts de migração de dados
O erro geralmente aparece assim:
psycopg2.errors.UniqueViolation: vio de chave duplicada viola a restrição única "res_partner_email_uniq" DETALHE: A chave (email)=(john@example.com) já existe.
Este guia explica por que esse erro acontece e como corrigi-lo adequadamente sem comprometer a integridade dos dados.
O que é uma restrição única no Odoo?
Uma restrição única garante que certos campos não possam conter valores duplicados.
No Odoo, a unicidade pode ser imposta através de:
- Restrições SQL
- _sql_constraints nas definições de modelo
- Índices únicos a nível de banco de dados
Exemplo:
_sql_constraints = [
('email_unique', 'unique(email)', 'O email deve ser único.')
]
Isto significa que nenhum dois registos podem partilhar o mesmo endereço de email.
Se um duplicado for inserido, o PostgreSQL rejeita a operação.
Causas comuns de erros de restrição de chave duplicada
1. Criando um Registo que Já Existe
Se você tentar criar:
- Um parceiro com um email existente
- Um produto com uma referência interna existente
- Um utilizador com um login existente
Odoo bloqueia isso.
2. API ou Integração Criando Registos Duplicados
Sistemas externos podem tentar:
- Recriar clientes existentes
- Reenviar o mesmo pedido
- Entradas de produtos duplicadas
Sem verificar se o registo já existe.
Este é um problema comum de integração.
3. Importação de Linhas Duplicadas
Importações CSV contendo valores duplicados em campos únicos falharão.
Exemplo:
Duas linhas com o mesmo email ou referência externa.
4. Migração Adicionando uma Nova Restrição Única
Se uma atualização de módulo introduzir uma nova restrição única e os dados existentes contiverem duplicados, a migração falha.
5. Tratamento Incorreto de ID Externo
Se as integrações ignorarem IDs externos e dependerem apenas de inserções brutas, duplicatas podem ocorrer.
Estratégias de mapeamento adequadas previnem este problema.
6. Manipulação Manual do Banco de Dados
Inserções SQL diretas podem contornar a validação do ORM, mas ainda assim ativar restrições únicas a nível de base de dados.
Como corrigir o erro de restrição de chave duplicada no Odoo
Passo 1 – Identificar o Nome da Restrição
A mensagem de erro especifica a restrição:
o valor da chave duplicada viola a restrição única "res_partner_email_uniq"
Isto indica qual campo está duplicado.
Passo 2 – Localizar o Registro Duplicado
Pesquise o modelo pelo valor duplicado.
Exemplo:
Pesquise o email existente em res.partner.
Decida se deve:
- Atualizar o registro existente
- Mesclar duplicados
- Remover entrada incorreta
Passo 3 – Ajustar a Lógica de Integração
Se causado pela integração da API:
- Implementar a lógica de “pesquisar antes de criar”
- Usar pesquisa para encontrar registos existentes
- Atualizar em vez de criar duplicados
Isto evita falhas repetidas.
Passo 4 – Limpar Dados Duplicados Antes da Migração
Se a migração falhar devido a duplicados:
- Identificar registos duplicados
- Fundir ou eliminar entradas redundantes
- Depois, executar novamente a migração
Nunca remover a restrição sem limpar os dados.
Passo 5 – Use IDs Externos para Sincronização de Dados
Em vez de depender de IDs de banco de dados internos:
- Use IDs externos
- Mantenha um mapeamento consistente
- Evite inserções cegas
Estratégias de sincronização estruturadas reduzem significativamente erros de chave duplicada.
Passo 6 – Evite Inserções SQL Diretas
Use sempre o ORM do Odoo para criação de registros.
O ORM lida com validação de forma mais segura do que operações SQL manuais.
Como prevenir erros de chave duplicada
- Valide os dados antes da inserção
- Implemente o padrão “pesquisar antes de criar”
- Use IDs externos de forma consistente
- Limpar dados legados regularmente
- Monitorizar registos de integração
- Evitar contornar o ORM
As restrições únicas existem para proteger a integridade dos dados. O objetivo é resolver duplicados adequadamente em vez de desativar as restrições.
Como a Dasolo previne a duplicação de dados em grande escala
Erros de restrição de chave duplicada indicam tipicamente a falta de salvaguardas nos fluxos de trabalho de criação de dados. Quer sejam provocados por entrada manual, importações ou integrações de API, estes problemas frequentemente revelam a ausência de lógica idempotente ou validação insuficiente antes da criação de registos.
Na Dasolo, minimizamos os riscos de duplicação ao focar em:
- Estratégias claras de campos únicos
- Lógica de pesquisa antes da criação em integrações
- Gestão controlada de IDs externos
- Validação estruturada de importação
- Monitorização contínua dos fluxos de sincronização
Uma abordagem disciplinada de governança de dados previne a duplicação descontrolada e preserva a consistência da base de dados.
Conclusão
O erro "Valor da Chave Duplicada Viola a Restrição Única" do Odoo ocorre quando uma operação tenta criar ou atualizar um registro com um valor que deve permanecer único. Embora o banco de dados bloqueie a ação para proteger a integridade, a causa subjacente está frequentemente ligada a uma validação fraca ou lógica de sincronização.
Ao implementar padrões de pesquisa antes da criação, limpar duplicatas legadas e impor estratégias de unicidade consistentes, os desenvolvedores podem prevenir violações recorrentes de restrições. Proteger campos de dados únicos é essencial para manter ambientes Odoo confiáveis e escaláveis.