Vai al contenuto
code-to-code

Apro l'indice…

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

Il database nell'API3. Le rotte con psycopgp. 54

Le rotte con psycopg, esercizi spiegati

Cinque esempi sulla centrale dei treni

  • 20 minuti di lettura

Cinque esempi, tutti sulla stessa API: la centrale dei treni della Linea Menta, già risolta. Il file è palestra/centrale_psycopg.py nello zip della palestra: lo trovi nella pagina dopo, e puoi accenderlo insieme a me.

Ogni esempio ha lo stesso ritmo:

  1. Prevedi: leggi il comando e scrivi su un foglio cosa risponde la centrale. Prima di aprire la risposta.
  2. In italiano: cosa fa la rotta, a parole.
  3. Passo per passo: cosa succede, un pezzo alla volta.
  4. Cosa portiamo a casa.

Prima di cominciare, il database deve essere pronto e il server acceso. Dalla cartella dello zip, con il venv acceso (la prima volta il README dice come):

Terminale
createdb db_rotte_con_psycopg
psql -d db_rotte_con_psycopg -f linea_menta.sql
fastapi dev palestra/centrale_psycopg.py

Il server occupa il terminale: i comandi curl di questa pagina vanno in un secondo terminale.


A · Leggere: un treno che c'è e uno che non c'è

Marta Villa, capostazione di Piazza Query, chiede alla centrale il M14 (id 3) e poi un treno con id 99.

Terminale
curl -i http://127.0.0.1:8000/treni/3
curl -i http://127.0.0.1:8000/treni/99

La rotta è questa:

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
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
$ curl -i http://127.0.0.1:8000/treni/3
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 18:03:17 GMT
server: uvicorn
content-length: 79
content-type: application/json

{"codice":"M14","vagoni":3,"km":5200,"in_servizio":true,"stazione_id":3,"id":3}

$ curl -i http://127.0.0.1:8000/treni/99
HTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 18:03:17 GMT
server: uvicorn
content-length: 30
content-type: application/json

{"detail":"Treno non trovato"}
  • Il primo treno c'è: fetchone() dà un dizionario, l'if non scatta, la rotta lo restituisce. FastAPI lo trasforma nel JSON, con lo stesso formato dello stampo Treno.
  • Il secondo no: la query non trova niente, fetchone() dà None, e l'if alza il 404 con il detail che hai scritto tu.

In italiano.

  1. Apro la connessione.
  2. Chiedo al database la riga che ha quell'id.
  3. Ritiro una riga sola.
  4. Chiudo la connessione (il with finisce).
  5. Se non ho ritirato niente: 404. Altrimenti restituisco la riga.

Il disegno.

inizio GET /treni/{treno_id} passo SELECT ... WHERE id = treno_id passo fetchone() se treno is None sì: errore 404 Treno non trovato restituisci trenoGET /treni/{treno_id}SELECT ... WHERE id =treno_idfetchone()treno is None404 Treno non trovatorestituisci trenonosì
La rotta che legge un treno

Passo per passo.

RichiestaLa query diventafetchone() dàL'ifRisposta
/treni/3... WHERE id = 3il dizionario del M14non scatta200 e il JSON
/treni/99... WHERE id = 99Nonescatta404 e il detail

Cosa portiamo a casa. Il database non dice «404»: dice «nessuna riga». Il 404 è la traduzione di quel None, e la fai tu.


B · Scrivere: il M30, e la prova del nove

Ernesto Pozzi, capo deposito, mette in elenco un treno nuovo: il M30, cinque vagoni, fuori servizio. Poi controlla che sia davvero nel database, e che resti anche se il server si riavvia.

Terminale
curl -i -X POST http://127.0.0.1:8000/treni -H "Content-Type: application/json" -d '{"codice": "M30", "vagoni": 5, "km": 0, "in_servizio": false}'
psql -d db_rotte_con_psycopg -c "SELECT id, codice, vagoni, km, in_servizio, stazione_id FROM treni WHERE id = 10"
touch palestra/centrale_psycopg.py; sleep 3
curl http://127.0.0.1:8000/treni/10
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
$ curl -i -X POST http://127.0.0.1:8000/treni -H "Content-Type: application/json" -d '{"codice": "M30", "vagoni": 5, "km": 0, "in_servizio": false}'
HTTP/1.1 201 Created
date: Thu, 19 Nov 2026 18:03:17 GMT
server: uvicorn
content-length: 81
content-type: application/json

{"codice":"M30","vagoni":5,"km":0,"in_servizio":false,"stazione_id":null,"id":10}

$ psql -d db_rotte_con_psycopg -c "SELECT id, codice, vagoni, km, in_servizio, stazione_id FROM treni WHERE id = 10"
 id | codice | vagoni | km | in_servizio | stazione_id 
----+--------+--------+----+-------------+-------------
 10 | M30    |      5 |  0 | f           |            
(1 riga)

$ touch palestra/centrale_psycopg.py; sleep 3


$ curl http://127.0.0.1:8000/treni/10
{"codice":"M30","vagoni":5,"km":0,"in_servizio":false,"stazione_id":null,"id":10}
  • 201 Created, e il treno ha un id: l'ha scelto il database (nove treni, quindi il prossimo è 10), e RETURNING * l'ha riportato indietro. Non hai scritto stazione_id: vale null, il treno è al deposito.
  • psql non passa dalla tua API: guarda la tabella. Il treno c'è. La f vuol dire false, la colonna vuota è NULL.
  • touch finge un salvataggio del file: fastapi dev si accorge, spegne il server e lo riaccende (se guardi il terminale del server lo vedi scrivere Reloading...). Con il dizionario il M30 sarebbe sparito. Qui c'è ancora.

La rotta:

Python
@app.post("/treni", status_code=status.HTTP_201_CREATED)
def nuovo_treno(dati: TrenoNuovo) -> Treno:
    try:
        with connetti() as conn:
            treno = conn.execute(
                """
                INSERT INTO treni (codice, vagoni, km, in_servizio, stazione_id)
                VALUES (%s, %s, %s, %s, %s)
                RETURNING *
                """,
                (dati.codice, dati.vagoni, dati.km, dati.in_servizio, dati.stazione_id),
            ).fetchone()
    except psycopg.errors.UniqueViolation:
        raise HTTPException(status_code=409, detail="Codice già usato da un altro treno")
    return treno

Il try e l'except li guardiamo nell'esempio E: per ora leggi solo il with.

In italiano.

  1. Il corpo della richiesta è già un TrenoNuovo: Pydantic ha controllato che i campi ci siano e siano del tipo giusto.
  2. Apro la connessione.
  3. Scrivo la riga, con i cinque valori nei cinque buchi, e chiedo di riavere la riga scritta (RETURNING *).
  4. Ritiro quella riga.
  5. Il with finisce: il commit salva tutto sul disco.
  6. Restituisco la riga, e il decoratore dice che il codice è 201.

Passo per passo.

PezzoCosa faSe lo togli
VALUES (%s, %s, %s, %s, %s)un buco per ogni colonnathe query has 5 placeholders but 4 parameters were passed
la tupla dei cinque valoririempie i buchi, nello stesso ordine delle colonnei valori finiscono nelle colonne sbagliate
RETURNING *riporta indietro la riga scritta, con l'idfetchone() si ferma: the last operation didn't produce records
fine del withcommit: la riga restala riga sparisce, anche se la risposta è 201
status_code=201il codice della rispostarisponde 200: nessun errore, ma il codice è sbagliato

Cosa portiamo a casa. Una risposta 201 non prova che il dato sia salvato. La prova del nove: psql, oppure riavvia e rileggi. I test del capitolo, per questo, guardano dentro il database.


C · Cambiare: il M30 entra in servizio

Il M30 ha fatto il suo primo giro di prova: 120 km, adesso è in servizio e sta a Porta Codice (stazione 1). Poi Marta prova a cambiare un treno che non esiste.

Terminale
curl -i -X PUT http://127.0.0.1:8000/treni/10 -H "Content-Type: application/json" -d '{"codice": "M30", "vagoni": 5, "km": 120, "in_servizio": true, "stazione_id": 1}'
curl -i -X PUT http://127.0.0.1:8000/treni/99 -H "Content-Type: application/json" -d '{"codice": "M99", "vagoni": 5, "km": 120, "in_servizio": true}'

La rotta:

Python
@app.put("/treni/{treno_id}")
def aggiorna_treno(treno_id: int, dati: TrenoNuovo) -> Treno:
    try:
        with connetti() as conn:
            treno = conn.execute(
                """
                UPDATE treni
                SET codice = %s, vagoni = %s, km = %s, in_servizio = %s, stazione_id = %s
                WHERE id = %s
                RETURNING *
                """,
                (dati.codice, dati.vagoni, dati.km, dati.in_servizio, dati.stazione_id, treno_id),
            ).fetchone()
    except psycopg.errors.UniqueViolation:
        raise HTTPException(status_code=409, detail="Codice già usato da un altro treno")
    if treno is None:
        raise HTTPException(status_code=404, detail="Treno non trovato")
    return treno
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
$ curl -i -X PUT http://127.0.0.1:8000/treni/10 -H "Content-Type: application/json" -d '{"codice": "M30", "vagoni": 5, "km": 120, "in_servizio": true, "stazione_id": 1}'
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 18:03:20 GMT
server: uvicorn
content-length: 79
content-type: application/json

{"codice":"M30","vagoni":5,"km":120,"in_servizio":true,"stazione_id":1,"id":10}

$ curl -i -X PUT http://127.0.0.1:8000/treni/99 -H "Content-Type: application/json" -d '{"codice": "M99", "vagoni": 5, "km": 120, "in_servizio": true}'
HTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 18:03:20 GMT
server: uvicorn
content-length: 30
content-type: application/json

{"detail":"Treno non trovato"}
  • Il primo: 200 (il PUT non ha un codice speciale) e la riga come è adesso, con i 120 km e la stazione 1.
  • Il secondo: la WHERE id = 99 non trova niente, quindi UPDATE non cambia nessuna riga e RETURNING non ha niente da riportare. fetchone() dà None e scatta il 404.

In italiano.

  1. Cambio tutte le colonne della riga con quell'id, con i valori del corpo (è un PUT: il corpo è la scheda intera).
  2. Chiedo di riavere la riga cambiata.
  3. Se non l'ho ricevuta, quell'id non c'era: 404.

Il disegno.

inizio PUT /treni/{treno_id} passo UPDATE ... RETURNING * se UniqueViolation sì: errore 409 Codice già usato se treno is None sì: errore 404 Treno non trovato restituisci trenoPUT /treni/{treno_id}UPDATE ... RETURNING *UniqueViolation409 Codice già usatotreno is None404 Treno non trovatorestituisci trenonosìnosì
La rotta che cambia un treno

Passo per passo. Il pezzo delicato è la tupla: sei buchi nella query, sei valori, nell'ordine in cui compaiono i buchi.

Il bucoDove sta nella queryIl valore
1codice = %sdati.codice
2vagoni = %sdati.vagoni
3km = %sdati.km
4in_servizio = %sdati.in_servizio
5stazione_id = %sdati.stazione_id
6WHERE id = %streno_id (l'ultimo)

Cosa portiamo a casa. Nell'UPDATE l'id sta nel WHERE, cioè dopo il SET: nella tupla va per ultimo. E senza WHERE, l'UPDATE cambierebbe tutti i treni.


D · Cancellare: il M30 esce dall'elenco

Il M30 era una prova. Ernesto lo cancella; poi, per sbaglio, lo cancella una seconda volta.

Terminale
curl -i -X DELETE http://127.0.0.1:8000/treni/10
curl -i -X DELETE http://127.0.0.1:8000/treni/10

La rotta (senza il try: lo aggiungiamo nell'esempio E):

Python
@app.delete("/treni/{treno_id}", status_code=status.HTTP_204_NO_CONTENT)
def togli_treno(treno_id: int) -> None:
    with connetti() as conn:
        tolto = conn.execute("DELETE FROM treni WHERE id = %s RETURNING id", (treno_id,)).fetchone()
    if tolto is None:
        raise HTTPException(status_code=404, detail="Treno non trovato")
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
$ curl -i -X DELETE http://127.0.0.1:8000/treni/10
HTTP/1.1 204 No Content
date: Thu, 19 Nov 2026 18:03:20 GMT
server: uvicorn
content-type: application/json


$ curl -i -X DELETE http://127.0.0.1:8000/treni/10
HTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 18:03:20 GMT
server: uvicorn
content-length: 30
content-type: application/json

{"detail":"Treno non trovato"}
  • La prima volta: 204, e dopo la riga vuota non c'è niente. «Fatto, e non ho altro da dirti».
  • La seconda volta il treno non c'è più. DELETE cancella zero righe, RETURNING id non riporta niente, fetchone() dà None: 404.

In italiano.

  1. Cancello la riga con quell'id e chiedo di riavere il suo id.
  2. Se non ho ricevuto niente, quella riga non c'era: 404.
  3. Se l'ho ricevuto, la riga è stata cancellata: la rotta finisce, e il 204 lo mette il decoratore.

Passo per passo. Le due volte, viste dal database:

VoltaCosa dice DELETE ... RETURNING idfetchone()Risposta
primauna riga: 10{"id": 10}204
seconda(0 righe), DELETE 0None404

Cosa portiamo a casa. Senza RETURNING la rotta non saprebbe distinguere le due volte: risponderebbe 204 anche alla seconda, cancellando «con successo» un treno che non c'era. Il 204 non ha corpo: niente return, e il def è -> None.


E · Il database che dice di no

Due richieste che il database non può accettare: un treno nuovo con il codice del M12 (che esiste già) e la cancellazione del M12 (che ha tre segnalazioni di guasto).

Terminale
curl -i -X POST http://127.0.0.1:8000/treni -H "Content-Type: application/json" -d '{"codice": "M12", "vagoni": 4, "km": 0, "in_servizio": true}'
curl -i -X DELETE http://127.0.0.1:8000/treni/2
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
$ curl -i -X POST http://127.0.0.1:8000/treni -H "Content-Type: application/json" -d '{"codice": "M12", "vagoni": 4, "km": 0, "in_servizio": true}'
HTTP/1.1 409 Conflict
date: Thu, 19 Nov 2026 18:03:20 GMT
server: uvicorn
content-length: 48
content-type: application/json

{"detail":"Codice già usato da un altro treno"}

$ curl -i -X DELETE http://127.0.0.1:8000/treni/2
HTTP/1.1 409 Conflict
date: Thu, 19 Nov 2026 18:03:20 GMT
server: uvicorn
content-length: 43
content-type: application/json

{"detail":"Il treno ha delle segnalazioni"}

Due 409, due messaggi diversi: ognuno nato da un except diverso.

Vediamo cosa succede dentro, senza FastAPI, con un file palestra/provo_errori.py che fa le stesse due cose:

Python
import psycopg

from database import connetti

try:
    with connetti() as conn:
        conn.execute("INSERT INTO treni (codice, vagoni, km, in_servizio) VALUES ('M12', 4, 0, true)")
except psycopg.errors.UniqueViolation as errore:
    print("Preso:", type(errore).__name__)
    print(errore)

try:
    with connetti() as conn:
        conn.execute("DELETE FROM treni WHERE id = 2")
except psycopg.errors.ForeignKeyViolation as errore:
    print("Preso:", type(errore).__name__)
    print(errore)
Terminale
python palestra/provo_errori.py
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
$ python palestra/provo_errori.py
Preso: UniqueViolation
duplicate key value violates unique constraint "treni_codice_key"
DETAIL:  Key (codice)=(M12) already exists.
Preso: ForeignKeyViolation
update or delete on table "treni" violates foreign key constraint "segnalazioni_treno_id_fkey" on table "segnalazioni"
DETAIL:  Key (id)=(2) is still referenced from table "segnalazioni".

Le due regole del database hanno due eccezioni con il loro nome. Il messaggio dice quale regola (treni_codice_key, segnalazioni_treno_id_fkey) e quale valore (Key (codice)=(M12)). I messaggi del server sono in inglese anche su un Mac in italiano.

In italiano. Nella rotta, il try circonda il with. Se il database dice di no, l'errore esce dal with (che fa il rollback: niente resta a metà), e l'except lo trasforma in un HTTPException con il codice 409.

Passo per passo.

RichiestaCosa dice il databaseCosa succede nella rottaRisposta
POST con codice M12UniqueViolationl'except la prende409, «Codice già usato…»
POST con un codice nuovonienteil with fa il commit201
DELETE del treno 2ForeignKeyViolationl'except la prende409, «Il treno ha delle segnalazioni»
DELETE del treno 9 (nessuna segnalazione)nientefetchone() dà {"id": 9}204

Cosa succede se non prendi l'eccezione? Provalo con una richiesta che la centrale non gestisce: un treno nuovo in una stazione che non esiste ("stazione_id": 42).

Terminale
curl -i -X POST http://127.0.0.1:8000/treni -H "Content-Type: application/json" -d '{"codice": "M31", "vagoni": 5, "km": 0, "in_servizio": true, "stazione_id": 42}'
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
$ curl -i -X POST http://127.0.0.1:8000/treni -H "Content-Type: application/json" -d '{"codice": "M31", "vagoni": 5, "km": 0, "in_servizio": true, "stazione_id": 42}'
HTTP/1.1 500 Internal Server Error
date: Thu, 19 Nov 2026 18:03:20 GMT
server: uvicorn
content-length: 21
content-type: text/plain; charset=utf-8

Internal Server Error

Il client vede solo «Internal Server Error». La spiegazione vera è nel terminale del server, in fondo al traceback (qui abbiamo tolto le righe in mezzo):

  File "~/corso/db-rotte-con-psycopg/palestra/centrale_psycopg.py", line 65, in nuovo_treno
    treno = conn.execute(
            ^^^^^^^^^^^^^
psycopg.errors.ForeignKeyViolation: insert or update on table "treni" violates foreign key constraint "treni_stazione_id_fkey"
DETAIL:  Key (stazione_id)=(42) is not present in table "stazioni".

È la stessa ForeignKeyViolation del DELETE, ma nel POST nessuno la prende: la centrale non ha un except per questo caso. Un 500 vuol dire «il programma non aveva previsto questo». Quando scrivi una rotta, chiediti quali regole del database può rompere, e prendi quelle.

Cosa portiamo a casa. Il database è l'ultimo che controlla le regole, e dice di no con un'eccezione dal nome preciso. Tu la prendi con try attorno al with e la trasformi in un codice del 400 (qui il 409). Senza except il client riceve un 500.


Hai visto tutte e cinque le mosse. Nella palestra le scrivi tu.