SQLAlchemy Modelos — Diseño de tablas de base de datos

En este capítulo aprenderás a definir modelos de datos con el ORM nativo de SQLAlchemy y a gestionar las sesiones de base de datos mediante la inyección de dependencias de FastAPI.


¿Por qué FastAPI no trae su propio ORM?

Django tiene un ORM integrado, Flask recomienda Flask-SQLAlchemy.

FastAPI no tiene un ORM integrado: espera que elijas la herramienta más adecuada,SQLAlchemy + Pydantices la combinación reconocida por la comunidad como la mejor.

(venv) $ pip install sqlalchemy

Configurar la conexión a la base de datos

Ejemplo

# Ruta del archivo: database.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, DeclarativeBase

# Ruta del archivo de base de datos SQLite
SQLALCHEMY_DATABASE_URL = "sqlite:///./blog.db"

# Crear el motor: check_same_thread es un parámetro específico de SQLite
engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    connect_args={"check_same_thread": False}   # Específico de SQLite: permite el uso entre hilos
)

# Crear la fábrica de sesiones
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# Clase Base: todos los modelos ORM heredan de ella
class Base(DeclarativeBase):
    pass

check_same_thread=Falsees una configuración necesaria de SQLite en FastAPI. Por defecto, SQLite no permite usar la misma conexión entre hilos, pero en una aplicación web cada solicitud puede procesarse en un hilo diferente.

Inyección de dependencias: get_db

Ejemplo

# Ruta del archivo: agregar a database.py
from fastapi import Depends

def get_db():
    """Inyección de dependencias de FastAPI: crear una sesión de base de datos independiente para cada solicitud"""
    db = SessionLocal()
    try:
        yield db          # Usar esta sesión durante la solicitud
    finally:
        db.close()        # Cerrar la sesión automáticamente al finalizar la solicitud para evitar fugas de conexión

Depends(get_db)es el sistema de inyección de dependencias de FastAPI; las funciones de ruta obtienen automáticamente la sesión de base de datos mediante la inyección de dependencias.


Definir modelos: Post y Category

Ejemplo

# Ruta del archivo: models.py
from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey
from sqlalchemy.orm import relationship
from datetime import datetime
from database import Base

class Category(Base):
    """Categoría de artículos"""
    __tablename__ = "categories"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(50), unique=True, nullable=False)
    slug = Column(String(50), unique=True, nullable=False)
    # back_populates relación bidireccional
    posts = relationship("Post", back_populates="category")


class Post(Base):
    """Artículo de blog"""
    __tablename__ = "posts"
    id = Column(Integer, primary_key=True, index=True)
    title = Column(String(200), nullable=False)
    slug = Column(String(200), unique=True, nullable=False)
    summary = Column(Text, default="")
    content = Column(Text, nullable=False)
    category_id = Column(Integer, ForeignKey("categories.id"), nullable=False)
    created_at = Column(DateTime, default=datetime.utcnow)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
    # Relación bidireccional con Category
    category = relationship("Category", back_populates="posts")

Lo que se usa en FastAPI esSQLAlchemy nativo(no el de Flask-SQLAlchemydb.Model). Nota: las diferencias en la importación de Column, la herencia de Base y la sintaxis de relationship. Más adelante habrá una tabla comparativa.


Inicializar las tablas de la base de datos

Ejemplo

# Ruta del archivo: crear tablas en el evento de arranque de main.py
from fastapi import FastAPI
from database import engine, Base
from models import Category, Post   # Asegurar que las clases de modelos se importen para que Base.metadata pueda reconocerlas

app = FastAPI()

@app.on_event("startup")
def on_startup():
    """Crear automáticamente las tablas de la base de datos al iniciar la aplicación (solo para desarrollo)"""
    Base.metadata.create_all(bind=engine)

Más adelante se cambiará a migraciones con Alembic (capítulo 6),create_allsolo se usa en la etapa de prototipado rápido.


Insertar datos de prueba

Insertar datos de prueba en un script de Python:

Ejemplo

# Ruta del archivo: seed.py (ejecutar una sola vez)
from database import SessionLocal
from models import Category, Post

db = SessionLocal()

# Crear categoría
py = Category(name="Python", slug="python")
css = Category(name="CSS", slug="css")
fastapi = Category(name="FastAPI", slug="fastapi")
db.add_all([py, css, fastapi])
db.commit()

# Crear artículo
db.add_all([
    Post(title="Guía completa para empezar con FastAPI", slug="fastapi-guide",
         summary="Aprende FastAPI desde cero", content="<h2>¿Por qué elegir FastAPI?</h2><p>...</p>",
         category_id=fastapi.id),
    Post(title="Explicación detallada de las corrutinas en Python", slug="python-coroutine",
         summary="Entendiendo asyncio", content="<h2>¿Qué es una corrutina?</h2><p>...</p>",
         category_id=py.id),
    Post(title="Práctica de diseño CSS Grid", slug="css-grid",
         summary="Uso de Grid para diseño responsive", content="<h2>Introducción a Grid</h2><p>...</p>",
         category_id=css.id),
])
db.commit()
db.close()
print("¡Inserción de datos de prueba completada!")

Ejecutapython seed.py, se insertan 3 artículos en la base de datos.


Comparación de escritura ORM en cuatro frameworks

OperaciónDjangoFlask-SQLAlchemyFastAPI (SQLAlchemy nativo)
Clase basemodels.Modeldb.ModelBase (DeclarativeBase)
Camposmodels.CharField()db.Column(...)Column(...)
Clave foráneaForeignKey(to, on_delete)db.ForeignKey('table.col')ForeignKey('table.col')
RelaciónInverso automáticodb.relationship + backrefrelationship + back_populates
SesiónGestión automáticadb.sessionSessionLocal() + Depends

Resumen del capítulo

En este capítulo has dominado la integración de SQLAlchemy en FastAPI: create_engine + SessionLocal para configurar la conexión a la base de datos, DeclarativeBase para definir la clase base de los modelos, get_db con inyección de dependencias para gestionar las sesiones, y Column/relationship para definir campos y relaciones.

En comparación con Flask-SQLAlchemy, SQLAlchemy nativo requiere un poco más de código, pero es completamente de código abierto y controlable.

Otras extensiones