En el post anterior la API de la tienda guardaba los productos en una lista de Python. Funciona hasta que guardas el archivo: en modo dev el servidor se reinicia, la lista vuelve a tener los tres productos de partida y el que acabas de añadir con el POST ha desaparecido. Con el id pasa algo peor. Salía de len(productos) + 1, así que si borras el producto 2 de una lista de tres, el siguiente que añadas recibe el id 3, que ya existe.
Un programa que olvida todo al apagarse no sirve para guardar pedidos, usuarios ni nada que importe. Hace falta una base de datos, y aquí es donde mucha gente se frena porque da la impresión de que hay que montar un servidor, instalar cosas y aprender un montón de SQL antes de ver nada funcionando.
No hace falta. Vamos a guardar los productos en un único archivo, tienda.db, que vive en la carpeta de tu proyecto, y vamos a hacerlo con la misma API de la tienda de FastAPI para principiantes. Al final tendrás crear, leer, actualizar y borrar productos (lo que se conoce como CRUD) y los datos seguirán ahí después de reiniciar el servidor.
SQLite y SQLModel: qué es cada cosa
Si ya has visto el post de SQL básico, sabes que una base de datos guarda la información en tablas, como una hoja de cálculo con columnas fijas, y que se le piden cosas con SELECT, INSERT, UPDATE y DELETE. Lo único nuevo es dónde vive. SQLite es una base de datos que cabe en un archivo normal: no hay servidor que instalar, ni usuario, ni contraseña. Python la trae incluida.
Ahora piensa en cómo trabajas con los productos en tu código: como objetos de Python, con su nombre y su precio. La base de datos, en cambio, habla en filas y columnas. Alguien tiene que traducir de un lado a otro, y escribir esa traducción a mano en cada ruta es pesado y se presta a errores. Esa pieza traductora se llama ORM (mapeo objeto-relacional, por su nombre en inglés). Defines una clase de Python y la librería crea la tabla y convierte cada fila en un objeto.
SQLModel es un ORM creado por el mismo autor de FastAPI. Está construido sobre SQLAlchemy (que hace el trabajo con la base de datos) y sobre Pydantic (que valida los datos, igual que en el post anterior). Por eso una misma clase te sirve para describir la tabla y para validar lo que llega a la API.
Comprobé las versiones el 27 de octubre de 2026 en PyPI: SQLModel 0.0.48 y FastAPI 0.162.0, las dos con Python 3.10 o superior. El número de SQLModel empieza por 0.0, que quiere decir que sigue en desarrollo y de vez en cuando cambia alguna cosa, así que si algo no te cuadra, mira primero las notas de versión.
Preparar el proyecto
Reutiliza la carpeta tienda-api del post anterior, con su entorno virtual activado (tienes que ver (.venv) al principio de la línea del terminal). FastAPI ya está instalado; falta SQLModel:
pip install sqlmodel
Vamos a reescribir main.py entero, así que si quieres conservar la versión con lista en memoria, copia el archivo antes con otro nombre. Lo iré construyendo por partes y al final tienes el código completo para comparar.
Los modelos: una clase para cada trabajo
Lo lógico sería hacer una sola clase Producto y usarla para todo: la tabla, lo que recibes y lo que devuelves. Es lo primero que se intenta y no es buena idea, por un motivo concreto. Si la misma clase que recibe el POST tiene un campo id, el cliente puede mandar "id": 1 en el cuerpo de la petición y elegir él mismo qué fila toca. El id tiene que asignarlo la base de datos, nunca quien llama a tu API.
La solución es repartir el trabajo en varias clases pequeñas que comparten los campos comunes:
from pydantic import computed_field
from sqlmodel import Field, SQLModel
IVA = 0.21
class ProductoBase(SQLModel):
nombre: str = Field(min_length=2, index=True)
precio: float = Field(gt=0)
descripcion: str | None = None
class Producto(ProductoBase, table=True):
id: int | None = Field(default=None, primary_key=True)
class ProductoCrear(ProductoBase):
pass
class ProductoPublico(ProductoBase):
id: int
@computed_field
@property
def precio_con_iva(self) -> float:
return round(self.precio * (1 + IVA), 2)
class ProductoActualizar(SQLModel):
nombre: str | None = Field(default=None, min_length=2)
precio: float | None = Field(default=None, gt=0)
descripcion: str | None = None
ProductoBase tiene los campos que se parecen en todos los casos, con las mismas reglas que ya conoces del post anterior (min_length para el nombre, gt=0 para que el precio sea mayor que cero). Producto es la tabla: el table=True es lo que le dice a SQLModel que esta clase se convierte en una tabla y no solo en un molde de datos. Su id es int | None con valor por defecto None porque antes de guardar el producto todavía no tiene id; lo pondrá la base de datos al insertar.
ProductoCrear es lo que acepta el POST: los campos del producto y nada más, sin id. ProductoPublico es lo que devuelve la API, ahora sí con id, y añade el precio_con_iva calculado en el servidor, como en el post anterior. ProductoActualizar lo usaremos para el PATCH, y tiene todos los campos opcionales porque quien edita un producto puede querer cambiar solo el precio.
Error típico: olvidar table=True
Si quitas table=True de Producto, el servidor arranca sin quejarse, pero la tabla no se crea y las rutas que usan Producto fallan con un error de SQLAlchemy que no se parece en nada a lo que has tocado. Si ves errores raros en cuanto pruebas la primera ruta, mira primero esa palabra. Por cierto, SQLModel pone a la tabla el nombre de la clase en minúsculas, por eso es producto.
Conectar con la base de datos
Ahora hay que decirle a SQLModel dónde está la base de datos. Eso es el engine (motor, en inglés): un objeto que sabe conectarse y que se crea una sola vez para toda la aplicación.
import os
from sqlmodel import SQLModel, create_engine
DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///tienda.db")
connect_args = {"check_same_thread": False} if DATABASE_URL.startswith("sqlite") else {}
engine = create_engine(DATABASE_URL, connect_args=connect_args)
La dirección sqlite:///tienda.db significa "usa SQLite y guarda todo en el archivo tienda.db de esta carpeta". La leo de una variable de entorno llamada DATABASE_URL y dejo SQLite como valor por defecto. Hoy no tiene credenciales, pero el día que pases a PostgreSQL la dirección llevará usuario y contraseña, y esas cosas no se escriben en el código ni se suben a Git. Si quieres repasar el porqué, está en el post de variables de entorno.
El check_same_thread merece una explicación, porque es lo que más extraña la primera vez. FastAPI atiende las rutas con def en hilos distintos, y SQLite por defecto se queja si una conexión creada en un hilo se usa en otro. Sin esa opción te puede salir un ProgrammingError: SQLite objects created in a thread can only be used in that same thread, y lo malo es que aparece de forma intermitente. Con ella le decimos que no pasa nada, porque la sesión que veremos ahora se crea y se cierra dentro de cada petición.
Falta crear las tablas. SQLModel lo hace con SQLModel.metadata.create_all(engine), y lo natural es ejecutarlo una vez cuando arranca la aplicación. FastAPI tiene un sitio para eso, una función lifespan (ciclo de vida): lo que hay antes del yield se ejecuta al arrancar, y lo que hay después, al apagar.
from contextlib import asynccontextmanager
from fastapi import FastAPI
@asynccontextmanager
async def lifespan(app: FastAPI):
SQLModel.metadata.create_all(engine)
yield
app = FastAPI(title="API de la tienda", lifespan=lifespan)
En tutoriales más antiguos verás @app.on_event("startup") para hacer lo mismo. Sigue funcionando en muchos proyectos, pero la propia documentación de FastAPI recomienda lifespan, así que empieza por ahí. Dos detalles: create_all solo crea las tablas que no existen, así que ejecutarlo en cada arranque es seguro; y los modelos tienen que estar definidos antes de que se ejecute, por eso van más arriba en el archivo.
Una sesión por petición
Para hablar con la base de datos no se usa el engine directamente, sino una sesión. Piensa en el carrito de una tienda online: vas metiendo cosas, quitando otras, y no pasa nada real hasta que pulsas "pagar". La sesión es igual. Acumulas cambios (añadir este producto, borrar aquel) y solo se guardan de verdad cuando haces commit.
Cada petición a la API necesita su propia sesión, que se abre al empezar y se cierra al terminar pase lo que pase. FastAPI resuelve eso con las dependencias: una función que prepara algo y se lo entrega a la ruta que lo pide.
from typing import Annotated
from fastapi import Depends
from sqlmodel import Session
def get_session():
with Session(engine) as session:
yield session
SessionDep = Annotated[Session, Depends(get_session)]
El with garantiza que la sesión se cierra al acabar, incluso si la ruta lanza un error, y el yield es el momento en que se la entrega a la ruta. SessionDep es solo un atajo para no repetir Depends(get_session) en cada función. En tutoriales más antiguos verás la forma session: Session = Depends(get_session), que hace lo mismo. Y ojo con escribir solo session: Session sin el Depends: FastAPI no sabe de dónde sacar esa sesión y falla nada más arrancar.
A partir de aquí, cualquier ruta que escriba session: SessionDep en sus parámetros recibe una sesión lista para usar.
Crear productos: POST
Empezamos por la ruta que más se estropea, la de crear. Recibe un ProductoCrear (ya validado, igual que antes), lo convierte en un Producto de tabla y lo guarda:
@app.post("/productos", response_model=ProductoPublico, status_code=201)
def anadir_producto(datos: ProductoCrear, session: SessionDep):
producto = Producto.model_validate(datos)
session.add(producto)
session.commit()
session.refresh(producto)
return producto
Son cuatro pasos y conviene entender cada uno. model_validate copia los datos validados a un objeto Producto, todavía sin id. session.add lo mete en el carrito. session.commit paga: es el momento en que se ejecuta el INSERT y SQLite le asigna el id. Y session.refresh vuelve a leer el producto de la base de datos para que el objeto traiga ese id recién nacido antes de devolverlo.
Error típico: olvidar el commit
Sin session.commit() el producto no llega a guardarse: los cambios pendientes se descartan al cerrarse la sesión. Con el refresh puesto lo normal es que la ruta termine en un 500, porque no encuentra en la base de datos el producto que acabas de añadir. Si quitas también el refresh, es peor: responde con un 201 de aspecto perfecto y los datos no están al listar. En cualquiera de los dos casos, lo primero que hay que comprobar es el commit.
Prueba en fastapi dev main.py, abre /docs y manda un POST con {"nombre": "Alfombrilla", "precio": 10}. La respuesta trae el id que ha asignado la base de datos y el precio con IVA, algo así como 12.1. Si mandas un "id": 99 en el cuerpo, FastAPI lo ignora, porque ProductoCrear no tiene ese campo. Justo para eso hicimos las clases separadas.
Leer: listar, filtrar y buscar
Leer se hace con select, que es el SELECT de SQL escrito en Python. Vas añadiéndole condiciones por partes y la sesión lo ejecuta con exec. Aprovecho para meter lo que ya tenías (el filtro por precio máximo) y dos cosas nuevas: una búsqueda por nombre y límites de paginación, para que nadie pueda pedirte un millón de filas de golpe.
from fastapi import Query
from sqlmodel import col, select
@app.get("/productos", response_model=list[ProductoPublico])
def listar_productos(
session: SessionDep,
max_precio: float | None = None,
q: str | None = None,
offset: Annotated[int, Query(ge=0)] = 0,
limit: Annotated[int, Query(ge=1, le=100)] = 20,
):
consulta = select(Producto).order_by(Producto.id)
if max_precio is not None:
consulta = consulta.where(Producto.precio <= max_precio)
if q:
consulta = consulta.where(col(Producto.nombre).contains(q))
return session.exec(consulta.offset(offset).limit(limit)).all()
Mira cómo se lee: empiezo con "todos los productos ordenados por id" y añado un where solo si el cliente ha pedido ese filtro. col() es una ayuda para que tu editor entienda que Producto.nombre es una columna y no un texto; en ejecución funciona igual sin él, pero el editor te subrayaría en rojo. Y Query(ge=1, le=100) hace que un limit=5000 o un offset=-3 devuelvan un 422 en vez de ejecutarse. Otro fallo clásico está en el filtro de precio: si escribes if max_precio: en lugar de if max_precio is not None:, un max_precio=0 se trata como "sin filtro" y devuelve todo, porque en Python el cero cuenta como falso. Si quieres ver cómo se monta la paginación completa con su frontend, está en el post de paginación web.
Por qué no se pega el texto del usuario dentro del SQL
Fíjate en la línea de la búsqueda: el texto que escribe el usuario (q) no se mezcla con ningún SQL a mano. Esto es lo más importante de todo el post en cuanto a seguridad, y se entiende mejor viendo lo que pasaría si lo hicieras mal.
from sqlalchemy import text
# ❌ MAL: el texto del usuario se pega dentro del SQL
consulta = text(f"SELECT * FROM producto WHERE nombre LIKE '%{q}%'")
Si alguien manda q con el valor ' OR '1'='1, la consulta que se ejecuta deja de ser una búsqueda y pasa a devolver todas las filas. Con otro texto, podría borrar una tabla entera. Eso es una inyección SQL: el usuario consigue que su texto se interprete como parte de las órdenes. Es de los fallos más viejos y más repetidos que hay, y casi siempre nace de pegar una variable con un f-string dentro de una consulta.
Con select(...).where(...) eso no puede pasar, porque SQLAlchemy envía la orden y el valor por separado: el texto del usuario viaja como un dato, nunca como parte de la orden, y la base de datos no lo interpreta. A eso se le llama consulta parametrizada. Si algún día necesitas escribir SQL a mano, hazlo con parámetros (text("... WHERE nombre = :nombre") y pasas el valor aparte), nunca con un f-string.
Ver un producto y devolver 404
Para buscar por id no hace falta ni select: la sesión tiene get, que recibe la clase y la clave primaria. Si no existe devuelve None, y ahí es donde tu API tiene que decidir qué responder.
from fastapi import HTTPException
@app.get("/productos/{producto_id}", response_model=ProductoPublico)
def ver_producto(producto_id: int, session: SessionDep):
producto = session.get(Producto, producto_id)
if producto is None:
raise HTTPException(status_code=404, detail="Producto no encontrado")
return producto
Aquí es donde la mayoría se atasca la primera vez: se olvidan de comprobar el None y la API intenta devolver nada como si fuera un producto, con lo que FastAPI responde con un 500 y un error de validación en el terminal. El 404 es la respuesta correcta y la que tu frontend espera.
Actualizar con PATCH
Para modificar existen dos verbos. PUT sustituye el producto entero y exige mandar todos los campos. PATCH cambia solo lo que mandes. Para una tienda, donde casi siempre se edita un único campo (el precio, por ejemplo), PATCH es más cómodo, y es el que vamos a hacer.
@app.patch("/productos/{producto_id}", response_model=ProductoPublico)
def actualizar_producto(
producto_id: int, datos: ProductoActualizar, session: SessionDep
):
producto = session.get(Producto, producto_id)
if producto is None:
raise HTTPException(status_code=404, detail="Producto no encontrado")
cambios = {
campo: valor
for campo, valor in datos.model_dump(exclude_unset=True).items()
if valor is not None
}
producto.sqlmodel_update(cambios)
session.add(producto)
session.commit()
session.refresh(producto)
return producto
Lo delicado es la línea de cambios, y se entiende mejor por partes.
model_dump(exclude_unset=True) deja fuera los campos que el cliente no mandó, de modo que un PATCH con solo {"precio": 12} no toca el nombre ni la descripción. Sin esa opción, los campos que faltan vendrían como None y borrarías el nombre del producto sin querer. Luego sqlmodel_update copia esos cambios sobre el producto que ya está en la base de datos.
El filtro if valor is not None cubre otro caso: que el cliente mande {"nombre": null} a propósito. Esa clave sí cuenta como "mandada", y sin el filtro intentarías guardar un nombre vacío en una columna obligatoria, lo que acaba en un error 500 de la base de datos. El precio de esto es que con este PATCH no puedes borrar la descripción mandando null; para empezar es un trato razonable.
Borrar
from fastapi import Response
@app.delete("/productos/{producto_id}", status_code=204)
def borrar_producto(producto_id: int, session: SessionDep):
producto = session.get(Producto, producto_id)
if producto is None:
raise HTTPException(status_code=404, detail="Producto no encontrado")
session.delete(producto)
session.commit()
return Response(status_code=204)
Un 204 significa "hecho, y no tengo nada que devolverte", por eso la respuesta va vacía. Y ya no hay problema con los ids: si borras el 2 y añades un producto nuevo, SQLite le da un id que no ha usado ningún producto vivo. Un detalle de SQLite: si borras justo el último producto, es posible que el siguiente reutilice su id. Para una tienda de prácticas da igual; en una de verdad con pedidos que apunten a productos, se trata de otra manera.
El código completo
Junto todo en un único main.py. Compáralo con el tuyo si algo no te funciona; ojo con el orden, porque los modelos y el engine tienen que ir antes de las rutas:
import os
from contextlib import asynccontextmanager
from typing import Annotated
from fastapi import Depends, FastAPI, HTTPException, Query, Response
from pydantic import computed_field
from sqlmodel import Field, Session, SQLModel, col, create_engine, select
IVA = 0.21
DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///tienda.db")
connect_args = {"check_same_thread": False} if DATABASE_URL.startswith("sqlite") else {}
engine = create_engine(DATABASE_URL, connect_args=connect_args)
class ProductoBase(SQLModel):
nombre: str = Field(min_length=2, index=True)
precio: float = Field(gt=0)
descripcion: str | None = None
class Producto(ProductoBase, table=True):
id: int | None = Field(default=None, primary_key=True)
class ProductoCrear(ProductoBase):
pass
class ProductoPublico(ProductoBase):
id: int
@computed_field
@property
def precio_con_iva(self) -> float:
return round(self.precio * (1 + IVA), 2)
class ProductoActualizar(SQLModel):
nombre: str | None = Field(default=None, min_length=2)
precio: float | None = Field(default=None, gt=0)
descripcion: str | None = None
def get_session():
with Session(engine) as session:
yield session
SessionDep = Annotated[Session, Depends(get_session)]
@asynccontextmanager
async def lifespan(app: FastAPI):
SQLModel.metadata.create_all(engine)
yield
app = FastAPI(title="API de la tienda", lifespan=lifespan)
@app.get("/")
def inicio():
return {"mensaje": "La API de la tienda funciona"}
@app.post("/productos", response_model=ProductoPublico, status_code=201)
def anadir_producto(datos: ProductoCrear, session: SessionDep):
producto = Producto.model_validate(datos)
session.add(producto)
session.commit()
session.refresh(producto)
return producto
@app.get("/productos", response_model=list[ProductoPublico])
def listar_productos(
session: SessionDep,
max_precio: float | None = None,
q: str | None = None,
offset: Annotated[int, Query(ge=0)] = 0,
limit: Annotated[int, Query(ge=1, le=100)] = 20,
):
consulta = select(Producto).order_by(Producto.id)
if max_precio is not None:
consulta = consulta.where(Producto.precio <= max_precio)
if q:
consulta = consulta.where(col(Producto.nombre).contains(q))
return session.exec(consulta.offset(offset).limit(limit)).all()
@app.get("/productos/{producto_id}", response_model=ProductoPublico)
def ver_producto(producto_id: int, session: SessionDep):
producto = session.get(Producto, producto_id)
if producto is None:
raise HTTPException(status_code=404, detail="Producto no encontrado")
return producto
@app.patch("/productos/{producto_id}", response_model=ProductoPublico)
def actualizar_producto(
producto_id: int, datos: ProductoActualizar, session: SessionDep
):
producto = session.get(Producto, producto_id)
if producto is None:
raise HTTPException(status_code=404, detail="Producto no encontrado")
cambios = {
campo: valor
for campo, valor in datos.model_dump(exclude_unset=True).items()
if valor is not None
}
producto.sqlmodel_update(cambios)
session.add(producto)
session.commit()
session.refresh(producto)
return producto
@app.delete("/productos/{producto_id}", status_code=204)
def borrar_producto(producto_id: int, session: SessionDep):
producto = session.get(Producto, producto_id)
if producto is None:
raise HTTPException(status_code=404, detail="Producto no encontrado")
session.delete(producto)
session.commit()
return Response(status_code=204)
Una diferencia con el post anterior: ya no hay tres productos de partida. La tabla empieza vacía, así que lo primero que verás al listar es []. Añade unos cuantos desde /docs con el POST.
Comprobar que los datos sobreviven
Esta es la prueba que cuenta. Añade dos o tres productos desde /docs, comprueba que salen en GET /productos y mira en la carpeta del proyecto: ha aparecido un archivo tienda.db. Ahora para el servidor con Ctrl+C, vuelve a arrancarlo con fastapi dev main.py y repite el GET. Los productos siguen ahí. Haz también un cambio tonto en main.py y guarda: el modo dev reinicia el servidor y la lista no se vacía.
Mientras estás en ello, evita subir ese archivo a Git. Un .db con datos de prueba no tiene sitio en el repositorio, y el día que tenga datos reales, menos todavía. Añade esto a tu .gitignore:
.env
*.db
.venv/
__pycache__/
⚠️ Si subiste credenciales a Git por error:
1. Cambia inmediatamente todas las credenciales expuestas
2. Eliminar el archivo no es suficiente: el historial de Git lo guarda
3. Usa git filter-branch o BFG Repo Cleaner para limpiar el historial
4. En casos graves, considera recrear el repositorio
Cuando cambias un modelo y la tabla no se entera
Este fallo te va a pasar, así que mejor verlo ya. Añade un campo al modelo, por ejemplo stock: int = 0 en ProductoBase, guarda y haz un GET. Te sale un 500 y en el terminal un sqlite3.OperationalError: no such column: producto.stock.
La razón es que create_all solo crea las tablas que faltan; si la tabla producto ya existe, no la toca, aunque tu clase tenga una columna nueva. El archivo tienda.db sigue teniendo la estructura antigua. Mientras estés practicando, la solución es la bruta: para el servidor, borra tienda.db y arranca de nuevo. Pierdes los datos de prueba, pero la tabla se crea con la forma nueva.
Con datos que sí importan eso no vale, y para eso existen las migraciones: pequeños scripts que modifican la tabla existente paso a paso sin perder nada. La herramienta habitual con SQLAlchemy se llama Alembic. No hace falta que la aprendas ahora, pero conviene que sepas que existe y por qué llegará un día en que la necesites.
Qué toca ahora
Con esto ya tienes una API que guarda datos de verdad, que sobrevive a los reinicios y que no se deja engañar por un campo id colado en el cuerpo de la petición. Para comprobar que lo entiendes, haz una cosa concreta: coge el formulario del post de enviar un formulario al backend con fetch, apunta su fetch a POST /productos y añade un producto desde la página. Si lo ves aparecer en GET /productos después de recargar el servidor, ya tienes una web que guarda cosas.
Después, pruébate con el PATCH y el DELETE desde el navegador: un botón para cambiar el precio y otro para borrar, pintando la lista con createElement y textContent como en el post anterior. Cuando algo te dé un error de SQLAlchemy que no entiendas, copia el mensaje completo a una IA y pídele que te explique qué significa, en vez de que te dé el código arreglado. Es una forma de aprender que funciona, siempre que después leas lo que te propone y compruebes que lo entiendes.
Y si te apetece seguir con la misma API, el siguiente paso natural es una segunda tabla: categorías, con cada producto perteneciendo a una. Ahí aparecen las relaciones entre tablas, que es el punto donde el SQL empieza a resultar útil de verdad.