// Referência de erro do PostgreSQL

PostgreSQL 23505: chave duplicada viola a restrição de unicidade

Um INSERT ou UPDATE criaria uma segunda linha com o mesmo valor em uma coluna coberta por chave primária, restrição única ou índice único.

SQLSTATE
23505
Nome
unique_violation
Categoria
Violação de restrição de integridade
Mensagem de erro
duplicate key value violates unique constraint "users_email_key"
DETAIL:  Key (email)=([email protected]) already exists.

O que significa

O PostgreSQL aplica cada chave primária, UNIQUE restrição e índice único no momento em que uma linha é gravada. Se a nova linha ou a linha alterada tiver a mesma chave que uma linha que já existe (ou que outra transação gravou mas ainda não foi confirmada), a instrução falha com 23505 e nada que foi alterado é mantido.

O DETAIL a linha nomeia a coluna e o valor duplicado, e a mensagem nomeia a restrição ou o índice, o que diz exatamente qual regra foi violada.

Causas comuns

  • Inserindo uma linha cuja chave já existe, por exemplo, executando novamente uma importação ou um script de seed.
  • A serial ou sequência de identidade que ficou para trás em relação aos dados, geralmente depois que linhas foram carregadas com IDs explícitos. O próximo ID padrão colide com uma linha existente: o clássico Key (id)=(1) already exists.
  • Duas sessões inserindo a mesma chave ao mesmo tempo; a segunda espera pela primeira e falha assim que a primeira é confirmada.
  • Uma UPDATE que define uma coluna única para um valor que outra linha já possui.

Como corrigir

  1. Encontre a linha existente mencionada na DETAIL linha e decida se os novos dados são um duplicado ou um registro diferente.

    SELECT * FROM users WHERE email = '[email protected]';
  2. Se a gravação deve atualizar a linha existente, transforme em um upsert com ON CONFLICT.

    INSERT INTO users (email, name)
    VALUES ('[email protected]', 'Ada')
    ON CONFLICT (email) DO UPDATE SET name = EXCLUDED.name;
  3. Se as duplicatas devem ser simplesmente ignoradas, use ON CONFLICT DO NOTHING.

    INSERT INTO users (email, name)
    VALUES ('[email protected]', 'Ada')
    ON CONFLICT (email) DO NOTHING;
  4. Se a duplicata estiver em uma serial ou ID de identidade, mova a sequência para além do maior valor existente.

    SELECT setval(pg_get_serial_sequence('users', 'id'),
                  (SELECT COALESCE(MAX(id), 0) + 1 FROM users), false);

Reproduza com segurança

CREATE TEMP TABLE t (id int PRIMARY KEY);
INSERT INTO t VALUES (1);
INSERT INTO t VALUES (1);  -- ERROR: duplicate key value violates unique constraint "t_pkey"

Perguntas

Por que o insert falha com chave duplicada na coluna id quando eu nunca defino o id?

A sequência da tabela está atrasada em relação aos dados, geralmente porque linhas foram inseridas com IDs explícitos ou restauradas sem o valor da sequência. Redefina-a com setval para uma posição depois MAX(id).

O ON CONFLICT funciona com qualquer índice único?

Funciona com as colunas de um índice único ou restrição única, ou com ON CONFLICT ON CONSTRAINT name. Requer PostgreSQL 9.5 ou mais recente.

Erros relacionados

Mais erros de violação de restrição de integridade

O código e o texto da mensagem são de documentação do PostgreSQL, Apêndice A: Códigos de erro do PostgreSQL. Veja toda a Lista de erros do PostgreSQL ou pesquise todos os erros do banco de dados.

// menos erros, correções mais rápidas

Trabalhe com PostgreSQL no SQLly

Um cliente SQL nativo para macOS, Windows e Linux com IntelliSense que conhece o esquema, proteções para instruções arriscadas e mensagens de erro claras, para o PostgreSQL e os outros bancos de dados que você usa.