Asistente de Migraciones de Base de Datos
Este skill te ayuda a crear archivos de migración de base de datos que siguen las convenciones del ORM y los patrones de nomenclatura de tu proyecto.
Cuándo Usar Este Skill
- El usuario solicita crear una migración de base de datos
- Agregar nuevas tablas o columnas a la base de datos
- Modificar el esquema de base de datos existente
- Crear índices, restricciones o relaciones
- El usuario menciona "migración", "cambio de esquema" o "actualización de base de datos"
Instrucciones
1. Detectar el ORM/Herramienta de Migración
Primero, identifica qué ORM o herramienta de migración utiliza el proyecto:
- Prisma: Busca
prisma/schema.prismao@prisma/clienten package.json - Sequelize: Busca
.sequelizercosequelize-clien package.json - Knex: Busca
knexfile.jsoknexen package.json - TypeORM: Busca
ormconfig.jsonotypeormen package.json - Alembic (Python): Busca
alembic.inio directorioalembic/ - Django: Busca
manage.pyy migraciones de Django en*/migrations/ - Active Record (Rails): Busca directorio
db/migrate/ - Flyway: Busca
flyway.confodb/migration/ - Liquibase: Busca
liquibase.propertieso archivos changelog
Usa Glob para buscar estos archivos indicadores.
2. Examinar Migraciones Existentes
Lee los archivos de migración existentes para entender:
- Convenciones de nomenclatura (formato de timestamp, formato de descripción)
- Estructura de directorios
- Formato de archivo de migración (SQL, JavaScript, TypeScript, Python, etc.)
- Patrones de código (funciones up/down, forwards/rollback, etc.)
Usa Grep para encontrar migraciones recientes: busca en directorios comunes como:
prisma/migrations/db/migrate/migrations/odatabase/migrations/alembic/versions/
3. Generar Archivo de Migración
Basado en el ORM detectado, crea un archivo de migración apropiado:
Prisma
- Ejecuta
npx prisma migrate dev --name <descripcion>O - Crea manualmente el SQL de migración en
prisma/migrations/<timestamp>_<nombre>/migration.sql
Sequelize
- Genera:
npx sequelize-cli migration:generate --name <descripcion> - Luego completa las funciones up/down con los cambios de esquema
Knex
- Genera:
npx knex migrate:make <descripcion> - Completa las funciones exports.up y exports.down
TypeORM
- Genera:
npm run typeorm migration:create src/migrations/<Nombre> - Implementa los métodos up() y down()
Alembic
- Genera:
alembic revision -m "<descripcion>" - Completa las funciones upgrade() y downgrade()
Django
- Ejecuta:
python manage.py makemigrations - O crea manualmente la migración en
<app>/migrations/
Rails
- Genera:
rails generate migration <NombreClase> - Completa el método change (o up/down para migraciones complejas)
4. Seguir Convenciones de Nomenclatura
Usa nombres consistentes y descriptivos:
- Bueno:
add_user_email_index,create_products_table,add_payment_status_to_orders - Malo:
migration1,update,fix
Formato basado en patrones del proyecto:
- Prefijo de timestamp:
20231215120000_add_email_to_users - Secuencial:
001_create_users,002_add_indexes
5. Incluir Tanto Up como Down/Rollback
Siempre proporciona ambas direcciones cuando sea compatible:
- Up/Upgrade/Forward: Aplica el cambio de esquema
- Down/Downgrade/Rollback: Revierte el cambio de esquema
Para ORMs que usan operaciones reversibles (Rails, algunos Sequelize), un único método change puede ser suficiente.
6. Directrices de Contenido de Migración
Creación de Tablas:
- Define todas las columnas con tipos apropiados
- Establece restricciones NOT NULL donde corresponda
- Agrega claves primarias
- Incluye timestamps (created_at, updated_at) si el proyecto los usa
- Agrega claves foráneas e índices en la misma migración o separadas si el proyecto lo prefiere
Modificación de Tablas:
- Sé específico:
ADD COLUMN,DROP COLUMN,MODIFY COLUMN - Maneja los datos existentes apropiadamente (valores por defecto, rellenos)
- Considera la compatibilidad hacia atrás
Agregar Índices:
- Nombra los índices claramente:
idx_users_email,idx_orders_user_id_created_at - Usa tipos de índice apropiados (B-tree, Hash, GIN, etc.)
- Considera índices parciales para tablas grandes
Migraciones de Datos:
- Separa las migraciones de esquema de las migraciones de datos si es posible
- Ten cuidado con conjuntos de datos grandes (operaciones por lotes)
- Prueba el rollback con volúmenes de datos realistas
7. Validar Seguridad de la Migración
Antes de finalizar, verifica:
- Reversibilidad: ¿Se puede revertir la migración?
- Pérdida de datos: ¿Se perderán datos? ¡Advierte al usuario!
- Tiempo de inactividad: ¿Bloqueará tablas? Considera migraciones en línea para tablas grandes
- Dependencias: ¿Hay migraciones dependientes que deban ejecutarse primero?
8. Recomendaciones de Prueba
Sugiere al usuario:
- Ejecutar la migración en una base de datos de desarrollo primero
- Probar la funcionalidad de rollback
- Para producción: probar en un entorno de staging
- Revisar el SQL generado (para ORMs que lo auto-generan)
Plantillas Específicas por ORM
Consulta las plantillas en el directorio templates/:
prisma-migration.sql- Ejemplo de migración de Prismasequelize-migration.js- Ejemplo de migración de Sequelizeknex-migration.js- Ejemplo de migración de Knextypeorm-migration.ts- Ejemplo de migración de TypeORMalembic-migration.py- Ejemplo de migración de Alembicrails-migration.rb- Ejemplo de migración de Rails
Mejores Prácticas
- Un propósito por migración: No mezcles cambios no relacionados
- Nombres descriptivos: Los nombres deben explicar qué hace la migración
- Timestamps: Usa el formato de timestamp del ORM para ordenar
- Idempotente cuando sea posible: Seguro para ejecutar múltiples veces
- Prueba rollbacks: Asegúrate de que down/rollback funcione correctamente
- Documenta lógica compleja: Agrega comentarios para operaciones no obvias
- Operaciones por lotes grandes: Para migraciones de datos que afecten muchas filas
- Usa transacciones: Envuelve las operaciones en transacciones cuando sea posible
Archivos de Apoyo
templates/: Plantillas de migración para varios ORMsreference.md: Convenciones de nomenclatura y patrones de migración