# migration new (/docs/cli/migration-new) 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 #### 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 | 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`](/guides/migration-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. ## Where it starts Without `--from`, `migration new` picks its starting point the way [`migration plan`](/guides/migration-migration-plan) does. The result depends on whether the [`db` ref](/guides/migration-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. - 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](/guides/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 #### 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 ``` ## 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`](/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.