managing-dev-migrations

Decision Tree

Use prisma migrate dev when: Building production-ready features; working on teams with shared schema changes; needing migration history for rollbacks; version controlling schema changes; deploying to staging/production.

Use prisma db push when: Rapid prototyping and experimentation; early-stage development with frequent schema changes; personal projects without deployment concerns; testing schema ideas quickly; no migration history needed.

migrate dev Workflow

npx prisma migrate dev --name add_user_profile

Detects schema changes in schema.prisma, generates SQL migration, applies to database, regenerates Prisma Client.

Review generated SQL before applying with --create-only:

npx prisma migrate dev --create-only --name add_indexes

Edit if needed, then apply:

npx prisma migrate dev

db push Workflow

npx prisma db push

Syncs schema.prisma directly to database without creating migration files; regenerates Prisma Client with warnings on destructive changes. Use for throwaway prototypes or when recreating migrations later.

Editing Generated Migrations

When to edit: Add custom indexes; include

data migrations; optimize generated SQL; add database-specific features.

Example: After --create-only:

CREATE TABLE "User" (
    "id" TEXT NOT NULL,
    "email" TEXT NOT NULL,
    "name" TEXT,
    "role" TEXT NOT NULL DEFAULT 'user',
    CONSTRAINT "User_pkey" PRIMARY KEY ("id")
);

UPDATE "User" SET "role" = 'admin' WHERE "email" = 'admin@example.com';

CREATE UNIQUE INDEX "User_email_key" ON "User"("email");

Apply:

npx prisma migrate dev

Workflow Examples

Scenario	Commands
Feature Development	npx prisma migrate dev --name add_comments; npx prisma migrate dev --name add_comment_likes; npx prisma migrate dev --name add_comment_moderation
Prototyping	npx prisma db push (repeat); once stable: npx prisma migrate dev --name initial_schema
Review & Customize	npx prisma migrate dev --create-only --name optimize_queries; edit prisma/migrations/[timestamp]_optimize_queries/migration.sql; npx prisma migrate dev

Switching Between Workflows

From db push to migrate dev: Prisma detects current state and creates baseline migration:

npx prisma migrate dev --name initial_schema

Handling conflicts (unapplied migrations + db push usage):

npx prisma migrate reset
npx prisma migrate dev

Common Patterns

Pattern	Command
Daily Development	npx prisma migrate dev --name descriptive_name (one per logical change)
Experimentation	npx prisma db push (until design stable)
Pre-commit Review	npx prisma migrate dev --create-only --name feature_name (review SQL, commit schema + migration)
Team Collaboration	git pull; npx prisma migrate dev (apply teammate migrations)

Troubleshooting

Migration Already Applied: Normal when no schema changes exist. Run npx prisma migrate dev.

Drift Detected: Shows differences between database and migration history:

npx prisma migrate diff --from-migrations ./prisma/migrations --to-schema

-datamodel ./prisma/schema.prisma

Resolve by resetting or creating new migration.

Data Loss Warnings: Both commands warn before destructive changes. Review carefully before proceeding; migrate data or adjust schema to cancel.