Prisma Migrate Dev vs Deploy vs DB Push

Use prisma migrate dev to create and test versioned migrations in development, prisma migrate deploy to apply committed pending migrations in staging or production, and prisma db push to synchronize a schema when you intentionally do not need migration files—usually during prototyping.

The commands are not interchangeable. They answer different questions: should Prisma create history, apply existing history, or move directly to a desired schema state?

Comparison

This repository does not contain Prisma packages or a Prisma schema, so there is no locally pinned Prisma CLI version. The Prisma 7 behavior documented below must be checked against the version in the application where the commands will run.

prisma migrate dev: create migration history in development

After editing prisma/schema.prisma, a typical development command is:

npx prisma migrate dev --name add_order_status

Before running it, confirm the configured datasource is a disposable development database—not staging or production.

The command replays existing migration history in a shadow database, checks the development schema for drift, generates a SQL migration when the Prisma schema changed, applies unapplied migrations to the development database, and updates _prisma_migrations. It also triggers generators such as Prisma Client.

Because it can prompt for a development reset when history conflicts or drift are detected, Prisma explicitly says not to use migrate dev in production. A reset drops the PostgreSQL schema and loses its data. A prompt that is acceptable for an isolated developer database is not a production recovery plan.

Why the shadow database exists

The shadow database is a temporary second database used to replay migration history and calculate its expected end state. Prisma compares that state with the development database to identify out-of-band changes, then evaluates the proposed migration.

The database user may need permission to create databases. For a cloud development database that does not grant that permission, configure a separate shadow database according to the Prisma documentation. Never use the production database as the shadow database.

prisma migrate deploy: apply committed migrations

A deployment pipeline normally runs:

npx prisma migrate deploy

This applies pending migration files and records them in _prisma_migrations. It does not create migrations, detect production schema drift, reset the database, use a shadow database, or generate Prisma Client.

That narrow behavior is intentional. The SQL should already have been generated, reviewed, tested against representative data, and committed before deployment.

CI/CD example

The exact syntax depends on the platform, but the sequence is usually:

steps:
  - run: npm ci
  - run: npm run lint
  - run: npm run typecheck
  - run: npm test
  - run: npx prisma migrate deploy
    env:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
  - run: npm run build

This is illustrative YAML, not a complete workflow for a particular CI vendor. Store DATABASE_URL in the CI secret store, restrict who can trigger production deployments, and avoid printing it. Ensure the Prisma CLI dependency is available in the deployment job even if production dependency pruning would otherwise remove it.

For pooled environments, follow the installed Prisma version and provider guidance about using a direct migration URL. See PostgreSQL Connection Pooling: Direct Connection vs Pooler.

prisma db push: synchronize without history

For a prototype where migration history is intentionally unnecessary:

npx prisma db push
npx prisma generate

db push introspects the target and applies changes needed to match the Prisma schema, but it does not create migration files or update _prisma_migrations. In Prisma 7 it no longer runs prisma generate automatically, so the second command updates generated client code.

If Prisma anticipates data loss, db push stops. Its --accept-data-loss and --force-reset options can destroy data, so they are deliberately not part of the recommended workflow here. Do not turn a warning into an automated production deployment step.

db push is appropriate when:

• exploring an early schema locally;
• using a disposable database;
• the final state matters but versioned, customizable SQL does not yet;
• the database connector's documented workflow uses it instead of Prisma Migrate.

It is not a replacement for versioned production migrations. It provides no committed SQL history to review, reproduce across environments, or customize for a safe column rename or data backfill.

A development-to-production workflow

1. Edit the Prisma schema on a feature branch.
2. Run npx prisma migrate dev --name descriptive_name against the development database.
3. Read the generated migration.sql; check locks, table rewrites, constraints, defaults, indexes, and data transitions.
4. Test the migration on a restored, sanitized copy with representative volume when the change is material.
5. Commit the Prisma schema and the complete migration directory together.
6. Run code review and automated checks.
7. Back up according to the database's recovery policy and verify that recovery is usable.
8. Run npx prisma migrate deploy through the controlled staging/production pipeline.
9. Verify migration status and application health without exposing connection strings.

If production has drifted from migration history, pause deployment and diagnose it. A separate schema-drift recovery procedure should remain unpublished until its repair steps have received owner and DBA review.

How prisma generate relates to migrations

prisma generate creates artifacts such as Prisma Client from the Prisma schema. It does not alter the database and does not apply migration files.

Current Prisma behavior differs by command:

• migrate dev triggers generators.
• migrate deploy does not generate artifacts.
• db push does not trigger generators in Prisma 7.

Build or deployment pipelines should run generation explicitly when they cannot guarantee that a preceding command generated the client. Keeping generation explicit also makes upgrades easier to review.

Decision guide

• Need to turn a reviewed development schema change into versioned SQL? Use migrate dev in development.
• Need to apply committed pending SQL non-interactively? Use migrate deploy in the deployment pipeline.
• Need rapid disposable prototyping without history? Use db push.
• Need to repair drift or migration history? Stop. Diagnose first; none of these three is an automatic production repair command.
• Need to add Prisma Migrate to a populated database? Use a reviewed baseline workflow, covered in Prisma Migration Baseline for an Existing Database.

Common mistakes

• Running migrate dev with a production URL because it creates migrations locally.
• Expecting migrate deploy to detect manual production changes.
• Running db push in production and assuming it created auditable history.
• Editing an already applied migration instead of adding a new migration.
• Omitting the migration directory from the deployment artifact.
• Assuming every command regenerates Prisma Client.
• Treating a reset prompt as permission to erase a shared database.

Verification checklist

• The Prisma CLI version is pinned and its version-specific documentation was reviewed.
• Development, shadow, staging, and production URLs cannot be confused.
• Generated SQL was reviewed and committed with the schema change.
• Material changes were rehearsed against a restored copy.
• The CI job has the Prisma CLI and the migration directory.
• migrate deploy runs once through a controlled deployment path.
• Client generation happens explicitly where the build needs it.
• Logs and command output do not reveal a connection string.

References

Documentation checked on 2026-08-08:

• Prisma: development and production migration workflows
• Prisma: migrate command reference
• Prisma: db push command reference
• Prisma: prototyping a schema with db push
• Prisma: shadow database behavior
• Prisma: deploy database changes with Prisma Migrate