Database migrations in NextJS - Step-by-Step Execution

Concept Flow - Database migrations

Write migration file

↓

Run migration command

↓

Migration tool reads file

↓

Apply schema changes to DB

↓

Update migration history

↓

App uses updated DB schema

This flow shows how writing and running a migration file updates the database schema step-by-step.

Execution Sample

NextJS

import { migrate } from '@nextjs/db-migrate';

await migrate('2024_06_add_users_table');

This code runs a migration named '2024_06_add_users_table' to update the database schema.

Execution Table

Step	Action	Input	Result	DB State Change
1	Write migration file	'2024_06_add_users_table' with SQL to create users table	Migration file created	No change yet
2	Run migration command	migrate('2024_06_add_users_table')	Migration tool starts	No change yet
3	Read migration file	Read SQL commands	SQL commands loaded	No change yet
4	Apply schema changes	Execute SQL: CREATE TABLE users (...)	Users table created	Users table added
5	Update migration history	Record migration applied	Migration recorded	Migration history updated
6	Finish migration	Return success	Migration complete	DB schema updated
7	Exit	No more migrations	Process ends	Final DB schema with users table

💡 All migration steps completed successfully; database schema is now updated.

Variable Tracker

Variable	Start	After Step 4	After Step 5	Final
migrationFile	undefined	'2024_06_add_users_table' content	'2024_06_add_users_table' content	'2024_06_add_users_table' content
dbSchema	Initial schema	Users table added	Users table added	Users table added
migrationHistory	Empty	Empty	Contains '2024_06_add_users_table'	Contains '2024_06_add_users_table'

Key Moments - 2 Insights

Why doesn't the database schema change when I just write the migration file?

Writing the migration file only prepares the instructions. The schema changes only happen when you run the migration command, as shown in steps 2 to 4 in the execution table.

What happens if I run the migration command twice?

The migration history (step 5) prevents reapplying the same migration. The tool checks history and skips already applied migrations to avoid errors.

Visual Quiz - 3 Questions

Look at the execution table, at which step is the users table actually created in the database?

A Step 3

B Step 5

C Step 4

D Step 6

💡 Hint

Check the 'DB State Change' column for when the users table is added.

According to the variable tracker, what is the state of migrationHistory after step 5?

A Empty

B Contains '2024_06_add_users_table'

C Undefined

D Reset to initial

💡 Hint

Look at the migrationHistory row under 'After Step 5' in variable_tracker.

If the migration file is missing, what step would fail in the execution table?

A Step 3

B Step 2

C Step 4

D Step 5

💡 Hint

Step 3 reads the migration file; if missing, it cannot load SQL commands.

Concept Snapshot

Database migrations:
- Write migration files with schema changes
- Run migration command to apply changes
- Migration tool reads files and updates DB
- Migration history tracks applied changes
- Prevents duplicate or missing updates

Full Transcript

Database migrations in Next.js involve writing migration files that describe changes to the database schema. When you run the migration command, the tool reads these files and applies the changes to the database. It also records which migrations have been applied to avoid repeating them. This process updates the database schema safely and in order.