Configuración y uso de migraciones con TimeORM y TypeScript

Clase 15 de 36 • Curso de NestJS: Persistencia de Datos con TypeORM

Resumen

¿Cómo integrar TimeORM para gestionar migraciones?

Integrar un sistema de migraciones en tu proyecto es crucial para la gestión eficiente y ordenada de los cambios en tu base de datos. TimeORM, con su CLI, te facilita este proceso de manera automatizada, similar a cómo lo hace NEST para APIs. Aprenderás a configurar y correr migraciones utilizando TimeORM, optimizando así la adaptación de tu base de datos a cambios en tu aplicación. ¡Vamos al código!

¿Cómo configuramos las migraciones?

Para configurar migraciones con TimeORM, es fundamental entender que requiere una conexión y configuración propias, diferentes a las de tu aplicación NEST. Puedes optar por usar un archivo ormconfig.json o, preferiblemente, integrar variables de ambiente que añadan flexibilidad.

Crea el archivo de configuración: Define conexiones, host, usuario, password, tipo de base de datos y puerto. Un ejemplo para una base de datos PostgreSQL:

{
  "type": "postgres",
  "host": "localhost",
  "port": 5432,
  "username": "root",
  "password": "123456",
  "database": "mydb",
  "entities": ["dist/**/*.entity{.ts,.js}"],
  "migrations": ["dist/migration/*.js"],
  "cli": {
    "migrationsDir": "src/migration"
  }
}

Usa variables de entorno: Configura host, usuario, y tablas de migración en un archivo .env. Ejemplo:

TYPEORM_CONNECTION=postgres
TYPEORM_HOST=localhost
TYPEORM_USERNAME=root
TYPEORM_PASSWORD=123456
TYPEORM_DATABASE=mydb
TYPEORM_MIGRATIONS_DIR=src/migration

Entidades y migraciones en TypeScript: Cambia a TypeScript ajustando los paths para buscar archivos .ts. Utiliza expresiones regulares como dist/**/*.entity{.ts,.js} para que reconozca las entidades.

¿Cómo ajustar el `package.json` para TimeORM?

Modifica el package.json para incluir scripts que manejen el CLI de TimeORM, facilitando la ejecución de comandos desde tu proyecto.

Actualiza los scripts:

Añade un script para ejecutar el CLI de TimeORM utilizando ts-node.

"scripts": {
  "typeorm": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js",
  "migration:generate": "npm run typeorm migration:generate -- -n"
}

Ejecuta migraciones:
- En consola, usa el script para generar una nueva migración nombrada:
```
npm run migration:generate -- -n InitialMigration
```

¿Qué problemas comunes podemos encontrar y cómo solucionarlos?

Al integrar sistemas complejos como TimeORM, es común enfrentar errores. Aquí te comparto algunos y cómo resolverlos:

Errores de conexión: Verifica que las variables de entorno estén correctamente configuradas sin typos y que el servicio de tu base de datos esté activo.
Problemas con TypeScript: Asegúrate de que el CLI de TimeORM reconoce las configuraciones tipeadas. Ajusta el uso de ts-node para que interprete correctamente decoradores y estructuras modulares.
```
"scripts": {
  "typeorm": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js"
}
```
Migraciones no generadas: Si encuentras que no hay cambios detectados, verifica si las tablas fueron creadas manualmente. Si es así, elimínalas y vuelve a generar las migraciones para que el CLI las reconozca.

¿Cómo asegurarnos de que las migraciones corren correctamente?

Finalmente, ejecutar eficazmente las migraciones es vital. Un error común es que no se detecten cambios si las tablas ya existen. Siempre:

Elimina tablas creadas previamente desde la consola de administración antes de generar nuevas migraciones.
Revisa los logs tras ejecutar migraciones para confirmar que no hay errores silenciosos.

Implementa las mejores prácticas, como evitar el uso del modo síncrono en producción, y confía en las migraciones para manejar los datos historiales correctamente. Sigue explorando y configurando, y estarás un paso más cerca de una base de datos robusta y bien gestionada. ¡Ánimo, sigue adelante y mejora cada día!

Eduardo Pech

student•

Lo que vimos:

No olviden ajustarlo a sus datos .env

TYPEORM_CONNECTION = postgres
TYPEORM_HOST = localhost
TYPEORM_USERNAME = root
TYPEORM_PASSWORD = 123456
TYPEORM_DATABASE = my_db
TYPEORM_PORT = 5432
TYPEORM_SYNCHRONIZE = false
TYPEORM_LOGGING = true
TYPEORM_ENTITIES = src/**/*.entity.ts

TYPEORM_MIGRATIONS = src/database/migrations/*.ts
TYPEORM_MIGRATIONS_DIR = src/database/migrations
TYPEORM_MIGRATIONS_TABLE_NAME = migrations

package.json

"scripts": {
    "typeorm": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js",
    "migrations:generate": "npm run typeorm -- migration:generate -n"
  },

Comando para generar la migration

npm run migrations:generate -- init

Si realizaron el test de mysql, no olviden regresarlo a postgres.

database.module.ts

imports: [
    TypeOrmModule.forRootAsync({
      inject: [config.KEY],
      useFactory: (configService: ConfigType<typeof config>) => {
        const { user, password, host, dbName, port } = configService.postgres;

        return {
          type: 'postgres',
          host,
          port,
          username: user,
          password,
          database: dbName,
          synchronize: true,
          autoLoadEntities: true,
        };
      },
    }),
  ],

Renato Renzo Luna Herrera

student•

Consulta, por que tendríamos que regresar a postgres? no se puede hacer lo mismo en MySQL

Miguel Angel Reyes Moreno

student•

Porque en el curso siguen usando Postgres, pero tú puedes ajustarlo a MySQL si así lo prefieres

Jenny Aguilar

student•

Si ingresas al curso recientemente, sobre abril de 2023, te recomiendo que vayas a los módulos 32, 33 y 34 antes de seguir, ya que explican como migrar el proyecto a las versiones más recientes. El módulo 34 se centra en las migraciones. Los cambios son importantes, particularmente con las migraciones de TypeORM, ya que ahora pide configurar un archivo data-source.ts y cambia el script. Hazlo y te ahorraras varias horas de investigación y dolores de cabeza.

Cesar Augusto Torrens Acosta

student•

me salvaste la vida xD

Dennis Adrian Guzman Betancur

student•

Algunas cosas en TypeORM son diferentes actualmente (versión 0.3.7) a como están esta lección

Ya no existe documentación acerca de archivos de configuración como el ormconfig.json o las variables de entorno
Los comandos del CLI funciona de una manera diferente

Hice un pequeño tutorial mostrando los cambios que yo hice para que me funcione el CLI:

Configurando el CLI para migraciones

Ernán Alexander Velásquez Ramírez

student•

Así es. Al parecer se han reducido las opciones a solo una: instalar el CLI, configurar las migraciones y ejecutarlas desde el comando del package json.

Camilo Sepulveda

student•

Si tienen el error de:

Not enough non-option arguments: got 0, need at least 1

Recomiendo bajar la versión de typeORM a la 0.2.45

npm remove typeorm 
npm install typeorm@0.2.45 --save

Jose Luis Campos Bautista

student•

Thank u!!

RENNY DE JESÚS PETIT JAIMES

student•

Muchas gracias, me funcionó

Ricardo Tribaldos Hernández

student•

Para evitar futuros dolores de cabeza en sus despliegues, traten de definir siempre sus variables de entorno en archivos .env sin dejar espacios antes/después del signo igual:

# Eviten esto 🚫
TYPEORM_CONNECTION = postgres

# Así es mejor ✔️
TYPEORM_CONNECTION=postgres

Marcos Vargas

student•

A mi me Funciono de la siguiente forma: Crear un dataSource.ts

import { DataSource } from 'typeorm';

export const dataSource = new DataSource({
  type: 'postgres',
  host: 'localhost',
  port: 5432,
  username: 'nada',
  password: '123456',
  database: 'my_db',
  logging: true,
  synchronize: false,
  entities: ['src/**/**/*.entity.ts'],
  migrations: ['src/database/migrations/*.ts'],
});

Posteriormente en packaje.json:

    "typeorm": "typeorm-ts-node-commonjs -d src/database/dataSource.ts",
    "migration:generate": "npm run typeorm migration:generate src/database/initaltables"

Y finalmente correr:

npm run migration:generate

Dany Fernando Lasso Ayala

student•

Sos grande Marcos

Miguel Palacios Banda

student•

Holaaa, lo has probado con variables de entorno?

Ernán Alexander Velásquez Ramírez

student•

La configuración dada por el profesor dejó de funcionar a partir de la versión 0.3 de typeorm según hilos de issues de github. La forma en cómo lo resolví fue la siguiente:

Instalé ts-node y typeorm

npm i typeorm
npm install ts-node --save-dev

Creé un archivo donde instancié la clase Datasource en la carpeta config
Tomar nota que las rutas entities y migrations debe ser acorde a cómo tienen organizadas las carpetas de su proyecto
Configuré package json

"typeorm": "typeorm-ts-node-esm",
"migration:generate": "npm run typeorm migration:generate -- -d src/config/typeOrm.config-migrations.ts src/database/migrations/migration",

Lo que todavía me hace falta mejorar es que todavía no puedo darle un nombre a los archivos dinámicamente.

Tomar nota que para correr el comando migration:generate debe estar encendida la base de datos para recibir peticiones.

Fuentes: Issue Github Documentación oficial

Ferran Solis Chorvat

student•

Muchas gracias por tu aporte! Me funcionó

José Carrillo

student•

Les dejo mi versión del archivo typeorm.config.ts:

import { DataSource } from 'typeorm';
import * as dotenv from 'dotenv';

import { environments } from './environments';

dotenv.config({
  path: environments[process.env.NODE_ENV] || '.env',
});

const PostgresDataSource = new DataSource({
  type: 'postgres',
  host: process.env.DATABASE_HOST,
  port: parseInt(process.env.DATABASE_PORT, 10),
  username: process.env.DATABASE_USER,
  password: process.env.DATABASE_PASS,
  database: process.env.DATABASE_NAME,
  synchronize: false,
  logging: true,
  entities: ['src/**/entities/*.entity.ts'],
  migrations: ['src/database/migrations/*.ts'],
});

export default PostgresDataSource;

y los scripts quedaron así:

"typeorm": "typeorm-ts-node-commonjs",
      "typeorm:generate": "yarn typeorm migration:generate -d src/typeorm.config.ts src/database/migrations/$MIGRATION_NAME",
      "typeorm:create": "yarn typeorm migration:create",
      "typeorm:run": "yarn typeorm migration:run -d src/typeorm.config.ts",
      "typeorm:revert": "yarn typeorm revert -d src/typeorm.config.ts"

Y no olviden instalar el ts-node porque con eso fue que me dio.

Andrés Esteban Rodríguez Jiménez

student•

Configurando el CLI para migraciones (Actual)

Crear un archivo con una instancia de DataSource

Veamos cómo configurar el CLI de TypeORM para trabajar con migraciones en nuestro proyecto utilizando un archivo de instancia de DataSource.

Crear un archivo con una instancia de DataSource: Para comenzar, crearemos un archivo llamado dataSource.ts en la carpeta src/database. Aquí está un ejemplo de cómo se podría configurar este archivo:

import { DataSource } from 'typeorm';
import { config } from 'dotenv';
import { ConfigService } from '@nestjs/config';

config();
const configService = new ConfigService();

// creamos una nueva instancia de DataSource con un objeto de configuración
export default new DataSource({
  type: 'postgres',
  username: configService.get('POSTGRES_USER'),
  password: configService.get('POSTGRES_PASSWORD'),
  database: configService.get('POSTGRES_DB'),
  port: configService.get('POSTGRES_PORT'),
  host: configService.get('POSTGRES_HOST'),
  synchronize: false,
  logging: true,
	
	// entidades que va a leer
  entities: ['src/*/*/*.entity.ts'],
	
	// donde leerá las migraciones
	migrations: ['src/database/migrations/*.ts'],
	
	// nombre de la tabla de migraciones
	migrationsTableName: 'migrations',
});

Cambios en los comandos del CLI: Ahora, necesitaremos actualizar los comandos en el archivo package.json para reflejar los cambios en el CLI de TypeORM.

{
	"scripts": {
		"typeorm": "typeorm-ts-node-commonjs -d src/database/dataSource.ts",
		"migration:generate": "npm run typeorm migration:generate src/database/migrations/migration"
	}
}

En los comandos actualizados:

El comando typeorm se ha cambiado a typeorm-ts-node-commonjs para trabajar con TypeScript en lugar de JavaScript común.
El comando migration:generate ahora requiere el uso del flag -dataSource seguido de la ruta al archivo dataSource.ts que hemos creado.

Es importante tener en cuenta que ahora ya no se utiliza el flag -n para indicar el nombre del archivo de migración. En su lugar, al ejecutar el comando migration:generate, debemos especificar la ruta y el nombre del archivo de migración, que en mi caso lo hago de forma automática desde el package.json.

Para crear la migración ejecutamos el siguiente comando:

npm run migration:generate

Y listo, así es como creamos la configuración para generar migraciones.

miguel angel gonzalez jaimen

student•

Muchas gracias por esto, deberían subir esto en un video del mismo curso.

José Carrillo

student•

El curso está algo desfasado, pero a mí me dio con esto 👇🏻

Primero hice una instalación del paquete ts-node como dev:

yarn add ts-node -D

Cree un archivo typeorm.config.ts dentro del src, con lo siguiente:

import { DataSource } from 'typeorm';
import * as dotenv from 'dotenv';

import { environments } from './environments';

dotenv.config({
  path: environments[process.env.NODE_ENV] || '.env',
});

const PostgresDataSource = new DataSource({
  type: 'postgres',
  host: process.env.DATABASE_HOST,
  port: parseInt(process.env.DATABASE_PORT, 10),
  username: process.env.DATABASE_USER,
  password: process.env.DATABASE_PASS,
  database: process.env.DATABASE_NAME,
  synchronize: false,
  logging: true,
  entities: ['src/**/entities/*.entity.ts'],
  migrations: ['src/database/migrations/*.ts'],
});

export default PostgresDataSource;

Y los scripts quedaron así:

      "typeorm": "typeorm-ts-node-commonjs",
      "typeorm:generate": "yarn typeorm migration:generate -d src/typeorm.config.ts src/database/migrations/$MIGRATION_NAME",
      "typeorm:create": "yarn typeorm migration:create src/database/migrations/$MIGRATION_NAME",
      "typeorm:run": "yarn typeorm migration:run -d src/typeorm.config.ts",
      "typeorm:revert": "yarn typeorm revert -d src/typeorm.config.ts"

Y para ejecutar el generate lo hago asi:

MIGRATION_NAME=primer-migration yarn typeorm:generate

Para crear una migración:

MIGRATION_NAME=initial yarn typeorm:create

Fue la manera con la que me quedo lo más dinámico.

David Bryan Arias Castro

student•

Como seria con NPM

José Carrillo

student•

Exactamente lo mismo, pero en lugar de colocar

yarn ...

Seria con

npm run ...

Jassen Castillo

student•

hola! me fui a la documentacion actual y esto de ormconfig esta deprecado, recomiendo actualizar esta parte del curso https://typeorm.io/changelog#breaking-changes-1

Froilán Martin Ramos Garcia

student•

Tengo una consulta, al usar migraciones y las variables de entorno para la config de TypeORM, ya no es necesaria la configuracion que se hizo en **database.module.ts ** importando el modulo de TypeOrmModule? Gracias

Braian Molina

student•

Paso configuracion con dontenv para usar variables de entornos:

// src/database.dataSource.ts
import { DataSource } from 'typeorm';
import 'dotenv/config';

export const connectionSource = new DataSource({
  type: 'postgres',
  username: process.env.POSTGRES_USER,
  password: process.env.POSTGRES_PASSWORD,
  database: process.env.POSTGRES_DATABASE,
  port: Number(process.env.POSTGRES_PORT),
  host: process.env.POSTGRES_HOST,
  synchronize: false,
  logging: true,
  entities: ['src/*/*/*.entity.ts'],
  migrations: ['src/database/migrations/*.ts'],
});

Agregamos los siguientes comandos:

"typeorm": "typeorm-ts-node-commonjs -d src/database/dataSource.ts",
"migration:generate": "npm run typeorm migration:generate ./src/database/migrations/init"

ejecutamos el comando:

npm run migration:generate

Dando como resultado la creacion del archivo 👍:

Mauricio Jourdan

student•

Excelente! Muchas gracias.

Mónica Paola Parra López

student•

A mi lo que me funciono fue crear un dataSource.ts en la carpeta de database

import { DataSource } from 'typeorm';

export const connectionSource = new DataSource({
  type: 'postgres',
  host: 'localhost',
  port: 5432,
  username: 'root',
  password: '123456',
  database: 'my_db',
  logging: true,
  synchronize: false,
  entities: ['src/**/*.entity.ts'],
  migrations: ['src/database/migrations/*.ts'],
});

luego crear el siguiente script

 "migration:generate": "./node_modules/.bin/ts-node ./node_modules/.bin/typeorm migration:generate -d src/database/dataSource.ts"

y finalmente correrlo en la terminal de la siguiente forma

npm run migration:generate -- src/database/migrations/init

y eso me genero mi migración, espero les sirva

David Hilera

student•

Muchas gracias por el aporte.

Esteban Chamba Jimenez

student•

Revisando una librería que utilizo de algún tiempo atrás para general las entidades, me he encontrado con esto: https://github.com/Kononnable/typeorm-model-generator/issues/329

Básicamente dice que el futuro de TypeORM es incierto, con errores y un mantenimiento muy pobre, otro artìculo sobre el tema está acá. https://news.ycombinator.com/item?id=26888369

David Bryan Arias Castro

student•

Deben actualizar esta parte del curso.

Andre Huaman Yovera

student•

Nota: En el curso actual se está utilizando una versión de TypeORM de 2021. Sin embargo, en 2024, se han implementado cambios en la configuración de TypeORM. Estos cambios se abordan en la siguiente clase: Migraciones en TypeORM - Clase 34. Asegúrate de revisarla para entender cómo aplicar la nueva configuración correctamente.

Andres Prieto

student•

En la documentación hay un ejemplo que recomiendo mucho ver:

https://typeorm.io/data-source-options#data-source-options-example

Muestra cuáles son las opciones del objeto de Data Source

Andres Prieto

student•

Este aspecto de TypeORM es un desastre, para la quien esté usando la versión: 9.0.1 de TypeORM, la forma de poder conectar a una base de datos, ahora es usando un objeto por aparte llamado 'DataSource' que ha de exportarse, el archivo que le contiene puede poner en cualquier lugar, pero TypeORM por defecto lo genera en la ruta ./src/data-source.ts, por lo que si se pone con ese nombre en esa ruta lo va a poder encontrar por defecto, si se desea o necesita; también se puede especificar un path a ese archivo, por ejemplo: './src/database/dataSource.ts' (Ahí lo puse yo), el archivo dataSource.ts debería contener esto:

import { ConfigService } from '@nestjs/config';
import { DataSource } from 'typeorm';
import { config } from 'dotenv';

config();

const configService = new ConfigService();

const connectionSource = new DataSource({
  type: 'postgres',
  port: parseInt(configService.get('DATABASE_PORT'), 10),
  host: configService.get('DATABASE_HOST'),
  username: configService.get('DATABASE_USER'),
  password: configService.get('DATABASE_PASSWORD'),
  database: configService.get('DATABASE_NAME'),
  logging: configService.get('ORM_LOG'),
  synchronize: configService.get('ORM_SYNC'),
  entities: ['src/**/*.entity.ts'],
  migrations: ['./src/database/migrations/*.ts'],
});

connectionSource.initialize();

export { connectionSource };

Para no hard codear las variables de entorno se puede usar dotenv que se instala al instalar @nest/config, como se ve en un comentario de esta guía

Sin embargo, la opción migrations: ['./src/database/migrations/*.ts'] realmente no hace nada, pues en la documentación de TypeORM (El décimo ejemplo), en el ejemplo de este apartado simpre especifican el path en donde se ha de crear el archivo de migraciones:

npx typeorm-ts-node-esm migration:generate ./src/migrations/update-post-table -d ./src/data-source.ts

Si usas npx typeorm-ts-node-esm npm se ahorra un cambio de contexto por así decirlo

Y si no lo pones te salta un error del CLI, por lo que por mantenibilidad, recomendaría dejar ese script del package.json, así:

"migration:generate": "npx typeorm-ts-node-commonjs migration:generate -p -d src/database/dataSource.ts ./migrations/current.migration"

O bien sin poner la ruta ./migrations/current.migration, porque de esa manera se hace menos incómodo de buscar luego, pero toca redactar a mano la ruta en donde se va generar la migración

Andres Prieto

student•

Un par de correcciones:

migrations: ['./src/database/migrations/*.ts']  // Esta opción lo que hace es que indica en donde se han de leer las migraciones, no en donde TypeORM debería de ponerlas

Usar la terminología de whatever.whatever en el archivo que se va a generar (./migrations/current.migration como puse arriba), genera un error en el CLI de TypeORM, esa terminación debe de ir sin puntos o en cambio con barra al piso "_"

Como se muestra en esta documentación, se puede especificar más bien poco al objeto de Data Source

Jimmy Alex Guevara Cruz

student•

Tengo problemas para generar las migraciones!

Me aparece el siguiente error: Falta argumento requerido: dataSource.

Alguien que me ayude con esto?

Miguel Manrique

student•

Tengo el mismo problema, si es cuestión de la versión, pero no logro configurar que el CLI tome las variables de entorno, y no me parece correcto hacer un downgrade de la versión

cli-ts-node-commonjs.js migration:generate <path>

Generates a new migration file with sql needs to be executed to update schema.

Opciones:
  -h, --help          Muestra ayuda                                   [booleano]
  -d, --dataSource    Path to the file where your DataSource instance is
                      defined.                [cadena de caracteres] [requerido]
  -p, --pretty        Pretty-print generated SQL     [booleano] [defecto: false]
  -o, --outputJs      Generate a migration file on Javascript instead of
                      Typescript                     [booleano] [defecto: false]
      --dr, --dryrun  Prints out the contents of the migration instead of
                      writing it to a file           [booleano] [defecto: false]
      --ch, --check   Verifies that the current database is up to date and that
                      no migrations are needed. Otherwise exits with code 1.
                                                     [booleano] [defecto: false]
  -t, --timestamp     Custom timestamp for the migration name
                                                       [número] [defecto: false]
  -v, --version       Muestra número de versión                       [booleano]

Hacen falta argumentos no-opcionales: Número recibido 0, necesita por lo menos 1

Julian Francisco Pinchao Ortiz

student•

Lo pudieron solucionar? Tengo el mismo error

Jilson Pérez

student•

¿Porqué cuando corro una migración me crea la tabla typeorm_metadata? Saben como desactivar esta opción porque no le veo la utilidad

Configuración y uso de migraciones con TimeORM y TypeScript

¿Cómo integrar TimeORM para gestionar migraciones?

¿Cómo configuramos las migraciones?

¿Cómo ajustar el package.json para TimeORM?

¿Qué problemas comunes podemos encontrar y cómo solucionarlos?

¿Cómo asegurarnos de que las migraciones corren correctamente?

¿Cómo ajustar el `package.json` para TimeORM?