docs: record that a bare read fetches scalars, not relations (#848) - #849
Merged
Conversation
Records the decision from triage of #848: a `context.db` read with no `include` (and no fragment `query`) returns the row's own columns plus its virtual fields, never its relations — matching Prisma. Adds ADR-0024 with the rejected alternatives (keep-and-document, an opt-out flag, the resolveOutput-only fix, folding in the caller-directed walk, holding for 1.0) and the consequences, chiefly that this break is silent for affected code and so leads with detection rather than rationale. Adds a "Bare read" glossary entry and notes on Access Filter that it scopes the relations a read asked for rather than choosing them. Docs only — no package code changes, so no changeset. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PifFTifspW7ud4ptUGK4Mx
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Coverage Report for Core Package Coverage (./packages/core)
File CoverageNo changed files found. |
Contributor
Coverage Report for UI Package Coverage (./packages/ui)
File CoverageNo changed files found. |
Contributor
Coverage Report for CLI Package Coverage (./packages/cli)
File CoverageNo changed files found. |
Contributor
Coverage Report for Auth Package Coverage (./packages/auth)
File CoverageNo changed files found. |
Contributor
Coverage Report for Storage Package Coverage (./packages/storage)
File CoverageNo changed files found. |
Contributor
Coverage Report for RAG Package Coverage (./packages/rag)
File CoverageNo changed files found. |
Contributor
Coverage Report for Storage S3 Package Coverage (./packages/storage-s3)
File CoverageNo changed files found. |
Contributor
Coverage Report for Storage Vercel Package Coverage (./packages/storage-vercel)
File CoverageNo changed files found. |
8 tasks
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
2 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.
Docs-only. Records the decision reached while triaging #848, ahead of the implementation.
The decision
A
context.dbread with noinclude(and no fragmentquery) returns the row's own columns plus its virtual fields, and no relations — matching Prisma. Relations come back only when a caller names them.Uniform across
findUnique,findManyand singleton reads, sudo and non-sudo. No opt-in and no back-compat flag. Ships as a minor, following the precedent of #844 and ADR-0022.Why it needed an ADR
The current default is deliberate and ADR-adjacent, so a future reader would otherwise reasonably "fix" the flip back. Two findings from triage drove it:
includethrough, and on a bare read there isn't one — so the same call returns a five-level tree on a session context and a flat row under sudo. The singleton read is a third shape again, auto-including unconditionally with no caller-includeplumbing at all. The default was a property of one branch of the read API, not of the API.querytool, where a five-deep tree is actively harmful.The behaviour was verified against a mocked Prisma before any of this was written: a bare
findUniqueemits a nested relation tree,include: {}emits{}, and the reporter's virtual-field cycle reproduces asResolveOutputCycleError: User.name → User.namefrom an ordinary read with no include.Changes
docs/adr/0024-a-read-with-no-include-fetches-scalars-not-relations.md— the decision, five rejected alternatives, and the consequences.CONTEXT.md— a Bare read glossary entry, and a note on Access Filter that it scopes the relations a read asked for rather than choosing them.Notes for review
The consequence worth arguing with is the first one: this break is silent. A read that returned
post.authornow returns noauthorkey — no error, just less data — which is the opposite of ADR-0022's breakage. The ADR commits the changeset and migration note to leading with detection (grep forcontext.db.*.find*calls with noinclude, and virtualresolveOutputhooks readingitem.<relation>) rather than with rationale.ADR-0022 and ADR-0023 both stand. Neither said anything about what a read with no include should fetch, which is the gap this fills.
No package code changed, so no changeset. Implementation is tracked on #848 (
ready-for-agent), with follow-ups forvirtual({ needs: [...] }), anincludeargument on MCP tools, and making the access-scoped walk caller-directed.🤖 Generated with Claude Code
https://claude.ai/code/session_01PifFTifspW7ud4ptUGK4Mx
Generated by Claude Code