docs(skills): prisma-next-queries — Postgres surface is always namespace-qualified

[ankur-arch]

What this fixes

The prisma-next-queries skill teaches agents (and people) how to query Prisma Next. Three things it teaches no longer match how the released packages behave. Anyone following the skill on a Postgres project today writes code that crashes on its first query.

This PR updates the skill to the tested behavior. Every correction was verified by running real queries against @prisma-next 0.14.0 on a live Postgres database, and cross-checked against the source on main.

The major change: Postgres access is always namespace-qualified

Since #778, the ORM and SQL builder resolve models through the schema namespace only:

// What the skill taught          // What actually works
db.orm.User.where(...)            db.orm.public.User.where(...)
db.sql.user.select(...)           db.sql.public.user.select(...)

The flat form does not error helpfully. db.orm.User is undefined, so the first chained call throws Cannot read properties of undefined (reading 'where'). The skill said the flat form "still works for single-namespace contracts", which is exactly the setup every new project has, so the guidance broke the most common case.

Impact: every Postgres example in the skill produced crashing code. This also affects the create-prisma scaffold templates (seed.ts, index.ts, users.ts still use the flat form, so npm run db:seed crashes on a fresh scaffold). That template fix is separate from this PR and still needed.

Two smaller corrections

1. .count() is not a query terminal. Calling it throws count() is only available inside include() refinement callbacks. Counting goes through .aggregate((a) => ({ n: a.count() })), which the skill's aggregate section already documents. The terminal list now reads .all() / .first() / .aggregate(...).

2. SQL builder inserts need the array form. .insert({ email }) fails inside result decoding on 0.14.0 (this[#rows].map is not a function). .insert([{ email }]) works, including .returning(...) and generated-id defaults. The example now uses the array form and notes the constraint.

How this was verified

db.orm.User                                          -> undefined
db.orm.public.User.where({...}).all()                -> rows ✓
db.orm.public.Post.where({...}).count()              -> throws
db.orm.public.Post.aggregate((a) => ({n: a.count()})) -> { n: number } ✓
db.sql.public.user.insert({ email })                 -> execute throws
db.sql.public.user.insert([{ email }]).returning(...) -> [{ id, email }] ✓

The same validation run surfaced a few adjacent issues that are out of scope here but worth tracking: the scaffold templates above, MongoDB @default(now()) not being applied at create time, and pipeline .match on ObjectId fields matching nothing. Happy to file them separately.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated Postgres query guidance to use namespace-qualified accessors throughout.
  • Clarified that flat Postgres access forms no longer apply and may resolve to undefined.
  • Refreshed examples for reads, writes, joins, aggregates, and scripts to match the current Postgres patterns.
  • Added clearer notes on common pitfalls and how to choose the right query path.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: af10b4be-f5fd-40de-b336-2cb59d9d5820

📥 Commits

Reviewing files that changed from the base of the PR and between a047147 and c9cf152.

📒 Files selected for processing (2)

• skills/prisma-next-queries/SKILL.md
• skills/prisma-next-queries/postgres.md

🚧 Files skipped from review as they are similar to previous changes (2)

• skills/prisma-next-queries/SKILL.md
• skills/prisma-next-queries/postgres.md

---

📝 Walkthrough

Walkthrough

Documentation updates across skills/prisma-next-queries/SKILL.md and skills/prisma-next-queries/postgres.md replace flat Postgres accessor forms with namespace-qualified db.orm.<ns>.<Model> and db.sql.<ns>.<table> usage, and state that flat Postgres access resolves to undefined.

Changes

Namespace-qualified accessor documentation

Layer / File(s)	Summary
SKILL.md overview and accessor guidance skills/prisma-next-queries/SKILL.md	Frontmatter, target-picking guidance, and checklist updated to describe namespace-qualified accessors and note that flat Postgres forms resolve to undefined.
SKILL.md consumption and script examples skills/prisma-next-queries/SKILL.md	Consumption examples, single-consumption buffering, short-script seeding, and the N:M include workaround updated to namespace-qualified form.
postgres.md lane overview and read/query examples skills/prisma-next-queries/postgres.md	Lane definitions, ORM reads, predicates, pagination, eager-loading, and read-side aggregate examples updated to namespace-qualified accessors.
postgres.md SQL builder and namespace behavior notes skills/prisma-next-queries/postgres.md	SQL builder examples, DML returning examples, computed projection, self-join, namespace behavior notes, and grouped top-N guidance updated to namespace-qualified form.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• prisma/prisma-next#564: Both PRs update the same db.orm accessor addressing docs, one for Postgres namespace-qualified paths and one for MongoDB storage-name-keyed paths.
• prisma/prisma-next#548: Related docs update in the same prisma-next-queries skill covering script teardown behavior alongside these accessor changes.

Suggested reviewers: wmadden

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main documentation change: Postgres access is now namespace-qualified throughout.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/queries-skill-qualified-orm-surface

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@skills/prisma-next-queries/postgres.md`:
- Around line 111-117: The pagination example builds the next cursor from
page1[page1.length - 1] in the Post query flow, which will fail when the first
page is empty. Update the Post pagination snippet to guard the empty result from
db.orm.public.Post.orderBy(...).take(20).all() before deriving last or
constructing page2, and only continue to the next page when page1 has at least
one item.

In `@skills/prisma-next-queries/SKILL.md`:
- Around line 124-126: The Postgres short-script example is not self-contained
because the `users` iterable is missing, so the snippet cannot be copied and run
as shown. Update the example around the `for (const u of users)` and
`db.orm.public.User.create` usage by adding a concrete `users` binding or an
inline seed source in the same snippet so the loop has defined input.
- Around line 79-84: The buffered query example uses the projected shape from
User.select('id', 'email'), so the type annotation should match the returned row
shape instead of the full entity type. Update the Promise<User[]> annotation in
the buffered example to Promise<Row[]> and keep the surrounding prose/examples
consistent with the Row[] terminology used by
db.orm.public.User.select(...).all().toArray().

🪄 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.yml

Review profile: CHILL

Plan: Pro

Run ID: 18448aa6-cceb-44ae-a59f-adc5980ca23e

📥 Commits

Reviewing files that changed from the base of the PR and between a2791c5 and a047147.

📒 Files selected for processing (2)

• skills/prisma-next-queries/SKILL.md
• skills/prisma-next-queries/postgres.md

[SevInf]

Do we need this historical fun fact in the skill?

[ankur-arch]

Agreed, dropped. It now states the rule plainly: the namespace coordinate is always required on Postgres, and a bare model access returns undefined so the first chained call throws. Same cleanup applied to the equivalent sentence in SKILL.md. Fixed in c9cf152.

[SevInf]

I think we need to mention a bit on how ns relates to PSL and contract. We always use either public or placeholder <ns> throughout the doc. We should mention somewhere that public is default (for the models declarated outside of namespace block in PSL) and <ns> stand for a namespace model have been explicitly defined in.

[ankur-arch]

Good call. Added a paragraph to the Key Concepts section (and mirrored it in SKILL.md's namespace section): models declared at the top level of the PSL live in the default public namespace, and models declared inside a namespace <name> { ... } block are addressed by that namespace; the examples use public and readers substitute their own. Fixed in c9cf152.

[SevInf]

Preemtively approve, but there are few things I'd like to change before we merge it