Gli attributi
Cosa sai di ognuna delle tue cose
- 15 minuti di lettura
Nives Corti, all'ufficio oggetti smarriti di Porta Codice, ha un'altra domanda. Hai già deciso che l'app Ritrovato ricorda quattro cose: stazioni, oggetti, addetti, restituzioni (le entità). Ora Nives chiede: «Per ogni oggetto, cosa scrivo?».
Nel canvas la risposta sta nel riquadro 6, accanto a ogni cosa: gli oggetti trovati: cos'è, la categoria, il colore, un segno particolare, dove, quando, a che punto è. Sono parole di Nives, non ancora colonne. Questo capitolo le trasforma in attributi: nomi, tipi, regole. Alla fine hai lo schema.sql di Ritrovato.
Le basi le hai già: i tipi in Tabelle, tipi e psql, i vincoli in Scrivere, il disegno completo in Disegnare un database. Qui non le ripeto: ti dico come scegliere, attributo per attributo, e quali errori si fanno di più.
Da dove vengono gli attributi
Non si inventano: si leggono. Gli attributi stanno in due posti del canvas.
- Nelle schermate (riquadro 5): cosa mostro, cosa filtro, cosa ordino.
- Nelle azioni (riquadro 7): cosa scrivo, cosa controllo.
Prendi la scheda di un oggetto e l'elenco con i filtri. Per ogni schermata, una riga:
| Schermata o azione | Usa questi attributi dell'oggetto |
|---|---|
| L'elenco (mostro) | descrizione, categoria, colore, trovato_il |
| L'elenco (filtro) | stazione_id, categoria, trovato_il |
| L'elenco (ordino) | trovato_il, il più recente per primo |
| La scheda (mostro) | descrizione, categoria, colore, stazione_id, trovato_il, stato |
| «Registro» (scrivo) | descrizione, categoria, colore, segno_particolare, stazione_id, trovato_il, registrato_da |
| «Restituisco» (scrivo) | stato |
| «Restituisco» (controllo) | segno_particolare: l'addetto lo confronta con quello che dice chi chiede l'oggetto |
Nota la scheda: non mostra il segno particolare, perché è la prova che chi chiede l'oggetto sia il proprietario. Lo usa solo l'azione di restituzione. Un attributo può servire a una sola azione, ed è giusto così.
La prova al contrario
Ora il test che toglie le cose inutili. Nives, entusiasta, propone: «Segniamo anche il peso dell'oggetto, e il numero dello scatolone!». Per ognuno chiediti: quale schermata lo mostra? quale azione lo scrive o lo controlla?
| Attributo proposto | Chi lo usa | Verdetto |
|---|---|---|
| il peso | nessuna schermata, nessuna azione | fuori |
| il numero dello scatolone | nessuna schermata (oggi, con il database, l'oggetto si trova cercando) | fuori |
| il colore | l'elenco, la scheda, la registrazione | dentro |
Un attributo che nessuna schermata e nessuna azione usa, non serve. Ogni colonna in più è un campo da compilare in più, e qualcuno prima o poi smette di compilarlo. Se un giorno servirà, lo aggiungi: aggiungere una colonna costa poco.
Le cinque decisioni
Per ogni attributo che hai trovato, cinque domande, sempre nello stesso ordine.
| # | Decisione | La domanda | In SQL |
|---|---|---|---|
| 1 | Il nome | Come lo chiamo? | il nome della colonna |
| 2 | Il tipo | Che genere di dato è? | TEXT, INTEGER, NUMERIC(8,2), DATE, TIMESTAMP, BOOLEAN |
| 3 | Obbligatorio o facoltativo | L'app può funzionare senza? | NOT NULL, oppure niente |
| 4 | Unico | Possono esserci due uguali? | UNIQUE |
| 5 | I valori ammessi | Quali valori sono sbagliati? E se non c'è, cosa vale? | CHECK, DEFAULT |
1. Il nome
Le regole sono quelle di Disegnare un database: minuscolo, parole con _, niente accenti, la chiave esterna è <cosa>_id, le date finiscono in _il. Qui aggiungo una cosa sola: il tipo non va nel nome.
| Evita | Scrivi | Perché |
|---|---|---|
descrizione_testo | descrizione | il tipo lo dice già la colonna |
data_trovato | trovato_il | il suffisso _il dice già che è una data |
colore_stringa | colore | come sopra |
L'unità di misura, invece, nel nome ci va: peso_kg, ritardo_min. Non è il tipo (che sarebbe NUMERIC): è quello che serve a chi legge per capire cosa sta guardando.
2. Il tipo
Il tipo dice cosa può contenere la colonna, e PostgreSQL controlla per te.
| Quando il dato è… | Tipo | Esempio di Ritrovato |
|---|---|---|
| un testo, anche breve | TEXT | descrizione, colore |
| un numero intero che si conta o si somma | INTEGER | stazione_id |
| dei soldi | NUMERIC(8,2) | il prezzo di un biglietto |
| un giorno | DATE | trovato_il |
| un giorno e un'ora | TIMESTAMP | l'ora di una prenotazione |
| sì o no | BOOLEAN | fuori_uso |
Le due scelte dove si sbaglia sono queste.
I soldi mai in virgola mobile. REAL e DOUBLE PRECISION sono numeri approssimati. Guarda:
SELECT 0.1::float8 + 0.2::float8 AS in_virgola_mobile, 0.1::numeric + 0.2::numeric AS numeric; in_virgola_mobile | numeric
---------------------+---------
0.30000000000000004 | 0.3
(1 row)Su un incasso di mille righe quei decimali di troppo si sommano. NUMERIC(8,2) vuol dire: al massimo otto cifre in tutto, due dopo la virgola, senza approssimazioni.
I «numeri» che non sono numeri. Un numero di telefono, un CAP, il codice di un ombrello: non ci fai mai somme, e i primi zeri contano. Sono testi.
SELECT '00100'::text AS testo, '00100'::integer AS numero; testo | numero
-------+--------
00100 | 100
(1 row)La domanda per decidere: «ci faccio dei conti?». Se la risposta è no (nemmeno una somma, nemmeno un confronto «maggiore di»), è un TEXT.
Un'ultima scelta: DATE o TIMESTAMP? Dipende da cosa serve a chi legge. Nives vuole sapere in che giorno è stato trovato un ombrello, non a che minuto: trovato_il è un DATE. Un'app che prenota sale riunioni ha bisogno dell'ora: lì serve un TIMESTAMP.
3. Obbligatorio o facoltativo
Ogni colonna ha due strade: NOT NULL, il valore deve esserci sempre; oppure niente, e la colonna può restare vuota. Il vuoto in SQL si chiama NULL e vuol dire «non c'è, o non lo so».
Domanda: l'app può funzionare senza questo dato?
descrizione: senza, l'elenco mostra una riga vuota. Obbligatorio.trovato_il: senza, non si può ordinare né calcolare da quanto è in deposito. Obbligatorio.colore: le chiavi non hanno un colore che conta. Facoltativo.segno_particolare: non tutti gli oggetti ne hanno uno. Facoltativo.
La regola pratica: parti da NOT NULL e togli solo dove un dato può davvero mancare. Un NOT NULL di troppo ti avvisa subito (non riesci a salvare); un NULL di troppo ti avvisa mesi dopo, con le query che sbagliano.
Perché NULL è insidioso? Perché non è mai «uguale» né «diverso» da niente. Cerca gli oggetti che non sono blu (a Ritrovato c'è anche un mazzo di chiavi senza colore):
SELECT descrizione, colore FROM oggetti WHERE colore <> 'blu' ORDER BY id; descrizione | colore
--------------------+--------
Sciarpa di lana | rosso
Telefono con cover | nero
(2 rows)Le chiavi non compaiono: «senza colore» non è «non blu», per PostgreSQL è «non lo so». Per trovarle serve IS NULL (lo sai da Leggere):
SELECT descrizione, colore FROM oggetti WHERE colore <> 'blu' OR colore IS NULL ORDER BY id; descrizione | colore
--------------------+--------
Mazzo di chiavi |
Sciarpa di lana | rosso
Telefono con cover | nero
(3 rows)Per questo i facoltativi si decidono uno per uno, e ci si chiede cosa vuol dire il vuoto. Se non sai rispondere («colore vuoto vuol dire…?»), non è facoltativo: è obbligatorio, e ti serve una parola come «nessuno».
4. Unico
UNIQUE dice: due righe non possono avere lo stesso valore in questa colonna. La domanda è: se ne trovo due uguali, è un errore o è normale?
| Attributo | Due uguali sono… | Scelta |
|---|---|---|
stazioni.nome | un errore: una stazione sola si chiama così | UNIQUE |
addetti.email | un errore: con quell'email si fa il login | UNIQUE |
oggetti.descrizione | normale: dieci ombrelli neri | niente |
oggetti.colore | normale, ovvio | niente |
INSERT INTO addetti (nome, email, password_hash) VALUES ('Altra Nives', 'nives@lineamenta.example', 'x');ERROR: duplicate key value violates unique constraint "addetti_email_key"
DETAIL: Key (email)=(nives@lineamenta.example) already exists.Una cosa da sapere: UNIQUE lascia passare più NULL, perché due «non lo so» non sono due valori uguali. Un attributo facoltativo e unico (per esempio il numero del microchip di un animale) può quindi mancare in tante righe.
5. I valori ammessi
Ultima domanda: cosa non deve mai entrare? Due strumenti.
CHECK: la regola che il valore deve rispettare. Il caso tipico è la lista fissa di parole del capitolo sulle entità: le categorie di Ritrovato sono sei, e solo quelle.
INSERT INTO oggetti (descrizione, categoria, stazione_id, trovato_il, registrato_da)
VALUES ('Ombrello nero', 'ombrello', 1, '2026-11-19', 1);ERROR: new row for relation "oggetti" violates check constraint "oggetti_categoria_check"
DETAIL: Failing row contains (6, Ombrello nero, ombrello, null, null, 1, 2026-11-19, in deposito, 1).«ombrello» al singolare non è «ombrelli»: senza il CHECK sarebbe entrato lo stesso, e il filtro per categoria avrebbe cercato di trovarlo per sempre. Il CHECK serve anche per i numeri («ore maggiore di zero») e per le lunghezze («quattro caratteri esatti»).
DEFAULT: il valore che la colonna prende se non lo scrivi. Un oggetto appena registrato è sempre «in deposito»: stato ha DEFAULT 'in deposito', e chi registra non deve pensarci.
INSERT INTO oggetti (descrizione, categoria, stazione_id, trovato_il, registrato_da)
VALUES (NULL, 'altro', 1, '2026-11-19', 1);ERROR: null value in column "descrizione" of relation "oggetti" violates not-null constraint
DETAIL: Failing row contains (7, null, altro, null, null, 1, 2026-11-19, in deposito, 1).Guarda l'ultima riga di tutti e due gli errori: stato ha già il suo valore, in deposito, scritto dal DEFAULT. E nota il primo numero, 6 e poi 7: l'id si dà da solo, anche per le righe rifiutate. Gli id non si prevedono.
Il foglio degli attributi
Le cinque decisioni, per tutti gli attributi di una cosa, stanno bene su un foglio solo. Ecco gli oggetti di Ritrovato:
| Attributo | Tipo | Facoltativo? | Unico? | Valori e DEFAULT |
|---|---|---|---|---|
descrizione | TEXT | no | no | |
categoria | TEXT | no | no | CHECK: sei parole |
colore | TEXT | sì | no | |
segno_particolare | TEXT | sì | no | |
stazione_id | INTEGER | no | no | REFERENCES stazioni(id) |
trovato_il | DATE | no | no | |
stato | TEXT | no | no | CHECK: tre parole; DEFAULT 'in deposito' |
registrato_da | INTEGER | no | no | REFERENCES addetti(id) |
E id, che manca nell'elenco perché c'è sempre: SERIAL PRIMARY KEY. Questo foglio è il CREATE TABLE: lo vedi tra poco. Prima, le tre trappole.
Le tre trappole
Calcolato o salvato
Il canvas di Ritrovato dice: «dopo sessanta giorni gli oggetti non ritirati vanno in beneficenza». Quindi la scheda vuole mostrare da quanti giorni è in deposito, e l'ufficio vuole sapere quali sono da donare. Viene voglia di scrivere due colonne: giorni_in_deposito e da_donare.
Guarda cosa succede alla prima. Lo zaino viene registrato il 10 settembre, con zero giorni:
CREATE TABLE oggetti_sbagliati (descrizione TEXT, trovato_il DATE, giorni_in_deposito INTEGER);
INSERT INTO oggetti_sbagliati VALUES ('Zaino', '2026-09-10', 0);
SELECT descrizione, giorni_in_deposito AS salvato, DATE '2026-11-19' - trovato_il AS vero FROM oggetti_sbagliati; descrizione | salvato | vero
-------------+---------+------
Zaino | 0 | 70
(1 row)Il 19 novembre lo zaino è in deposito da settanta giorni, ma la colonna dice ancora zero. Qualcuno dovrebbe aggiornarla ogni notte, e se si dimentica è sbagliata senza dare nessun errore.
La regola: se un dato si può calcolare dagli altri, non si salva. Si ricalcola ogni volta che serve, ed è sempre giusto. Tutti e due i dati di Ritrovato si calcolano dalla data in cui l'oggetto è stato trovato:
SELECT descrizione, trovato_il FROM oggetti
WHERE stato = 'in deposito' AND DATE '2026-11-19' - trovato_il > 60; descrizione | trovato_il
-------------+------------
Zaino | 2026-09-10
(1 row)(Nell'app, al posto di DATE '2026-11-19' ci sarà la data di oggi, CURRENT_DATE.) Ecco la lista di quello che non si salva: l'età (si calcola dalla data di nascita), «in ritardo» (da una data di scadenza e da oggi), un totale (dalle righe che lo compongono), un conteggio.
C'è un'eccezione, e la conosci già: la fotografia. Il prezzo pagato da un cliente non è «il prezzo di listino di oggi», è un fatto storico, e si salva (la spiegazione completa è in SQL, capitolo Disegnare un database). La domanda che distingue i due casi: «se domani cambia l'originale, questo dato deve cambiare?». I giorni in deposito: sì, devono cambiare, quindi si calcolano. Il prezzo pagato: no, quindi si salva.
Non salvare quello che non serve
Alla restituzione Nives deve controllare che chi chiede l'oggetto sia il proprietario. Viene spontaneo scrivere il documento d'identità. Ma ti serve davvero tutto? Il canvas dice a cosa serve: a riconoscere il passeggero se torna. Bastano le ultime quattro cifre.
INSERT INTO restituzioni (oggetto_id, nome_passeggero, documento_finale, restituito_il, addetto_id)
VALUES (1, 'Elena Marchi', 'AX1234567', '2026-11-19', 1);ERROR: new row for relation "restituzioni" violates check constraint "restituzioni_documento_finale_check"
DETAIL: Failing row contains (1, 1, Elena Marchi, AX1234567, 2026-11-19, 1).Il CHECK (length(documento_finale) = 4) rifiuta il documento intero: l'app non è nemmeno capace di conservarlo. Se un giorno qualcuno entra nel database, trova quattro cifre, non un documento.
Lo stesso vale per la password dell'addetto: non si salva la password, si salva la sua impronta (password_hash). Come si calcola e perché lo spiega il libro del login, nel capitolo Le password: qui ti basta il nome della colonna.
Prima di aggiungere un attributo sensibile, due domande: a chi serve? (la prova al contrario) e cosa succede se finisce in mani sbagliate? Meno dati tieni, meno ne puoi perdere.
Una lista dentro una colonna
Nives dice: «Alcuni oggetti hanno più di un segno: un graffio, un adesivo, un nastro». Viene voglia di scrivere segno_particolare = 'graffio, adesivo, nastro'. È la trappola più vecchia del libro di SQL: una casella contiene un valore solo, e una lista è un'altra tabella (la dimostrazione è in Disegnare un database).
Per Ritrovato la risposta è più semplice: bastano pochi segni, e quello che serve è confrontarli a voce. segno_particolare resta un testo libero («manico con nastro giallo»), e la scelta si scrive nel canvas. Se la ricerca dovesse distinguere i segni uno per uno, nascerebbe una tabella segni, con un oggetto e un segno per riga.
La domanda che scopre la lista: «ne ha uno o tanti?». Se tanti, e ti serve contarli o cercarli uno per uno, è un'altra tabella. E non rimediare con segno1, segno2, segno3: sono la stessa lista, solo scritta male.
Lo schema.sql di Ritrovato
Ecco tutto insieme. Le quattro cose del capitolo precedente, con gli attributi che hai deciso. Questo è il file schema.sql, nella cartella del progetto.
CREATE TABLE stazioni (
id SERIAL PRIMARY KEY,
nome TEXT NOT NULL UNIQUE
);
CREATE TABLE addetti (
id SERIAL PRIMARY KEY,
nome TEXT NOT NULL,
email TEXT NOT NULL UNIQUE,
password_hash TEXT NOT NULL
);
CREATE TABLE oggetti (
id SERIAL PRIMARY KEY,
descrizione TEXT NOT NULL,
categoria TEXT NOT NULL CHECK (categoria IN ('ombrelli', 'borse', 'telefoni', 'chiavi', 'abbigliamento', 'altro')),
colore TEXT,
segno_particolare TEXT,
stazione_id INTEGER NOT NULL REFERENCES stazioni(id),
trovato_il DATE NOT NULL,
stato TEXT NOT NULL DEFAULT 'in deposito' CHECK (stato IN ('in deposito', 'restituito', 'donato')),
registrato_da INTEGER NOT NULL REFERENCES addetti(id)
);
CREATE TABLE restituzioni (
id SERIAL PRIMARY KEY,
oggetto_id INTEGER NOT NULL UNIQUE REFERENCES oggetti(id),
nome_passeggero TEXT NOT NULL,
documento_finale TEXT NOT NULL CHECK (length(documento_finale) = 4),
restituito_il DATE NOT NULL,
addetto_id INTEGER NOT NULL REFERENCES addetti(id)
);Lo carichi in un database vuoto con createdb ritrovato e psql -d ritrovato -f schema.sql. Poi \d oggetti ti mostra com'è venuto:
Table "public.oggetti"
Column | Type | Collation | Nullable | Default
-------------------+---------+-----------+----------+-------------------------------------
id | integer | | not null | nextval('oggetti_id_seq'::regclass)
descrizione | text | | not null |
categoria | text | | not null |
colore | text | | |
segno_particolare | text | | |
stazione_id | integer | | not null |
trovato_il | date | | not null |
stato | text | | not null | 'in deposito'::text
registrato_da | integer | | not null |
Indexes:
"oggetti_pkey" PRIMARY KEY, btree (id)
Check constraints:
"oggetti_categoria_check" CHECK (categoria = ANY (ARRAY['ombrelli'::text, 'borse'::text, 'telefoni'::text, 'chiavi'::text, 'abbigliamento'::text, 'altro'::text]))
"oggetti_stato_check" CHECK (stato = ANY (ARRAY['in deposito'::text, 'restituito'::text, 'donato'::text]))
Foreign-key constraints:
"oggetti_registrato_da_fkey" FOREIGN KEY (registrato_da) REFERENCES addetti(id)
"oggetti_stazione_id_fkey" FOREIGN KEY (stazione_id) REFERENCES stazioni(id)
Referenced by:
TABLE "restituzioni" CONSTRAINT "restituzioni_oggetto_id_fkey" FOREIGN KEY (oggetto_id) REFERENCES oggetti(id)Le scelte da rileggere, una per una:
| Dove | La scelta | Perché |
|---|---|---|
oggetti.colore, oggetti.segno_particolare | facoltativi: gli unici due senza NOT NULL | le chiavi non hanno un colore che conta; non tutti gli oggetti hanno un segno |
oggetti.categoria, oggetti.stato | CHECK ... IN (...) | liste fisse di parole, che non cambiano spesso e non hanno dati propri |
oggetti.stato | DEFAULT 'in deposito' | un oggetto appena registrato è sempre in deposito |
oggetti.trovato_il | DATE, non TIMESTAMP | a Nives serve il giorno, non il minuto |
(non c'è) giorni_in_deposito, da_donare | calcolati da trovato_il e da oggi | salvati sarebbero sbagliati già domani |
restituzioni.documento_finale | quattro caratteri, CHECK | del documento bastano le ultime quattro cifre |
addetti.password_hash | l'impronta, mai la password | le password |
restituzioni.oggetto_id | UNIQUE | un oggetto si restituisce una volta sola |
Nel capitolo dopo, La cartella del progetto, ogni riga di questo file diventa una riga di modelli.py: per esempio descrizione TEXT NOT NULL diventa descrizione: Mapped[str], e colore TEXT diventa colore: Mapped[str | None] (la tabella di traduzione è in Database nell'API). Se qui hai deciso bene il NOT NULL, là non hai niente da pensare.
Le sei domande per rileggere
Prima delle dieci domande di Disegnare un database, sei domande solo sugli attributi. Falle a un compagno che ha il tuo schema davanti, tabella per tabella:
- Ogni colonna è usata da una schermata o da un'azione? (la prova al contrario)
- Il nome è minuscolo, senza il tipo dentro, con
_ilper le date e_idper le frecce? - Ogni
NULLha un significato che sai dire a parole? Gli altri sonoNOT NULL? - Ogni soldo è
NUMERIC, ogni data èDATEoTIMESTAMP, ogni «numero» di telefono o CAP è un testo? - C'è una colonna che si può calcolare da altre (un'età, un conteggio, un «in ritardo»)? Se sì, toglila, a meno che sia una fotografia.
- C'è un dato sensibile che non serve (un documento intero, una password in chiaro)?
Ricorda
- Gli attributi si leggono dalle schermate (cosa mostro, filtro, ordino) e dalle azioni (cosa scrivo, controllo). Un attributo che nessuna schermata e nessuna azione usa, non serve.
- Cinque decisioni per ogni attributo: il nome (senza il tipo dentro), il tipo, obbligatorio o facoltativo, unico, i valori ammessi (
CHECK,DEFAULT). - I soldi sono
NUMERIC(8,2), maiREAL. Un numero con cui non fai conti (telefono, CAP) è unTEXT. - Parti da
NOT NULL: il facoltativo si sceglie, e si deve sapere cosa vuol dire il vuoto.NULLnon è mai uguale a niente, nemmeno a<>. - Se un dato si può calcolare, non si salva: i giorni in deposito, l'età, un totale. L'eccezione è la fotografia.
- Non salvare quello che non serve: del documento le ultime quattro cifre, della password solo l'impronta.
- Una lista non sta in una colonna: è un'altra tabella.
- Il risultato del capitolo è
schema.sql. Nel capitolo successivo lo ricopi inmodelli.py.