Database migrations in NextJS - Mini Project: Build & Apply

Database Migrations with Next.js

📖 Scenario: You are building a Next.js app that needs to store user profiles in a database. To keep your database organized and up to date, you will create a simple migration system to add a users table.

🎯 Goal: Build a basic database migration script in Next.js that creates a users table with id, name, and email columns.

📋 What You'll Learn

Create a migration file with SQL commands to create the users table

Add a configuration variable for the database connection string

Write a function to run the migration using the connection string

Export the migration function for use in the Next.js app

💡 Why This Matters

🌍 Real World

Database migrations help keep your app's database structure consistent and up to date as your app evolves.

💼 Career

Understanding migrations is essential for backend and full-stack developers working with databases and modern web frameworks like Next.js.

1

Create the migration SQL string

Create a constant called migrationSQL that contains the SQL command to create a users table with columns id (integer primary key), name (text), and email (text). Use a template string for the SQL.

NextJS

# Your code here

Hint

Use backticks ` to create a multi-line string for the SQL command.

2

Add the database connection string

Create a constant called connectionString and set it to the string 'postgresql://user:password@localhost:5432/mydb' to represent the database connection URL.

NextJS

const migrationSQL = `
CREATE TABLE users (
  id INTEGER PRIMARY KEY,
  name TEXT,
  email TEXT
);
`;

# Your code here

Hint

Use single quotes for the connection string.

3

Write the migration function

Write an async function called runMigration that connects to the database using connectionString, runs the migrationSQL command, and then closes the connection. Use the pg library's Client class. Import { Client } from 'pg' at the top.

NextJS

import { Client } from 'pg';

const migrationSQL = `
CREATE TABLE users (
  id INTEGER PRIMARY KEY,
  name TEXT,
  email TEXT
);
`;

const connectionString = 'postgresql://user:password@localhost:5432/mydb';

// Your code here

Hint

Remember to use await for asynchronous calls and to close the client connection.

4

Export the migration function

Add an export statement to export the runMigration function as a named export from the module.

NextJS

import { Client } from 'pg';

const migrationSQL = `
CREATE TABLE users (
  id INTEGER PRIMARY KEY,
  name TEXT,
  email TEXT
);
`;

const connectionString = 'postgresql://user:password@localhost:5432/mydb';

async function runMigration() {
  const client = new Client({ connectionString });
  await client.connect();
  await client.query(migrationSQL);
  await client.end();
}

// Your code here

Hint

Use a named export to make the function available to other files.

Practice

1.

What is the main purpose of database migrations in a Next.js project?

easy

A. To deploy the Next.js app to the server

B. To safely update the database structure as the app evolves

C. To create user interfaces automatically

D. To write CSS styles for the app

Solution

1. Step 1: Understand database migrations

   Database migrations are used to change the database schema safely without losing data.

2. Step 2: Relate to Next.js usage

   In Next.js, migrations help keep the database structure in sync with app changes.

3. Final Answer:

   To safely update the database structure as the app evolves -> Option B

4. Quick Check:

   Database migrations = safe schema updates [OK]

Hint: Migrations change database structure safely [OK]

Common Mistakes:

• Confusing migrations with UI or styling tasks
• Thinking migrations deploy the app
• Assuming migrations create app features

2.

Which command is used to create and apply a new migration in a Next.js project using Prisma?

?

easy

A. next dev

B. npm run build

C. npx prisma migrate dev

D. npx prisma generate

Solution

1. Step 1: Identify Prisma migration command

   The command npx prisma migrate dev creates and applies migrations during development.

2. Step 2: Differentiate from other commands

   npm run build builds the app, next dev runs dev server, and npx prisma generate regenerates Prisma client but does not migrate.

3. Final Answer:

   npx prisma migrate dev -> Option C

4. Quick Check:

   Migration command = npx prisma migrate dev [OK]

Hint: Use 'npx prisma migrate dev' to create and apply migrations [OK]

Common Mistakes:

• Using 'npm run build' to migrate database
• Confusing 'npx prisma generate' with migration
• Running 'next dev' expecting migration

3.

Given this Prisma schema change and migration command, what will happen?

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
  name  String?
}

// After adding a new field:
model User {
  id       Int    @id @default(autoincrement())
  email    String @unique
  name     String?
  isActive Boolean @default(true)
}

Command: npx prisma migrate dev --name add-isActive

medium

A. A new migration file is created and applied adding the isActive column with default true

B. The migration fails because isActive is missing in existing rows

C. The database schema remains unchanged

D. The app crashes due to schema mismatch

Solution

1. Step 1: Understand schema change

   A new Boolean field isActive with default true is added to the User model.

2. Step 2: Effect of migration command

   The command creates a migration file that adds the new column with default value, so existing rows get true automatically.

3. Final Answer:

   A new migration file is created and applied adding the isActive column with default true -> Option A

4. Quick Check:

   Adding field with default = migration applies safely [OK]

Hint: Adding field with default creates migration safely [OK]

Common Mistakes:

• Thinking migration fails due to missing data for new field
• Assuming schema does not change without manual SQL
• Believing app crashes immediately after migration

4.

What is wrong with this migration command usage in a Next.js project?

npx prisma migrate dev --name

medium

A. The command is correct and will run successfully

B. The command should be run with npm, not npx

C. The command should be prisma migrate deploy instead

D. The migration name is missing after --name flag

Solution

1. Step 1: Check command syntax

   The --name flag requires a migration name string after it.

2. Step 2: Identify missing argument

   Here, no name is provided, so the command will error out.

3. Final Answer:

   The migration name is missing after --name flag -> Option D

4. Quick Check:

   Migration name required after --name [OK]

Hint: Always provide a name after --name flag [OK]

Common Mistakes:

• Omitting migration name after --name
• Confusing migrate dev with migrate deploy
• Using npm instead of npx unnecessarily

5.

You want to add a new required field age Int to your User model in Prisma, but your database already has users without this field. What is the best way to handle this migration?

hard

A. Add age Int? as optional first, migrate, then backfill data, then make it required

B. Add age Int directly and run migration; it will succeed automatically

C. Delete all existing users before migration to avoid errors

D. Skip migration and add the field only in the app code

Solution

1. Step 1: Understand required field constraints

   Adding a required field age Int directly will fail because existing rows lack this data.

2. Step 2: Use a safe migration approach

   First add the field as optional (age Int?), migrate, then update existing data, and finally change it to required.

3. Final Answer:

   Add age Int? as optional first, migrate, then backfill data, then make it required -> Option A

4. Quick Check:

   Make new required fields optional first [OK]

Hint: Add new required fields as optional first [OK]

Common Mistakes:

• Adding required field directly causing migration failure
• Deleting data unnecessarily
• Skipping migration and causing runtime errors