Getting Started with Prisma Migrate

Create your first database migration with Prisma Migrate and learn the basic workflow.

This guide walks you through creating your first migration with Prisma Migrate.

Prerequisites

• A Prisma project with a Prisma schema
• A Prisma config file (e.g., prisma.config.ts)
• Database connection configured

Your First Migration

1. Define Your Schema

   Create or update your Prisma schema with your data model:

   model User {
     id    Int     @id @default(autoincrement())
     email String  @unique
     name  String?
     posts Post[]
   }
   
   model Post {
     id        Int     @id @default(autoincrement())
     title     String
     content   String?
     published Boolean @default(false)
     authorId  Int
     author    User    @relation(fields: [authorId], references: [id])
   }
   
2. Create the Migration

   Run prisma migrate dev to create and apply the migration:

   prisma migrate dev --name init
   

   This command will:

   • Create a new migration directory with timestamp: prisma/migrations/20201231000000_init/
   • Generate a migration.sql file with the SQL statements
   • Apply the migration to your database
   • Generate Prisma Client (if not using --create-only)
3. Review the Generated SQL

   Prisma Migrate generates SQL based on your schema changes:

   prisma/migrations/20201231000000_init/migration.sql

   -- CreateTable
   CREATE TABLE "User" (
       "id" SERIAL NOT NULL,
       "email" TEXT NOT NULL,
       "name" TEXT,
   
       CONSTRAINT "User_pkey" PRIMARY KEY ("id")
   );
   
   -- CreateTable
   CREATE TABLE "Post" (
       "id" SERIAL NOT NULL,
       "title" TEXT NOT NULL,
       "content" TEXT,
       "published" BOOLEAN NOT NULL DEFAULT false,
       "authorId" INTEGER NOT NULL,
   
       CONSTRAINT "Post_pkey" PRIMARY KEY ("id")
   );
   
   -- CreateIndex
   CREATE UNIQUE INDEX "User_email_key" ON "User"("email");
   
   -- AddForeignKey
   ALTER TABLE "Post" ADD CONSTRAINT "Post_authorId_fkey" 
     FOREIGN KEY ("authorId") REFERENCES "User"("id") 
     ON DELETE RESTRICT ON UPDATE CASCADE;
   
4. Verify the Migration

   Check that your migration was applied successfully:

   prisma migrate status
   

   You should see:

   1 migration found in prisma/migrations
   
   Database schema is up to date!
   

Command Options

The prisma migrate dev command supports several options:

--name or -n

Name the migration:

prisma migrate dev --name add_users_table

--create-only

Create the migration without applying it:

prisma migrate dev --create-only

This is useful when you need to:

• Review the generated SQL before applying
• Manually edit the migration
• Create an empty migration for custom SQL

After editing, apply with:

prisma migrate dev

--schema

Specify a custom schema path:

prisma migrate dev --schema=./custom/schema.prisma

--config

Specify a custom config path:

prisma migrate dev --config=./custom/prisma.config.ts

Making Additional Changes

1. Update Your Schema

   Add a new field to an existing model:

   model User {
     id        Int      @id @default(autoincrement())
     email     String   @unique
     name      String?
     posts     Post[]
     createdAt DateTime @default(now())  // New field
   }
   
2. Create Another Migration

   prisma migrate dev --name add_created_at
   
3. View Migration History

   Your migrations directory now contains:

   prisma/
     └─ migrations/
       ├─ 20201231000000_init/
       │  └─ migration.sql
       ├─ 20210101120000_add_created_at/
       │  └─ migration.sql
       └─ migration_lock.toml
   

Handling Data Loss Warnings

Some schema changes may result in data loss. Prisma Migrate will warn you:

⚠️  There might be data loss when applying the changes:

  • You are about to drop the column `name` on the `User` table.

Are you sure you want to create and apply this migration?

Options:

• Type y to proceed
• Type n to cancel
• Use --accept-data-loss flag to skip the prompt (CI/CD environments)

Handling Unexecutable Steps

Some changes cannot be executed automatically:

⚠️ We found changes that cannot be executed:

  • Added the required column `authorId` to the `Post` table without a default value.

Solutions:

1. Add a default value in your schema
2. Make the field optional
3. Use --create-only and manually edit the migration

Best Practices

Descriptive Names

Use clear, descriptive migration names that explain the change

Review Generated SQL

Always review the generated SQL before applying in production

Small Migrations

Keep migrations focused on a single logical change

Version Control

Commit migration files to version control

Next Steps

Migration Workflows

Learn development and production workflows

Schema Prototyping

Use db push for rapid iteration