Come si integra un database SQL con FastAPI?

Question

Accepted Answer

A differenza di Django, FastAPI è **agnostico** rispetto ai database — scegli tu la libreria. La scelta comune è **SQLAlchemy** (spesso con **SQLModel**, dell'autore di FastAPI, che unisce SQLAlchemy + Pydantic). Le sessioni del database sono fornite tramite dependency injection.

## Setup di SQLAlchemy

```python
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

engine = create_engine("postgresql://user:pass@localhost/db")
SessionLocal = sessionmaker(bind=engine)
Base = declarative_base()

class User(Base):                        # an ORM model (maps to a table)
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String, unique=True)
```

## Fornire la sessione del DB tramite una dependency

```python
def get_db():
    db = SessionLocal()
    try:
        yield db                 # provide the session
    finally:
        db.close()               # ALWAYS close after the request (cleanup)

@app.get("/users/{id}")
def get_user(id: int, db: Session = Depends(get_db)):   # inject a session per request
    user = db.query(User).filter(User.id == id).first()
    if not user:
        raise HTTPException(404, "Not found")
    return user
```

Il pattern della dependency con `yield` è il modo standard per gestire le sessioni: apri una per richiesta, iniettala, e chiudila automaticamente dopo — ogni endpoint ottiene una sessione pulita e correttamente chiusa.

## SQLModel — SQLAlchemy + Pydantic in uno

```python
from sqlmodel import SQLModel, Field, Session, select

class User(SQLModel, table=True):        # ONE class = ORM model AND Pydantic model
    id: int | None = Field(default=None, primary_key=True)
    name: str
    email: str

@app.get("/users")
def list_users(db: Session = Depends(get_session)):
    return db.exec(select(User)).all()    # query; results are also valid response models
```

SQLModel unifica il modello ORM e il modello Pydantic in un'unica classe — riducendo la duplicazione tra il database e gli schemi dell'API.

## Migrazioni e opzioni async

```text
✓ Migrations: use Alembic (SQLAlchemy's migration tool) for schema changes
✓ Async: use SQLAlchemy's async engine + async session for async endpoints
  (don't use a SYNC database driver inside async def — it blocks the event loop)
```

## Perché è importante

L'integrazione del database è essenziale per quasi qualsiasi API reale, e poiché FastAPI è deliberatamente **agnostico** (a differenza dell'ORM built-in di Django), comprendere l'approccio comune è una conoscenza pratica importante.

Il pattern standard — **SQLAlchemy** (o **SQLModel**, che unisce elegantemente il modello ORM e Pydantic per ridurre la duplicazione) con **sessioni iniettate tramite dependency injection** tramite il pattern `yield` — è quello che quasi ogni app FastAPI utilizza per persistere i dati.

La dependency session-per-richiesta (apri prima, chiudi dopo, automaticamente) è il modo idiomatico e corretto per gestire le connessioni al database, e l'unificazione di SQLModel tra database e schemi dell'API è una notevole feature di produttività dell'autore di FastAPI.

Sapere come configurare il database, fornire sessioni tramite DI, eseguire query, e gestire le migrazioni (Alembic) e il caveat async (usare driver async in endpoint async, mai bloccare quelli sync) è necessario per costruire applicazioni FastAPI basate sui dati — poiché FastAPI ti dà la libertà di scegliere, conoscere il percorso convenzionale e ben consolidato è prezioso per costruire app reali correttamente.