# migration new (/docs/cli/migration-new) > For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL. Scaffold a Prisma ORM migration package for manual authoring. Location: CLI > migration new `migration new` creates a migration package with a `migration.ts` file for manual authoring. Use it when the generated plan is not enough and you want to write the migration operations yourself. The command is offline. It does not consult the database. ## Usage [#usage] #### bun ```bash bunx prisma migration new --name split-name ``` #### pnpm ```bash pnpm prisma migration new --name split-name ``` #### yarn ```bash yarn prisma migration new --name split-name ``` #### npm ```bash npx prisma migration new --name split-name ``` ## Options [#options] | Option | What it does | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--name ` | Sets the migration directory name suffix. | | `--from ` | Starts from the contract state an existing migration ends at: the `to` hash in that migration's `migration.json`, or a unique prefix of it. Without it, see [Where it starts](#where-it-starts). | | `--config ` | Read this config file instead of `./prisma.config.ts`. | | `--json` | Prints a machine-readable result. | `migration new --from` takes only a hash or a unique prefix of one. Unlike [`migration plan --from`](https://www.prisma.io/docs/cli/migration-plan#options), it does not accept a migration directory name or a ref name. It refuses `--from` when `migrations/app/` has no migrations, and refuses a prefix that matches more than one migration. Run `npx prisma migration list` to see the hashes of your migrations. [Contract references each command accepts](https://www.prisma.io/docs/orm/migrations/the-migration-graph#contract-reference-forms) compares it with the other commands. ## Where it starts [#where-it-starts] Without `--from`, `migration new` picks its starting point the way [`migration plan`](https://www.prisma.io/docs/cli/migration-plan) does. The result depends on whether the [`db` ref](https://www.prisma.io/docs/cli/migration-ref#the-db-ref) exists and whether `migrations/app/` has migrations. The `db` ref is the file `migrations/app/refs/db.json`, which records the contract state you expect your local database to match. `migrations/app/` is the folder for your application's own migrations, and each extension package that ships migrations has its own folder beside it. * When the `db` ref exists and `migrations/app/` has migrations, it starts from the `db` ref. If the contract has not changed since that state, it refuses with `MIGRATION.NO_CHANGES`; to create a migration that holds only SQL or data changes on the current contract, pass `--from` with the `to` hash of your newest migration. * When there are no migrations and no `db` ref, it starts from an empty database. * When migrations exist but there is no `db` ref, it refuses with `MIGRATION.PLAN_ORIGIN_UNKNOWN`. Pass `--from` with the `to` hash of the migration to build on, or point the `db` ref at the state your database is on. To find that state, run `npx prisma migration status --db "$DATABASE_URL" --json`: the `currentContract` of the `app` entry in `result.spaces` is the hash of the contract state your database matches. Then run `npx prisma migration ref set db `, where `` is that hash or the directory name of the migration that ends at it. * When the `db` ref exists but there are no migrations, it refuses with `MIGRATION.HASH_NOT_IN_GRAPH`, because there is no migration yet that ends at the state the `db` ref names. Run `migration plan` first. It writes a [baseline migration](https://www.prisma.io/docs/orm/migrations/the-migration-graph#baselines), a migration from an empty database to that state, and then `migration new` can start from it. `migration plan` reads that state from the copy saved under `migrations/snapshots/` by the command that set the `db` ref, and if the copy is missing, it fails and asks you to restore `migrations/snapshots/` from version control. Before `8.0.0-rc.12`, `migration new` started from the newest migration. Scripts that relied on that should pass `--from` with the newest migration's `to` hash. ## Examples [#examples] #### bun ```bash bunx prisma migration new --name split-name bunx prisma migration new --name custom-fk --from abc123 ``` #### pnpm ```bash pnpm prisma migration new --name split-name pnpm prisma migration new --name custom-fk --from abc123 ``` #### yarn ```bash yarn prisma migration new --name split-name yarn prisma migration new --name custom-fk --from abc123 ``` #### npm ```bash npx prisma migration new --name split-name npx prisma migration new --name custom-fk --from abc123 ``` ## Data lines [#data-lines] Without `--json`, standard output gets one line: the directory the command wrote. So a script can open the new `migration.ts`: ```bash dir="$(npx prisma migration new --name split-name)" && "$EDITOR" "$dir/migration.ts" ``` [Global flags](https://www.prisma.io/docs/cli/global-flags#data-lines-of-prisma-orm-commands) lists the rules data lines follow. ## After scaffolding [#after-scaffolding] Write the migration body in `migration.ts`, then run the file with Node so it emits `ops.json` and attests the package: ```bash node migration.ts ``` Inspect the result: #### bun ```bash bunx prisma migration show ``` #### pnpm ```bash pnpm prisma migration show ``` #### yarn ```bash yarn prisma migration show ``` #### npm ```bash npx prisma migration show ``` Apply the migration only after review: #### bun ```bash bunx prisma db migrate --db "$DATABASE_URL" ``` #### pnpm ```bash pnpm prisma db migrate --db "$DATABASE_URL" ``` #### yarn ```bash yarn prisma db migrate --db "$DATABASE_URL" ``` #### npm ```bash npx prisma db migrate --db "$DATABASE_URL" ``` Manual migrations should still end at a contract state that matches the emitted contract. ## Related pages - [`auth`](https://www.prisma.io/docs/cli/auth): Sign in to your Prisma account from the CLI, sign out, and manage workspace sessions. - [`branch`](https://www.prisma.io/docs/cli/branch): List platform branches for a project. - [`bucket`](https://www.prisma.io/docs/cli/bucket): Create and manage object-store buckets. - [`Configuration`](https://www.prisma.io/docs/cli/configuration): Configure Prisma ORM CLI commands with prisma.config.ts and global flags. - [`contract emit`](https://www.prisma.io/docs/cli/contract-emit): Emit Prisma ORM contract artifacts.