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 ref manages named refs stored in migrations/refs.json. A ref is a named pointer to a contract hash — analogous to a git ref — that lets you label specific points in the migration graph with meaningful names like staging or production. Commands such as migration apply --ref and migration status --ref use these refs to target a specific graph position rather than always advancing to the latest contract hash. This makes it straightforward to operate staging and production databases that track different points in the same migration history.

​
Subcommands

​
ref set

Assign a contract hash to a named ref. Creates the ref if it does not exist; updates it if it does. 
prisma-next migration ref set <name> <hash>

prisma-next migration ref set staging sha256:bbb2abc...
prisma-next migration ref set prod/us-east sha256:aaa1def...
​
name
string
required
The ref name to create or update. Must be lowercase alphanumeric with hyphens or forward slashes (e.g., staging, prod/us-east). No . or .. path segments are allowed.
​
hash
string
required
The contract hash to assign. Must be a valid sha256:<64 hex chars> hash or the special value sha256:empty.
​
--config
string
Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts.
​
--json
boolean
Emit a machine-readable JSON envelope.
​
-q
boolean
Quiet mode — suppresses all output except errors.

​
ref get

Print the hash that a named ref currently points to. 
prisma-next migration ref get <name>

prisma-next migration ref get staging
​
name
string
required
The ref name to look up.
​
--config
string
Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts.
​
--json
boolean
Emit a machine-readable JSON envelope.
​
-q
boolean
Quiet mode — suppresses all output except errors.

​
ref delete

Remove a named ref from refs.json. Has no effect on the migration packages or the database. 
prisma-next migration ref delete <name>

prisma-next migration ref delete old-staging
​
name
string
required
The ref name to delete.
​
--config
string
Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts.
​
--json
boolean
Emit a machine-readable JSON envelope.
​
-q
boolean
Quiet mode — suppresses all output except errors.

​
ref list

List all refs currently stored in migrations/refs.json. 
prisma-next migration ref list
​
--config
string
Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts.
​
--json
boolean
Emit a machine-readable JSON envelope.
​
-q
boolean
Quiet mode — suppresses all output except errors.

​
Ref naming rules

Ref names must match the pattern: lowercase alphanumeric characters, hyphens (-), and forward slashes (/). Forward slashes allow hierarchical names for multi-region or multi-tier environments. Valid names: 
staging
production
prod/us-east
prod/eu-west
feature/my-branch
Invalid names (will be rejected): 
Staging          # uppercase letters
my_env           # underscore
../escape        # path traversal (..)
env.name         # dot segment

​
Ref value format

All ref values must be valid contract hashes in the form sha256:<64 hex chars>, or the special value sha256:empty (used for the initial state before any migration has been applied). 
sha256:abc123def456...  ← 64 hex chars after the prefix
sha256:empty            ← valid for the initial state

​
Atomic writes

refs.json is written atomically via a temp file followed by a rename. This prevents refs.json from being observed in a partially-written state if a concurrent write or process interruption occurs.

​
Multi-environment workflow

The typical pattern is to keep refs aligned with your deployment pipeline. After validating migrations in staging, update the staging ref to the new hash, then later advance production once the release is confirmed.
1

Plan and apply to staging

Run migration plan and then apply to staging:
prisma-next migration plan --name add-new-table
prisma-next migration apply --db $STAGING_DATABASE_URL
2

Advance the staging ref

Record the new state for staging in refs.json:
prisma-next migration ref set staging sha256:ccc3abc...
Commit migrations/refs.json to version control alongside the new migration packages.
3

Check production status

Verify how far production is behind:
prisma-next migration status --ref production --db $PROD_DATABASE_URL
4

Apply to production and advance the ref

Once the release is approved, apply migrations and update the production ref:
prisma-next migration apply --ref production --db $PROD_DATABASE_URL
prisma-next migration ref set production sha256:ccc3abc...
Store migrations/refs.json in version control. It is a plain JSON file and merges cleanly when different branches update different ref names.

​
refs.json format

{
  "staging": "sha256:bbb2abc...",
  "production": "sha256:aaa1def...",
  "prod/us-east": "sha256:aaa1def...",
  "prod/eu-west": "sha256:aaa0ccc..."
}

​
JSON output examples

ref set: 
{
  "ok": true,
  "name": "staging",
  "hash": "sha256:bbb2abc...",
  "action": "updated"
}
ref list: 
{
  "ok": true,
  "refs": {
    "staging": "sha256:bbb2abc...",
    "production": "sha256:aaa1def..."
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us