Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/prisma/prisma-next/llms.txt

Use this file to discover all available pages before exploring further.

prisma-next migration status shows the full migration graph and, when given a database connection, marks which migrations have been applied and which are still pending. Without a database connection the command works entirely offline, rendering the graph structure from disk. All named refs stored in migrations/refs.json are overlaid on the graph regardless of mode, giving you a complete picture of where each environment sits relative to the migration history.

​
Options

​
--db
string
Database connection string. When provided, the command enters online mode: it reads the current database marker and shows applied/pending status. Defaults to config.db.connection if set.
​
--ref
string
Target a named ref from migrations/refs.json instead of the contract hash. The active ref is highlighted in bold; other refs are dimmed. In ref mode, the CONTRACT.AHEAD warning is suppressed.
​
--config
string
Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts in the current working directory.
​
--json
boolean
Emit a machine-readable JSON envelope instead of the default TTY output.
​
-q
boolean
Quiet mode — suppresses all output except errors.
​
-v
boolean
Verbose output — includes additional graph metadata and timings.

​
Online vs offline mode

migration status adapts its output based on whether a database connection is available. Without --db (offline mode): Reads migration packages from disk and renders the graph structure. Useful for reviewing migration history in CI or on machines without database access. Contract and ref markers are still shown. With --db (online mode): Connects to the database, reads the current marker hash, and annotates the graph with applied/pending status. Shows the distance from the current database position to the ref or contract target (e.g., “2 edge(s) behind ref”).

​
Graph display markers

The graph uses the following inline markers to show context at each node:
MarkerMeaning
◄ DBThe node where the database’s current marker points.
◄ ContractThe node corresponding to the current contract.json hash.
◄ ref:<name>The node a named ref points to.
Each migration edge also shows a summary of its operation count and, when the migration contains destructive operations, a highlighted warning. Example output (online mode): 
prisma-next migration status ➜ View migration graph
  config:     prisma-next.config.ts
  migrations: migrations/
  db:         postgresql://localhost/mydb

Migration graph

  sha256:0000...  (initial)
  │
  ├─ 20240110-init          sha256:aaa1...  [3 ops, additive]
  │                                         ◄ ref:production
  │
  ├─ 20240115-add-roles     sha256:bbb2...  [2 ops, additive]
  │                                         ◄ DB  ◄ ref:staging
  │
  └─ 20240120-backfill      sha256:ccc3...  [1 op, additive]
                                            ◄ Contract

1 pending migration(s) — 1 edge(s) behind contract

​
Branched graphs and AMBIGUOUS_TARGET

When the migration graph has multiple branches (two or more migrations share the same starting contract hash), the command cannot automatically determine a single target without additional guidance: 
✖ AMBIGUOUS_TARGET
  The migration graph has diverged at sha256:aaa1...
  Branch A: 20240115-add-roles  →  sha256:bbb2...
  Branch B: 20240115-add-cols   →  sha256:bbb3...

  Use --ref <name> to target a specific branch.
Resolve ambiguity by using --ref to point status at a named ref that sits on a specific branch, or by running migration ref set to assign refs to each branch.

​
Ref mode and CONTRACT.AHEAD suppression

When --ref is provided, the command uses the ref’s hash as the target instead of the contract hash. This suppresses the CONTRACT.AHEAD warning that would otherwise appear when contract.json is ahead of the ref target — in multi-environment workflows, the contract being ahead of a ref is expected and not an error. 
# Check staging's status without CONTRACT.AHEAD noise
prisma-next migration status --ref staging
The active ref is rendered in bold in the graph; other refs are dimmed to keep the focus on the environment you are inspecting.

​
Examples

prisma-next migration status

​
JSON output format

{
  "ok": true,
  "mode": "online",
  "graph": {
    "nodes": [
      { "hash": "sha256:0000...", "label": "initial" },
      { "hash": "sha256:aaa1...", "label": "20240110-init", "applied": true, "refs": ["production"] },
      { "hash": "sha256:bbb2...", "label": "20240115-add-roles", "applied": true, "refs": ["staging"], "isDB": true },
      { "hash": "sha256:ccc3...", "label": "20240120-backfill", "applied": false, "isContract": true }
    ]
  },
  "pending": 1,
  "db": { "current": "sha256:bbb2..." },
  "contract": { "hash": "sha256:ccc3..." },
  "timings": { "total": 88 }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us