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

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:

Python
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 databaseIn 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 attributi
treno = TrenoDB(id=2, codice="M12", vagoni=4)trenoTrenoDBid2codice"M12"vagoni4
Una riga della tabella, un oggetto

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

SQL
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)
);
Python
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 classeVuol direNel CREATE TABLE
class TrenoDB(Base)Una classe figlia di Base (ereditarietà): essere figlia di Base la rende una tabellaCREATE TABLE treni
__tablename__ = "treni"Il nome della tabella nel databasetreni
id: Mapped[int]Una colonna di numeri interiINTEGER
mapped_column(primary_key=True)La chiave primariaPRIMARY KEY
Mapped[str]Una colonna di testoTEXT
mapped_column(unique=True)Nessun valore ripetutoUNIQUE
Mapped[bool]Vero o falsoBOOLEAN
Mapped[int | None]Un numero oppure Noneniente NOT NULL
mapped_column(ForeignKey("stazioni.id"))Questa colonna punta alla colonna id della tabella stazioniREFERENCES 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 DEFAULT del database. La colonna km ha DEFAULT 0 nel SQL, ma Mapped[int] non lo dice. Un oggetto creato senza km ha km uguale a None, finché non viene salvato (lo vedi negli esercizi spiegati).
  • I controlli CHECK. vagoni > 0 lo controlla il database, e lo controlla Pydantic con Field(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:

ClasseDi chi èA cosa serveHa l'id?
TrenoNuovoPydantic (stampo)Il corpo che arriva (POST, PUT): controlla i datiNo: lo sceglie il database
TrenoDBSQLAlchemy (classe-tabella)La riga nella tabella treni: è lei che va nel databaseSì
TrenoPydantic (stampo)La risposta che parte: cosa vede chi chiamaSì

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:

Python
def nuovo_treno(dati: TrenoNuovo, db: Session = Depends(get_db)) -> Treno:
    treno = TrenoDB(codice=dati.codice, vagoni=dati.vagoni, ...)   # la riga nuova

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

Python
class Treno(TrenoNuovo):
    model_config = ConfigDict(from_attributes=True)
    id: int

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

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

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

Terminale
fastapi dev palestra/centrale_sqlalchemy.py
curl http://127.0.0.1:8000/treni/2

Nel 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 ROLLBACK

Si legge così:

RigaVuol 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 treniLa tabella: viene da __tablename__
WHERE treni.id = %(pk_1)s::INTEGERIl 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
ROLLBACKFine: 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:

Python
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 numero NOT NULL; Mapped[int | None] può essere NULL.
  • Tre classi per ogni tabella: TrenoNuovo (il corpo che arriva) e Treno (la risposta) sono stampi di Pydantic, TrenoDB è la riga nel database.
  • from_attributes=True fa 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=True stampa il SQL vero: BEGIN, la query con i suoi buchi, ROLLBACK.