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.