prisma-next-migrations

name

prisma-next-migrations

description

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, prisma db push, db update, db update --dry-run, migration plan, migrate, migration new, migration show, db verify, db sign, data migration, this.dataTransform, dataTransform, placeholder, generated migration.ts, edit migration.ts, MIGRATION.HASH_MISMATCH, schema drift.

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.
  • end-contract.json and end-contract.d.ts — the contract this migration ends at, imported by migration.ts for type-safe data transforms.
  • 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.
• 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 with db update, then publish the first real migration:

pnpm prisma-next db init --db $DATABASE_URL
pnpm prisma-next contract emit && pnpm prisma-next db update --db $DATABASE_URL
pnpm prisma-next contract emit && pnpm prisma-next migration plan --name add_feature
pnpm prisma-next migrate --db $DATABASE_URL
pnpm prisma-next db verify --db $DATABASE_URL

The db ref is a named pointer at migrations/app/refs/db.json plus a paired contract snapshot (db.contract.json, db.contract.d.ts). It records which contract hash the project's dev database has been brought up to — the offline planner's stand-in for "where is my local DB?" without opening a connection at plan time.

What db init / db update write. When run against the project's default --db URL (no explicit --db flag), both commands implicitly advance the db ref and refresh its paired snapshot from the post-command contract IR. Override the ref name with --advance-ref <name>. When you pass --db <non-default-url>, ref advancement is suppressed unless --advance-ref is explicit — reconciling a different database is not the same as checkpointing this project's dev state.

The on-disk layout mirrors migration bundle snapshots:

migrations/app/refs/
├── db.json                 # { "hash": "sha256:…", "invariants": [] }
├── db.contract.json        # full contract IR at that hash
└── db.contract.d.ts        # typed import handle

First migration plan after dev iteration. migration plan defaults --from to the db ref. When the on-disk migration graph is still empty and the db ref points at a non-null hash with a paired snapshot (typical after one or more db update cycles), the planner emits two bundles instead of one:

1. Baseline: null → from-hash (introduces from-hash as a graph node)
2. Delta: from-hash → current_contract

Both land on disk in one invocation — expect two new directories in git status. migrate then finds a path through the baseline and applies the delta. This closes the dev → ship trap where a single-bundle plan referenced a hash that was not yet a graph node and produced an unapplyable migration (MIGRATION.PATH_UNREACHABLE at apply time).

The forgot-the-flag pitfall. After the graph is non-empty, the default db ref may point past the graph tip (the ref advanced on every db update while you iterated, but you never committed migrations). The next implicit-default migration plan refuses with MIGRATION.HASH_NOT_IN_GRAPH and names reachable refs that point at graph nodes.

Recovery when you see MIGRATION.HASH_NOT_IN_GRAPH on plan:

# Option A — plan from a graph node explicitly
pnpm prisma-next migration plan --from production --name my_change

# Option B — realign the db ref to a graph-node hash, then plan with the default
pnpm prisma-next ref set db <graph-node-hash>
pnpm prisma-next migration plan --name my_change

If the paired snapshot is missing (MIGRATION.SNAPSHOT_MISSING), repopulate with db update --advance-ref db or delete the orphan pointer with ref delete db.

After plain migrate. migrate does not implicitly advance the db ref (production-shaped commands stay explicit). The live marker advances while the ref may lag. Refresh with db update (no-op on DB when already current) or migrate --advance-ref db in the same invocation.

When to switch paths. Use db update while the schema is in flux on a solo dev database. Switch to migration plan + migrate when the change needs a reviewable, replayable migration — typically before opening a PR or touching any shared environment. The db ref bridges the two: it captures dev iteration state on disk so the first formal plan knows where you left off.

Graph-node rule (plan time). Any hash used as a from end — explicit --from, default db ref, or ref name — must already be a node in the on-disk migration graph once the graph is non-empty. The auto-baseline two-bundle emission is the one exception: it applies only on an empty graph with a non-null ref-resolved from and an available paired snapshot. If you deleted the snapshot files or the ref pointer without the graph, plan refuses with MIGRATION.SNAPSHOT_MISSING instead.

Apply-time complement. migrate reads the live marker before DDL. If the marker hash is not a graph node, the command refuses with MIGRATION.MARKER_MISMATCH — catching drift the offline planner cannot see. This is separate from MIGRATION.MARKER_NOT_IN_HISTORY, which fires later during the runner's graph walk when the marker is off the path being traversed. See prisma-next-migration-review for the full diagnostic catalog.

db is a default ref name, not a reserved one. The framework overwrites it on the next dev cycle; you may ref set db <hash> explicitly and accept that a subsequent db update replaces it when run against the default URL.

Canonical detail: Migration System § Refs (paired contract snapshots), § migration plan, § Recovery affordances, and ADR 218 — Refs with paired contract snapshots and universal graph-node invariant (TML-2629).

Workflow — db update (quick path)

The concept: db update resolves the destination (emitted contract) against the live DB and applies the difference. Preview with --dry-run. Destructive ops prompt interactively unless you pass -y or --no-interactive. The path excludes operations of the data class entirely — if the diff requires a data transform, db update fails with a planning error and you switch to migration plan to author the transform.

Run after a contract edit:

pnpm prisma-next contract emit
# Postgres: --db postgresql://...