Cuando trabajas con migraciones en TypeORM y ya tienes datos en producción, cualquier cambio en una columna puede borrar información valiosa. Aquí aprenderás a modificar entidades, agregar columnas y ajustar restricciones sin perder los datos de tus usuarios.

¿Cómo agregar columnas nuevas sin romper datos existentes?

Antes de tocar cualquier esquema, conviene tener datos reales en la base. Crea un par de usuarios, categorías y artículos desde tu API para simular un entorno productivo y ver con claridad qué pasa cuando aplicas una migración sobre tablas que ya tienen información.

La primera regla es sencilla: si una columna no existía antes, debe declararse como nullable: true. Si intentas crearla como obligatoria, la migración fallará porque no hay forma de llenar los registros antiguos. Por ejemplo, al agregar description con un tamaño de 800 caracteres a la entidad Category, debes marcarla como nula. Lo mismo aplica para una nueva columna cover_image en categorías.

¿Cuándo debo usar nullable: true en una migración? Siempre que agregues una columna a una tabla que ya tiene registros. Si la haces obligatoria, no podrás llenar las filas antiguas y la migración se romperá.

¿Y si necesito que la columna sea obligatoria?

El flujo correcto es en tres pasos: primero creas la columna como nula, luego ejecutas un script para poblar los registros antiguos con valores reales, y por último corres una segunda migración que cambie la restricción a not null. Este trabajo suele coordinarse con el equipo de data o ingeniería para automatizar el script de poblamiento.

¿Por qué cambiar el tamaño de un varchar puede borrar tus datos?

Aquí viene la parte delicada. Si en Post tienes una columna cover_image con tamaño 255 y decides aumentarla a 800, parecería un cambio inofensivo. Pero al ejecutar migration:generate, TypeORM genera dos instrucciones peligrosas: un DROP COLUMN seguido de un ADD COLUMN con la nueva restricción.

El resultado: todas las imágenes que tus usuarios ya habían cargado desaparecen. La estructura queda correcta, pero los datos se pierden. Y aunque puedes hacer un revert para volver al esquema anterior, los datos ya no se recuperan.

¿Qué hace migration:generate cuando cambio un varchar? En lugar de alterar la columna, la elimina y la crea de nuevo con el tamaño actualizado. Eso borra toda la información previa de esa columna.

Por eso es fundamental abrir el archivo de migración generado y revisar instrucción por instrucción antes de ejecutarlo en producción. Si ves un dropColumn seguido de un addColumn sobre una tabla con datos, detente.

¿Cómo escribir una migración manual con alter column?

La solución es generar una migración manual usando el comando migration:create en lugar de migration:generate. La diferencia es clave:

• generate lee el data source y deduce los cambios automáticamente comparando entidades contra la base.
• create solo te entrega un boilerplate vacío para que tú escribas el SQL.
• create no necesita el flag -d porque no consulta la base de datos.

Dentro del archivo manual, reemplazas el dropColumn por una instrucción de alteración directa:

typescript await queryRunner.query( ALTER TABLE post ALTER COLUMN cover_image TYPE varchar(900) );

En el método down, devuelves la columna a su tamaño anterior, en este caso 800, para mantener la reversibilidad. Al ejecutar migration:run, el cambio se aplica sin tocar los datos. Haces refresh en la base y verificas: el límite ahora es 900 y todas las cover_image siguen ahí.

¿Qué comandos conviene tener a la mano?

Estos son los que más vas a usar al trabajar con migraciones en TypeORM:

• migration:generate: crea la migración deduciendo cambios desde tus entidades.
• migration:create: genera un archivo vacío para escribir SQL manual.
• migration:show: lista qué migraciones se han ejecutado y cuáles están pendientes.
• migration:run: aplica las migraciones pendientes.
• migration:revert: deshace la última migración aplicada, pero no recupera datos.

¿Cuándo revisar manualmente una migración generada?

La respuesta corta: siempre que toques una columna existente. La automatización funciona bien para crear tablas nuevas o agregar columnas, pero falla cuando se trata de modificar restricciones sobre columnas con datos.

Si tu equipo tiene conocimientos de SQL o cuentas con un equipo de data, pídeles que revisen la migración antes de ejecutarla en producción. Un dropColumn mal interpretado sobre una tabla con mil millones de artículos puede convertirse en un incidente serio.

La lección práctica: los datos no son un lujo recuperable. La estructura del esquema sí se puede revertir, pero la información perdida no vuelve. Por eso la disciplina de revisar, ajustar y, cuando sea necesario, escribir migraciones manuales marca la diferencia entre un sistema robusto y uno frágil.

¿Has tenido que rescatar una migración antes de ejecutarla en producción? Cuéntalo en los comentarios.