prisma-next-migration-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prisma Next — Migration Review (Deployment + Concurrency)

Prisma Next — 迁移审核（部署与并发）

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.

编辑你的数据契约，其余工作由Prisma处理。

本技能聚焦于迁移的审核，而非迁移的编写。它涵盖了部署阶段以及多名开发者同时提交迁移时会遇到的各类问题。

本技能会教授系统的心智模型——什么是ref、什么是marker、什么是迁移图谱，并展示如何查询系统状态。它不会规定僵化的分步流程：大多数“审核”问题都可以通过理解模型并执行正确的查询来解决。只有在极少数存在唯一安全路径的情况下，才会使用固定流程。

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.

用户询问“合并此分支后会运行哪些迁移？”或“部署时将要运行什么？”
用户遇到并发迁移冲突（
```
main
```
分支在其分支开发期间已更新）
用户希望配置
```
staging
```
/
```
production
```
ref，以便CI可以针对其进行部署
用户希望针对非本地开发数据库的环境运行迁移
用户询问迁移的CI集成相关问题

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
```
.

用户想要编写迁移 → 使用
```
prisma-next-migrations
```
用户想要修复单个环境中的哈希不匹配/漂移 → 使用
```
prisma-next-migrations
```
（重新规划路径）或
```
prisma-next-debug
```
（信封驱动）
用户想要编辑契约 → 使用
```
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

起点（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.

起点是数据库当前的契约哈希值。数据库在PN的marker表中存储了一行记录，标记着“此数据库处于哈希X状态”。当CLI在线运行（提供

--db <url>

或在

prisma-next.config.ts

中设置

db.connection

）时，PN会读取该marker，对应的哈希值即为起点。离线运行（无数据库连接）时，起点未知——许多命令会退化为列出磁盘上的迁移，并跳过每个迁移的已应用/待处理状态。

因此，实时数据库是起点的权威来源。其他任何工件（refs、本地缓存、你的假设）中的“记录marker”都是可能发生漂移的副本，而实时数据库永远不会漂移。

Destination

终点（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.

终点是你希望数据库达到的契约哈希值。有两种方式指定终点：

--ref <name>
——指向哈希值的命名指针，存储在
```
migrations/app/refs/<name>
```
下。按照惯例，refs以环境命名（
```
staging
```
、
```
production
```
），用于传达“这是生产环境预期的状态”。ref本身只是一个哈希值加上一组可选的必需约束，与你连接的数据库无关。
当前契约头——未传递
```
--ref
```
时默认使用，即磁盘上当前
```
contract.json
```
的哈希值。

--ref staging

并不意味着“连接到预发布数据库”，而是意味着“将我连接的数据库（通过

--db

或配置指定）导航到该ref指向的哈希值”。数据库选择是独立的：需传递

--db $STAGING_DATABASE_URL

才能实际指向预发布环境。

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.

磁盘上的迁移构成一个有向图：节点是契约哈希值；边是迁移。每个迁移都声明了

from

哈希值和

to

哈希值。只有当数据库当前的marker与迁移的

from

哈希值匹配时，该迁移才能被应用；运行迁移后，marker会更新为其

to

哈希值。

migration status

会查询从起点到终点的路径，并报告每条边的状态：

applied（已应用）——位于从
```
EMPTY_CONTRACT_HASH
```
到marker的路径上（历史记录）
pending（待处理）——位于从marker到终点的路径上（即将运行的内容）
unreachable（不可达）——位于从
```
EMPTY_CONTRACT_HASH
```
到终点的路径上，但marker位于不同分支，若不重新路由则无法到达终点

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.

migration status

会在结果信封（

diagnostics[].code

）中输出结构化诊断信息，以便Agent根据代码进行分支处理，而非解析文本摘要。每个诊断信息还包含

severity

（

warn

或

info

）、人类可读的

message

以及

hints

——与CLI在摘要行下方打印的提示信息一致。

代码	级别	导航模型中的含义	下一步操作
`MIGRATION.UP_TO_DATE`	info	Marker与终点一致；无需执行任何迁移	无需操作
`MIGRATION.DATABASE_BEHIND`	info	Marker是终点的祖先；两者之间有N个待处理迁移	执行 `migrate --to <name> --db $URL`
`MIGRATION.INVARIANTS_PENDING`	info	Marker在结构上已到达终点，但缺少ref声明的必需约束	执行 `migrate --to <name> --db $URL` 以覆盖这些约束
`MIGRATION.NO_MARKER`	warn	在线状态，但数据库无marker行——从未初始化	执行 `migrate --db $URL` （首次应用会写入marker）
`MIGRATION.MARKER_NOT_IN_HISTORY`	warn	在线状态；marker哈希值不在图谱节点中。数据库在迁移系统外被修改	确定哪一方为真相： `db sign` （接受数据库为真相）、 `db update` （将契约推送到数据库）、 `contract infer` （从数据库重新推导契约）或 `db verify` （先检查）
`MIGRATION.DIVERGED`	warn	存在多个有效分支；终点不明确	传递 `--to <name>` ，或执行 `ref set <name> <hash>` 创建一个ref
`CONTRACT.AHEAD`	warn	契约头不在图谱中——契约已被编辑但未重新规划	执行 `migration plan` 扩展图谱
`CONTRACT.UNREADABLE`	warn	无法读取 `contract.json`	执行 `contract emit` 重新生成

CI网关应读取

--json

输出中的

diagnostics

，并根据

severity

和

code

做出决策；请参阅下方“工作流——CI”的结构。

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.

用户询问：“我即将合并此PR。部署到预发布环境时会运行哪些迁移？”

这是一个导航问题：起点=预发布环境的实时marker；终点=ref

staging

（若未设置则为契约头）。向系统查询：

bash

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

该命令：

读取预发布数据库的marker（起点）
将
```
staging
```
解析为契约哈希值（终点）
将两者之间的路径渲染为有序迁移列表，每条边标记
```
applied
```
/
```
pending
```
/
```
unreachable
```
状态，并输出明确的摘要行，格式为“落后于ref 'staging' N个迁移”
打印包含配置、迁移目录、活动ref和数据库连接（已掩码）的头部信息——以便在输出中清晰看到上下文

如果省略

--db

，命令将离线运行：它会列出磁盘上的迁移，但无法告知哪些已应用，因为没有起点。这适用于“此分支上有什么迁移？”的问题，但不适用于“预发布环境即将运行什么？”——后者需要预发布环境的实时marker。

如果省略

--ref

，终点默认是契约头——这回答的是“此分支的契约是否可从数据库到达，以及如何到达？”，而非“部署时会运行什么”。当问题涉及特定环境时，请显式传递ref。

migration status

会按类别（

additive

、

widening

、

data

、

destructive

）总结每个待处理迁移的操作，并在存在破坏性操作时报告其数量。在用户合并或部署前，应向其展示该数量——破坏性操作是需要手动审核的类别。

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.

只需对每个环境的数据库执行

migration status --db $URL

即可。marker（起点）直接来自数据库本身；摘要行会告知你该环境是处于契约头、命名ref、超前于契约头还是处于分歧分支。

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.

在某些PN文档中，这曾被称为菱形收敛；无论标签如何，场景都是相同的。

发生的情况：两个主题分支均基于同一个父契约哈希值编写了迁移。第一个分支合并到

main

；目标ref（如

production

）更新为该分支的

to

哈希值。你的分支的迁移仍将

from

哈希值指向旧的父节点。重新基址后，迁移图谱不再有通过你的迁移的清晰路径：

你的迁移的
```
from
```
不再是新分支头的祖先
或者你的迁移的
```
from
```
可达，但通过你的迁移到达的哈希值并非两个分支变更的并集

无论哪种情况，磁盘上的规划都已过时。

解决方案：磁盘上的规划过时是因为其

from

哈希值不再是图谱的分支头；对重新基址后的状态应用集群标准的编辑→规划→应用循环，规划器会生成一个新的迁移，其

from

与新分支头匹配。

规划器无法为你完成的一件事是将废弃的

migration.ts

中的自定义数据转换逻辑移植到新迁移中——模式差异是从契约推导而来，但任何手写的

data

操作都需要你在应用前自行迁移。没有单独的“重新验证”步骤，也没有特殊的“菱形应用”流程。

Workflow — set, list, get, delete refs

工作流——设置、列出、获取、删除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

refs是小型工件。没有每个环境的生命周期；只需将名称指向哈希值即可。

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

ref get

已被移除——使用

ref list

并按名称过滤

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.

pnpm prisma-next ref list | grep production pnpm prisma-next ref delete production


`ref set`会在`migrations/app/refs/<name>`写入一个包含哈希值和任何必需约束的文件。refs是适合提交的工件——将其保存在git中；团队就`production`指向的内容达成一致，就像他们就`main`分支的内容达成一致一样。

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.

bash

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

终点是ref的哈希值；起点是生产数据库的实时marker。该命令会计算两者之间的路径，并按顺序应用每个待处理迁移，更新marker。

--db

是环境选择的控制项。

--ref

是终点哈希值的控制项。它们是独立的。

Concept — ref-mismatch on CI / deploy

概念——CI/部署时的ref不匹配

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.

CI报告：“记录的ref

production

处于哈希X；实时数据库处于哈希Y。”

不匹配是两种状态不一致的事实。无论哪一方出错，调查流程都是相同的：

数据库超前于ref：有人在CI外应用了迁移，但未更新git中的ref。使用
```
prisma-next ref set <ref-name> <db-marker-hash>
```
重新记录ref（提交并推送）；然后审核该非预期应用是如何发生的。
数据库落后于ref：之前的部署被回滚，或者数据库从旧备份恢复。可以选择执行
```
prisma-next migrate --to <ref-name> --db $URL
```
向前重新应用，或者执行
```
prisma-next ref set <ref-name> <db-marker-hash>
```
将ref重新路由到实际部署的状态。选择权在用户手中——请列出这两个选项。
数据库位于不同分支：非预期的模式变更（手动SQL、临时迁移）写入了迁移图谱未建模的内容。运行
```
prisma-next db verify
```
检查漂移，然后选择执行
```
prisma-next contract infer
```
从数据库重新推导契约，或编辑契约并运行
```
prisma-next migration plan
```
使数据库最终到达目标状态。

使用

ref set

静默对齐ref与当前数据库状态几乎永远不是正确的做法。这会掩盖你以后需要付出代价的漂移问题。

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

工作流——CI：验证分支能否推进目标环境

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.

网关是

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

：它计算从实时marker到ref的路径并报告，不会修改任何内容。

migrate

没有

--dry-run

标志；检查/网关步骤是

migration status

。

yaml

- name: 验证预发布环境可达
  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("阻塞性诊断信息:", warns);
        process.exit(1);
      }
    '
- name: 应用迁移
  run: pnpm prisma-next migrate --to staging --db "$STAGING_DATABASE_URL"

migration status

仅在出现严重错误（无法读取迁移目录、无法满足约束、无法重建历史）时才会返回非零退出码。

MIGRATION.MARKER_NOT_IN_HISTORY

、

MIGRATION.DIVERGED

、

CONTRACT.AHEAD

和

MIGRATION.NO_MARKER

等诊断信息会在结果信封中以

severity: 'warn'

报告，但进程会返回

——Agent（或CI网关）必须检查

diagnostics[]

并自行终止构建。使用

--json

以便网关解析结构化数据，而非人类可读的摘要。

migrate

无需交互，也没有破坏性操作确认提示——提示破坏性更改的安全防护在

db update

上（请参阅

prisma-next-migrations

技能）。规划器在迁移图谱中放入的内容就是

migrate

将运行的内容；审核在

migration plan

和

migration status

阶段进行，在应用步骤之前。

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.

针对部署问题读取
migration status
时未传递
--ref
：这询问的是“此分支的契约能否到达分支头？”，而非“预发布环境即将运行什么？”。当问题涉及特定环境时，请始终传递ref。
针对部署问题读取
migration status
时未传递
--db
：没有实时数据库，就没有起点。输出仅列出磁盘上的内容；无法说明环境中已应用的迁移。对于任何高风险问题，请传递
```
--db $URL
```
。
混淆ref与数据库连接：
```
--ref staging
```
选择的是终点哈希值，而非数据库。请显式传递
```
--ref
```
和
```
--db
```
。
将菱形收敛视为特殊流程：它不是。这只是对重新基址后的状态应用常规的编辑→规划→应用循环。唯一的额外步骤是“将旧
```
migration.ts
```
中的任何数据转换逻辑移植过来”。
在未理解原因的情况下运行
ref set
以消除CI不匹配：这可能掩盖非预期变更或回滚漂移。请先调查原因。

What Prisma Next doesn't do yet

Prisma Next目前尚未支持的功能

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.

默认链之外的每个环境迁移排序：如果需要预发布环境跳过生产环境需要的迁移（反之亦然），支持的方式是将每个环境的差异编写为单独的迁移，并在部署脚本中进行控制。如果需要一流的每个环境路由，请通过
```
prisma-next-feedback
```
技能提交功能请求。
内置的并排“分支差异”视图：有完整的图谱渲染（
```
migration graph
```
）显示分支，但没有类似
```
git diff
```
的两个分支迁移集比较视图。解决方法：在每个分支上运行
```
migration status
```
并对比输出。如果需要内置的分支比较视图，请通过
```
prisma-next-feedback
```
技能提交功能请求。

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.

本技能仅包含主体内容；底层CLI参考（

prisma-next migration status --help

、

migrate --help

、

ref --help

）是标志级细节的权威来源。如有疑问，请运行

--help

并阅读实际命令的描述，而非根据本技能猜测。

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.

为用户的问题明确了起点（实时数据库marker）和终点（ref或契约头）
每当问题涉及特定环境时，都传递了
```
--db $URL
```
每当问题是关于部署到命名环境（而非仅从当前分支头部署）时，都传递了
```
--ref <name>
```
在读取每条边的列表之前，先读取
```
migration status
```
的头部（它会命名配置、ref、数据库）和摘要行（它会命名起点/终点的差距）
对于并发迁移冲突：重新应用核心工作流（编辑→规划→应用），而非遵循记忆中的“菱形收敛”流程。将旧
```
migration.ts
```
中的任何数据转换逻辑移植过来
对于ref不匹配：调查哪一方状态出错（数据库超前、数据库落后、数据库位于分歧分支）。未使用
```
ref set
```
消除不匹配
在用户合并或部署前，展示了
```
migration status
```
中的破坏性操作数量（这是部署前需要手动审核的唯一操作类别）
在CI中：解析
```
migration status --json
```
的
```
diagnostics[]
```
并根据
```
severity === 'warn'
```
进行控制；未依赖
```
migrate
```
的
```
--dry-run
```
标志（不存在该标志）
未混淆
```
--ref
```
与数据库选择
未虚构“分支差异”CLI子命令、
```
migration revalidate
```
步骤或本技能未提及的任何其他API

prisma-next-migration-review

Original

Translation

Prisma Next — Migration Review (Deployment + Concurrency)

Prisma Next — 迁移审核（部署与并发）

When to Use

适用场景

When Not to Use

不适用场景

Key Concepts — the navigation model

核心概念——导航模型

Origin

起点（Origin）

Destination

终点（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

工作流——设置、列出、获取、删除refs

ref get was removed — use ref list and filter by name

ref get已被移除——使用ref list并按名称过滤

Workflow — apply a migration against an environment

工作流——针对环境应用迁移

Concept — ref-mismatch on CI / deploy

概念——CI/部署时的ref不匹配

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

工作流——CI：验证分支能否推进目标环境

Common Pitfalls

常见陷阱

What Prisma Next doesn't do yet

Prisma Next目前尚未支持的功能

Reference Files

参考文件

Checklist

检查清单

`ref get`
was removed — use
`ref list`
and filter by name

`ref get`
已被移除——使用
`ref list`
并按名称过滤