Skip to content

Database migration runbook

When to use this runbook

You are deploying a service change that includes a Prisma schema migration, or a migration has failed and you need to diagnose and recover.

Before deploying

  1. Review the migration SQL. Prisma generates SQL in prisma/migrations/<timestamp>/migration.sql. Read it carefully — look for column drops, type changes, or index removals that cannot be reversed without data loss.

  2. Check for backwards compatibility. The new application code and the old code should both be able to run against the migrated schema during the deployment window. If they cannot, plan for a maintenance window.

  3. Back up or snapshot the database. For production, take a MySQL snapshot before running a destructive migration.

Running a migration

All services use prisma migrate deploy (not prisma migrate dev) in production. This is typically run as a pre-start step in the service container or as a separate migration job. The Prisma client is generated separately; do not run prisma generate against a production database.

If a migration fails

  1. Check the Prisma migration history table (_prisma_migrations) for the failed row. It will have a non-null rolled_back_at or a non-null applied_steps_count less than the total.

  2. Examine the error. Common causes: duplicate key conflicts, missing foreign key targets, or column type coercions that MySQL rejects.

  3. Resolve the data issue if the migration is correct and the data state is the problem (e.g. clean up rows that violate the new constraint).

  4. Mark the migration as rolled back using prisma migrate resolve --rolled-back <migration_name> if you need to re-apply after fixing the SQL.

  5. Roll back the application code to a version compatible with the pre-migration schema. See deployment-rollback.md.

After a migration

  • Confirm GET /health/ready returns 200 on each instance of the service.
  • Check application logs for Prisma query errors that may indicate a schema/code mismatch.
  • Monitor error rates for at least 15 minutes after a schema change.

If this doesn't work

  • Escalate to the on-call engineer and the infrastructure team if the database cluster is involved.
  • Do not attempt to manually edit the _prisma_migrations table in production without explicit DBA sign-off.

Owners

See ../README.md for the service-to-owner map.