Perché un database
Il dizionario sparisce, il database resta
- 10 minuti di lettura
Marta Villa, capostazione di Piazza Query, mette in servizio un treno nuovo, il M30. Lo fa dalla centrale: una richiesta POST, la risposta è 201 Created. Il M30 c'è.
Poi uno sviluppatore salva un file, il server si riavvia, e Marta chiede di nuovo del M30: 404. Il treno non esiste più.
Ernesto Pozzi, il capo deposito, lo sapeva già: «Sul mio registro di carta c'è ancora».
Questo capitolo spiega perché. E spiega perché, da qui in poi, i dati della tua API vanno in un posto che si chiama database.
Dove vivono i dati
Nel CRUD su un dizionario i treni stavano in un dizionario, dentro il 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),
}Quel dizionario vive nella memoria del programma. La memoria è veloce, ma dura quanto il programma: quando il programma si ferma, la memoria si libera e i dati se ne vanno con lei.
E il programma si ferma più spesso di quanto pensi:
- premi
Ctrl+Cnel terminale; - il computer si spegne o si riavvia;
- il programma va in errore e si chiude;
- salvi un file:
fastapi devse ne accorge e riavvia il server da capo, con un dizionario nuovo, uguale a quello scritto nel codice.
L'ultimo è il più traditore. Non hai spento niente: hai solo premuto Ctrl+S.
Un database è un programma che scrive i dati su disco. Il disco non si svuota quando un programma si ferma. Tu spegni l'API, lui resta acceso a tenere i dati. E se spegni il computer, li ritrovi alla riaccensione.
| Dizionario | Database | |
|---|---|---|
| Dove sono i dati | nella memoria del tuo programma | su disco, in un altro programma |
| Dopo il riavvio dell'API | spariti: torna quello scritto nel codice | ci sono ancora |
| Chi può leggerli | solo il tuo programma | chiunque abbia il permesso: l'API, psql, un altro programma |
Il quadro intero
Finora, quando un client faceva una richiesta, il viaggio finiva nell'API. Adesso l'API non tiene più i dati: li chiede a PostgreSQL.
CLIENT API psycopg POSTGRESQL
(curl, Postman, (FastAPI) (il traduttore) (il database)
un browser)
│ GET /treni/5 │ │ │
│ ─────────────────▶ │ │ │
│ │ la rotta vuole │ │
│ │ il treno 5 │ │
│ │ ─────────────────▶ │ SELECT … id = 5 │
│ │ │ ────────────────▶ │
│ │ │ │ legge
│ │ │ │ dal disco
│ │ │ la riga │
│ │ │ ◀──────────────── │
│ │ un dizionario │ │
│ │ ◀───────────────── │ │
│ 200 e il JSON │ │ │
│ ◀───────────────── │ │ │Chi fa cosa:
| Pezzo | Cosa fa | Cosa non fa |
|---|---|---|
| Client | Manda la richiesta e legge la risposta | Non sa dove stanno i dati |
| API (FastAPI) | Controlla la richiesta (Pydantic), decide i codici (404, 201, 409) | Non conserva niente |
| psycopg | Porta le domande SQL a PostgreSQL e riporta le righe a Python | Non decide cosa chiedere |
| PostgreSQL | Conserva i dati su disco e risponde alle domande | Non parla HTTP |
Ogni pezzo fa una cosa sola. L'API è il cameriere: prende l'ordine, lo porta in cucina, riporta il piatto. Il database è la cucina, dove le cose si tengono e si preparano. Il cameriere può cambiare turno (il server si riavvia): la cucina è sempre lì.
Cosa cambia nella rotta
La rotta con il dizionario:
@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 trenoLa rotta con il database:
@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 trenoLe righe sotto il with sono identiche. Cambia solo il modo di prendere il treno: al posto di treni.get(...) c'è una domanda SQL. Cosa fa ogni parola di quel with lo vedi nel capitolo psycopg, e le rotte intere nelle rotte con psycopg.
Il resto dell'API (percorsi, stampi, codici di risposta) è quello che già sai. Il client non si accorge di niente: stesso GET, stessa risposta. Si accorge solo che, dopo un riavvio, il treno c'è ancora.
Due client, un database
Siccome i dati sono in PostgreSQL e non nell'API, chiunque parli con PostgreSQL vede gli stessi dati. Non solo la tua API.
curl ───▶ API ───▶ ┌──────────────┐ ◀─── psql
│ PostgreSQL │
Postman ─▶ API ──▶ │ (i treni) │ ◀─── VS Code
└──────────────┘Se cambi una riga da psql, la prossima richiesta all'API la vede subito. Se l'API salva un treno, psql lo trova. L'API può anche essere spenta: psql continua a vedere tutto.
Con il dizionario era impossibile: i dati erano chiusi dentro il programma.
Due database in ogni esercizio
Negli esercizi di questo libro troverai due database con nomi quasi uguali, per esempio db_psycopg e db_psycopg_test. Il primo è tuo: ci giochi, ci salvi quello che vuoi, i dati restano. Il secondo è dei test: pytest lo ricarica da capo a ogni prova, così i test non rovinano i tuoi dati. Come funziona è nel capitolo I test con il database.
Ricorda
- Il dizionario vive nella memoria del programma: ogni riavvio, anche un semplice
Ctrl+Sconfastapi dev, lo svuota. - Il database scrive su disco ed è un altro programma: resta acceso quando l'API si ferma.
- Il viaggio completo: client, API, psycopg, PostgreSQL, e la risposta fa la strada al contrario.
- L'API decide i codici; il database conserva i dati; psycopg porta le domande e le righe.
- Più client possono parlare con lo stesso database: curl e
psqlvedono le stesse righe.