docs(orm/next): data modeling guides

[SevInf]

What

Adds a Data modeling section under the Prisma Next docs (/orm/next/data-modeling) with three pages:

• Overview — what a model is, primary keys (natural vs. surrogate + how to choose the type), scalar fields (how to pick a data type), and what a relation is.
• Relational databases — one-to-one, one-to-many, many-to-many (implicit + explicit), and polymorphic relations, plus how to pick which side owns the foreign key.
• MongoDB — documents/ObjectId, the embed-vs-reference decision, references, and polymorphic collections.

Registers the section in the Next nav (orm/next/meta.json).

Notes for reviewers

• Draft. Conceptual guides, not a PSL syntax reference — snippets illustrate the concepts.

• ⚠️ In-flight syntax. Relation snippets use the directional @relation(from:, to:) vocabulary and implicit many-to-many from the unmerged PSL relation-syntax stack:

  • TML-2940: from/to FK relation syntax — clean break, reject legacy fields/references prisma-next#872
  • TML-2941: through: explicit many-to-many junction authoring in PSL prisma-next#873
  • TML-2942: disambiguate relations by pointing, retire @relation(name:) prisma-next#874
  • TML-2943: implicit many-to-many via a synthesised model-less junction prisma-next#875
  • TML-2944: arrow-path through: for relation-field-less junctions prisma-next#876

  These need a re-check against source before publishing.

• MongoDB many-to-many is intentionally omitted for now.

• Docs forward-reference a "relations reference" and "MongoDB query material" that don't exist yet — those pointers are intentional placeholders.

• All PSL was cross-checked against the prisma/prisma-next source rather than prior Prisma syntax.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
blog	Ready	Preview, Comment	Jul 7, 2026 8:47am
docs	Ready	Preview, Comment	Jul 7, 2026 8:47am
eclipse	Ready	Preview, Comment	Jul 7, 2026 8:47am
site	Ready	Preview, Comment	Jul 7, 2026 8:47am

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7e3b8993-52bc-4906-98b9-aadea26874fc

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

🍈 Lychee Link Check Report

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

✅ All links are working!

---

Full Statistics Table

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

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Jul 7, 2026, 8:53 AM

[ankur-arch]

Pushed a revision (b436d39) addressing the review feedback, with every schema snippet emit-tested against @prisma-next 0.14.0 before landing in the pages.

Accuracy fixes (tested):

Construct in the previous draft	0.14.0	Change
@relation(from: [...], to: [...])	Rejected: unsupported argument "from" (main only accepts fields/references/map/onDelete/onUpdate too)	All examples now use @relation(fields:, references:)
Implicit many-to-many (Tag[] both sides)	Rejected: "use an explicit join model for many-to-many"	Section now teaches the explicit junction model as the working pattern and names the implicit form as not supported yet
@relation(through: UserTag)	Rejected: unsupported argument	Removed; junction declared with two plain relations
Composite @@id, @@discriminator/@@base (both layouts), Mongo type blocks, uuid()	All pass	Kept

Writing and structure:

• Plain-language intros (idea first, blog example, terms last), no em dashes; the docs-writer skill now codifies this in a "Teach in plain language" section so the parallel PRs can follow it.
• Bare (1:1) / (1:n) / (m:n) were being eaten by remark-directive and rendered as (1\n). Backticked now, verified intact in the rendered HTML.
• Dense paragraphs broken into scannable subsections with code blocks: natural vs surrogate keys (Country ISO example, User/Product + @unique), surrogate type choice, data type choice, and "Which side owns the foreign key" as an assertive checklist.
• MongoDB shown with tab switchers where it differs, cross-links into the Fundamentals pages for querying each shape, "Prompt your coding agent" endings, and direct link phrasing ("To model relational data, see...").
• DR-8679 redirects parked, commented out, in next.config.mjs under the shared "Prisma Next URL cutover (DR-8687)" block per the convention in the docs-writer skill.

Validation: cspell 0 issues, types:check clean, rendered-HTML check for the directive fix. Happy to iterate on any of it.

[ankur-arch]

Live-database pass on top of the emit matrix, 2026-07-07: on a fresh Prisma Postgres database, db init applied the page's schemas and the natural-key example works as written (Country create/read by ISO code). Variant models work live with one caveat now noted on the page: variants appear as ORM roots and base queries return variant rows, but creating through a variant needs the discriminator passed explicitly on 0.14.0 (d652e12 adds that sentence). On a local MongoDB replica set, the embedded-type examples run live: creating a user with a nested address returns the document with the embedded object intact. Side note for the CLI team: switching an already-signed database to a different contract via db update -y failed mid-plan on a foreign-key drop ordering (dropTable post before its junction); fresh db init works fine.

[ankur-arch]

Pushed 291c565: the sidebar now reads Data Modeling as its own section with Overview, Relational data modeling, and MongoDB data modeling as its pages (separator + flattened folder, index retitled Overview; SEO title unchanged via metaTitle).