Configuración de migraciones de base de datos con TypeORM

Mantener el control de los cambios en una base de datos es fundamental, especialmente en proyectos modernos donde la estructura evoluciona mientras el negocio crece. Aquí conocerás cómo implementar migraciones en bases de datos usando TypeORM junto a NestJS, asegurando integridad y organización a lo largo del desarrollo.

¿Por qué es importante versionar una base de datos con migraciones?

Al igual que el código fuente se versiona con herramientas como Git, las bases de datos pueden gestionarse mediante migraciones. Esto permite aplicar, rastrear y revertir cambios en las tablas o columnas, protegiendo tus datos y facilitando colaboraciones entre equipos.

• Los cambios en la base de datos (agregar, quitar tablas o columnas) afectan directamente a la aplicación y a los usuarios.
• El uso de migraciones asegura que el esquema esté sincronizado en todos los entornos: local, pruebas y producción.
• TypeORM, como ORM, ofrece herramientas CLI y una API para manipular migraciones de forma segura y replicable.

¿Cómo se configura TypeORM para manejar migraciones en NestJS?

Para gestionar migraciones correctamente, TypeORM usa dos conexiones distintas: una para la aplicación NestJS y otra para su CLI. Ambas deben configurarse para acceder a la base de datos, pero con archivos de ajuste separados.

• Es recomendable crear una carpeta database dentro de la carpeta src, donde se colocará el archivo config.ts, necesario para la CLI.
• Esta configuración debe leer variables de ambiente (process.env y dotenv) para definir credenciales, puertos y rutas de entidades.
• Es clave que las entidades mantengan un nombre uniforme (*.entity.ts) para que TypeORM las reconozca automáticamente al generar migraciones.
• Debe desactivarse la sincronización automática (synchronize: false) tanto en la app como en la CLI para evitar cambios inesperados.

¿Qué comandos de TypeORM CLI permiten trabajar con migraciones?

El CLI de TypeORM integrado con NestJS gestiona migraciones mediante scripts de NPM y comandos específicos.

• migration:generate: Genera automáticamente el archivo de migración con base en los cambios detectados en las entidades.
• migration:create: Permite escribir migraciones personalizadas, útil para modificaciones específicas y delicadas.
• migration:run: Aplica las migraciones pendientes a la base de datos.
• migration:show: Muestra el historial de migraciones ejecutadas y pendientes.

Para su integración:

• Exponer TypeORM CLI usando scripts en package.json, apuntando al archivo de configuración adecuado.
• Es común trabajar con proyectos empaquetados en CommonJS; verificar esto en ts.config asegura compatibilidad.

¿Cómo se inicializan y gestionan las migraciones en la base de datos con TypeORM?

La gestión efectiva de migraciones requiere limpiar el estado previo y generar los archivos necesarios:

• Se recomienda realizar un docker compose down -v para borrar contenedores y volúmenes de la base de datos en desarrollo, asegurando un esquema limpio.
• Tras levantar de nuevo los servicios (docker compose up -d), se genera la migración inicial (init migration).
• TypeORM creará un archivo de migración en la carpeta indicada, usando un identificador timestamp para ordenar su aplicación.
• Estas migraciones traducen las entidades actuales en instrucciones SQL que crean tablas, índices, relaciones y constraints.
• Una tabla especial, Migrations, se genera automáticamente para rastrear el estado y versión aplicada.

¿Cómo verificar y aplicar los cambios realizados en las migraciones?

Comprobar y ejecutar migraciones es sencillo con TypeORM y su CLI:

• Usar el comando show para ver si hay migraciones pendientes o problemas de conexión.
• Realizar ajustes en las entidades y generar nuevas migraciones cada vez que haya cambios.
• Aplicar las migraciones con run; TypeORM solo ejecuta las pendientes y marca en la tabla de control cuando se aplicaron correctamente.
• Visualizar en el cliente de la base de datos cómo se crea la estructura y cómo evoluciona el esquema de acuerdo a las migraciones activas.

¿Tienes dudas sobre cómo aplicar migraciones en tu flujo de trabajo NestJS y TypeORM? Comparte tu experiencia o pregunta en los comentarios. ¡La gestión de la base de datos puede ser tan ordenada como el código fuente!