El síntoma: INSERT o UPDATE intenta repetir un valor único
Una restricción UNIQUE expresa que una columna —o una combinación de columnas— no debe repetirse entre filas. PostgreSQL y SQLite documentan que un intento de insertar o actualizar otra fila con la misma clave única produce una violación de la restricción.
El mensaje exacto cambia entre motores, pero la pregunta de diagnóstico es la misma: ¿qué fila ya contiene el valor que intento guardar?
Ejemplo reproducible: el correo ya existe
CREATE TABLE clientes (
id INTEGER PRIMARY KEY,
email TEXT NOT NULL UNIQUE
);
INSERT INTO clientes (id, email)
VALUES (1, 'ana@ejemplo.com');
INSERT INTO clientes (id, email)
VALUES (2, 'ana@ejemplo.com');La segunda fila intenta reutilizar el mismo correo. Si el correo identifica de forma única a un cliente, la restricción está haciendo su trabajo: el problema está en el dato o en la operación, no en UNIQUE.
Busca primero la fila existente
SELECT id, email
FROM clientes
WHERE email = 'ana@ejemplo.com';| id | |
|---|---|
| 1 | ana@ejemplo.com |
Después decide qué intención tenías: actualizar al cliente existente, corregir el correo de la fila nueva o usar otra clave si el dominio permite realmente duplicados. No elimines la restricción solo para hacer desaparecer el error.
No generalices el comportamiento de NULL
Esta guía trata duplicados no nulos. Las reglas de NULL dentro de restricciones únicas no son idénticas en todos los motores. PostgreSQL, por ejemplo, permite por defecto varios valores nulos en una restricción única y ofrece NULLS NOT DISTINCT para cambiar ese comportamiento. SQLite también considera distintos los valores nulos al comprobar UNIQUE. Si tu problema incluye NULL, revisa la documentación del motor y la página de UNIQUE.
Método de diagnóstico
- Identifica la restricción y las columnas que protege.
- Copia el valor rechazado y búscalo con un
SELECT. - Comprueba si el registro ya existe por una operación anterior.
- Decide la intención: crear una fila nueva, actualizar la existente o corregir el dato.
- Mantén la restricción si expresa una regla real del dominio.
Error frecuente: convertir un problema de identidad en un problema de esquema
Quitar UNIQUE no elimina el duplicado lógico
Solo permite almacenarlo. Si dos filas representan al mismo cliente, la base deja de avisarte y el problema pasa a consultas, informes y futuras actualizaciones.
Práctica correctiva
Comprueba qué código ya está ocupado
La tabla productos tiene codigo TEXT UNIQUE y el valor 'P-104' es rechazado al insertar. Escribe la consulta de diagnóstico antes de modificar nada.
Solución razonada
SELECT id, codigo
FROM productos
WHERE codigo = 'P-104';Si devuelve una fila, ya tienes la causa inmediata. A partir de ahí debes decidir si la operación debía actualizar ese producto o usar otro código.
Qué debes recordar
UNIQUEprotege una regla de unicidad.- Busca primero la fila que ya contiene el valor.
- No elimines la restricción para ocultar un duplicado lógico.
- El tratamiento de
NULLpuede variar entre motores.