Vai al contenuto
code-to-code

Apro l'indice…

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

Il database nell'API5. La sessionep. 136

La sessione, se qualcosa va storto

Gli errori della sessione, uno per uno

Gli errori che vedrai di più in questo capitolo. Per ognuno: cosa leggi, cosa vuol dire, cosa fai. Il capitolo è uno dei più difficili del libro: è normale sbagliare, e quasi tutti gli errori hanno un nome che dice già dove cercare.

Ricorda come si legge un traceback: dal basso. L'ultima riga dice cosa, la riga con File … line … dice dove. Tutto il resto è nel capitolo Leggere un traceback.

Il 500 e dove guardare

Quando una rotta si rompe, il client non vede niente di utile:

$ 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 500 Internal Server Error
date: Thu, 19 Nov 2026 18:10:17 GMT
server: uvicorn
content-length: 21
content-type: text/plain; charset=utf-8

Internal Server Error

Il 500 è solo il segnale: l'errore vero è nel terminale del server, in fondo al traceback. In questo caso:

  File "~/corso/db-sessione/palestra/rotta_guasta.py", line 45, in nuovo_treno
    db.refresh(treno)
  File "~/corso/db-sessione/.venv/lib/python3.12/site-packages/sqlalchemy/orm/session.py", line 3364, in refresh
    self._expire_state(state, attribute_names)
  File "~/corso/db-sessione/.venv/lib/python3.12/site-packages/sqlalchemy/orm/session.py", line 3490, in _expire_state
    self._validate_persistent(state)
  File "~/corso/db-sessione/.venv/lib/python3.12/site-packages/sqlalchemy/orm/session.py", line 4410, in _validate_persistent
    raise sa_exc.InvalidRequestError(
sqlalchemy.exc.InvalidRequestError: Instance '<TrenoDB at 0x10efe6780>' is not persistent within this Session

Le ultime righe dicono tutto: la riga della tua rotta (line 45, in nuovo_treno, la riga con db.refresh(treno)) e il nome dell'errore. Qui manca il commit. Con pytest invece non c'è nessun 500: TestClient ti fa vedere direttamente l'eccezione, e il test è rosso con lo stesso messaggio. Come si ispeziona una rotta con il debugger: Il debugger con FastAPI e i test.

Gli errori con un nome

LeggiVuol direCosa fai
FastAPIError: Invalid args for response field! Hint: check that <class 'sqlalchemy.orm.session.Session'> is a valid Pydantic field typeIl parametro db non ha Depends: FastAPI crede che sia un dato che arriva dal client, e non sa che tipo di dato sia Session. Succede appena accendi il server, non alla richiestadb: Session = Depends(get_db), completo
FastAPIError: Invalid args for response field! Hint: check that <class 'modelli.TrenoDB'> is a valid Pydantic field typeNel def hai scritto -> TrenoDB: la classe-tabella al posto dello stampoDopo la freccia va lo stampo: -> Treno, oppure -> list[Treno]
TypeError: <generator object get_db at 0x…> is not a callable objectHai scritto Depends(get_db()): la funzione l'hai chiamata tuDepends(get_db), senza parentesi
AttributeError: 'NoneType' object has no attribute 'codice'db.get o db.scalar hanno risposto None (la riga non c'è) e sei andato avantiSubito dopo: if treno is None: e raise HTTPException(status_code=404, …)
ResponseValidationError … Input should be a valid dictionary or object to extract fields from, con 'input': NoneLa rotta ha restituito None: manca l'if … is NoneL'if con il 404, prima del return
ResponseValidationError … Field required, con 'input': (<modelli.StazioneDB object at 0x…>,)Hai usato db.execute(…).all(): arrivano righe, ognuna con un oggetto dentro, non gli oggettidb.scalars(…).all()
ArgumentError: Column expression, FROM clause, or other columns clause element expected, got <class '…Treno'>.In select(…) hai messo lo stampo (Treno)select(TrenoDB): dentro va la classe-tabella
NoInspectionAvailable: No inspection system is available for object of type <class 'pydantic._internal._model_construction.ModelMetaclass'>Hai passato lo stampo a db.getdb.get(TrenoDB, treno_id)
UnmappedInstanceError: Class '__main__.Treno' is not mapped (o un nome di modulo al posto di __main__)A db.add hai dato un oggetto Pydantic, non una classe-tabelladb.add(TrenoDB(…)): crea un TrenoDB dai dati dello stampo
UnmappedInstanceError: Class 'builtins.NoneType' is not mappedA db.delete (o db.add) hai passato None: la riga non c'eraif … is None con il 404, prima di db.delete
DataError: (psycopg.errors.InvalidTextRepresentation) invalid input syntax for type integer: "B-07"db.get vuole l'id, un numero, e tu gli hai dato un badge (o un fascicolo): un testodb.scalar(select(…).where(Classe.colonna == valore))
TypeError: 'carrozze' is an invalid keyword argument for TrenoDBUna colonna che non esiste nella classe-tabellaGuarda modelli.py: i nomi sono quelli
InvalidRequestError: Instance '<TrenoDB at 0x…>' is not persistent within this SessionHai fatto db.refresh su un oggetto che non è stato salvato: manca il db.commit() (o il db.add)add, commit, e solo dopo refresh
IntegrityError: (psycopg.errors.UniqueViolation) duplicate key value violates unique constraint "personale_badge_key"Hai scritto un valore che deve essere unico, e c'è già: il database ha detto noControlla prima, con db.scalar, e rispondi 409
IntegrityError: (psycopg.errors.ForeignKeyViolation) … Key (stazione_id)=(42) is not present in table "stazioni"Il valore punta a una riga che non esisteControlla prima con db.get e rispondi 404
PendingRollbackError: This Session's transaction has been rolled back due to a previous exception during flushLa sessione ha avuto un errore (di solito un IntegrityError preso con except) e non l'hai rimessa a postodb.rollback() subito dopo l'except
OperationalError: (psycopg.OperationalError) connection failed: … FATAL: database "db_sessione_manca" does not existIl database con quel nome non c'ècreatedb db_sessione, poi psql -d db_sessione -f linea_menta.sql
ProgrammingError: (psycopg.errors.UndefinedTable) relation "treni" does not existIl database c'è, ma è vuotopsql -d db_sessione -f linea_menta.sql
assert 501 == 200C'è ancora la riga del «da fare»Al suo posto, il tuo codice

Gli errori che non danno errori

I più difficili sono quelli senza traceback: la rotta risponde, la risposta sembra giusta, ma il database non è come dovrebbe. In questo capitolo sono quasi sempre uno di questi.

Il commit dimenticato (in una modifica o in una cancellazione). La rotta risponde 200 o 204, e il database non cambia. Se hai fatto add e refresh ti salva un errore (is not persistent); se hai cambiato un attributo o fatto delete, niente: la risposta mostra il treno già cambiato perché l'oggetto in memoria è cambiato. La prova del nove è sempre la stessa: guarda il database con psql -d db_sessione -c "SELECT …". Oppure accendi il server e guarda nel suo terminale: se non vedi la riga COMMIT, non è partita nessuna scrittura.

Il flush al posto del commit. Il database riceve il SQL (la riga INSERT compare nel terminale del server) ma non lo conferma: manca la riga COMMIT. La risposta è un perfetto 201, con l'id giusto, e il dato non c'è.

Il where che manca. Una select senza where non è un errore: torna tutta la tabella. Se una lista è più lunga del previsto, guarda la domanda con print(domanda): il SQL dice cosa chiedi davvero.

db.scalar su un campo che si ripete. Dà la prima riga e le altre le perde, senza dirti niente. Se vuoi tutte le righe, db.scalars(…).all().

L'ordine che non c'è. Senza order_by il database non promette nessun ordine: una volta le righe escono come le hai scritte, un'altra no. Se l'ordine conta, scrivilo.

Due cose che non sono errori, anche se sembrano:

  • db.scalars(…) senza .all() funziona: FastAPI scorre il risultato da solo. Tieni .all() per avere una lista vera.
  • Niente db.refresh dopo il commit funziona: l'oggetto si ricarica da solo quando lo leggi. Tienilo per chiarezza.

Come guardare cosa fa la sessione

Il modo più veloce per capire cosa succede è guardare il SQL. database.py ha echo=True: nel terminale del server, per ogni richiesta, vedi BEGIN, le SELECT, le INSERT o gli UPDATE o i DELETE, e infine COMMIT o ROLLBACK. Leggilo con queste domande:

Se nel terminale vedi…Vuol dire
BEGIN, SELECT …, ROLLBACKuna lettura, o una rotta che si è fermata prima di scrivere (un 404, un 409)
BEGIN, INSERT … o UPDATE … o DELETE …, COMMITuna scrittura confermata
BEGIN, INSERT …, ROLLBACKuna scrittura non confermata: manca il commit
nessun INSERT dopo il tuo addl'add c'è ma non è partito niente: senza commit (o flush) il SQL non viene nemmeno spedito

Per i test: pytest -v mostra quali sono rossi. Se un test di scrittura è rosso e la risposta sembra giusta, il problema è quasi sempre il commit.

Se il problema non è il codice

PostgreSQL non risponde nel terminale di pytest, connection failed: … No such file or directory, database "db_sessione" does not exist, pytest: command not found, No module named 'sqlalchemy': non è il tuo codice, è l'ambiente.

  • PostgreSQL spento: Mac brew services start postgresql@16, WSL sudo service postgresql start.
  • Il socket non si trova: Mac export PGHOST=/tmp, WSL export PGHOST=/var/run/postgresql.
  • Il venv è spento: source .venv/bin/activate, dalla cartella dello zip.

Tutto il resto, con le soluzioni passo per passo, è nel Pronto soccorso; per pytest e il venv in particolare: pytest non parte, o non trova niente.