Actualizar el sistema de migraciones es uno de los pasos más críticos al migrar de TypeORM 0.2 a TypeORM 0.3. Los cambios no solo afectan la forma en que se ejecutan los comandos, sino también cómo se configura la conexión a la base de datos. A continuación se explican los ajustes necesarios para que todo funcione correctamente en un proyecto con NestJS 9.
¿Por qué TypeORM 0.3 ya no lee variables de entorno ni ormconfig?
En versiones anteriores, TypeORM podía leer la configuración de conexión desde variables de entorno predefinidas o desde un archivo llamado ormconfig.json. Ambas opciones han sido deprecadas en la versión 0.3 [01:15]. Esto significa que si tu proyecto dependía de cualquiera de esas dos formas, necesitas un ajuste obligatorio.
El concepto central ahora es el DataSource. Se trata de una instancia donde defines explícitamente los datos de conexión: tipo de base de datos, URL, entidades, migraciones y más. TypeORM ya no adivinará de dónde obtener esos datos.
Es fundamental entender que existen dos conexiones diferentes [02:05]:
- La conexión que usa tu API en producción para consultar y escribir datos.
- La conexión que usa el sistema de migraciones desde la línea de comandos.
Cada una corre en un nivel distinto y requiere su propia configuración.
¿Cómo se crea el archivo DataSource para migraciones?
Dentro del módulo de database, se crea un archivo data-source.ts con la siguiente estructura [03:00]:
typescript
import { DataSource } from 'typeorm';
export const appDataSource = new DataSource({
type: 'postgres',
url: 'postgres://usuario:password@host:puerto/nombre_db',
synchronize: false,
logging: false,
migrations: ['./src/database/migrations/.ts'],
entities: ['./src/**/.entity.ts'],
});
- type: el motor de base de datos, en este caso
postgres.
- url: un string con toda la información de conexión en un solo lugar.
- synchronize: se establece en
false para evitar cambios automáticos en producción.
- migrations y entities: rutas donde TypeORM encuentra los archivos correspondientes.
¿Qué cambió en los scripts del package.json?
El comando para invocar el CLI de TypeORM ahora utiliza un módulo especial llamado ESM (EcmaScript Modules) [05:22]. Además, se requiere pasar el parámetro -d para indicar la ubicación del DataSource:
"typeorm": "typeorm-ts-node-esm -d ./src/database/data-source.ts"
Otro cambio importante está en el comando generate. Antes se usaba -n seguido del nombre de la migración. Ahora se debe indicar la ruta completa donde se guardará el archivo [08:20]:
bash
npm run migrations:generate -- ./src/database/migrations/change-limit-brand-name
TypeORM añade automáticamente un timestamp al nombre para mantener el orden de ejecución. Los comandos run, show y drop se mantienen prácticamente iguales.
¿Cómo leer variables de entorno desde el DataSource?
Dejar credenciales de conexión en texto plano dentro del código no es seguro. En la API de NestJS se utiliza @nestjs/config para leer el archivo .env, pero el sistema de migraciones no corre dentro de NestJS [10:45]. Por eso se necesita instalar el paquete dotenv:
bash
npm install dotenv
Luego se importa y configura en el archivo data-source.ts [11:30]:
typescript
import * as dotenv from 'dotenv';
import { DataSource } from 'typeorm';
dotenv.config();
export const appDataSource = new DataSource({
type: 'postgres',
url: process.env.DATABASE_URL,
synchronize: false,
logging: false,
migrations: ['./src/database/migrations/.ts'],
entities: ['./src/**/.entity.ts'],
});
Por defecto, dotenv.config() busca un archivo .env en la raíz del proyecto. Este archivo no se sube al repositorio porque está en el .gitignore, lo cual garantiza que las credenciales permanezcan seguras. Al desplegar en plataformas como AWS, Heroku o Digital Ocean, las variables de entorno se configuran directamente en el servicio [12:30].
¿Cómo verificar que el sistema de migraciones funciona?
Una vez configurado el DataSource, se pueden ejecutar los comandos habituales [06:50]:
npm run migrations:show muestra las migraciones pendientes y ejecutadas.npm run migrations:run ejecuta las migraciones faltantes.npm run migrations:drop elimina todas las migraciones aplicadas.
Las migraciones funcionan como un control de versiones para la base de datos [07:40]. En un sistema productivo no se borra la base de datos desde cero, sino que se aplican cambios de estructura de forma controlada y uniforme.
Con estos ajustes, el proyecto queda actualizado de NestJS 7 con TypeORM 0.2 a NestJS 9 con TypeORM 0.3, incluyendo un sistema de migraciones seguro y listo para producción. Si tienes dudas sobre la configuración o has encontrado diferencias en tu proyecto, comparte tu experiencia en los comentarios.
