managing-dev-migrations

---

name: managing-dev-migrations description: Use migrate dev for versioned migrations; db push for rapid prototyping. Use when developing schema changes locally. allowed-tools: Read, Write, Edit, Bash

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

Copynpx 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:

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

Edit if needed, then apply:

Copynpx prisma migrate dev

db push Workflow

Copynpx 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:

CopyCREATE 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:

Copynpx prisma migrate dev

Workflow Examples

Switching Between Workflows

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

Copynpx prisma migrate dev --name initial_schema

Handling conflicts (unapplied migrations + db push usage):

Copynpx prisma migrate reset
npx prisma migrate dev

Common Patterns

Troubleshooting

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

Drift Detected: Shows differences between database and migration history:

Copynpx 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.