Prisma Migrate

Getting started with Prisma Migrate

See Developing with Prisma Migrate for a more in-depth development workflow.

To get started with Prisma Migrate in a development environment:

1. Create a Prisma schema:

   schema.prisma
   1datasource db {
   2  provider = "postgresql"
   3  url      = env("DATABASE_URL")
   4}
   5
   6model User {
   7  id    Int      @id @default(autoincrement())
   8  name  String
   9  posts Post[]
   10}
   11
   12model Post {
   13  id        Int     @id @default(autoincrement())
   14  title     String
   15  published Boolean @default(true)
   16  authorId  Int
   17  author    User    @relation(fields: [authorId], references: [id])
   18}

   Tip: You can use native type mapping attributes in your schema to decide which exact database type to create (for example, String can map to varchar(100) or text).

2. Create the first migration:

   $prisma migrate dev --name init

   Show migration SQL

   Your Prisma schema is now in sync with your database schema and you have initialized a migration history:

   migrations/
     └─ 20210313140442_init/
       └─ migration.sql

3. Evolve your schema by introducing additional fields:

   model User {
     id       Int      @id @default(autoincrement())
     jobTitle String
     name     String
     posts    Post[]
   }

4. Create the second migration:

   $prisma migrate dev --name added_job_title

   Show migration SQL

   Your Prisma schema is once again in sync with your database schema, and your migration history contains two migrations:

   migrations/
     └─ 20210313140442_init/
       └─ migration.sql
     └─ 20210313140442_added_job_title/
       └─ migration.sql

You now have a migration history that you can source control and use to deploy changes to test environments and production.

Migration history

Your migration history is the story of the changes to your data model, and is represented by:

• A prisma/migrations folder with a sub-folder and migration.sql file for each migration:

  migrations/
    └─ 20210313140442_init/
      └─ migration.sql
    └─ 20210313140442_added_job_title/
      └─ migration.sql

  This folder is the source of truth for the history of your data model.

• A _prisma_migrations table in the database, which is used to check:

  • If a migration has been run against the database
  • If an applied migration has been deleted
  • If an applied migration has been changed

  If you change or delete a migration (not recommended), the next steps depend on whether you are in a development environment (and therefore using migrate dev) or a production / testing environment (and therefore using migrate deploy).

6 migrations found in prisma/migrations
WARNING The following migrations have been modified since they were applied:
20210310143435_change_type

Development environments

In a development environment, use the migrate dev command to generate and apply migrations:

$npx prisma migrate dev

This command:

1. Replays the existing migration history in the shadow database in order to detect schema drift (edited or deleted migration file, or a manual changes to the database schema)
2. Applies pending migrations to the shadow database (for example, new migrations created by colleagues)
3. Generates a new migration from any changes you made to the Prisma schema before running migrate dev
4. Applies all unapplied migrations to the development database and updates the _prisma_migrations table
5. Triggers the generation of artifacts (for example, the Prisma Client)

The migrate dev command will prompt you to reset the database in the following scenarios:

• Migration history conflicts caused by modified or missing migrations
• The database schema has drifted away from the end-state of the migration history

You can also reset the database yourself to undo manual changes or db push experiments by running:

$npx prisma migrate reset

This command:

1. Drops the database if possible, or performs a soft reset if the environment does not allow deleting databases
2. Creates a new database with the same name if the database was dropped
3. Applies all migrations
4. Runs seed scripts

Note: For a simple and integrated way to re-create data in your development database as often as needed, check out our seeding guide.

$npx prisma migrate dev --create-only

Production and testing environments

In production and testing environments, use the migrate deploy command to apply migrations:

$npx prisma migrate deploy

Note: migrate deploy should generally be part of an automated CI/CD pipeline, and we do not recommend running this command locally to deploy changes to a production database (for example, by temporarily changing the DATABASE_URL environment variable). It is not generally considered good practice to store the production database URL locally.

This command:

1. Compares applied migrations against the migration history and warns if any migrations have been modified:

WARNING The following migrations have been modified since they were applied:
20210313140442_favorite_colors

1. Applies pending migrations

The migrate deploy command:

• Does not issue a warning if an already applied migration is missing from migration history
• Does not detect drift (production database schema differs from migration history end state - for example, due to a hotfix
• Does not reset the database or generate artifacts (such as Prisma Client)
• Does not rely on a shadow database

See also:

• Prisma Migrate in deployment
• Production troubleshooting

Commands

See Prisma Migrate CLI reference for all available Prisma Migrate commands.