Le rotte con psycopg, se qualcosa va storto
Gli errori delle rotte, uno per uno
Gli errori che vedrai di più in questo capitolo. Per ognuno: cosa leggi, cosa vuol dire, cosa fai.
Un'API ha due posti dove guardare: il test (o curl), che ti dice cosa ha ricevuto il client, e il terminale del server (quello dove hai lanciato fastapi dev), che ti dice cosa è successo davvero. Un 500 Internal Server Error non spiega niente da solo: la spiegazione è nel traceback del server, in fondo. Come si legge un traceback: Leggere un traceback.
Gli errori con un nome
| Leggi | Vuol dire | Cosa fai |
|---|---|---|
ResponseValidationError: ... Input should be a valid dictionary or object to extract fields from (e 'input': None) | fetchone() ha dato None e la rotta l'ha restituito come se fosse un treno. Il client riceve un 500 | Subito dopo il with: if riga is None: e raise HTTPException(status_code=404, detail=...) |
ResponseValidationError con 'input': [{...}] (una lista con un dizionario dentro) | Hai usato fetchall() dove serviva fetchone() | fetchone() per una riga sola, fetchall() per la lista |
psycopg.errors.ForeignKeyViolation: ... is not present in table "stazioni" | Stai scrivendo un stazione_id che non esiste | Controlla il valore. Se può capitare, prendi l'eccezione con try / except e rispondi con un codice del 400 |
psycopg.errors.ForeignKeyViolation: ... is still referenced from table "segnalazioni" | Stai cancellando una riga a cui altre righe puntano | try attorno al with, except psycopg.errors.ForeignKeyViolation, e un 409 |
psycopg.errors.UniqueViolation: duplicate key value violates unique constraint | Quel valore (un codice, un badge) c'è già in una riga diversa | except psycopg.errors.UniqueViolation e un 409 con il detail del contratto |
psycopg.ProgrammingError: the last operation didn't produce records | fetchone() su una query che non riporta righe: INSERT, UPDATE o DELETE senza RETURNING | Aggiungi RETURNING * (o RETURNING id per il DELETE) |
TypeError: object of type 'int' has no len() | Hai scritto (treno_id): tra parentesi c'è solo un numero | La tupla la fa la virgola: (treno_id,) |
TypeError: query parameters should be a sequence or a mapping, got str | Stesso errore con una stringa: (codice) | (codice,) |
the query has 2 placeholders but 1 parameters were passed | I %s e i valori non sono tanti quanti | Un valore per ogni %s, nello stesso ordine |
psycopg.errors.UndefinedFunction: operator does not exist: integer = boolean | In un UPDATE i valori sono nell'ordine sbagliato: ogni valore è andato nel buco accanto | Conta i %s nella query e metti i valori nello stesso ordine. L'id del WHERE è l'ultimo |
psycopg.errors.SyntaxError: syntax error at or near "Orto" | Hai messo il valore dentro la stringa del SQL (f-string), e un apostrofo ha chiuso la stringa | Mai f-string: il valore va nel buco %s e nella tupla |
assert 501 == 200 (o == 201, == 204) | C'è ancora la riga del «da fare» | Al posto di raise HTTPException(status_code=501, ...) scrivi la rotta |
assert 200 == 201 (o == 204) | La rotta funziona ma manca il codice nel decoratore | @app.post("/personale", status_code=201), @app.delete(..., status_code=204) |
assert [] == [...] in un test che guarda il database (sql(...)) | La risposta era giusta, ma la scrittura non è arrivata: niente commit (una conn = connetti() senza with) | with connetti() as conn:: è il with che fa il commit |
Questi errori nascono dentro la rotta; nel terminale del server li vedi così. È la ForeignKeyViolation dell'ultimo esempio degli esercizi spiegati: un treno nuovo in una stazione che non c'è.
$ 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 ErrorINFO: 127.0.0.1:63176 - "POST /treni HTTP/1.1" 500 Internal Server Error
ERROR: Exception in ASGI application
Traceback (most recent call last):
…
File "~/corso/db-rotte-con-psycopg/palestra/centrale_psycopg.py", line 65, in nuovo_treno
treno = conn.execute(
^^^^^^^^^^^^^
File "~/corso/db-rotte-con-psycopg/.venv/lib/python3.12/site-packages/psycopg/connection.py", line 304, in execute
raise ex.with_traceback(None)
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".Le righe in mezzo (tante: sono le viscere di FastAPI) sono tolte e segnate con …. Quello che conta è la riga della tua rotta (centrale_psycopg.py, in nuovo_treno) e l'ultima riga, che ha il nome dell'errore e dice quale valore ha dato fastidio.
Gli errori che non danno errori
I più difficili sono quelli senza traceback: la rotta risponde, il codice sembra giusto, ma il dato è sbagliato o non c'è. In questo capitolo sono quasi sempre uno di questi quattro.
La scrittura che sparisce. La rotta risponde 201 con la riga giusta (l'ha ritirata con RETURNING), ma psql non la trova. Senza with nessuno ha fatto il commit. Come vederlo: guarda dentro il database, con psql o con la fixture sql(...) dei test, non solo la risposta.
L'UPDATE senza WHERE. Nessun errore, e cambiano tutte le righe. Rimedio: psql -d db_rotte_con_psycopg -c "SELECT * FROM segnalazioni" dopo la prova, e guarda se è cambiato più di una riga.
Il DELETE che non trova niente e dice «fatto». Senza RETURNING e senza if sul None, cancellare un id che non c'è risponde 204. Per accorgersene chiedi due volte lo stesso DELETE: la seconda deve dare 404.
L'ordine che «sembra» giusto. Senza ORDER BY le righe arrivano nell'ordine che il database preferisce: all'inizio è quello degli id, dopo qualche UPDATE non più. Se l'ordine conta, lo scrivi.
Per trovarli, il debugger funziona anche dentro una rotta: un breakpoint subito dopo il fetchone() e guardi cosa c'è in treno. Come si fa: Il debugger con FastAPI e con i test.
Se il problema non è il codice
| Leggi | Vuol dire | Cosa fai |
|---|---|---|
PostgreSQL non risponde (dai test) o connection refused | PostgreSQL è spento | Mac: brew services start postgresql@16 · WSL: sudo service postgresql start |
connection failed: ... No such file or directory | psycopg non trova il socket di PostgreSQL | Mac: export PGHOST=/tmp · WSL: export PGHOST=/var/run/postgresql, poi riprova |
database "db_rotte_con_psycopg" does not exist | Non hai creato il tuo database | createdb db_rotte_con_psycopg, poi psql -d db_rotte_con_psycopg -f linea_menta.sql |
relation "treni" does not exist | Il database c'è, ma è vuoto | psql -d db_rotte_con_psycopg -f linea_menta.sql |
pytest: command not found o command not found: fastapi | Il venv è spento | source .venv/bin/activate, dalla cartella dello zip |
No module named 'stazione_per_id' | Hai lanciato pytest da un'altra cartella | cd nella cartella dello zip, poi di nuovo pytest |
Address already in use | Un altro server è già acceso (un altro terminale, o un altro esercizio) | Ctrl+C nell'altro terminale, oppure fastapi dev ... --port 8001 |
La pagina del Pronto soccorso per i test che non partono: pytest non parte, o non trova niente. Per PostgreSQL e gli altri guai di ambiente: il Pronto soccorso.