How to Use Migrations in NestJS: Step-by-Step Guide

In NestJS, you use migrations by integrating a database ORM like TypeORM and running migration commands via the CLI. Define migration files that describe schema changes, then execute them with npm run typeorm migration:run to update your database safely.

Syntax

To use migrations in NestJS with TypeORM, you typically use the CLI commands and migration files structured like this:

• typeorm migration:create -n MigrationName: Creates a new migration file.
• typeorm migration:run: Runs all pending migrations.
• typeorm migration:revert: Reverts the last executed migration.

Migration files export a class with up and down methods to apply or undo changes.

typescript

import { MigrationInterface, QueryRunner } from "typeorm";

export class MigrationNameTimestamp implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    // Code to apply changes, e.g., create table
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    // Code to revert changes, e.g., drop table
  }
}

Example

This example shows how to create a migration that adds a users table and then run it using NestJS with TypeORM.

typescript

import { MigrationInterface, QueryRunner, Table } from "typeorm";

export class CreateUsersTable1680000000000 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.createTable(
      new Table({
        name: "users",
        columns: [
          { name: "id", type: "int", isPrimary: true, isGenerated: true, generationStrategy: "increment" },
          { name: "name", type: "varchar" },
          { name: "email", type: "varchar", isUnique: true },
          { name: "createdAt", type: "timestamp", default: "now()" }
        ]
      })
    );
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.dropTable("users");
  }
}

Output

Migration CreateUsersTable1680000000000 has been run successfully.

Common Pitfalls

Common mistakes when using migrations in NestJS include:

• Not configuring ormconfig.json or DataSource properly, causing migration commands to fail.
• Forgetting to generate migration files after changing entities, leading to schema mismatches.
• Running migrations without backing up data, risking data loss.
• Using legacy CLI commands instead of the latest DataSource CLI in TypeORM v0.3+.

Always check your migration files before running and test in a development environment first.

bash

/* Wrong: Using old CLI command (legacy) */
// typeorm migration:generate -n NewMigration

/* Right: Using DataSource CLI (TypeORM v0.3+) */
// npx typeorm-ts-node-commonjs migration:generate -d ./src/data-source.ts -n NewMigration

Quick Reference

Command	Description
typeorm migration:create -n MigrationName	Create a new migration file
typeorm migration:generate -n MigrationName	Generate migration from entity changes
typeorm migration:run	Run all pending migrations
typeorm migration:revert	Revert the last migration
npx typeorm-ts-node-commonjs migration:generate -d ./src/data-source.ts -n MigrationName	Generate migration using DataSource CLI (TypeORM v0.3+)

Key Takeaways

Use TypeORM migrations in NestJS to safely update your database schema.

Always generate migration files after entity changes before running migrations.

Configure your DataSource or ormconfig correctly to avoid CLI errors.

Run migrations in development first to prevent data loss.

Use the latest TypeORM CLI commands compatible with your version.