Prisma Next — Migration Review (Deployment + Concurrency)

Edit your data contract. Prisma handles the rest.

This skill is about reviewing migrations, not authoring them. It covers the questions that come up at deploy time and when multiple developers are landing migrations concurrently.

The skill teaches the system's mental model — what a ref is, what a marker is, what the migration graph is — and shows how to ask the system for its state. It does not prescribe rigid step-by-step procedures: most "review" questions are answered by understanding the model and querying the right thing. Rigid procedures are reserved for the rare case where there's literally one safe path.

When to Use

User asks "what migrations will run when I merge this?" or "what's about to run on deploy?".
User hit a concurrent-migration conflict (
```
main
```
advanced while their branch was open).
User wants to wire up a
```
staging
```
/
```
production
```
ref so CI can deploy against it.
User wants to run a migration against an environment that isn't the local dev DB.
User asks about CI integration for migrations.

When Not to Use

User wants to author a migration →
```
prisma-next-migrations
```
.
User wants to fix a hash-mismatch / drift in a single env →
```
prisma-next-migrations
```
(re-plan path) or
```
prisma-next-debug
```
(envelope-driven).
User wants to edit the contract →
```
prisma-next-contract
```
.

Key Concepts — the navigation model

Every migration question is a navigation from an origin to a destination. Once you have this model, the rest of the skill is just "which command asks the system about which navigation."

Origin

The origin is the database's current contract hash. The database carries a row in PN's marker table that records "this database is at hash X". When the CLI runs online (a

--db <url>

is provided, or

db.connection

is set in

prisma-next.config.ts

), PN reads the marker and that hash is the origin. Offline (no DB connection), the origin is unknown — many commands degrade to listing the on-disk migrations and skip the per-edge applied/pending status.

A live DB is therefore the authoritative source of origin. The "recorded marker" in any other artifact (refs, local cache, your assumptions) is a working copy that can drift; the live DB never does.

Destination

The destination is the contract hash you want the database to be at. Two ways to name a destination:

A
--ref <name>
— a named pointer to a hash, stored under
```
migrations/app/refs/<name>
```
. Refs are named after environments by convention (
```
staging
```
,
```
production
```
) to communicate "this is where production is expected to be". The ref itself is just a hash + an optional set of required invariants; it has nothing to do with which database you connect to.
The current contract head — implicit when no
```
--ref
```
is passed. This is the hash of the current
```
contract.json
```
on disk.

--ref staging

does not mean "connect to the staging database." It means "navigate the database I connected to (via

--db

or config) toward whatever hash this ref points at." Database selection is orthogonal: pass

--db $STAGING_DATABASE_URL

to actually point at staging.

The migration graph

The on-disk migrations form a directed graph: nodes are contract hashes; edges are migrations. Each migration declares a

from

hash and a

to

hash. A migration applies only when the database's current marker matches its

from

hash; running it advances the marker to its

to

hash.

migration status

queries the graph for the path from origin to destination and reports per-edge status:

applied — on the path from
```
EMPTY_CONTRACT_HASH
```
to the marker (history).
pending — on the path from the marker to the destination (what would run).
unreachable — on the path from
```
EMPTY_CONTRACT_HASH
```
to the destination, but the marker is on a different branch and won't reach it without first re-routing.

Diagnostic codes

migration status

emits structured diagnostics on the result envelope (

diagnostics[].code

) so the agent can branch on the code rather than parsing the prose summary. Each diagnostic also carries

severity

(

warn

info

), a human

message

, and

hints

— the same hints the CLI prints under the summary line.

Code	Severity	Meaning in the navigation model	Next move
`MIGRATION.UP_TO_DATE`	info	Marker = destination; no edges to walk.	Nothing to do.
`MIGRATION.DATABASE_BEHIND`	info	Marker is an ancestor of the destination; N pending edges in between.	`migrate --to <name> --db $URL` .
`MIGRATION.INVARIANTS_PENDING`	info	Marker reached destination structurally but missing required invariants the ref declares.	`migrate --to <name> --db $URL` to take a path that covers them.
`MIGRATION.NO_MARKER`	warn	Online, but the database has no marker row — never initialised.	`migrate --db $URL` (first apply writes the marker).
`MIGRATION.MARKER_NOT_IN_HISTORY`	warn	Online; marker hash is not a node in the graph. The database was changed outside the migration system.	Decide which side is truth: `db sign` (accept DB as truth), `db update` (push contract to DB), `contract infer` (re-derive contract from DB), or `db verify` (inspect first).
`MIGRATION.DIVERGED`	warn	Multiple valid leaves; the destination is ambiguous.	Pass `--to <name>` , or `ref set <name> <hash>` to create one.
`CONTRACT.AHEAD`	warn	Contract head is not in the graph — the contract was edited without re-planning.	`migration plan` to extend the graph.
`CONTRACT.UNREADABLE`	warn	`contract.json` couldn't be read.	`contract emit` to regenerate it.

A CI gate should read

diagnostics

from

--json

output and decide based on

severity

plus

code

; see Workflow — CI below for the structure.

Workflow — "What's about to run on deploy?"

The user asks: "I'm about to merge this PR. What migrations are going to run when I deploy to staging?"

This is the navigation question: origin = staging's live marker; destination = the ref

staging

(or the contract head if you haven't set one). Ask the system:

bash

pnpm prisma-next migration status --to staging --db "$STAGING_DATABASE_URL"

The command:

Reads the staging DB's marker (the origin).
Resolves
```
staging
```
to a contract hash (the destination).
Renders the path between them as an ordered list of migrations, with per-edge
```
applied
```
/
```
pending
```
/
```
unreachable
```
status, and an explicit summary line of the form "N migration(s) behind ref 'staging'".
Prints a header that names the config, migrations directory, the active ref, and the database connection (masked) — so the framing is visible in the output.

If you omit

--db

, the command runs offline: it lists the migrations on disk but cannot tell you what's applied, because it has no origin. That's fine for "what's on this branch?"; it's not fine for "what's about to run on staging?" — for that you need staging's live marker.

If you omit

--ref

, the destination defaults to the contract head — which answers "is this branch's contract reachable from the database, and how?", not "what runs on deploy". Pass the ref explicitly when the question is about a specific environment.

migration status

summarises each pending migration's operations by class (

additive

widening

data

destructive

) and reports a destructive-op count when destructive operations are present. Surface that count to the user before they merge or deploy — destructive operations are the class that warrants manual review.

Workflow — "What state is each environment at?"

Just

migration status --db $URL

for each environment's DB. The marker (origin) comes back from the DB itself; the summary line tells you whether the environment is at the contract head, at a named ref, ahead of head, or on a divergent branch.

Concept — concurrent migrations on the same branch point

This used to be called diamond convergence in some PN docs; the situation is the same regardless of the label.

What's happening. Two topic branches each authored a migration off the same parent contract hash. The first branch merges to

main

; the destination ref (e.g.

production

) advances to that branch's

to

hash. Your branch's migration still has its

from

hash pointing at the old parent. The migration graph, after rebase, no longer has a clean path through your migration:

Your migration's
```
from
```
is no longer an ancestor of the new head.
Or your migration's
```
from
```
is reachable, but the path through your migration arrives at a hash that's not the union of both branches' changes.

Either way, the on-disk plan is stale.

Resolution. The on-disk plan is stale because its

from

hash is no longer the head of the graph; apply the cluster's standard edit → plan → apply loop to the post-rebase state and the planner produces a fresh migration whose

from

matches the new head.

The one thing the planner can't do for you is port custom data-transform logic from the abandoned

migration.ts

into the new one — schema deltas are derived from the contract, but any hand-written

data

operations are yours to carry across before applying. There is no separate "revalidate" step, no special "diamond apply" flow.

Workflow — set, list, get, delete refs

Refs are small artifacts. There's no per-environment lifecycle; you just point a name at a hash.

bash

pnpm prisma-next ref set production <contract-hash>
pnpm prisma-next ref list
# `ref get` was removed — use `ref list` and filter by name
pnpm prisma-next ref list | grep production
pnpm prisma-next ref delete production

ref set

writes a file at

migrations/app/refs/<name>

carrying the hash and any required invariants. Refs are commit-friendly artifacts — keep them in git; the team agrees on what

production

points at the same way they agree on what

main

is.

Workflow — apply a migration against an environment

bash

pnpm prisma-next migrate --to production --db "$PRODUCTION_DATABASE_URL"

The destination is the ref's hash; the origin is the production DB's live marker. The command computes the path between them and applies each pending migration in order, advancing the marker.

--db

is the environment selection knob.

--ref

is the destination-hash knob. They're independent.

Concept — ref-mismatch on CI / deploy

CI reports: "the recorded ref
production
is at hash X; the live DB is at hash Y."

The mismatch is a fact about two pieces of state that disagree. The investigation is the same regardless of which piece is wrong:

DB ahead of the ref. Someone applied a migration outside CI without updating the ref in git. Re-record the ref with
```
prisma-next ref set <ref-name> <db-marker-hash>
```
(commit + push); then audit how the out-of-band apply happened.
DB behind the ref. A previous deploy was rolled back, or the DB was restored from an older backup. Either re-apply forward with
```
prisma-next migrate --to <ref-name> --db $URL
```
, or re-route the ref backward to match what's actually deployed with
```
prisma-next ref set <ref-name> <db-marker-hash>
```
. The choice is the user's — name both options.
DB on a different branch. An out-of-band schema change (manual SQL, ad-hoc migration) wrote something the migration graph doesn't model. Run
```
prisma-next db verify
```
to inspect the drift, then either
```
prisma-next contract infer
```
to re-derive the contract from the database, or edit the contract and run
```
prisma-next migration plan
```
so the database is the eventual destination.

ref set

to silently align the ref with whatever the DB happens to be at is almost never the right move. It papers over drift that you'll pay for later.

Workflow — CI: verify a branch can advance the target environment

The gate is

migration status --to <env> --db $URL

: it computes the path from the live marker to the ref and reports it, without mutating anything. There is no

--dry-run

flag on

migrate

; the inspect / gate step is

migration status

yaml

- name: Verify staging is reachable
  run: |
    pnpm prisma-next migration status \
      --to staging --db "$STAGING_DATABASE_URL" --json > status.json
    node -e '
      const s = JSON.parse(require("fs").readFileSync("status.json", "utf8"));
      const warns = (s.diagnostics ?? []).filter(d => d.severity === "warn");
      if (warns.length) {
        console.error("Blocking diagnostics:", warns);
        process.exit(1);
      }
    '
- name: Apply
  run: pnpm prisma-next migrate --to staging --db "$STAGING_DATABASE_URL"

migration status

exits non-zero only on hard errors (unreadable migrations directory, unsatisfiable invariants, unreconstructable history). Diagnostics like

MIGRATION.MARKER_NOT_IN_HISTORY

MIGRATION.DIVERGED

CONTRACT.AHEAD

, and

MIGRATION.NO_MARKER

are reported on the result envelope with

severity: 'warn'

but the process exits

— the agent (or a CI gate) must inspect

diagnostics[]

and fail the build itself. Use

--json

so the gate parses a structured shape rather than the human summary.

migrate

is interactive-free and has no destructive-op confirmation prompt — the safety rails that prompt for destructive changes live on

db update

(see the

prisma-next-migrations

skill). Whatever the planner put in the migration graph is what

migrate

runs; review happens at

migration plan

and at

migration status

time, before the apply step.

Common Pitfalls

Reading
migration status
without
--ref
for a deploy question. That asks "can this branch's contract reach the head?", not "what's about to run on staging?". Always pass the ref when the question is about a specific environment.
Reading
migration status
without
--db
for a deploy question. Without a live DB, you have no origin. The output lists what's on disk; it can't say what's applied on the environment. Pass
```
--db $URL
```
for any high-stakes question.
Confusing the ref with a DB connection.
```
--ref staging
```
selects the destination hash, not the database. Pass both
```
--ref
```
and
```
--db
```
explicitly.
Treating diamond convergence as a special procedure. It's not. It's the normal edit → plan → apply loop applied to the post-rebase state. The only extra step is "port any data-transform logic from your old
migration.ts
over."
Running
ref set
to silence a CI mismatch without understanding the cause. That can mask out-of-band changes or rollback drift. Investigate first.

What Prisma Next doesn't do yet

Per-environment migration ordering beyond the default chain. If you need staging to skip a migration that production requires (or vice versa), the supported path is to author the per-env divergence as separate migrations and gate them in your deploy script. If you want first-class per-env routing, file a feature request via the
```
prisma-next-feedback
```
skill.
A built-in side-by-side "branch diff" view. There is a full-graph render (
```
migration graph
```
) that shows branches, but no
```
git diff
```
-style comparison between two branches' migration sets. Workaround: run
```
migration status
```
on each branch and
```
diff
```
the output. If you want a built-in branch-comparison view, file a feature request via the
```
prisma-next-feedback
```
skill.

Reference Files

This skill is intentionally body-only; the underlying CLI reference (

prisma-next migration status --help

migrate --help

ref --help

) is the authoritative surface for flag-level detail. When in doubt, run

--help

and read the actual command's description rather than guessing from this skill.

Checklist

Named both the origin (live DB marker) and the destination (ref or contract head) for the question the user asked.
Passed
```
--db $URL
```
whenever the question involves a specific environment.
Passed
```
--ref <name>
```
whenever the question is about deploying to a named environment, not just from the current branch's head.
Read the
```
migration status
```
header (it names config, ref, database) and the summary line (it names the origin/destination distance) before reading the per-edge list.
For concurrent-migration conflicts: re-applied the core workflow (edit → plan → apply) rather than following a memorised "diamond convergence" procedure. Ported any data-transform logic from the abandoned
```
migration.ts
```
over.
For a ref-mismatch: investigated which piece of state is wrong (DB ahead, DB behind, DB on a divergent branch). Did NOT
```
ref set
```
to silence the mismatch.
Surfaced the destructive-op count from
```
migration status
```
(the only operation class that warrants manual review pre-deploy) before the user merges or deploys.
In CI: parsed
```
migration status --json
```
```
diagnostics[]
```
and gated on
```
severity === 'warn'
```
; did NOT rely on a
```
--dry-run
```
flag on
```
migrate
```
(no such flag exists).
Did NOT confuse
```
--ref
```
with database selection.
Did NOT confabulate a "branch diff" CLI subcommand, a
```
migration revalidate
```
step, or any other API the skill above doesn't reference.

prisma-next-migration-review

NPX Install

Tags

SKILL.md Content

Prisma Next — Migration Review (Deployment + Concurrency)

When to Use

When Not to Use

Key Concepts — the navigation model

Origin

Destination

The migration graph

Diagnostic codes

Workflow — "What's about to run on deploy?"

Workflow — "What state is each environment at?"

Concept — concurrent migrations on the same branch point

Workflow — set, list, get, delete refs

Workflow — apply a migration against an environment

Concept — ref-mismatch on CI / deploy

Workflow — CI: verify a branch can advance the target environment

Common Pitfalls

What Prisma Next doesn't do yet

Reference Files

Checklist