Vai al contenuto
code-to-code

Apro l'indice…

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

Il database nell'API1. Perché un databasep. 1

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:

Python
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),
}
treni = { 1: Treno(id=1, codice="M10", vagoni=4, in_servizio=True), 2: Treno(id=2, codice="M12", vagoni=4, in_servizio=True), }trenidict12Trenoid1codice"M10"vagoni4in_servizioTrueTrenoid2codice"M12"vagoni4in_servizioTrue
Il dizionario dei treni

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+C nel terminale;
  • il computer si spegne o si riavvia;
  • il programma va in errore e si chiude;
  • salvi un file: fastapi dev se 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.

DizionarioDatabase
Dove sono i datinella memoria del tuo programmasu disco, in un altro programma
Dopo il riavvio dell'APIspariti: torna quello scritto nel codiceci sono ancora
Chi può leggerlisolo il tuo programmachiunque 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:

PezzoCosa faCosa non fa
ClientManda la richiesta e legge la rispostaNon sa dove stanno i dati
API (FastAPI)Controlla la richiesta (Pydantic), decide i codici (404, 201, 409)Non conserva niente
psycopgPorta le domande SQL a PostgreSQL e riporta le righe a PythonNon decide cosa chiedere
PostgreSQLConserva i dati su disco e risponde alle domandeNon 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:

Python
@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

La rotta con il database:

Python
@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

Le 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+S con fastapi 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 psql vedono le stesse righe.