Vincoli CHECK in SQLite: validare i dati a livello di tabella

Un vincolo CHECK è una regola che ogni riga deve rispettare

Un vincolo CHECK è un'espressione booleana che associ a una tabella. SQLite la valuta a ogni INSERT e UPDATE, e se l'espressione risulta falsa l'operazione fallisce. È un modo per incorporare una regola di business, "il prezzo non può essere negativo", "lo stato deve essere uno di questi tre valori", direttamente nello schema.

CREATE TABLE products (
    id    INTEGER PRIMARY KEY,
    name  TEXT NOT NULL,
    price REAL NOT NULL CHECK (price >= 0)
);

INSERT INTO products (name, price) VALUES ('Notebook', 4.50);
INSERT INTO products (name, price) VALUES ('Free sample', 0);
INSERT INTO products (name, price) VALUES ('Bug', -1);

SELECT * FROM products;

Le prime due righe vengono inserite. La terza solleva CHECK constraint failed e viene rifiutata: la tabella non la vede mai. Il vincolo impone la regola a chiunque scriva, che sia la tua app, uno script di migrazione o qualcuno che sta curiosando nella CLI.

A livello di colonna contro a livello di tabella

Puoi scrivere un CHECK in due punti: dopo la definizione di una colonna (a livello di colonna) o dopo tutte le colonne (a livello di tabella). Si comportano allo stesso modo; la differenza è in cosa si legge in modo più naturale.

-- A livello di colonna: regola su una sola colonna.
CREATE TABLE accounts (
    id      INTEGER PRIMARY KEY,
    balance REAL CHECK (balance >= 0)
);

-- A livello di tabella: regola che coinvolge più colonne.
CREATE TABLE bookings (
    id         INTEGER PRIMARY KEY,
    start_date TEXT NOT NULL,
    end_date   TEXT NOT NULL,
    CHECK (start_date <= end_date)
);

INSERT INTO bookings (start_date, end_date) VALUES ('2026-01-10', '2026-01-15');
INSERT INTO bookings (start_date, end_date) VALUES ('2026-02-01', '2026-01-31');

La prima prenotazione viene inserita. La seconda fallisce: la fine è prima dell'inizio. Le regole su una sola colonna si leggono meglio a livello di colonna; tutto ciò che confronta due o più colonne si legge meglio a livello di tabella.

Limitare i valori a un elenco

Un uso comune è costringere una colonna a uno di un insieme fisso di valori. SQLite non ha un tipo enum nativo, quindi l'idioma è CHECK ... IN (...):

CREATE TABLE tickets (
    id     INTEGER PRIMARY KEY,
    title  TEXT NOT NULL,
    status TEXT NOT NULL CHECK (status IN ('open', 'in_progress', 'closed'))
);

INSERT INTO tickets (title, status) VALUES ('Login broken', 'open');
INSERT INTO tickets (title, status) VALUES ('Typo in footer', 'closed');
INSERT INTO tickets (title, status) VALUES ('Mystery', 'pending');

La terza riga fallisce: 'pending' non è nell'elenco dei valori ammessi. Se un giorno dovrai aggiungere un nuovo stato, dovrai ricostruire la tabella (ne parliamo più sotto), quindi pensaci un attimo prima di bloccare l'elenco. Ma per vocabolari davvero fissi, come nomi di ruoli o stati degli ordini, è esattamente il vincolo che ti serve.

Dare un nome ai vincoli

Di default un vincolo è anonimo. Il messaggio di errore dice solo "CHECK constraint failed" con l'espressione, che va bene quando sulla tabella c'è un solo CHECK, ma confonde quando ce ne sono cinque. Aggiungi un nome con CONSTRAINT:

CREATE TABLE employees (
    id       INTEGER PRIMARY KEY,
    name     TEXT NOT NULL,
    salary   REAL NOT NULL,
    bonus    REAL NOT NULL DEFAULT 0,
    CONSTRAINT salary_positive CHECK (salary > 0),
    CONSTRAINT bonus_not_negative CHECK (bonus >= 0),
    CONSTRAINT bonus_not_huge CHECK (bonus <= salary)
);

INSERT INTO employees (name, salary, bonus) VALUES ('Ada', 60000, 70000);

Ora il messaggio di errore include il nome del vincolo, così sai subito quale regola è stata violata. Dare un nome costa qualche carattere in più e si ripaga la prima volta che qualcosa si rompe in produzione.

CHECK e NULL: l'insidia

CHECK passa quando l'espressione è vera oppure NULL. Fallisce solo con un falso esplicito. Sembra strano, finché non ricordi che quasi ogni confronto con NULL restituisce NULL, non vero o falso.

CREATE TABLE people (
    id  INTEGER PRIMARY KEY,
    age INTEGER CHECK (age >= 0)
);

INSERT INTO people (age) VALUES (25);
INSERT INTO people (age) VALUES (NULL);
INSERT INTO people (age) VALUES (-5);

SELECT * FROM people;

La riga con NULL viene inserita senza problemi: NULL >= 0 è NULL, non falso, quindi il CHECK non fallisce. Se vuoi davvero vietare sia i numeri negativi sia i valori mancanti, combina NOT NULL con il CHECK:

CREATE TABLE people (
    id  INTEGER PRIMARY KEY,
    age INTEGER NOT NULL CHECK (age >= 0)
);

INSERT INTO people (age) VALUES (NULL);

Ora l'insert fallisce sul vincolo NOT NULL prima ancora che venga eseguito il CHECK. I due vincoli lavorano insieme: NOT NULL copre l'assenza, CHECK copre la forma.

Funzioni integrate utili dentro CHECK

L'espressione può usare la maggior parte delle funzioni integrate di SQLite. Alcune capitano spesso:

CREATE TABLE users (
    id       INTEGER PRIMARY KEY,
    email    TEXT NOT NULL CHECK (email LIKE '%_@_%.__%'),
    username TEXT NOT NULL CHECK (length(username) BETWEEN 3 AND 20),
    country  TEXT NOT NULL CHECK (country = upper(country))
);

INSERT INTO users (email, username, country) VALUES ('ada@example.com', 'ada', 'US');
INSERT INTO users (email, username, country) VALUES ('not-an-email', 'ada2', 'US');
INSERT INTO users (email, username, country) VALUES ('boris@x.io', 'b', 'US');
INSERT INTO users (email, username, country) VALUES ('cara@x.io', 'cara', 'us');

Tre fallimenti: un'email con una forma sbagliata, uno username troppo corto e un codice paese in minuscolo. LIKE gestisce i pattern semplici; length(), upper(), lower() e l'aritmetica sono tutti ammessi. Tieni però l'espressione deterministica: usare qualcosa come random() o current_timestamp dentro un CHECK crea regole che possono cambiare da una riga all'altra, e raramente è quello che vuoi.

CHECK contro trigger

Sia CHECK sia i trigger possono rifiutare dati sbagliati, e chi inizia si chiede spesso quale usare. La regola pratica:

• CHECK quando la regola dipende solo dalla riga che stai scrivendo. "Questa colonna confrontata con quella", "questo valore dentro un intervallo", "questa stringa corrisponde a un pattern".
• Trigger (nello specifico un trigger BEFORE INSERT/UPDATE che chiama RAISE) quando la regola dipende da altre righe, da altre tabelle o deve fare qualcosa di più complesso di una singola espressione booleana.

CHECK è più veloce, più semplice e visibile nello schema: chiunque legga il CREATE TABLE vede la regola. Ricorri a un trigger solo quando CHECK non riesce a esprimere ciò che ti serve.

Non puoi eliminare un CHECK con ALTER

Questo è l'unico punto spigoloso. SQLite non ha ALTER TABLE ... DROP CONSTRAINT. Per rimuovere o cambiare un CHECK, ricostruisci la tabella:

BEGIN;

CREATE TABLE products_new (
    id    INTEGER PRIMARY KEY,
    name  TEXT NOT NULL,
    price REAL NOT NULL CHECK (price >= 0 AND price <= 1000000)
);

INSERT INTO products_new SELECT * FROM products;
DROP TABLE products;
ALTER TABLE products_new RENAME TO products;

COMMIT;

Racchiudi tutto in una transazione, così un errore a metà lascia il database com'era. Se altre tabelle hanno chiavi esterne che puntano alla tabella che stai ricostruendo, il procedimento si allunga: disattivi foreign_keys, ricostruisci, riattivi, ricontrolli. Lo vedremo nella guida sulle migrazioni più avanti nel percorso.

Prossimo passo: vincoli UNIQUE

CHECK valida la forma dei valori dentro una riga. Il prossimo vincolo, UNIQUE, valida le relazioni tra righe: garantisce che due righe non abbiano lo stesso valore in una colonna o in un insieme di colonne. È il prossimo argomento.