Vai al contenuto
code-to-code

Apro l'indice…

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

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

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:

  1. Prevedi: leggi cosa succede e scrivi su un foglio cosa risponderà il server. Prima di aprire la risposta.
  2. In italiano: cosa è successo, a parole.
  3. Passo per passo: cosa c'è nella memoria e sul disco a ogni mossa.
  4. 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.

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

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

Accendilo in un terminale (quello resta occupato dal server):

Terminale
fastapi dev centrale_dizionario.py

Dal secondo terminale (nella stessa cartella, con il venv acceso) fai tre cose, nell'ordine:

Terminale
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/5

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

Terminale
curl -i http://127.0.0.1:8000/treni/5
Prevedi 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 POST aggiunge il M30. Il server risponde 201 con l'id che ha scelto, il 5.
  • Terza: adesso il treno 5 esiste. 200 e 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.

  1. Il server parte e costruisce il dizionario treni, con quattro treni.
  2. Il POST aggiunge un quinto treno dentro quel dizionario.
  3. Il salvataggio del file fa spegnere il server e accendere un server nuovo.
  4. Il server nuovo costruisce un dizionario nuovo, leggendo di nuovo il codice: quattro treni.

Passo per passo.

MossaIl dizionario treni nella memoriaRisposta per il treno 5
Il server parteM10, M12, M14, M18404
POST del M30M10, M12, M14, M18, M30201
GET /treni/5M10, M12, M14, M18, M30200
Ctrl+S: il server si riavviadi nuovo M10, M12, M14, M18404

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

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

Terminale
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ù.

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

Ferma il server di prima (Ctrl+C nel suo terminale) e accendi questo:

Terminale
fastapi dev centrale_database.py

Rifai 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: 200 e il M30. Il server si è riavviato, ma il M30 era nel database, non nel server.

In italiano.

  1. Il POST non aggiunge il M30 a un dizionario: manda al database una INSERT, che scrive una riga nuova nella tabella treni.
  2. 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.
  3. PostgreSQL ha la riga sul disco e la restituisce.

Passo per passo.

MossaMemoria dell'APITabella treni su discoRisposta per il treno 5
Il server parteniente dei treniM10, M12, M14, M18404
POST del M30niente dei treniM10, M12, M14, M18, M30201
Ctrl+S: il server si riavvianiente dei treniM10, M12, M14, M18, M30200

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:

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

PassoCosa può andare stortoCosa vedi
1Il server non è accesocurl: (7) Failed to connect
2Il percorso non esiste, o treno_id non è un numero404 o 422 (lo decide FastAPI)
3PostgreSQL non è acceso, o il database non esiste500, e nel terminale del server un errore di psycopg
4La tabella o la colonna non esistono500, e relation "…" does not exist
5La riga non c'è: psycopg restituisce Nonela rotta lo vede e risponde 404
6La riga non rispetta lo stampo500

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.

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

Terminale
psql -d db_perche_un_database -c "UPDATE treni SET in_servizio = true WHERE codice = 'M18'"
curl http://127.0.0.1:8000/treni/4
Prevedi 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:

Terminale
dropdb db_perche_un_database

Nel prossimo capitolo apri la scatola in mezzo: psycopg, cosa fanno davvero connetti, execute e fetchone.