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:
- Prevedi: leggi il comando e scrivi su un foglio cosa risponde la centrale. Prima di aprire la risposta.
- In italiano: cosa fa la rotta, a parole.
- Passo per passo: cosa succede, un pezzo alla volta.
- 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):
createdb db_rotte_con_psycopg
psql -d db_rotte_con_psycopg -f linea_menta.sql
fastapi dev palestra/centrale_psycopg.pyIl 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.
curl -i http://127.0.0.1:8000/treni/3
curl -i http://127.0.0.1:8000/treni/99La rotta è questa:
@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 trenoPrevedi 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'ifnon scatta, la rotta lo restituisce. FastAPI lo trasforma nel JSON, con lo stesso formato dello stampoTreno. - Il secondo no: la query non trova niente,
fetchone()dàNone, e l'ifalza il 404 con ildetailche hai scritto tu.
In italiano.
- Apro la connessione.
- Chiedo al database la riga che ha quell'id.
- Ritiro una riga sola.
- Chiudo la connessione (il
withfinisce). - Se non ho ritirato niente: 404. Altrimenti restituisco la riga.
Il disegno.
Passo per passo.
| Richiesta | La query diventa | fetchone() dà | L'if | Risposta |
|---|---|---|---|---|
/treni/3 | ... WHERE id = 3 | il dizionario del M14 | non scatta | 200 e il JSON |
/treni/99 | ... WHERE id = 99 | None | scatta | 404 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.
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/10Prevedi 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), eRETURNING *l'ha riportato indietro. Non hai scrittostazione_id: valenull, il treno è al deposito. psqlnon passa dalla tua API: guarda la tabella. Il treno c'è. Lafvuol direfalse, la colonna vuota èNULL.touchfinge un salvataggio del file:fastapi devsi accorge, spegne il server e lo riaccende (se guardi il terminale del server lo vedi scrivereReloading...). Con il dizionario il M30 sarebbe sparito. Qui c'è ancora.
La rotta:
@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 trenoIl try e l'except li guardiamo nell'esempio E: per ora leggi solo il with.
In italiano.
- Il corpo della richiesta è già un
TrenoNuovo: Pydantic ha controllato che i campi ci siano e siano del tipo giusto. - Apro la connessione.
- Scrivo la riga, con i cinque valori nei cinque buchi, e chiedo di riavere la riga scritta (
RETURNING *). - Ritiro quella riga.
- Il
withfinisce: il commit salva tutto sul disco. - Restituisco la riga, e il decoratore dice che il codice è 201.
Passo per passo.
| Pezzo | Cosa fa | Se lo togli |
|---|---|---|
VALUES (%s, %s, %s, %s, %s) | un buco per ogni colonna | the query has 5 placeholders but 4 parameters were passed |
| la tupla dei cinque valori | riempie i buchi, nello stesso ordine delle colonne | i valori finiscono nelle colonne sbagliate |
RETURNING * | riporta indietro la riga scritta, con l'id | fetchone() si ferma: the last operation didn't produce records |
fine del with | commit: la riga resta | la riga sparisce, anche se la risposta è 201 |
status_code=201 | il codice della risposta | risponde 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.
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:
@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 trenoPrevedi 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
PUTnon ha un codice speciale) e la riga come è adesso, con i 120 km e la stazione 1. - Il secondo: la
WHERE id = 99non trova niente, quindiUPDATEnon cambia nessuna riga eRETURNINGnon ha niente da riportare.fetchone()dàNonee scatta il 404.
In italiano.
- Cambio tutte le colonne della riga con quell'id, con i valori del corpo (è un
PUT: il corpo è la scheda intera). - Chiedo di riavere la riga cambiata.
- Se non l'ho ricevuta, quell'id non c'era: 404.
Il disegno.
Passo per passo. Il pezzo delicato è la tupla: sei buchi nella query, sei valori, nell'ordine in cui compaiono i buchi.
| Il buco | Dove sta nella query | Il valore |
|---|---|---|
| 1 | codice = %s | dati.codice |
| 2 | vagoni = %s | dati.vagoni |
| 3 | km = %s | dati.km |
| 4 | in_servizio = %s | dati.in_servizio |
| 5 | stazione_id = %s | dati.stazione_id |
| 6 | WHERE id = %s | treno_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.
curl -i -X DELETE http://127.0.0.1:8000/treni/10
curl -i -X DELETE http://127.0.0.1:8000/treni/10La rotta (senza il try: lo aggiungiamo nell'esempio E):
@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ù.
DELETEcancella zero righe,RETURNING idnon riporta niente,fetchone()dàNone: 404.
In italiano.
- Cancello la riga con quell'id e chiedo di riavere il suo id.
- Se non ho ricevuto niente, quella riga non c'era: 404.
- 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:
| Volta | Cosa dice DELETE ... RETURNING id | fetchone() | Risposta |
|---|---|---|---|
| prima | una riga: 10 | {"id": 10} | 204 |
| seconda | (0 righe), DELETE 0 | None | 404 |
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).
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/2Prevedi 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:
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)python palestra/provo_errori.pyPrevedi 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.
| Richiesta | Cosa dice il database | Cosa succede nella rotta | Risposta |
|---|---|---|---|
POST con codice M12 | UniqueViolation | l'except la prende | 409, «Codice già usato…» |
POST con un codice nuovo | niente | il with fa il commit | 201 |
DELETE del treno 2 | ForeignKeyViolation | l'except la prende | 409, «Il treno ha delle segnalazioni» |
DELETE del treno 9 (nessuna segnalazione) | niente | fetchone() 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).
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 ErrorIl 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.