Creating and Running Migrations
1. Creating Development Migration
npx prisma migrate dev --name add_user_email_index| Step | Detail |
|---|---|
| Diff | Compare schema vs shadow DB |
| Generate SQL | Stored in prisma/migrations/<ts>_name/ |
| Apply | Run on dev DB |
| Regenerate | Prisma client refreshed |
2. Applying Production Migrations
npx prisma migrate deploy| Aspect | Detail |
|---|---|
| No prompts | Apply pending migrations only |
| CI/CD | Run in deploy pipeline before app boot |
| DIRECT_URL | Use direct DB URL (skip pooler) |
3. Resetting Database
npx prisma migrate reset # drop, recreate, re-apply, seed| Use | Detail |
|---|---|
| Dev only | Wipes all data |
| Runs seed | Triggers prisma db seed |
4. Checking Migration Status
| Command | Output |
|---|---|
migrate status | Pending / applied migrations |
migrate diff | Schema diff (without applying) |
5. Creating Baseline Migration
npx prisma migrate resolve --applied 0_init| Use | Detail |
|---|---|
| Existing DB | Mark current state as baseline |
| Adopting Prisma | Avoid re-running schema |
6. Resolving Migration Conflicts
| Scenario | Resolution |
|---|---|
| Drift | Inspect with migrate diff |
| Failed migration | prisma migrate resolve --rolled-back <name> |
| Manual fix | Edit SQL, mark applied |
7. Using Shadow Database
| Aspect | Detail |
|---|---|
| Purpose | Diff state for safe migration generation |
| Default | Auto-created (PG/MySQL) |
| Cloud | Set shadowDatabaseUrl for managed DBs |
8. Customizing Migration SQL Files
| Use | Detail |
|---|---|
| Data backfill | Add SQL between schema changes |
--create-only | Generate SQL without applying |
| Run review | Edit, then migrate dev applies it |
9. Handling Schema Drift
Warning: If the database has unexpected changes not tracked in
_prisma_migrations, Prisma will block migrations. Use migrate diff to inspect and either pull (db pull) or reset.| Action | When |
|---|---|
db pull | Adopt out-of-band changes |
migrate reset | Wipe + reapply |
10. Rolling Back Migrations
| Strategy | Detail |
|---|---|
| No auto-rollback | Prisma forward-only |
| Manual | Create reverse migration |
| Mark rolled back | migrate resolve --rolled-back |