Introducción a SQLAlchemy con FastAPI

¿Qué es un ORM y por qué SQLAlchemy?

Hasta ahora has trabajado con datos almacenados en listas y diccionarios dentro de tu aplicación FastAPI. Esto funciona perfectamente para aprender y prototipar, pero presenta un problema fundamental: cuando tu aplicación se cierra, todos los datos desaparecen. En aplicaciones reales necesitas que la información persista entre ejecuciones.

Aquí es donde entran las bases de datos. Una base de datos te permite almacenar información de forma permanente en el disco duro, pero trabajar directamente con bases de datos requiere escribir consultas SQL, lo cual puede ser complejo y propenso a errores.

El problema de trabajar directamente con SQL

Imagina que quieres obtener todos los usuarios de tu aplicación. Con SQL puro tendrías que escribir algo como:

SELECT id, nombre, email, fecha_creacion FROM usuarios WHERE activo = 1;

Y luego procesar manualmente cada fila del resultado para convertirla en objetos Python. Además, cada vez que cambies la estructura de tu tabla, tendrías que actualizar todas las consultas relacionadas.

Qué es un ORM

Un ORM (Object-Relational Mapping) es una herramienta que actúa como traductor entre tu código Python y la base de datos. Te permite trabajar con objetos Python normales en lugar de escribir consultas SQL directamente.

Con un ORM, en lugar de escribir SQL, puedes hacer algo como esto:

usuarios_activos = session.query(Usuario).filter(Usuario.activo == True).all()

El ORM se encarga automáticamente de:

• Traducir tu código Python a consultas SQL
• Convertir los resultados de la base de datos en objetos Python
• Gestionar las conexiones a la base de datos
• Validar que los datos cumplan las reglas definidas

Por qué SQLAlchemy

SQLAlchemy es el ORM más popular y maduro del ecosistema Python. Se ha convertido en el estándar de facto por varias razones importantes:

• Flexibilidad: Te permite trabajar tanto con un enfoque de alto nivel (usando modelos) como con SQL directo cuando lo necesites

• Compatibilidad: Funciona con múltiples bases de datos (PostgreSQL, MySQL, SQLite, etc.) sin cambiar tu código

• Integración perfecta: Se integra naturalmente con FastAPI y Pydantic, manteniendo la consistencia en tu aplicación

• Comunidad activa: Tiene una documentación excelente y una comunidad muy activa que lo mantiene actualizado

Ventajas de usar SQLAlchemy con FastAPI

La combinación de FastAPI y SQLAlchemy te ofrece beneficios específicos:

• Validación consistente: Pydantic valida los datos de entrada, SQLAlchemy los valida antes de guardarlos

• Documentación automática: FastAPI puede generar documentación que incluye los esquemas de tu base de datos

• Desarrollo rápido: Reduces significativamente el código repetitivo para operaciones básicas de base de datos

• Mantenimiento sencillo: Los cambios en tu modelo de datos se propagan automáticamente

Considera este ejemplo comparativo. Sin ORM tendrías que escribir:

# Sin ORM - Mucho código repetitivo
import sqlite3

def crear_usuario(nombre, email):
    conn = sqlite3.connect('app.db')
    cursor = conn.cursor()
    cursor.execute(
        "INSERT INTO usuarios (nombre, email) VALUES (?, ?)",
        (nombre, email)
    )
    conn.commit()
    user_id = cursor.lastrowid
    conn.close()
    return user_id

Con SQLAlchemy, el mismo resultado se logra de forma más limpia:

# Con SQLAlchemy - Código más limpio y seguro
def crear_usuario(nombre, email):
    usuario = Usuario(nombre=nombre, email=email)
    session.add(usuario)
    session.commit()
    return usuario.id

SQLAlchemy no solo reduce la cantidad de código, sino que también previene errores comunes como inyecciones SQL y problemas de conexión, mientras mantiene tu código más legible y mantenible.

Conceptos básicos: Engine, Session, Model

SQLAlchemy se estructura en torno a tres componentes fundamentales que trabajan juntos para gestionar la comunicación con tu base de datos. Entender estos conceptos te permitirá usar SQLAlchemy de forma efectiva en tus aplicaciones FastAPI.

Engine: El motor de conexión

El Engine es el punto de entrada principal de SQLAlchemy. Piensa en él como el "motor" que establece y gestiona las conexiones con tu base de datos. Es el componente que sabe cómo hablar con tu base de datos específica.

from sqlalchemy import create_engine

# Crear un engine para SQLite
engine = create_engine("sqlite:///mi_aplicacion.db")

El Engine actúa como una fábrica de conexiones. No se conecta inmediatamente a la base de datos, sino que espera hasta que realmente necesites realizar una operación. Esto es eficiente porque evita conexiones innecesarias.

Cuando creas un Engine, le proporcionas una URL de conexión que especifica:

• Tipo de base de datos: sqlite, postgresql, mysql, etc.
• Ubicación: archivo local, servidor remoto, etc.
• Credenciales: usuario y contraseña si es necesario

# Diferentes tipos de conexión
engine_sqlite = create_engine("sqlite:///app.db")
engine_postgres = create_engine("postgresql://usuario:password@localhost/mi_db")
engine_mysql = create_engine("mysql://usuario:password@localhost/mi_db")

Session: Tu interfaz de trabajo

La Session es tu interfaz principal para interactuar con la base de datos. Es donde realizas todas las operaciones: crear, leer, actualizar y eliminar datos. Puedes pensar en ella como tu "sesión de trabajo" con la base de datos.

from sqlalchemy.orm import sessionmaker

# Crear una fábrica de sesiones
SessionLocal = sessionmaker(bind=engine)

# Crear una sesión específica
session = SessionLocal()

La Session mantiene un registro de cambios de todos los objetos que modificas durante tu sesión de trabajo. Esto significa que puedes hacer múltiples cambios y luego confirmarlos todos de una vez:

# Ejemplo de uso de session (sin conectar aún)
# session.add(nuevo_usuario)      # Marca para agregar
# session.add(otro_usuario)       # Marca para agregar  
# session.commit()                # Confirma todos los cambios

Una característica importante de las sesiones es que son temporales. Normalmente creas una sesión, realizas tus operaciones, confirmas los cambios y cierras la sesión:

# Patrón típico de uso
session = SessionLocal()
try:
    # Realizar operaciones
    session.commit()
except Exception:
    session.rollback()  # Deshacer cambios si hay error
finally:
    session.close()     # Cerrar la sesión

Model: La representación de tus datos

Los Models son clases Python que representan las tablas de tu base de datos. Cada modelo define la estructura de una tabla y cómo se relaciona con otras tablas. Es donde defines qué datos quieres almacenar y qué reglas deben cumplir.

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from sqlalchemy import Integer, String

class Base(DeclarativeBase):
    pass

class Usuario(Base):
    __tablename__ = "usuarios"
    
    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    nombre: Mapped[str] = mapped_column(String(100))
    email: Mapped[str] = mapped_column(String(255))

Cada modelo hereda de una clase base que proporciona la funcionalidad ORM. Los atributos de la clase se convierten en columnas de la tabla, y puedes especificar:

• Tipo de dato: Integer, String, Boolean, etc.
• Restricciones: primary_key, nullable, unique, etc.
• Validaciones: longitud máxima, valores permitidos, etc.

from sqlalchemy import Boolean
from datetime import datetime

class Producto(Base):
    __tablename__ = "productos"
    
    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    nombre: Mapped[str] = mapped_column(String(200))
    precio: Mapped[float] = mapped_column()
    disponible: Mapped[bool] = mapped_column(Boolean, default=True)

Cómo trabajan juntos

Estos tres componentes forman un flujo de trabajo coherente:

1. El Engine proporciona la conexión a la base de datos

2. La Session usa el Engine para comunicarse con la base de datos

3. Los Models definen qué datos intercambiar a través de la Session

# Configuración inicial
engine = create_engine("sqlite:///app.db")
SessionLocal = sessionmaker(bind=engine)

# Crear las tablas basadas en los modelos
Base.metadata.create_all(bind=engine)

# Usar los componentes juntos
session = SessionLocal()
nuevo_usuario = Usuario(nombre="Ana", email="ana@ejemplo.com")
session.add(nuevo_usuario)
session.commit()
session.close()

Esta arquitectura te permite separar responsabilidades:

• Engine: Se encarga de los detalles técnicos de conexión
• Session: Gestiona el estado y las transacciones
• Models: Definen la estructura y reglas de negocio

La belleza de esta separación es que puedes cambiar tu base de datos (por ejemplo, de SQLite a PostgreSQL) simplemente modificando la URL del Engine, sin tocar el resto de tu código.