¿Cómo integras una base de datos SQL con FastAPI?

Question

Accepted Answer

A diferencia de Django, FastAPI es **agnóstico** respecto a las bases de datos — tú eliges la librería. La opción común es **SQLAlchemy** (a menudo con **SQLModel**, del autor de FastAPI, que combina SQLAlchemy + Pydantic). Las sesiones de base de datos se proporcionan mediante inyección de dependencias.

## Configuración de 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)
```

## Proporcionar la sesión de BD mediante una dependencia

```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
```

El patrón de dependencia `yield` es la forma estándar de gestionar sesiones: abrir una por solicitud, inyectarla y cerrarla automáticamente después — cada endpoint obtiene una sesión limpia y correctamente cerrada.

## SQLModel — SQLAlchemy + Pydantic en 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 el modelo ORM y el modelo Pydantic en una sola clase — reduciendo la duplicación entre la base de datos y los esquemas de la API.

## Migraciones y opciones asincrónicas

```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)
```

## Por qué es importante

La integración de bases de datos es esencial para casi cualquier API real, y dado que FastAPI es deliberadamente **agnóstico** al respecto (a diferencia del ORM integrado de Django), entender el enfoque común es un conocimiento práctico importante.

El patrón estándar — **SQLAlchemy** (o **SQLModel**, que unifica elegantemente el ORM y los modelos Pydantic para reducir la duplicación) con **sesiones inyectadas mediante dependencias** a través del patrón `yield` — es lo que utiliza casi todas las aplicaciones FastAPI para persistir datos.

La dependencia de sesión por solicitud (abrir antes, cerrar después, automáticamente) es la forma idiomática y correcta de gestionar conexiones de base de datos, y la unificación de SQLModel entre la base de datos y los esquemas de la API es una característica notable de productividad del propio autor de FastAPI.

Saber cómo configurar la base de datos, proporcionar sesiones a través de DI, realizar consultas y manejar migraciones (Alembic) y la advertencia asincrónica (usar drivers asincrónico en endpoints asincrónico, nunca bloquear los sincrónico) es necesario para construir aplicaciones FastAPI orientadas a datos — dado que FastAPI te da la libertad de elegir, conocer el camino convencional y bien trillado es valioso para construir aplicaciones reales correctamente.