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
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
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
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-SQLAlchemy
db.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
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
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ón | Django | Flask-SQLAlchemy | FastAPI (SQLAlchemy nativo) |
|---|---|---|---|
| Clase base | models.Model | db.Model | Base (DeclarativeBase) |
| Campos | models.CharField() | db.Column(...) | Column(...) |
| Clave foránea | ForeignKey(to, on_delete) | db.ForeignKey('table.col') | ForeignKey('table.col') |
| Relación | Inverso automático | db.relationship + backref | relationship + back_populates |
| Sesión | Gestión automática | db.session | SessionLocal() + 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