docs(next): Prisma Next Fundamentals section (DR-8681)#8011
Open
ankur-arch wants to merge 7 commits into
Open
Conversation
…mples (DR-8681) Adds the five Prisma Next Fundamentals pages (reading data, writing data, relations and joins, transactions, advanced queries) under /docs/next/fundamentals, wires them into the sidebar and the Prisma Next landing page, and adds the temporary Prisma 7 -> Prisma Next redirects from the DR-8681 table to apps/docs/vercel.json. Every code sample was validated against @prisma-next 0.14.0: PostgreSQL via a create-db database, MongoDB via mongodb-memory-server (replica set). 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 a new Prisma Next Fundamentals docs section, wires it into navigation and redirects, expands concept animation with relationship flow scenes, and adds a gitignore rule for an internal cloned repo. ChangesFundamentals docs addition
Concept animation relationship scenes
Repository ignore rule
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
Contributor
🍈 Lychee Link Check Report65 links: ✅ All links are working!Full Statistics Table
|
![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: 1
🤖 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/`(index)/next/fundamentals/reading-data.mdx:
- Around line 82-85: Rename the sample variable in the reading-data docs from
alicesPosts to alicePosts to avoid the awkward possessive form and the cspell
hit; update the identifier in the posts query example so it consistently uses
alicePosts in that snippet.
🪄 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: a1d87228-ecf8-4084-9191-c9b74a956d1c
📒 Files selected for processing (10)
.gitignoreapps/docs/content/docs/(index)/meta.jsonapps/docs/content/docs/(index)/next/fundamentals/advanced-queries.mdxapps/docs/content/docs/(index)/next/fundamentals/meta.jsonapps/docs/content/docs/(index)/next/fundamentals/reading-data.mdxapps/docs/content/docs/(index)/next/fundamentals/relations-and-joins.mdxapps/docs/content/docs/(index)/next/fundamentals/transactions.mdxapps/docs/content/docs/(index)/next/fundamentals/writing-data.mdxapps/docs/content/docs/(index)/next/index.mdxapps/docs/vercel.json
… task-first - Move the five Fundamentals pages from /docs/next/fundamentals to /docs/orm/next/fundamentals so they live in the ORM "Next" version dropdown, and register the section in orm/next/meta.json. - Replace the broken <Tabs> JSX with the app's code-tab syntax (```lang tab="PostgreSQL"), which renders the styled code switcher. - Rewrite all pages task-first: each section starts with what to do and which API to use, shows the simplest example, states what it returns, and keeps caveats after the happy path. Implementation details (adapter capabilities, planner internals) removed from Fundamentals; limitations rephrased as user-facing guidance. Count-returning examples use count-named variables. - Update redirect destinations in vercel.json and landing-page cards to the new /docs/orm/next/fundamentals URLs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
apps/docs/content/docs/orm/next/fundamentals/reading-data.mdx (1)
72-72: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd a code example for
or/and/nothelpers.Every other filtering capability in this section (equality, lambda comparisons, range) has a code sample; this one is described in prose only. A short snippet would make the OR/NOT pattern immediately usable.
🤖 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/fundamentals/reading-data.mdx` at line 72, The OR/NOT filtering guidance in the reading-data section is only described in prose; add a short example showing how to use the `or`, `and`, and `not` helpers from `@prisma-next/sql-orm-client` alongside the surrounding query-building examples. Place the snippet near the existing filtering samples in the docs so readers can see the pattern immediately and reuse it with the same style as the other helpers in this section.
🤖 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/fundamentals/reading-data.mdx`:
- Line 72: The OR/NOT filtering guidance in the reading-data section is only
described in prose; add a short example showing how to use the `or`, `and`, and
`not` helpers from `@prisma-next/sql-orm-client` alongside the surrounding
query-building examples. Place the snippet near the existing filtering samples
in the docs so readers can see the pattern immediately and reuse it with the
same style as the other helpers in this section.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 627b6025-6a1d-4a7a-a3f8-c58b1387851d
📒 Files selected for processing (10)
apps/docs/content/docs/(index)/next/index.mdxapps/docs/content/docs/orm/next/fundamentals/advanced-queries.mdxapps/docs/content/docs/orm/next/fundamentals/meta.jsonapps/docs/content/docs/orm/next/fundamentals/reading-data.mdxapps/docs/content/docs/orm/next/fundamentals/relations-and-joins.mdxapps/docs/content/docs/orm/next/fundamentals/transactions.mdxapps/docs/content/docs/orm/next/fundamentals/writing-data.mdxapps/docs/content/docs/orm/next/index.mdxapps/docs/content/docs/orm/next/meta.jsonapps/docs/vercel.json
💤 Files with no reviewable changes (1)
- apps/docs/content/docs/orm/next/fundamentals/meta.json
✅ Files skipped from review due to trivial changes (7)
- apps/docs/content/docs/orm/next/meta.json
- apps/docs/content/docs/orm/next/index.mdx
- apps/docs/content/docs/orm/next/fundamentals/relations-and-joins.mdx
- apps/docs/content/docs/(index)/next/index.mdx
- apps/docs/content/docs/orm/next/fundamentals/advanced-queries.mdx
- apps/docs/content/docs/orm/next/fundamentals/transactions.mdx
- apps/docs/content/docs/orm/next/fundamentals/writing-data.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- apps/docs/vercel.json
…ture builders Deep revision of the Fundamentals pages for first-time readers: - Relations and joins now teaches one-to-one, one-to-many, and many-to-many each as concept -> animated diagram -> model -> query -> result shape -> pitfalls, using three new ConceptAnimation flow scenes. Many-to-many is documented as a working pattern (explicit junction model + nested include, verified end to end) instead of a limitation. - Reading data gains a tested "Stream large results" section: await buffers and is reusable, for-await streams and is single-use, mixing the two throws. (Verified on both databases; a repeated await does NOT throw, correcting the earlier claim.) - Advanced queries restructured into parallel "PostgreSQL: SQL query builder" and "MongoDB: Pipeline builder" sections, each with what-it-is, when to use it, when to prefer the ORM API, and tested examples per use case. - Common mistakes rewritten as narrated subsections: what you meant, what went wrong, the fix, and why it is safer. Type-level claims (no data wrapper, mutations require .where) verified with @ts-expect-error assertions; all documented snippets compile under strict TypeScript. - Naming: "Prisma Next ORM" replaced with Prisma Next; the query lane is called the ORM API. Test schema extended with Profile (1:1) and Tag/PostTag (M:N junction); 1:1 back-reference fields are unsupported by the PSL provider, so the 1:1 section documents querying from the foreign-key side. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (3)
apps/docs/content/docs/orm/next/fundamentals/reading-data.mdx (2)
203-210: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win"Reusing a streamed result" mistake example doesn't show the mistake.
The other two "Common mistakes" entries on this page show the wrong code, then the fix. This one jumps straight to the corrected
await ... .all()pattern without showing the actual mistake (re-iterating or re-awaiting afor awaitresult), which is already demonstrated earlier at Line 160-169. Consider pairing the mistake snippet with the fix here for consistency, e.g.:📝 Suggested addition
### Reusing a streamed result You streamed a result with `for await`, then tried to read it again. The second read throws, because a streamed result is consumed as it is read. Store the data if you need it twice: +```typescript +for await (const post of db.orm.public.Post.all()) { + // ... +} +// Re-reading the same result throws here. +``` + ```typescript const posts = await db.orm.public.Post.all(); // posts is a plain array now; read it as often as you like</details> <details> <summary>🤖 Prompt for AI Agents</summary>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/fundamentals/reading-data.mdxaround lines
203 - 210, The “Reusing a streamed result” example in reading-data.mdx skips the
actual mistake and jumps straight to the fix, unlike the other Common mistakes
entries. Update the section around the “Reusing a streamed result” heading to
show the wrong pattern first using the streamed result from
db.orm.public.Post.all() with for await, then follow it with the corrected
“store the data” example using await ... .all(), matching the style used in the
other mistake examples on the page.</details> <!-- cr-comment:v1:4466e2708c27d3a1341b2a96 --> --- `72-75`: _📐 Maintainability & Code Quality_ | _🔵 Trivial_ | _⚡ Quick win_ **Add a short OR/AND/NOT example** The surrounding filter sections are example-driven, but this paragraph only describes the helper APIs in prose. A tiny PostgreSQL snippet showing the `@prisma-next/sql-orm-client` import plus `or(...)`, `and(...)`, and `not(...)` usage would make the call shape obvious. <details> <summary>🤖 Prompt for AI Agents</summary>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/fundamentals/reading-data.mdxaround lines
72 - 75, Add a brief PostgreSQL example in the reading-data docs where the
helper APIs are introduced, using the existingor,and, andnotsymbols
from@prisma-next/sql-orm-clientso readers can see the call shape directly.
Keep the MongoDB note as-is, but make the new snippet concise and aligned with
the surrounding filter examples to show how the boolean helpers are combined in
a.where(...)query.</details> <!-- cr-comment:v1:fda6c19beeba9e213b961ef1 --> </blockquote></details> <details> <summary>apps/docs/src/components/concept-animation/index.tsx (1)</summary><blockquote> `15-19`: _📐 Maintainability & Code Quality_ | _🔵 Trivial_ | _💤 Low value_ **Optional: simplify indexed-type casts.** `(typeof FLOW_SCENES)[FlowName]` resolves to just `FlowScene` (all values share that type), and `(typeof CONCEPT_PRESETS)[ConceptName]` resolves to the preset's value type. Importing those types directly would read more clearly than the indexed-access expressions. <details> <summary>♻️ Optional simplification</summary> ```diff -import { FLOW_SCENES, type FlowName } from "./flow-presets"; +import { FLOW_SCENES, type FlowName, type FlowScene } from "./flow-presets"; ... - const scene = (FLOW_SCENES as Partial<Record<string, (typeof FLOW_SCENES)[FlowName]>>)[name]; + const scene = (FLOW_SCENES as Partial<Record<string, FlowScene>>)[name];🤖 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/index.tsx` around lines 15 - 19, Simplify the indexed-type casts in ConceptAnimation by replacing the inline `(typeof FLOW_SCENES)[FlowName]` and `(typeof CONCEPT_PRESETS)[ConceptName]` usages with the actual imported value types. Update the `ConceptAnimation` function’s `scene` and `preset` lookups to use those explicit types instead of the indexed-access expressions, keeping the existing runtime logic unchanged.
🤖 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/fundamentals/reading-data.mdx`:
- Around line 203-210: The “Reusing a streamed result” example in
reading-data.mdx skips the actual mistake and jumps straight to the fix, unlike
the other Common mistakes entries. Update the section around the “Reusing a
streamed result” heading to show the wrong pattern first using the streamed
result from db.orm.public.Post.all() with for await, then follow it with the
corrected “store the data” example using await ... .all(), matching the style
used in the other mistake examples on the page.
- Around line 72-75: Add a brief PostgreSQL example in the reading-data docs
where the helper APIs are introduced, using the existing `or`, `and`, and `not`
symbols from `@prisma-next/sql-orm-client` so readers can see the call shape
directly. Keep the MongoDB note as-is, but make the new snippet concise and
aligned with the surrounding filter examples to show how the boolean helpers are
combined in a `.where(...)` query.
In `@apps/docs/src/components/concept-animation/index.tsx`:
- Around line 15-19: Simplify the indexed-type casts in ConceptAnimation by
replacing the inline `(typeof FLOW_SCENES)[FlowName]` and `(typeof
CONCEPT_PRESETS)[ConceptName]` usages with the actual imported value types.
Update the `ConceptAnimation` function’s `scene` and `preset` lookups to use
those explicit types instead of the indexed-access expressions, keeping the
existing runtime logic unchanged.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 2c9a400a-b9d8-4ede-8f48-6aea5a41215e
📒 Files selected for processing (7)
apps/docs/content/docs/orm/next/fundamentals/advanced-queries.mdxapps/docs/content/docs/orm/next/fundamentals/reading-data.mdxapps/docs/content/docs/orm/next/fundamentals/relations-and-joins.mdxapps/docs/content/docs/orm/next/fundamentals/transactions.mdxapps/docs/content/docs/orm/next/fundamentals/writing-data.mdxapps/docs/src/components/concept-animation/flow-presets.tsapps/docs/src/components/concept-animation/index.tsx
✅ Files skipped from review due to trivial changes (3)
- apps/docs/content/docs/orm/next/fundamentals/relations-and-joins.mdx
- apps/docs/content/docs/orm/next/fundamentals/writing-data.mdx
- apps/docs/content/docs/orm/next/fundamentals/advanced-queries.mdx
…tals Style pass emulating the v6 CRUD reference: - Section-linked page intros and an expandable example schema (PostgreSQL/MongoDB tabs) on Reading and Writing data. - Queries now show their result shape in no-copy blocks, taken from the validation runs. - Prisma 7 migration notes are diff blocks (findMany -> .all(), data wrapper -> direct fields, $transaction array -> callback). - MongoDB filter section shows how to reach ranges and in() through the pipeline builder (newly tested: .match gte/lte chaining and .in() both work); PostgreSQL filters gain or() example (tested). - Sort section shows the composite orderBy array and explains offset vs cursor pagination before the cursor example. - Streaming section now defines streaming and its benefits before the consumption rules. - "Choose the right lane" renamed to "Choose the right query API". - Each page ends with "Prompt your coding agent": copyable prompts per section that reference the scaffolded Prisma Next skills. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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/fundamentals/reading-data.mdx`:
- Around line 230-252: The pagination example in the reading-data docs is
missing the tiebreaker used by the composite sort above, so it can produce
unstable results when createdAt is not unique. Update the cursor pagination
example to match the orderBy composition in the Post example, using the same
sort keys in the cursor resume step, or add a brief note in the docs explaining
that a unique tiebreaker like id must be included for correctness on tied
timestamps.
🪄 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: 9b94e86d-f0da-4e02-a08b-9ebde624b535
📒 Files selected for processing (5)
apps/docs/content/docs/orm/next/fundamentals/advanced-queries.mdxapps/docs/content/docs/orm/next/fundamentals/reading-data.mdxapps/docs/content/docs/orm/next/fundamentals/relations-and-joins.mdxapps/docs/content/docs/orm/next/fundamentals/transactions.mdxapps/docs/content/docs/orm/next/fundamentals/writing-data.mdx
✅ Files skipped from review due to trivial changes (3)
- apps/docs/content/docs/orm/next/fundamentals/advanced-queries.mdx
- apps/docs/content/docs/orm/next/fundamentals/writing-data.mdx
- apps/docs/content/docs/orm/next/fundamentals/transactions.mdx
…dance - Cursor pagination example now carries the id tiebreaker in both the composite orderBy and the cursor, with a sentence on why a cursor on a non-unique field alone can skip or repeat records. Verified against rows sharing the same createdAt: pages come back with zero overlap. - .select(...).create(...) now has a tested example with its narrowed result shape, and the same show-don't-tell treatment applies to the primary-key lookup (tabs), the updateAll rows result, and the 1:1 user-side SQL builder join that was previously only linked. - Result-block ids replaced with format-preserving placeholders so cspell passes (the random cuid/ObjectId fragments tripped it). The alicesPosts naming flag was already resolved by an earlier rewrite. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…entions - Remove the nine live Prisma 7 -> Prisma Next redirects from apps/docs/vercel.json and park them, commented out, in next.config.mjs under a "Prisma Next URL cutover (DR-8687)" block. They ship when /orm/next becomes /orm; until then section owners append their commented map to the same block so the full cutover builds up in one reviewable place. - Add .claude/skills/docs-writer/references/prisma-next.md so the parallel section PRs follow the same conventions: page location, the commented-redirects rule, tested-example requirements, tab and diagram usage, naming, and validation commands. Linked from SKILL.md. - Document raw SQL precisely on Advanced queries: standalone raw statements do not run, but fns.raw fragments inside the SQL query builder do (tested with a computed UPPER(email) projection). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
Author
|
Re-validated every example against a fresh Prisma Postgres database (bunx create-db) and a local MongoDB replica set (mongodb-memory-server), 2026-07-07. PostgreSQL: 45/45 core checks, 15/15 relations/streaming, 6/6 builder checks, plus the consumption probes (await twice OK, any for-await makes the result single-use), composite cursor with zero page overlap on tied timestamps, or()/fns.raw/junction-create checks. MongoDB: 26/26 core checks, snippet shapes, driver-session transaction escape hatch (commit and abort), streaming parity, and pipeline range/in() probes. The three legacy suite checks that exercised superseded API shapes were updated to the documented forms, so the suites now run green end to end. |
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
1 participant
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.
Adds the Prisma Next Fundamentals section: the ORM happy path for reading, querying, writing, batching, and transacting, plus the advanced-query escape hatches.
Linear: DR-8681 (redirects per DR-8687/DR-8688)
What was added
Five pages in the ORM "Next" version tree under
/docs/orm/next/fundamentals(content/docs/orm/next/fundamentals/), following the Concept-and-example template and multi-database rules from the docs spec (prisma-orm-messagingPR #14):.all()/.first(),where(object + lambda forms),select,orderBy,take/skip, cursor pagination, counting via.aggregatecreate,update,delete,upsert, and the bulk variants (createAll/updateAll/deleteAll+*Count), single-row vs bulk semantics.include(...), branch refinement, relation predicates, N:M junction limitation + escape hatchdb.transaction(...)with commit/rollback,tx.orm/tx.sql/tx.execute; MongoDB driver-session escape hatchRETURNING), MongoDB pipeline builder (group,lookup)Also: sidebar wiring in
orm/next/meta.json, Fundamentals cards on the Prisma Next landing page, andprisma-orm-messaging/added to.gitignore(local working clone of the messaging repo).How the examples were tested
No untested examples. Two throwaway apps scaffolded with
create-prisma@nextagainst@prisma-next0.14.0:bunx create-db; 45+ checks covering every read/filter/bulk/write/transaction/SQL-builder snippet, including rollback-on-throw.mongodb-memory-server(single-node replica set),prisma-next db initagainst it; 30+ checks including the driver-session transaction escape hatch (commit + abort verified).Notable tested behaviors the pages document (several diverge from older internal docs):
db.orm.public.User(the flatdb.orm.Userwas removed in prisma-next#778); MongoDB stays flat with lowercased plural roots (db.orm.users)..update()/.delete()mutate one matching row;updateAll/deleteAll/*Countare the bulk forms..count()terminal; counting goes through.aggregate((a) => ({ n: a.count() }))on PostgreSQL and the pipeline builder on MongoDB._id; filters use_id, not the mappedidfield.db.transaction(...)and no ORM.aggregate(...); both pages say so directly and show the tested escape hatch..insert([{...}])(single-object form throws in 0.14.0).Validation:
pnpm --filter docs types:checkclean,pnpm lint:links0 errors, dev-server smoke test 200 on all five URLs, tab content confirmed server-rendered (present in the.mdxagent-markdown route).Redirects: parked as comments until the URL cutover
The DR-8681 redirect map now lives commented out in
apps/docs/next.config.mjsunder the "Prisma Next URL cutover (DR-8687)" block. These redirects retire live Prisma 7 URLs, so they ship together when/orm/nextbecomes/orm. Sibling section PRs append their own commented map to the same block (documented in the newdocs-writerskill reference). The map, for review:/docs/orm/prisma-client→/docs/orm/next/fundamentals/reading-data/docs/orm/prisma-client/queries/crud→reading-data(page splits; Writing data cross-linked)/docs/orm/prisma-client/queries/select-fields→reading-data/docs/orm/prisma-client/queries/filtering-and-sorting→reading-data/docs/orm/prisma-client/queries/pagination→reading-data/docs/orm/prisma-client/queries/aggregation-grouping-summarizing→reading-data/docs/orm/prisma-client/queries/relation-queries→relations-and-joins/docs/orm/prisma-client/queries/transactions→transactions/docs/orm/prisma-client/using-raw-sql→advanced-queriesNothing redirects on deploy; enabling the block is the cutover action.
No-equivalent pages, left in place and flagged for the SEO owner (per DR-8681, not silently dropped):
queries/full-text-search(extension-based now),queries/advanced/query-optimization-performance(future Guides > Performance),queries/excluding-fields.Follow-ups filed
prisma-next-queriesskill still teaches the flatdb.orm.Userform for Postgres, a.count()terminal, and single-object.insert({...}); none of these match 0.14.0/main behavior.@default(false)emits an invalid contract in 0.14.0 (fix already onfeature/ledger-contract-snapshots); MongoDB@default(now())is not applied at create time (documented inline); pipeline.matchon ObjectId fields matches nothing;create-prismascaffold templates still use the removed flat ORM form, so the generateddb:seed/devscripts crash on Postgres.🤖 Generated with Claude Code
Summary by CodeRabbit
Update (2026-07-06): Fundamentals moved into the ORM "Next" version dropdown (
/docs/orm/next/fundamentals/*), the code switcher now uses the app'stab="..."code-block syntax (the<Tabs>JSX rendered broken), and all five pages were rewritten task-first: each section leads with the user task and the simplest example, states return values, and keeps caveats and database-specific notes after the happy path. Redirect destinations updated accordingly.Update 2 (2026-07-06): first-time-reader revision.
Relationship teaching with diagrams. Relations and joins now walks one-to-one, one-to-many, and many-to-many each as concept → diagram → model → query → result shape → pitfalls. The diagrams ship as three new
ConceptAnimationflow scenes (same component the Compute docs use), designed from these Mermaid sketches:erDiagram USER ||--o| PROFILE : "userId (unique)" USER ||--o{ POST : "authorId" POST ||--o{ POSTTAG : "postId" TAG ||--o{ POSTTAG : "tagId"Many-to-many is now a working pattern, not a limitation. Testing showed an explicit junction model traverses fine with a nested include (
Post.include("tags", (pt) => pt.include("tag")), verified end to end); only the implicit through-relation form is unsupported. Also verified: 1:1 back-reference fields (profile Profile?) are rejected by the PSL provider, so the 1:1 section documents querying from the foreign-key side.Streaming section on Reading data, from a dedicated behavior probe on both databases:
awaitbuffers and can be re-awaited (the earlier "second await throws" claim was wrong); anyfor awaitmakes the result single-use, including after an earlybreak; mixing the two throwsAsyncIterableResult iterator has already been consumed.Builder sections restructured into parallel
PostgreSQL: SQL query builder/MongoDB: Pipeline builderwith when-to-use and when-to-prefer-the-ORM-API guidance and per-use-case tested examples (joins, junction flattening, grouped top-N,RETURNING;$group, staged$match,$lookup).Common mistakes rewritten as narrated subsections (what you meant → what went wrong → fix → why). The type-level claims are verified with
@ts-expect-errorassertions:.create({ data: {...} }),.update()/.delete()without.where()all fail to compile. Every documented SQL-builder snippet compiles under strict TypeScript.Naming: the product is Prisma Next (not "Prisma Next ORM"); the high-level lane is called the ORM API.
Update 3 (2026-07-06): context and readability pass, emulating the v6 CRUD reference style.
no-copyblock, taken from the validation runs.findMany→.all(), thedatawrapper → direct fields,$transaction([...])→ the callback form.in()through the pipeline builder (newly tested: chained.matchgte/lte and.in()both work); the PostgreSQL section gained a testedor()example.orderByarray, and explains why cursor pagination beats offsets before showing it.create-prisma(prisma-next-queries,prisma-next-contract).Update 4 (2026-07-06): redirects moved out of
vercel.jsoninto the commented cutover block innext.config.mjs(see above); added.claude/skills/docs-writer/references/prisma-next.mdso parallel section PRs follow the same conventions (location, commented redirects, tested examples, tabs, diagrams, naming, validation); documentedfns.rawfragments on Advanced queries with a tested example.