docs: add Prisma Next Migrations section#8025
Merged
Merged
Conversation
Six pages under /docs/orm/next/migrations covering the full migration workflow: how migrations work, the migration graph, generating, editing, applying, and rollbacks/recovery. All commands, file layouts, and CLI outputs verified against prisma-next origin/main by running the flows end-to-end (plan, placeholder backfill, self-emit, apply, status, log, rollback, failure/atomicity behavior). Adds three ConceptAnimation presets (migration-loop, migration-graph, migration-rollback), temporary redirects from the Prisma 7 migrate pages that have clean equivalents, and cspell entries for migration terms. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThis PR adds Prisma Next migration documentation pages for the migration model, graph, generation, editing, applying, and rollback flows, plus navigation metadata, redirects, spelling entries, a homepage link update, and new migration-themed concept animation presets. ChangesMigrations documentation pages and support
Estimated code review effort: 3 (Moderate) | ~25 minutes Migration concept presets
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Poem 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
Contributor
🍈 Lychee Link Check Report77 links: ✅ All links are working!Full Statistics Table
|
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
Fresh-eyes review as two personas (newcomer, evaluating expert); applied the top findings: define contract/emit/marker/attestation on first use, explain operation classes, de-jargon codecRef, standardize on "migration directory", fix a timestamp inconsistency, and stabilize the db-ref heading anchor. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
apps/docs/src/components/concept-animation/flow-presets.ts (1)
1-1: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueIntentional decoupling looks fine — one thing to watch.
Dropping the
Partial<Record<ConceptName, FlowScene>>constraint in favor ofRecord<string, FlowScene>is the right move to letFlowNamestand on its own, but it also removes the compile-time guarantee thatFLOW_SCENESkeys line up with anything meaningful — a typo'd key now silently becomes a new validFlowNameinstead of a type error. GivenFlowNameis consumed directly inConceptAnimation's prop union (apps/docs/src/components/concept-animation/index.tsx), that's a low-risk trade-off worth being aware of, not a blocker.Also applies to: 529-531
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@apps/docs/src/components/concept-animation/flow-presets.ts` at line 1, `FLOW_SCENES` is now typed too loosely with `Record<string, FlowScene>`, so typoed keys can silently create new `FlowName` values instead of failing at compile time. Update the `flow-presets` typing to keep a meaningful key union tied to the scene map, and make sure the `FlowName` prop union used by `ConceptAnimation` still derives from that constrained source rather than arbitrary strings.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/docs/content/docs/orm/next/migrations/editing-a-migration.mdx`:
- Around line 64-85: The migration example is assigning the deserialized
contract to endContractJson, but the docs expect the raw JSON snapshot there. In
the editing-a-migration example, keep endContract for the typed db setup and
change M’s endContractJson override to use the imported end-contract.json value
instead of the deserialized contract, so it stays consistent with
startContractJson and the rest of the migration docs.
In `@apps/docs/src/components/concept-animation/index.tsx`:
- Around line 15-21: `ConceptAnimation` currently resolves `FLOW_SCENES` before
`CONCEPT_PRESETS`, so overlapping names like `compute-model`, `env-layers`, and
`github-connection` always render the flow scene instead of the concept preset.
Update the lookup logic in `ConceptAnimation` to either remove the duplicate
concept entries if the overlap is intended, or make the naming sets disjoint /
add an explicit collision check so `FLOW_SCENES` and `CONCEPT_PRESETS` cannot
silently shadow each other.
---
Nitpick comments:
In `@apps/docs/src/components/concept-animation/flow-presets.ts`:
- Line 1: `FLOW_SCENES` is now typed too loosely with `Record<string,
FlowScene>`, so typoed keys can silently create new `FlowName` values instead of
failing at compile time. Update the `flow-presets` typing to keep a meaningful
key union tied to the scene map, and make sure the `FlowName` prop union used by
`ConceptAnimation` still derives from that constrained source rather than
arbitrary strings.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 60f7194f-ed2a-4b3c-8d3d-6fc56fa800e1
📒 Files selected for processing (14)
.claude/launch.jsonapps/docs/content/docs/orm/next/meta.jsonapps/docs/content/docs/orm/next/migrations/applying-a-migration.mdxapps/docs/content/docs/orm/next/migrations/editing-a-migration.mdxapps/docs/content/docs/orm/next/migrations/generating-a-migration.mdxapps/docs/content/docs/orm/next/migrations/how-migrations-work.mdxapps/docs/content/docs/orm/next/migrations/meta.jsonapps/docs/content/docs/orm/next/migrations/rollbacks-and-recovery.mdxapps/docs/content/docs/orm/next/migrations/the-migration-graph.mdxapps/docs/cspell.jsonapps/docs/next.config.mjsapps/docs/src/components/concept-animation/flow-presets.tsapps/docs/src/components/concept-animation/index.tsxapps/docs/src/components/concept-animation/presets.ts
Verified every runnable example against prisma-next origin/main (remaining fixtures, ref list, migrate --show, hash-prefix targeting, db verify, migration new, the rawSql sample compiled in a real scaffold). Two fixes from verification: softened the db verify claim to match its actual output, and added the real migrate --show path preview. Full review per house docs style: removed prose em dashes and filler, standardized terminology, added a MongoDB data-transform section with a link to the working retail-store example, moved the wiring-ceremony note next to the code it excuses, consolidated CI guidance (commit both files, check exit codes), and linked the db-ref explanation to one canonical home. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
apps/docs/content/docs/orm/next/migrations/rollbacks-and-recovery.mdx (1)
23-28: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winSwitch these command snippets to
npmfences.
Thesebashblocks bypass the tabbed package-manager rendering used elsewhere inapps/docs/content. Based on learnings, this docs subtree should use a singlenpmfenced code block so the tooling can expand it automatically.Also applies to: 48-50
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@apps/docs/content/docs/orm/next/migrations/rollbacks-and-recovery.mdx` around lines 23 - 28, The migration rollback snippets are using generic bash fences, which prevents the docs tooling from rendering the package-manager tabs consistently. Update the affected code blocks in the rollback/recovery MDX document to use the npm fence style instead of bash, keeping the existing command content intact; use the surrounding docs patterns in apps/docs/content and the migration section as the reference for the correct fenced block format.Source: Learnings
apps/docs/content/docs/orm/next/migrations/applying-a-migration.mdx (1)
42-51: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winSwitch these command snippets to
npmfences.
Thesebashblocks bypass the tabbed package-manager rendering used elsewhere inapps/docs/content. Based on learnings, this docs subtree should use a singlenpmfenced code block so the tooling can expand it automatically.Also applies to: 93-105, 131-141
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@apps/docs/content/docs/orm/next/migrations/applying-a-migration.mdx` around lines 42 - 51, The migration command examples are using bash fences, which bypass the package-manager tab rendering used in this docs subtree. Update the affected snippets in the migration docs content to use a single npm fenced code block instead, so the tooling can expand them automatically; make the change consistently across the examples shown in the migration guide.Source: Learnings
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@apps/docs/content/docs/orm/next/migrations/applying-a-migration.mdx`:
- Around line 42-51: The migration command examples are using bash fences, which
bypass the package-manager tab rendering used in this docs subtree. Update the
affected snippets in the migration docs content to use a single npm fenced code
block instead, so the tooling can expand them automatically; make the change
consistently across the examples shown in the migration guide.
In `@apps/docs/content/docs/orm/next/migrations/rollbacks-and-recovery.mdx`:
- Around line 23-28: The migration rollback snippets are using generic bash
fences, which prevents the docs tooling from rendering the package-manager tabs
consistently. Update the affected code blocks in the rollback/recovery MDX
document to use the npm fence style instead of bash, keeping the existing
command content intact; use the surrounding docs patterns in apps/docs/content
and the migration section as the reference for the correct fenced block format.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 49a3b748-418c-48a2-8716-7673e51ac7ee
📒 Files selected for processing (7)
apps/docs/content/docs/orm/next/migrations/applying-a-migration.mdxapps/docs/content/docs/orm/next/migrations/editing-a-migration.mdxapps/docs/content/docs/orm/next/migrations/generating-a-migration.mdxapps/docs/content/docs/orm/next/migrations/how-migrations-work.mdxapps/docs/content/docs/orm/next/migrations/rollbacks-and-recovery.mdxapps/docs/content/docs/orm/next/migrations/the-migration-graph.mdxapps/docs/src/components/concept-animation/presets.ts
✅ Files skipped from review due to trivial changes (4)
- apps/docs/content/docs/orm/next/migrations/the-migration-graph.mdx
- apps/docs/content/docs/orm/next/migrations/editing-a-migration.mdx
- apps/docs/content/docs/orm/next/migrations/generating-a-migration.mdx
- apps/docs/content/docs/orm/next/migrations/how-migrations-work.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- apps/docs/src/components/concept-animation/presets.ts
Resolves: meta.json (Migrations placed after Fundamentals, before Middleware), concept-animation presets (both sides additive), and next.config.mjs — the prisma-migrate redirects move into the new DR-8687 cutover block as commented-out entries per the convention main introduced, including the no-equivalent-yet list for the SEO owner. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
CodeRabbit: bind endContractJson to the raw end-contract.json import in the filled editing example (verified the variant self-emits with identical hashes); restore the extensions cross-link now that #8008 is merged; re-add the closing braces the merge common-suffix folding dropped between the migration and middleware presets. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Member
Author
|
Addressed the review in d9ed6b2 (plus the merge of main in 1c32f78):
Also from the merge: the five |
The overview page now runs the whole loop inline: three commands with the verified plan and apply output and an explicit success signal, so a newcomer is productive before leaving page one. Swept all six pages for forward references: terms like ledger, marker, and contract space are now glossed or linked at first use instead of assuming later sections. Also links the graph page from the Prisma Next index bullet, links the contract to Data Modeling, and straightens the branch/merge lanes in the migration-graph animation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Every migrations page now opens its "Prompt your coding agent" section with the same line, linking /ai/tools/skills and phrased as "Ask your agent to:". Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ills catalog Per review: - The three migration animations are rebuilt as single-concept flow scenes with one-sentence captions, replacing the dense token animations: the loop is four boxes in a cycle (change, plan, review, apply), the graph teaches exactly one idea (states are nodes, migrations are edges, shown through a branch and merge), and rollback shows one thing (a new forward edge back to a previous state, history grows). The token-preset duplicates that FLOW_SCENES already shadowed (migration trio, middleware-pipeline, extension-planes) are removed, addressing the CodeRabbit shadowing note for the entries this stack introduced. - "What a migration is" becomes "What a migration contains": a three-file table first (the file you edit, the file Prisma runs, the history marker), then one short subsection per file with the package.json/package-lock.json analogy and the Git-commit-range reading of from/to. Less jargon, one idea per paragraph. - /ai/tools/skills gains an "Available skills for Prisma Next" section cataloging the twelve skills create-prisma installs (verified against a scaffolded project's skills-lock.json), with the install command for existing projects. Every migration page's "Prompt your coding agent" section now deep-links that anchor. - CodeRabbit: the editing example's raw-JSON import is renamed startContractJson so the deserialized/raw pair reads consistently. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Validated the whole section end to end on a fresh create-prisma app against a live Prisma Postgres database and a local MongoDB replica set. Everything documented works as written: the three-command loop, the file shapes (migration.json fields, ops.json precheck/execute/ postcheck with operation classes), every command in the tables, rollback with --from/--to and the destructive warning, the placeholder flow for backfills, and full MongoDB parity (same commands, same layout, marker in _prisma_migrations). Three findings from the runs are now on the pages: - The migration directory listing includes the *-contract.d.ts snapshot types, which are what type-check migration.ts. - After a rollback, the contract source still holds the change, so db verify reports a hash mismatch until you revert and re-emit; and the resulting cycle makes the next migration plan require an explicit --from (MIGRATION.NO_TARGET names the reachable states). - Adding an extension to an existing project can hit a contract-space layout violation on db init; one migration plan run materializes the extension's baseline migration and db init proceeds (verified with pgvector on Prisma Postgres, CREATE EXTENSION included). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
|
Pushed two commits addressing the review, then validated the whole section end to end. b699109, the review feedback:
9c7c561, live validation of everything on these pages (fresh
Three findings from the runs are now on the pages: the directory listing includes the |
Style and coherence pass across the Prisma Next tree: - The intro no longer says "your contract is your schema", which contradicted the contract-authoring definition (contract = what you author, schema = the database's actual structure). Both sections now use the same distinction. - The generating tutorial drops a mislabeled link (the word "contract" pointed at the data modeling section) and a "we'll" opener. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
|
Style and coherence pass (32007a5), reviewed as a reader navigating the whole Prisma Next tree: the intro's "your contract is your schema" contradicted the contract-authoring definition (contract = what you author, schema = the database's actual structure), so both sections now draw the same distinction; the generating tutorial also drops a mislabeled link and a "we'll" opener. One coordination note: once #8024 merges, the contract mention in the intro here should link /orm/next/contract-authoring/the-data-contract; it stays unlinked for now so this branch's link check remains green whichever PR lands first. |
…ations Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # apps/docs/content/docs/orm/next/meta.json # apps/docs/cspell.json
nurul3101
approved these changes
Jul 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Adds the Migrations section to the Prisma Next docs at
/docs/orm/next/migrations/*— six pages covering the full workflow, per the migrations docs brief. Every command name, flag, file layout, hash, and CLI output was verified againstprisma/prisma-nextorigin/mainby actually running the flows end-to-end (fresh Postgres, plan → placeholder backfill → self-emit → apply → status/log → rollback → failure and atomicity behavior).New pages
migration.ts/ops.json/migration.jsonpackage), the plan–review–apply loop, precheck/execute/postcheck, and a command overview. Includes themigration-loopanimated diagram.migration-graphanimated diagram and a realmigration graphrender of the diamond fixture.migration plantutorial: greenfield vs delta planning, thedbref default (and the greenfield foot-gun when it is missing), placeholders, and reviewing withshow/graph/check.node migration.ts→ recompiledops.jsonloop, a fully verified typeddataTransformbackfill (NOT NULL on a populated table),rawSql,migration new, and attestation.migrate(notmigration apply),--showpreviews,--totargeting,--advance-ref, status/log, dev vs CI/production flows, extension spaces, and the verified failure model.--to <dir>^), destructive-op warnings, the verified atomic-rollback-on-failure behavior on Postgres, drift handling (db verify/db update/db init), and the post-rollback--fromplanning caveat.Each page ends with honest "What's early" notes (no squash/baseline/split commands, no shadow-database rehearsal, rename inference not built, data-transform wiring ceremony) and "Prompt your coding agent" prompts, matching the Middleware/Extensions pages (#8008).
Diagrams
Three new
ConceptAnimationpresets:migration-loop,migration-graph,migration-rollback.index.tsx/flow-presets.tsget the sameFlowNametyping fix as #8008 (identical content, merges cleanly).Verified behaviors worth flagging
prisma-next migrate;migration applywas removed from the CLI (the old blog posts still saymigration apply).migration planwithout--fromuses thedbref if present, otherwise plans from empty — documented with a warning, and themigrate --advance-ref dbloop documented as the happy path.migraterun rolls back atomically (whole run is one transaction); "previously applied migrations are preserved" means prior runs. The docs state this precisely instead of repeating the blog's resume-at-failed-step framing, which only applies to out-of-band satisfied ops and MongoDB.Redirects (cutover block, per DR-8687)
Main introduced a cutover convention while this PR was in flight: redirects that retire live Prisma 7 URLs ship only when Prisma Next becomes the default docs version, and accumulate commented-out in
next.config.mjsuntil then. The five migrate redirects from the brief now live there instead of being active:/orm/prisma-migrate{,/getting-started}→ how-migrations-work,.../mental-model→ the-migration-graph,.../workflows/development-and-production→ applying-a-migration,.../workflows/customizing-migrations→ editing-a-migration. The block also records the no-clean-equivalent pages for the SEO owner (shadow-database, migration-histories, limitations-and-known-issues, and the workflows pages for seeding, baselining, squashing, down-migrations, hotfixing, native functions/types, prototyping, troubleshooting) — to be reassessed as matching Prisma Next pages land.Notes
/docs/orm/next/migrations/*(the brief says/docs/next/migrations/*, butorm/nextis where the section lives on main and in docs: add Prisma Next Middleware and Extensions sections #8008).orm/next/meta.jsonwill conflict trivially with docs: add Prisma Next Middleware and Extensions sections #8008 (both add a section topages).pnpm check,types:check,lint:links,lint:spellcheck— all green; all six pages rendered and eyeballed in the dev server.🤖 Generated with Claude Code
Summary by CodeRabbit