Adding Prisma Migrate to an existing project

This guide describes how to add Prisma Migrate to an existing project, including upgrading from the Experimental version of Prisma Migrate.

  • For users who are transitioning from the Experimental Prisma Migrate, the flow is conceptually very similar.
  • For users coming from a third party migration tool, the flow differs from the old "introspection flow". With Prisma Migrate, you no longer modify your database schema and then use prisma introspect to pull the changes into your Prisma schema.

Update the development environment

During the initial transition to Prisma Migrate, you must reset your database - this will result in data loss in the development database. For production and other environments, the database should be baselined to avoid data loss.

To transition your development database:

  1. Make sure your Prisma schema is in sync with your database schema. This should already be true if you are using a previous version of Prisma Migrate. To make sure, introspect your database to align your database schema and Prisma schema:

    prisma introspect
  2. If you have a prisma/migrations folder, delete, move, rename, or otherwise archive this folder.

  3. Initialize a new migration history by running the following command:

    $prisma migrate dev

    Prisma Migrate will:

    1. Create a new migration directory with a SQL migration file in it
    2. Detect that the database is out of sync with the migration history and will prompt you to reset it. You should confirm to reset to the database (development environment only!)

    The new migration history and the new database schema should now be in sync with your Prisma schema.

  4. Review the schema to ensure the migration leads to the desired end-state (for example, by comparing the schema to the production database)

  5. Commit the entire migrations directory to your repository.

Reset other development environments

In other development environments (for example, other team members' computers):

  1. Check out a copy of the repository with the new migration directory and the initial migration

  2. Run the following command to reset the development database:

    $prisma migrate dev

Baseline your production environment

Baselining is for introducing Prisma Migrate to existing databases / brownfield projects. Concretely it's to tell Prisma Migrate to assume that one or more migration(s) were already executed so the generated migration(s) won't fail when they will try to create tables that already exist.

Assuming you started a new migration history in your repository using prisma migrate dev, you now need to baseline any database that contains important data – such as production or staging. Trying to apply this new migration history with prisma migrate deploy will normally fail as the migrations are trying to re-create a state that is already there. Instead, the database should be baselined.

In development, we assume it is acceptable to reset and seed your database to make sure your migration files are in sync with your database schema. This is not acceptable in a production environment, or any other environment where data must be maintained.

You will need to use prisma migrate resolve --applied "MIGRATION_NAME" (see example below) to register migration(s) in the _prisma_migrations table as "already applied", this table will be created if it does not exist. This will cause Prisma Migrate to ignore the "applied" migrations in your deployments. When running prisma migrate deploy:

  • Any "applied" migrations, whether actually applied or baselined (marked as applied) will be skipped.
  • Any new migrations that come after baselined migrations will be applied.

To baseline a production database:

  1. Make sure you have a working copy of the new migrations directory

  2. Run the following command to baseline a migration:

    $prisma migrate resolve --applied "20201124-create-users"

    If you need to baseline multiple migrations (for example, if you generated more migrations after transitioning your development environment), run the prisma migrate resolve command for each migration separately.

Resolve migration issues in production databases

In certain cases, you can run into issues with the migration history and that prevent you from applying further database migrations with prisma migrate resolve. This can happen if:

  • A migration failed, either because of an error or because it was interrupted while running (for example, unexepected shutdown)
  • The database needs to be baselined to skip certain migrations that are unnecessary on this database schema - this can be the case when a change to the database schema was done manually, such as a hotfix, or when the database needs to be baselined
Edit this page on GitHub