UNIQUE no SQLite: colunas, chaves compostas e NULL

UNIQUE: nada de valores duplicados

A constraint UNIQUE no SQLite é a forma de avisar ao banco que os valores de uma coluna (ou de um conjunto de colunas) não podem se repetir entre as linhas. É com ela que você garante regras do tipo "dois usuários não podem ter o mesmo e-mail" ou "um código de produto aparece no máximo uma 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 Two');

SELECT * FROM users;

O terceiro INSERT falha com falha na restrição UNIQUE: users.email. O SQLite verifica a restrição a cada escrita e rejeita qualquer coisa que gere duplicata. As duas primeiras linhas são gravadas; a terceira nunca entra.

Nos bastidores, o UNIQUE é implementado como um índice único — a mesma estrutura de dados que o SQLite usa para buscas rápidas — então a checagem sai barato e a coluna já fica indexada automaticamente.

Sintaxe por coluna vs por tabela

Dá para escrever UNIQUE de duas formas: inline, ao lado da coluna, ou como uma cláusula separada no final da definição da tabela:

-- Nível de coluna: simples, uma coluna.
CREATE TABLE products (
    sku   TEXT UNIQUE,
    name  TEXT
);

-- Nível de tabela: mesmo efeito, posicionamento diferente.
CREATE TABLE products2 (
    sku   TEXT,
    name  TEXT,
    UNIQUE(sku)
);

Para uma única coluna, as duas formas são equivalentes — use a que ficar mais legível. Já a versão a nível de tabela vira indispensável no momento em que você precisa garantir unicidade combinando mais de uma coluna.

UNIQUE composto: chave única em múltiplas colunas no SQLite

Tem situações em que nenhuma coluna sozinha é única, mas a combinação delas precisa ser. Um usuário pode se inscrever em vários cursos, e um curso pode ter vários usuários — mas o mesmo par (user_id, course_id) não pode aparecer duas vezes:

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);  -- ok, curso diferente
INSERT INTO enrollments (user_id, course_id) VALUES (2, 100);  -- ok, usuário diferente
INSERT INTO enrollments (user_id, course_id) VALUES (1, 100);  -- falha: o par já existe

SELECT * FROM enrollments;

A constraint vale para o par, não para nenhuma das colunas isoladamente. O usuário 1 pode se matricular em vários cursos, o curso 100 pode ter vários usuários — só não pode repetir a mesma combinação.

Esse é o padrão clássico para tabelas de junção em relacionamentos muitos-para-muitos.

UNIQUE vs PRIMARY KEY no SQLite

Os nomes parecem próximos e os conceitos têm a ver, mas não são a mesma coisa:

• Cada tabela tem no máximo uma PRIMARY KEY, mas pode ter várias constraints UNIQUE.
• A PRIMARY KEY é a identidade da linha — é para ela que as foreign keys apontam, e é dela que o rowid vira apelido.
• Já o UNIQUE só diz "esse valor (ou combinação) não se repete".
• Em uma tabela comum, uma coluna UNIQUE aceita valores NULL; uma PRIMARY KEY não (existe uma exceção histórica que vamos deixar de lado).

Um formato bem comum:

CREATE TABLE accounts (
    id       INTEGER PRIMARY KEY,   -- identidade interna, nunca muda
    email    TEXT NOT NULL UNIQUE,  -- identificador visível ao usuário, deve ser único
    username TEXT NOT NULL UNIQUE   -- outro identificador único
);

id é o que o resto do banco referencia. Já email e username são únicos porque a aplicação exige isso, não porque sejam a identidade. Se o usuário trocar de e-mail, o id continua o mesmo — é justamente para isso que separamos os dois.

A pegadinha do NULL

Essa aqui pega quase todo mundo de primeira viagem. Uma coluna UNIQUE no SQLite aceita quantos valores NULL você quiser:

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');  -- esta falha

SELECT * FROM invites;

Três NULLs, sem problema. Dois 'ada@example.com', aí sim temos conflito.

O motivo: o SQL trata NULL como "desconhecido", e dois valores desconhecidos não são considerados iguais — então a checagem de unicidade não tem como afirmar que são duplicados. Se você precisa permitir no máximo um NULL, a solução mais limpa é NOT NULL UNIQUE. Se NULLs são válidos mas você quer apenas um por combinação das outras colunas, parta para um índice único parcial (assunto do capítulo de índices, mais adiante).

Lidando com conflitos: ON CONFLICT

Por padrão, uma violação de UNIQUE aborta o comando. Mas, em algumas situações, você quer um comportamento diferente — substituir a linha existente, ignorar a nova ou atualizar colunas específicas. O SQLite oferece duas formas de pedir isso.

A primeira fica embutida na própria constraint, com 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');   -- substitui o primeiro
INSERT INTO settings (key, value) VALUES ('lang', 'en');

SELECT * FROM settings;

Na segunda vez que theme é inserido, a linha existente é apagada e a nova ocupa o lugar dela. Outras opções são IGNORE (ignora silenciosamente), ABORT (o padrão), FAIL e ROLLBACK.

A segunda forma é definida por instrução, usando a sintaxe de upsert — geralmente mais flexível, já que permite atualizar colunas específicas:

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;

O primeiro INSERT cria a linha. Os dois seguintes esbarram na constraint UNIQUE e caem no ramo DO UPDATE, incrementando count. Esse é o padrão de upsert com INSERT ... ON CONFLICT — tem uma página dedicada a ele mais adiante.

UNIQUE constraint vs índice único no SQLite

O CREATE UNIQUE INDEX faz o mesmo trabalho que uma constraint UNIQUE. Aliás, quando você declara uma constraint UNIQUE, o SQLite cria um índice único nos bastidores — é praticamente o mesmo mecanismo usando chapéus diferentes.

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');  -- falha

Quando usar cada um:

• Constraint quando a unicidade faz parte da definição da tabela. Fica documentada ali, ao lado das colunas.
• Índice único quando você precisa de um índice parcial (com cláusula WHERE), quer dar um nome específico ao índice, ou precisa adicioná-lo a uma tabela já existente sem ter que recriá-la. O ALTER TABLE do SQLite não consegue adicionar uma constraint, mas sempre dá pra criar um índice depois.

Na hora da escrita, o comportamento é idêntico. A escolha é mais sobre onde você quer que a regra fique declarada no schema.

Adicionando UNIQUE a uma tabela existente

O ALTER TABLE do SQLite é propositalmente limitado — não existe ALTER TABLE ... ADD CONSTRAINT. As duas saídas práticas são:

-- Opção 1: adicionar um índice único. Funciona em tabelas existentes, mesma aplicação.
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');  -- agora falha

A Opção 2 — quando você realmente quer ter a cláusula UNIQUE cravada na definição da tabela — exige aquela dança de recriar a tabela: cria uma nova com a constraint, copia os dados, dropa a antiga e renomeia. Isso a gente vê na próxima página.

Um aviso importante: se você está aplicando unicidade numa coluna que já tem valores duplicados, o CREATE UNIQUE INDEX vai falhar. Limpe os registros duplicados primeiro e só depois crie o índice.

Quando o UNIQUE falha: entendendo o erro

A mensagem de erro mostra exatamente qual constraint estourou:

Erro: falha na restrição UNIQUE: users.email
Erro: falha na restrição UNIQUE: enrollments.user_id, enrollments.course_id

A primeira forma é uma restrição em uma única coluna sobre users.email. A segunda é composta — as duas colunas aparecem juntas porque é a combinação delas que já existe. Quando você se deparar com esse erro:

1. Descubra qual linha já tem o valor em conflito (SELECT ... WHERE email = '...').
2. Decida se vai atualizar essa linha, pular o insert ou usar um valor diferente.
3. Se duplicatas são esperadas e a ideia é mesclá-las, troque para INSERT ... ON CONFLICT DO UPDATE.

O erro é barulhento de propósito: na maioria das vezes você realmente quer saber. Duplicatas silenciosas seriam bem piores do que uma gravação que falha na sua cara.

A seguir: removendo e alterando tabelas

Restrições UNIQUE não podem ser adicionadas a uma tabela já existente com um simples ALTER TABLE. É justamente por causa dessa limitação que o SQLite tem aquela coreografia específica para mudanças de schema — a reescrita da tabela —, e esse é o assunto da próxima página, junto com o básico de como remover tabelas sem deixar lixo para trás.