docs(docs): document orderBy() nulls, remove {bin} from CLI hints, and check the engine version against prisma

[wmadden-electric]

At a glance

The SQL query builder reference said that the nulls option of orderBy() does nothing. On @prisma/orm-postgres 8.0.0-rc.13 it works:

db.sql.public.task
  .select('id', 'description')
  .orderBy('description', { direction: 'desc', nulls: 'last' })
  .build();

SELECT "id" AS "id", "description" AS "description" FROM "public"."task" ORDER BY "description" DESC NULLS LAST

What this pull request does

It corrects the Prisma ORM 8 pages that are still wrong for the packages npm installs today, prisma 8.0.0-rc.19 and @prisma/orm-postgres 8.0.0-rc.13. It also changes the rule the docs version check applies to @prisma/cli-engine, so that the check stops failing on correct pages between an engine release and the prisma release that uses it.

#8345 already moved the prisma and @prisma/cli-engine version numbers to 8.0.0-rc.19 and 0.6.2. This pull request does not repeat that.

The changes

orderBy() and nulls. orm/reference/sql-query-builder.mdx now lists options.nulls in the options table, states the PostgreSQL default and the error for an invalid value, and has an example that uses the option. The paragraph that said the option does nothing is gone, and so is the CASE WHEN workaround.

CLI hints. guides/database/schema-changes.mdx showed a literal {bin} where the CLI names itself in a hint, for example {bin} migration status. That was a bug in @prisma/cli-engine, fixed in 0.6.2 (prisma/prisma-cli#313), which prisma 8.0.0-rc.19 installs. The CLI now prints prisma there. The six output lines show prisma, and the two sentences that explained {bin} as a placeholder are removed. No other current page contains {bin}.

Contract hash. In guides/integrations/github-actions.mdx, the executionHash that prisma contract emit prints for the guide's contract changed in 8.0.0-rc.13. The storageHash and the profileHash are the same as before.

Composer version in prisma init output. In guides/frameworks/solid-start.mdx, the skill line for @prisma/composer now shows 0.25.0, which prisma init prints with prisma 8.0.0-rc.19.

The version check. pnpm lint:versions in apps/docs compares each version in the docs with the latest tag of the package on npm. For @prisma/cli-engine that rule is wrong, because a reader never installs the engine's latest. prisma orm init installs the exact engine version that the prisma package depends on. On 29 September the engine's latest became 0.6.2 before any prisma release used it, and in that window the check reported nine correct lines as stale on every docs pull request. The script now reads the expected engine version from the dependencies of prisma@latest, and fails with an error if that dependency is missing or is not an exact version. The rule for every other package is unchanged. apps/docs/AGENTS.md describes the new rule.

What was checked

• orderBy() with nulls, run against PostgreSQL 17 with the schema from the reference page. The SQL comes from the PostgreSQL statement log.

  Options	SQL	Position of the row with a null
  { direction: 'asc' }	ORDER BY "description" ASC	last
  { direction: 'asc', nulls: 'first' }	ORDER BY "description" ASC NULLS FIRST	first
  { direction: 'desc' }	ORDER BY "description" DESC	first
  { direction: 'desc', nulls: 'last' }	ORDER BY "description" DESC NULLS LAST	last
  { nulls: 'middle' }	none	orderBy() throws ORM.ARGUMENT_INVALID, "orderBy nulls must be "first" or "last""

• The team guide's scenario, run in a pseudo-terminal with two PostgreSQL 17 databases and prisma 8.0.0-rc.19, printed these lines. Every contract hash in the run matches the hash on the page.

  Command	Line
  db migrate --advance-ref db	→ Check every space against the database: prisma migration status
  migration status, two branch tips	⚠ No migration path from the database state (91e7f9f03580) to the application's contract (1e5059c1976c). Run `prisma migration plan --name <name>` to author one.
  migration status, one pending	⚠ 1 pending — run `prisma db migrate --to 1e5059c1976c` (the page keeps its colon)
  migration plan with no db ref	→ Point the db ref at the origin contract: prisma migration ref set db <contract>, → Plan from an explicit origin: prisma migration plan --from <contract>, → Plan from an empty database deliberately: prisma migration plan --from @empty

• npx prisma contract emit on the contract from the GitHub Actions guide printed the three hashes that the page now shows.

• npx prisma init reported @prisma/composer 0.25.0.

• pnpm lint:versions passes: "Every pinned version in 300 files is current."

• pnpm lint:links and cspell on the changed pages pass.

What this does not do

• The nulls option was not run on SQLite.
• The version check script has no tests, and this pull request adds none. The new engine rule was only exercised while the engine's latest and the version prisma depends on were the same.

Agent: keen-finch-33
🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated migration command examples to use prisma directly and clarified the corresponding npx prisma commands.
  • Added guidance and an example for PostgreSQL null ordering in orderBy(), including how to place null values first or last.
  • Refreshed package version and migration output examples in the framework and GitHub Actions guides.

[vercel]

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

Project	Deployment	Actions	Updated
blog	Ready	Preview	Sep 30, 2026 5:34am UTC
docs	Ready	Preview	Sep 30, 2026 5:34am UTC
eclipse	Ready	Preview	Sep 30, 2026 5:34am UTC
site	Ready	Preview	Sep 30, 2026 5:34am UTC

[github-actions]

🍈 Lychee Link Check Report

90 links: ✅ 7 OK | 🚫 0 errors | 🔀 5 redirects | 👻 83 excluded

✅ All links are working!

---

Full Statistics Table

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

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 288011df-f136-431a-a009-e5eebbcac0ed

📥 Commits

Reviewing files that changed from the base of the PR and between 9228911 and 0c0f303.

📒 Files selected for processing (1)

• apps/docs/content/docs/guides/frameworks/solid-start.mdx

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

• apps/docs/content/docs/guides/frameworks/solid-start.mdx

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 1 remain after this review.

---

Walkthrough

The documentation version linter now checks @prisma/cli-engine against the dependency version in prisma@latest. The docs update migration command hints, PostgreSQL null-ordering guidance, and displayed package and execution-hash values.

Changes

Documentation updates

Layer / File(s)	Summary
CLI engine version check apps/docs/AGENTS.md, apps/docs/scripts/lint-versions.ts	The version linter now checks @prisma/cli-engine against the exact version in prisma@latest’s dependencies. Diagnostics label the comparison value as expected.
Migration command hints apps/docs/content/docs/guides/database/schema-changes.mdx	Migration status, planning, migration, and recovery hints now use direct prisma commands instead of {bin} placeholders.
SQL null-ordering guidance apps/docs/content/docs/orm/reference/sql-query-builder.mdx	The reference documents PostgreSQL null-ordering options and invalid-value handling, and adds an example using NULLS LAST.
Guide example values apps/docs/content/docs/guides/frameworks/solid-start.mdx, apps/docs/content/docs/guides/integrations/github-actions.mdx	The displayed prisma-composer-core-concepts version and migration execution hash are updated.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 0c0f3

This change updates documentation example values and version references. No actionable merge-blocking risk was identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 1 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: documenting orderBy() null handling, removing {bin} from CLI hints, and updating engine-version validation.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 1 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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