// Referencia de errores de SQL Server

Error 2627 de SQL Server: infracción de PRIMARY KEY o UNIQUE KEY

Un INSERT o UPDATE duplicaría un valor en una restricción de PRIMARY KEY o UNIQUE. El mensaje nombra la restricción, la tabla y el valor duplicado de la clave.

Número de error
2627
Gravedad
14
Categoría
Restricciones y claves
Mensaje de error
Violation of %ls constraint '%.*ls'. Cannot insert duplicate key in object '%.*ls'. The duplicate key value is %ls.

Qué significa

Las claves primarias y las restricciones únicas garantizan que no haya dos filas que compartan la misma clave. Cuando una operación de escritura crearía un duplicado, SQL Server detiene la instrucción con 2627, seguido de 3621 ("La instrucción ha sido terminada"). El mensaje indica qué tipo de restricción (PRIMARY KEY o UNIQUE KEY), su nombre, la tabla y, desde SQL Server 2017, el propio valor duplicado.

El error 2601 es el mismo fallo en un índice único que no es una restricción.

Causas comunes

  • Insertar una fila cuya clave ya existe, por ejemplo al volver a ejecutar una carga.
  • Insertar valores explícitos en una columna de identidad con IDENTITY_INSERT activado, o un reinicio de la semilla de identidad por debajo de los valores existentes.
  • Una inserción por lotes desde una fuente que contiene claves duplicadas.
  • Dos sesiones insertan la misma clave a la vez: el patrón de comprobar y luego insertar (IF NOT EXISTS ... INSERT) no es seguro sin sugerencias de bloqueo.

Cómo solucionarlo

  1. Encuentra la fila existente usando el valor que aparece en el mensaje.

    SELECT * FROM dbo.Customers WHERE Email = N'[email protected]';
  2. Omitir filas que ya existen al cargar.

    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. Busca duplicados en la fuente antes de insertar.

    SELECT Email, COUNT(*) FROM staging.Customers GROUP BY Email HAVING COUNT(*) > 1;
  4. Para un upsert seguro con concurrencia, actualiza primero e inserta si no se actualizó nada, manteniendo un bloqueo de rango.

    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. Si una columna de identidad colisiona, verifícala y reiníciala.

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

Reprodúcelo de forma segura

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;

Preguntas

¿Cuál es la diferencia entre el error 2627 y el 2601?

2627 se genera por una restricción PRIMARY KEY o UNIQUE; 2601 por un índice único creado con CREATE UNIQUE INDEX. La causa y las soluciones son las mismas.

¿Puedo hacer que SQL Server ignore las claves duplicadas?

Un índice único creado con WITH (IGNORE_DUP_KEY = ON) descarta las filas duplicadas de un INSERT con una advertencia, en lugar de fallar la instrucción. Úsalo a sabiendas, porque descarta datos en silencio.

Errores relacionados

Más errores de restricciones y claves

El código y el texto del mensaje son de Referencia de eventos y errores del motor de base de datos de Microsoft. Explora la lista completa de Lista de errores de SQL Server o buscar cada error de base de datos.

// menos errores, correcciones más rápidas

Trabajar con SQL Server en SQLly

Un cliente SQL nativo para macOS, Windows y Linux con IntelliSense que conoce el esquema, protecciones para las instrucciones de riesgo y mensajes de error claros, para SQL Server y las demás bases de datos que uses.