Migrations in NestJS - Deep Dive

Overview - Migrations

What is it?

Migrations are a way to manage changes to a database structure over time. They let you add, remove, or change tables and columns in a controlled, repeatable way. In NestJS, migrations help keep your database schema in sync with your application code. This avoids manual database updates and errors.

Why it matters

Without migrations, developers would have to update databases by hand, which is slow and error-prone. This can cause bugs, lost data, or inconsistent environments between development, testing, and production. Migrations automate and track database changes, making teamwork smoother and deployments safer.

Where it fits

Before learning migrations, you should understand basic NestJS app structure and how to connect to databases using TypeORM or other ORMs. After migrations, you can learn about seeding data, advanced database optimization, and continuous integration with automated database updates.

Mental Model

Core Idea

Migrations are step-by-step instructions that safely change your database structure as your app evolves.

Think of it like...

Think of migrations like a recipe book for your database. Each recipe (migration) tells you exactly how to add or change ingredients (tables and columns) so the dish (database) turns out right every time.

┌───────────────┐
│ Initial State │
└──────┬────────┘
       │ Apply Migration 1 (Add Table)
       ▼
┌───────────────┐
│ Updated State │
└──────┬────────┘
       │ Apply Migration 2 (Modify Column)
       ▼
┌───────────────┐
│ Latest State  │

Build-Up - 7 Steps

1

Foundation

What Are Database Migrations

Concept: Introduce the basic idea of migrations as a way to change database structure over time.

A database stores data in tables. When your app grows, you need to add or change these tables. Migrations are files that describe these changes step-by-step. They let you update your database safely and keep track of what changed.

Result

You understand migrations as a safe, repeatable way to update databases.

Understanding migrations as instructions for database changes helps you see why they are safer than manual edits.

2

Foundation

Setting Up Migrations in NestJS

Concept: Learn how to prepare a NestJS project to use migrations with TypeORM.

Install TypeORM and a database driver (like PostgreSQL). Configure TypeORM in your NestJS app with connection details. Enable migrations by setting migration paths in the config. This setup lets you create and run migration files.

Result

Your NestJS app is ready to create and run migrations.

Knowing how to configure migrations is key to using them effectively in your project.

3

Intermediate

Creating and Running Migration Files

🤔Before reading on: do you think migration files are written manually or generated automatically? Commit to your answer.

Concept: Learn how to create migration files and apply them to the database.

You can generate migration files using TypeORM CLI or write them yourself. Each file has 'up' and 'down' methods: 'up' applies changes, 'down' reverts them. Run migrations with commands to update the database schema.

Result

You can create migration files and update your database schema safely.

Understanding the 'up' and 'down' methods helps you control database changes and rollbacks.

4

Intermediate

Tracking Migration History

🤔Before reading on: do you think migration history is stored in your app code or in the database? Commit to your answer.

Concept: Learn how migration tools keep track of which migrations have run.

TypeORM stores migration history in a special table inside your database. This table records which migrations ran and when. This prevents running the same migration twice and helps coordinate changes across teams.

Result

You understand how migration history prevents conflicts and errors.

Knowing migration history is stored in the database explains how migrations stay consistent across environments.

5

Intermediate

Handling Schema Changes Safely

🤔Before reading on: do you think migrations can cause data loss if not careful? Commit to your answer.

Concept: Learn best practices to avoid data loss or downtime during migrations.

When changing columns or tables, write migrations that preserve data. Avoid dropping columns without backups. Use transactions if supported. Test migrations in development before production. Plan for downtime if needed.

Result

You can write migrations that protect your data and keep your app running smoothly.

Understanding risks in migrations helps you write safer database updates.

6

Advanced

Automating Migrations in Deployment

🤔Before reading on: do you think migrations should run manually or automatically during deployment? Commit to your answer.

Concept: Learn how to integrate migrations into automated deployment pipelines.

Use scripts or CI/CD tools to run migrations automatically when deploying new app versions. This ensures the database is always up to date. Handle errors gracefully and log migration results. Automating reduces human error and speeds up releases.

Result

Your deployments include safe, automatic database updates.

Knowing how to automate migrations improves reliability and developer productivity.

7

Expert

Advanced Migration Strategies and Pitfalls

🤔Before reading on: do you think all migrations should be small and frequent or large and rare? Commit to your answer.

Concept: Explore advanced patterns like splitting large migrations, dealing with legacy data, and avoiding locking issues.

Large migrations can cause downtime or lock tables. Split big changes into smaller steps. Use feature flags to deploy code before schema changes. Handle legacy data carefully with scripts. Monitor migration performance and rollback plans.

Result

You can manage complex migrations in production without downtime or data loss.

Understanding advanced strategies prevents common production migration failures.

Under the Hood

Migrations work by running code that changes the database schema step-by-step. Each migration file has two parts: 'up' to apply changes and 'down' to undo them. The migration system records which migrations ran in a special table inside the database. When you run migrations, the system checks this table to run only new migrations. This ensures the database schema matches your app code exactly.

Why designed this way?

Migrations were designed to solve the problem of evolving databases in a team environment. Before migrations, developers manually edited databases, causing errors and inconsistencies. The design of up/down methods and history tracking allows safe, repeatable, and reversible changes. Alternatives like manual scripts or ORM auto-sync were less reliable and harder to control.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Migration 1  │──────▶│ Migration 2  │──────▶│ Migration 3  │
└──────┬────────┘       └──────┬────────┘       └──────┬────────┘
       │                       │                       │
       ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────┐
│               Database Migration Table                  │
│  Records applied migrations: 1, 2, 3                     │
└─────────────────────────────────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: do you think running a migration twice causes no issues? Commit to yes or no.

Common Belief: Running the same migration multiple times is safe and has no side effects.

Reality: Migration systems track which migrations ran and prevent rerunning the same migration. Running a migration twice manually can cause errors or duplicate changes.

Why it matters: Ignoring migration history can corrupt your database schema or cause crashes.

Quick: do you think migrations automatically update your app code? Commit to yes or no.

Common Belief: Migrations automatically update both the database and the application code.

Reality: Migrations only change the database schema. You must update your app code separately to match the new schema.

Why it matters: Assuming migrations update code can cause runtime errors and bugs.

Quick: do you think you can safely drop columns anytime with migrations? Commit to yes or no.

Common Belief: Dropping columns in migrations is always safe and reversible.

Reality: Dropping columns can cause data loss and may not be reversible if backups are missing.

Why it matters: Careless column drops can cause permanent data loss and service outages.

Quick: do you think large migrations run instantly without affecting users? Commit to yes or no.

Common Belief: Large migrations run quickly and do not impact app performance.

Reality: Large migrations can lock tables and cause downtime or slow queries during execution.

Why it matters: Ignoring migration size can lead to user-facing outages and degraded performance.

Expert Zone

1

Migrations should be idempotent in effect, meaning running them multiple times or out of order should not break the database.

2

Using feature flags with migrations allows deploying code before or after schema changes to avoid downtime.

3

Some databases handle schema changes differently; understanding your database's locking and transaction behavior is crucial for safe migrations.

When NOT to use

Avoid using migrations for frequent small data updates or content changes; use seeders or application logic instead. Also, do not rely on ORM auto-sync features in production as they can cause unpredictable schema changes.

Production Patterns

In production, teams use version-controlled migration files, automated migration runs in CI/CD pipelines, and monitor migration logs. They split large migrations into smaller steps and use blue-green deployments or feature flags to minimize downtime.

Connections

Version Control Systems

Migrations build on the idea of tracking changes over time, similar to how version control tracks code changes.

Understanding version control helps grasp why migrations track database changes step-by-step and why history matters.

Continuous Integration / Continuous Deployment (CI/CD)

Migrations integrate with CI/CD pipelines to automate database updates during app deployment.

Knowing CI/CD concepts helps you automate migrations safely and reliably in production environments.

Legal Document Revision History

Like legal documents track every change and who made it, migrations keep a history of database changes for accountability and rollback.

This connection shows how tracking changes and being able to revert is important in many fields beyond software.

Common Pitfalls

#1 Running migrations manually on production without tracking history.

Wrong approach:

psql -f migration.sql
psql -f migration.sql # ran twice by mistake

Correct approach:

typeorm migration:run # uses migration table to run only new migrations

Root cause:

Not using migration tools that track applied migrations leads to duplicate runs and errors.

#2 Dropping a column without backing up data.

Wrong approach:

await queryRunner.query('ALTER TABLE users DROP COLUMN email');

Correct approach:

// Backup data first
await queryRunner.query('CREATE TABLE backup_emails AS SELECT id, email FROM users');
await queryRunner.query('ALTER TABLE users DROP COLUMN email');

Root cause:

Ignoring data preservation risks causes irreversible data loss.

#3 Writing large migrations that lock tables for minutes.

Wrong approach:

await queryRunner.query('ALTER TABLE big_table ADD COLUMN new_col INT'); // runs on huge table without splitting

Correct approach:

// Split migration into smaller steps or use online schema change tools

Root cause:

Not considering database locking and performance impacts causes downtime.

Key Takeaways

Migrations are essential for safely evolving your database schema alongside your app code.

They work by running step-by-step scripts that apply and can undo changes, tracked in a special database table.

Proper setup, writing, and running of migrations prevent data loss and keep environments consistent.

Advanced use includes automating migrations in deployment and handling large or complex schema changes carefully.

Understanding migration history and risks helps avoid common pitfalls like duplicate runs or downtime.