// Referência de erro do SQL Server

Erro do SQL Server 2627: Violação de PRIMARY KEY ou UNIQUE KEY

Um INSERT ou UPDATE duplicaria um valor em uma restrição PRIMARY KEY ou UNIQUE. A mensagem informa a restrição, a tabela e o valor da chave duplicada.

Número do erro
2627
Gravidade
14
Categoria
Restrições e chaves
Mensagem de erro
Violation of %ls constraint '%.*ls'. Cannot insert duplicate key in object '%.*ls'. The duplicate key value is %ls.

O que significa

As restrições de chave primária e única garantem que duas linhas nunca compartilhem a mesma chave. Quando uma gravação cria um duplicado, o SQL Server interrompe a instrução com 2627, seguido de 3621 ("A instrução foi encerrada"). A mensagem indica qual tipo de restrição (PRIMARY KEY ou UNIQUE KEY), seu nome, a tabela e, desde o SQL Server 2017, o próprio valor duplicado.

O erro 2601 é a mesma falha em um índice único que não é uma restrição.

Causas comuns

  • Inserindo uma linha cuja chave já existe, por exemplo, ao reexecutar um carregamento.
  • Inserindo valores explícitos em uma coluna de identidade com IDENTITY_INSERT ativada, ou redefinir a semente de identidade para valores inferiores aos existentes.
  • Uma inserção em lote vinda de uma fonte que já contém chaves duplicadas.
  • Duas sessões inserindo a mesma chave simultaneamente: o padrão de verificar antes de inserir (IF NOT EXISTS ... INSERT) não é seguro sem dicas de bloqueio.

Como corrigir

  1. Encontre a linha existente usando o valor mostrado na mensagem.

    SELECT * FROM dbo.Customers WHERE Email = N'[email protected]';
  2. Ignore linhas que já existem ao carregar.

    INSERT INTO dbo.Customers (Email, Name)
    SELECT s.Email, s.Name
    FROM staging.Customers AS s
    WHERE NOT EXISTS (SELECT 1 FROM dbo.Customers AS c WHERE c.Email = s.Email);
  3. Procure duplicatas na própria origem antes de inserir.

    SELECT Email, COUNT(*) FROM staging.Customers GROUP BY Email HAVING COUNT(*) > 1;
  4. Para um upsert seguro sob concorrência, atualize primeiro e insira se nada foi atualizado, mantendo um bloqueio de intervalo.

    BEGIN TRANSACTION;
    UPDATE dbo.Customers WITH (UPDLOCK, SERIALIZABLE) SET Name = @Name WHERE Email = @Email;
    IF @@ROWCOUNT = 0
        INSERT INTO dbo.Customers (Email, Name) VALUES (@Email, @Name);
    COMMIT;
  5. Se uma coluna de identidade colidir, verifique-a e reinicialize-a.

    DBCC CHECKIDENT ('dbo.Customers', NORESEED);  -- shows current and max values
    DBCC CHECKIDENT ('dbo.Customers', RESEED);

Reproduza com segurança

CREATE TABLE #k (id int PRIMARY KEY);
INSERT INTO #k VALUES (1);
INSERT INTO #k VALUES (1);  -- Msg 2627 ... The duplicate key value is (1).
DROP TABLE #k;

Perguntas

Qual é a diferença entre os erros 2627 e 2601?

2627 é gerado por uma restrição PRIMARY KEY ou UNIQUE; 2601 por um índice único criado com CREATE UNIQUE INDEX. A causa e as soluções são as mesmas.

Posso fazer o SQL Server ignorar chaves duplicadas?

Um índice único criado WITH (IGNORE_DUP_KEY = ON) descarta as linhas duplicadas de um INSERT com um aviso, em vez de falhar a instrução. Use-o conscientemente, já que ele descarta dados em silêncio.

Erros relacionados

Mais erros de restrições e chaves

O código e o texto da mensagem são de Referência de eventos e erros do Microsoft Database Engine. Veja toda a Lista de erros do SQL Server ou pesquise todos os erros do banco de dados.

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

Trabalhe com SQL Server 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 SQL Server e os outros bancos de dados que você usa.