Prisma Next Migration Review

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 `--to <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 --to is passed. This is the hash of the current contract.json on disk.

--to 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 or info), a human message, and hints — the same hints the CLI prints under the summary line.

Graph-tree output

migration status (and migration list) render the migration graph as a colored lane tree in the terminal. Two flags control the rendering:

• --legend — prints the key for the tree glyphs and lane colors before the tree.
• --ascii — replaces box-drawing glyphs with pipe-safe ASCII characters (useful in CI logs or environments that don't support Unicode).

Both flags are also available on migration list and migration graph. migration log supports --ascii only (it renders a flat chronological table, not a tree).

Plan- and apply-time diagnostics

These codes surface on migration plan, ref set, and migrate — not on migration status. See Migration System § Recovery affordances and ADR 218.