SQLModel / SQLAlchemy

SQLAlchemy es el toolkit SQL y ORM fundamental de Python. SQLModel (del autor de FastAPI) superpone la validación Pydantic a los modelos SQLAlchemy para esquemas amigables con la API. Esta página orienta sobre lo esencial; la sección de bases de datos profundiza más.

Receta

from sqlmodel import Field, Session, SQLModel, create_engine, select
 
 
class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    secret_name: str
 
 
engine = create_engine("sqlite:///heroes.db")
SQLModel.metadata.create_all(engine)
 
with Session(engine) as session:
    session.add(Hero(name="Deadpond", secret_name="Dive"))
    session.commit()
    heroes = session.exec(select(Hero)).all()

Cuándo recurrir a esto:

• Servicios FastAPI que persisten en Postgres/MySQL/SQLite
• Compartir tipos entre filas de base de datos y modelos de respuesta de API
• Consultas complejas que necesitan la potencia de expresiones de SQLAlchemy
• Scripts adyacentes a Django que aún necesitan control SQL crudo

Ejemplo Funcional

from __future__ import annotations
 
from sqlmodel import Field, Session, SQLModel, create_engine, select
 
 
class Book(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    title: str
    author: str
    published_year: int
 
 
def seed(engine) -> None:
    with Session(engine) as session:
        session.add(Book(title="Neuromancer", author="Gibson", published_year=1984))
        session.commit()
 
 
def list_recent(engine, min_year: int) -> list[Book]:
    with Session(engine) as session:
        statement = select(Book).where(Book.published_year >= min_year).order_by(Book.title)
        return list(session.exec(statement))
 
 
if __name__ == "__main__":
    engine = create_engine("sqlite:///:memory:")
    SQLModel.metadata.create_all(engine)
    seed(engine)
    print(list_recent(engine, 1980))

Lo que esto demuestra:

• Una sola clase sirve como tabla ORM y modelo validado
• SQLAlchemy 2.0 select() + session.exec
• Sesión por unidad de trabajo con commit explícito
• SQLite en memoria para un ejemplo ejecutable

Profundización

Cómo Funciona

• Engine - Pool de conexiones a la URL de la base de datos.
• Session - Unidad de trabajo que rastrea objetos modificados; commit/rollback.
• SQLModel - table=True registra el mapeo ORM; sin él, la clase es un DTO solo Pydantic.
• SQLAlchemy Core - Table, insert(), update() cuando el ORM es demasiado pesado.

SQLModel vs SQLAlchemy Crudo

Notas de Python

# Modelos de lectura vs escritura en aplicaciones más grandes
class BookCreate(SQLModel):
    title: str
    author: str
 
class BookRead(BookCreate):
    id: int

Errores Comunes

• create_all en producción - Sin historial de migraciones. Solución: Revisiones de Alembic.
• Consultas N+1 - Carga perezosa en bucles. Solución: selectinload o joins explícitos.
• Suposiciones de SQLite en producción - Diferencias con el bloqueo/tipos de Postgres. Solución: probar contra el motor de producción en CI.
• Compartir sesión entre solicitudes - Condiciones de carrera. Solución: sesión por solicitud a través de la dependencia de FastAPI.
• Nullable sin Optional - Las pistas de tipo mienten. Solución: str | None coincide con columnas anulables.
• Tabla gigante de SQLModel - La API expone columnas de BD. Solución: esquemas Read/Create separados.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Bases de Datos - cobertura profunda de la capa de datos
• Alembic - migraciones de esquemas
• Rutas Asíncronas y Bases de Datos de FastAPI - patrones de AsyncSession
• Modelos y ORM de Django - alternativa de framework

Versiones de la Pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.