Migration flows

Development environments

In a development environment, history conflicts can occur in the following scenarios:

• A migration that has already been applied is later modified - this check requires a shadow database and is therefore only available in a development environment
• A migration that has already been applied is missing from the file system
• A migration failed

If Prisma Migrate detects a migration history conflict when you run prisma migrate dev --preview-feature (Development command), the CLI will ask to reset the database. Resetting the database:

1. Drops the database
2. Recreates the database
3. Applies all migrations

Production environments

In a production environment, history conflicts can occur in the following scenarios:

• A migration that has already been applied is missing from the file system
• A migration failed

If Prisma Migrate detects a migration history conflict when you run prisma migrate deploy --preview-feature (Production command)

• Add the missing migration file - for example, from source control

• Address the cause of the failed migration - each migration in the _prisma_migrations table has a logs column that stores the error. For example:

  Database error: Error accessing result set, column not found: name
   0: migration_core::api::ApplyMigrations
             at migration-engine\core\src\api.rs:102

Development environments

1. Make an equivalent change in the Prisma schema - for example, adding a field named bio and an index:

   model User {
       // Other fields
       bio   String?
       @@index([bio])
   }

2. Create and apply the new migration in dev:

   $prisma migrate dev --preview-feature

3. Commit the new migration and allow your CI process to apply the migration to all other non-production databases.

Production environments

When the manual change has been replicated in the Prisma schema, you must reconcile your migration history and database schema in production:

1. Mark the migration as 'already applied' so that Prisma Migrate does not try to create a field and index that already exists:

   $prisma migrate resolve --applied "20201127134938_added_bio_index" --preview-feature

   This command adds the migration to the migration history table without running the actual SQL.

Developer environments

The easiest way to handle a failed migration in a developer environment is to address the root cause and reset the database. For example:

• If you introduced a SQL syntax error by manually editing the database, update the migration.sql file that failed and reset the database:

  $prisma migrate reset --preview-feature

• If you introduced a change in the Prisma schema that cannot be applied to a database with data (for example, a mandatory column in a table with data):

  1. Delete the migration.sql file.

  2. Modify the schema - for example, add a default value to the mandatory field.

  3. Migrate:

     $prisma migrate dev --preview-feature

     Prisma Migrate will prompt you to reset the database and re-apply all migrations.

• If something interrupted the migration process, reset the database:

  $prisma migrate reset --preview-feature

Production environments

There are two ways to deal with failed migrations in a production environment:

• Roll back, optionally fix issues, and re-deploy
• Manually complete the migration steps and resolve the migration

Option 2: Manually complete migration and resolve as applied

The following example demonstrates how to manually complete the steps of a migration and mark that migration as applied.

1. Manually complete the migration steps on the production database. Make sure that any manual steps exactly match the steps in the migration file, and copy any changes back to source control.

2. Resolve the migration as applied - this tells Prisma Migrate to consider the migration successfully applied:

   $prisma migrate resolve --applied "20201127134938_my_migration" --preview-feature