docs(docs): contract references after prisma/orm#30475

[wmadden-electric]

The table "Contract references each command accepts" in apps/docs/content/docs/orm/migrations/the-migration-graph.mdx, before:

Command and option	Accepts
migration status --from, --to	a hash, a hash prefix, a ref name, a migration directory name, <dir>^, or @empty
db migrate --to	a hash, a hash prefix, a ref name, a migration directory name, or <dir>^
db migrate --show --to	a hash, a hash prefix, a ref name, a migration directory name, <dir>^, @contract, or @empty
db migrate --show --from	a hash, a hash prefix, a ref name, a migration directory name, <dir>^, @contract, @db, or @empty

After:

Command and option	Accepts
migration status --from, --to	a hash, a hash prefix, a ref name, a migration directory name, <dir>^, @contract, @db, or @empty
db migrate --to	a hash, a hash prefix, a ref name, a migration directory name, <dir>^, @contract, or @db
db migrate --show --from, --to	a hash, a hash prefix, a ref name, a migration directory name, <dir>^, @contract, @db, or @empty

The two db migrate --show rows now list the same forms, so they are one row. The other rows do not change.

Do not merge this until a published prisma release contains prisma/orm#30475. Today's release rejects or mishandles these forms, so the new rows would be wrong.

This pull request is stacked on #8348, which adds the table. Its base is #8348's branch. When #8348 merges, change the base to main.

What changes

prisma/orm#30475 changes which contract references three commands accept:

• migration status --from and --to accept @contract and @db. @db needs a database connection, even with --from.
• db migrate --to accepts @contract and @db, with and without --show.
• db update --to refuses @contract, @db, and @empty with MIGRATION.REF_WRONG_GRAMMAR. Before, @empty and @db crashed with CLI.UNEXPECTED.

The pages change to match:

• orm/migrations/the-migration-graph.mdx: the three table rows above.
• cli/migration-status.mdx: the --to row lists @contract and @db. The --from row and the paragraph under "Reading the result" say that @db needs a database. The "Contract references" subsection defines @contract and @db.
• cli/db-migrate.mdx: the --to row lists @contract and @db, and @empty with --show only.
• cli/db-update.mdx: the --to row says it refuses the three @ names, and that leaving out --to updates to the contract in contract.json.

How this was checked

Every cell was run on the pull request's head, prisma/orm 20615a96f0, with the workspace CLI (packages/1-framework/3-tooling/cli/dist/bin.mjs) and PostgreSQL 15. No cell comes from tests alone. The project had two migrations: a baseline, then one that adds a column. The database was at the baseline and the emitted contract was one migration ahead.

Command	@contract	@db	@empty	./path (3 forms)
migration status --to	ok, 1 pending	ok, up to date	ok	MIGRATION.REF_NOT_FOUND
migration status --from	ok, offline	ok, 1 pending; CONFIG.DB_CONNECTION_REQUIRED with no database	ok	MIGRATION.REF_NOT_FOUND
db migrate --to	ok, applies the pending migration	ok, already up to date	fails on every database (see below)	MIGRATION.REF_NOT_FOUND
db migrate --show --to	ok	ok, nothing to run	ok on an empty database	MIGRATION.REF_NOT_FOUND
db update --to, with and without --dry-run	MIGRATION.REF_WRONG_GRAMMAR	MIGRATION.REF_WRONG_GRAMMAR	MIGRATION.REF_WRONG_GRAMMAR	MIGRATION.REF_NOT_FOUND

db migrate --to @empty is not listed. The help text lists it, but no run succeeds: on an empty database it fails with MIGRATION.RUNNER_FAILED, and on any other database with MIGRATION.PATH_UNREACHABLE. db migrate --to @db on a database with no marker fails with MIGRATION.RUNNER_FAILED in the same way. On a database with a marker it works.

Re-check on the release

When a prisma release contains prisma/orm#30475, run these in a scratch project and PostgreSQL before marking this ready. Set up two migrations (baseline to H1, then H1 to H2), emit the contract at H2, point prisma.config.ts at a database at H1, and make a second config with no db.connection.

npx prisma migration status --to @contract           # ⚠ 1 pending
npx prisma migration status --from @contract         # ✔ Up to date, no database line
npx prisma migration status --to @db                 # ✔ Up to date
npx prisma migration status --from @db               # ⚠ 1 pending, baseline ✓ applied
npx prisma migration status --from @db --config prisma.nodb.config.ts   # CONFIG.DB_CONNECTION_REQUIRED
npx prisma db migrate --to @contract --db <db at H1>    # Applied 1 migration
npx prisma db migrate --to @db --db <db at H1>          # Already up to date
npx prisma db migrate --to @empty --db <db at H1>       # MIGRATION.PATH_UNREACHABLE
npx prisma db migrate --show --to @db                # Already up to date, nothing to run
npx prisma db migrate --show --to @contract          # 1 migration will run
npx prisma db migrate --show --from @empty --to @db  # 1 migration will run
npx prisma db update --dry-run --to @contract        # MIGRATION.REF_WRONG_GRAMMAR
npx prisma db update --dry-run --to @db              # MIGRATION.REF_WRONG_GRAMMAR
npx prisma db update --dry-run --to @empty           # MIGRATION.REF_WRONG_GRAMMAR
# each of these must still fail with MIGRATION.REF_NOT_FOUND:
npx prisma migration status --to ./migrations/app/<baseline dir>
npx prisma migration status --from ./src/prisma/contract.json
npx prisma db migrate --to ./migrations/app/<baseline dir> --db <db at H1>
npx prisma db migrate --show --to ./src/prisma/contract.json
npx prisma db update --dry-run --to ./src/prisma/contract.json
npx prisma db sign --contract ./src/prisma/contract.json --db <db at H1>
npx prisma migration plan --from ./migrations/app/<baseline dir> --name t

If db migrate --to @empty succeeds on the release, add @empty to the db migrate --to row.

Checks run on the changed pages: check-plain.sh, check-staccato.py, check-ai-signs.sh, fumadocs-mdx, pnpm lint:links, and cspell. All pass.

Agent: columbo-92
🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
blog	Ready	Preview	Sep 30, 2026 3:24pm UTC
docs	Ready	Preview	Sep 30, 2026 3:24pm UTC
eclipse	Ready	Preview	Sep 30, 2026 3:24pm UTC
handbook	Ready	Preview	Sep 30, 2026 3:24pm UTC
site	Ready	Preview	Sep 30, 2026 3:24pm UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🍈 Lychee Link Check Report

76 links: ✅ 0 OK | 🚫 0 errors | 🔀 0 redirects | 👻 76 excluded

✅ All links are working!

---

Full Statistics Table

Status	Count
✅ Successful	0
🔀 Redirected	0
👻 Excluded	76
🚫 Errors	0
⛔ Unsupported	0
⏳ Timeouts	0
❓ Unknown	0