Migrations

Prisma Next IDB migrations are source-controlled packages. The CLI creates and validates them; the browser applies them when the client opens.

IndexedDB migrations are not applied by prisma-next migrate or db update. IndexedDB exists in the browser, so the runtime apply path is createAutoMigratingIdbClient().

First migration

Run this once in a new project:

npm run contract:emit
npm run migration:baseline
npm run migration:generate-space
npm run migration:preflight

migration:baseline creates migrations/app/<timestamp>_baseline/ from an empty database. It refuses to run once migration history exists.

The IDB CLI defaults to src/lib/prisma/contract.json. If your contract lives somewhere else, add --contract <path> to migration:baseline, migration:generate, and migration:generate-space. If your generated contract-space file should live somewhere else too, add --out <path> to migration:generate-space.

Later schema changes

For normal schema changes:

npm run contract:emit
npm run migration:generate -- --name add-todo-priority
npm run migration:generate-space
npm run migration:preflight

migration:generate reads the head migration's end-contract.json as the from-state, diffs it against the newly emitted contract, and writes the next package under migrations/app/ with the correct from hash linking it to the previous migration.

Package layout

Each migration package contains:

migrations/app/20260621T0854_baseline/
  migration.ts
  migration.json
  ops.json
  end-contract.json
  end-contract.d.ts

migration.ts is the readable source. ops.json and migration.json are the artifacts the runtime consumes. end-contract.json is used as the starting point for the next plan.

Commit the whole package.

Inspect and validate

Preflight walks the full migration chain from an empty database to the current head against fake-indexeddb:

npm run migration:preflight

Run this in CI to catch broken package ordering, tampered migration hashes, and DDL operations that cannot apply cleanly.

Manual migrations

Use migration:generate when you want a scaffold you can then hand-edit:

npm run migration:generate -- --name custom-idb-change
# edit migrations/app/<migration-dir>/migration.ts as needed
npx tsx migrations/app/<migration-dir>/migration.ts

Running the file self-emits ops.json and migration.json from whatever describe() and operations you have. Re-run it after each edit. Use tsx or your project's TypeScript runner for this manual path.

Destructive changes

Dropping an object store or index is marked as destructive. By default, createAutoMigratingIdbClient() refuses to apply them so a deploy cannot silently wipe local user data. Review the migration carefully before opting in — see Client.