Prisma Migrate in development and production

This page explains how to use Prisma Migrate commands in development and production environments.

Development environments

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

$npx prisma migrate dev

Create and apply migrations

migrate dev is a development command and should never be used in a production environment.

This command:

  1. Reruns 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:

Reset the development database

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

$npx prisma migrate reset

migrate reset is a development command and should never be used in a production environment.

This command:

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

¹ For MySQL and MongoDB this refers to the database, for PostgreSQL and SQL Server to the schema, and for SQLite to the database file.

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

Customizing migrations

Sometimes, you need to modify a migration before applying it. For example:

  • You want to introduce a significant refactor, such as changing blog post tags from a String[] to a Tag[]
  • You want to rename a field (by default, Prisma Migrate will drop the existing field)
  • You want to change the direction of a 1-1 relationship
  • You want to add features that cannot be represented in Prisma Schema Language - such as a partial index or a stored procedure.

The --create-only command allows you to create a migration without applying it:

$npx prisma migrate dev --create-only

To apply the edited migration, run prisma migrate dev again.

Refer to Customizing migrations for examples.

Team development

See: Team development with Prisma Migrate .

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.

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
  2. 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:

Advisory locking

Prisma Migrate makes use of advisory locking when you run production commands such as:

  • prisma migrate deploy
  • prisma migrate resolve

This safeguard ensures that multiple commands cannot run at the same time - for example, if you merge two pull requests in quick succession.

Advisory locking has a 10 second timeout (not configurable), and uses the default advisory locking mechanism available in the underlying provider:

Prisma Migrate's implementation of advisory locking is purely to avoid catastrophic errors - if your command times out, you will need to run it again.

Edit this page on GitHub