Vai al contenuto
code-to-code

Apro l'indice…

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

Il database nell'API5. La sessionep. 99

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 vuoiCon psycopgCon la sessione
Un treno, dal suo idSELECT … WHERE id = %s e fetchone()db.get(TrenoDB, treno_id)
Tanti treni, in ordineSELECT … WHERE … ORDER BY e fetchall()db.scalars(select(TrenoDB).where(…).order_by(…)).all()
Un treno, da un altro campoSELECT … WHERE codice = %s e fetchone()db.scalar(select(TrenoDB).where(TrenoDB.codice == codice))
Un treno nuovoINSERT … RETURNING *db.add(treno), db.commit(), db.refresh(treno)
Cambiare un trenoUPDATE … RETURNING *treno.km = 0 e db.commit()
Togliere un trenoDELETE … RETURNING iddb.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:

Python
def get_db():
    """Apre una sessione, la presta alla rotta (yield) e alla fine la chiude."""
    with Session(engine) as db:
        yield db

Due 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».

Python
@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  ◀── FastAPI

Una 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 arrivaCome lo riconosciEsempio
Il percorsoil nome è tra graffe nell'indirizzotreno_id: int
La query (dopo il punto interrogativo)ha un valore predefinitosolo_aperte: bool = False
Il corpoè uno stampo Pydanticdati: TrenoNuovo
Dependsc'è 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

Python
treno = db.get(TrenoDB, 2)       # il treno con id 2: un oggetto TrenoDB
treno = db.get(TrenoDB, 99)      # nessun treno con id 99: None

db.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:

Python
treno = db.get(TrenoDB, treno_id)
if treno is None:
    raise HTTPException(status_code=404, detail="Treno non trovato")
return treno

Senza 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.

Python
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.km

Quel 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 PythonIn SQLCosa fa
select(TrenoDB)SELECT … FROM treniquale tabella
.where(TrenoDB.km >= 5000)WHERE km >= 5000quali righe
.order_by(TrenoDB.km)ORDER BY kmin 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:

Python
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 Nonecerchi 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:

Python
persona = db.scalar(select(PersonaDB).where(PersonaDB.badge == "B-09"))

Mossa 3 · add, commit, refresh: scrivere

Un treno nuovo si scrive in quattro righe:

Python
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'id

Il 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 riga
treno = TrenoDB(codice="M30", vagoni=5, km=0, in_servizio=False)trenoTrenoDBcodice"M30"vagoni5km0in_servizioFalse
Il treno dopo la prima riga, prima del commit
  • TrenoDB(…) crea l'oggetto. Non esiste ancora niente nel database, e treno.id vale None.
  • 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'id scelto 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.

Python
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

Python
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.

Python
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».

Python
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:

RottaCodiciLe mosse
GET /treni200db.scalars(select(…).order_by(…)).all()
GET /treni/{id}200, 404db.get, if … is None
POST /treni201, 409db.scalar di controllo, poi add, commit, refresh
PUT /treni/{id}200, 404, 409db.get, if … is None, controllo, cambia gli attributi, commit
DELETE /treni/{id}204, 404db.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: add mette dentro, commit consegna. Senza commit non arriva niente.
  • get_db la presta alla rotta, una per richiesta; Depends(get_db), senza parentesi, la chiede.
  • db.get cerca per id; select(…).where(…) cerca per tutto il resto. Dentro select e get va la classe-tabella (TrenoDB), mai lo stampo.
  • db.scalars(…).all() dà una lista, db.scalar(…) dà un oggetto o None: il 404 lo decidi tu, con un if.
  • Per cambiare: l'attributo e commit. Per togliere: db.delete(oggetto) e commit.