Vai al contenuto
code-to-code

Apro l'indice…

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

Il database nell'API4. SQLAlchemy: le tabelle diventano classip. 83

SQLAlchemy: esercizi spiegati

Cinque esempi, da provare in un file tuo

  • 25 minuti di lettura

Cinque esempi, dal più semplice. Ognuno ha lo stesso ritmo:

  1. Prevedi: leggi il codice e scrivi su un foglio cosa stampa. Prima di aprire la risposta.
  2. In italiano: cosa fa il programma, a parole.
  3. Passo per passo: cosa succede a ogni riga.
  4. Cosa portiamo a casa: la cosa da ricordare.

Per provarli ti serve lo zip della palestra, con il venv acceso e PostgreSQL acceso. Crea un file tuo dentro palestra/, per esempio palestra/prova.py, incolla il codice e lancialo dalla cartella dello zip:

Terminale
python palestra/prova.py

Il file sta in palestra/ perché lì ci sono modelli.py, stampi.py e database.py: Python li trova solo se sono nella stessa cartella del file che lanci.


A · La tabella dei treni, vista da Python

Pietro Galli vuole sapere se la classe TrenoDB descrive la tabella come il database: colonna per colonna.

Python
from modelli import TrenoDB

print(TrenoDB.__tablename__)
for colonna in TrenoDB.__table__.columns:
    print(colonna.name, colonna.type, "NULL" if colonna.nullable else "NOT NULL")
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
treni
id INTEGER NOT NULL
codice VARCHAR NOT NULL
vagoni INTEGER NOT NULL
km INTEGER NOT NULL
in_servizio BOOLEAN NOT NULL
stazione_id INTEGER NULL
  • La prima riga è il nome della tabella, da __tablename__.
  • Poi una riga per colonna, nell'ordine in cui le hai scritte nella classe.
  • Mapped[str] diventa VARCHAR, mentre nel CREATE TABLE c'è TEXT. In PostgreSQL i due si comportano allo stesso modo, e comunque la classe non crea niente: descrive.
  • Solo stazione_id è NULL: è l'unica con int | None.

In italiano. Ogni classe-tabella ha dietro un oggetto con l'elenco delle sue colonne (__table__.columns). Lo scorro e per ognuna stampo il nome, il tipo e se può essere NULL.

Passo per passo.

Riga della classeCosa stampa
id: Mapped[int] = mapped_column(primary_key=True)id INTEGER NOT NULL
codice: Mapped[str] = mapped_column(unique=True)codice VARCHAR NOT NULL
km: Mapped[int]km INTEGER NOT NULL
stazione_id: Mapped[int | None] = ...stazione_id INTEGER NULL

Cosa portiamo a casa. La classe si legge come uno schema: per ogni colonna, il tipo e se può mancare. È la stessa informazione di \d treni in psql.


B · Un treno che non è ancora nel database

Ernesto Pozzi, il capo deposito, sta per mettere in linea il M30. Creiamo l'oggetto.

Python
from modelli import TrenoDB

treno = TrenoDB(codice="M30", vagoni=5, in_servizio=True)
print(treno.codice, treno.vagoni)
print(treno.id)
print(treno.km)
treno.km = 120
print(treno.km)
TrenoDB(codice="M31", vagoni=5, carrozze=2)
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
M30 5
None
None
120

E poi un traceback lungo, che finisce con:

TypeError: 'carrozze' is an invalid keyword argument for TrenoDB
  • Riga 1: gli attributi che hai dato ci sono.
  • Riga 2: l'id lo sceglie il database quando salva. Per ora è None.
  • Riga 3: km non lo hai dato, e la classe non conosce il DEFAULT 0 del database. Quindi None.
  • Riga 4: un attributo si cambia con =, come in ogni oggetto.
  • Ultima riga: carrozze non è una colonna di TrenoDB. Un nome che la classe non conosce è un TypeError.
treno = TrenoDB(id=None, codice="M30", vagoni=5, km=120, in_servizio=True, stazione_id=None)trenoTrenoDBidNonecodice"M30"vagoni5km120in_servizioTruestazione_idNone
L'oggetto dopo treno.km = 120

In italiano. Creo un oggetto TrenoDB dando solo alcune colonne. Gli attributi che non do restano None. Non ho chiesto niente al database: l'oggetto vive nella memoria di Python, come qualsiasi altro.

Passo per passo.

RigaCosa c'è nell'oggetto trenoE nel database?
TrenoDB(codice="M30", ...)codice M30, vagoni 5, in_servizio vero; id, km, stazione_id sono Noneniente: nessuna riga in più
treno.km = 120anche km vale 120ancora niente
TrenoDB(..., carrozze=2)l'oggetto non nasce: erroreniente

Cosa portiamo a casa. Creare un oggetto non salva niente: è come scrivere un cartoncino senza consegnarlo. Per mandarlo nel database ci vuole la sessione, ed è il capitolo dopo. E il nome di un attributo che non esiste ti ferma subito, con un errore chiaro: meglio di un KeyError su una stringa.


C · Che SQL scrive SQLAlchemy?

Python
from sqlalchemy import select

from modelli import TrenoDB

tutti = select(TrenoDB)
print(tutti)
print()
m14 = select(TrenoDB).where(TrenoDB.codice == "M14")
print(m14)
print(m14.compile().params)
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
SELECT treni.id, treni.codice, treni.vagoni, treni.km, treni.in_servizio, treni.stazione_id 
FROM treni

SELECT treni.id, treni.codice, treni.vagoni, treni.km, treni.in_servizio, treni.stazione_id 
FROM treni 
WHERE treni.codice = :codice_1
{'codice_1': 'M14'}
  • select(TrenoDB) non ha una *: elenca tutte le colonne della classe, una per una. Il FROM viene da __tablename__.
  • .where(TrenoDB.codice == "M14") diventa WHERE treni.codice = .... Il == qui non confronta niente: costruisce un pezzo di SQL.
  • Il "M14" non è nella query: c'è un buco, :codice_1. Il nome è la colonna più un numero.
  • compile().params mostra cosa va nel buco: {'codice_1': 'M14'}.

In italiano. select(TrenoDB) è «tutte le righe della tabella dei treni». where aggiunge un filtro. Stampare la domanda non la esegue: la domanda è solo un oggetto, e print ne mostra il SQL. Non hai toccato il database.

Passo per passo.

Pezzo di PythonPezzo di SQL
select(TrenoDB)SELECT treni.id, treni.codice, ... e FROM treni
TrenoDB.codice (la colonna, scritta sulla classe)treni.codice
== "M14"= :codice_1, con il valore messo da parte

C'è una cosa da notare: TrenoDB.codice scritto sulla classe è la colonna; treno.codice scritto su un oggetto è il valore di quella riga. Lo stesso nome, due usi.

Ecco cosa succede se nel select metti per sbaglio lo stampo:

Python
from sqlalchemy import select

from stampi import Treno

select(Treno)
ArgumentError
Column expression, FROM clause, or other columns clause element expected, got <class 'stampi.Treno'>.

(Qui ho stampato il nome dell'errore e il messaggio, senza il traceback.) Treno è uno stampo, non una tabella: SQLAlchemy non sa da quale tabella leggere.

Cosa portiamo a casa. select vuole la classe-tabella, quella con DB. E per capire cosa chiederà al database, basta print.


D · Tre classi, un treno

Python
from modelli import TrenoDB
from stampi import Treno, TrenoNuovo

treno_db = TrenoDB(id=7, codice="M30", vagoni=5, km=0, in_servizio=True)
treno = Treno.model_validate(treno_db)
print(treno)
print(treno.model_dump())
print(type(treno_db).__name__, type(treno).__name__)

try:
    TrenoNuovo.model_validate(treno_db)
except Exception as errore:
    print(type(errore).__name__)
    print(errore)
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
codice='M30' vagoni=5 km=0 in_servizio=True stazione_id=None id=7
{'codice': 'M30', 'vagoni': 5, 'km': 0, 'in_servizio': True, 'stazione_id': None, 'id': 7}
TrenoDB Treno
ValidationError
1 validation error for TrenoNuovo
  Input should be a valid dictionary or instance of TrenoNuovo [type=model_type, input_value=<modelli.TrenoDB object at 0x1042576b0>, input_type=TrenoDB]
    For further information visit https://errors.pydantic.dev/2.14/v/model_type
  • Treno.model_validate(treno_db) legge gli attributi dell'oggetto e costruisce lo stampo: ha from_attributes=True. Lo stampo ha anche l'id.
  • model_dump() lo trasforma in un dizionario: è quello che FastAPI poi manda come JSON.
  • I due oggetti sono di classi diverse: TrenoDB (la riga) e Treno (la risposta).
  • TrenoNuovo non ha from_attributes: Pydantic si aspetta un dizionario o un TrenoNuovo, e un TrenoDB non è nessuno dei due. ValidationError. (L'indirizzo 0x1042576b0 sul tuo computer sarà diverso.)
treno_db = TrenoDB(id=7, codice="M30", vagoni=5, km=0, in_servizio=True) treno = Treno(codice="M30", vagoni=5, km=0, in_servizio=True, stazione_id=None, id=7)treno_dbtrenoTrenoDBid7codice"M30"vagoni5km0in_servizioTrueTrenocodice"M30"vagoni5km0in_servizioTruestazione_idNoneid7
Una riga, e lo stampo che ne esce

In italiano. Parto da una riga come la vede SQLAlchemy (TrenoDB). La passo allo stampo della risposta (Treno), che la legge con il punto. Per mostrare la differenza, lo stesso tentativo con lo stampo del corpo (TrenoNuovo) fallisce: lui è fatto per riempirsi da un JSON, non da una riga.

Passo per passo.

RigaCosa succede
TrenoDB(id=7, ...)Un oggetto-riga. L'id lo diamo noi, solo per l'esempio
Treno.model_validate(treno_db)Pydantic legge treno_db.codice, treno_db.vagoni... e riempie lo stampo
model_dump()Dallo stampo a un dizionario, pronto per il JSON
TrenoNuovo.model_validate(treno_db)Niente from_attributes: ValidationError

Cosa portiamo a casa. Il lavoro delle tre classi: TrenoDB è la riga, Treno è la riga vestita per uscire, TrenoNuovo è il corpo che entra. from_attributes serve proprio per il passaggio da TrenoDB a Treno.


E · Il SQL dal vivo, con echo=True

Accendi la centrale già pronta e fai tre richieste: un treno che c'è, uno che non c'è, la lista di quelli fuori servizio.

Terminale
fastapi dev palestra/centrale_sqlalchemy.py
Terminale
curl http://127.0.0.1:8000/treni/2
curl -i http://127.0.0.1:8000/treni/99
curl "http://127.0.0.1:8000/treni?in_servizio=false"
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.

Prima di guardare, rispondi: nel terminale del server, per la richiesta del treno 99, quale SELECT compare? Cambia qualcosa rispetto a quella del treno 2?

$ curl http://127.0.0.1:8000/treni/2
{"codice":"M12","vagoni":4,"km":4800,"in_servizio":true,"stazione_id":5,"id":2}

$ curl -i http://127.0.0.1:8000/treni/99
HTTP/1.1 404 Not Found
date: Thu, 19 Nov 2026 18:02:53 GMT
server: uvicorn
content-length: 30
content-type: application/json

{"detail":"Treno non trovato"}

$ curl "http://127.0.0.1:8000/treni?in_servizio=false"
[{"codice":"M18","vagoni":4,"km":7100,"in_servizio":false,"stazione_id":null,"id":5},{"codice":"M20","vagoni":6,"km":0,"in_servizio":false,"stazione_id":null,"id":6},{"codice":"T28","vagoni":2,"km":900,"in_servizio":false,"stazione_id":6,"id":9}]

E nel terminale del server (tolte le tre domande di avvio, le righe INFO del server e la terza richiesta):

2026-11-19 19:02:53,589 INFO sqlalchemy.engine.Engine BEGIN (implicit)
2026-11-19 19:02:53,591 INFO sqlalchemy.engine.Engine SELECT treni.id, treni.codice, treni.vagoni, treni.km, treni.in_servizio, treni.stazione_id 
FROM treni 
WHERE treni.id = %(pk_1)s::INTEGER
2026-11-19 19:02:53,591 INFO sqlalchemy.engine.Engine [generated in 0.00007s] {'pk_1': 2}
2026-11-19 19:02:53,593 INFO sqlalchemy.engine.Engine ROLLBACK
2026-11-19 19:02:53,604 INFO sqlalchemy.engine.Engine BEGIN (implicit)
2026-11-19 19:02:53,605 INFO sqlalchemy.engine.Engine SELECT treni.id, treni.codice, treni.vagoni, treni.km, treni.in_servizio, treni.stazione_id 
FROM treni 
WHERE treni.id = %(pk_1)s::INTEGER
2026-11-19 19:02:53,605 INFO sqlalchemy.engine.Engine [cached since 0.01405s ago] {'pk_1': 99}
2026-11-19 19:02:53,605 INFO sqlalchemy.engine.Engine ROLLBACK
  • Il SELECT è lo stesso: cambia solo il valore nel buco, {'pk_1': 2} contro {'pk_1': 99}.
  • La seconda volta SQLAlchemy dice cached since: ha già scritto quel SQL e lo riusa, cambia solo il numero.
  • Per il 99 il database non trova niente: la rotta risponde 404, ma la domanda al database era giusta.
  • Ogni richiesta ha il suo BEGIN (implicit) e il suo ROLLBACK: nessuna scrive, quindi non c'è niente da consegnare.

In italiano. Ogni richiesta apre una transazione, manda una domanda con il valore separato dalla query, chiude. Il 404 non è un errore del database: il database ha risposto «nessuna riga», e la rotta ha deciso di dire 404.

Per la terza richiesta, la lista dei fuori servizio, la query ha WHERE treni.in_servizio = false ORDER BY treni.id: il filtro è venuto dal ?in_servizio=false, e l'ordine è dell'id.

Passo per passo. Quando una rotta ti sorprende, leggi echo=True così:

  1. Guarda la riga SELECT o INSERT: è quello che SQLAlchemy ha chiesto davvero?
  2. Guarda il FROM: è la tabella giusta?
  3. Guarda il WHERE e le parentesi graffe {'pk_1': ...} dopo la query: i valori sono quelli che pensavi?
  4. L'ultima parola è ROLLBACK o COMMIT? (COMMIT vuol dire che qualcosa è stato salvato: per le rotte che scrivono lo vedrai nel capitolo dopo.)

Cosa portiamo a casa. Non devi indovinare cosa fa SQLAlchemy: te lo scrive lui, riga per riga. Il SQL lo conoscevi già dal libro SQL: qui lo leggi e basta.