Skip to main content
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.
​
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.
​
string
required
The contract hash to assign. Must be a valid sha256:<64 hex chars> hash or the special value sha256:empty.
​
string
Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts.
​
boolean
Emit a machine-readable JSON envelope.
​
boolean
Quiet mode — suppresses all output except errors.

​
ref get

Print the hash that a named ref currently points to.
​
string
required
The ref name to look up.
​
string
Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts.
​
boolean
Emit a machine-readable JSON envelope.
​
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.
​
string
required
The ref name to delete.
​
string
Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts.
​
boolean
Emit a machine-readable JSON envelope.
​
boolean
Quiet mode — suppresses all output except errors.

​
ref list

List all refs currently stored in migrations/refs.json.
​
string
Path to prisma-next.config.ts. Defaults to ./prisma-next.config.ts.
​
boolean
Emit a machine-readable JSON envelope.
​
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:
Invalid names (will be rejected):

​
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).

​
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:
2

Advance the staging ref

Record the new state for staging in refs.json:
Commit migrations/refs.json to version control alongside the new migration packages.
3

Check production status

Verify how far production is behind:
4

Apply to production and advance the ref

Once the release is approved, apply migrations and update the production ref:
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

​
JSON output examples

ref set:
ref list: