migration plan

migration plan compares the emitted contract against a starting contract and produces a new migration package with the required operations.

The starting contract is whatever --from names, or the ref named db when --from is absent.

With neither, what happens depends on the migrations already on disk:

• migrations/app/ is empty. The plan starts from an empty database and contains the full CREATE operations for the whole contract. This is the first migration in a new project. The command says so under its summary (No db ref set — planning from an empty database), and --json output carries fromDefaulted: true, so a plan that recreates a database you already have is easy to spot. If a database already exists, run db init, db update, or db sign first.
• Migrations already exist. The command refuses with MIGRATION.PLAN_ORIGIN_UNKNOWN rather than write a full-create package that no real database could apply. The error names the three exits: migration ref set db <contract> to point the ref at the state your database is on, --from <ref> to name the origin for this one plan, or --from @empty to plan from an empty database deliberately.

Keep the db ref current and you never see the refusal. db init and db update advance it for you when you run them without --db; with --db you have to add --advance-ref db. db sign advances it whenever it signs, --db or not. db migrate advances nothing unless you pass --advance-ref db.

Say migrations/app/ has no migrations yet, the db ref is set, and migrations/snapshots/ holds a copy of the contract the ref points at. Then migration plan writes a baseline: a migration from an empty database to the ref's contract. If your emitted contract has changed since then, the same run also writes a second migration with those changes. Expect one or two new directories in git status.

db migrate never applies the baseline to a database that already records which contract it matches, such as one you ran db sign on. It applies only the migrations after the contract that database records.

The baseline only creates things, because it is planned from an empty database, so it never removes data. The second migration can remove data. migration plan writes it without asking, and the command's output marks each destructive operation in it and warns that it may cause data loss. Review that migration before you apply it.

If a migration already starts from the contract the db ref points at, migration plan writes a second migration that starts from the same contract, so the migration history splits into two branches. This happens, for example, after db migrate without --advance-ref db, which applies migrations but leaves the db ref where it was. migration plan still writes the migration and prints a warning. A database that has already run the existing migration then has no migration leading to your new contract, so db migrate on that database fails with MIGRATION.PATH_UNREACHABLE. To build on the newest migration instead, delete the directory this run wrote and plan again with --from set to the newest migration's directory name.

The command is offline. It does not need a database connection.

bunx prisma migration plan --name add_users_table

pnpm prisma migration plan --name add_users_table

yarn prisma migration plan --name add_users_table

npx prisma migration plan --name add_users_table

bunx prisma contract emit

bunx prisma migration plan --name add_users_table

bunx prisma migration show <migration-dir>

pnpm prisma contract emit
pnpm prisma migration plan --name add_users_table
pnpm prisma migration show <migration-dir>

yarn prisma contract emit
yarn prisma migration plan --name add_users_table
yarn prisma migration show <migration-dir>

npx prisma contract emit
npx prisma migration plan --name add_users_table
npx prisma migration show <migration-dir>

Review the generated migration package before applying it with db migrate.

Because --to accepts <dir>^ (the source contract of a migration), you can plan a migration that walks back a change:

bunx prisma migration plan --to <migration-dir>^ --name rollback

pnpm prisma migration plan --to <migration-dir>^ --name rollback

yarn prisma migration plan --to <migration-dir>^ --name rollback

npx prisma migration plan --to <migration-dir>^ --name rollback

Use migration plan when your team wants database changes reviewed in version control. For local prototypes where review is not needed, db update is usually faster.

If the generated migration is not the migration you want, use migration new and author the migration manually.