# migration plan (/docs/cli/migration-plan) Plan an on-disk migration from Prisma ORM contract changes. Location: CLI > 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](/guides/migration-migration-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 ` to point the ref at the state your database is on, `--from ` 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`](/guides/orm-db-init) and [`db update`](/guides/orm-db-update) advance it for you when you run them without `--db`; with `--db` you have to add `--advance-ref db`. [`db sign`](/guides/orm-db-sign) advances it whenever it signs, `--db` or not. [`db migrate`](/guides/orm-db-migrate) advances nothing unless you pass `--advance-ref db`. ### The automatic baseline 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](/guides/migrations-the-migration-graph) 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. ## Usage #### bun ```bash bunx prisma migration plan --name add_users_table ``` #### pnpm ```bash pnpm prisma migration plan --name add_users_table ``` #### yarn ```bash yarn prisma migration plan --name add_users_table ``` #### npm ```bash npx prisma migration plan --name add_users_table ``` ## Options | Option | What it does | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--name ` | Sets the migration directory name suffix. | | `--from ` | Uses a specific starting contract reference (hash, prefix, ref name, migration directory name, `^`, `./path`, or `@empty`) instead of the `db` ref. `migration plan` is offline, so `@db` and `@contract` are not accepted here. | | `--to ` | Sets the destination contract reference. Defaults to the emitted contract. Same grammar as `--from`, except that `@empty` is refused as a destination. | | `--config ` | Read this config file instead of `./prisma.config.ts`. | | `--json` | Prints a machine-readable result. | ## Recommended flow #### bun ```bash bunx prisma contract emit bunx prisma migration plan --name add_users_table bunx prisma migration show ``` #### pnpm ```bash pnpm prisma contract emit pnpm prisma migration plan --name add_users_table pnpm prisma migration show ``` #### yarn ```bash yarn prisma contract emit yarn prisma migration plan --name add_users_table yarn prisma migration show ``` #### npm ```bash npx prisma contract emit npx prisma migration plan --name add_users_table npx prisma migration show ``` Review the generated migration package before applying it with [`db migrate`](/guides/orm-db-migrate). ## Planning a rollback Because `--to` accepts `^` (the source contract of a migration), you can plan a migration that walks back a change: #### bun ```bash bunx prisma migration plan --to ^ --name rollback ``` #### pnpm ```bash pnpm prisma migration plan --to ^ --name rollback ``` #### yarn ```bash yarn prisma migration plan --to ^ --name rollback ``` #### npm ```bash npx prisma migration plan --to ^ --name rollback ``` ## When to use migration plan Use `migration plan` when your team wants database changes reviewed in version control. For local prototypes where review is not needed, [`db update`](/guides/orm-db-update) is usually faster. If the generated migration is not the migration you want, use [`migration new`](/guides/migration-migration-new) and author the migration manually. ## Related pages - [`auth`](/guides/platform-auth): Sign in to your Prisma account from the CLI, sign out, and manage workspace sessions. - [`branch`](/guides/platform-branch): List platform branches for a project. - [`bucket`](/guides/platform-bucket): Create and manage object-store buckets. - [`Configuration`](/guides/introduction-6-configuration): Configure Prisma ORM CLI commands with prisma.config.ts and global flags. - [`contract emit`](/guides/orm-contract-emit): Emit Prisma ORM contract artifacts. ## Related pages - [Authentication & Tools](./authentication-tools-index.md) - [Build](./build-index.md) - [Changelog](../changelog.md) - [Concepts](./concepts-index.md) - [Console commands](./console-commands-index.md) - [Contract Authoring](./contract-authoring-index.md) - [Core Concepts](./core-concepts-index.md) - [Data Modeling](./data-modeling-index.md) - [Database](./database-index.md) - [DB commands](./db-commands-index.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.