Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

Il progetto3. Gli attributip. 61

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 azioneUsa 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 propostoChi lo usaVerdetto
il pesonessuna schermata, nessuna azionefuori
il numero dello scatolonenessuna schermata (oggi, con il database, l'oggetto si trova cercando)fuori
il colorel'elenco, la scheda, la registrazionedentro

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.

#DecisioneLa domandaIn SQL
1Il nomeCome lo chiamo?il nome della colonna
2Il tipoChe genere di dato è?TEXT, INTEGER, NUMERIC(8,2), DATE, TIMESTAMP, BOOLEAN
3Obbligatorio o facoltativoL'app può funzionare senza?NOT NULL, oppure niente
4UnicoPossono esserci due uguali?UNIQUE
5I valori ammessiQuali 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.

EvitaScriviPerché
descrizione_testodescrizioneil tipo lo dice già la colonna
data_trovatotrovato_ilil suffisso _il dice già che è una data
colore_stringacolorecome 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 è…TipoEsempio di Ritrovato
un testo, anche breveTEXTdescrizione, colore
un numero intero che si conta o si sommaINTEGERstazione_id
dei soldiNUMERIC(8,2)il prezzo di un biglietto
un giornoDATEtrovato_il
un giorno e un'oraTIMESTAMPl'ora di una prenotazione
sì o noBOOLEANfuori_uso

Le due scelte dove si sbaglia sono queste.

I soldi mai in virgola mobile. REAL e DOUBLE PRECISION sono numeri approssimati. Guarda:

SQL
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.

SQL
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):

SQL
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):

SQL
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?

AttributoDue uguali sono…Scelta
stazioni.nomeun errore: una stazione sola si chiama cosìUNIQUE
addetti.emailun errore: con quell'email si fa il loginUNIQUE
oggetti.descrizionenormale: dieci ombrelli neriniente
oggetti.colorenormale, ovvioniente
SQL
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.

SQL
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.

SQL
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:

AttributoTipoFacoltativo?Unico?Valori e DEFAULT
descrizioneTEXTnono
categoriaTEXTnonoCHECK: sei parole
coloreTEXTsìno
segno_particolareTEXTsìno
stazione_idINTEGERnonoREFERENCES stazioni(id)
trovato_ilDATEnono
statoTEXTnonoCHECK: tre parole; DEFAULT 'in deposito'
registrato_daINTEGERnonoREFERENCES 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:

SQL
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:

SQL
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.

SQL
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.

SQL
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:

DoveLa sceltaPerché
oggetti.colore, oggetti.segno_particolarefacoltativi: gli unici due senza NOT NULLle chiavi non hanno un colore che conta; non tutti gli oggetti hanno un segno
oggetti.categoria, oggetti.statoCHECK ... IN (...)liste fisse di parole, che non cambiano spesso e non hanno dati propri
oggetti.statoDEFAULT 'in deposito'un oggetto appena registrato è sempre in deposito
oggetti.trovato_ilDATE, non TIMESTAMPa Nives serve il giorno, non il minuto
(non c'è) giorni_in_deposito, da_donarecalcolati da trovato_il e da oggisalvati sarebbero sbagliati già domani
restituzioni.documento_finalequattro caratteri, CHECKdel documento bastano le ultime quattro cifre
addetti.password_hashl'impronta, mai la passwordle password
restituzioni.oggetto_idUNIQUEun 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:

  1. Ogni colonna è usata da una schermata o da un'azione? (la prova al contrario)
  2. Il nome è minuscolo, senza il tipo dentro, con _il per le date e _id per le frecce?
  3. Ogni NULL ha un significato che sai dire a parole? Gli altri sono NOT NULL?
  4. Ogni soldo è NUMERIC, ogni data è DATE o TIMESTAMP, ogni «numero» di telefono o CAP è un testo?
  5. 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.
  6. 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), mai REAL. Un numero con cui non fai conti (telefono, CAP) è un TEXT.
  • Parti da NOT NULL: il facoltativo si sceglie, e si deve sapere cosa vuol dire il vuoto. NULL non è 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 in modelli.py.