/migration-plan

name: migration-plan
description: "Planificar migraciones de base de datos con rollback y estimación de impacto. Activar cuando el usuario quiera migrar base de datos, cambiar esquema, ejecutar ALTER TABLE, planificar un rollback o realizar una migracion segura."

Planificación de migraciones de base de datos

Resumen

Este skill estructura la planificación de una migración de base de datos de principio a fin. Una migración mal planificada puede causar pérdida de datos, downtime prolongado o inconsistencias difíciles de detectar. La planificación rigurosa es la diferencia entre un cambio transparente y un incidente.

El resultado es un plan de migración que incluye el script forward, el script de rollback, la estimación de impacto y los pasos de verificación posteriores. Este plan se revisa antes de ejecutar cualquier cambio.

Proceso

1. **Analizar el cambio requerido.** Antes de escribir SQL, entender exactamente qué cambia y por qué:

• Qué tablas y columnas se ven afectadas.
• Si el cambio es aditivo (nueva tabla, nueva columna) o destructivo (eliminar columna, cambiar tipo).
• Si hay datos existentes que necesitan transformación.
• Si el cambio es compatible hacia atrás con la versión actual del código o requiere despliegue coordinado.

2. **Estimar el impacto en producción.** Obtener métricas del entorno real:

• Tamaño de las tablas afectadas (número de filas y tamaño en disco).
• Tiempo estimado de la migración según el volumen de datos.
• Si la operación bloquea la tabla (ALTER TABLE con lock en MySQL, por ejemplo).
• Si se necesita ventana de mantenimiento o se puede ejecutar en caliente.

Para tablas grandes (millones de filas), considerar migraciones en lotes o herramientas como gh-ost, pt-online-schema-change o pgroll.

3. **Escribir el script forward.** El script que aplica el cambio. Requisitos:

• Debe ser idempotente cuando sea posible (IF NOT EXISTS, IF EXISTS).
• Incluir transacción si el motor lo permite para DDL.
• Separar cambios de esquema y cambios de datos si la migración es compleja.
• Respetar el sistema de migraciones del proyecto (Prisma Migrate, Alembic, Django Migrations, Flyway).

4. **Escribir el script de rollback.** El script que deshace el cambio forward:

• Para cambios aditivos: DROP de lo creado.
• Para cambios destructivos: restaurar desde backup o columna temporal.
• Para transformaciones de datos: script inverso o restauración desde backup.
• Verificar que el rollback deja la base de datos en un estado consistente.

5. **Definir el orden de ejecución.** Si la migración afecta a varias tablas con dependencias:

• Crear tablas referenciadas antes que las que las referencian.
• Eliminar foreign keys antes de eliminar tablas referenciadas.
• Si hay migración de datos entre tablas, respetar el orden de dependencia.
• Documentar el orden explícitamente en el plan.

6. **Planificar la verificación post-migración.** Definir comprobaciones que confirmen que la migración se aplicó correctamente:

• Verificar que las tablas y columnas existen con los tipos esperados.
• Contar filas antes y después para detectar pérdida de datos.
• Ejecutar queries de validación sobre los datos migrados.
• Comprobar que la aplicación funciona correctamente con el nuevo esquema.
• Revisar los logs en busca de errores relacionados con el cambio.

7. **Documentar el plan.** El plan de migración debe incluir:

• Descripción del cambio y motivación.
• Script forward y script de rollback.
• Estimación de tiempo y necesidad de downtime.
• Orden de ejecución.
• Checklist de verificación post-migración.
• Responsable de la ejecución y plan de comunicación.

Que NO hacer

• No ejecutar migraciones directamente en producción sin haberlas probado en un entorno con datos realistas.
• No asumir que el rollback "no se necesitará". Si no hay rollback, no hay plan.
• No mezclar migraciones de esquema con migraciones de datos en un solo paso si la migración es compleja.
• No ignorar los bloqueos de tabla. Un ALTER TABLE en una tabla con millones de filas puede bloquear la base de datos durante minutos u horas.
• No olvidar actualizar los modelos del ORM después de la migración.
• No ejecutar migraciones sin rollback probado. Si el rollback no se ha verificado en un entorno de prueba, no se puede confiar en él cuando se necesite de verdad.
• No migrar sin backup previo. Antes de cualquier migración destructiva, asegurar que existe un backup reciente y verificado de la base de datos.