SQLAlchemy: le tabelle diventano classi
Una classe per ogni tabella, e il SQL lo scrive lui
- 15 minuti di lettura
Pietro Galli è il tecnico dei segnali della Linea Menta. Passa le giornate sugli schemi: ogni scambio, ogni semaforo ha il suo disegno, e il disegno dice com'è fatto senza essere lo scambio.
Guarda modelli.py e dice: «Una classe è lo schema di una tabella. Mica la tabella».
Ha ragione, ed è tutto il capitolo.
Cosa cambia rispetto a psycopg
Con psycopg il SQL lo scrivevi tu, in una stringa, e ogni riga tornava come dizionario:
treno = conn.execute("SELECT * FROM treni WHERE codice = %s", (codice,)).fetchone()
print(treno["codice"])Funziona. Ma il nome di una colonna è un pezzo di testo: se scrivi treno["codici"], Python lo scopre solo quando ci arriva, con un KeyError. E ogni query è una stringa che ti sei scritto da solo.
SQLAlchemy chiede un lavoro in più una volta sola: descrivi le tabelle come classi. Poi la riga diventa un oggetto, e le colonne diventano attributi:
| Nel database | In Python |
|---|---|
una tabella (treni) | una classe (TrenoDB) |
| una riga (il M12) | un oggetto (TrenoDB(codice="M12", ...)) |
una colonna (codice) | un attributo (treno.codice) |
Questo gioco si chiama ORM: Object-Relational Mapping. Un oggetto (O) in Python, una tabella relazionale (R) nel database, e un mapping (M), cioè una corrispondenza, che li tiene insieme. Non devi ricordare il nome inglese: ricorda che l'ORM fa da traduttore tra classi e tabelle.
POSTGRESQL PYTHON
tabella treni class TrenoDB(Base)
┌────┬────────┬────────┐
│ id │ codice │ vagoni │ ◀───▶ treno = TrenoDB(...) un oggetto
├────┼────────┼────────┤
│ 1 │ M10 │ 4 │ treno.id
│ 2 │ M12 │ 4 │ treno.codice
│ 3 │ M14 │ 6 │ treno.vagoni
└────┴────────┴────────┘
una riga i suoi attributimodelli.py, una riga alla volta
Apri palestra/modelli.py. Questa è la tabella dei treni, prima in SQL (da linea_menta.sql) e poi come classe:
CREATE TABLE treni (
id SERIAL PRIMARY KEY,
codice TEXT NOT NULL UNIQUE,
vagoni INTEGER NOT NULL CHECK (vagoni > 0),
km INTEGER NOT NULL DEFAULT 0 CHECK (km >= 0),
in_servizio BOOLEAN NOT NULL DEFAULT true,
stazione_id INTEGER REFERENCES stazioni(id)
);from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column
from database import Base
class TrenoDB(Base):
__tablename__ = "treni"
id: Mapped[int] = mapped_column(primary_key=True)
codice: Mapped[str] = mapped_column(unique=True)
vagoni: Mapped[int]
km: Mapped[int]
in_servizio: Mapped[bool]
stazione_id: Mapped[int | None] = mapped_column(ForeignKey("stazioni.id"))Una riga alla volta:
| Nella classe | Vuol dire | Nel CREATE TABLE |
|---|---|---|
class TrenoDB(Base) | Una classe figlia di Base (ereditarietà): essere figlia di Base la rende una tabella | CREATE TABLE treni |
__tablename__ = "treni" | Il nome della tabella nel database | treni |
id: Mapped[int] | Una colonna di numeri interi | INTEGER |
mapped_column(primary_key=True) | La chiave primaria | PRIMARY KEY |
Mapped[str] | Una colonna di testo | TEXT |
mapped_column(unique=True) | Nessun valore ripetuto | UNIQUE |
Mapped[bool] | Vero o falso | BOOLEAN |
Mapped[int | None] | Un numero oppure None | niente NOT NULL |
mapped_column(ForeignKey("stazioni.id")) | Questa colonna punta alla colonna id della tabella stazioni | REFERENCES stazioni(id) |
La regola per Mapped[...] è una sola: dentro le quadre c'è il tipo Python. Se la colonna può essere NULL, il tipo è «quel tipo oppure None», e si scrive int | None, come per i parametri opzionali delle rotte. Senza | None la colonna è NOT NULL.
Nei treni, stazione_id è l'unica che può essere NULL: un treno al deposito non è in nessuna stazione.
Due cose che la classe non sa:
- Il
DEFAULTdel database. La colonnakmhaDEFAULT 0nel SQL, maMapped[int]non lo dice. Un oggetto creato senzakmhakmuguale aNone, finché non viene salvato (lo vedi negli esercizi spiegati). - I controlli
CHECK.vagoni > 0lo controlla il database, e lo controlla Pydantic conField(gt=0). La classe non c'entra.
Le tre classi, e chi fa cosa
Fin qui è nuova solo la classe-tabella. Ma nelle rotte dei treni ne hai già due: gli stampi di Pydantic, che conosci dal capitolo su Pydantic. Ora sono tre, con nomi quasi uguali:
| Classe | Di chi è | A cosa serve | Ha l'id? |
|---|---|---|---|
TrenoNuovo | Pydantic (stampo) | Il corpo che arriva (POST, PUT): controlla i dati | No: lo sceglie il database |
TrenoDB | SQLAlchemy (classe-tabella) | La riga nella tabella treni: è lei che va nel database | Sì |
Treno | Pydantic (stampo) | La risposta che parte: cosa vede chi chiama | Sì |
Il nome dice a che mondo appartiene: DB in fondo vuol dire «questa è la tabella». Senza DB è uno stampo di Pydantic.
Il viaggio di un POST, con le tre classi:
chi chiama la tua rotta il database
JSON ───────▶ TrenoNuovo ───────▶ TrenoDB ───────▶ tabella treni
(il corpo) controlla i dati la riga nuova (INSERT)
JSON ◀─────── Treno ◀─────── TrenoDB ◀─────── tabella treni
(la risposta) ha anche l'id la riga salvata (SELECT)I dati cambiano abito tre volte: da JSON a stampo, da stampo a classe-tabella, e al ritorno al contrario. Tre abiti perché fanno tre mestieri: Pydantic controlla (il 422), SQLAlchemy parla con il database.
Per questo nei -> e nei parametri delle rotte vanno gli stampi, e dentro il corpo della rotta vive TrenoDB:
def nuovo_treno(dati: TrenoNuovo, db: Session = Depends(get_db)) -> Treno:
treno = TrenoDB(codice=dati.codice, vagoni=dati.vagoni, ...) # la riga nuovafrom_attributes
Gli stampi dei capitoli precedenti si riempivano da un dizionario: Treno(**riga). Ma da SQLAlchemy non arrivano dizionari: arrivano oggetti TrenoDB, e un oggetto non si legge con le quadre, si legge con il punto.
from_attributes=True dice a Pydantic: «puoi riempirti anche leggendo gli attributi di un oggetto». Sta nello stampo della risposta:
class Treno(TrenoNuovo):
model_config = ConfigDict(from_attributes=True)
id: intCon quella riga puoi scrivere Treno.model_validate(treno_db): Pydantic legge treno_db.codice, treno_db.vagoni, e costruisce lo stampo. Senza, model_validate si ferma con un ValidationError (lo vedi negli esercizi spiegati).
L'engine: la strada
Come fa SQLAlchemy a sapere con quale database parlare? Lo dice l'engine, che da qui in poi chiamiamo la strada: è la strada tra Python e PostgreSQL. È in palestra/database.py:
engine = create_engine(f"postgresql+psycopg:///{NOME_DB}", echo=True)La stringa, a pezzi:
postgresql+psycopg:///db_sqlalchemy
│ │ ││
│ │ │└── il nome del database, dopo l'ultima barra
│ │ └─── nessun computer scritto: questo computer (come connetti())
│ └───────────── il driver: sotto, a parlare con PostgreSQL è psycopg, quello di prima
└──────────────────────── il tipo di databaseTre barre: due sono l'indirizzo (//) e restano vuote, la terza apre il nome del database. Non c'è nessun utente e nessuna password: PostgreSQL si fida del tuo utente, come per psql.
L'engine non apre subito una connessione: aspetta la prima volta che serve. Per questo puoi importare modelli.py e creare oggetti TrenoDB anche con PostgreSQL spento.
NOME_DB si legge dalla variabile d'ambiente MENTA_DB, come in connetti(): i test la cambiano e lavorano sul database _test.
echo=True: il SQL dal vivo
L'ultimo pezzo, echo=True, è il più utile quando impari: SQLAlchemy ti scrive nel terminale il SQL che manda al database. Il SQL non sparisce: lo scrive lui, e tu puoi leggerlo.
Per vederlo senza scrivere niente, nello zip c'è palestra/centrale_sqlalchemy.py: la centrale dei treni già pronta, una scatola chiusa (ne scrivi le rotte nel capitolo sulla sessione). Accendila, e chiedi il M12 da un altro terminale:
fastapi dev palestra/centrale_sqlalchemy.py
curl http://127.0.0.1:8000/treni/2Nel terminale del server compare questo (ho tolto le tre domande di avvio che SQLAlchemy fa una volta sola, select pg_catalog.version() e le sue due sorelle, e le righe INFO del server):
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 ROLLBACKSi legge così:
| Riga | Vuol dire |
|---|---|
BEGIN (implicit) | Comincia una transazione: SQLAlchemy la apre da solo |
SELECT treni.id, treni.codice, ... | Il SQL scritto per te: tutte le colonne di TrenoDB, una per una |
FROM treni | La tabella: viene da __tablename__ |
WHERE treni.id = %(pk_1)s::INTEGER | Il valore non è dentro la query: c'è un buco con un nome, pk_1 («primary key, numero 1»). È il %s di psycopg, con un nome |
{'pk_1': 2} | Il valore che va nel buco: il 2 dell'indirizzo /treni/2 |
ROLLBACK | Fine: niente da consegnare, la transazione si chiude |
Il buco con il nome è la stessa difesa che hai visto con %s: i valori viaggiano separati dalla query, e un apostrofo o un ' OR '1'='1 non possono rompere il SQL.
Quando una rotta non va, echo=True è la prima cosa da guardare: ti dice cosa ha chiesto davvero SQLAlchemy.
Per vedere il SQL anche senza un server e senza database, basta stampare una domanda:
from sqlalchemy import select
print(select(TrenoDB).where(TrenoDB.codice == "M14"))(Lo provi negli esercizi spiegati.) La domanda stampata scrive i buchi come :codice_1; con PostgreSQL nel terminale del server li vedi come %(codice_1)s. È lo stesso buco.
Ricorda
- Una classe è lo schema di una tabella: un oggetto è una riga, un attributo è una colonna.
- La classe descrive la tabella, non la crea e non la cambia: se non coincide con il database, comanda il database.
Mapped[int]è un numeroNOT NULL;Mapped[int | None]può essereNULL.- Tre classi per ogni tabella:
TrenoNuovo(il corpo che arriva) eTreno(la risposta) sono stampi di Pydantic,TrenoDBè la riga nel database. from_attributes=Truefa leggere a Pydantic gli attributi di un oggetto, non solo le chiavi di un dizionario.- L'engine è la strada verso il database:
postgresql+psycopg:///nome_del_database. echo=Truestampa il SQL vero:BEGIN, la query con i suoi buchi,ROLLBACK.