Author Prisma Next migrations — choose db update vs migration plan, edit the framework-rendered migration.ts (replace placeholder sentinels with dataTransform closures), recover from MIGRATION.HASH_MISMATCH or PN-MIG-2001 unfilled placeholder. Use for prisma migrate dev, prisma migrate deploy, prism

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. migration.ts is framework rendered, not hand authored Files under migrations/<space id /<timestamp /migration.ts (for your own app, <space id is always app/ ) are rendered for you by the framework — prisma next migration plan writes a populated package whenever the contract changes, and prisma next migration new writes an empty scaffold when you want to author operations directly. You do not write these files from scratch. You edit specific holes the framework leaves behind — chiefly replacing placeholder("<slot ") sentinels (Postgres) or filling dataTransform({ check, run }) pipeline slots (Mongo) — then self emit. Postgres rendered imports point at @prisma next/postgres/migration (or @prisma next/sqlite/migration for SQLite projects). Mongo rendered imports use @prisma next/family mongo/migration for the Migration base class and @prisma next/target mongo/migration for operation factories ( createIndex , dataTransform , …). MigrationCLI comes from @prisma next/cli/migration cli . Treat the rendered import lines as framework managed on both targets: Leave them where they are. Don't rewrite them to a different @prisma next/<… path; the framework's renderer is the authoritative shape and any change you make by hand will be reverted (and may trip MIGRATION.HASH MISMATCH ) the next time the package is re rendered or self emitted. If you need an additional factory symbol, add it to the existing rendered import line (Postgres: @prisma next/postgres/migration ; Mongo: @prisma next/target mongo/migration ) rather than introducing a second import from a different @prisma next/... subpath. The "user code imports only from @prisma next/<target " convention applies to your own modules (queries, runtime setup, contract authoring). The framework rendered migration.ts scaffold is the framework's surface, not yours; the rule is suspended for that one file. Diagnostic codes you route on Code Source Move PN MIG 2001 Unfilled migration placeholder Throwing placeholder(...) at emit time Open migration.ts , replace the named placeholder("<slot ") call with the real query closure, self emit. PN MIG 2002 migration.ts not found Reading a migration package The package is malformed. Recover from version control, or run prisma next migration new for a fresh one. PN MIG 2003 invalid default export Loading migration.ts The file's default export is not a Migration subclass or factory function. Restore the planner emitted scaffold from version control or re run migration plan for a clean package. PN MIG 2005 dataTransform contract mismatch Building a data transform query plan The query builder was instantiated with a contract reference different from the endContract passed to this.dataTransform(...) . Use the endContract imported at module scope for both. MIGRATION.HASH MISMATCH Migration package is corrupt migrate (or any read of the package) ops.json / migration.json were edited without self emitting. Run node migrations/app/<dir /migration.ts to re emit, then re run migrate . PN RUN 3002 Hash mismatch db verify The marker disagrees with the contract hash ( Postgres: prisma contract.marker ; Mongo: prisma migrations ). The DB is at a different contract version than the code thinks. Either run a migration forward, or — if the DB is correct and the marker is stale after a manual fix up — run db sign . PN RUN 3001 Database not signed Any command needing a marker The DB has no marker yet. Run prisma next db init db <url to baseline an empty database, or db update db <url to apply the current contract directly. Decision — which path do you take? Situation Path Why Local dev, schema in flux db update Fast, interactive, no migration files. Shared branch with other developers migration plan + migrate Replayable, reviewable, content hashed. Anything reaching production migration plan + migrate Production must run a reviewed, hashed migration. Adding a column that needs a backfill migration plan (writes placeholder ), edit migration.ts , self emit, then migrate db update does not author data transforms; the formal path does. Recovering from drift (DB diverged from contract) db sign after manual fix, or migration plan if PN can plan the fix Depends on which side is right. See Recover from drift below. Dev → ship transition (the db ref pattern) Example — iterate locally wi

prisma-next-migrations