// Referencia de errores de PostgreSQL

PostgreSQL 23505: clave duplicada viola la restricción única

Un INSERT o UPDATE crearía una segunda fila con el mismo valor en una columna cubierta por una clave primaria, restricción única o índice único.

SQLSTATE
23505
Nombre
unique_violation
Categoría
Violación de restricción de integridad
Mensaje de error
duplicate key value violates unique constraint "users_email_key"
DETAIL:  Key (email)=([email protected]) already exists.

Qué significa

PostgreSQL aplica cada clave primaria, UNIQUE restricción e índice único en el momento en que se escribe una fila. Si la fila nueva o modificada tiene la misma clave que una fila que ya existe (o que otra transacción ha escrito pero que aún no se ha confirmado), la instrucción falla con 23505 y no se conserva ningún cambio.

La DETAIL La línea indica la columna y el valor duplicado, y el mensaje nombra la restricción o el índice, lo que te dice exactamente qué regla se incumplió.

Causas comunes

  • Insertar una fila cuya clave ya existe, por ejemplo al volver a ejecutar una importación o un script de inicialización.
  • A serial o secuencia de identidad que se ha quedado atrás respecto a los datos, normalmente porque se cargaron filas con ids explícitos. El siguiente id por defecto colisiona con una fila existente: el clásico Key (id)=(1) already exists.
  • Dos sesiones insertan la misma clave al mismo tiempo; la segunda espera a la primera y falla en cuanto esta confirma.
  • Una UPDATE que establece en una columna única un valor que otra fila ya tiene.

Cómo solucionarlo

  1. Encuentra la fila existente mencionada en la DETAIL línea y decide si los nuevos datos son un duplicado o un registro diferente.

    SELECT * FROM users WHERE email = '[email protected]';
  2. Si lo que quieres es actualizar la fila existente, conviértelo en un upsert con ON CONFLICT.

    INSERT INTO users (email, name)
    VALUES ('[email protected]', 'Ada')
    ON CONFLICT (email) DO UPDATE SET name = EXCLUDED.name;
  3. Si simplemente quieres omitir los duplicados, usa ON CONFLICT DO NOTHING.

    INSERT INTO users (email, name)
    VALUES ('[email protected]', 'Ada')
    ON CONFLICT (email) DO NOTHING;
  4. Si el duplicado está en un serial o id de identidad, adelanta la secuencia más allá del valor más alto existente.

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

Reprodúcelo de forma segura

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"

Preguntas

¿Por qué falla el insert con clave duplicada en la columna id si nunca establecí el id?

La secuencia de la tabla está por detrás de los datos, normalmente porque se insertaron filas con IDs explícitos o se restauraron sin el valor de la secuencia. Restablécela con setval a uno más que MAX(id).

¿Funciona ON CONFLICT con cualquier índice único?

Funciona con las columnas de un índice único o una restricción, o con ON CONFLICT ON CONSTRAINT name. Necesita PostgreSQL 9.5 o posterior.

Errores relacionados

Más errores de violación de restricciones de integridad

El código y el texto del mensaje son de documentación de PostgreSQL, Apéndice A: Códigos de error de PostgreSQL. Explora la lista completa de Lista de errores de PostgreSQL o buscar cada error de base de datos.

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

Trabajar con PostgreSQL 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 PostgreSQL y las demás bases de datos que uses.