Perché un database, esercizi spiegati
Il M30 che sparisce, e il M30 che resta
- 25 minuti di lettura
Cinque esempi. I primi tre li fai con le mani: accendi un server, mandi una richiesta, lo riavvii. Gli ultimi due li leggi e li provi.
Ogni esempio ha lo stesso ritmo:
- Prevedi: leggi cosa succede e scrivi su un foglio cosa risponderà il server. Prima di aprire la risposta.
- In italiano: cosa è successo, a parole.
- Passo per passo: cosa c'è nella memoria e sul disco a ogni mossa.
- Cosa portiamo a casa: la cosa da ricordare.
Prima di cominciare
Servono PostgreSQL acceso (se non lo è, PostgreSQL e psql) e una cartella di lavoro con il suo venv. Su Windows, tutto dentro Ubuntu.
mkdir -p ~/corso/centrale
cd ~/corso/centrale
python3 -m venv .venv
source .venv/bin/activate
pip install "fastapi[standard]" "psycopg[binary]"
code .Questa cartella è solo tua: non è uno zip degli esercizi, serve per questo capitolo. In VS Code crea i file uno alla volta, man mano che servono.
A · Il M30 e il dizionario
Il primo file è la centrale con i treni in un dizionario, come nel libro HTTP. Chiamalo centrale_dizionario.py.
from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field
app = FastAPI()
class TrenoNuovo(BaseModel):
codice: str = Field(min_length=1)
vagoni: int = Field(gt=0)
in_servizio: bool
class Treno(TrenoNuovo):
id: int
# I treni vivono qui, nella memoria del programma.
treni: dict[int, Treno] = {
1: Treno(id=1, codice="M10", vagoni=4, in_servizio=True),
2: Treno(id=2, codice="M12", vagoni=4, in_servizio=True),
3: Treno(id=3, codice="M14", vagoni=3, in_servizio=True),
4: Treno(id=4, codice="M18", vagoni=4, in_servizio=False),
}
@app.get("/treni")
def lista_treni() -> list[Treno]:
return list(treni.values())
@app.get("/treni/{treno_id}")
def leggi_treno(treno_id: int) -> Treno:
treno = treni.get(treno_id)
if treno is None:
raise HTTPException(status_code=404, detail="Treno non trovato")
return treno
@app.post("/treni", status_code=status.HTTP_201_CREATED)
def nuovo_treno(dati: TrenoNuovo) -> Treno:
nuovo_id = max(treni) + 1
treno = Treno(id=nuovo_id, **dati.model_dump())
treni[nuovo_id] = treno
return trenoAccendilo in un terminale (quello resta occupato dal server):
fastapi dev centrale_dizionario.pyDal secondo terminale (nella stessa cartella, con il venv acceso) fai tre cose, nell'ordine:
curl http://127.0.0.1:8000/treni/5
curl -i -X POST http://127.0.0.1:8000/treni -H "Content-Type: application/json" -d '{"codice": "M30", "vagoni": 5, "in_servizio": true}'
curl http://127.0.0.1:8000/treni/5Poi salva il file: basta aprirlo in VS Code e premere Ctrl+S (su Mac Cmd+S), anche senza cambiare niente. Se vuoi farlo da terminale, touch centrale_dizionario.py ha lo stesso effetto. Aspetta un paio di secondi e rifai la richiesta:
curl -i http://127.0.0.1:8000/treni/5Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Cosa risponde ciascuna delle quattro richieste al treno 5?
$ curl http://127.0.0.1:8000/treni/5
{"detail":"Treno non trovato"}
$ curl -i -X POST http://127.0.0.1:8000/treni -H "Content-Type: application/json" -d '{"codice": "M30", "vagoni": 5, "in_servizio": true}'
HTTP/1.1 201 Created
date: Thu, 19 Nov 2026 17:58:10 GMT
server: uvicorn
content-length: 53
content-type: application/json
{"codice":"M30","vagoni":5,"in_servizio":true,"id":5}
$ curl http://127.0.0.1:8000/treni/5
{"codice":"M30","vagoni":5,"in_servizio":true,"id":5}
$ curl -i http://127.0.0.1:8000/treni/5
HTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 17:58:13 GMT
server: uvicorn
content-length: 30
content-type: application/json
{"detail":"Treno non trovato"}- Prima richiesta: i treni sono quattro, il numero 5 non c'è.
404. - Seconda: il
POSTaggiunge il M30. Il server risponde201con l'id che ha scelto, il 5. - Terza: adesso il treno 5 esiste.
200e il M30. - Quarta: dopo il salvataggio, di nuovo
404. Il M30 è sparito, anche se nessuno lo ha cancellato.
Le date nelle risposte sono quelle di quando è stato provato: le tue saranno diverse.
Nel terminale del server, a ogni salvataggio, leggi:
WARNING: WatchFiles detected changes in 'centrale_dizionario.py'. Reloading...
INFO: Shutting down
INFO: Waiting for application shutdown.
INFO: Application shutdown complete.
INFO: Finished server process [84805]
INFO: Started server process [84827]
INFO: Waiting for application startup.
INFO: Application startup complete.In italiano.
- Il server parte e costruisce il dizionario
treni, con quattro treni. - Il
POSTaggiunge un quinto treno dentro quel dizionario. - Il salvataggio del file fa spegnere il server e accendere un server nuovo.
- Il server nuovo costruisce un dizionario nuovo, leggendo di nuovo il codice: quattro treni.
Passo per passo.
| Mossa | Il dizionario treni nella memoria | Risposta per il treno 5 |
|---|---|---|
| Il server parte | M10, M12, M14, M18 | 404 |
POST del M30 | M10, M12, M14, M18, M30 | 201 |
GET /treni/5 | M10, M12, M14, M18, M30 | 200 |
Ctrl+S: il server si riavvia | di nuovo M10, M12, M14, M18 | 404 |
Cosa portiamo a casa. I dati dell'API stavano nella memoria del server, e il server era appena stato spento. Il dizionario non è rotto: fa quello che deve. Solo che non è il posto giusto per conservare qualcosa.
B · Il M30 e il database
Stessa centrale, stesse tre rotte. Cambia dove stanno i treni: in una tabella di PostgreSQL.
Prima il database. Crea treni.sql con la tabella e quattro treni (è il SQL del libro SQL):
DROP TABLE IF EXISTS treni;
CREATE TABLE treni (
id SERIAL PRIMARY KEY,
codice TEXT NOT NULL UNIQUE,
vagoni INTEGER NOT NULL CHECK (vagoni > 0),
in_servizio BOOLEAN NOT NULL
);
INSERT INTO treni (codice, vagoni, in_servizio) VALUES
('M10', 4, true),
('M12', 4, true),
('M14', 3, true),
('M18', 4, false);Poi crea il database e caricalo (è un database solo per questo capitolo):
createdb db_perche_un_database
psql -d db_perche_un_database -f treni.sql
psql -d db_perche_un_database -c "SELECT * FROM treni"$ createdb db_perche_un_database
$ psql -d db_perche_un_database -f treni.sql
psql:treni.sql:1: NOTICE: table "treni" does not exist, skipping
DROP TABLE
CREATE TABLE
INSERT 0 4
$ psql -d db_perche_un_database -c "SELECT * FROM treni"
id | codice | vagoni | in_servizio
----+--------+--------+-------------
1 | M10 | 4 | t
2 | M12 | 4 | t
3 | M14 | 3 | t
4 | M18 | 4 | f
(4 righe)Ora la centrale. Crea centrale_database.py. Gli stampi e le rotte hanno la stessa forma di prima; non serve capire ancora le righe con connetti e execute: le spiega il capitolo psycopg. Qui contano due cose: dentro la rotta c'è una domanda SQL, e il dizionario treni non c'è più.
import psycopg
from fastapi import FastAPI, HTTPException, status
from psycopg.rows import dict_row
from pydantic import BaseModel, Field
app = FastAPI()
class TrenoNuovo(BaseModel):
codice: str = Field(min_length=1)
vagoni: int = Field(gt=0)
in_servizio: bool
class Treno(TrenoNuovo):
id: int
def connetti():
return psycopg.connect(dbname="db_perche_un_database", row_factory=dict_row)
@app.get("/treni")
def lista_treni() -> list[Treno]:
with connetti() as conn:
return conn.execute("SELECT * FROM treni ORDER BY id").fetchall()
@app.get("/treni/{treno_id}")
def leggi_treno(treno_id: int) -> Treno:
with connetti() as conn:
treno = conn.execute("SELECT * FROM treni WHERE id = %s", (treno_id,)).fetchone()
if treno is None:
raise HTTPException(status_code=404, detail="Treno non trovato")
return treno
@app.post("/treni", status_code=status.HTTP_201_CREATED)
def nuovo_treno(dati: TrenoNuovo) -> Treno:
with connetti() as conn:
treno = conn.execute(
"INSERT INTO treni (codice, vagoni, in_servizio) VALUES (%s, %s, %s) RETURNING *",
(dati.codice, dati.vagoni, dati.in_servizio),
).fetchone()
return trenoFerma il server di prima (Ctrl+C nel suo terminale) e accendi questo:
fastapi dev centrale_database.pyRifai la stessa sequenza dell'esempio A: GET del treno 5, POST del M30, salva il file (touch centrale_database.py), GET del treno 5.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Dopo il salvataggio, cosa risponde l'ultima richiesta?
$ curl http://127.0.0.1:8000/treni/5
{"detail":"Treno non trovato"}
$ curl -i -X POST http://127.0.0.1:8000/treni -H "Content-Type: application/json" -d '{"codice": "M30", "vagoni": 5, "in_servizio": true}'
HTTP/1.1 201 Created
date: Thu, 19 Nov 2026 17:58:19 GMT
server: uvicorn
content-length: 53
content-type: application/json
{"codice":"M30","vagoni":5,"in_servizio":true,"id":5}
$ touch centrale_database.py; sleep 3
$ curl -i http://127.0.0.1:8000/treni/5
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 17:58:22 GMT
server: uvicorn
content-length: 53
content-type: application/json
{"codice":"M30","vagoni":5,"in_servizio":true,"id":5}- Le prime due risposte sono identiche a quelle dell'esempio A: il client non vede la differenza.
- L'ultima è diversa:
200e il M30. Il server si è riavviato, ma il M30 era nel database, non nel server.
In italiano.
- Il
POSTnon aggiunge il M30 a un dizionario: manda al database unaINSERT, che scrive una riga nuova nella tabellatreni. - Il salvataggio spegne il server e ne accende uno nuovo. Il server nuovo ha la memoria vuota... e non gli serve: quando arriva il
GET, chiede il treno 5 a PostgreSQL. - PostgreSQL ha la riga sul disco e la restituisce.
Passo per passo.
| Mossa | Memoria dell'API | Tabella treni su disco | Risposta per il treno 5 |
|---|---|---|---|
| Il server parte | niente dei treni | M10, M12, M14, M18 | 404 |
POST del M30 | niente dei treni | M10, M12, M14, M18, M30 | 201 |
Ctrl+S: il server si riavvia | niente dei treni | M10, M12, M14, M18, M30 | 200 |
Cosa portiamo a casa. Il server si può riavviare mille volte: non conteneva i treni, quindi non li perde. Per l'API conta chi sa dove sono i dati, non chi li tiene.
C · Il server spento
Il database non ha bisogno dell'API per tenere i dati. Fermiamola davvero: nel terminale del server premi Ctrl+C. Ora l'API non esiste più.
Dal secondo terminale, guarda la tabella direttamente:
psql -d db_perche_un_database -c "SELECT * FROM treni ORDER BY id"Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Con l'API spenta, il M30 c'è?
$ psql -d db_perche_un_database -c "SELECT * FROM treni ORDER BY id"
id | codice | vagoni | in_servizio
----+--------+--------+-------------
1 | M10 | 4 | t
2 | M12 | 4 | t
3 | M14 | 3 | t
4 | M18 | 4 | f
5 | M30 | 5 | t
(5 righe)Sì. Il M30 è nella tabella, con l'id 5 che gli ha dato il database.
In italiano. psql si collega a PostgreSQL, non all'API. PostgreSQL è un altro programma, ancora acceso, e la sua tabella non dipende da nessun server FastAPI.
Cosa portiamo a casa. Dopo Ctrl+C, un dizionario non esiste più. Una tabella sì. Se domani riaccendi il computer, accendi PostgreSQL (vedi PostgreSQL e psql) e il M30 è ancora lì.
D · Il viaggio di una richiesta
Questo esempio non ha niente da lanciare: devi solo leggere. Riaccendi il server dell'esempio B (fastapi dev centrale_database.py) e fai curl http://127.0.0.1:8000/treni/5. Quella richiesta fa sei passi.
1 curl ─ GET /treni/5 ──────────────────▶ FastAPI
2 FastAPI trova la rotta leggi_treno e prende treno_id = 5 dal percorso
3 la rotta ─ SELECT * FROM treni WHERE id = 5 ▶ PostgreSQL (tramite psycopg)
4 PostgreSQL legge la riga dal disco e la restituisce a psycopg
5 psycopg trasforma la riga in un dizionario Python e lo consegna alla rotta
6 FastAPI lo controlla con lo stampo Treno, lo trasforma in JSON
curl ◀──────────────── 200 {"codice":"M30", …}Dove può andare storto, passo per passo:
| Passo | Cosa può andare storto | Cosa vedi |
|---|---|---|
| 1 | Il server non è acceso | curl: (7) Failed to connect |
| 2 | Il percorso non esiste, o treno_id non è un numero | 404 o 422 (lo decide FastAPI) |
| 3 | PostgreSQL non è acceso, o il database non esiste | 500, e nel terminale del server un errore di psycopg |
| 4 | La tabella o la colonna non esistono | 500, e relation "…" does not exist |
| 5 | La riga non c'è: psycopg restituisce None | la rotta lo vede e risponde 404 |
| 6 | La riga non rispetta lo stampo | 500 |
Quando qualcosa non va, la prima domanda è sempre la stessa: a quale passo ci siamo fermati? Dal tipo di errore capisci quale pezzo è rotto. L'ultima pagina del capitolo, «Se qualcosa va storto», ha la tabella degli errori che vedrai di più.
Cosa portiamo a casa. Una richiesta non è un'azione sola: sono quattro pezzi in fila. Se sai quale pezzo fa cosa, sai dove cercare.
E · Due client, un database (da provare)
Con l'API acceso (fastapi dev centrale_database.py), guarda il M18: è fuori servizio.
psql -d db_perche_un_database -c "SELECT * FROM treni ORDER BY id"Ora cambialo con psql, senza toccare l'API, e chiedi del M18 alla centrale:
psql -d db_perche_un_database -c "UPDATE treni SET in_servizio = true WHERE codice = 'M18'"
curl http://127.0.0.1:8000/treni/4Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
La risposta dell'API sa già della modifica?
$ psql -d db_perche_un_database -c "SELECT * FROM treni ORDER BY id"
id | codice | vagoni | in_servizio
----+--------+--------+-------------
1 | M10 | 4 | t
2 | M12 | 4 | t
3 | M14 | 3 | t
4 | M18 | 4 | f
5 | M30 | 5 | t
(5 righe)
$ psql -d db_perche_un_database -c "UPDATE treni SET in_servizio = true WHERE codice = 'M18'"
UPDATE 1
$ curl http://127.0.0.1:8000/treni/4
{"codice":"M18","vagoni":4,"in_servizio":true,"id":4}Sì: "in_servizio":true. L'API non ha ricevuto nessun avviso: a ogni richiesta, rilegge la riga dal database. Se una riga cambia, la prossima richiesta la trova già cambiata.
Cosa portiamo a casa. Il database è un posto in comune. Chi ci scrive (la tua API, psql, un altro programma) cambia una cosa sola, che tutti gli altri vedono. Con il dizionario, due programmi avevano due copie diverse.
Prima di andare avanti
Quando hai finito, ferma il server (Ctrl+C). Puoi tenere il database db_perche_un_database; se vuoi toglierlo:
dropdb db_perche_un_databaseNel prossimo capitolo apri la scatola in mezzo: psycopg, cosa fanno davvero connetti, execute e fetchone.