Migrations in NestJS - Mini Project: Build & Apply

Database Migrations with NestJS

📖 Scenario: You are building a simple NestJS application that manages a list of books. You need to set up database migrations to create and update the database schema safely over time.

🎯 Goal: Learn how to create and run migrations in a NestJS project using TypeORM to manage database schema changes step-by-step.

📋 What You'll Learn

Create an initial migration file to set up the books table

Add a configuration variable for the migration directory

Write a migration to add a new column to the books table

Run the migration and finalize the setup in the NestJS project

💡 Why This Matters

🌍 Real World

Database migrations help developers safely update database schemas as applications grow and change, avoiding data loss and keeping environments consistent.

💼 Career

Understanding migrations is essential for backend developers working with databases and frameworks like NestJS to maintain and evolve production databases.

1

Create Initial Migration File

Create a migration file named InitialBooksMigration that creates a table called books with columns id (primary key, auto-increment integer) and title (string). Use TypeORM migration syntax inside a class that extends MigrationInterface with up and down methods.

NestJS

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

export class InitialBooksMigration implements MigrationInterface {
    public async up(queryRunner: QueryRunner): Promise {
        // Your code here
    }

    public async down(queryRunner: QueryRunner): Promise {
        // Your code here
    }
}

Hint

Use queryRunner.createTable inside the up method to create the table. Use queryRunner.dropTable inside the down method to remove it.

2

Add Migration Directory Configuration

In your ormconfig.ts or equivalent TypeORM config file, add a configuration variable called migrationsDir and set it to 'src/migrations'. This will tell TypeORM where to find migration files.

NestJS

import { DataSourceOptions } from 'typeorm';

export const ormconfig: DataSourceOptions = {
    // Your code here
};

Hint

Add migrationsDir: 'src/migrations' inside the exported config object.

3

Add Migration to Add Author Column

Create a new migration class named AddAuthorToBooksMigration that adds a new column called author of type varchar to the books table in the up method. In the down method, remove the author column.

NestJS

import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm';

export class AddAuthorToBooksMigration implements MigrationInterface {
    public async up(queryRunner: QueryRunner): Promise {
        // Add author column here
    }

    public async down(queryRunner: QueryRunner): Promise {
        // Remove author column here
    }
}

Hint

Use queryRunner.addColumn in up and queryRunner.dropColumn in down.

4

Run Migrations and Finalize Setup

In your NestJS main application file or migration script, import DataSource from typeorm, create a new DataSource instance using ormconfig, and call initialize() followed by runMigrations() to apply all pending migrations.

NestJS

const dataSource = new DataSource(ormconfig);

// Initialize and run migrations
// Your code here

Hint

Call initialize() on the DataSource instance, then runMigrations() inside the then callback.

Practice

1. What is the main purpose of migrations in a NestJS project using TypeORM?

easy

A. To handle HTTP requests and responses

B. To safely update the database schema step-by-step

C. To write business logic for the application

D. To manage user authentication

Solution

1. Step 1: Understand what migrations do

   Migrations help change the database structure safely without losing data.

2. Step 2: Identify the correct purpose in NestJS context

   They are not for business logic or HTTP handling but for database schema updates.

3. Final Answer:

   To safely update the database schema step-by-step -> Option B

4. Quick Check:

   Migrations = safe database updates [OK]

Hint: Migrations change database structure safely [OK]

Common Mistakes:

• Confusing migrations with business logic
• Thinking migrations handle HTTP requests
• Assuming migrations manage authentication

2. Which command correctly runs all pending migrations in a NestJS project using TypeORM?

easy

A. npx typeorm migration:create

B. npx typeorm migration:revert

C. npx typeorm migration:generate

D. npx typeorm migration:run

Solution

1. Step 1: Recall commands for migrations

   migration:run applies pending migrations to the database.

2. Step 2: Differentiate from other commands

   migration:create creates a new migration file, migration:generate generates migration from schema changes, and migration:revert undoes the last migration.

3. Final Answer:

   npx typeorm migration:run -> Option D

4. Quick Check:

   Run migrations = migration:run [OK]

Hint: Run migrations with migration:run command [OK]

Common Mistakes:

• Using migration:create to run migrations
• Confusing migration:generate with migration:run
• Using migration:revert to apply migrations

3. Given this migration class, what will happen when up() is run?

export class AddAgeColumn1678901234567 {
  async up(queryRunner) {
    await queryRunner.query(`ALTER TABLE users ADD COLUMN age int`);
  }
  async down(queryRunner) {
    await queryRunner.query(`ALTER TABLE users DROP COLUMN age`);
  }
}

medium

A. Creates a new table called 'age'

B. Removes the 'age' column from the 'users' table

C. Adds a new integer column 'age' to the 'users' table

D. Throws a syntax error because of missing semicolons

Solution

1. Step 1: Analyze the up() method

   The up() method runs SQL to add a column named 'age' of type integer to the 'users' table.

2. Step 2: Understand the effect of the query

   This modifies the existing 'users' table by adding the new column; it does not remove columns or create new tables.

3. Final Answer:

   Adds a new integer column 'age' to the 'users' table -> Option C

4. Quick Check:

   up() adds column 'age' [OK]

Hint: up() applies changes like adding columns [OK]

Common Mistakes:

• Confusing up() with down() method
• Thinking it creates a new table
• Assuming syntax error due to semicolons

4. You wrote this migration but get an error when running npx typeorm migration:run. What is the likely problem?

export class RemoveEmailColumn1678901234568 {
  async up(queryRunner) {
    await queryRunner.query(`ALTER TABLE users DROP email`);
  }
  async down(queryRunner) {
    await queryRunner.query(`ALTER TABLE users ADD email varchar(255)`);
  }
}

medium

A. The SQL syntax for dropping a column is incorrect

B. The migration class name is invalid

C. Missing async keyword in down() method

D. The migration file is not saved

Solution

1. Step 1: Check the SQL in up() method

   The query ALTER TABLE users DROP email is incorrect SQL syntax for dropping a column.

2. Step 2: Correct SQL syntax for dropping a column

   The correct syntax is ALTER TABLE users DROP COLUMN email. Missing 'COLUMN' causes the error.

3. Final Answer:

   The SQL syntax for dropping a column is incorrect -> Option A

4. Quick Check:

   DROP COLUMN keyword required in SQL [OK]

Hint: Use DROP COLUMN to remove columns in SQL [OK]

Common Mistakes:

• Omitting COLUMN keyword in DROP statement
• Assuming class name causes error
• Forgetting async keyword (not the cause here)

5. You want to create a migration that renames a column 'username' to 'user_name' in the 'accounts' table and can be reverted. Which up() and down() methods are correct?

hard

A. async up(queryRunner) {
await queryRunner.query(`ALTER TABLE accounts RENAME COLUMN username TO user_name`);
}
async down(queryRunner) {
await queryRunner.query(`ALTER TABLE accounts RENAME COLUMN user_name TO username`);
}

B. async up(queryRunner) {
await queryRunner.query(`ALTER TABLE accounts CHANGE username user_name varchar(255)`);
}
async down(queryRunner) {
await queryRunner.query(`ALTER TABLE accounts CHANGE user_name username varchar(255)`);
}

C. async up(queryRunner) {
await queryRunner.query(`ALTER TABLE accounts DROP COLUMN username`);
await queryRunner.query(`ALTER TABLE accounts ADD COLUMN user_name varchar(255)`);
}
async down(queryRunner) {
await queryRunner.query(`ALTER TABLE accounts DROP COLUMN user_name`);
await queryRunner.query(`ALTER TABLE accounts ADD COLUMN username varchar(255)`);
}

D. async up(queryRunner) {
await queryRunner.query(`RENAME COLUMN username TO user_name`);
}
async down(queryRunner) {
await queryRunner.query(`RENAME COLUMN user_name TO username`);
}

Solution

1. Step 1: Identify correct SQL syntax for renaming columns

   The standard SQL syntax supported by many databases is ALTER TABLE table_name RENAME COLUMN old_name TO new_name.

2. Step 2: Check each option's SQL correctness and revert logic

   async up(queryRunner) {
     await queryRunner.query(`ALTER TABLE accounts RENAME COLUMN username TO user_name`);
   }
   async down(queryRunner) {
     await queryRunner.query(`ALTER TABLE accounts RENAME COLUMN user_name TO username`);
   }

   uses correct syntax for both up() and down() to rename and revert the column name.

   async up(queryRunner) {
     await queryRunner.query(`ALTER TABLE accounts CHANGE username user_name varchar(255)`);
   }
   async down(queryRunner) {
     await queryRunner.query(`ALTER TABLE accounts CHANGE user_name username varchar(255)`);
   }

   uses MySQL-specific CHANGE syntax which may not be portable.

   async up(queryRunner) {
     await queryRunner.query(`ALTER TABLE accounts DROP COLUMN username`);
     await queryRunner.query(`ALTER TABLE accounts ADD COLUMN user_name varchar(255)`);
   }
   async down(queryRunner) {
     await queryRunner.query(`ALTER TABLE accounts DROP COLUMN user_name`);
     await queryRunner.query(`ALTER TABLE accounts ADD COLUMN username varchar(255)`);
   }

   drops and adds columns, losing data.

   async up(queryRunner) {
     await queryRunner.query(`RENAME COLUMN username TO user_name`);
   }
   async down(queryRunner) {
     await queryRunner.query(`RENAME COLUMN user_name TO username`);
   }

   misses the table name in the query, causing error.

3. Final Answer:

   ALTER TABLE accounts RENAME COLUMN username TO user_name -> Option A

4. Quick Check:

   Rename column with ALTER TABLE RENAME COLUMN [OK]

Hint: Use ALTER TABLE RENAME COLUMN for renaming columns [OK]

Common Mistakes:

• Dropping and adding columns instead of renaming
• Omitting table name in ALTER TABLE
• Using database-specific syntax without checking compatibility