database-migration

Descripción general de la skill database-migration

Qué te ayuda a hacer la skill database-migration

La skill database-migration sirve para planificar y generar trabajo de migración de esquemas y datos en bases de datos dentro de flujos habituales con ORM y SQL, con especial atención a la seguridad del rollback y a los despliegues sin downtime. Resulta especialmente útil cuando necesitas algo más que un prompt genérico de “escribe una migración”: por ejemplo, si el cambio afecta a datos reales en producción, requiere un despliegue por fases o debe ajustarse a un framework de migraciones concreto como Sequelize o TypeORM.

Quién debería usar esta skill database-migration

Los perfiles a los que mejor encaja son equipos de Database Engineering, ingenieros backend, ingenieros de plataforma y desarrolladores que trabajan con ayuda de IA y necesitan una migración pensada para operar en entornos reales, no solo correcta a nivel sintáctico. Si vas a modificar tablas, rellenar datos históricos, renombrar columnas de forma segura o cambiar entre patrones de ORM, esta skill le da al modelo un marco de trabajo mucho más útil que un prompt en blanco.

Para qué trabajo resuelve mejor la necesidad

Usa la skill database-migration cuando la tarea real sea producir un plan de migración que se pueda ejecutar de verdad: archivos de migración, pasos de despliegue por fases, rutas de rollback y consideraciones sobre transformación de datos. Su valor principal no es solo generar código. Es reducir la incertidumbre en torno al orden de operaciones, las ventanas de compatibilidad y la recuperación ante fallos.

Diferenciadores principales frente a un prompt normal de programación

Frente a un prompt corriente, esta skill database-migration está claramente orientada a:

• ejemplos de migración conscientes del ORM
• patrones explícitos de up y down
• enfoque de zero-downtime
• flujos que combinan cambios de esquema y cambios de datos
• procedimientos de rollback como requisito de primera clase

Por eso encaja mejor en cambios de producción que una petición genérica de “genera SQL”.

Qué entra en alcance y qué no

El contenido actual de la skill destaca sobre todo en patrones de migración y estructuras de ejemplo, especialmente para Sequelize y TypeORM. Tiene menos profundidad en automatización específica del repositorio, scripts de validación y reglas de decisión, porque la carpeta de la skill solo expone SKILL.md. En la práctica, puede orientar y redactar bien el trabajo de migración, pero aun así conviene que aportes los detalles de tu stack, tus restricciones y tu modelo de despliegue para obtener resultados fiables.

Cómo usar la skill database-migration

Contexto de instalación para la skill database-migration

Si usas el sistema de Skills de este repositorio, instala la skill desde el repo y ejecútala después en una sesión del agente que ya tenga acceso a tu codebase y al contexto del esquema. Una instalación típica sería:

npx skills add https://github.com/wshobson/agents --skill database-migration

Como esta skill se entrega principalmente como un único SKILL.md, gran parte de su valor dependerá de cómo formules la solicitud y de cuánto contexto de esquema proporciones.

Lee primero este archivo antes de usarla

Empieza por:

• plugins/framework-migration/skills/database-migration/SKILL.md

Como no hay rules/, resources/ ni scripts de soporte visibles para esta skill, no hace falta una fase larga de lectura del repositorio. El recorrido práctico es simple: revisa SKILL.md y pasa enseguida a tus propios archivos de esquema, configuración del ORM e historial de migraciones existente.

Qué entrada necesita la skill para funcionar bien

La skill database-migration funciona mucho mejor cuando le proporcionas:

• ORM o herramienta de migración actual: Sequelize, TypeORM, Prisma, SQL puro, etc.
• esquema actual o definiciones de modelos
• cambio de esquema objetivo
• si hace falta backfill de datos
• tamaño de las tablas o sensibilidad al tráfico
• tolerancia al downtime
• expectativas de rollback
• motor de base de datos objetivo: PostgreSQL, MySQL, etc.
• estilo de despliegue: one-shot, por fases, blue/green, canary

Sin estos detalles, el modelo puede devolver una migración aparentemente válida pero insegura para producción.

Convierte un objetivo difuso en un prompt sólido para database-migration

Prompt débil:

Create a migration to rename a column.

Prompt más sólido:

Use the database-migration skill. We use TypeORM with PostgreSQL.
Current table: users(id, full_name, created_at).
Goal: replace full_name with first_name and last_name.
Constraints: production table has 20M rows, cannot block writes, rollout must be zero-downtime, app and migration may be deployed separately.
Need:
1. phased migration plan
2. TypeORM migration files
3. data backfill strategy
4. rollback plan
5. application compatibility notes during transition

La segunda versión le da a la skill lo que necesita para elegir un enfoque expand-migrate-contract más seguro, en lugar de un renombrado directo y arriesgado.

Mejor flujo de trabajo para tareas reales de migración

Un flujo práctico de database-migration usage sería:

1. Pide primero la estrategia de migración.
2. Revisa riesgos, comportamiento de locks y supuestos de rollback.
3. Después pide el archivo de migración real en tu framework.
4. Si el despliegue será por fases, pide también los cambios de compatibilidad en la capa de aplicación.
5. Solicita consultas de verificación y pasos de rollback.
6. Prueba en staging con una forma de datos parecida a producción antes de confiar en el resultado.

Este orden importa, porque el código de migración generado demasiado pronto suele incorporar un modelo de despliegue equivocado.

Patrones de ORM en los que la skill rinde mejor

La evidencia del repositorio muestra ejemplos explícitos para:

• migraciones con Sequelize
• migraciones con TypeORM

La descripción también menciona un uso más amplio para migraciones en ORMs y plataformas, pero los ejemplos visibles son especialmente sólidos en esos dos ecosistemas. Si usas otro stack, pídele al modelo que traduzca la misma intención de migración a tu toolchain en vez de asumir la misma profundidad nativa.

Cuándo pedir explícitamente orientación de zero-downtime

No des por hecho que el modelo siempre va a optimizar para la seguridad de una migración online. Dilo de forma explícita cuando se cumpla cualquiera de estos casos:

• tablas grandes
• alto volumen de escrituras
• despliegues independientes de aplicación y base de datos
• renombrado de columnas o cambios de tipo
• backfills en rutas calientes
• cambios de constraints con tráfico de producción

Para database-migration en equipos de Database Engineering, este suele ser el punto que separa una respuesta de juguete de una realmente desplegable.

Qué salidas pedirle a la skill

Para usar la skill database-migration con alta confianza, pide un paquete completo, no solo un archivo:

• código de migración
• secuencia de rollout
• secuencia de rollback
• lógica de backfill de datos
• supuestos y riesgos
• checklist de validación
• pasos de limpieza posteriores a la migración

Esto evita que se omita trabajo operativo importante.

Advertencia práctica sobre cambios destructivos directos

La skill se aprovecha mejor para evitar cambios inseguros de un solo paso, como:

• eliminar columnas antiguas de inmediato
• renombrar columnas críticas en caliente sin compatibilidad
• cambiar tipos sin una estrategia de conversión
• añadir constraints non-null antes del backfill
• reescribir tablas grandes sin planificar el impacto de los locks

Si la primera salida hace alguna de estas cosas en una ruta de producción, pide una alternativa por fases.

Preguntas frecuentes sobre la skill database-migration

¿Esta skill database-migration es solo para migraciones con ORM?

No. La skill está planteada para migraciones de esquema y datos en bases de datos a través de ORMs y plataformas distintas. En la práctica, los ejemplos visibles están orientados a ORM, especialmente Sequelize y TypeORM, así que obtendrás mejores resultados si indicas tu stack exacto y pides SQL o adaptación al framework cuando haga falta.

¿La skill database-migration es buena para principiantes?

Sí, con límites. Es accesible porque los ejemplos son concretos, pero da por hecho que sabes evaluar si una migración es segura desde el punto de vista operativo. Quienes empiezan pueden usarla para redactar archivos de migración y planes de rollout, pero no deberían tratar la primera respuesta como lista para producción sin revisarla.

¿Cuándo no debería usar database-migration?

Evita esta skill cuando tu tarea sea puramente conceptual y no implique ejecutar cambios reales de esquema o datos. También encaja mal si esperas validación completa y específica del entorno solo a partir del repositorio, porque esta skill no incluye scripts extra, reglas ni harnesses de prueba en la carpeta expuesta.

¿En qué mejora esto a pedirle a una IA que escriba SQL?

El valor de la database-migration guide está en que plantea la tarea desde el ciclo de vida de la migración, no solo desde la sintaxis. Un prompt simple de SQL suele pasar por alto el rollback, las ventanas de compatibilidad, los backfills por fases y las convenciones de migración del ORM. Esta skill funciona mejor cuando la seguridad del despliegue importa tanto como la corrección del código.

¿Admite despliegues zero-downtime?

Sí, ese es uno de sus casos de uso más claros. Aun así, debes especificar qué significa zero-downtime en tu entorno. La expresión por sí sola es demasiado amplia; el modelo necesita conocer tu orden de despliegue, el patrón de tráfico de lectura y escritura, y tus restricciones de compatibilidad.

Cómo mejorar la skill database-migration

Dale a la skill el diff de esquema junto con las restricciones operativas

La forma más rápida de mejorar la calidad de salida de database-migration es proporcionar a la vez el cambio de esquema y las restricciones de ejecución. Por ejemplo:

Current: orders.status VARCHAR nullable
Target: orders.status ENUM not null
DB: PostgreSQL
Rows: 80M
Traffic: constant writes
Requirement: no downtime, rollback available, deploy app separately

Esto empuja al modelo hacia un diseño de migración por fases en lugar de una sentencia alter simplista.

Pide expand-migrate-contract cuando la seguridad importe

Si el primer borrador parece demasiado destructivo, pide explícitamente un plan expand-migrate-contract. Suele mejorar los resultados en casos como:

• renombrados
• conversiones de tipo
• incorporación de non-null
• división de tablas
• cambios de desnormalización o normalización

Es una de las formas más fiables de obtener mejor database-migration usage con esta skill.

Exige validación y rollback en la primera respuesta

Un fallo habitual es recibir una migración up correcta pero un down débil o poco realista. Puedes mejorar esto pidiendo:

• condiciones de rollback
• advertencias de pérdida de datos
• consultas de verificación
• criterios de éxito después de cada fase

Eso obliga al modelo a razonar desde el principio sobre la reversibilidad.

Aporta el estilo de migraciones existente en tu repo

Si tu proyecto ya tiene convenciones de migración, pega uno o dos archivos representativos y pide a la skill que los siga. Eso mejora de forma tangible el naming, el manejo de transacciones, el estilo de timestamps y los modismos del framework. Es especialmente útil en Sequelize y TypeORM, donde los equipos suelen tener patrones locales más allá de los valores por defecto del framework.

Itera sobre el riesgo de locks, no solo sobre la corrección del código

Después de la primera salida, haz preguntas de seguimiento como:

• Which steps may lock the table?
• Which steps can run while writes continue?
• What should be split into separate deploys?
• Which part is irreversible after backfill?
• What monitoring should we watch during rollout?

Aquí es donde la skill database-migration suele pasar de generar boilerplate a aportar valor real para trabajo de Database Engineering.

Vigila estos modos de fallo comunes

Actúa con cautela si la migración generada:

• asume tablas pequeñas
• omite el rollback
• elimina campos antiguos demasiado pronto
• combina cambio de esquema y backfill masivo en un único paso arriesgado
• ignora la compatibilidad de la aplicación durante la transición
• usa sintaxis del framework que no coincide con tu versión

Estas son razones normales para refinar el prompt, no señales de que la skill sea inútil.

Mejor forma de mejorar los resultados después del primer borrador

Trata la primera respuesta como una propuesta de migración, no como un artefacto final. Después, pide a la skill que la revise en función de:

• el tamaño real de tus tablas
• la situación de índices
• el orden de despliegue esperado
• los hallazgos en canary o staging
• cualquier supuesto fallido detectado en la revisión

Ese bucle de feedback es la forma más práctica de extraer valor de nivel producción del flujo de database-migration install y uso.