Migraciones y modelos ORM con Cursor y Alembic

Contenido del curso

Web App con FastAPI + Docker

Frontend con Next.js y Cursor IDE

iOS con Swift + Cursor IDE

Android + Cursor IDE

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:0012:52

Migraciones y modelos ORM con Cursor y Alembic

Curso de Cursor AI Code Editor

Clase 7 de 25

Clase 7 / 25

Recursos

Crear migraciones de bases de datos y modelos ORM desde un contrato de entidades puede automatizarse con Cursor si configuras bien el contexto y la documentación indexada. Aquí verás cómo llevar las specs al contenedor, indexar Alembic y SQLAlchemy, y guiar al asistente paso a paso para que genere migraciones, modelos y seeds alineados con tu contrato.

Esta guía es útil si trabajas con Python, Docker y un workflow asistido por IA, y necesitas que la generación de código respete tu arquitectura sin saltarse pasos críticos como la reconstrucción de la imagen.

¿Cómo preparar el contenedor para que Cursor vea las specs?

El primer obstáculo es que el editor corre dentro del contenedor de Docker, así que cualquier archivo de contrato debe estar visible ahí. Si la carpeta specs no está montada, Cursor no puede usarla como contexto [00:32].

La solución tiene dos ajustes paralelos:

En el Dockerfile, copia la carpeta specs dentro de specs de la imagen.
En el docker-compose, agrega el volumen app/specs para que los cambios se reflejen sin reconstruir cada vez.

Después corres make stop, make build y make start, y vuelves a hacer attach al contenedor. Al revisar la carpeta API, las specs ya aparecen disponibles para el chat de Cursor.

¿Por qué los archivos de contrato deben estar dentro del contenedor? Porque Cursor solo puede leer lo que vive en el editor activo. Si las specs quedan fuera del volumen de Docker, el modelo no las verá como contexto y generará código sin alinearse al contrato.

¿Cómo indexar la documentación de Alembic y SQLAlchemy en Cursor?

Antes de pedirle migraciones a Cursor, conviene indexar la documentación oficial para que las respuestas se basen en la API real y no en suposiciones [02:20].

En Settings > Indexing and Docs agregas una nueva fuente pegando la URL de la documentación. Cursor hace scrapping y detecta el nombre. Cuando indexas Alembic, el sistema lo etiqueta como SQLAlchemy porque Alembic es parte del proyecto, así que renómbralo manualmente como Alembic para distinguirlo. Repite el proceso con SQLAlchemy ORM como segunda entrada.

Con ambas referencias indexadas, en el chat puedes invocarlas con el símbolo de documentación y forzar que Cursor use esas fuentes al planear los pasos.

¿Cómo guiar a Cursor para crear migraciones sin romper el flujo de Docker?

El prompt inicial debe pedir análisis y planificación, no ejecución directa. Le indicas que en contracts están las entidades, que cada una debe convertirse en tabla con sus atributos, y que use Alembic para las migraciones [04:10].

Cursor responde con una lista de pasos. El primero suele ser la configuración inicial: instalar Alembic y actualizar pyproject.toml. Aquí entra una corrección importante: no debe usar pip ni ejecutar la instalación, solo agregar la dependencia en pyproject.toml. La instalación real ocurre cuando se reconstruye la imagen.

El flujo queda así:

Pides ejecutar únicamente el paso uno.
Aceptas el cambio en pyproject.toml.
Sales del contenedor y corres make stop, make build, make start.
Vuelves a hacer attach y verificas con alembic en la terminal que el binario responde.

Una vez confirmada la instalación, le dices a Cursor que omita el uv sync y continúe con el resto. El asistente crea el esqueleto de versiones, el archivo alembic.ini y modifica env.py para conectar las migraciones.

¿Por qué no instalar Alembic con pip dentro del contenedor? Porque el entorno se gestiona con uv y la instalación debe quedar registrada en la imagen de Docker. Si lo haces manualmente dentro del contenedor, el cambio se pierde al reconstruir.

¿Qué hacer si Alembic se crea fuera del volumen montado?

Un detalle común: Cursor genera los archivos de Alembic en la raíz del contenedor, pero esa ruta no está montada como volumen, así que fuera del contenedor no aparecen [07:40]. Le pides explícitamente que mueva todos los archivos de Alembic dentro de la carpeta App, que sí está en el volumen. Tras el movimiento, revisas los diffs: en uno corrige la importación de App y en otro ajusta la referencia para invocar solo el core. Aceptas ambos cambios.

¿Qué genera Cursor al crear los modelos de SQLAlchemy?

Con la base lista, le pides continuar y aplicar todos los pasos restantes. La ejecución toma tiempo porque toca varios archivos, pero el resumen final muestra una implementación completa [09:30].

Lo más interesante es la abstracción que propone:

Un BaseModel con campos de auditoría: id, created_at, updated_at y deleted_at.
Un modelo Teacher que hereda de BaseModel y solo añade name, email y la relación con cursos.
Un modelo Course con su relación a profesores y a clases.
Un modelo Lesson en lugar de Class, porque Class es una palabra reservada en Python.

Ese cambio de Class a Lesson lo detecta Cursor solo, durante el chat, y crea un archivo nuevo manteniendo los atributos definidos en el contrato. La relación entre Course y Lesson se resuelve por la tabla intermedia correspondiente.

¿Qué incluye la migración generada y los seeds de desarrollo?

La migración inicial crea las tablas Teachers, Courses y Lessons con sus campos, los constraints y los campos de auditoría heredados [11:50]. Además, Cursor genera un archivo seed con datos de ejemplo: varios profesores, cursos asociados a esos profesores y clases vinculadas a cada curso. El seed hace commit e imprime confirmación.

Como cierre, el asistente entrega un dump estilo bitácora en formato Markdown dentro de la carpeta db, más un README adicional explicando los pasos. Esa documentación queda dentro del proyecto y evita que el conocimiento del proceso se pierda.

El reto queda abierto: haz que esos seeds se ejecuten automáticamente al construir la imagen de Docker, para que cualquier entorno local arranque con datos listos. Cuéntame en los comentarios cómo lo resolviste.

Daniel Flores

Hace un año

🧱 ¿Por qué Alembic + SQLAlchemy?

Usar Alembic para migraciones y SQLAlchemy como ORM asegura una estructura de datos robusta, escalable y mantenible, sobre todo en proyectos que usan contenedores Docker y desarrollo asistido con IA (Cursor). 🧪 Configuración de Alembic paso a paso

🧬 Agrega Alembic en pyproject.toml con UV (no pip).
🔁 Reconstruye la imagen para que se instale correctamente.
🖥️ En terminal del contenedor, verifica con: alembic
📚 Indexa en Cursor la documentación de SQLAlchemy y Alembic para generar código contextual y correcto.

🏗️ Creación de migraciones y modelos con Cursor

📄 Cursor genera migraciones desde archivos contracts bien definidos.

Ejemplo de campos comunes para auditoría:

id, created_at, updated_at, deleted_at

🧱 Estructura típica de modelos:

base_model.py: clase base con atributos comunes
teacher.py: relaciones profesor–curso
lesson.py: maneja nombres reservados con cuidado
course.py: incluye relaciones con teacher y lesson

🌱 Seed automático de datos

📦 Cursor generó un archivo seed.py con datos ficticios para desarrollo.
✔️ Usa transacciones SQL para poblar la base de datos localmente.
🧪 Ideal para testear funcionalidades sin escribir datos manualmente.

📝 Documentación y transparencia del proceso

🧾 Se creó un Markdown (db/migrations_log.md) con dumps de pasos realizados
📚 Facilita la revisión, onboarding de nuevos devs y reproducibilidad técnica.
🧠 Propuesta: integrar los seeds directamente al Dockerfile o entrypoint.sh para poblar automáticamente la base en cada build.

✅ Beneficios clave

🔄 Sincronización con Docker Specs y código siempre alineados, evitando inconsistencias entre el entorno local y el contenedor.

🤖 IA generando migraciones precisas Gracias a Cursor y contratos bien definidos, las migraciones se crean de forma eficiente y con menor margen de error.

🧱 Modelos robustos Los modelos generados están basados en buenas prácticas como campos de auditoría, relaciones claras y una arquitectura limpia.

📝 Documentación técnica automática Se generan archivos markdown útiles que documentan el proceso paso a paso, facilitando la revisión y el mantenimiento futuro.

Comentarios (32)32 comentarios

Ramiro José López Velásquez

Yeins David Llano Hernández

Oscar Monsalve

Bryan Alzate

Eduardo José Álvarez

Team Platzi

Rolando Perez

Francisco Ibarra

Hace 9 meses

Axel Manuel Medrano Sánchez

Andrea Bohorquez

Hace 3 meses

Manuel Ferriz

Gerencia Sistemas

Hace 4 meses

César Francisco Ramírez Chávez

Angel Rafael Menchaca Gonzalez

Hace 7 meses

Martin Lazzeri

Hace 6 meses

Guillermo Castaño Vèlez

Alejandro Javier Moyano

Hace 10 meses

Enrique Alexis Lopez Araujo

Andres Trujillo

JOSUE ANTHONY CAMACHO MARBAN

Diego Alejandro Lesmes

Oscar Andres Ramos Lopez

Hace un mes

Alexander Jose Cordero Guerra

Jhon Heyner Romero Ruiz

Juan Miguel Garcia Moreno

Valerio Maquera

MARIA TERESA PANIAGUA RIVERA

Hace 8 meses

Mateo Montoya Henao

Web App con FastAPI + Docker

Vibe coding con Cursor en dos semanas

Stack tecnológico para plataforma educativa online

Configuración de contexto y reglas en Cursor para FastAPI

Setup de FastAPI con Cursor paso a paso

Ejecución autónoma de setup con Cursor

Cursor dentro de un contenedor Docker

Migraciones y modelos ORM con Cursor y Alembic

Creación de servicios y endpoints en FastAPI con Docker

Pruebas unitarias en FastAPI con PyTest

Frontend con Next.js y Cursor IDE

Cursor Agent para front-end sin configuración

Creación y configuración de Cursor Rules para proyectos Next.js

Mejora visual de landing pages con imágenes y tokens CSS

Configuración de estilos globales SCSS y páginas dinámicas en Next.js

Configuración de Vitest para pruebas unitarias en Next.js

Página completa con un solo prompt en Cursor

E2E testing con Playwright MCP en Cursor

iOS con Swift + Cursor IDE

Configuración de Cursor con Xcode para desarrollo iOS nativo

Configura reglas y contexto en Cursor

Genera UI en SwiftUI con prompts en Cursor

Cursor genera capas data y domain en iOS

Conexión de view models con capas domain y data

Android + Cursor IDE

Setup de Cursor para apps Android con Kotlin

Cursor genera una app Android desde cero

Corrección de errores de dependencias con Cursor en Android Studio

Cursor en equipo: entrega frontend en un día

Migraciones y modelos ORM con Cursor y Alembic

Progreso del curso

Web App con FastAPI + Docker

Frontend con Next.js y Cursor IDE

iOS con Swift + Cursor IDE

Android + Cursor IDE

Recursos

Recursos