prisma-next-migrations

Prisma Next — Migration Authoring

Edit your data contract. Prisma Next plans the migration. You fill in any data transforms.

The three-step user model:

1. You edit your data contract. (prisma-next-contract)
2. Prisma Next plans the migration for you. ← this skill
3. If a data transform is needed, you edit migration.ts and self-emit. ← this skill

Once the contract changes, you choose how the change reaches the database. This skill covers the two paths (db update and migration plan + migrate), the migration-package contract, the migration.ts authoring API, and the failure modes you recover from without leaving the loop.

Targets. Migration authoring is first-class for Postgres and Mongo. The CLI reads the target from prisma-next.config.ts (set during prisma-next init --target …). Migration commands do not accept a --target flag — use a config scoped to the target you need. Examples below call out target-specific imports, markers, factories, and transaction behavior where they diverge.

When to Use

• User edited the contract and wants to apply the change to the DB.
• User wants to author a migration with a data transform.
• User wants to run pending migrations against a local DB.
• User hit MIGRATION.HASH_MISMATCH, PN-MIG-2001 (unfilled placeholder), or a partially-applied migration.
• User mentions: migrate, migration, db push, db update, prisma migrate dev, prisma migrate deploy, drift, hash mismatch, data backfill.

When Not to Use

• User wants to know what migrations will run on deploy / on merge, or to manage refs and invariants → prisma-next-migration-review.
• User wants to edit the contract → prisma-next-contract.
• User wants a deeper read of a single structured error envelope → prisma-next-debug.

Key Concepts

• db update (quick path). Reads the emitted contract, diffs against the live DB, applies the change. Optional --dry-run prints the plan without executing. Interactive destructive-op confirmation (or -y to auto-accept). Writes no migration directory. Operations needing data transforms are not handled by this path — db update excludes the data operation class entirely and short-circuits where a data transform would be required. Use only against a database that has no shared history with anyone else (your local dev DB).
• migration plan (formal path). Reads the emitted contract, diffs against the head of the on-disk migration graph, writes a new migration package under migrations/app/<YYYYMMDDTHHMM>_<snake_slug>/. If any operation needs a data transform, the package's migration.ts contains placeholder(...) calls you fill in.
• The app/ segment in migration paths is the consuming application's contract-space id. Every migration you author lives under migrations/app/. Extensions your contract depends on get their own sibling directories (migrations/<extension-space-id>/) — those are managed by the extension package and you don't write into them. The app/ segment lands automatically the first time you run migration plan / db init against an app-level config.
• Migration package files (inside each migrations/app/<dir>/):
  • migration.json — manifest (metadata + migrationHash).
  • ops.json — canonical operation list. Content-addressed; migrationHash is computed over this.
  • migration.ts — TypeScript authoring source, framework-rendered by migration plan (or migration new). You edit specific holes in it (see Fill a placeholder below) and re-emit ops.json / migration.json by running it.
• Contract snapshots. migration.ts imports its bookend contracts from the shared, content-addressed store at migrations/snapshots/<hex>/contract.json + contract.d.ts (<hex> is the contract's 64-hex storage hash) — not from files inside the migration package.
• Self-emit. Running node migrations/app/<dir>/migration.ts regenerates ops.json and migration.json from the (possibly edited) TS source. This is the only supported way to update an existing migration package after edits.
• migration.ts shape. Framework-rendered. A class extending Migration (from @prisma-next/family-mongo/migration on Mongo, or re-exported via @prisma-next/postgres/migration on Postgres — see the framing block below), with an operations getter that returns an array of factory-call values. The file ends with MigrationCLI.run(import.meta.url, M) so executing it self-emits.
• placeholder(slot). A sentinel the planner emits into the rendered migration.ts (from @prisma-next/errors/migration on Mongo, or the @prisma-next/postgres/migration import on Postgres) wherever a data transform is needed. Calling placeholder(...) at emit time throws PN-MIG-2001 Unfilled migration placeholder. The user replaces the () => placeholder(...) arrow with a real query-plan closure (Postgres) or fills dataTransform({ check, run }) sources (Mongo — see Fill a placeholder), then self-emits.
• this.dataTransform(endContract, name, { check, run }). The data-transform factory. check is a rowset query whose presence-of-any-row signals "work remains"; run is one or more mutation queries that perform the backfill. Both are lazy closures returning query-plans built against endContract. The runner wraps check as EXISTS(...) for precheck and NOT EXISTS(...) for postcheck, so the same closure asserts both "there is work" and "the work is done".
• pendingPlaceholders. A boolean field on the JSON result of migration plan. true means the package was written but contains unfilled placeholders — migrate will throw PN-MIG-2001 until you edit migration.ts and self-emit.
• migrationHash. Content-addressed identity of a migration package. MIGRATION.HASH_MISMATCH fires when the stored hash in migration.json disagrees with the hash recomputed from the on-disk files (almost always: someone edited migration.ts without self-emitting).
• Marker. Records "this database is at contract hash X for space Y". Postgres: a row in prisma_contract.marker. Mongo: a document in the _prisma_migrations collection (keyed by space). Each successful migration advances the marker once schema verification passes for that space. db sign writes the marker from the current contract hash, but only after a schema-verification pass succeeds (it will not sign a database whose live schema disagrees with the contract).
• Apply atomicity. Postgres: each migration runs inside BEGIN ... COMMIT; on failure, Postgres rolls back and the marker stays at the previous migration's to hash. Mongo: DDL ops (createCollection, createIndex, collMod, setValidation, …) are not wrapped in a multi-document transaction; the runner applies ops, verifies the live schema against the destination contract, and advances the marker only on verify-pass (resumable across spaces — see the MongoDB family doc). Ordinary DDL + dataTransform flows stay consistent; partial state from failed mid-migration runs is diagnosed with db verify / db schema, not assumed away.
• Operation classes. Every operation declares an operationClass: additive, widening, data, or destructive. The CLI surfaces these in the plan preview and in JSON output. There is no long-running class and the framework does not emit CREATE INDEX CONCURRENTLY — operations stay transactional.