Skip to main content

About migration histories

This page explains how Prisma ORM uses migration histories to track changes to your schema.

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

    The migrations 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 was run against the database
    • If an applied migration was deleted
    • If an applied migration was 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).

Do not edit or delete migrations that have been applied​

In general, you should not edit or delete a migration that has already been applied. Doing so can lead to inconsistencies between development and production environment migration histories, which may have unforeseen consequences — even if the change does not appear to break anything at first.

The following scenario simulates a change that creates a seemingly harmless inconsistency:

  1. Modify an existing migration that has already been applied in a development environment by changing the value of VARCHAR(550) to VARCHAR(560):
    ./prisma/migrations/20210310143435_default_value/migrations.sql
      -- AlterTable
     ALTER TABLE "Post" ALTER COLUMN "content" SET DATA TYPE VARCHAR(560);
    After making this change, the end state of the migration history no longer matches the Prisma schema, which still has @db.VarChar(550).
  2. Run prisma migrate dev - Prisma Migrate detects that a migration has changed, and asks to reset the database: 
    ? The migration `20210310143435_change_type` was modified after it was applied.

     We need to reset the PostgreSQL database "migrate-example" at "localhost:5432".
     Do you want to continue? All data will be lost. » (y/N)
  3. If you accept resetting, Prisma Migrate resets the database and replays all migrations, including the migration you edited.
  4. After applying all existing migrations, Prisma Migrate compares the end state of the migration history to the Prisma schema and detects a discrepancy:
    • Prisma schema has @db.VarChar(550)
    • Database schema has VARCHAR(560)
  5. Prisma Migrate generates a new migration to change the value back to 550, because the end state of the migration history should match the Prisma schema.
  6. From now on, when you use prisma migrate deploy to deploy migrations to production and test environments, Prisma Migrate will always warn you that migration histories do not match (and continue to warn you each time you run the command ) - even though the schema end states match: 
    6 migrations found in prisma/migrations
    WARNING The following migrations have been modified since they were applied:
    20210310143435_change_type

A change that does not appear to break anything after a migrate reset can hide problems - you may end up with a bug in production that you cannot replicate in development, or the other way around - particularly if the change concerns a highly customized migration.

If Prisma Migrate reports a missing or edited migration that has already been applied, we recommend fixing the root cause (restoring the file or reverting the change) rather than resetting.

info

There may be situations where a manual change to your migration history doesn't actually alter the database schema, like adding a comment to a generated SQL migration. In these situation, you can avoid resetting the database by following the instructions in this tutorial.

Committing the migration history to source control​

You must commit the entire prisma/migrations folder to source control. This includes the prisma/migrations/migration_lock.toml file, which is used to detect if you have attempted to change providers.

Source-controlling the schema.prisma file is not enough - you must include your migration history. This is because:

  • As you start to customize migrations, your migration history contains information that cannot be represented in the Prisma schema. For example, you can customize a migration to mitigate data loss that would be caused by a breaking change.
  • The prisma migrate deploy command, which is used to deploy changes to staging, testing, and production environments, only runs migration files. It does not use the Prisma schema to fetch the models.