La sessione
Il carrello tra l'API e il database
- 15 minuti di lettura
Ernesto Pozzi, il capo deposito, non porta i ricambi al treno uno alla volta. Li carica su un carrello: una guarnizione, un fusibile, un faro. Quando il carrello è pieno, lo spinge fino al treno. Se il carrello resta in magazzino, al treno non arriva niente, e nessuno se ne accorge finché il treno non si ferma.
Con SQLAlchemy funziona uguale. Il carrello si chiama sessione: ci metti dentro quello che vuoi leggere, scrivere, cambiare o togliere, e il database lo riceve solo quando lo dici tu.
Questo capitolo è il più importante del libro: è qui che la tua API smette di scrivere SQL e comincia a parlare con le classi. Ci sono sei mosse da imparare. Sono poche, e tornano sempre.
Si dà per letto il capitolo SQLAlchemy: le tabelle diventano classi: TrenoDB, modelli.py, l'engine. E il capitolo Le rotte con psycopg: le stesse cinque rotte, con il SQL scritto a mano.
Con psycopg e con la sessione
Le rotte sono le stesse, i codici sono gli stessi, i test sono gli stessi. Cambia chi scrive il SQL.
| Cosa vuoi | Con psycopg | Con la sessione |
|---|---|---|
| Un treno, dal suo id | SELECT … WHERE id = %s e fetchone() | db.get(TrenoDB, treno_id) |
| Tanti treni, in ordine | SELECT … WHERE … ORDER BY e fetchall() | db.scalars(select(TrenoDB).where(…).order_by(…)).all() |
| Un treno, da un altro campo | SELECT … WHERE codice = %s e fetchone() | db.scalar(select(TrenoDB).where(TrenoDB.codice == codice)) |
| Un treno nuovo | INSERT … RETURNING * | db.add(treno), db.commit(), db.refresh(treno) |
| Cambiare un treno | UPDATE … RETURNING * | treno.km = 0 e db.commit() |
| Togliere un treno | DELETE … RETURNING id | db.delete(treno) e db.commit() |
Il with connetti() as conn: sparisce dalle rotte. Al suo posto, un parametro in più: la sessione, che si chiama db. Da dove arriva?
La sessione in prestito
Apri palestra/database.py. In fondo c'è questa funzione:
def get_db():
"""Apre una sessione, la presta alla rotta (yield) e alla fine la chiude."""
with Session(engine) as db:
yield dbDue cose nuove: yield e Depends.
yield è come un return che non chiude la funzione. La funzione dà db a chi l'ha chiamata, resta in pausa, e quando chi l'ha chiamata ha finito riparte da dopo il yield. Qui, da dopo il yield, il with finisce e la sessione si chiude. Apri, presta, chiudi: tutto in una funzione sola.
Depends è il modo di dire a FastAPI: «questo parametro non arriva dal client, procuratelo tu chiamando questa funzione».
@app.get("/treni/{treno_id}")
def leggi_treno(treno_id: int, db: Session = Depends(get_db)) -> Treno:
...Così FastAPI, a ogni richiesta, fa questo:
richiesta ──▶ FastAPI
│ 1. chiama get_db: apre una sessione
│ 2. la passa alla tua rotta, nel parametro db
▼
la tua rotta db.get(…), db.add(…), db.commit(…)
│
│ 3. la rotta ha finito: get_db riparte da dopo il yield
▼ e la sessione si chiude
risposta ◀── FastAPIUna sessione per richiesta: nasce quando arriva, muore quando la risposta parte. Due richieste insieme hanno due sessioni diverse, e non si pestano i piedi.
Un parametro di una rotta può arrivare da posti diversi. Con Depends ce n'è uno in più:
| Da dove arriva | Come lo riconosci | Esempio |
|---|---|---|
| Il percorso | il nome è tra graffe nell'indirizzo | treno_id: int |
| La query (dopo il punto interrogativo) | ha un valore predefinito | solo_aperte: bool = False |
| Il corpo | è uno stampo Pydantic | dati: TrenoNuovo |
| Depends | c'è Depends(…) | db: Session = Depends(get_db) |
I primi tre li conosci dal capitolo La forma della chiamata. Il quarto non viene dal client: lo prepara FastAPI.
Mossa 1 · get: un oggetto, dalla chiave primaria
treno = db.get(TrenoDB, 2) # il treno con id 2: un oggetto TrenoDB
treno = db.get(TrenoDB, 99) # nessun treno con id 99: Nonedb.get vuole due cose: la classe-tabella (TrenoDB, non lo stampo Treno) e la chiave primaria, cioè l'id. Dà l'oggetto, oppure None.
Il None è il 404 di sempre. Lo decidi tu:
treno = db.get(TrenoDB, treno_id)
if treno is None:
raise HTTPException(status_code=404, detail="Treno non trovato")
return trenoSenza l'if, il programma va avanti con un None in mano. Il return restituisce None, e la risposta non è un treno: ResponseValidationError, e il client riceve un 500.
Mossa 2 · select e where: una domanda
db.get cerca solo per id. Per tutto il resto serve una domanda: si scrive con select.
from sqlalchemy import select
domanda = select(TrenoDB).where(TrenoDB.km >= 5000).order_by(TrenoDB.km)
print(domanda)SELECT treni.id, treni.codice, treni.vagoni, treni.km, treni.in_servizio, treni.stazione_id
FROM treni
WHERE treni.km >= :km_1 ORDER BY treni.kmQuel print mostra che la domanda è SQL scritto da SQLAlchemy. Ma attenzione: a questo punto non è successo niente. Una select è solo una domanda scritta: non è ancora stata fatta al database. Per farla serve la sessione.
Dentro select(...) ci va la classe-tabella: select(TrenoDB). Se per sbaglio ci scrivi lo stampo (select(Treno)) ottieni ArgumentError: Column expression, FROM clause, or other columns clause element expected.
Le tre parti si leggono come il SQL:
| In Python | In SQL | Cosa fa |
|---|---|---|
select(TrenoDB) | SELECT … FROM treni | quale tabella |
.where(TrenoDB.km >= 5000) | WHERE km >= 5000 | quali righe |
.order_by(TrenoDB.km) | ORDER BY km | in che ordine |
Con più condizioni nel where, separate da virgola, valgono tutte insieme (è un AND): .where(TrenoDB.in_servizio, TrenoDB.km > 1000). Per una colonna già vera o falsa, come in_servizio, basta il nome della colonna, senza confronti.
Poi la domanda si esegue. Quasi sempre con una di queste due:
treni = db.scalars(domanda).all() # una lista di oggetti TrenoDB (anche vuota)
treno = db.scalar(select(TrenoDB).where(TrenoDB.codice == "M20")) # un oggetto, oppure None| Cosa dà | Quando | |
|---|---|---|
db.scalars(domanda).all() | una lista di oggetti (vuota se non trova niente) | le rotte che elencano |
db.scalar(domanda) | un oggetto, il primo, oppure None | cerchi per un campo che non si ripete (codice, badge) |
Perché «scalar»? Perché una riga di risultato, per il database, è una riga con delle colonne. scalars dice: «di ogni riga, dammi solo il primo pezzo, cioè l'oggetto TrenoDB». Se usi db.execute(domanda).all() ricevi le righe intere, ognuna con dentro un solo oggetto: la risposta della rotta non si valida più (Field required per ogni campo).
E quando non basta get, perché la domanda non è sull'id? Un badge è un testo ("B-09"), non l'id: db.get(PersonaDB, "B-09") non funziona (DataError: invalid input syntax for type integer: "B-09"). Serve il where:
persona = db.scalar(select(PersonaDB).where(PersonaDB.badge == "B-09"))Mossa 3 · add, commit, refresh: scrivere
Un treno nuovo si scrive in quattro righe:
treno = TrenoDB(codice="M30", vagoni=5, km=0, in_servizio=False) # 1. l'oggetto, ancora solo in Python
db.add(treno) # 2. nel carrello
db.commit() # 3. il carrello parte: INSERT e conferma
db.refresh(treno) # 4. riprendi l'oggetto dal database, con l'idIl carrello, riga per riga:
il tuo codice la sessione (il carrello) il database
treno = TrenoDB(…) vuoto niente
db.add(treno) [ treno ] niente
db.commit() vuoto ─ INSERT, COMMIT ─▶ la riga c'è
db.refresh(treno) treno, con l'id ◀─── SELECT ─────── la rigaTrenoDB(…)crea l'oggetto. Non esiste ancora niente nel database, etreno.idvaleNone.db.add(treno)lo mette nel carrello. Ancora niente nel database.db.commit()lo consegna: parte l'INSERT, e il database conferma. Solo adesso la riga esiste, e resta anche se spegni il server.db.refresh(treno)rilegge la riga dal database. Serve per riavere l'idscelto dal database, e tutti i valori di partenza.
La mossa che non si può dimenticare è il commit. Senza, il carrello non parte: la sessione si chiude, il contenuto viene buttato, e nel database non arriva niente. Nessun errore. Lo vedi nell'esempio C degli esercizi spiegati.
Mossa 4 · Cambiare: un attributo e commit
Per cambiare un treno non serve nessun update: prendi l'oggetto, cambi un attributo con il punto, fai il commit.
treno = db.get(TrenoDB, 9)
treno.stazione_id = 2
db.commit()La sessione si accorge da sola che l'oggetto è cambiato, e al commit scrive solo la colonna cambiata. Niente add: l'oggetto è già nella sessione, perché l'hai letto da lì. Di nuovo: senza commit la risposta mostra il treno spostato, ma il database non lo sa.
Mossa 5 · Togliere: delete e commit
treno = db.get(TrenoDB, 10)
db.delete(treno)
db.commit()db.delete vuole un oggetto, non un id. Prima lo trovi (e se non c'è, 404), poi lo togli. Se gli passi None ottieni UnmappedInstanceError: Class 'builtins.NoneType' is not mapped: è la stessa dimenticanza dell'if sul 404.
Quando il database dice di no
Se un codice è già usato, o un treno ha segnalazioni, il database dice di no. In una rotta lo trasformi in un 409. Il modo più semplice: guardi prima di scrivere, con una db.scalar di controllo.
gemello = db.scalar(select(TrenoDB).where(TrenoDB.codice == dati.codice))
if gemello is not None:
raise HTTPException(status_code=409, detail="Codice già usato da un altro treno")Se gemello c'è, non scrivi niente. È il controllo che usa la centrale: lo trovi nel file palestra/centrale_sqlalchemy.py.
Per un controllo sull'altro treno nel PUT ci vuole un pezzo in più: il codice è «già usato» solo se è di un treno diverso da quello che stai aggiornando (TrenoDB.id != treno_id nel where).
C'è anche l'altra strada: scrivi e, se il database dice di no, lo prendi. Dopo l'errore la sessione è da rimettere a posto con db.rollback(), cioè «butta il carrello».
db.add(persona)
try:
db.commit()
except IntegrityError:
db.rollback()
raise HTTPException(status_code=409, detail="Badge già usato da un'altra persona")Senza il rollback, la prossima domanda sulla stessa sessione dà PendingRollbackError: This Session's transaction has been rolled back due to a previous exception during flush. L'IntegrityError viene da sqlalchemy.exc.
Quale scegliere? Il controllo prima è più facile da leggere, ed è quello che usi negli esercizi. Ma ha un buco: se due richieste con lo stesso codice arrivano nello stesso istante, passano entrambe il controllo. Il vincolo UNIQUE del database invece non si lascia battere: è il giudice finale. Per ora ti basta il controllo; quando scrivi qualcosa di serio, ricordati che dietro c'è anche l'IntegrityError.
Lo schema da copiare
Le cinque rotte di ogni risorsa si scrivono sempre allo stesso modo:
| Rotta | Codici | Le mosse |
|---|---|---|
GET /treni | 200 | db.scalars(select(…).order_by(…)).all() |
GET /treni/{id} | 200, 404 | db.get, if … is None |
POST /treni | 201, 409 | db.scalar di controllo, poi add, commit, refresh |
PUT /treni/{id} | 200, 404, 409 | db.get, if … is None, controllo, cambia gli attributi, commit |
DELETE /treni/{id} | 204, 404 | db.get, if … is None, db.delete, commit |
E in ogni rotta, sempre, lo stesso primo parametro: db: Session = Depends(get_db).
Ricorda
- La sessione è il carrello:
addmette dentro,commitconsegna. Senzacommitnon arriva niente. get_dbla presta alla rotta, una per richiesta;Depends(get_db), senza parentesi, la chiede.db.getcerca perid;select(…).where(…)cerca per tutto il resto. Dentroselectegetva la classe-tabella (TrenoDB), mai lo stampo.db.scalars(…).all()dà una lista,db.scalar(…)dà un oggetto oNone: il 404 lo decidi tu, con unif.- Per cambiare: l'attributo e
commit. Per togliere:db.delete(oggetto)ecommit.