docs: add raw SQL query support to the Prisma 8 RC1 roadmap

[wmadden-electric]

Linked issue

No single ticket — this documents a gap in the Prisma 8 RC1 roadmap, part of the Prisma 8 RC1 project. Context tickets referenced in the new block: TML-2672 (the gotcha that proves the gap) and TML-2959 (the one frozen-surface fix on the shipped fragment path). Follows the docs: convention set by the roadmap's own PR (#1028).

At a glance

A new Requirement 4 item in ROADMAP.md, opening with:

<details><summary>⬜ <b>Raw SQL query support — running an arbitrary SQL statement when the ORM and builder can't</b></summary>

"Raw queries" is a headline row every Prisma 7 user will look for: hand a parameterized
SQL string to the client and get rows back, or an affected-row count. Prisma 8 ships part
of this today and has to settle the rest before the scoreboard freezes.

…followed by five bullets naming the major items, and closing on the July 24 bar: statement-level raw SQL either ships with a proving test or becomes a written-down "not in 8.0" absence.

Decision

Raw SQL query support was absent from the roadmap. The roadmap's own principle is "everything absent is named rather than silently missing", and raw queries are one of the most-used Prisma 7 features — so it gets a named block. The block lands as one new <details> task under Requirement 4 — the release's claims must be proven, beside the existing "Capabilities still landing before the verdicts freeze" item, because that's where the roadmap tracks features whose scoreboard verdict must resolve before July 24.

The block distinguishes what already ships from what's missing, grounded in the current codebase and the checked-in scorecard (scorecard/13-raw-and-typed-sql.md):

• Shipped, proven: the raw SQL fragment inside the typed builder (fns.raw`…`) on Postgres and SQLite; MongoDB has its own raw-command hatch.
• The gap: the statement-level $queryRaw/$executeRaw path. The substrate exists (the driver's query(sql, params), a lane: 'raw' execution-plan shape, the guardrail evaluator) and the design is written (ADR 012), but no public helper surfaces it — so a real Prisma 8 app had to hand-forge an execution plan to run a truncate and hit a guardrail crash (TML-2672).

The five major items listed: a public statement-level query/execute API; safe-by-default parameterization with a named unsafe door; read/write intent the guardrails can see; a decided answer on result typing and the Prisma.sql/join/raw/empty helpers (currently not in 8.0); and the explicit-codec fix on the shipped fragment path (TML-2959).

What changed

• ROADMAP.md — the new <details> block under Requirement 4; top task tally updated (21 not started → 22).
• ROADMAP.html — the same block mirrored in the hand-maintained styled render (matching <details class="task"> markup), plus the three count surfaces kept in sync: the header tally (34 → 35 tasks, 22 not started, flight-bar width), the legend, and Requirement 4's mini-bar (6 → 7 tasks, 1 done · 2 in flight · 4 not started).

Reviewer notes

• This branch was fast-forwarded onto origin/main before editing. The worktree's original HEAD predated docs: ROADMAP.md carries the Prisma 8 roadmap; database tiers stated; stale planning docs deleted #1028, which rewrote ROADMAP.md from the old marketing roadmap into the RC1 plan — editing the stale file would have produced a 280-line phantom diff. The diff here is the two files only.
• ROADMAP.html is a hand-authored mirror, not generated from the Markdown, so both files change together. Worth spot-checking that the prose and the five bullets match between them.
• The task-count math is the fiddly part. The added item is Not started, so: page total 34 → 35, not-started 21 → 22 (done and in-flight unchanged); Requirement 4 goes 6 → 7 tasks with not-started 3 → 4; the HTML flight-bar and mini-bar widths were recomputed to match. A grep confirms no stale 34 tasks / 21 not started / 6 tasks: strings remain.
• "Not started" pill, deliberately — the shipped fragment path is mentioned inside the block, but the block's work (the statement-level API) hasn't started, so a single not-started pill is the honest summary, mirroring how the polymorphism block carries one pill over mixed sub-items.
• Claims are grounded, not invented. The "already works / not in 8.0" split matches scorecard/13-raw-and-typed-sql.md (rawSql fragment ✅ PG+SQLite; Prisma.sql/join/raw/empty, typed fragment generics, TypedSQL all ❌); the substrate claims match the driver SqlQueryable.query interface and the lane: 'raw' plan; the crash and hand-forged-plan story is from TML-2672.

Verification

• Rendered ROADMAP.html and confirmed the block expands with its five bullets and correct links (TML-2672, ADR 012, TML-2959); the header shows the updated 35 tasks — 1 done, 12 in flight, 22 not started.
• grep across both files: no stale counts remain; the new block is present in both; Requirement 4 now has 7 balanced <details>/</details> pairs.
• Doc-only change — no test suites apply.

Checklist

• All commits are signed off (git commit -s + Will's Signed-off-by certification); DCO will pass.
• I read CONTRIBUTING.md and the change is scoped to one logical concern (one roadmap item, mirrored across both files).
• Tests are updated — n/a, doc-only change with no behavioural delta.
• PR title follows the docs: convention used by the roadmap's own PR (docs: ROADMAP.md carries the Prisma 8 roadmap; database tiers stated; stale planning docs deleted #1028); no dedicated Linear ticket.
• Skill update — n/a, no skill touched.

[coderabbitai]

Warning

Review limit reached

@wmadden-electric, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 19 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4fd0187f-162c-412b-a6b8-c48a71c64ec3

📥 Commits

Reviewing files that changed from the base of the PR and between 418dcb3 and 327bbbd.

📒 Files selected for processing (2)

• ROADMAP.html
• ROADMAP.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch worktree/raw-sql-roadmap-edc2be

---

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]

size-limit report 📦

Path	Size
postgres / no-emit	163.8 KB (0%)
postgres / emit	145.92 KB (0%)
mongo / no-emit	100.14 KB (0%)
mongo / emit	89.85 KB (0%)
cf-worker / no-emit	189.41 KB (0%)
cf-worker / emit	169.53 KB (0%)

[pkg-pr-new]

Open in StackBlitz

@prisma-next/extension-author-tools

npm i https://pkg.pr.new/@prisma-next/extension-author-tools@1039

@prisma-next/mongo-runtime

npm i https://pkg.pr.new/@prisma-next/mongo-runtime@1039

@prisma-next/family-mongo

npm i https://pkg.pr.new/@prisma-next/family-mongo@1039

@prisma-next/sql-runtime

npm i https://pkg.pr.new/@prisma-next/sql-runtime@1039

@prisma-next/family-sql

npm i https://pkg.pr.new/@prisma-next/family-sql@1039

@prisma-next/extension-arktype-json

npm i https://pkg.pr.new/@prisma-next/extension-arktype-json@1039

@prisma-next/middleware-cache

npm i https://pkg.pr.new/@prisma-next/middleware-cache@1039

@prisma-next/mongo

npm i https://pkg.pr.new/@prisma-next/mongo@1039

@prisma-next/extension-paradedb

npm i https://pkg.pr.new/@prisma-next/extension-paradedb@1039

@prisma-next/extension-pgvector

npm i https://pkg.pr.new/@prisma-next/extension-pgvector@1039

@prisma-next/extension-postgis

npm i https://pkg.pr.new/@prisma-next/extension-postgis@1039

@prisma-next/postgres

npm i https://pkg.pr.new/@prisma-next/postgres@1039

@prisma-next/sql-orm-client

npm i https://pkg.pr.new/@prisma-next/sql-orm-client@1039

@prisma-next/sqlite

npm i https://pkg.pr.new/@prisma-next/sqlite@1039

@prisma-next/extension-supabase

npm i https://pkg.pr.new/@prisma-next/extension-supabase@1039

@prisma-next/target-mongo

npm i https://pkg.pr.new/@prisma-next/target-mongo@1039

@prisma-next/adapter-mongo

npm i https://pkg.pr.new/@prisma-next/adapter-mongo@1039

@prisma-next/driver-mongo

npm i https://pkg.pr.new/@prisma-next/driver-mongo@1039

@prisma-next/contract

npm i https://pkg.pr.new/@prisma-next/contract@1039

@prisma-next/utils

npm i https://pkg.pr.new/@prisma-next/utils@1039

@prisma-next/config

npm i https://pkg.pr.new/@prisma-next/config@1039

@prisma-next/errors

npm i https://pkg.pr.new/@prisma-next/errors@1039

@prisma-next/framework-components

npm i https://pkg.pr.new/@prisma-next/framework-components@1039

@prisma-next/operations

npm i https://pkg.pr.new/@prisma-next/operations@1039

@prisma-next/ts-render

npm i https://pkg.pr.new/@prisma-next/ts-render@1039

@prisma-next/contract-authoring

npm i https://pkg.pr.new/@prisma-next/contract-authoring@1039

@prisma-next/ids

npm i https://pkg.pr.new/@prisma-next/ids@1039

@prisma-next/psl-parser

npm i https://pkg.pr.new/@prisma-next/psl-parser@1039

@prisma-next/psl-printer

npm i https://pkg.pr.new/@prisma-next/psl-printer@1039

@prisma-next/cli

npm i https://pkg.pr.new/@prisma-next/cli@1039

@prisma-next/cli-telemetry

npm i https://pkg.pr.new/@prisma-next/cli-telemetry@1039

@prisma-next/config-loader

npm i https://pkg.pr.new/@prisma-next/config-loader@1039

@prisma-next/emitter

npm i https://pkg.pr.new/@prisma-next/emitter@1039

@prisma-next/language-server

npm i https://pkg.pr.new/@prisma-next/language-server@1039

@prisma-next/migration-tools

npm i https://pkg.pr.new/@prisma-next/migration-tools@1039

prisma-next

npm i https://pkg.pr.new/prisma-next@1039

@prisma-next/vite-plugin-contract-emit

npm i https://pkg.pr.new/@prisma-next/vite-plugin-contract-emit@1039

@prisma-next/mongo-codec

npm i https://pkg.pr.new/@prisma-next/mongo-codec@1039

@prisma-next/mongo-contract

npm i https://pkg.pr.new/@prisma-next/mongo-contract@1039

@prisma-next/mongo-value

npm i https://pkg.pr.new/@prisma-next/mongo-value@1039

@prisma-next/mongo-contract-psl

npm i https://pkg.pr.new/@prisma-next/mongo-contract-psl@1039

@prisma-next/mongo-contract-ts

npm i https://pkg.pr.new/@prisma-next/mongo-contract-ts@1039

@prisma-next/mongo-emitter

npm i https://pkg.pr.new/@prisma-next/mongo-emitter@1039

@prisma-next/mongo-schema-ir

npm i https://pkg.pr.new/@prisma-next/mongo-schema-ir@1039

@prisma-next/mongo-query-ast

npm i https://pkg.pr.new/@prisma-next/mongo-query-ast@1039

@prisma-next/mongo-orm

npm i https://pkg.pr.new/@prisma-next/mongo-orm@1039

@prisma-next/mongo-query-builder

npm i https://pkg.pr.new/@prisma-next/mongo-query-builder@1039

@prisma-next/mongo-lowering

npm i https://pkg.pr.new/@prisma-next/mongo-lowering@1039

@prisma-next/mongo-wire

npm i https://pkg.pr.new/@prisma-next/mongo-wire@1039

@prisma-next/sql-contract

npm i https://pkg.pr.new/@prisma-next/sql-contract@1039

@prisma-next/sql-errors

npm i https://pkg.pr.new/@prisma-next/sql-errors@1039

@prisma-next/sql-operations

npm i https://pkg.pr.new/@prisma-next/sql-operations@1039

@prisma-next/sql-schema-ir

npm i https://pkg.pr.new/@prisma-next/sql-schema-ir@1039

@prisma-next/sql-contract-psl

npm i https://pkg.pr.new/@prisma-next/sql-contract-psl@1039

@prisma-next/sql-contract-ts

npm i https://pkg.pr.new/@prisma-next/sql-contract-ts@1039

@prisma-next/sql-contract-emitter

npm i https://pkg.pr.new/@prisma-next/sql-contract-emitter@1039

@prisma-next/sql-lane-query-builder

npm i https://pkg.pr.new/@prisma-next/sql-lane-query-builder@1039

@prisma-next/sql-relational-core

npm i https://pkg.pr.new/@prisma-next/sql-relational-core@1039

@prisma-next/sql-builder

npm i https://pkg.pr.new/@prisma-next/sql-builder@1039

@prisma-next/target-postgres

npm i https://pkg.pr.new/@prisma-next/target-postgres@1039

@prisma-next/target-sqlite

npm i https://pkg.pr.new/@prisma-next/target-sqlite@1039

@prisma-next/adapter-postgres

npm i https://pkg.pr.new/@prisma-next/adapter-postgres@1039

@prisma-next/adapter-sqlite

npm i https://pkg.pr.new/@prisma-next/adapter-sqlite@1039

@prisma-next/driver-postgres

npm i https://pkg.pr.new/@prisma-next/driver-postgres@1039

@prisma-next/driver-sqlite

npm i https://pkg.pr.new/@prisma-next/driver-sqlite@1039

commit: 327bbbd