Restricciones UNIQUE en SQLite: columnas, claves compuestas y NULL

UNIQUE significa "no se permiten duplicados"

La restricción UNIQUE en SQLite le indica al motor que los valores de una columna (o de un conjunto de columnas) no pueden repetirse entre filas. Es la forma de decir "dos usuarios no pueden compartir el mismo email" o "un código de producto aparece como mucho una vez".

CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT UNIQUE,
    name  TEXT
);

INSERT INTO users (email, name) VALUES ('ada@example.com', 'Ada');
INSERT INTO users (email, name) VALUES ('boris@example.com', 'Boris');
INSERT INTO users (email, name) VALUES ('ada@example.com', 'Ada Dos');

SELECT * FROM users;

El tercer INSERT falla con UNIQUE constraint failed: users.email. SQLite valida la restricción en cada escritura y rechaza cualquier cosa que genere un duplicado. Las dos primeras filas sí se guardan; la tercera nunca llega a la tabla.

Por dentro, UNIQUE se implementa como un índice único — la misma estructura de datos que SQLite usa para hacer búsquedas rápidas — así que la comprobación es barata y, de paso, la columna queda indexada automáticamente.

Sintaxis a nivel de columna vs a nivel de tabla

Hay dos formas de declarar UNIQUE en SQLite: en línea, junto a la columna, o como una cláusula aparte al final de la definición de la tabla:

-- A nivel de columna: simple, una sola columna.
CREATE TABLE products (
    sku   TEXT UNIQUE,
    name  TEXT
);

-- A nivel de tabla: mismo efecto, diferente ubicación.
CREATE TABLE products2 (
    sku   TEXT,
    name  TEXT,
    UNIQUE(sku)
);

Para una sola columna, ambas formas son equivalentes: usa la que te resulte más legible. La forma a nivel de tabla se vuelve indispensable en cuanto necesitas garantizar unicidad en más de una columna.

UNIQUE en varias columnas: clave única compuesta en SQLite

A veces una columna por sí sola no tiene por qué ser única, pero la combinación de varias sí debe serlo. Un usuario puede matricularse en muchos cursos, y un curso puede tener muchos usuarios, pero el mismo par (user_id, course_id) no debería aparecer dos veces:

CREATE TABLE enrollments (
    id        INTEGER PRIMARY KEY,
    user_id   INTEGER NOT NULL,
    course_id INTEGER NOT NULL,
    UNIQUE(user_id, course_id)
);

INSERT INTO enrollments (user_id, course_id) VALUES (1, 100);
INSERT INTO enrollments (user_id, course_id) VALUES (1, 101);  -- correcto, curso diferente
INSERT INTO enrollments (user_id, course_id) VALUES (2, 100);  -- correcto, usuario diferente
INSERT INTO enrollments (user_id, course_id) VALUES (1, 100);  -- falla: el par ya existe

SELECT * FROM enrollments;

La restricción aplica al par, no a cada columna por separado. El usuario 1 puede inscribirse en muchos cursos y el curso 100 puede tener muchos usuarios; lo único que no se permite es repetir la misma combinación.

Es el patrón clásico para tablas intermedias en relaciones muchos a muchos.

UNIQUE vs PRIMARY KEY en SQLite

Suenan parecido y están relacionadas, pero no son lo mismo:

• Una tabla tiene como mucho una PRIMARY KEY, pero puede tener varias restricciones UNIQUE.
• La PRIMARY KEY es la identidad de la fila: a ella apuntan las claves foráneas y de ella es alias el rowid.
• UNIQUE significa simplemente "este valor (o combinación) no se repite".
• En una tabla normal, una columna UNIQUE sí admite valores NULL; una PRIMARY KEY no (con una excepción histórica que vamos a obviar).

Una forma habitual de usarlas juntas:

CREATE TABLE accounts (
    id       INTEGER PRIMARY KEY,   -- identidad interna, nunca cambia
    email    TEXT NOT NULL UNIQUE,  -- identificador visible para el usuario, debe ser único
    username TEXT NOT NULL UNIQUE   -- otro identificador único
);

id es lo que referencia el resto de la base de datos. email y username son únicos porque la aplicación lo exige, no porque sean la identidad. Si un usuario cambia su correo, el id se mantiene igual: ese es justo el sentido de separarlos.

El detalle con los NULL

Esto pilla a casi todo el mundo la primera vez. Una columna UNIQUE en SQLite acepta tantos valores NULL como quieras:

CREATE TABLE invites (
    id    INTEGER PRIMARY KEY,
    email TEXT UNIQUE
);

INSERT INTO invites (email) VALUES (NULL);
INSERT INTO invites (email) VALUES (NULL);
INSERT INTO invites (email) VALUES (NULL);
INSERT INTO invites (email) VALUES ('ada@example.com');
INSERT INTO invites (email) VALUES ('ada@example.com');  -- este falla

SELECT * FROM invites;

Tres NULL, ningún problema. Dos 'ada@example.com', ahí sí hay conflicto.

¿Por qué? Porque SQL trata a NULL como "desconocido", y dos valores desconocidos no se consideran iguales entre sí. Por eso la verificación de unicidad no los marca como duplicados. Si necesitas que haya como máximo un NULL, lo más limpio es usar NOT NULL UNIQUE. Y si los NULL son válidos pero solo quieres uno por cada combinación de las demás columnas, lo tuyo es un índice único parcial (lo vemos más adelante en el capítulo de índices).

Resolver conflictos con ON CONFLICT

Por defecto, una violación de la restricción UNIQUE aborta la sentencia. Pero a veces te interesa otro comportamiento: reemplazar la fila existente, ignorar la nueva o actualizar ciertas columnas. SQLite te ofrece dos formas de pedirlo.

La primera va incrustada en la propia restricción mediante ON CONFLICT:

CREATE TABLE settings (
    key   TEXT UNIQUE ON CONFLICT REPLACE,
    value TEXT
);

INSERT INTO settings (key, value) VALUES ('theme', 'light');
INSERT INTO settings (key, value) VALUES ('theme', 'dark');   -- reemplaza la primera
INSERT INTO settings (key, value) VALUES ('lang', 'en');

SELECT * FROM settings;

La segunda vez que se inserta theme, la fila existente se elimina y la nueva ocupa su lugar. Otras opciones son IGNORE (lo omite sin avisar), ABORT (la predeterminada), FAIL y ROLLBACK.

La segunda forma se aplica por sentencia, mediante la sintaxis upsert, que suele ser más flexible porque permite actualizar columnas concretas:

CREATE TABLE counters (
    name  TEXT UNIQUE,
    count INTEGER NOT NULL DEFAULT 0
);

INSERT INTO counters (name, count) VALUES ('hits', 1);
INSERT INTO counters (name, count) VALUES ('hits', 1)
    ON CONFLICT(name) DO UPDATE SET count = count + 1;
INSERT INTO counters (name, count) VALUES ('hits', 1)
    ON CONFLICT(name) DO UPDATE SET count = count + 1;

SELECT * FROM counters;

El primer INSERT crea la fila. Los dos siguientes chocan con la restricción UNIQUE y caen en la rama DO UPDATE, que incrementa count. Este es el patrón upsert de INSERT ... ON CONFLICT — más adelante hay una página dedicada solo a este tema.

Restricción UNIQUE vs índice único en SQLite

CREATE UNIQUE INDEX cumple el mismo papel que una restricción UNIQUE. De hecho, cuando defines una restricción UNIQUE, SQLite crea un índice único por debajo: son prácticamente el mismo mecanismo con distinto nombre.

CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT NOT NULL
);

CREATE UNIQUE INDEX idx_users_email ON users(email);

INSERT INTO users (email) VALUES ('ada@example.com');
INSERT INTO users (email) VALUES ('ada@example.com');  -- falla

¿Cuándo conviene usar cada una?

• Restricción cuando la unicidad forma parte de la definición de la tabla. Queda documentada justo al lado de las columnas.
• Índice único cuando necesitas un índice parcial (con cláusula WHERE), quieres ponerle un nombre concreto o añadirlo a una tabla existente sin tener que reescribirla. El ALTER TABLE de SQLite no permite agregar restricciones, pero sí siempre crear un índice.

A la hora de escribir, el comportamiento es idéntico. La elección depende sobre todo de dónde prefieres que viva la regla dentro del esquema.

Añadir UNIQUE a una tabla existente en SQLite

El ALTER TABLE de SQLite es limitado a propósito: no existe ALTER TABLE ... ADD CONSTRAINT. Tienes dos opciones prácticas:

-- Opción 1: añadir un índice único. Funciona en tablas existentes, misma garantía.
CREATE TABLE customers (
    id    INTEGER PRIMARY KEY,
    email TEXT
);

INSERT INTO customers (email) VALUES ('ada@example.com');
INSERT INTO customers (email) VALUES ('boris@example.com');

CREATE UNIQUE INDEX idx_customers_email ON customers(email);

INSERT INTO customers (email) VALUES ('ada@example.com');  -- ahora falla

La opción 2 —cuando lo que quieres de verdad es dejar la cláusula UNIQUE cocida dentro de la definición de la tabla— es el típico baile de reescribir la tabla: creas una tabla nueva con la restricción, copias los datos, eliminas la vieja y renombras. Lo vemos en la siguiente página.

Un aviso: si intentas añadir unicidad sobre una columna que ya contiene duplicados, el CREATE UNIQUE INDEX va a fallar. Primero limpia las filas duplicadas y después crea el índice.

Cuándo falla UNIQUE: cómo leer el error

El mensaje de error te dice exactamente qué restricción se rompió:

Error: UNIQUE constraint failed: users.email
Error: UNIQUE constraint failed: enrollments.user_id, enrollments.course_id

La primera forma es una restricción de una sola columna sobre users.email. La segunda es compuesta: aparecen ambas columnas porque ya existe esa combinación. Cuando veas este error:

1. Localiza qué fila tiene ya el valor en conflicto (SELECT ... WHERE email = '...').
2. Decide si quieres actualizar esa fila, saltarte el insert o usar otro valor.
3. Si los duplicados son esperables y lo que buscas es fusionarlos, usa INSERT ... ON CONFLICT DO UPDATE.

El error salta de forma escandalosa porque la mayoría de las veces te interesa enterarte: un duplicado silencioso sería peor que un INSERT fallido.

Siguiente paso: borrar y modificar tablas

Las restricciones UNIQUE no se pueden añadir a una tabla existente con un simple ALTER TABLE. Esa limitación es la razón por la que SQLite tiene su propio baile para los cambios de esquema —la reescritura de tabla— y de eso va la próxima página, junto con lo básico para eliminar tablas sin dejar restos.