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.

bunx prisma migration new --name split-name

pnpm prisma migration new --name split-name

yarn prisma migration new --name split-name

npx prisma migration new --name split-name

migration new --from takes only a hash or a unique prefix of one. Unlike migration plan --from, 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.

Without --from, migration new picks its starting point the way migration plan does. The result depends on whether 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 <contract>, where <contract> 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, 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.

bunx prisma migration new --name split-name

bunx prisma migration new --name custom-fk --from abc123

pnpm prisma migration new --name split-name
pnpm prisma migration new --name custom-fk --from abc123

yarn prisma migration new --name split-name
yarn prisma migration new --name custom-fk --from abc123

npx prisma migration new --name split-name
npx prisma migration new --name custom-fk --from abc123

Write the migration body in migration.ts, then run the file with Node so it emits ops.json and attests the package:

node migration.ts

Inspect the result:

bunx prisma migration show <migration-dir>

pnpm prisma migration show <migration-dir>

yarn prisma migration show <migration-dir>

npx prisma migration show <migration-dir>

Apply the migration only after review:

bunx prisma db migrate --db "$DATABASE_URL"

pnpm prisma db migrate --db "$DATABASE_URL"

yarn prisma db migrate --db "$DATABASE_URL"

npx prisma db migrate --db "$DATABASE_URL"

Manual migrations should still end at a contract state that matches the emitted contract.