This guide describes how to add Prisma Migrate to an existing project.
As part of adding Prisma Migrate to your development environment, you must reset your development database. This will result in data loss in the development database only.
Production databases and any other database that cannot be reset should be baselined to avoid data loss.
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.
Introspect the database to make sure that your Prisma schema is up-to-date:$prisma introspect
To initialize a new migration history:
If you have a
prisma/migrationsfolder, delete, move, rename, or archive this folder.
Run the following command to create the first migration without applying it, in case you need to modify the initial migration:$prisma migrate dev --name initial-migration --create-only
Prisma Migrate will create a new migration directory with a SQL migration file in it:./prisma/migrations/20210426141759_initial-migration
Some database features cannot be represented in the Prisma schema, including but not limited to:
- Stored procedures
- Partial indexes
To include unsupported features, you must replace or modify the initial migration SQL:
migration.sqlfile generated in the Initialize migration history section.
Modify the generated SQL. For example:
/* Generated migration SQL */CREATE UNIQUE INDEX tests_success_constraint ON posts (subject, target)WHERE success;
- If the changes are minor, you can append additional custom SQL to the generated migration - the following example creates a partial index:
To apply your initial migration(s):
Run the following command against your development database:$npx prisma migrate dev
Prisma Migrate detects that the database is out of sync with the migration history and will prompt you to reset it. Confirm the reset (in development environments only!)
Review the database schema to ensure the migration leads to the desired end-state (for example, by comparing the schema to the production database).
The new migration history and the new database schema should now be in sync with your Prisma schema.
Commit the following to source control:
- The entire migration history folder
To reset other development environments (for example, other team members' computers):
Check out a copy of the repository with the new migration directory and the
Run the following command to reset the development database:$npx prisma migrate dev
Baselining initializes a migration history for databases that contain data and cannot be reset - such as the production database. Baselining tells Prisma Migrate to assume that one or more migrations have already been applied.
To baseline a database:
Switch to an environment that has access to the database you want to baseline.
Make sure you have a working copy of the new migrations directory.
Run the following command to baseline a migration - this example marks the migration genreated by the Initialize migration history step as already applied:$prisma migrate resolve --applied 20210426141759_initial-migration
If you need to baseline multiple migrations (for example, if you generated more migrations after transitioning your development environment), run the
prisma migrate resolvecommand for each migration separately.
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, unexpected 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.