From d5b5a1fb6625455f7e37985ccede4afb073bd251 Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Thu, 24 Sep 2026 17:30:32 +0200
Subject: [PATCH 01/16] docs(docs): update the Prisma ORM 8 pages for
 8.0.0-rc.12

Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../docs/(index)/full-stack-tutorial.mdx      |  2 +-
 .../add-to-existing-project/postgresql.mdx    |  2 +-
 .../docs/(index)/prisma-orm/from-scratch.mdx  | 12 ++--
 apps/docs/content/docs/cli/configuration.mdx  | 70 ++++++++++++++++++-
 apps/docs/content/docs/cli/contract-emit.mdx  |  6 +-
 apps/docs/content/docs/cli/contract-infer.mdx |  2 +
 apps/docs/content/docs/cli/db-verify.mdx      |  4 ++
 apps/docs/content/docs/cli/global-flags.mdx   |  2 +-
 apps/docs/content/docs/cli/migration-new.mdx  | 13 +++-
 apps/docs/content/docs/cli/migration-plan.mdx |  2 +
 apps/docs/content/docs/cli/orm-init.mdx       | 22 +++++-
 .../guides/deployment/cloudflare-workers.mdx  |  2 +-
 .../content/docs/guides/deployment/docker.mdx |  2 +-
 .../guides/deployment/pnpm-workspaces.mdx     |  4 +-
 .../docs/guides/deployment/turborepo.mdx      |  2 +-
 .../docs/guides/frameworks/react-router-7.mdx |  2 +-
 .../docs/guides/frameworks/solid-start.mdx    |  2 +-
 .../switch-to-prisma-orm/from-drizzle.mdx     |  2 +-
 .../switch-to-prisma-orm/from-mongoose.mdx    |  4 +-
 .../switch-to-prisma-orm/from-sql-orms.mdx    |  2 +
 .../guides/upgrade-prisma-orm/mongodb.mdx     | 10 +--
 .../guides/upgrade-prisma-orm/postgresql.mdx  | 19 +++--
 .../docs/orm/coming-from-prisma-orm-7.mdx     | 32 +++++----
 .../orm/contract-authoring/editor-support.mdx |  7 +-
 .../orm/contract-authoring/psl-syntax.mdx     | 66 ++++++++++++++---
 .../the-contract-artifact.mdx                 | 10 +--
 .../contract-authoring/the-data-contract.mdx  |  6 +-
 .../typescript-schema-builder.mdx             | 23 ++++--
 apps/docs/content/docs/orm/core-concepts.mdx  |  4 +-
 .../content/docs/orm/data-modeling/index.mdx  |  6 +-
 .../docs/orm/data-modeling/mongodb.mdx        |  2 +-
 .../docs/orm/extensions/using-extensions.mdx  | 10 ++-
 .../orm/fundamentals/advanced-queries.mdx     | 10 ++-
 .../docs/orm/fundamentals/reading-data.mdx    |  2 +-
 .../orm/fundamentals/relations-and-joins.mdx  |  2 +-
 .../docs/orm/fundamentals/transactions.mdx    |  6 +-
 .../docs/orm/fundamentals/writing-data.mdx    |  4 +-
 .../authoring-custom-middleware.mdx           | 24 +++----
 .../docs/orm/middleware/built-in-budgets.mdx  |  6 +-
 .../docs/orm/middleware/built-in-cache.mdx    |  6 +-
 .../docs/orm/middleware/built-in-lints.mdx    | 18 ++---
 .../orm/middleware/how-middleware-works.mdx   | 10 +--
 .../orm/migrations/applying-a-migration.mdx   |  2 +-
 .../orm/migrations/editing-a-migration.mdx    | 20 +++---
 .../orm/migrations/generating-a-migration.mdx |  2 +
 .../orm/migrations/how-migrations-work.mdx    | 12 ++--
 .../orm/migrations/the-migration-graph.mdx    |  2 +-
 .../docs/content/docs/orm/reference/index.mdx |  2 +-
 .../content/docs/orm/reference/orm-client.mdx | 63 +++++++++++++++--
 .../docs/orm/reference/pipeline-builder.mdx   |  2 +-
 .../docs/orm/reference/raw-queries.mdx        |  2 +-
 .../docs/orm/reference/sql-query-builder.mdx  | 22 +++++-
 .../reference/transactions-and-runtime.mdx    | 34 ++++++---
 apps/docs/content/docs/orm/release-status.mdx |  6 +-
 apps/docs/cspell.json                         |  3 +
 55 files changed, 456 insertions(+), 158 deletions(-)

diff --git a/apps/docs/content/docs/(index)/full-stack-tutorial.mdx b/apps/docs/content/docs/(index)/full-stack-tutorial.mdx
index 17fb5f869e..832f72cf32 100644
--- a/apps/docs/content/docs/(index)/full-stack-tutorial.mdx
+++ b/apps/docs/content/docs/(index)/full-stack-tutorial.mdx
@@ -219,7 +219,7 @@ npx prisma migration plan --name add-user-role --from <timestamp>_init
 The plan is your change and nothing else. Review it like any other diff, with [`migration show`](/cli/migration-show) or by reading the generated package:
 
 ```text no-copy
-ALTER TABLE "public"."user" ADD COLUMN "role" text DEFAULT 'member' NOT NULL
+ALTER TABLE "public"."User" ADD COLUMN "role" text DEFAULT 'member' NOT NULL
 ```
 
 Emitting also updated the query types, so surface the new field in the route's typed select in `src/prisma/users.ts`, adding `"role"` to the `.select(...)` list and `role: user.role` to the returned object:
diff --git a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/postgresql.mdx b/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/postgresql.mdx
index 0296fe3c78..7c609dd69f 100644
--- a/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/postgresql.mdx
+++ b/apps/docs/content/docs/(index)/prisma-orm/add-to-existing-project/postgresql.mdx
@@ -84,7 +84,7 @@ npx prisma contract infer --output ./src/prisma/contract.prisma
 
 The command writes a first draft of `src/prisma/contract.prisma`.
 
-Open that file and review it before you go on. This is the moment to clean up model names, keep only the tables you want Prisma ORM to know about first, and make the file easier to read.
+Open that file and review it before you go on. This is the moment to clean up model names, keep only the tables you want Prisma ORM to know about first, and make the file easier to read. A model's table is the model name exactly as written, so a table such as `User` gets a model with no `@@map`, and a table such as `user` or `user_profile` gets `@@map` with its name. Keep those `@@map` lines when you rename a model, so the table stays the same.
 
 :::note[Temporal types on inferred date and time columns]
 
diff --git a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
index eb1f9e96bb..0e8453f95d 100644
--- a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
+++ b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
@@ -43,7 +43,7 @@ npm install @prisma/orm-postgres dotenv
 npm install --save-dev prisma tsx typescript
 ```
 
-`@prisma/orm-postgres` is the library your code imports, and `prisma` is the command-line tool. `dotenv` loads `.env`, `tsx` runs `index.ts` without a build step, and `typescript` 5.9 or newer is a peer dependency of `@prisma/orm-postgres`. The two Prisma packages have different version numbers (this page was tested with `prisma` 8.0.0-rc.15 and `@prisma/orm-postgres` 8.0.0-rc.11); that is normal, and any two `latest` versions work together.
+`@prisma/orm-postgres` is the library your code imports, and `prisma` is the command-line tool. `dotenv` loads `.env`, `tsx` runs `index.ts` without a build step, and `typescript` 5.9 or newer is a peer dependency of `@prisma/orm-postgres`. The two Prisma packages have different version numbers (for example `prisma` 8.0.0-rc.15 and `@prisma/orm-postgres` 8.0.0-rc.12); that is normal, and any two `latest` versions work together.
 
 ## 2. Create the config file and `.env`
 
@@ -122,8 +122,8 @@ npx prisma db init
 │  database:  postgres://****:****@db.prisma.io:5432/postgres?sslmode=require
 ✔ Applied 2 operation(s) across 1 contract space
 App space
-├─ Create table "user"
-├─ Add unique constraint on "user" (email)
+├─ Create table "User"
+├─ Add unique constraint on "User" (email)
 └─ marker f4e1954fd8bed87828d13c3f1a02164dc9796ef1af76ed6f98184c01263169c5
 ✔ Advanced ref "db" → f4e1954fd8bed87828d13c3f1a02164dc9796ef1af76ed6f98184c01263169c5
 ```
@@ -215,13 +215,13 @@ npx prisma migration plan --name add_user_phone
 ```text
 ✔ Planned baseline + 1 operation(s)
 migrations/app/20260917T1457_add_user_phone
-└─ Add column "phone" to "user"
+└─ Add column "phone" to "User"
 from:       f4e1954fd8bed87828d13c3f1a02164dc9796ef1af76ed6f98184c01263169c5
 to:         a8a6806fd2d219065fd4449b295c80626e9123c18bd40847ec3588aa9d565bc9
 baseline:   migrations/app/20260917T1456_baseline
 app space:  migrations/app/20260917T1457_add_user_phone
 ℹ DDL preview
-ALTER TABLE "public"."user" ADD COLUMN "phone" text;
+ALTER TABLE "public"."User" ADD COLUMN "phone" text;
 ```
 
 Two directories appear under `migrations/app/`: a baseline that records the table `db init` created, and your change. The baseline is never applied to this database, because the database is already signed at that state. Each migration directory holds a `migration.ts` you can read and edit; [Generating a migration](/orm/migrations/generating-a-migration) explains the files.
@@ -235,7 +235,7 @@ npx prisma db migrate --advance-ref db
 ```text
 ✔ Applied 1 migration(s) (1 operation(s)) across 1 contract space(s)
 App space
-├─ Add column "phone" to "user"
+├─ Add column "phone" to "User"
 └─ marker a8a6806fd2d219065fd4449b295c80626e9123c18bd40847ec3588aa9d565bc9
 ✔ Advanced ref "db" → a8a6806fd2d219065fd4449b295c80626e9123c18bd40847ec3588aa9d565bc9
 ```
diff --git a/apps/docs/content/docs/cli/configuration.mdx b/apps/docs/content/docs/cli/configuration.mdx
index 6ed4f5a3f6..c96fb8986a 100644
--- a/apps/docs/content/docs/cli/configuration.mdx
+++ b/apps/docs/content/docs/cli/configuration.mdx
@@ -6,7 +6,7 @@ metaTitle: Prisma ORM CLI configuration
 metaDescription: 'Learn how Prisma ORM CLI commands find config, read database URLs, and format output.'
 ---
 
-Prisma ORM CLI commands read `prisma.config.ts` in your project root. The file has one section per part of the CLI. The Prisma ORM data commands read the `orm` section; the [agent skills commands](/cli/skills) read the `skills` section.
+Prisma ORM CLI commands read `prisma.config.ts`, starting in the directory you run them from. The file has one section per part of the CLI. The Prisma ORM data commands read the `orm` section; the [agent skills commands](/cli/skills) read the `skills` section.
 
 ## Config file
 
@@ -27,14 +27,78 @@ export default definePrismaConfig({
 });
 ```
 
-For MongoDB projects, import the section helper from `@prisma/orm-mongo/config` instead. `defineConfig` from `@prisma/cli-engine` is the former name of `definePrismaConfig` and still works, so configs scaffolded by earlier release candidates keep evaluating.
+For MongoDB projects, import the section helper from `@prisma/orm-mongo/config` instead. The `defineConfig` you import from `@prisma/orm-postgres/config` or `@prisma/orm-mongo/config` keeps its name.
 
-[`orm init`](/cli/orm-init) writes this file for you. Pass `--config` when your config file is not at `./prisma.config.ts`:
+`defineConfig` from `@prisma/cli-engine` was the former name of `definePrismaConfig`, and `@prisma/cli-engine` 0.6.1 removed it. A config scaffolded by an earlier release candidate that imports it fails to load. Import `definePrismaConfig` instead, and call it in place of `defineConfig`.
+
+[`orm init`](/cli/orm-init) writes this file for you. Pass `--config` when your config file is not in the directory you run the command from:
 
 ```npm
 npx prisma contract emit --config ./config/prisma.config.ts
 ```
 
+## How the CLI finds the config
+
+The CLI looks for `prisma.config.ts` in the current directory, or starts from the file you pass to `--config`. It then looks in each parent directory, up to the root of the repository, which is the first directory that has a `.git` entry. It merges every `prisma.config.ts` it finds key by key, and where two files set the same key, the one nearest to the starting point wins.
+
+A project inside a larger repository therefore inherits any setting its own config leaves out from a `prisma.config.ts` higher up. To stop that, add `parent: false` to the project's config. The search then ends at that file:
+
+```typescript title="prisma.config.ts"
+import { definePrismaConfig } from "prisma/config";
+import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";
+
+export default definePrismaConfig({
+  parent: false,
+  orm: ormConfig({
+    contract: "./prisma/contract.prisma",
+  }),
+});
+```
+
+`parent` also takes a path, which names the next config file to read instead of the one in the parent directory.
+
+A relative path in a config file, such as `contract`, `output`, or `migrations.dir`, resolves from the directory of the config file that sets it, not from the directory you run the command in. So `--config ./config/prisma.config.ts` with `contract: "./prisma/contract.prisma"` reads `./config/prisma/contract.prisma`.
+
+## Split the schema across several files
+
+`contract` accepts a glob, so one schema can span several `.prisma` files:
+
+```typescript title="prisma.config.ts"
+import { definePrismaConfig } from "prisma/config";
+import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";
+
+export default definePrismaConfig({
+  orm: ormConfig({
+    contract: "./prisma/**/*.prisma",
+  }),
+});
+```
+
+Every file the glob matches that starts with `// use prisma-8` becomes part of one schema, and `contract emit` builds one contract from them. A file without that first line is left out without a warning, and if no matched file has it, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. A new file joins the schema on the next emit, with no change to the config. The emitted files go in the fixed part of the glob, here `./prisma/contract.json` and `./prisma/contract.d.ts`.
+
+## Use a Prisma ORM 7 schema
+
+On PostgreSQL, Prisma ORM 8 can read a Prisma ORM 7 `schema.prisma` directly as its contract source, so the two versions can run side by side on the database that Prisma ORM 7 migrates. Wrap the path in `prisma7Schema`:
+
+```typescript title="prisma.config.ts"
+import "dotenv/config";
+import { definePrismaConfig } from "prisma/config";
+import { defineConfig as ormConfig, prisma7Schema } from "@prisma/orm-postgres/config";
+
+export default definePrismaConfig({
+  orm: ormConfig({
+    contract: prisma7Schema("prisma/schema.prisma"),
+    db: {
+      connection: process.env["DATABASE_URL"]!,
+    },
+  }),
+});
+```
+
+`prisma7Schema` takes one schema file, or a directory of `.prisma` files as Prisma ORM 7 reads it. `contract emit` writes `contract.json` and `contract.d.ts` into the directory that holds the schema, here `prisma/`, unless you set `output`. Prisma ORM 7 keeps owning the database and its migrations: after each `prisma7 migrate dev` or `prisma7 migrate deploy`, run `npx prisma contract emit` and then `npx prisma db sign`.
+
+Prisma ORM 8 describes each part of the schema exactly or refuses it. A part it cannot describe, such as a `view` block, `Unsupported(...)`, or `relationMode = "prisma"`, fails `contract emit` with an error that names the file, the line, and a Prisma ORM 7 edit that removes it. [`orm init --from-prisma7-schema`](/cli/orm-init#on-a-prisma-orm-7-project) writes this config for you.
+
 ## Emit-only config
 
 `contract emit` does not connect to a database, so the `orm` section can omit `db.connection`:
diff --git a/apps/docs/content/docs/cli/contract-emit.mdx b/apps/docs/content/docs/cli/contract-emit.mdx
index 4b07f20961..cfebc6b088 100644
--- a/apps/docs/content/docs/cli/contract-emit.mdx
+++ b/apps/docs/content/docs/cli/contract-emit.mdx
@@ -10,6 +10,8 @@ metaDescription: Learn how to emit contract.json and contract.d.ts for Prisma OR
 
 The command is offline. It does not need a database connection.
 
+A PSL contract source can be one file or a glob that matches several files; see [Split the schema across several files](/cli/configuration#split-the-schema-across-several-files). `contract emit` reads only the `.prisma` files whose first line is `// use prisma-8`, and leaves any other file out without a warning. When no file has that line, it fails with `CONTRACT.SOURCE_LOAD_FAILED` and the finding `PSL_NO_OPTED_IN_SCHEMA_FILES`.
+
 ## Usage
 
 ```npm
@@ -31,7 +33,9 @@ The command emits:
 - `contract.json`, the canonical machine-readable contract
 - `contract.d.ts`, the generated TypeScript contract declarations
 
-Do not edit these files by hand. Re-run `contract emit` after changing the contract source or extension pack list.
+Do not edit these files by hand. Re-run `contract emit` after changing the contract source or extension pack list. `contract.d.ts` lists models, fields, and relations in the same order as `contract.json`.
+
+When the contract source cannot be read, the command fails with `CONTRACT.SOURCE_LOAD_FAILED`. The terminal prints each finding, and in `--json` output the error carries a `diagnostics` array with one entry per finding: its code, its summary, and, where known, its file and line.
 
 ## Run it automatically
 
diff --git a/apps/docs/content/docs/cli/contract-infer.mdx b/apps/docs/content/docs/cli/contract-infer.mdx
index 0e267a98b4..f23060c6d5 100644
--- a/apps/docs/content/docs/cli/contract-infer.mdx
+++ b/apps/docs/content/docs/cli/contract-infer.mdx
@@ -43,6 +43,8 @@ Inference gives you a starting point, not a finished design. Review:
 - defaults, indexes, and constraints
 - extension-backed column types
 
+The file starts with `// use prisma-8`, which `contract emit` needs. Each model is named after its table, and gets `@@map` only when the table name differs from the model name: a table `User` becomes `model User`, and a table `user_profile` becomes `model UserProfile` with `@@map("user_profile")`. Each column default is written in a form `contract emit` reads back: a JSON default as a `json` literal, a decimal as a bare number with every digit, and any other SQL expression as a `sql` literal, as [Default values](/orm/contract-authoring/psl-syntax#default-values) describes. A nullable list column is written `Type[]?`. If you keep an inferred contract in version control, running `contract infer` again can print the same database differently than earlier release candidates did; review the diff.
+
 The command stops at `contract.prisma`. Follow it with the emit and sign steps:
 
 ```npm
diff --git a/apps/docs/content/docs/cli/db-verify.mdx b/apps/docs/content/docs/cli/db-verify.mdx
index 852a919c98..bbd5c4bc41 100644
--- a/apps/docs/content/docs/cli/db-verify.mdx
+++ b/apps/docs/content/docs/cli/db-verify.mdx
@@ -60,3 +60,7 @@ npx prisma db verify --db "$DATABASE_URL" --json
 | Extension mismatch | The contract requires an extension that is not wired in the config. |
 
 Fix the database or contract, emit again if needed, then verify again.
+
+## How PostgreSQL defaults are compared
+
+`db verify` compares a column default by its value, not by how PostgreSQL prints it, so `'-1'::integer`, `(5)::smallint`, an enum value cast to a type in another schema, a `timestamp` value without a time zone, and an `ARRAY[...]` list all compare equal to the default in your contract. It reads the database with `TimeZone = UTC` and ISO dates, whatever the server or role sets. A contract inferred from a server outside UTC before `8.0.0-rc.12` can therefore show one difference in a `timestamptz` value inside a check constraint or an index predicate. Emit the contract and run `db sign` once to clear it.
diff --git a/apps/docs/content/docs/cli/global-flags.mdx b/apps/docs/content/docs/cli/global-flags.mdx
index 1409297a7d..efd35ae1c9 100644
--- a/apps/docs/content/docs/cli/global-flags.mdx
+++ b/apps/docs/content/docs/cli/global-flags.mdx
@@ -18,7 +18,7 @@ All commands in the unified Prisma CLI accept these flags.
 | `--color` / `--no-color` | Force colored output on or off. |
 | `--interactive` / `--no-interactive` | Force prompts on or off. |
 | `-y`, `--yes` | Accept prompt defaults without asking. |
-| `--confirm <token>` | Grant a consent prompt non-interactively by typing its token (repeatable). |
+| `--confirm <token>` | Grant a consent prompt in advance by giving its token, so the command does not ask (repeatable). Works in scripts and in an interactive terminal. |
 | `--config <path>` | Read this config file instead of `./prisma.config.ts`. |
 | `-h`, `--help` | Print the manual for a command: what it does, its options, a workflow where one applies, and examples. |
 | `--version` | Print the CLI version and exit. |
diff --git a/apps/docs/content/docs/cli/migration-new.mdx b/apps/docs/content/docs/cli/migration-new.mdx
index 86b1d1c668..e3c0b316aa 100644
--- a/apps/docs/content/docs/cli/migration-new.mdx
+++ b/apps/docs/content/docs/cli/migration-new.mdx
@@ -21,10 +21,21 @@ npx prisma migration new --name split-name
 | Option | What it does |
 | --- | --- |
 | `--name <slug>` | Sets the migration directory name suffix. |
-| `--from <hash>` | Sets the starting contract hash. Defaults to the latest migration target. |
+| `--from <hash>` | Sets the starting contract: the target hash of an existing migration, or a unique prefix of one. Defaults to the `db` ref, as on [`migration plan`](/cli/migration-plan). A hash on an empty migrations directory, or a prefix that matches more than one migration, is refused. |
 | `--config <path>` | Read this config file instead of `./prisma.config.ts`. |
 | `--json` | Prints a machine-readable result. |
 
+## Where it starts
+
+Without `--from`, `migration new` picks its starting point the way `migration plan` does:
+
+- When the `db` ref exists and `migrations/app/` has migrations, it starts from the `db` ref.
+- When there are no migrations and no `db` ref, it starts from an empty database.
+- When migrations exist but there is no `db` ref, it refuses with `MIGRATION.PLAN_ORIGIN_UNKNOWN`. Pass `--from` with the hash of the migration to build on, or set the ref with [`migration ref`](/cli/migration-ref). `npx prisma migration list` shows the hashes.
+- When the `db` ref exists but there are no migrations, it refuses and points you to `migration plan`, which writes the baseline first.
+
+Before `8.0.0-rc.12`, `migration new` started from the newest migration. Scripts that relied on that should pass `--from`.
+
 ## Examples
 
 ```npm
diff --git a/apps/docs/content/docs/cli/migration-plan.mdx b/apps/docs/content/docs/cli/migration-plan.mdx
index fbb7012412..116deeba78 100644
--- a/apps/docs/content/docs/cli/migration-plan.mdx
+++ b/apps/docs/content/docs/cli/migration-plan.mdx
@@ -21,6 +21,8 @@ Keep the `db` ref current and you never see the refusal. [`db init`](/cli/db-ini
 
 When `migrations/app/` is empty and the `db` ref points at a contract whose snapshot is stored under `migrations/snapshots/`, one `migration plan` run writes a baseline package from nothing to the ref's contract and, when your emitted contract differs from the ref's, a second package with the delta. Expect one or two new directories in `git status`. The baseline is never replayed against a database that already carries a marker, because the runner starts from the marker and only applies edges past it.
 
+When the baseline would contain destructive operations, `migration plan` asks for consent before it writes it, as [`db update`](/cli/db-update) does. In a script, pass `--no-interactive --confirm <directory>`. It also warns when planning from the `db` ref would start a second branch in the migration history.
+
 The command is offline. It does not need a database connection.
 
 ## Usage
diff --git a/apps/docs/content/docs/cli/orm-init.mdx b/apps/docs/content/docs/cli/orm-init.mdx
index ecdfd27346..71e1495451 100644
--- a/apps/docs/content/docs/cli/orm-init.mdx
+++ b/apps/docs/content/docs/cli/orm-init.mdx
@@ -31,6 +31,7 @@ npx prisma@latest orm init --yes --target postgres --authoring psl
 | `--target <db>` | Sets the database target. Use `postgres` or `mongodb`. |
 | `--authoring <style>` | Sets the contract authoring style. Use `psl` or `typescript`. |
 | `--schema-path <path>` | Sets where the starter contract is written. |
+| `--from-prisma7-schema <path>` | Uses the Prisma ORM 7 schema at `<path>` as the contract source instead of writing a starter contract. PostgreSQL only. See [On a Prisma ORM 7 project](#on-a-prisma-orm-7-project). |
 | `--write-env` | Writes `.env` from `.env.example` (gitignored). |
 | `--probe-db` | Connects to `DATABASE_URL` once and checks the server version. |
 | `--strict-probe` | Treats a failed database probe as fatal. |
@@ -42,7 +43,7 @@ npx prisma@latest orm init --yes --target postgres --authoring psl
 The exact files depend on the target and authoring style, but a Postgres PSL setup normally includes:
 
 - `prisma.config.ts`
-- a starter contract file such as `src/prisma/contract.prisma`
+- a starter contract file such as `src/prisma/contract.prisma`, whose first line is `// use prisma-8`
 - emitted contract artifacts after installation runs
 - a runtime client file (`src/prisma/db.ts`) that imports `contract.json`
 - `.env.example`, `tsconfig.json`, and updated `package.json`
@@ -54,6 +55,25 @@ The runtime files are ES modules. If your `package.json` declares `"type": "comm
 
 The generated `prisma.config.ts` imports `definePrismaConfig` from `@prisma/cli-engine`, while projects created by `create-prisma` (and the examples in [Configuration](/cli/configuration)) import it from `prisma/config`. Both work; keep the import your project already has when you copy a config example.
 
+## On a Prisma ORM 7 project
+
+`orm init` can set up Prisma ORM 8 beside Prisma ORM 7 on PostgreSQL, with Prisma ORM 8 reading your existing `schema.prisma` as its contract source. Pass the schema path:
+
+```npm title="Terminal"
+npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma
+```
+
+A plain `orm init` offers the same setup when it finds a Prisma ORM 7 config, or a `prisma/schema.prisma` with a `datasource` block. The database target comes from the schema's `datasource` provider, and a `--target` that disagrees with it fails with `CLI.INIT_PRISMA7_TARGET_MISMATCH`.
+
+Before it changes any file, `orm init` installs `@prisma/orm-postgres` and checks that Prisma ORM 8 can read the schema. A schema it cannot read, for example one with a `view` block, stops the command with `CLI.INIT_PRISMA7_SCHEMA_REFUSED`, which lists each problem with its line and the Prisma ORM 7 edit that removes it. Then it asks for consent, which `--confirm <directory>` gives in a script, and:
+
+- renames the Prisma ORM 7 config to `prisma7.config.ts` and points its import at `@prisma/prisma7/config`
+- changes every `package.json` script that runs `prisma` to run `prisma7`
+- installs Prisma ORM 7 as `@prisma/prisma7`, next to `prisma@latest`
+- writes `prisma.config.ts` with `contract: prisma7Schema("<schema path>")`, plus `src/prisma/db.ts` and `prisma-8.md`
+
+It does not write a starter contract, and it does not change `prisma/` or the database. Prisma ORM 7 keeps owning the schema and its migrations. Set `DATABASE_URL` and run `npx prisma db sign` once. After each `prisma7 migrate dev`, run `npx prisma contract emit` and then `npx prisma db sign`. [Configuration](/cli/configuration#use-a-prisma-orm-7-schema) explains `prisma7Schema`, and [the upgrade guide](/guides/upgrade-prisma-orm/postgresql) covers the rest of the move.
+
 ## Examples
 
 ```npm
diff --git a/apps/docs/content/docs/guides/deployment/cloudflare-workers.mdx b/apps/docs/content/docs/guides/deployment/cloudflare-workers.mdx
index de12b8e5ca..525209644b 100644
--- a/apps/docs/content/docs/guides/deployment/cloudflare-workers.mdx
+++ b/apps/docs/content/docs/guides/deployment/cloudflare-workers.mdx
@@ -95,7 +95,7 @@ Without `--yes`, the command asks for the contract authoring style and the schem
 ```json no-copy
 {"kind":"step-finished","step":"npm add @prisma/orm-postgres dotenv","outcome":"ok"}
 {"kind":"step-finished","step":"npm add -D prisma@latest","outcome":"ok"}
-{"kind":"step-finished","step":"npm add -D @prisma/cli-engine@0.3.0","outcome":"ok"}
+{"kind":"step-finished","step":"npm add -D @prisma/cli-engine@0.6.1","outcome":"ok"}
 {"kind":"step-finished","step":"Emit the contract","outcome":"ok"}
 {"kind":"result","envelope":{"ok":true,"result":{"target":"postgres","authoring":"psl","schemaPath":"src/prisma/contract.prisma","filesWritten":["src/prisma/contract.prisma","prisma.config.ts","src/prisma/db.ts","prisma-8.md",".env.example","tsconfig.json",".gitignore",".gitattributes","package.json","README.md"]}}}
 ```
diff --git a/apps/docs/content/docs/guides/deployment/docker.mdx b/apps/docs/content/docs/guides/deployment/docker.mdx
index 2c73a6dad8..d0595cfa09 100644
--- a/apps/docs/content/docs/guides/deployment/docker.mdx
+++ b/apps/docs/content/docs/guides/deployment/docker.mdx
@@ -90,7 +90,7 @@ package.json declares "type": "commonjs" ... the scaffolded prisma/db.ts uses an
 If you want the default, set "type": "module" in package.json.
 ✔ npm add @prisma/orm-postgres dotenv
 ✔ npm add -D prisma@latest @types/node
-✔ npm add -D @prisma/cli-engine@0.3.0
+✔ npm add -D @prisma/cli-engine@0.6.1
 ✔ Emit the contract
 │  target:     postgres
 │  authoring:  psl
diff --git a/apps/docs/content/docs/guides/deployment/pnpm-workspaces.mdx b/apps/docs/content/docs/guides/deployment/pnpm-workspaces.mdx
index c64a097b8c..c95a8ba297 100644
--- a/apps/docs/content/docs/guides/deployment/pnpm-workspaces.mdx
+++ b/apps/docs/content/docs/guides/deployment/pnpm-workspaces.mdx
@@ -95,8 +95,8 @@ Answer the prompts: choose `PSL` for the authoring style and keep the default sc
 ✔ pnpm add @prisma/orm-postgres dotenv
 ▸ pnpm add -D prisma@latest @types/node
 ✔ pnpm add -D prisma@latest @types/node
-▸ pnpm add -D @prisma/cli-engine@0.3.0
-✔ pnpm add -D @prisma/cli-engine@0.3.0
+▸ pnpm add -D @prisma/cli-engine@0.6.1
+✔ pnpm add -D @prisma/cli-engine@0.6.1
 ▸ Emit the contract
 ✔ Emit the contract
 │  target:     postgres
diff --git a/apps/docs/content/docs/guides/deployment/turborepo.mdx b/apps/docs/content/docs/guides/deployment/turborepo.mdx
index f04a665b70..4d9b798f3d 100644
--- a/apps/docs/content/docs/guides/deployment/turborepo.mdx
+++ b/apps/docs/content/docs/guides/deployment/turborepo.mdx
@@ -232,7 +232,7 @@ Add the database scripts and a package entrypoint to `packages/database/package.
     "dotenv": "^17.4.2"
   },
   "devDependencies": {
-    "@prisma/cli-engine": "0.3.0",
+    "@prisma/cli-engine": "0.6.1",
     "@types/node": "26.4.1",
     "prisma": "8.0.0"
   }
diff --git a/apps/docs/content/docs/guides/frameworks/react-router-7.mdx b/apps/docs/content/docs/guides/frameworks/react-router-7.mdx
index 17428bcc54..296658acfc 100644
--- a/apps/docs/content/docs/guides/frameworks/react-router-7.mdx
+++ b/apps/docs/content/docs/guides/frameworks/react-router-7.mdx
@@ -88,7 +88,7 @@ npx prisma@latest orm init --yes --target postgres --authoring psl
 Updated tsconfig.json with required compiler options.
 npm add @prisma/orm-postgres dotenv
 npm add -D prisma@latest
-npm add -D @prisma/cli-engine@0.3.0
+npm add -D @prisma/cli-engine@0.6.1
 Emit the contract
 
 filesWritten: src/prisma/contract.prisma, prisma.config.ts, src/prisma/db.ts,
diff --git a/apps/docs/content/docs/guides/frameworks/solid-start.mdx b/apps/docs/content/docs/guides/frameworks/solid-start.mdx
index 2df7825acb..05e0d70ba5 100644
--- a/apps/docs/content/docs/guides/frameworks/solid-start.mdx
+++ b/apps/docs/content/docs/guides/frameworks/solid-start.mdx
@@ -90,7 +90,7 @@ npx prisma@latest orm init --yes --target postgres --authoring psl
 Updated tsconfig.json with required compiler options.
 ✔ npm add @prisma/orm-postgres dotenv
 ✔ npm add -D prisma@latest @types/node
-✔ npm add -D @prisma/cli-engine@0.3.0
+✔ npm add -D @prisma/cli-engine@0.6.1
 ✔ Emit the contract
 │  target:     postgres
 │  authoring:  psl
diff --git a/apps/docs/content/docs/guides/switch-to-prisma-orm/from-drizzle.mdx b/apps/docs/content/docs/guides/switch-to-prisma-orm/from-drizzle.mdx
index 89245155b2..a2e2d5ff90 100644
--- a/apps/docs/content/docs/guides/switch-to-prisma-orm/from-drizzle.mdx
+++ b/apps/docs/content/docs/guides/switch-to-prisma-orm/from-drizzle.mdx
@@ -176,7 +176,7 @@ Choose `PSL` as the authoring style and keep the default schema path, `src/prism
 ```text no-copy
 ✔ npm add @prisma/orm-postgres dotenv
 ✔ npm add -D prisma@latest
-✔ npm add -D @prisma/cli-engine@0.3.0
+✔ npm add -D @prisma/cli-engine@0.6.1
 ✔ Emit the contract
 │  target:     postgres
 │  authoring:  psl
diff --git a/apps/docs/content/docs/guides/switch-to-prisma-orm/from-mongoose.mdx b/apps/docs/content/docs/guides/switch-to-prisma-orm/from-mongoose.mdx
index f40fdaadaa..eb4c488d13 100644
--- a/apps/docs/content/docs/guides/switch-to-prisma-orm/from-mongoose.mdx
+++ b/apps/docs/content/docs/guides/switch-to-prisma-orm/from-mongoose.mdx
@@ -146,7 +146,7 @@ Choose `PSL` when asked for the contract authoring style and keep the default sc
 ```text no-copy
 ✔ npm add @prisma/orm-mongo dotenv
 ✔ npm add -D prisma@latest
-✔ npm add -D @prisma/cli-engine@0.3.0
+✔ npm add -D @prisma/cli-engine@0.6.1
 ✔ Emit the contract
 │  target:     mongodb
 │  authoring:  psl
@@ -165,7 +165,7 @@ installed
 ├─ @prisma/orm-mongo
 ├─ dotenv
 ├─ prisma@latest (dev)
-└─ @prisma/cli-engine@0.3.0 (dev)
+└─ @prisma/cli-engine@0.6.1 (dev)
 ✔ Done. Open prisma-8.md to get started.
 ```
 
diff --git a/apps/docs/content/docs/guides/switch-to-prisma-orm/from-sql-orms.mdx b/apps/docs/content/docs/guides/switch-to-prisma-orm/from-sql-orms.mdx
index d4bc9a9ad0..4d159cb346 100644
--- a/apps/docs/content/docs/guides/switch-to-prisma-orm/from-sql-orms.mdx
+++ b/apps/docs/content/docs/guides/switch-to-prisma-orm/from-sql-orms.mdx
@@ -155,6 +155,8 @@ npx prisma contract infer --output ./src/prisma/contract.prisma
 The inferred contract mirrors what TypeORM created, down to the constraint names and the `CASCADE` on the foreign key. Model names are PascalCase; `@@map` keeps the physical table names, so no table is renamed:
 
 ```prisma title="src/prisma/contract.prisma"
+// use prisma-8
+
 model User {
   id        Int         @id(map: "PK_cace4a159ff9f2512dd42373760") @default(autoincrement())
   email     VarChar     @unique(map: "UQ_e12875dfb3b1d92d7d7c5377e22")
diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx
index b93ef051e2..5a892eb4ce 100644
--- a/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx
+++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx
@@ -24,7 +24,7 @@ Install the companion [prisma-mongodb-upgrade](https://github.com/prisma/skills/
 
 :::info
 
-Prisma ORM MongoDB support evolves quickly, so check anything below against the `@prisma/orm-*` version you install. This guide targets `@prisma/orm-mongo@8.0.0-rc.11`.
+Prisma ORM MongoDB support evolves quickly, so check anything below against the `@prisma/orm-*` version you install. This guide targets `@prisma/orm-mongo@8.0.0-rc.12`.
 
 :::
 
@@ -106,7 +106,7 @@ export { prisma };
 
 :::note
 
-Prisma ORM 8 addresses collections by **storage name**, not model name: `db.orm.users` (the `@@map` name, or the lowercased model name), never `db.orm.User`. Whatever you `@@map` in this step is the exact name every client call uses in step 3.
+Prisma ORM 8 addresses collections by **storage name**, not model name: `db.orm.users` (the `@@map` name, or the model name exactly as written), never `db.orm.User` when the model maps to `users`. Whatever you `@@map` in this step is the exact name every client call uses in step 3.
 
 :::
 
@@ -122,6 +122,7 @@ You can use the [prisma-mongodb-upgrade](https://github.com/prisma/skills/tree/m
 
 | Concept | v6 (`schema.prisma`) | Prisma ORM 8 (`contract.prisma`) |
 |---------|----------------------|---------------------------------|
+| First line | (nothing) | `// use prisma-8`. `contract emit` reads only the files that start with it |
 | Datasource | `datasource db { provider = "mongodb" }` | no `provider` (configured in `prisma.config.ts`) |
 | Id field | `id String @id @default(auto()) @map("_id") @db.ObjectId` | `id ObjectId @id @map("_id")` |
 | Embedded document | `type Address { ... }` | `type Address { ... }` (unchanged) |
@@ -130,8 +131,9 @@ You can use the [prisma-mongodb-upgrade](https://github.com/prisma/skills/tree/m
 
 A fuller contract putting together enum, embedded type, relation, and polymorphism:
 
-```prisma
-// src/prisma/contract.prisma
+```prisma title="src/prisma/contract.prisma"
+// use prisma-8
+
 enum UserRole {
   @@type("mongo/string@1")
   Admin  = "admin"
diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
index c5a8af9069..79a12f267e 100644
--- a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
+++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
@@ -14,7 +14,7 @@ The guide covers **PostgreSQL only**. Guidance for other databases will follow.
 
 :::info
 
-This guide targets `prisma@latest`, `@prisma/orm-postgres@8.0.0-rc.11`, `@prisma/cli-engine@0.3.0`, and `@prisma/prisma7@7.10.0`, with a Prisma ORM 7 baseline on `7.9.1`. `prisma@latest` is the Prisma ORM 8 CLI, `8.0.0-rc.15` at the time of writing. It is versioned and released separately from the ORM packages, so its version number will not match theirs.
+This guide targets `prisma@latest`, `@prisma/orm-postgres@8.0.0-rc.12`, `@prisma/cli-engine@0.6.1`, and `@prisma/prisma7@7.10.0`, with a Prisma ORM 7 baseline on `7.9.1`. `prisma@latest` is the Prisma ORM 8 CLI, `8.0.0-rc.15` at the time of writing. It is versioned and released separately from the ORM packages, so its version number will not match theirs.
 
 :::
 
@@ -267,16 +267,23 @@ Prisma ORM 8 describes your schema as a [contract](/orm/contract-authoring/the-d
 npx prisma contract infer --output prisma8/contract.prisma
 ```
 
+:::tip[Read the Prisma ORM 7 schema instead]
+
+Prisma ORM 8 can also read `prisma/schema.prisma` directly, so you keep one schema file while Prisma ORM 7 owns migrations. Set `contract: prisma7Schema("prisma/schema.prisma")` in `prisma.config.ts`, with `prisma7Schema` imported from `@prisma/orm-postgres/config`, and skip steps 2.3 and 2.4. After each `prisma7 migrate dev`, run `npx prisma contract emit` and then `npx prisma db sign`. [`prisma orm init --from-prisma7-schema prisma/schema.prisma`](/cli/orm-init#on-a-prisma-orm-7-project) sets this up, and does phase 1 as well. [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema) lists what Prisma ORM 8 cannot read. The steps in phase 4 are written for the inferred `prisma8/contract.prisma`.
+
+:::
+
 ### 2.4. Edit the inferred contract
 
-The inferred contract needs two edits before it is correct:
+Delete the `PrismaMigrations` model. `contract infer` picks up Prisma ORM 7's `_prisma_migrations` ledger table. Prisma ORM 8 must not manage it, and extra tables in the database are fine. Remove the whole model.
 
-1. **Delete the `PrismaMigrations` model.** `contract infer` picks up Prisma ORM 7's `_prisma_migrations` ledger table. Prisma ORM 8 must not manage it, and extra tables in the database are fine. Remove the whole model.
-2. **Add `@@map` to every model.** Prisma ORM 8 addresses tables by storage name and lowercases unmapped model names, so without `@@map("User")` it would query `public.user`. The table Prisma ORM 7 created is `"User"`, so queries fail with `relation "public.user" does not exist`.
+The models need no `@@map`. A model without `@@map` names its table exactly as written, so `User` reads and writes the `"User"` table that Prisma ORM 7 created.
 
 The finished contract:
 
 ```prisma title="prisma8/contract.prisma"
+// use prisma-8
+
 model User {
   id    Int     @id(map: "User_pkey") @default(autoincrement())
   email String
@@ -284,7 +291,6 @@ model User {
   posts Post[]
 
   @@index([email], map: "User_email_key", unique: true)
-  @@map("User")
 }
 
 model Post {
@@ -295,10 +301,11 @@ model Post {
   author    User    @relation(fields: [authorId], references: [id], onDelete: Cascade, onUpdate: Cascade, map: "Post_authorId_fkey")
 
   @@index([authorId], map: "Post_authorId_idx")
-  @@map("Post")
 }
 ```
 
+Keep `// use prisma-8` as the first line: `contract emit` reads only files that start with it.
+
 ### 2.5. Emit the contract artifacts
 
 ```npm
diff --git a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
index d0494a0168..7c86e1ea78 100644
--- a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
+++ b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
@@ -14,7 +14,7 @@ All examples use PostgreSQL.
 
 ## Before you start
 
-If you are adding Prisma ORM 8 to an application that runs Prisma ORM 7, follow [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql). It installs both versions side by side and takes over your existing database. Do not run the commands below in that project: `npm install prisma` installs version 8 and replaces the version 7 command-line tool.
+If you are adding Prisma ORM 8 to an application that runs Prisma ORM 7, follow [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql). It installs both versions side by side and takes over your existing database. Do not run the commands below in that project: `npm install prisma` installs version 8 and replaces the version 7 command-line tool. On PostgreSQL, [`prisma orm init --from-prisma7-schema prisma/schema.prisma`](/cli/orm-init#on-a-prisma-orm-7-project) does that setup for you, and Prisma ORM 8 then reads your `schema.prisma` as its contract.
 
 In a new project, three commands set up Prisma ORM 8:
 
@@ -37,7 +37,7 @@ The biggest visible change is in field types. Where Prisma ORM 7 wrote a Prisma
 | Prisma ORM 7 | Prisma ORM 8 | Notes |
 | --- | --- | --- |
 | `schema.prisma` | `contract.prisma` | |
-| (nothing) | `// use prisma-8` as the first line | `prisma orm init` writes it; add it yourself if you write the contract by hand. Without it the contract still works, but the [Prisma editor extension](/orm/contract-authoring/editor-support) does not recognise the file. Contracts from before `8.0.0-rc.10` say `// use prisma-next` instead; the editor extension still accepts that and rewrites it when you format |
+| (nothing) | `// use prisma-8` as the first line | `prisma orm init` writes it; add it yourself if you write the contract by hand. `prisma contract emit` reads only the files that start with it, and the [Prisma editor extension](/orm/contract-authoring/editor-support) does not recognise a file without it. Contracts from before `8.0.0-rc.10` say `// use prisma-next` instead, which still works; the editor extension rewrites it when you format |
 | `generator client { ... }` | removed | `emit` is the new word for `generate`. `prisma contract emit` writes two files next to your contract, `contract.json` and `contract.d.ts`. Commit both |
 | `datasource db { ... }` | the `orm` section of `prisma.config.ts` | the connection string and file paths live in the config file, not the schema. Example below |
 | `String @db.Text` | `String` | `String` is already stored as `text`. A known bug in one error message suggests `Text`; there is no such type |
@@ -47,15 +47,17 @@ The biggest visible change is in field types. Where Prisma ORM 7 wrote a Prisma
 | `String @db.Uuid` | `Uuid` | |
 | `DateTime`, `DateTime @db.Timestamptz` | `DateTime` | same name, and it is already a `timestamptz` column. Values come back as `Temporal.Instant`, not JavaScript `Date`; `new Date(value.epochMilliseconds)` converts one. See the note below the table |
 | `updatedAt DateTime @updatedAt` | `updatedAt temporal.updatedAt()` | write `temporal.updatedAt()` where the type would go. It declares a `DateTime` field and sets it on every create and update. Any field name works. `temporal.` is part of the contract syntax; there is nothing to import |
-| `createdAt DateTime @default(now())` | the same, or `createdAt temporal.createdAt()` | both work |
+| `createdAt DateTime @default(now())` | the same, or `createdAt temporal.createdAt()` | both work. `@default(now())` is a database default. `temporal.createdAt()` is set by Prisma ORM from your application's clock and gives the column no database default |
 | `String @default(cuid())` | `String @default(cuid(2))` | `2` is the cuid version. Plain `cuid()` is rejected |
+| `@default(dbgenerated("gen_random_uuid()"))` | ``@default(sql`gen_random_uuid()`)`` | `dbgenerated` is rejected. Any SQL expression is a `sql` tagged literal, except `now()` and `autoincrement()`, which you write as those functions. [Default values](/orm/contract-authoring/psl-syntax#default-values) covers every kind of default |
 | `Json` | `Jsonb` | Prisma ORM 7's `Json` stored a PostgreSQL `jsonb` column, so write `Jsonb`. In Prisma ORM 8, `Json` means PostgreSQL's older `json` type, which you almost certainly do not want |
+| `Json @default("{}")` | ``Jsonb @default(json`{}`)`` | a JSON default is a `json` tagged literal. A quoted string is text, and a JSON column does not accept it |
 | `enum Role { ADMIN USER }`, in a new database | `enum Role { ADMIN USER }` | same syntax. You can give members explicit values (`ADMIN = "admin"`). The column is stored as text, not as a PostgreSQL enum type |
-| `enum Role { ADMIN USER }` with a field `role Role`, in an existing Prisma ORM 7 database | `native_enum Role { ADMIN = "ADMIN" USER = "USER" }` with the field `role pg.enum(Role)` | your database already has a PostgreSQL enum type for it; `native_enum` keeps it. Every member needs an explicit value. You can switch to a plain `enum` later; that changes the column type, so it needs a migration. `pg.` is part of the contract syntax, like `temporal.` |
+| `enum Role { ADMIN USER }` with a field `role Role`, in an existing Prisma ORM 7 database | `native_enum Role { ADMIN = "ADMIN" USER = "USER" }` with the field `role pg.enum(Role)` | your database already has a PostgreSQL enum type for it; `native_enum` keeps it. Every member needs an explicit value. You can switch to a plain `enum` later; that changes the column type, so it needs a migration. `pg.` is part of the contract syntax, like `temporal.`. A `pg.enum(...)` column has no `like` or `ilike`; compare it with `eq` or `in` |
 | `String[]` | `String[]` | unchanged on PostgreSQL. The list filters (`has`, `hasEvery`, `hasSome`, `isEmpty`) are not available; filter on a list with raw SQL for now (see below) |
 | `@@schema("billing")` | `namespace billing { model ... }` | a `namespace` block is a PostgreSQL schema; wrap the models in it. They become `db.orm.billing.Invoice` and so on |
 | implicit many-to-many (`Post[]` on `Tag` and `Tag[]` on `Post`, with no model for the join table) | the same two list fields, plus a model for the join table | you write the join table as a model yourself. Example below |
-| `@id`, `@unique`, `@default`, `@relation`, `@map`, `@@map`, `@@index`, `@@id`, `@@unique` | unchanged | |
+| `@id`, `@unique`, `@default`, `@relation`, `@map`, `@@map`, `@@index`, `@@id`, `@@unique` | unchanged | a model without `@@map` names its table after the model, exactly as written, as in Prisma ORM 7 |
 | a required relation field over an optional foreign key, or the reverse | rejected | since `8.0.0-rc.10`, `contract emit` reports `PSL_RELATION_NULLABILITY_MISMATCH`. Give the relation field and its `@relation(fields: [...])` columns the same `?`, or none |
 
 :::note[DateTime values and Node.js versions]
@@ -75,6 +77,8 @@ Homebrew's build of Node.js 26 leaves `Temporal` out, so check with `node -p "ty
 A many-to-many relation keeps the two list fields and adds a model for the join table. Its primary key must be the two foreign keys and nothing else, as `@@id([postId, tagId])` below:
 
 ```prisma title="src/prisma/contract.prisma"
+// use prisma-8
+
 model Post {
   id   Int    @id @default(autoincrement())
   tags Tag[]
@@ -118,7 +122,7 @@ export default definePrismaConfig({
 
 The `orm` section takes these keys:
 
-- `contract`: the path to your contract file.
+- `contract`: the path to your contract file, or a glob for a [contract in several files](/orm/contract-authoring/psl-syntax#split-the-contract-across-several-files). On PostgreSQL it can also be `prisma7Schema("prisma/schema.prisma")`, which reads your Prisma ORM 7 schema as it is; see [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema).
 - `db`: the connection.
 - `output` (optional): where `contract.json` and `contract.d.ts` are written. Default: next to the contract.
 - `extensions` (optional): database extensions, for example `extensions: [pgvector]` with `import pgvector from "@prisma/orm-extension-pgvector/control"`. See [Using extensions](/orm/extensions/using-extensions).
@@ -178,7 +182,7 @@ export const db = postgres<Contract>({
 `db` has these parts:
 
 - `db.orm`: your models, by model name (`db.orm.public.User`).
-- `db.sql`: your tables, by table name (`db.sql.public.user`; the table name is the model name with a lowercase first letter, unless you set `@@map`). You need it only for raw SQL.
+- `db.sql`: your tables, by table name (`db.sql.public.User`; the table name is the model name, unless you set `@@map`). You need it only for raw SQL.
 - `db.raw.sql`: writes a raw SQL query.
 - `db.runtime()`: the connection. It runs raw queries.
 - `db.transaction`: runs several queries in one transaction.
@@ -206,6 +210,8 @@ A query is a chain of calls that you `await` as a whole. The last call (`.all()`
 | `create({ data: { ... } })` | `.create({ ... })`, without the `data` wrapper |
 | `create({ data: { ..., posts: { create: [...] } } })` | `.create({ ..., posts: (p) => p.create([...]) })`; `connect` works the same way |
 | `createMany({ data: [...] })` | `.createAll([...])` to get the rows back, or `.createAndCount([...])` to get a count |
+| `createMany({ data: [...], skipDuplicates: true })` | `.createAll([...], { onConflict: "skip" })` or `.createAndCount([...], { onConflict: "skip" })` |
+| `where: { title: { search: "cat & dog" } }`, with the `fullTextSearchPostgres` preview feature | `.where((p) => p.title.fullTextMatches(toTsquery("cat & dog")))`, with `toTsquery` from `@prisma/orm-postgres/target/full-text`. `websearchToTsquery(input)` reads search-box text. Sort by relevance with `.orderBy((p) => p.title.fullTextRank(query).desc())`, where `query` is the same `toTsquery(...)` value. Add `@@fullTextIndex([title], name: "...")` to the model so PostgreSQL can use an index. See [Full-text search](/orm/reference/orm-client#full-text-search) |
 | `update({ where, data })` | `.where(...).update({ ... })` |
 | `updateMany({ where, data })` | `.where(...).updateAll({ ... })` for the rows, or `.updateAndCount({ ... })` for a count |
 | `delete({ where })` | `.where(...).delete()` |
@@ -266,20 +272,20 @@ await prisma.$executeRaw`UPDATE "User" SET active = false WHERE id = ${id}`;
 
 ```ts title="Prisma ORM 8"
 // A query that returns rows must say what type each column is.
-const user = db.sql.public.user;
-const select = db.raw.sql`SELECT id, email FROM "user" WHERE active = true`
+const user = db.sql.public.User;
+const select = db.raw.sql`SELECT id, email FROM "User" WHERE active = true`
   .returnsRow({ id: user.columns.id, email: user.columns.email })
   .build();
 const rows = await db.runtime().query(select);
 
 // A statement that changes rows: ask for the count.
-const update = db.raw.sql`UPDATE "user" SET active = false WHERE id = ${id}`
+const update = db.raw.sql`UPDATE "User" SET active = false WHERE id = ${id}`
   .affectedCount()
   .build();
 await db.runtime().execute(update);
 ```
 
-The table is `user`, not `User`: Prisma ORM 8 names a table after its model with a lowercase first letter, unless the model sets `@@map`. Every raw query that returns rows needs `.returnsRow(...)` with a type per column, and you take the type from the table, as above. For a computed column, write the type name instead, such as `pg/int4@1` or `pg/text@1`; the `@1` is a version number and is always `1` today. [Raw queries](/orm/reference/raw-queries) lists the names. Finish the query with `.build()` and pass it to `db.runtime().query()` for rows or `db.runtime().execute()` for a count.
+The table is `User`, as in Prisma ORM 7: a model without `@@map` names its table after the model. Every raw query that returns rows needs `.returnsRow(...)` with a type per column, and you take the type from the table, as above. For a computed column, write the type name instead, such as `pg/int4@1` or `pg/text@1`; the `@1` is a version number and is always `1` today. [Raw queries](/orm/reference/raw-queries) lists the names. Finish the query with `.build()` and pass it to `db.runtime().query()` for rows or `db.runtime().execute()` for a count.
 
 ### Transaction
 
@@ -304,7 +310,7 @@ Prisma ORM 7 features that have no direct form in Prisma ORM 8, with what to do
 
 | Prisma ORM 7 feature | Status | What to do instead |
 | --- | --- | --- |
-| `skipDuplicates` on `createMany` | not available | `createMany` itself is `.createAll([...])` or `.createAndCount([...])` (see the queries table). To skip rows that already exist, `.upsert({ create, update: {}, conflictOn })` one row at a time; there is no batch form |
+| `skipDuplicates` on `createMany` | available in a different form | `.createAll(rows, { onConflict: "skip" })` or `.createAndCount(rows, { onConflict: "skip" })` skips each row that collides with a unique constraint; add `conflictOn: ["email"]` to name the constraint. `createAll` returns only the rows the database wrote. Run `prisma contract emit` once before you use it, because a contract emitted before `8.0.0-rc.12` does not list the capability it needs |
 | `{ increment: n }` / `{ decrement: n }` in an update | not available | write the arithmetic as raw SQL (see the example above), or read the value and write it back inside `db.transaction(...)` |
 | `findUniqueOrThrow` / `findFirstOrThrow` | not available on the query | the usual form is `.first()` and a `null` check. If you want the throw, write `await db.orm.public.User.where({ id }).all().firstOrThrow()`. It throws an error with code `RUNTIME.NO_ROWS` when nothing matches. Avoid it on a filter that can match many rows; it reads them all first |
 | `mode: "insensitive"` | available in a different form | on PostgreSQL, `.ilike("%alice%")` on a text field. You write the `%` wildcards yourself |
@@ -320,7 +326,7 @@ Prisma ORM 7 features that have no direct form in Prisma ORM 8, with what to do
 Also not available today:
 
 - Nested writes other than `create`, `connect`, and `disconnect`: `connectOrCreate`, nested `update`, `updateMany`, `upsert`, `delete`, `deleteMany`, and `set` on a relation. Change the related rows through their own model instead, for example `db.orm.public.Post.where({ authorId }).updateAll({ ... })`, inside `db.transaction(...)` if it must be atomic.
-- The list filters `has`, `hasEvery`, `hasSome`, and `isEmpty` on `String[]` and other list fields. The fields themselves work; filter on them with raw SQL, for example ``db.raw.sql`SELECT id FROM post WHERE ${tag} = ANY(tags)` ``.
+- The list filters `has`, `hasEvery`, `hasSome`, and `isEmpty` on `String[]` and other list fields. The fields themselves work; filter on them with raw SQL, for example ``db.raw.sql`SELECT id FROM "Post" WHERE ${tag} = ANY(tags)` ``.
 - Transaction options: `isolationLevel`, `timeout`, `maxWait`, and transactions inside transactions.
 - `omit`, `relationLoadStrategy`, `Prisma.skip`, and the automatic batching of `findUnique` calls.
 - The `P2002` / `P2025` style error codes. Errors carry a `code` such as `RUNTIME.NO_ROWS` instead, and a database error such as a unique-constraint violation carries the standard SQL state code in `error.sqlState` (`23505` for a unique violation, on every database), so catch it with `if (error instanceof Error && "sqlState" in error && error.sqlState === "23505")`. See the [error reference](/orm/reference/error-reference).
diff --git a/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx b/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx
index 8150d89f97..a793808427 100644
--- a/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx
@@ -20,7 +20,7 @@ The extension only works on `.prisma` files whose first non-blank line is:
 // use prisma-8
 ```
 
-A file without that line gets no error checking, no completion, and no formatting. [`orm init`](/cli/orm-init) and [`contract infer`](/cli/contract-infer) write the line for you. Add it yourself when you create a contract by hand.
+A file without that line gets no error checking, no completion, and no formatting, and [`prisma contract emit`](/cli/contract-emit) leaves it out of the contract. [`orm init`](/cli/orm-init) and [`contract infer`](/cli/contract-infer) write the line for you. Add it yourself when you create a contract by hand.
 
 Contracts from before `8.0.0-rc.10` start with `// use prisma-next`, the preview's name. The extension still accepts that line, and nothing breaks if you leave it. When you format the file, the extension rewrites that line to `// use prisma-8`.
 
@@ -28,12 +28,11 @@ Contracts from before `8.0.0-rc.10` start with `// use prisma-next`, the preview
 
 - **Errors** appear inline as you type. They are the same errors you would get from [`prisma contract emit`](/cli/contract-emit), the command that checks the contract and writes `contract.json` and `contract.d.ts`.
 - **Formatting** reformats the whole file. In VS Code, run **Format Document**.
-- **Completion** starts when you type `@` or `@@`. The editor lists attribute names such as `@id`, `@default`, and `@@index`. Inside an attribute, it lists the names of the arguments you have not filled in yet. When an attribute has required arguments, VS Code inserts them as placeholders you tab through.
+- **Completion** starts when you type `@` or `@@`. The editor lists attribute names such as `@id`, `@default`, and `@@index`, each with a short description. Inside an attribute, it lists the names of the arguments you have not filled in yet, and it suggests values for them, including values nested inside lists, records, and function calls. Where an attribute expects a field name, it suggests only scalar fields. When an attribute has required arguments, VS Code inserts them as placeholders named after each argument, which you tab through.
+- **Signature help** appears when you type `(` or `,` inside an attribute. It shows the attribute's arguments and describes the one you are typing.
 
 The list of attributes comes from your `prisma.config.ts`: the database it declares and the Prisma extension packs listed under `extensions`; see [Extension packs](/cli/configuration#extension-packs) for that config. Extension packs are add-on packages for database features such as [pgvector](/orm/extensions/using-extensions). If your config lists the pgvector pack, the editor also suggests pgvector's attributes. No database connection is needed.
 
-The editor does not yet suggest argument values. Type `@default(` and it does not offer `autoincrement()` or the other values you could put there.
-
 ## False errors after an upgrade
 
 If the editor marks attributes as errors in a contract that `prisma contract emit` accepts, the likely cause is an old ORM package. That is the `@prisma/orm-postgres`, `@prisma/orm-mongo`, or `@prisma/orm-sqlite` package your project installs for its database. Check the installed version:
diff --git a/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx b/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
index b0eac04486..68c24d6e35 100644
--- a/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
@@ -6,7 +6,7 @@ metaTitle: Author the Prisma ORM contract in PSL
 metaDescription: 'Learn how to write a Prisma ORM contract in the Prisma schema language, including named types, enums, value objects, relations, and extension types.'
 ---
 
-PSL, the Prisma Schema Language, is the preferred way to author [your contract](/orm/contract-authoring/the-data-contract), the `contract.prisma` file that replaced `schema.prisma`. You write one file, usually `src/prisma/contract.prisma`, and [`npx prisma contract emit`](/cli/contract-emit) writes `contract.json` and `contract.d.ts` beside it. If you know the Prisma schema language, most of a contract file reads exactly as you expect. The five biggest additions are listed here, and the rest of the page is the full reference for every attribute and block:
+PSL, the Prisma Schema Language, is the preferred way to author [your contract](/orm/contract-authoring/the-data-contract), the `contract.prisma` file that replaced `schema.prisma`. You usually write one file, `src/prisma/contract.prisma`, or [split it into several](#split-the-contract-across-several-files), and [`npx prisma contract emit`](/cli/contract-emit) writes `contract.json` and `contract.d.ts` beside it. If you know the Prisma schema language, most of a contract file reads exactly as you expect. The five biggest additions are listed here, and the rest of the page is the full reference for every attribute and block:
 
 - named types: give a database column type a name you can reuse on many fields.
 - enums: an enum can now say how its values are stored, and what each member stores.
@@ -18,7 +18,7 @@ The `datasource` and `generator` blocks are gone: the connection URL and the fil
 
 ## A complete contract
 
-Every contract starts with `// use prisma-8`, so keep that line at the top.
+Every contract file starts with `// use prisma-8`. `contract emit` reads only the files that start with this line, so keep it at the top. A file without it is left out of the contract without a warning, and when no file has it, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. `// use prisma-next`, from earlier release candidates, still counts.
 
 ```prisma title="src/prisma/contract.prisma" tab="PostgreSQL"
 // use prisma-8
@@ -107,7 +107,7 @@ model Post {
 
 ## Point the config at the schema
 
-The config's `contract` path names the one file Prisma ORM reads: it takes a single path, so there is no folder of contract files. If the path ends in `.prisma`, Prisma ORM reads it as PSL, and if it ends in `.ts`, as TypeScript. The `db` key holds the connection URL:
+The config's `contract` path names the file Prisma ORM reads. If the path ends in `.prisma`, Prisma ORM reads it as PSL, and if it ends in `.ts`, as TypeScript. The `db` key holds the connection URL:
 
 ```typescript title="prisma.config.ts"
 import 'dotenv/config';
@@ -126,15 +126,19 @@ export default definePrismaConfig({
 
 `npx prisma orm init` writes a config like this, `DATABASE_URL` included. The import chooses the database: `@prisma/orm-postgres/config` makes it a PostgreSQL project, and `@prisma/orm-mongo/config` a MongoDB one. [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7#schema) lists the other keys.
 
+### Split the contract across several files
+
+Set `contract` to a glob, such as `"./src/prisma/**/*.prisma"`, to write the contract in several files. Every matching file that starts with `// use prisma-8` becomes part of one contract, and a file you add later joins it on the next `contract emit`, with no change to the config. A model in one file can refer to a model in another. `contract emit` writes `contract.json` and `contract.d.ts` into the fixed part of the glob, here `./src/prisma/`. See [Configuration](/cli/configuration#split-the-schema-across-several-files).
+
 ## Models and fields
 
-Models declare fields with a type, an optional `?` marker, and attributes. [Scalar fields](/orm/data-modeling#scalar-fields) lists the types a field can hold, among them `String`, `Int`, `Boolean`, `Decimal`, `DateTime`, `Json`, and `Bytes`. You can write a PostgreSQL type wherever you would write `String` or `DateTime`. The PostgreSQL types you can write are `VarChar`, `Char`, `Numeric`, `Timestamp`, `Timestamptz`, `Time`, `Timetz`, `Date`, `Uuid`, `Inet`, `SmallInt`, and `Real`, plus `DateString`, `TimestampString`, `TimestamptzString`, and `TimeString`, which store the same columns but read back as text. On PostgreSQL, plain `String` is a `text` column, `Int` is `int4`, and `DateTime` is `timestamptz`.
+Models declare fields with a type, an optional `?` marker, and attributes. [Scalar fields](/orm/data-modeling#scalar-fields) lists the types a field can hold, among them `String`, `Int`, `Boolean`, `Decimal`, `DateTime`, `Json`, and `Bytes`. You can write a PostgreSQL type wherever you would write `String` or `DateTime`. The PostgreSQL types you can write are `VarChar`, `Char`, `Numeric`, `Timestamp`, `Timestamptz`, `Time`, `Timetz`, `Date`, `Uuid`, `Inet`, `SmallInt`, and `Real`, plus `DateString`, `TimestampString`, `TimestamptzString`, and `TimeString`, which store the same columns but read back as text, and `TimestamptzJsDate`, a `timestamptz` column that reads and writes a JavaScript `Date` and needs no `Temporal` polyfill. A `Date` keeps only milliseconds. On PostgreSQL, plain `String` is a `text` column, `Int` is `int4`, and `DateTime` is `timestamptz`.
 
 - `@id` marks the primary key. `@@id([a, b])` declares a composite key.
 - `@unique` adds a unique constraint on one field. `@@unique([userId, title])` adds one across several fields.
 - `@@index([...])` declares a secondary index.
-- `@default(...)` sets a default. Database defaults are a literal, `@default(now())`, `@default(autoincrement())`, or `@default(dbgenerated("nextval('user_serial_seq')"))`, whose string is any SQL expression; the database fills them in. Generated defaults are `uuid()` (a version 4 UUID, the same as `uuid(4)`), `uuid(7)`, `cuid(2)`, `ulid()`, and `nanoid()`, where `nanoid(21)` sets the length to any value from 2 to 255; Prisma ORM computes them when it writes the row, and the database will not fill them in for you, so a row written by raw SQL or another application gets no value. Prisma ORM 7's `cuid()` is rejected with a hint to use `cuid(2)`.
-- `@map("column_name")` sets a field's column name in the database. `@@map("table_name")` sets the table or collection name when it differs from the model name.
+- `@default(...)` sets a default. Database defaults are a literal, `@default(now())`, `@default(autoincrement())`, or a SQL expression written as a `sql` tagged literal, such as ``@default(sql`gen_random_uuid()`)``; the database fills them in. See [Default values](#default-values) for how to write each kind of literal. Generated defaults are `uuid()` (a version 4 UUID, the same as `uuid(4)`), `uuid(7)`, `cuid(2)`, `ulid()`, and `nanoid()`, where `nanoid(21)` sets the length to any value from 2 to 255; Prisma ORM computes them when it writes the row, and the database will not fill them in for you, so a row written by raw SQL or another application gets no value. Prisma ORM 7's `cuid()` is rejected with a hint to use `cuid(2)`.
+- `@map("column_name")` sets a field's column name in the database. `@@map("table_name")` sets the table or collection name when it differs from the model name. Without `@@map`, the table or collection has the model's name exactly as written, so `model UserProfile` is the table `"UserProfile"`.
 - `@@check(expression: "total >= 0", name: "order_total_positive")` adds a check constraint of your own to the table. See [Check constraints](#check-constraints).
 - `@@control(observed)` says how far Prisma ORM manages the table. See [Control policy](#control-policy).
 
@@ -148,7 +152,7 @@ model Post {
 }
 ```
 
-Prisma ORM sets the field to the current time on every create and update. `temporal` is built in, so you do not import it or declare it. On PostgreSQL the column is `timestamptz`, and you can still set the field yourself on a write. `temporal.createdAt()` sets the field once, when the row is created.
+Prisma ORM sets the field to the current time on every create and update. `temporal` is built in, so you do not import it or declare it. On PostgreSQL the column is `timestamptz`, and you can still set the field yourself on a write. `temporal.createdAt()` sets the field once, when the row is created. Both take the time from your application's clock, not from the database, so the column has no database default, and a row you insert with raw SQL must supply the value. For a value the database generates, use `DateTime @default(now())` instead. `temporal.createdAtJsDate()` and `temporal.updatedAtJsDate()` do the same with a JavaScript `Date` in place of a `Temporal` value. The `Temporal` presets need a global `Temporal` for writes as well as reads, so load a polyfill such as `temporal-polyfill/global` when your runtime has none.
 
 How IDs map differs by database:
 
@@ -166,6 +170,31 @@ model User {
 
 On PostgreSQL the primary key is an ordinary column, so pick its type and default yourself. On MongoDB the primary key is the document's `_id`, so type it `ObjectId` and map it to `_id`.
 
+### Default values
+
+A value you write in `@default(...)` has a data type, and how you write it decides which one. A column takes the value only if its own data type accepts that type; otherwise `contract emit` fails with `PSL_DEFAULT_TYPE_INCOMPATIBLE` and names the types the column accepts. A quoted string is text, so it does not work as a default for a JSON, decimal, or floating-point column:
+
+```prisma title="src/prisma/contract.prisma (excerpt)"
+model Account {
+  id        String   @id @default(sql`gen_random_uuid()`)
+  meta      Jsonb    @default(json`{ "plan": "free" }`)
+  tags      Jsonb    @default(json`[1, 2]`)
+  price     Decimal  @default(1.50)
+  ratio     Float    @default(NaN)
+  role      String   @default("member")
+  createdAt DateTime @default(now())
+  expiresAt DateTime @default(sql`(now() + '00:03:00'::interval)`)
+}
+```
+
+- A JSON default is a `json` tagged literal, whose body is the JSON document itself. A JSON list on a column that holds one JSON value is also one `json` literal, as `tags` shows.
+- A decimal default is a bare number, and it keeps every digit you write, trailing zeros included.
+- `NaN`, `Infinity`, and `-Infinity` are written without quotes.
+- A text default, or the value of an enum member, is a quoted string.
+- Any other SQL expression is a `sql` tagged literal, and it goes into the column default exactly as written. Write the current time as `now()` and a sequence as `autoincrement()`, not as `` sql`now()` `` or `` sql`autoincrement()` ``, which are refused.
+
+Prisma ORM 7's `dbgenerated("...")` is not accepted, and `contract emit` reports `PSL_UNKNOWN_DEFAULT_FUNCTION` with the replacement. [`contract infer`](/cli/contract-infer) writes every default in these forms.
+
 ### Indexes
 
 `@@index([...])` takes a list of fields, and on PostgreSQL the named arguments below. Either the list or `expression:` is required, and an `expression:` index needs a `name:`:
@@ -186,6 +215,21 @@ model User {
 
 The `expression:` and `where:` strings go into the SQL as written, so they use column names, not field names (they differ when a field has `@map`), and you quote the names yourself. Prisma ORM does not check the SQL until the migration runs. On MongoDB, `@@index` takes different arguments; see [MongoDB indexes](#mongodb-indexes).
 
+### Full-text indexes
+
+`@@fullTextIndex([field])` creates the GIN index that PostgreSQL [full-text search](/orm/reference/orm-client#full-text-search) uses. It takes one text field, and a `name:` or a `map:`:
+
+```prisma title="src/prisma/contract.prisma (excerpt)"
+model Post {
+  id    Int    @id
+  title String
+
+  @@fullTextIndex([title], name: "post_title_search")
+}
+```
+
+`language:` sets the text-search configuration and defaults to `english`. Give the index and the query operations the same language, because PostgreSQL does not use the index for a query in another language. `where:` makes it a partial index, as on `@@index`. A `pg.enum(...)` column cannot have a full-text index. PostgreSQL only.
+
 ### Check constraints
 
 `@@check` adds a check constraint you write yourself, on top of the ones Prisma ORM generates for enum and list columns:
@@ -279,6 +323,8 @@ model User {
 
 Each member needs a value. `pg` comes with `@prisma/orm-postgres`, so there is nothing to import. You do not create the PostgreSQL type yourself: `npx prisma migration plan` includes the `CREATE TYPE`.
 
+PostgreSQL has no `LIKE`, `ILIKE`, or text search for an `enum` type, so a `pg.enum(...)` column has no text operations: `like`, `ilike`, and the full-text operations are type errors on it. Compare it with `eq` or `in` instead. An `enum` block stored as text, such as `Priority` above, keeps every text operation.
+
 ## Value objects
 
 A `type` block declares a value object: a structured value stored inside its parent row, with no table of its own.
@@ -382,7 +428,7 @@ namespace audit {
 }
 ```
 
-Models outside any block are in `public`. In queries, the block name is the segment after `db.orm`, so this model is `db.orm.audit.AuditLog`. A relation can point at a model that another extension pack owns in a different schema, written `<pack>:<schema>.<Model>`, for example `supabase:auth.AuthUser`; the [Supabase extension](/orm/extensions) documents that form.
+Models outside any block are in `public`. In queries, the block name is the segment after `db.orm`, so this model is `db.orm.audit.AuditLog`. Two `namespace` blocks with the same name in one file are one namespace, so you can open a block again further down the file. A relation can point at a model that another extension pack owns in a different schema, written `<pack>:<schema>.<Model>`, for example `supabase:auth.AuthUser`; the [Supabase extension](/orm/extensions) documents that form.
 
 ## Row-level security
 
@@ -464,7 +510,7 @@ model Bug {
 }
 ```
 
-A field name is written bare, as `type` is in `@@discriminator(type)`, and a database name is quoted, as in `@@map("task")`. Rows whose `type` column holds `"bug"` are `Bug` records. A variant reuses its base model's fields, so a `Bug` has `id`, `title`, and `type` as well as `severity` and `stepsToRepro`. A variant does not declare an `@id` of its own: it takes the base model's primary key.
+A field name is written bare, as `type` is in `@@discriminator(type)`, and a database name is quoted, as in `@@map("task")`. Rows whose `type` column holds `"bug"` are `Bug` records. A variant reuses its base model's fields, so a `Bug` has `id`, `title`, and `type` as well as `severity` and `stepsToRepro`. The base model can be declared before or after its variants. A variant does not declare an `@id` of its own: it takes the base model's primary key.
 
 You query a variant through the base model: `db.orm.public.Task.variant('Bug')` returns the `Bug` rows only, and `public` here is the PostgreSQL schema. Writing a row of a variant starts with the same `variant('Bug')` call. See [`variant()`](/orm/reference/orm-client#variant).
 
@@ -488,6 +534,8 @@ import pgvector from "@prisma/orm-extension-pgvector/control";
 ```
 
 ```prisma title="src/prisma/contract.prisma"
+// use prisma-8
+
 types {
   Embedding1536 = pgvector.Vector(1536)
 }
diff --git a/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx b/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx
index 5a62786f01..b298ed4b45 100644
--- a/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx
@@ -48,8 +48,8 @@ An abridged `contract.json` for a `User` and `Post` schema:
   "target": "postgres",
   "profileHash": "…",
   "roots": {
-    "post": { "model": "Post", "namespace": "public" },
-    "user": { "model": "User", "namespace": "public" }
+    "Post": { "model": "Post", "namespace": "public" },
+    "User": { "model": "User", "namespace": "public" }
   },
   "domain": {
     "namespaces": {
@@ -63,7 +63,7 @@ An abridged `contract.json` for a `User` and `Post` schema:
             "storage": {
               "fields": { "email": { "column": "email" }, "id": { "column": "id" } },
               "namespaceId": "public",
-              "table": "user"
+              "table": "User"
             }
           }
         }
@@ -75,7 +75,7 @@ An abridged `contract.json` for a `User` and `Post` schema:
       "public": {
         "entries": {
           "table": {
-            "user": {
+            "User": {
               "columns": {
                 "email": { "codecId": "pg/text@1", "nativeType": "text", "nullable": false },
                 "id": { "codecId": "pg/uuid@1", "nativeType": "uuid", "nullable": false }
@@ -95,7 +95,7 @@ An abridged `contract.json` for a `User` and `Post` schema:
 The sections, top to bottom:
 
 - **`schemaVersion`, `targetFamily`, `target`**: the contract format version, whether the database is SQL or MongoDB, and which database this contract targets.
-- **`roots`**: one entry per table that stores a model. The key is the name of that table, so for a model `User` mapped to a table `users` the key is `users`. The value names the model. The [ORM reference](/orm/reference) covers both ways of reaching it, `db.sql.public.user` by table name and `db.orm.public.User` by model name.
+- **`roots`**: one entry per table that stores a model. The key is the name of that table, so for a model `User` mapped to a table `users` the key is `users`. The value names the model. The [ORM reference](/orm/reference) covers both ways of reaching it, `db.sql.public.User` by table name and `db.orm.public.User` by model name. The two names are the same here because the model sets no `@@map`.
 - **`domain` and `storage`**: your application's view, then the database's view. Each scalar field in `domain` records whether it is nullable and its `codecId`. `nativeType` is the column type in the database. `codecId` names how Prisma ORM reads and writes the value, the PostgreSQL type plus a version. `storage` holds the tables with their columns, keys, indexes, constraints, and enum values. `prisma db verify` compares it to the live database.
 - **`capabilities`**: which database features this contract can use. `npx prisma contract emit` collects them from the adapter for your database and from the packages listed in `extensions: [...]` in `prisma.config.ts`, the config file `prisma orm init` writes. The query APIs check them before building a query that needs one. See [supported database features](/orm/contract-authoring/capabilities) and [extension types](/orm/contract-authoring/psl-syntax#extension-types).
 
diff --git a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
index f923189284..725a023e32 100644
--- a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
@@ -25,7 +25,7 @@ model Post {
 }
 ```
 
-`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema. The CLI does not need this line, but the editor extension looks for it before it checks, completes, or formats the file, so keep it. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
+`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema, and every `.prisma` contract file needs it. `contract emit` reads only the files that start with this line and leaves any other file out of the contract without a warning. When no file has it, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. The editor extension also looks for the line before it checks, completes, or formats the file. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
 
 `npx prisma contract emit` turns this file into two files that the CLI and your application read: `contract.json` and `contract.d.ts`. Your queries are type-checked against the contract, migrations are planned as changes to it, and `npx prisma db verify` checks a live database against it.
 
@@ -64,7 +64,7 @@ export default definePrismaConfig({
 
 To start a new project, run `npm create prisma@latest -- my-app`. To add Prisma ORM 8 to a project that has no Prisma ORM at all, run `npx prisma orm init`. If you already have a Prisma ORM 7 `schema.prisma`, follow the [PostgreSQL upgrade guide](/guides/upgrade-prisma-orm/postgresql) instead, and [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7) lists what changed. Both `npm create prisma@latest` and `npx prisma orm init` write `prisma.config.ts`, the contract file, and `src/prisma/db.ts`, and install the database package.
 
-The contract file is either a PSL file (`contract.prisma`) or a TypeScript file (`contract.ts`). The file extension selects the authoring mode, so to author in TypeScript you point `contract` at `./src/prisma/contract.ts`. Both modes describe the same things: models with fields and relations, the tables and columns they map to, named types, enums, and any types that [extension packages](/orm/contract-authoring/psl-syntax#extension-types) add. Extension packages are npm packages that add field types and database features, such as pgvector, a PostgreSQL extension for vector columns.
+The contract file is either a PSL file (`contract.prisma`) or a TypeScript file (`contract.ts`). The file extension selects the authoring mode, so to author in TypeScript you point `contract` at `./src/prisma/contract.ts`. A PSL contract can also span several files, when `contract` is a glob such as `./src/prisma/**/*.prisma`; see [Split the schema across several files](/cli/configuration#split-the-schema-across-several-files). Both modes describe the same things: models with fields and relations, the tables and columns they map to, named types, enums, and any types that [extension packages](/orm/contract-authoring/psl-syntax#extension-types) add. Extension packages are npm packages that add field types and database features, such as pgvector, a PostgreSQL extension for vector columns.
 
 After every change to the contract, run these three commands:
 
@@ -84,7 +84,7 @@ npx prisma db migrate
 
 Define models with the **[TypeScript builder](/orm/contract-authoring/typescript-schema-builder)** instead when you want to build them with code: reach for it when model definitions must be composed, generated, or shared as ordinary TypeScript modules. That page shows what a `contract.ts` file looks like.
 
-Both modes produce the same contract, so migrations, database checks, and `db` behave the same no matter which mode you write. A project has exactly one contract file, so do not keep both a `contract.prisma` and a `contract.ts`: the config names one file and Prisma ORM reads only that one, so edits to the other file do nothing. To switch modes, change the path in `contract` and delete the old file.
+Both modes produce the same contract, so migrations, database checks, and `db` behave the same no matter which mode you write. A project has exactly one contract source, so do not keep both a `contract.prisma` and a `contract.ts`: the config names one source and Prisma ORM reads only that one, so edits to the other file do nothing. To switch modes, change the path in `contract` and delete the old file.
 
 ## What the contract contains
 
diff --git a/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx b/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
index 85976593a7..a3c02d5f93 100644
--- a/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
@@ -199,14 +199,14 @@ The examples below use the PostgreSQL builder.
 
 There is no helper for a date without a time, or a time without a date. For a date-only column, name the type yourself: `field.column({ codecId: "pg/date-temporal@1", nativeType: "date" } as const)`. `field.column(...)` and the chained `.column(...)` below are different calls: `field.column(descriptor)` builds a field from a type description, and `.column(name)` on an existing field sets its column name. Extension packs add more helpers of their own.
 
-For a primary key whose value your app generates, use `field.id.uuidv4String()`, `field.id.uuidv7String()`, `field.id.ulid()`, `field.id.nanoid()`, `field.id.cuid2()`, or `field.id.ksuid()`. They all generate the ID in your app, and `uuidv4String` is the common choice. Each marks the field as the primary key for you, and `field.id.uuidv4Native()` and `field.id.uuidv7Native()` do the same in a `uuid` column. There is no auto-increment helper, so use one of those `field.id.*` helpers. For a key the database generates instead, write `field.uuidNative().defaultSql("gen_random_uuid()").id()`.
+For a primary key whose value your app generates, use `field.id.uuidv4String()`, `field.id.uuidv7String()`, `field.id.ulid()`, `field.id.nanoid()`, `field.id.cuid2()`, or `field.id.ksuid()`. They all generate the ID in your app, and `uuidv4String` is the common choice. Each marks the field as the primary key for you, and `field.id.uuidv4Native()` and `field.id.uuidv7Native()` do the same in a `uuid` column. There is no auto-increment helper, so use one of those `field.id.*` helpers. For a key the database generates instead, write ``field.uuidNative().default(sql`gen_random_uuid()`).id()``, with `sql` imported from `@prisma/orm-postgres/contract-builder`.
 
-`field.temporal.createdAt()` fills the column with `now()` when the row is created, while `field.temporal.updatedAt()` fills it on every create and every update, and Prisma ORM sets it in the client, not with a database trigger. `field.namedType(x)` takes an enum or a type from an extension pack.
+`field.temporal.createdAt()` sets the column to the current time when the row is created, while `field.temporal.updatedAt()` sets it on every create and every update. Prisma ORM sets both in the client, from your application's clock, so the column has no database default, and a row you insert with raw SQL must supply the value. For a value the database generates, use `field.dateTime().default(now())` instead. `field.temporal.timestamptzJsDate()` is a `timestamptz` column that reads and writes a JavaScript `Date`, with no `Temporal` polyfill, and `field.temporal.createdAtJsDate()` and `field.temporal.updatedAtJsDate()` are the matching presets. `field.namedType(x)` takes an enum or a type from an extension pack.
 
 Every field builder supports chained modifiers:
 
 - `.optional()` makes the field nullable.
-- `.default(value)` sets a literal default. `.defaultSql(expression)` sets a default the database computes, and the argument is a SQL expression as a string: `.defaultSql("now()")`.
+- `.default(value)` sets a literal default. It also takes a default the database computes: `.default(now())`, `.default(autoincrement())`, or any other SQL expression as a `sql` template, such as ``.default(sql`gen_random_uuid()`)``. Import `now`, `autoincrement`, and `sql` from `@prisma/orm-postgres/contract-builder`. `` sql`now()` `` and `` sql`autoincrement()` `` are refused; use the named helpers. `.defaultSql(expression)` still works but is deprecated, and it will be removed in `8.0.0`.
 - `.unique()` adds a unique constraint. `.id()` marks the primary key, for a key that is not generated, such as an integer you set yourself.
 - `.column("column_name")` sets the column name in the database when it differs from the field name.
 - `.many()` makes the field a list, stored as a PostgreSQL array column such as `text[]`. A list column gets a check constraint that rejects `NULL` elements.
@@ -265,7 +265,7 @@ Prisma ORM does not check that the column types on the two sides of a relation m
 
 ## Storage mapping
 
-`.sql(...)` maps a model to its table, and the object form covers the common case: `User.sql({ table: "user" })`.
+`.sql(...)` maps a model to its table, and the object form covers the common case: `User.sql({ table: "user" })`. Without a `table`, and without the `naming` option, the table has the model's name exactly as written, so `User` is the table `"User"`.
 
 You can chain `.relations(...)`, `.attributes(...)`, and `.sql(...)` in any order, and you can skip any of them, so a model with no relations calls `.sql({ table })` straight after `model(...)`.
 
@@ -293,6 +293,21 @@ indexes: [
 
 The `where` and `expression` strings go into the SQL as written, so they use column names, and you quote them yourself.
 
+The ids, unique constraints, indexes, and foreign keys of one model must all have different names. A name used twice is a type error at `defineContract`.
+
+For PostgreSQL [full-text search](/orm/reference/orm-client#full-text-search), `fullTextIndex` from `@prisma/orm-postgres/contract-builder` creates the GIN index the search operations use. It takes one text column and a `name` or `map`, plus optional `language` and `where`:
+
+```typescript title="src/prisma/contract.ts (excerpt)"
+import { fullTextIndex } from "@prisma/orm-postgres/contract-builder";
+
+Post.sql(({ cols }) => ({
+  table: "post",
+  indexes: [fullTextIndex(cols.title, { name: "post_title_search" })],
+}));
+```
+
+Give the index and the search operations the same `language`, which defaults to `english`; otherwise PostgreSQL does not use the index.
+
 Two more keys go in the same object, in either the object form or the callback form: `checks`, a list of check constraints you write yourself, built with `check` from the package, and `control`, the model's [control policy](#control-policy):
 
 ```typescript
diff --git a/apps/docs/content/docs/orm/core-concepts.mdx b/apps/docs/content/docs/orm/core-concepts.mdx
index 87d313e05c..f0cc4eaab4 100644
--- a/apps/docs/content/docs/orm/core-concepts.mdx
+++ b/apps/docs/content/docs/orm/core-concepts.mdx
@@ -16,6 +16,8 @@ This idea relies upon a small vocabulary which repeats throughout: in the CLI, i
 The contract is your description of the data your application needs: the models, their fields, how they relate, and how they map to database tables or collections. You author it in PSL (the Prisma schema language) in a `.prisma` file, or in TypeScript:
 
 ```prisma title="prisma/contract.prisma"
+// use prisma-8
+
 model User {
   id    Int    @id @default(autoincrement())
   email String @unique
@@ -82,7 +84,7 @@ With the SQL query builder, the two steps are visible in your code:
 ```typescript
 import { db } from "./prisma/db";
 
-const plan = db.sql.public.post
+const plan = db.sql.public.Post
   .select("id", "title", "userId")
   .where((f, fns) => fns.eq(f.published, true))
   .limit(10)
diff --git a/apps/docs/content/docs/orm/data-modeling/index.mdx b/apps/docs/content/docs/orm/data-modeling/index.mdx
index 0a8be0c8ca..ba36a8d8e8 100644
--- a/apps/docs/content/docs/orm/data-modeling/index.mdx
+++ b/apps/docs/content/docs/orm/data-modeling/index.mdx
@@ -56,7 +56,7 @@ model User {
 }
 ```
 
-On MongoDB, the primary key is the document's mandatory `_id` field, and it must be an `ObjectId`. `@map("_id")` gives the field that name in the database. The field takes no `@default`, because MongoDB assigns the id itself when you create a document without one. `@@map("users")` names the collection and is optional: without it, the collection is the model name with a lowercase first letter.
+On MongoDB, the primary key is the document's mandatory `_id` field, and it must be an `ObjectId`. `@map("_id")` gives the field that name in the database. The field takes no `@default`, because MongoDB assigns the id itself when you create a document without one. `@@map("users")` names the collection and is optional: without it, the collection is the model name exactly as written, `User`.
 
 ### Natural keys
 
@@ -145,11 +145,11 @@ A scalar field holds a single value. The common types:
 
 The PostgreSQL names in the table are the column types Prisma ORM creates. `ObjectId` is the only MongoDB-only type.
 
-Three types arrive in your code as something other than a plain JavaScript value. A `Decimal` reaches you as a string, so nothing is rounded through a JavaScript number, and a `Bytes` value reaches you as a `Uint8Array`. A `DateTime` reaches you as a `Temporal.Instant`, the standard JavaScript type for a point in time. `Temporal` is built into Node.js 26.8.2 and later, but Homebrew's build of Node.js 26 leaves it out, so check with `node -p "typeof Temporal"`. If that prints `undefined`, install the `temporal-polyfill` package and add `import "temporal-polyfill/full/global"` to your app's entry file, before any query runs.
+Three types arrive in your code as something other than a plain JavaScript value. A `Decimal` reaches you as a string, so nothing is rounded through a JavaScript number, and a `Bytes` value reaches you as a `Uint8Array`. A `DateTime` reaches you as a `Temporal.Instant`, the standard JavaScript type for a point in time. `Temporal` is built into Node.js 26.8.2 and later, but Homebrew's build of Node.js 26 leaves it out, so check with `node -p "typeof Temporal"`. If that prints `undefined`, install the `temporal-polyfill` package and add `import "temporal-polyfill/full/global"` to your app's entry file, before any query runs. To work with a JavaScript `Date` instead, and need no polyfill, type the field `TimestamptzJsDate` on PostgreSQL. A `Date` keeps only milliseconds.
 
 `Json` and `Jsonb` are two separate types, and they differ in how you can filter on them. On a `Jsonb` field, `.where()` compares the whole value, so you can ask whether the column equals a given document but not whether a key inside it matches. A `Json` field cannot be compared in `.where()` at all, so use `Jsonb` unless you specifically need PostgreSQL's plain `json` column. When you need a path query into the document, reach for [raw SQL](/orm/reference/raw-queries). [Extensions](/orm/extensions) add more types, such as vectors or geometry.
 
-A trailing `?` makes a field optional: `name String?`. A trailing `[]` makes it a list: `tags String[]`.
+A trailing `?` makes a field optional: `name String?`. A trailing `[]` makes it a list: `tags String[]`. A `@default(...)` must be written in a form the field's type accepts, such as ``@default(json`{}`)`` on a `Jsonb` field and `@default(1.50)` on a `Decimal` field; [Default values](/orm/contract-authoring/psl-syntax#default-values) lists them.
 
 A field can also hold one of a fixed set of values. Declare them in an `enum` block:
 
diff --git a/apps/docs/content/docs/orm/data-modeling/mongodb.mdx b/apps/docs/content/docs/orm/data-modeling/mongodb.mdx
index 28a62020d6..e44644205f 100644
--- a/apps/docs/content/docs/orm/data-modeling/mongodb.mdx
+++ b/apps/docs/content/docs/orm/data-modeling/mongodb.mdx
@@ -21,7 +21,7 @@ model User {
 }
 ```
 
-In the contract you call the field `id`, but in TypeScript it is always `_id`, never `id`, because `@map("_id")` sets the name in the database and in your code alike. So you write `user._id` and `where({ _id })`. `@@map("users")` names the collection and is optional: without it the collection takes the model name with a lowercase first letter, so `user`. `@unique` on `email` becomes a unique index when you migrate.
+In the contract you call the field `id`, but in TypeScript it is always `_id`, never `id`, because `@map("_id")` sets the name in the database and in your code alike. So you write `user._id` and `where({ _id })`. `@@map("users")` names the collection and is optional: without it the collection takes the model name exactly as written, so `User`. `@unique` on `email` becomes a unique index when you migrate.
 
 Write `ObjectId` for the key type. That is the contract type only: in TypeScript a document's own `_id` is a plain string, so there is no `ObjectId` to construct. The old `String @db.ObjectId` and `@default(auto())` are no longer allowed.
 
diff --git a/apps/docs/content/docs/orm/extensions/using-extensions.mdx b/apps/docs/content/docs/orm/extensions/using-extensions.mdx
index 4ea7934208..e59110513e 100644
--- a/apps/docs/content/docs/orm/extensions/using-extensions.mdx
+++ b/apps/docs/content/docs/orm/extensions/using-extensions.mdx
@@ -70,6 +70,8 @@ Now that pgvector is in `prisma.config.ts`, `npx prisma contract emit` accepts `
 The `pgvector` in `pgvector.Vector(1536)` is the name the extension registers its types under, and its page in the extension directory lists them. PostGIS, for example, gives you `postgis.Geometry(4326)`.
 
 ```prisma title="src/prisma/contract.prisma"
+// use prisma-8
+
 types {
   Embedding1536 = pgvector.Vector(1536)
 }
@@ -87,7 +89,7 @@ Getting the new column from your contract into your database takes these command
 
 1. `npx prisma contract emit`, so that `contract.json` and `contract.d.ts` pick up the new column. Run it again after every later change to `contract.prisma`.
 2. `npx prisma migration plan`, which writes the extension's own migration into `migrations/`, so commit it along with your other migrations. Skip this and the next command stops with an error whose `code` is `MIGRATION.CONTRACT_SPACE_LAYOUT_VIOLATION`.
-3. `npx prisma db init` on a new database, or `npx prisma db update` on one that already has tables, which [Applying a migration](/orm/migrations/applying-a-migration) covers. This runs the extension's migration and creates the `post` table.
+3. `npx prisma db init` on a new database, or `npx prisma db update` on one that already has tables, which [Applying a migration](/orm/migrations/applying-a-migration) covers. This runs the extension's migration and creates the `Post` table.
 
 The extension's migration is the `CREATE EXTENSION IF NOT EXISTS vector` statement, so you never write that statement yourself, but the PostgreSQL server has to have pgvector available for it to succeed. Both databases the quickstart offers have it: the local Prisma Postgres database that Composer starts, and a Prisma Postgres database from `npx create-db@latest`. A stock PostgreSQL image may not, and then the migration fails on that statement, so install pgvector on the server first, following [pgvector's own instructions](https://github.com/pgvector/pgvector).
 
@@ -105,7 +107,7 @@ In Prisma ORM 8 `create` takes the fields directly, with no `data` wrapper. [Cre
 Searching for the rows closest to a query vector uses the operations the extension adds, and you write that search with the SQL query builder rather than with `db.orm`. In that block:
 
 - `db.orm` is the ORM API, and under it you address a model by the name in your contract, so the model `Post` is `db.orm.public.Post`.
-- `db.sql` is the [SQL query builder](/orm/fundamentals/advanced-queries), and under it you address a table by the name it has in the database, so the same data is `db.sql.public.post`.
+- `db.sql` is the [SQL query builder](/orm/fundamentals/advanced-queries), and under it you address a table by the name it has in the database, so the same data is `db.sql.public.Post`. The two names are the same because the model sets no `@@map`.
 - `db.runtime()` is what runs a built query.
 - `f`, in the callback of each builder method, holds the row's columns.
 - `fns` holds the functions you can call on those columns, including the ones pgvector adds.
@@ -115,7 +117,7 @@ Searching for the rows closest to a query vector uses the operations the extensi
 import { db } from './db';
 
 export async function similaritySearch(queryVector: number[]) {
-  const plan = db.sql.public.post
+  const plan = db.sql.public.Post
     .select('id', 'title')
     .select('distance', (f, fns) => fns.cosineDistance(f.embedding, queryVector))
     .orderBy((f, fns) => fns.cosineDistance(f.embedding, queryVector), { direction: 'asc' })
@@ -204,6 +206,8 @@ export const db = await supabase<Contract>({
 
 `await db.asUser(jwt)` takes the user's Supabase JWT and gives you a client that runs as that user. `db.asAnon()` gives you one that runs as the anonymous role, and `db.asServiceRole()` one that bypasses row-level security. `db` itself has no `orm` or `sql`: those live on the three role-bound clients. The [runnable example](https://github.com/prisma/orm/tree/main/examples/supabase) shows the whole setup in one project.
 
+The extension's contract describes Supabase's `auth` and `storage` tables as they are in a reference Supabase build, supabase/postgres 17.6.1.106, check constraints included. If your build differs, `db verify` reports the difference. When an update to `@prisma/orm-extension-supabase` changes that contract, run `npx prisma db sign` again against every database signed with the earlier version. If you also re-emit your own contract, do that first.
+
 :::
 
 If you would rather read a whole working project than a set of snippets, there is a runnable example for each of these extensions: [pgvector](https://github.com/prisma/orm/tree/main/examples/prisma-8-demo), [PostGIS](https://github.com/prisma/orm/tree/main/examples/prisma-8-postgis-demo), [ParadeDB](https://github.com/prisma/orm/tree/main/examples/paradedb-demo), and [Supabase](https://github.com/prisma/orm/tree/main/examples/supabase).
diff --git a/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx b/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx
index f9feb755d0..1d4a6a81a9 100644
--- a/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx
@@ -22,6 +22,8 @@ model User {
   email String  @unique
   name  String?
   posts Post[]
+
+  @@map("user")
 }
 
 model Post {
@@ -32,12 +34,16 @@ model Post {
   authorId  String
   author    User     @relation(fields: [authorId], references: [id])
   tags      Tag[]
+
+  @@map("post")
 }
 
 model Tag {
   id    String @id @default(cuid(2))
   name  String @unique
   posts Post[]
+
+  @@map("tag")
 }
 
 model PostTag {
@@ -68,7 +74,7 @@ A SQL builder query takes two steps: first you build it, then you run it. You de
 
 ### Build a query and run it
 
-Start from a table with `db.sql.public.<table>`. `db.sql` is the SQL query builder, keyed by table name. A table's name is the model name with a lowercase first letter unless the model sets `@@map`, and column names are the field names unless a field sets `@map`. `public` is the PostgreSQL schema your tables are in, unless the model sits in a `namespace billing { ... }` block in your contract, in which case the path is `db.sql.billing.<table>`.
+Start from a table with `db.sql.public.<table>`. `db.sql` is the SQL query builder, keyed by table name. A table's name is the model's `@@map` value, or the model name exactly as written when the model has no `@@map`, and column names are the field names unless a field sets `@map`. `public` is the PostgreSQL schema your tables are in, unless the model sits in a `namespace billing { ... }` block in your contract, in which case the path is `db.sql.billing.<table>`.
 
 `db.runtime()` is the database connection; call it whenever you run a query. `query()` always resolves to an array of rows, even when the query matches one row.
 
@@ -306,7 +312,7 @@ All MongoDB aggregation happens here: the ORM API has no `.aggregate(...)` on Mo
 
 ### Build a pipeline and run it
 
-Start from a collection with `db.query.from(...)`, which takes the collection name as a string: the model's `@@map` value, or the model name with a lowercase first letter when the model has no `@@map`. The models above set no `@@map` except `PostTag`, so the collections are `user`, `post`, `tag`, and `post_tag`. That is the same name the ORM API uses, as in `db.orm.post`.
+Start from a collection with `db.query.from(...)`, which takes the collection name as a string: the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. Every model above sets `@@map`, so the collections are `user`, `post`, `tag`, and `post_tag`. That is the same name the ORM API uses, as in `db.orm.post`.
 
 `acc` holds the aggregate functions you can use inside `.group(...)`, such as `acc.count()` and `acc.max(f.createdAt)`. In the pipeline builder, fields use their stored names, so the id is `_id` (see the note under the contract above), and `_id` is also the grouping key in `.group(...)`. On MongoDB `db.runtime()` returns a promise, so await it before you run anything. Chain stages, call `.build()`, and run the result:
 
diff --git a/apps/docs/content/docs/orm/fundamentals/reading-data.mdx b/apps/docs/content/docs/orm/fundamentals/reading-data.mdx
index 9f783d4c47..86f199627f 100644
--- a/apps/docs/content/docs/orm/fundamentals/reading-data.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/reading-data.mdx
@@ -175,7 +175,7 @@ const recentPosts = await db.orm.public.Post
 
 ### Filter operators on PostgreSQL
 
-On PostgreSQL, `.where(...)` also accepts a callback for richer comparisons, as in the range example above. The callback receives one object, written `p` here, with a property per field of your model. Each of those fields has `.eq`, `.neq`, `.lt`, `.lte`, `.gt`, `.gte`, `.like`, `.ilike`, `.in([...])`, `.notIn([...])`, `.isNull()`, and `.isNotNull()`. `.like` and `.ilike` take SQL `LIKE` patterns, where `%` matches any run of characters:
+On PostgreSQL, `.where(...)` also accepts a callback for richer comparisons, as in the range example above. The callback receives one object, written `p` here, with a property per field of your model. Each of those fields has `.eq`, `.neq`, `.lt`, `.lte`, `.gt`, `.gte`, `.like`, `.ilike`, `.in([...])`, `.notIn([...])`, `.isNull()`, and `.isNotNull()`, as far as its type supports them: a native enum field (`pg.enum(...)`), for example, has no `.like` or `.ilike`. `.like` and `.ilike` take SQL `LIKE` patterns, where `%` matches any run of characters. For search over words rather than patterns, text fields also have PostgreSQL [full-text search](/orm/reference/orm-client#full-text-search):
 
 ```typescript
 // Case-insensitive text search
diff --git a/apps/docs/content/docs/orm/fundamentals/relations-and-joins.mdx b/apps/docs/content/docs/orm/fundamentals/relations-and-joins.mdx
index 867b31cdcc..cdc93022b8 100644
--- a/apps/docs/content/docs/orm/fundamentals/relations-and-joins.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/relations-and-joins.mdx
@@ -38,7 +38,7 @@ npx prisma orm init                  # a project you already have
 That is the file the examples above import as `./prisma/db`, from a file directly inside `src/`. Here is what the rest of those lines are made of:
 
 - On PostgreSQL the path is `db.orm.<schema>.<ModelName>`. `db.orm` is the model API; `db.sql` and `db.raw.sql` are for SQL. The PostgreSQL schema (not the contract file) is `public` unless you wrap the model in a `namespace` block. Write `namespace billing { model Invoice { ... } }` in your contract and the path becomes `db.orm.billing.Invoice`.
-- On MongoDB there is no schema segment. The path is `db.orm.<collectionName>`. The collection name is the `@@map(...)` on the model, or the model name with a lowercase first letter. The models behind the MongoDB query above are [further down this page](#postgresql-and-mongodb-differences).
+- On MongoDB there is no schema segment. The path is `db.orm.<collectionName>`. The collection name is the `@@map(...)` on the model, or the model name exactly as written. The models behind the MongoDB query above are [further down this page](#postgresql-and-mongodb-differences).
 - You `await` the whole chain, and the last call says what you want back. `.all()` returns every matching record as an array. `.first()` returns one record, or `null` when nothing matches.
 - `.where(...)` takes two forms. Pass an object, like `.where({ published: true })`, to match fields to exact values. Pass a callback for a comparison, like `.where((p) => p.title.like("Hello%"))`. Chaining `.where(...)` twice requires both to match.
 
diff --git a/apps/docs/content/docs/orm/fundamentals/transactions.mdx b/apps/docs/content/docs/orm/fundamentals/transactions.mdx
index 36c59f1d60..f7cecefa8f 100644
--- a/apps/docs/content/docs/orm/fundamentals/transactions.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/transactions.mdx
@@ -111,7 +111,7 @@ The [SQL query builder](/orm/fundamentals/advanced-queries) works the same way i
 ```typescript
 const cutoff = Temporal.Instant.from("2026-01-01T00:00:00Z");
 await db.transaction(async (tx) => {
-  const query = tx.sql.public.post
+  const query = tx.sql.public.Post
     .update({ published: false })
     .where((f, fns) => fns.lt(f.createdAt, cutoff))
     .build();
@@ -119,7 +119,7 @@ await db.transaction(async (tx) => {
 });
 ```
 
-Two things differ from `tx.orm`. Under `tx.sql.public` the property name is the table name, so it is `tx.sql.public.post` where the ORM API has `tx.orm.public.Post`. The table name is the model name with a lowercase first letter, so the model `BlogPost` has the table `blogPost`, and you set `@@map` on the model to use a different table name.
+Two things differ from `tx.orm`. Under `tx.sql.public` the property name is the table name, not the model name. The table name is the model name exactly as written, so the model `Post` has the table `Post` and it is `tx.sql.public.Post`, unless the model sets `@@map`: a model with `@@map("post")` is `tx.sql.public.post`.
 The second difference is that you chain clauses and then call `.build()` to finish the query: `.build()` returns the query without running it, and `tx.execute(...)` runs it and returns `{ affectedRows }`, the number of rows it changed. The `.where(...)` callback receives two arguments: `f` holds the columns, and `fns` holds the operators (`lt` is less-than). [Advanced queries](/orm/fundamentals/advanced-queries#build-a-query-and-run-it) covers both.
 
 ## Transactions on MongoDB
@@ -172,7 +172,7 @@ try {
 const jane = await db.orm.users.where({ email: "jane@prisma.io" }).first();
 ```
 
-On MongoDB there is no schema segment in the path, and the property name is the collection name. The collection name is the model name with a lowercase first letter, so a model `User` is `db.orm.user`. `db.orm.users` above is the collection name; the model is `User` with `@@map("users")`.
+On MongoDB there is no schema segment in the path, and the property name is the collection name. The collection name is the model name exactly as written, so a model `User` is `db.orm.User`, unless the model sets `@@map`. `db.orm.users` above is the collection name; the model is `User` with `@@map("users")`.
 Writes you make through the driver skip the type-checking that Prisma ORM queries get, so put each driver transaction in its own small function, and write everything around it as Prisma ORM queries.
 
 ## Coming from Prisma ORM 7
diff --git a/apps/docs/content/docs/orm/fundamentals/writing-data.mdx b/apps/docs/content/docs/orm/fundamentals/writing-data.mdx
index a39083875b..64cecfbdce 100644
--- a/apps/docs/content/docs/orm/fundamentals/writing-data.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/writing-data.mdx
@@ -12,7 +12,7 @@ Every example imports `db`. In a new project run `npm create prisma@latest -- my
 
 This page uses `db.orm`, which holds your models. The rest of `db` is `db.sql` for the SQL query builder, `db.raw.sql` for raw SQL, and `db.transaction` for running several writes together.
 
-On PostgreSQL the path to a model is `db.orm.<schema>.<ModelName>`, so the `User` model is `db.orm.public.User`. `public` is the PostgreSQL schema; you type it. It is `public` unless the model sits in a `namespace` block (shown under [Example schema](#example-schema)). On MongoDB there is no schema segment, and the path is `db.orm.<collectionName>`, so the model below is `db.orm.users`. The collection name is the model's `@@map(...)`, or the model name with a lowercase first letter.
+On PostgreSQL the path to a model is `db.orm.<schema>.<ModelName>`, so the `User` model is `db.orm.public.User`. `public` is the PostgreSQL schema; you type it. It is `public` unless the model sits in a `namespace` block (shown under [Example schema](#example-schema)). On MongoDB there is no schema segment, and the path is `db.orm.<collectionName>`, so the model below is `db.orm.users`. The collection name is the model's `@@map(...)`, or the model name exactly as written.
 
 ## Example schema
 
@@ -296,6 +296,8 @@ const deletedCount = await db.orm.public.Post.where((p) => p.title.ilike("draft%
 
 The `AndCount` methods return a plain number, so if three posts match, `updatedCount` is `3`, not an object.
 
+To insert many records and skip the ones that would break a unique constraint, pass `{ onConflict: "skip" }` as the second argument to `createAll` or `createAndCount`, and optionally `conflictOn: ["email"]` to name the constraint. This replaces Prisma ORM 7's `skipDuplicates`, and it works on PostgreSQL and SQLite. `createAll` returns only the records the database wrote, and `createAndCount` counts only those. [`createAll()`](/orm/reference/orm-client#createall) in the reference covers the details.
+
 `.where((p) => p.title.ilike("draft%"))` is the callback form of a filter, for conditions an object cannot express. Its argument gives you one entry per field, and each field carries the comparisons you can apply to it. [Reading data](/orm/fundamentals/reading-data) covers the filters you can write.
 
 The bulk methods work the same on MongoDB, on the collection: `db.orm.posts`. Pass `createdAt` in every object you give `createAll`, as with `create`.
diff --git a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
index e0feb0d24a..34eb276279 100644
--- a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
+++ b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
@@ -51,7 +51,7 @@ The `name` is the label Prisma ORM uses when it talks about your middleware, so
 
 If a call gives you back a count instead of rows, `afterQuery` is not called for it and `afterExecute` is called instead. On the ORM API the calls that return a count are `createAndCount`, `updateAndCount`, and `deleteAndCount`. Every other call returns rows and reaches `afterQuery`, including `create`, `update`, `delete`, `updateAll`, and `deleteAll`.
 
-The SQL query builder is the other way to write a query on the same client, `db.sql.public.user...` in place of `db.orm.public.User...`. With it you build a query and run it in two steps, and the step you run it with decides which hook you get. Calling `.build()` gives you the plan, and `db.runtime()` is the method on your client that runs one. `db.runtime().query(plan)` returns rows and reaches `afterQuery`, while `db.runtime().execute(plan)` reports how many rows the statement changed and reaches `afterExecute`.
+The SQL query builder is the other way to write a query on the same client, `db.sql.public.User...` in place of `db.orm.public.User...`. With it you build a query and run it in two steps, and the step you run it with decides which hook you get. Calling `.build()` gives you the plan, and `db.runtime()` is the method on your client that runs one. `db.runtime().query(plan)` returns rows and reaches `afterQuery`, while `db.runtime().execute(plan)` reports how many rows the statement changed and reaches `afterExecute`.
 
 To have the logger cover the counting calls as well, add a second hook to the object `queryLogger()` returns in `src/prisma/query-logger.ts`, next to `afterQuery`:
 
@@ -114,8 +114,8 @@ npm run dev
 The logger reports both queries, and prints the SQL that actually ran:
 
 ```text no-copy
-[query-logger] 1 rows in 18ms · INSERT INTO "public"."user" ("email", "name", "updatedAt") VALUES ($1, $2, $3) RETURNING "user"."createdAt", "user"."email", "user"."id", "user"."name", "user"."updatedAt", "user"."username"
-[query-logger] 1 rows in 17ms · SELECT "user"."id" AS "id", "user"."email" AS "email" FROM "public"."user" LIMIT 5
+[query-logger] 1 rows in 18ms · INSERT INTO "public"."User" ("email", "name", "updatedAt") VALUES ($1, $2, $3) RETURNING "User"."createdAt", "User"."email", "User"."id", "User"."name", "User"."updatedAt", "User"."username"
+[query-logger] 1 rows in 17ms · SELECT "User"."id" AS "id", "User"."email" AS "email" FROM "public"."User" LIMIT 5
 fetched 1 users
 ```
 
@@ -222,7 +222,7 @@ A hook you implement for one kind of call is never called for the other kind, so
 
 Its argument is called a draft because the SQL text does not exist yet. A draft has `ast`, the tree you change, and `meta`, which records where the query came from and which you pass through unchanged. You return a copy of the draft with a new `ast`, or `undefined` when there is nothing to change.
 
-The middleware below adds a condition to every `SELECT` on the `user` table:
+The middleware below adds a condition to every `SELECT` on the `User` table:
 
 ```ts title="src/prisma/scope-user-selects.ts"
 import type { SqlMiddleware } from '@prisma/orm-postgres/family-runtime';
@@ -236,7 +236,7 @@ export function scopeUserSelects(predicate: BinaryExpr): SqlMiddleware {
     async beforeCompile(draft) {
       if (draft.ast.kind !== 'select') return undefined;
       if (draft.ast.from?.kind !== 'table-source') return undefined;
-      if (draft.ast.from.name !== 'user') return undefined;
+      if (draft.ast.from.name !== 'User') return undefined;
       const where = draft.ast.where ? AndExpr.of([draft.ast.where, predicate]) : predicate;
       return { ...draft, ast: draft.ast.withWhere(where) };
     },
@@ -244,7 +244,7 @@ export function scopeUserSelects(predicate: BinaryExpr): SqlMiddleware {
 }
 ```
 
-The `kind` check on `from` keeps the middleware to plain tables: a `SELECT` that reads from a subquery has a `from` whose `kind` is `'derived-table-source'`, and one that reads from a function has `'function-source'`. The name it checks, `'user'`, is the table name in your database rather than the model name in your contract, because by this point the query is expressed in tables and columns. `draft.ast.withWhere(where)` gives back a new tree with that `WHERE` and leaves the original alone.
+The `kind` check on `from` keeps the middleware to plain tables: a `SELECT` that reads from a subquery has a `from` whose `kind` is `'derived-table-source'`, and one that reads from a function has `'function-source'`. The name it checks, `'User'`, is the table name in your database rather than the model name in your contract, because by this point the query is expressed in tables and columns. The two are the same unless the model sets `@@map`. `draft.ast.withWhere(where)` gives back a new tree with that `WHERE` and leaves the original alone.
 
 The condition itself is an object you build from the same classes, and you pass it in when you register the middleware. Put values through `ParamRef.of` rather than `LiteralExpr.of`, because a `ParamRef` becomes a bound parameter such as `$1` while a literal is pasted into the SQL text itself, so a value that came from one of your users could inject SQL of its own. A `ParamRef` you build by hand has to name the PostgreSQL type of the value with `codec: { codecId: ... }`, and the ids start with `pg/` and end with `@1`, so the `text` column `name` takes `pg/text@1`. Leave that out and the query fails with an error whose `code` is `RUNTIME.PARAM_REF_MISSING_CODEC`.
 
@@ -256,7 +256,7 @@ import type { Contract } from './contract.d';
 import contractJson from './contract.json' with { type: 'json' };
 
 const onlyMia = BinaryExpr.eq(
-  ColumnRef.of('user', 'name'),
+  ColumnRef.of('User', 'name'),
   ParamRef.of('Mia', { codec: { codecId: 'pg/text@1' } }),
 );
 
@@ -267,11 +267,11 @@ export const db = postgres<Contract>({
 });
 ```
 
-Every `SELECT` on `user` now runs with `WHERE "user"."name" = $1` added, and a query that already had a `WHERE` clause keeps it, joined to yours with `AND`. Swap `name` for whatever column holds your tenant to get the tenant filter.
+Every `SELECT` on `User` now runs with `WHERE "User"."name" = $1` added, and a query that already had a `WHERE` clause keeps it, joined to yours with `AND`. Swap `name` for whatever column holds your tenant to get the tenant filter.
 
 Copy each import as it is written, including the one that says `type` and the one that does not.
 
-A `uuid` column takes `pg/uuid@1`, and the other common ids are `pg/int4@1`, `pg/int8@1`, `pg/float8@1`, `pg/bool@1`, and `pg/timestamptz-temporal@1` for a `timestamptz` column. For a column whose type is not in that list, read the id off your own client: `db.sql.public.user.columns.name.codecId` is the id for the `name` column of the `user` table, so print it from any script that imports `db`. [`fns.raw` and `.returns()`](/orm/reference/sql-query-builder#fnsraw-and-returns) lists the ids in one place.
+A `uuid` column takes `pg/uuid@1`, and the other common ids are `pg/int4@1`, `pg/int8@1`, `pg/float8@1`, `pg/bool@1`, and `pg/timestamptz-temporal@1` for a `timestamptz` column. For a column whose type is not in that list, read the id off your own client: `db.sql.public.User.columns.name.codecId` is the id for the `name` column of the `User` table, so print it from any script that imports `db`. [`fns.raw` and `.returns()`](/orm/reference/sql-query-builder#fnsraw-and-returns) lists the ids in one place.
 
 `BinaryExpr` has one method per comparison (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `in`, `notIn`), and `AndExpr.of` and `OrExpr.of` combine conditions. They all come from `@prisma/orm-postgres/relational-core/ast`, so your editor lists them once you import from there.
 
@@ -287,7 +287,7 @@ async onRow(row) {
 },
 ```
 
-For the `SELECT` in step 3, whose SQL is `SELECT "user"."id" AS "id", "user"."email" AS "email" FROM "public"."user" LIMIT 5`, a row object has an `id` key holding a number and an `email` key holding a string. The fixture below returns one row of that shape, and you register it the same way as the logger, with `middleware: [userFixture()]`:
+For the `SELECT` in step 3, whose SQL is `SELECT "User"."id" AS "id", "User"."email" AS "email" FROM "public"."User" LIMIT 5`, a row object has an `id` key holding a number and an `email` key holding a string. The fixture below returns one row of that shape, and you register it the same way as the logger, with `middleware: [userFixture()]`:
 
 ```ts title="src/prisma/user-fixture.ts"
 import type { SqlMiddleware } from '@prisma/orm-postgres/family-runtime';
@@ -298,7 +298,7 @@ export function userFixture(): SqlMiddleware {
     familyId: 'sql',
 
     async interceptQuery(plan) {
-      if (!plan.sql.includes('FROM "public"."user"')) return undefined;
+      if (!plan.sql.includes('FROM "public"."User"')) return undefined;
       return { rows: [{ id: 1, email: 'mia@prisma.io' }] };
     },
   };
@@ -386,7 +386,7 @@ Timing itself does not need any of this, because `result.latencyMs` already tell
 Projects created with `npm create prisma@latest` install [Prisma ORM skills](/ai/tools/skills#available-skills-for-prisma-8) for your coding agent, so you can ask it for the middleware built in the steps above:
 
 - "Write a Prisma ORM middleware that logs every query slower than 250ms, and register it before budgets."
-- "Add a beforeCompile middleware that scopes every SELECT on the user table to the current tenant."
+- "Add a beforeCompile middleware that scopes every SELECT on the User table to the current tenant."
 - "Write an interceptQuery middleware that returns fixture rows for the products table in tests."
 
 ## Next steps
diff --git a/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx b/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx
index 7a1dc9f12b..e07f6926a4 100644
--- a/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx
+++ b/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx
@@ -44,7 +44,7 @@ export const db = postgres<Contract>({
     budgets({
       maxRows: 10_000,
       defaultTableRows: 10_000,
-      tableRows: { user: 10_000, post: 10_000 },
+      tableRows: { User: 10_000, Post: 10_000 },
       maxLatencyMs: 1_000,
     }),
   ],
@@ -55,7 +55,7 @@ The built-in middleware is imported from `@prisma/orm-postgres/family-runtime`,
 
 The example sets `maxRows`, `defaultTableRows`, and `maxLatencyMs` to the values they already take by default, so that you can see where each one goes, and you can leave all three out. Set `maxRows` and `maxLatencyMs` to the largest number of rows and the longest time any single query in your app should ever need, because they are there to catch mistakes rather than to tune anything.
 
-The two numbers in `tableRows` are placeholders for how many rows your own tables really hold, so a `post` table with two million rows in it is written `tableRows: { post: 2_000_000 }`. A `count` from the database is enough to get each number, such as `select count(*) from "public"."user";` for the `user` table, and you can leave `tableRows` out altogether, in which case every table is assumed to hold `defaultTableRows` rows. Each key is the table name as it is in the database, which is the model name with a lowercase first letter, so the model `User` is keyed `user` and not `User` or `public.User`. If you renamed a table with `@@map` in your contract, use the name you mapped it to. If you misspell a table name, `budgets` silently uses `defaultTableRows` for that table and never warns you.
+The two numbers in `tableRows` are placeholders for how many rows your own tables really hold, so a `Post` table with two million rows in it is written `tableRows: { Post: 2_000_000 }`. A `count` from the database is enough to get each number, such as `select count(*) from "public"."User";` for the `User` table, and you can leave `tableRows` out altogether, in which case every table is assumed to hold `defaultTableRows` rows. Each key is the table name as it is in the database, which is the model name exactly as written, so the model `User` is keyed `User` and not `public.User`. If you renamed a table with `@@map` in your contract, use the name you mapped it to. If you misspell a table name, `budgets` silently uses `defaultTableRows` for that table and never warns you.
 
 Passing `budgets` to a MongoDB client throws an error whose `code` is `RUNTIME.MIDDLEWARE_FAMILY_MISMATCH` the first time that client is used, before any query of yours runs, and there is no MongoDB version of `budgets` to use instead.
 
@@ -148,7 +148,7 @@ Import that `db` in your export script and nowhere else, so the rest of your app
 
 The check that runs before your query never asks the database how big your tables are. It only knows the numbers you gave it in `tableRows` and `defaultTableRows`, so when your real tables are much larger than those numbers, a query can get past that first check and then fail part way through reading rows, once the rows the database returns pass `maxRows`.
 
-Say `maxRows` is `10_000` and you listed `user` at 5,000 rows, but the table really holds 5 million. A query with `.limit(50_000)` on it is estimated at 5,000 rows, because `budgets` takes the smaller of your limit and the size you gave for the table, so it passes the first check. The database then starts sending 50,000 rows and the count check throws at row 10,001, part way through your read. A query that used to work failing with `source: 'observed'` is your sign to put a fresh count into `tableRows`.
+Say `maxRows` is `10_000` and you listed `User` at 5,000 rows, but the table really holds 5 million. A query with `.limit(50_000)` on it is estimated at 5,000 rows, because `budgets` takes the smaller of your limit and the size you gave for the table, so it passes the first check. The database then starts sending 50,000 rows and the count check throws at row 10,001, part way through your read. A query that used to work failing with `source: 'observed'` is your sign to put a fresh count into `tableRows`.
 
 :::
 
diff --git a/apps/docs/content/docs/orm/middleware/built-in-cache.mdx b/apps/docs/content/docs/orm/middleware/built-in-cache.mdx
index 5b18717e83..245fbcee2f 100644
--- a/apps/docs/content/docs/orm/middleware/built-in-cache.mdx
+++ b/apps/docs/content/docs/orm/middleware/built-in-cache.mdx
@@ -43,14 +43,14 @@ You tell Prisma ORM that a read may be cached by attaching a cache annotation to
 
 Prisma ORM gives you two ways to write the same read, the SQL query builder and the ORM API, and both of them can be cached. Use whichever one the rest of your code already uses, because the annotation attaches differently in each.
 
-With the SQL query builder you build the query yourself, call `.build()`, and run the result with `db.runtime().query(...)` for rows or `db.runtime().execute(...)` for a count. Only rows can be cached, so nothing you run with `db.runtime().execute(...)` ever is. To cache a read, chain `.annotate(cacheAnnotation({ ttl: 60_000 }))` onto the query before you call `.build()`. `db.sql.public.user` names the `user` table in the PostgreSQL schema `public`.
+With the SQL query builder you build the query yourself, call `.build()`, and run the result with `db.runtime().query(...)` for rows or `db.runtime().execute(...)` for a count. Only rows can be cached, so nothing you run with `db.runtime().execute(...)` ever is. To cache a read, chain `.annotate(cacheAnnotation({ ttl: 60_000 }))` onto the query before you call `.build()`. `db.sql.public.User` names the `User` table in the PostgreSQL schema `public`.
 
 ```ts title="src/prisma/get-users-cached.ts"
 import { cacheAnnotation } from '@prisma/orm-extension-middleware-cache';
 import { db } from './db';
 
 export async function getUsersCached() {
-  const plan = db.sql.public.user
+  const plan = db.sql.public.User
     .select('id', 'email')
     .annotate(cacheAnnotation({ ttl: 60_000 }))
     .limit(10)
@@ -88,7 +88,7 @@ Leave `ttl` out and the annotation does nothing, so the query is not cached.
 `skip` and `key` go in the same object as `ttl`, in either API. `skip: true` sends that one call to the database and leaves the stored rows untouched, so everyone else keeps getting the stored rows until the `ttl` runs out. The `ttl` in the same object is ignored on a call with `skip: true`, which is why you can leave the annotation as it is and flip `skip` on the one call that has to see current rows. With the SQL query builder it goes in the same object you pass to `.annotate(...)`:
 
 ```ts
-const plan = db.sql.public.user
+const plan = db.sql.public.User
   .select('id', 'email')
   .annotate(cacheAnnotation({ ttl: 60_000, skip: true }))
   .limit(10)
diff --git a/apps/docs/content/docs/orm/middleware/built-in-lints.mdx b/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
index 632f468c20..922c8aded9 100644
--- a/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
+++ b/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
@@ -58,7 +58,7 @@ The rules are named after the SQL they are about, and you write your queries in
 | `deleteAll()` or `updateAll()` | none, because TypeScript makes you write `.where(...)` first |
 | the query builder's `delete()` or `update()` with no `where()` | `LINT.DELETE_WITHOUT_WHERE` or `LINT.UPDATE_WITHOUT_WHERE` |
 
-So `await db.orm.public.User.limit(50).all()` sets off `LINT.SELECT_STAR`, while `await db.orm.public.User.select('id', 'email').limit(50).all()` does not. In `db.orm.public.User`, `public` is the PostgreSQL schema and `User` is your model name. The SQL query builder reaches the same table by its name in the database, as `db.sql.public.user`, which is why the two are spelled differently in the examples here.
+So `await db.orm.public.User.limit(50).all()` sets off `LINT.SELECT_STAR`, while `await db.orm.public.User.select('id', 'email').limit(50).all()` does not. In `db.orm.public.User`, `public` is the PostgreSQL schema and `User` is your model name. The SQL query builder reaches the same table by its name in the database, as `db.sql.public.User`. The model and the table have the same name here because the model sets no `@@map`.
 
 This is the record `lints` builds for a `warn` finding: the code of the rule, a message, and the table the query touched.
 
@@ -66,7 +66,7 @@ This is the record `lints` builds for a `warn` finding: the code of the rule, a
 warn {
   code: 'LINT.NO_LIMIT',
   message: 'Unbounded SELECT may return large result sets',
-  details: { table: 'user' }
+  details: { table: 'User' }
 }
 ```
 
@@ -80,7 +80,7 @@ The blocked `DELETE` below comes from the SQL query builder, where you build the
 import { isRuntimeError } from '@prisma/orm-postgres/components/runtime';
 
 try {
-  const plan = db.sql.public.user.delete().build();
+  const plan = db.sql.public.User.delete().build();
   await db.runtime().execute(plan);
 } catch (error) {
   if (isRuntimeError(error) && error.code === 'LINT.DELETE_WITHOUT_WHERE') {
@@ -90,7 +90,7 @@ try {
 }
 ```
 
-Those properties hold this for a `DELETE` with no `WHERE` on the `user` table:
+Those properties hold this for a `DELETE` with no `WHERE` on the `User` table:
 
 ```text title="Blocked DELETE" no-copy
 {
@@ -98,7 +98,7 @@ Those properties hold this for a `DELETE` with no `WHERE` on the `user` table:
   category: 'LINT',
   severity: 'error',
   message: 'DELETE without WHERE clause blocks execution to prevent accidental full-table deletion',
-  details: { table: 'user' }
+  details: { table: 'User' }
 }
 ```
 
@@ -145,7 +145,7 @@ A whole statement you wrote yourself with [`db.raw.sql`](/orm/reference/raw-quer
 So a `select *` you wrote by hand is blocked:
 
 ```ts
-const plan = db.raw.sql`select * from "user"`
+const plan = db.raw.sql`select * from "User"`
   .returnsRow({ id: 'pg/int4@1' })
   .build();
 await db.runtime().query(plan);
@@ -157,7 +157,7 @@ Because these are searches through the text rather than checks on the structure
 
 :::warning
 
-A severity you set in `severities` applies to a finding by its code wherever that finding came from, so it changes the raw defaults as well as the four rules. If you set `selectStar: 'warn'` to quiet the ORM-API rule, raw SQL's `select *` drops from `error` to `warn` along with it, and `select * from "user"` starts running instead of being blocked. To keep the ORM-API rule at `error` and still run a raw `select *`, give the code that runs it a `db` client of its own, in the way [Common gotchas](#common-gotchas) does for a backfill script.
+A severity you set in `severities` applies to a finding by its code wherever that finding came from, so it changes the raw defaults as well as the four rules. If you set `selectStar: 'warn'` to quiet the ORM-API rule, raw SQL's `select *` drops from `error` to `warn` along with it, and `select * from "User"` starts running instead of being blocked. To keep the ORM-API rule at `error` and still run a raw `select *`, give the code that runs it a `db` client of its own, in the way [Common gotchas](#common-gotchas) does for a backfill script.
 
 :::
 
@@ -178,14 +178,14 @@ Sometimes you do mean to change every row, in a backfill script for example. `LI
 The first way is to write a `WHERE` clause that is true for every row, which states the intent in the query itself. In a query builder callback the first argument, `f`, has one property for each column, and the second, `fns`, holds the comparison helpers. Comparing a column to `null` gives you a null check rather than a comparison, so `fns.ne(f.id, null)` gives `id IS NOT NULL` and `fns.eq(f.id, null)` gives `id IS NULL`. On a table whose primary key is `id`, `IS NOT NULL` is true for every row:
 
 ```ts
-const plan = db.sql.public.user
+const plan = db.sql.public.User
   .delete()
   .where((f, fns) => fns.ne(f.id, null))
   .build();
 await db.runtime().execute(plan);
 ```
 
-That delete passes the rule and runs, because the query has a `WHERE` clause and that is all `LINT.DELETE_WITHOUT_WHERE` looks for, so you can leave `lints` on its defaults in the script that runs it. An `UPDATE` takes the same shape, as in `db.sql.public.user.update({ name: 'x' }).where((f, fns) => fns.ne(f.id, null)).build()`.
+That delete passes the rule and runs, because the query has a `WHERE` clause and that is all `LINT.DELETE_WITHOUT_WHERE` looks for, so you can leave `lints` on its defaults in the script that runs it. An `UPDATE` takes the same shape, as in `db.sql.public.User.update({ name: 'x' }).where((f, fns) => fns.ne(f.id, null)).build()`.
 
 The second way is to build that script its own `db` client with the rule set to `warn`:
 
diff --git a/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx b/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
index 8a18a287e0..40deaf92a3 100644
--- a/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
+++ b/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
@@ -125,7 +125,7 @@ Prisma ORM calls your middleware in the order you listed them in the `middleware
 
 Reach for `beforeCompile` when you want to change what a query asks for rather than only look at it. It runs on both kinds of query, and it hands you a draft with two fields: `meta`, the metadata Prisma ORM keeps about the query, and `ast`, the query as a tree of typed objects. The tree is the part you can change, because the SQL text has not been written yet. Return a copy of the draft with a changed `ast` and Prisma ORM runs your version instead, which is how you add a tenant filter to every `SELECT` without editing a single call site. Return `undefined` and the query goes through as written.
 
-The middleware below adds a condition to every `SELECT` that reads the `user` table:
+The middleware below adds a condition to every `SELECT` that reads the `User` table:
 
 ```ts title="src/prisma/scope-user-selects.ts"
 import type { SqlMiddleware } from '@prisma/orm-postgres/family-runtime';
@@ -139,7 +139,7 @@ export function scopeUserSelects(predicate: BinaryExpr): SqlMiddleware {
     async beforeCompile(draft) {
       if (draft.ast.kind !== 'select') return undefined;
       if (draft.ast.from?.kind !== 'table-source') return undefined;
-      if (draft.ast.from.name !== 'user') return undefined;
+      if (draft.ast.from.name !== 'User') return undefined;
       const where = draft.ast.where ? AndExpr.of([draft.ast.where, predicate]) : predicate;
       return { ...draft, ast: draft.ast.withWhere(where) };
     },
@@ -147,7 +147,7 @@ export function scopeUserSelects(predicate: BinaryExpr): SqlMiddleware {
 }
 ```
 
-The three checks above are how you say "only `SELECT`s, and only ones over the `user` table". `draft.ast.kind` is `'select'`, `'insert'`, `'update'`, `'delete'`, or `'raw-query'`, and `draft.ast.from.kind` is `'table-source'` when a `SELECT` reads a plain table rather than a subquery or a function. Use the table name as it is in your database, `user`, rather than the model name in your contract, `User`: a model called `User` is the `user` table unless you renamed it with `@@map`. `withWhere` returns a new `SELECT` with that `WHERE` on it and leaves the original alone, which is why the hook returns a copy of the draft.
+The three checks above are how you say "only `SELECT`s, and only ones over the `User` table". `draft.ast.kind` is `'select'`, `'insert'`, `'update'`, `'delete'`, or `'raw-query'`, and `draft.ast.from.kind` is `'table-source'` when a `SELECT` reads a plain table rather than a subquery or a function. Use the table name as it is in your database rather than the model name in your contract. They are the same, `User`, unless the model sets `@@map`, in which case use the name it maps to. `withWhere` returns a new `SELECT` with that `WHERE` on it and leaves the original alone, which is why the hook returns a copy of the draft.
 
 The `predicate` you pass in is a comparison you build yourself, and the types for building one come from `@prisma/orm-postgres/relational-core/ast`. A value you compare against needs its `codecId`, which says how the value is stored: `pg/` plus the PostgreSQL type name plus `@1`, so text is `pg/text@1` and a 32-bit integer is `pg/int4@1`:
 
@@ -156,7 +156,7 @@ import { BinaryExpr, ColumnRef, ParamRef } from '@prisma/orm-postgres/relational
 import { scopeUserSelects } from './scope-user-selects';
 
 const onlyMia = BinaryExpr.eq(
-  ColumnRef.of('user', 'name'),
+  ColumnRef.of('User', 'name'),
   ParamRef.of('Mia', { codec: { codecId: 'pg/text@1' } }),
 );
 ```
@@ -208,7 +208,7 @@ The rows you return are plain objects, keyed by the column aliases in the SQL, h
 { id: 3, email: 'mia+1@prisma.io', createdAt: '2026-09-17 08:00:08.775+00' }
 ```
 
-So for a query whose SQL is `SELECT "user"."id" AS "id", "user"."email" AS "email" FROM "public"."user" LIMIT 5`, `return { rows: [{ id: 1, email: 'mia@prisma.io' }] }` is a complete answer to it. Rows you return go through the same conversion as rows from the database, so a caller on the ORM API gets the types its contract says it should, even though you returned a string. This is how the cache serves repeated reads. Anything you checked in a before-hook has already run by the time either hook is called.
+So for a query whose SQL is `SELECT "User"."id" AS "id", "User"."email" AS "email" FROM "public"."User" LIMIT 5`, `return { rows: [{ id: 1, email: 'mia@prisma.io' }] }` is a complete answer to it. Rows you return go through the same conversion as rows from the database, so a caller on the ORM API gets the types its contract says it should, even though you returned a string. This is how the cache serves repeated reads. Anything you checked in a before-hook has already run by the time either hook is called.
 
 ### onRow: watch rows arrive
 
diff --git a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
index 6478c65989..5023589bae 100644
--- a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
@@ -139,7 +139,7 @@ npx prisma db migrate --advance-ref db
 
 In development, add `--advance-ref db` so the next `migration plan` starts from what you just applied, and leave the flag off in CI and production, where you never plan a migration anyway. [The db ref](/orm/migrations/generating-a-migration#the-db-ref-skipping---from) covers what happens without it and how to fix a missed flag. If you edit `migration.ts` while reviewing the migration, recompile it with `node migrations/app/<dir>/migration.ts` before you apply, as [Editing a migration](/orm/migrations/editing-a-migration) explains.
 
-**In CI and production**, you never plan a migration, because migrations arrive through your repository, already reviewed and merged. For that to work, commit each migration's directory, the directories `migration plan` added under `migrations/snapshots/`, one per contract state, and `contract.prisma`, `contract.json`, and `contract.d.ts`. Deploy with the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed, because it fails with an error whose `code` is `MIGRATION.CHECK_HASH_MISMATCH` when a migration's files no longer match the hash stored when it was written, as [Editing a migration](/orm/migrations/editing-a-migration) explains. When that happens, either restore the migration's files from Git, or move the hand edit into `migration.ts` and recompile.
+**In CI and production**, you never plan a migration, because migrations arrive through your repository, already reviewed and merged. For that to work, commit each migration's directory, the directories `migration plan` added under `migrations/snapshots/`, one per contract state, and `contract.prisma`, `contract.json`, and `contract.d.ts`. Deploy with the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed, because it fails with an error whose `code` is `MIGRATION.CHECK_HASH_MISMATCH` when a migration's files no longer match the hash stored when it was written, as [Editing a migration](/orm/migrations/editing-a-migration) explains. It fails with `MIGRATION.CHECK_SNAPSHOT_CONTENT_MISMATCH` when a contract snapshot under `migrations/snapshots/` no longer matches the hash it is filed under, and the other commands that read a snapshot stop with `MIGRATION.CONTRACT_SNAPSHOT_CONTENT_MISMATCH`. Restore an edited snapshot from Git. MongoDB snapshots are not checked yet. When that happens, either restore the migration's files from Git, or move the hand edit into `migration.ts` and recompile.
 
 If two deployments can run at once, what happens next depends on your database. On PostgreSQL, when two `db migrate` runs start against the same database, one of them waits for the other. On MongoDB, if another run updates the marker while yours is running, yours fails with `Marker was modified by another process during migration execution.` When that happens, run `npx prisma migration status` to see which contract state the database matches, and then run `db migrate` again.
 
diff --git a/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx b/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
index fadbaff828..b762028fe8 100644
--- a/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
@@ -40,7 +40,7 @@ to:         e6b5c2849eca8d24ff1e8e88ab2a4234db8e74c497c035cb7ce42e814f31cd63
 app space:  migrations/app/20260707T1008_add_display_name
 ```
 
-In that output, `self-emit` is what the CLI calls recompiling, and `app space` is the directory the new migration was written to. `migration plan` writes the change as three steps rather than one, because the column is required and the table already has rows: `addColumn` adds the column as nullable, `dataTransform` holds the backfill you write, and `setNotNull` makes the column required. The table is called `user` because the table name is the model name with a lowercase first letter, unless the model sets `@@map`:
+In that output, `self-emit` is what the CLI calls recompiling, and `app space` is the directory the new migration was written to. `migration plan` writes the change as three steps rather than one, because the column is required and the table already has rows: `addColumn` adds the column as nullable, `dataTransform` holds the backfill you write, and `setNotNull` makes the column required. The table is called `user` because the contract from [Generating a migration](/orm/migrations/generating-a-migration#your-first-migration) maps `User` to it with `@@map("user")`. Without `@@map`, the table name is the model name exactly as written:
 
 ```ts title="migration.ts (as planned)"
 override get operations() {
@@ -156,28 +156,32 @@ Sooner or later a backfill has to read a column that the same migration takes aw
 What you need instead is a contract that describes the database as it is while the backfill runs, and you write that one yourself. Copy your whole contract into the migration directory as `intermediate.prisma`, then in its `User` model add `isAdmin` back and make `role` optional, because at that point no row has a `role` yet.
 
 ```prisma title="intermediate.prisma (User, other fields left out)"
+// use prisma-8
+
 model User {
   id          Int     @id
   displayName String
   isAdmin     Boolean
   role        String?
+
+  @@map("user")
 }
 ```
 
-In the same migration directory, add `intermediate.config.ts`, a second config file that names `intermediate.prisma` as the contract and needs no database connection:
+Keep `// use prisma-8` as the first line of the copy, because `contract emit` reads only files that start with it.
+
+In the same migration directory, add `intermediate.config.ts`, a second config file that names `intermediate.prisma` as the contract and needs no database connection. `parent: false` stops the CLI from also reading your project's `prisma.config.ts`, which it would otherwise find in a parent directory and merge in:
 
 ```ts title="intermediate.config.ts"
 import { definePrismaConfig } from 'prisma/config';
 import { defineConfig as ormConfig } from '@prisma/orm-postgres/config';
-export default definePrismaConfig({ orm: ormConfig({ contract: './intermediate.prisma' }) });
+export default definePrismaConfig({ parent: false, orm: ormConfig({ contract: './intermediate.prisma' }) });
 ```
 
-Emit the intermediate contract from inside the migration directory, because `intermediate.config.ts` reads its paths from the directory you run the command in. Commit all four `intermediate.*` files along with the migration, since the migration no longer recompiles without them.
+Emit the intermediate contract with `--config` pointing at that file. A relative path in a config file resolves from the directory of that file, so `./intermediate.prisma` is found wherever you run the command from. Commit all four `intermediate.*` files along with the migration, since the migration no longer recompiles without them.
 
 ```bash
-cd migrations/app/20260708T0900_replace_is_admin
-npx prisma contract emit --config intermediate.config.ts
-cd ../../..
+npx prisma contract emit --config migrations/app/20260708T0900_replace_is_admin/intermediate.config.ts
 ```
 
 ```text title="migrations/app/20260708T0900_replace_is_admin/"
@@ -288,7 +292,7 @@ override get operations() {
 
 Not every migration comes from a contract change. When you want a data-only migration, which changes rows and leaves your contract state as it is, or a migration you intend to write entirely by hand, run `npx prisma migration new`. It writes an empty `ops.json`, a `migration.json`, and a `migration.ts` that already has the snapshot imports, the class, and an empty `operations` array. Nothing was planned for you, so there is no `placeholder` import to remove, but you do have to add the `@prisma/orm-postgres` imports and the `endContract`, `stack`, and `db` statements from the filled-in `displayName` listing.
 
-Because a data-only migration starts and ends at the contract state your database already matches, you have to tell the command which state that is, by passing `--from` with your contract's hash. `npx prisma migration graph` marks that hash `@contract`. The [`migration new` reference](/cli/migration-new) lists the rest of the options:
+A data-only migration starts and ends at the contract state your database already matches. Without `--from`, `migration new` starts from the `db` ref, which is that state when you apply migrations with `--advance-ref db`. To start from another state, pass `--from` with the hash of the migration that ends there. `npx prisma migration graph` marks your contract's hash `@contract`. The [`migration new` reference](/cli/migration-new) lists the rest of the options:
 
 ```npm
 npx prisma migration new --name backfill_scores --from <hash>
diff --git a/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx b/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
index dc2384b719..49de023f8a 100644
--- a/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
@@ -15,6 +15,8 @@ Two commands do the work, and you run them in this order every time you change y
 Say your contract has a single model:
 
 ```prisma title="contract.prisma"
+// use prisma-8
+
 model User {
   id    Int     @id
   email String
diff --git a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
index a6f3b24766..5d90bcc73b 100644
--- a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
+++ b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
@@ -34,7 +34,7 @@ npx prisma db migrate --advance-ref db
 ✔ Planned 1 operation(s)
 
 migrations/app/20260707T1006_add_user_phone
-└─ Add column "phone" to "user"
+└─ Add column "phone" to "User"
 
 from:       705b1a62f26f0913caa4bfe3f8b7cb491a1b94bd47fc43471d8711bc480bcbb5
 to:         925198f3cc272c5fd19c24ac02f251661775ddac21cdac4e634bbc0dda8b2d72
@@ -42,10 +42,10 @@ app space:  migrations/app/20260707T1006_add_user_phone
 
 ℹ DDL preview
 
-ALTER TABLE "public"."user" ADD COLUMN "phone" text;
+ALTER TABLE "public"."User" ADD COLUMN "phone" text;
 ```
 
-A table name is the model name with a lowercase first letter unless the model sets `@@map`, so `User` becomes `"user"` and `UserProfile` becomes `"userProfile"`. If your database was created by Prisma ORM 7, it has a `"User"` table instead, so [the upgrade guide](/guides/upgrade-prisma-orm/postgresql#24-edit-the-inferred-contract) maps the old names with `@@map` before you plan a migration for it.
+A table name is the model name exactly as written unless the model sets `@@map`, so `User` is the table `"User"` and `UserProfile` is `"UserProfile"`, the same names Prisma ORM 7 used. Before `8.0.0-rc.12`, a model without `@@map` named its table with a lowercase first letter, `"userProfile"`. If your tables were created with those names, run the `add-model-map` script from the [upgrade recipe](https://github.com/prisma/orm/blob/v8.0.0-rc.12/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.11-to-8.0.0-rc.12/) over every `.prisma` file, including the `contract.prisma` copies under `migrations/`, before you plan. It adds `@@map("<current table name>")` to each model that has none. Without it, `migration plan` stops with [`MIGRATION.TABLE_NAME_CASE_CHANGED`](/orm/reference/error-reference#MIGRATION.TABLE_NAME_CASE_CHANGED) rather than drop the table and create an empty one.
 
 The `app space:` line tells you which migration history the new directory was written into. A contract space is a separate migration history, so your own migrations stay in `migrations/app/` while each [Prisma ORM extension package](/orm/migrations/applying-a-migration#extension-spaces) that ships migrations, such as pgvector, keeps its migrations in its own directory under `migrations/`.
 
@@ -103,11 +103,11 @@ Because that `from` hash is what ties one migration to another, your [migration
 
 Inside `ops.json`, an operation is not only the change itself: it also carries the checks that decide whether the change needs to run and whether it worked. Here are the parts of the operation that adds the `phone` column:
 
-- **Precheck**: confirms the database is in the state the change expects, here that `"user"` has no `phone` column.
-- **Execute**: the statements that make the change, here `ALTER TABLE "public"."user" ADD COLUMN "phone" text`.
+- **Precheck**: confirms the database is in the state the change expects, here that `"User"` has no `phone` column.
+- **Execute**: the statements that make the change, here `ALTER TABLE "public"."User" ADD COLUMN "phone" text`.
 - **Postcheck**: confirms the change is in the database, here that the `phone` column exists. Some operations have no postcheck. `db migrate` skips an operation only when its postcheck already passes, so an operation with no postcheck always runs.
 
-When `db migrate` reaches an operation, it runs the postcheck before the change as well as after, because if the postcheck already passes then the change is in the database and there is nothing to do, so the operation is skipped. If the postcheck does not pass, `db migrate` runs the precheck, then the statements, then the postcheck, and it stops the run if either check fails. Once the operations are done, it checks the database against the contract before it updates the marker, which catches a database that satisfied every individual operation but still doesn't match what you declared. Say `"user"` already has a `phone` column of another type: the postcheck only asks whether a `phone` column exists, so it passes, the operation is skipped, and that final contract check then fails the run.
+When `db migrate` reaches an operation, it runs the postcheck before the change as well as after, because if the postcheck already passes then the change is in the database and there is nothing to do, so the operation is skipped. If the postcheck does not pass, `db migrate` runs the precheck, then the statements, then the postcheck, and it stops the run if either check fails. Once the operations are done, it checks the database against the contract before it updates the marker, which catches a database that satisfied every individual operation but still doesn't match what you declared. Say `"User"` already has a `phone` column of another type: the postcheck only asks whether a `phone` column exists, so it passes, the operation is skipped, and that final contract check then fails the run.
 
 Each operation also has an `operationClass`, which says what kind of change the operation makes to the database and which you choose yourself when you write a raw SQL operation:
 
diff --git a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
index 28dc88e0f1..a74cea8cdd 100644
--- a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
+++ b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
@@ -180,7 +180,7 @@ The graph itself, the way `db migrate` chooses which migrations to run, refs, th
 
 - **No squash.** You cannot yet collapse a long chain of migrations into one.
 - **No split.** You cannot yet break one large migration into smaller ones after the fact.
-- **`migration new` needs `--from` when your history has more than one end state.** `npx prisma migration new` writes an empty migration for a change you write yourself, such as a data update, and without `--from` it starts at the end state of the latest migration. An end state is a contract state that no migration starts from. With two end states, such as `5e1f082` and `e377d00` in the drawing above, it fails with an error whose `code` is `MIGRATION.AMBIGUOUS_TARGET` and lists both. Pass a prefix of the one you want, for example `npx prisma migration new --name backfill --from e377d00`.
+- **`migration new` starts from the `db` ref.** `npx prisma migration new` writes an empty migration for a change you write yourself, such as a data update, and without `--from` it starts where `migration plan` would: at the `db` ref. To build on another state, such as `e377d00` in the drawing above, pass a prefix of it: `npx prisma migration new --name backfill --from e377d00`.
 
 ## Common tasks
 
diff --git a/apps/docs/content/docs/orm/reference/index.mdx b/apps/docs/content/docs/orm/reference/index.mdx
index 8ee689ce98..68719c917e 100644
--- a/apps/docs/content/docs/orm/reference/index.mdx
+++ b/apps/docs/content/docs/orm/reference/index.mdx
@@ -29,7 +29,7 @@ const plan = db.sql.public.user.select('id', 'email').where((f, fns) => fns.eq(f
 const rows = await runtime.query(plan);
 ```
 
-`User` is the model name and `user` is the table name. The ORM client compares on the column, `u.kind.eq(...)`, while the SQL query builder compares through `fns`, `fns.eq(f.kind, ...)`.
+`User` is the model name and `user` is the table name, which the [example schema](/orm/reference/orm-client#example-schema) sets with `@@map("user")`. Without `@@map`, the two names are the same. The ORM client compares on the column, `u.kind.eq(...)`, while the SQL query builder compares through `fns`, `fns.eq(f.kind, ...)`.
 
 ### MongoDB
 
diff --git a/apps/docs/content/docs/orm/reference/orm-client.mdx b/apps/docs/content/docs/orm/reference/orm-client.mdx
index 102e35ffcb..b73bc1f331 100644
--- a/apps/docs/content/docs/orm/reference/orm-client.mdx
+++ b/apps/docs/content/docs/orm/reference/orm-client.mdx
@@ -178,7 +178,7 @@ model Tutorial {
 Some parts of the schema the examples rely on:
 
 - The `types` block at the top gives a name to a type from an extension package, so your models can use that name. `Embedding1536` comes from the pgvector extension, and `pgvector.` is that package's prefix. See [PostgreSQL](#postgresql) for the extra line it needs when you create the client.
-- `@@map("user")` sets the table or collection name. Without it, the table name is the model name with a lowercase first letter.
+- `@@map("user")` sets the table or collection name. Without it, the table name is the model name exactly as written, `User`.
 - On MongoDB, `id ObjectId @id @map("_id")` renames the field to `_id` everywhere: you filter on `_id`, and the returned document has an `_id` key. That is why the MongoDB examples never say `id`.
 - `Uuid` is a built-in type for a PostgreSQL `uuid` column. You do not import it. `@default(uuid())` fills the id in when you insert a row.
 - `@@type("pg/text@1")` on an `enum` block stores the enum as a text column. The `@1` is the version of that storage format, and only version 1 exists today, so write it exactly like that. The MongoDB form of the same attribute is `@@type("mongo/string@1")`. This page calls an enum written this way a text-backed enum.
@@ -231,7 +231,7 @@ To give a model your own methods on top of the built-in ones, import `Collection
 
 ### MongoDB
 
-Create a MongoDB client with `mongo(...)`. `db.orm` holds your models by collection name, with no schema in between: `db.orm.users`, `db.orm.posts`, not `db.orm.User`. The collection name is the one you set with `@@map`, or the model name with a lowercase first letter when you did not set one. `dbName` is the MongoDB database name.
+Create a MongoDB client with `mongo(...)`. `db.orm` holds your models by collection name, with no schema in between: `db.orm.users`, `db.orm.posts`, not `db.orm.User`. The collection name is the one you set with `@@map`, or the model name exactly as written when you did not set one. `dbName` is the MongoDB database name.
 
 ```typescript
 import mongo from '@prisma/orm-mongo/runtime';
@@ -1006,12 +1006,15 @@ Insert multiple rows and return them.
 - Available for PostgreSQL and MongoDB.
 - Returns an [`AsyncIterableResult`](#asynciterableresult): `await` for an array, or `for await` to stream inserted rows.
 - On PostgreSQL every row is inserted by one statement before the first row reaches you. Stopping the loop early does not undo an insert.
+- On PostgreSQL and SQLite, `{ onConflict: 'skip' }` as the second argument skips each row that collides with a unique constraint, and the result holds only the rows the database wrote. `conflictOn: ['email']` names the unique constraint by its columns; without it, a collision on any unique constraint skips the row. A variant stored in its own table refuses the option with `ORM.OPERATION_UNSUPPORTED`. The option needs capabilities that a contract emitted before `8.0.0-rc.12` does not list, so run `npx prisma contract emit` once first; otherwise it fails with `ORM.CAPABILITY_MISSING`.
 
 #### Options
 
 | Name | Type | Required | Description |
 |---|---|---|---|
-| The rows | Array of field objects | Yes | The rows to insert, passed as the only argument. There is no `data` wrapper. |
+| The rows | Array of field objects | Yes | The rows to insert, passed as the first argument. There is no `data` wrapper. |
+| `onConflict` | `'skip'` | No | Skip rows that collide with a unique constraint. PostgreSQL and SQLite. |
+| `conflictOn` | Array of field names | No | With `onConflict`, the columns of the unique constraint to check. |
 
 #### Return type
 
@@ -1025,6 +1028,13 @@ Insert multiple rows and return them.
 
 ```typescript tab="PostgreSQL"
 const created = await db.orm.public.Tag.createAll([{ label: 'alpha' }, { label: 'beta' }]);
+
+// Skip rows whose label already exists instead of failing.
+const added = await db.orm.public.Tag.createAll([{ label: 'alpha' }, { label: 'gamma' }], {
+  onConflict: 'skip',
+  conflictOn: ['label'],
+});
+// added holds only the gamma row
 ```
 
 ```typescript tab="MongoDB"
@@ -1044,12 +1054,15 @@ Insert rows and return how many were inserted, without reading them back.
 - On PostgreSQL, `createAndCount()` does not work on a variant that is stored in its own table, meaning its `@@map` names a different table than its base model does. `Bug` in the [example schema](#example-schema) is one: it maps to `bug` while `Task` maps to `task`. Use `createAll()` instead.
 - Calling it on such a variant throws an error whose `code` is `ORM.OPERATION_UNSUPPORTED`, with the message `createAndCount() is not supported for MTI variant "Bug" on model "Task". Use createAll() instead.` MTI in the message means multi-table inheritance, the variant stored in its own table described above.
 - On MongoDB, a variant is one document in one collection, so `createAndCount()` works on a variant as usual.
+- It returns the number of rows the database inserted. With `{ onConflict: 'skip' }`, the skipped rows are not counted. The option works as on [`createAll()`](#createall).
 
 #### Options
 
 | Name | Type | Required | Description |
 |---|---|---|---|
-| The rows | Array of field objects | Yes | The rows to insert, passed as the only argument. There is no `data` wrapper. |
+| The rows | Array of field objects | Yes | The rows to insert, passed as the first argument. There is no `data` wrapper. |
+| `onConflict` | `'skip'` | No | Skip rows that collide with a unique constraint. PostgreSQL and SQLite. |
+| `conflictOn` | Array of field names | No | With `onConflict`, the columns of the unique constraint to check. |
 
 #### Return type
 
@@ -1670,7 +1683,7 @@ Comparison methods on a field.
 - `eq`, `neq`, `in`, and `notIn` are on a field whose values can be compared for equality.
 - `gt`, `lt`, `gte`, and `lte` are on a field whose values can be ordered.
 - `like` and `ilike` are on a text field.
-- `String` and enum fields have all of them. `Uuid` and `DateTime` have all but `like` and `ilike`. A `Boolean` field has only the equality methods, `isNull()`, and `isNotNull()`. A `Json` field has only `isNull()` and `isNotNull()`.
+- `String` fields and enums stored as text have all of them. A native enum field (`pg.enum(...)`) has all but `like` and `ilike`, because PostgreSQL has no pattern match for an `enum` type. `Uuid` and `DateTime` have all but `like` and `ilike`. A `Boolean` field has only the equality methods, `isNull()`, and `isNotNull()`. A `Json` field has only `isNull()` and `isNotNull()`.
 - `like()` matches a SQL pattern case-sensitively. `ilike()` matches the same pattern case-insensitively.
 - `in([])` matches no rows. `notIn([])` matches every row.
 
@@ -1717,6 +1730,46 @@ const notLowOrHigh = await db.orm.public.Post.where((p) => p.priority.notIn(['lo
 const withoutDescription = await db.orm.public.Task.where((t) => t.description.isNull()).all(); // Task.description is String? in the example schema
 ```
 
+### Full-text search (PostgreSQL) [#full-text-search]
+
+PostgreSQL full-text search on a text field.
+
+#### Remarks
+
+- PostgreSQL. A text field has `fullTextMatches(query, options?)` to filter and `fullTextRank(query, options?)` to sort by relevance. The [SQL query builder](/orm/reference/sql-query-builder) has the same operations as `fns.fullTextMatches(column, query)`, `fns.fullTextRank(column, query)`, and `fns.fullTextHeadline(column, query)`, which returns the matching text with each match marked.
+- `query` is a `tsquery`, not a string, and a bare string is a type error. Build it with a parser from `@prisma/orm-postgres/target/full-text`: `websearchToTsquery(text)` reads search-box text, `plaintoTsquery(text)` requires every word, and `phrasetoTsquery(text)` requires the words in order. `toTsquery(text)` takes PostgreSQL's operator syntax as written, so never pass user input to it.
+- For user input inside operator syntax, such as a prefix match while the user types, use the `tsquery` template tag from the same package: `` tsquery`${term}:*` ``. It turns each interpolated value into one quoted term, so the input cannot add operators. Do not put quotes around the interpolation yourself.
+- `language` sets the text-search configuration and defaults to `english`. The operation's `language` applies to the field, and each parser, and the tag as `` tsquery({ language })`...` ``, takes its own `language` for the query. Pass the same value to both.
+- Add [`@@fullTextIndex`](/orm/contract-authoring/psl-syntax#full-text-indexes) to the model, with the same `language`, so PostgreSQL can use an index for the search. Without it the query still works, with a sequential scan.
+- A native enum field (`pg.enum(...)`) has no full-text operations.
+
+#### Options
+
+| Method | Options | Description |
+|---|---|---|
+| `fullTextMatches(query, options?)` | `language` | Matches rows whose field matches `query`. |
+| `fullTextRank(query, options?)` | `language`, `normalization` (0 to 63), `coverDensity` | The relevance of the match, for `orderBy()`. `coverDensity: true` uses `ts_rank_cd` in place of `ts_rank`. |
+
+#### Examples
+
+##### Search and sort by relevance
+
+```typescript title="src/search-posts.ts"
+import { tsquery, websearchToTsquery } from '@prisma/orm-postgres/target/full-text';
+
+const q = websearchToTsquery('"Prisma ORM" -draft');
+const posts = await db.orm.public.Post.select('id', 'title')
+  .where((p) => p.title.fullTextMatches(q))
+  .orderBy((p) => p.title.fullTextRank(q).desc())
+  .limit(10)
+  .all();
+
+const suggestions = await db.orm.public.Post.select('id', 'title')
+  .where((p) => p.title.fullTextMatches(tsquery`${input}:*`))
+  .limit(5)
+  .all();
+```
+
 ### Combinators
 
 Combine or negate conditions.
diff --git a/apps/docs/content/docs/orm/reference/pipeline-builder.mdx b/apps/docs/content/docs/orm/reference/pipeline-builder.mdx
index 3d28460be8..413028dbe9 100644
--- a/apps/docs/content/docs/orm/reference/pipeline-builder.mdx
+++ b/apps/docs/content/docs/orm/reference/pipeline-builder.mdx
@@ -91,7 +91,7 @@ Enter the pipeline builder on a collection.
 
 #### Remarks
 
-- `from()` takes the collection name, the same name you use on `db.orm` (`'posts'`, `'users'`), not the model name `Post`. The collection name is the model's `@@map` value, or the model name with a lowercase first letter when there is no `@@map`.
+- `from()` takes the collection name, the same name you use on `db.orm` (`'posts'`, `'users'`), not the model name `Post`. The collection name is the model's `@@map` value, or the model name exactly as written when there is no `@@map`.
 - Passing an unknown collection name throws right away, with an error whose `code` is `ORM.MODEL_UNKNOWN` and whose message is `Unknown root: "<name>". Valid roots: ...` (the message says root; it means the collection name).
 - `from()` returns a builder you chain stages onto. Call `insertOne()` and `insertMany()` on `from()` directly, before any stage.
 - You can build the same pipelines without a client. `import { mongoQuery } from '@prisma/orm-mongo/query-builder'`, then `mongoQuery({ contractJson }).from('posts')`. Import `contractJson` the same way the example below does. `mongoQuery` only builds queries. It never runs one, so you still need a client's `runtime` to get results. Use it in tests, or to build a query once and run it through any client you like.
diff --git a/apps/docs/content/docs/orm/reference/raw-queries.mdx b/apps/docs/content/docs/orm/reference/raw-queries.mdx
index 30e9c40231..a8e13f7f47 100644
--- a/apps/docs/content/docs/orm/reference/raw-queries.mdx
+++ b/apps/docs/content/docs/orm/reference/raw-queries.mdx
@@ -22,7 +22,7 @@ A **whole raw statement** is a complete SQL statement written with `db.raw.sql`.
 A type id such as `pg/text@1` tells Prisma ORM what JavaScript type a column should become, and the property is named `codecId`. `.returnsRow(spec)` names a type id for every column of a whole `db.raw.sql` statement, so you get real JavaScript values back. A fragment's `.returns(...)` does not convert anything: it only tells TypeScript what type to expect, so the value is whatever the `pg` package, the PostgreSQL driver underneath, gives you. For a `text` or an `integer` column that is already a JavaScript string or number, while a `numeric` column arrives as a string. A date column gets no conversion by Prisma ORM, so you get the `pg` package's own value for that column.
 :::
 
-The examples in this section run against the `user` / `post` schema from the SQL query builder page. See its [example schema](/orm/reference/sql-query-builder#example-schema) for the full model definitions. As on that page, create the client with `postgres(...)` and reach tables through `db.sql.public`, which is keyed by table name (the model name with a lowercase first letter unless the model sets the `@@map` attribute, which renames a table). `db.runtime()` gives you the connection that runs a built query.
+The examples in this section run against the `user` / `post` schema from the SQL query builder page. See its [example schema](/orm/reference/sql-query-builder#example-schema) for the full model definitions. As on that page, create the client with `postgres(...)` and reach tables through `db.sql.public`, which is keyed by table name (the model name exactly as written, unless the model sets the `@@map` attribute, which renames a table). `db.runtime()` gives you the connection that runs a built query.
 
 ```ts
 import postgres from '@prisma/orm-postgres/runtime';
diff --git a/apps/docs/content/docs/orm/reference/sql-query-builder.mdx b/apps/docs/content/docs/orm/reference/sql-query-builder.mdx
index d9e2f4d488..44da5ffefb 100644
--- a/apps/docs/content/docs/orm/reference/sql-query-builder.mdx
+++ b/apps/docs/content/docs/orm/reference/sql-query-builder.mdx
@@ -130,7 +130,7 @@ model Feature {
 
 In Prisma ORM 8 your `schema.prisma` is called `contract.prisma`. [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7) gets you from a Prisma ORM 7 project to that file, and has the rest of the setup steps. Install the client with `npm install @prisma/orm-postgres`. Run `npx prisma contract emit` to write `contract.json` and `contract.d.ts` beside `contract.prisma`. The examples below assume your own file is in `src/prisma/`, next to those two files, and they write the type import path as `./contract.d`, exactly like that.
 
-You build queries from the client's `sql` property. Create a Postgres client with `postgres(...)`, then reach tables through `db.sql.public`. `public` is the PostgreSQL schema your tables are in, and a model goes in `public` unless your contract puts it in a `namespace` block. Table accessors are keyed by table name, not model name. A table name is the model name with a lowercase first letter unless the model sets `@@map`, so the `User` model mapped to `user` is reached as `db.sql.public.user`, and the model for the `Post`/`Tag` join table, mapped to `post_tag`, is reached as `db.sql.public.post_tag`. Column names are the field names unless a field sets `@map`.
+You build queries from the client's `sql` property. Create a Postgres client with `postgres(...)`, then reach tables through `db.sql.public`. `public` is the PostgreSQL schema your tables are in, and a model goes in `public` unless your contract puts it in a `namespace` block. Table accessors are keyed by table name, not model name. A table name is the model's `@@map` value, or the model name exactly as written when the model has no `@@map`, so the `User` model mapped to `user` is reached as `db.sql.public.user`, and the model for the `Post`/`Tag` join table, mapped to `post_tag`, is reached as `db.sql.public.post_tag`. Column names are the field names unless a field sets `@map`.
 
 ### The `db.sql` builder [#the-dbsql-facet]
 
@@ -923,7 +923,25 @@ Which aggregate functions exist depends on your database, and PostgreSQL gives y
 | `min(field)` | The input column's own type. A `VarChar` column gives a `String` (`text`) |
 | `max(field)` | The input column's own type. A `VarChar` column gives a `String` (`text`) |
 
-On PostgreSQL you also get `ilike(expr, pattern)` for text columns, as in `fns.ilike(f.displayName, '%alice%')`. `cosineDistance(a, b)` compares two vector values and returns a `number`. It comes with pgvector, the PostgreSQL extension for vector columns, so it is there only if your contract composes pgvector. See [Extension types](/orm/contract-authoring/psl-syntax#extension-types).
+On PostgreSQL you also get `ilike(expr, pattern)` for text columns, as in `fns.ilike(f.displayName, '%alice%')`, but not for a native enum column (`pg.enum(...)`), which has no text operations.
+
+Full-text search on PostgreSQL uses `fns.fullTextMatches(column, query)` to filter, `fns.fullTextRank(column, query)` to score, and `fns.fullTextHeadline(column, query, options?)` to return the matching text with each match marked. `query` is a `tsquery`: build it with `fns.websearchToTsquery(text)`, `fns.plaintoTsquery(text)`, `fns.phrasetoTsquery(text)`, or `fns.toTsquery(text)`, or with the `tsquery` tag from `@prisma/orm-postgres/target/full-text`. `fullTextHeadline` takes `startSel`, `stopSel`, `maxWords`, `minWords`, and `highlightAll`, and all three take `language`. [Full-text search](/orm/reference/orm-client#full-text-search) on the ORM client reference covers the parsers, the options, and the index:
+
+```ts title="src/search-posts.ts"
+const q = 'prisma orm';
+const plan = db.sql.public.post
+  .select('id', 'title')
+  .select('rank', (f, fns) => fns.fullTextRank(f.title, fns.websearchToTsquery(q)))
+  .select('headline', (f, fns) =>
+    fns.fullTextHeadline(f.title, fns.websearchToTsquery(q), { startSel: '<mark>', stopSel: '</mark>' }),
+  )
+  .where((f, fns) => fns.fullTextMatches(f.title, fns.websearchToTsquery(q)))
+  .orderBy((f, fns) => fns.fullTextRank(f.title, fns.websearchToTsquery(q)), { direction: 'desc' })
+  .limit(10)
+  .build();
+```
+
+`cosineDistance(a, b)` compares two vector values and returns a `number`. It comes with pgvector, the PostgreSQL extension for vector columns, so it is there only if your contract composes pgvector. See [Extension types](/orm/contract-authoring/psl-syntax#extension-types).
 
 ### `fns.raw` and `.returns()`
 
diff --git a/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx b/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx
index b71d63d397..cc85a5ceea 100644
--- a/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx
+++ b/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx
@@ -55,7 +55,7 @@ Pass exactly one of `url`, `pg`, and `binding`.
 | `PostgresClient` | `postgres<Contract>({ contractJson, url })` | A client that has not connected yet. Its members are listed below. |
 
 - `.orm` holds your models by model name. See the [ORM client reference](/orm/reference/orm-client).
-- `.sql` is the SQL query builder, keyed by schema, then table name: `db.sql.public.tag`. The table name is the model's `@@map` value, or the model name with a lowercase first letter when the model sets no `@@map`. See the [SQL query builder reference](/orm/reference/sql-query-builder). `.raw` writes raw SQL as a template string. See the [raw queries reference](/orm/reference/raw-queries).
+- `.sql` is the SQL query builder, keyed by schema, then table name: `db.sql.public.tag`. The table name is the model's `@@map` value, or the model name exactly as written when the model sets no `@@map`. See the [SQL query builder reference](/orm/reference/sql-query-builder). `.raw` writes raw SQL as a template string. See the [raw queries reference](/orm/reference/raw-queries).
 - `.enums` holds the enum values from your contract, by PostgreSQL schema: `db.enums.public.Role`. `.nativeEnums` holds the values of enum types that exist in PostgreSQL itself, created with `CREATE TYPE`, also by schema. Look the type up by name in brackets: `db.nativeEnums.auth['AalLevel'].values` is `['aal1', 'aal2', 'aal3']`.
 - `.contract` is the contract as an object. [`connect()`](#connect), [`runtime()`](#runtime), [`transaction()`](#dbtransactioncallback), [`prepare()`](#dbpreparedeclaration-callback), and [`close()`](#close) are documented on this page.
 
@@ -211,7 +211,7 @@ Pass exactly one of `url`, `uri`, `mongoClient`, and `binding`. `dbName` is sepa
 |---|---|---|
 | `MongoClient` | `mongo<Contract>({ contractJson, url, dbName })` | A client that has not connected yet. This is Prisma ORM's own type. The `mongodb` driver has a class of the same name, so when you import both, name this one `db`. |
 
-- `.orm` holds your models by collection name, with no schema segment: `db.orm.users`. The collection name is the model's `@@map` value, or the model name with a lowercase first letter when the model sets no `@@map`. The [example schema](/orm/reference/orm-client#example-schema) sets `@@map("users")` on `User`, which is why the key here is `users`. See the [ORM client reference](/orm/reference/orm-client).
+- `.orm` holds your models by collection name, with no schema segment: `db.orm.users`. The collection name is the model's `@@map` value, or the model name exactly as written when the model sets no `@@map`. The [example schema](/orm/reference/orm-client#example-schema) sets `@@map("users")` on `User`, which is why the key here is `users`. See the [ORM client reference](/orm/reference/orm-client).
 - `.query` is the pipeline builder, which builds MongoDB aggregation pipelines. See the [pipeline builder reference](/orm/reference/pipeline-builder). `.raw` sends raw MongoDB commands. See the [raw queries reference](/orm/reference/raw-queries).
 - `.enums` holds the enum values from your contract, and `.contract` is the contract as an object. [MongoDB `connect()`](#connect-1), [MongoDB `runtime()`](#runtime-1), and [MongoDB `close()`](#close-1) are documented below.
 
@@ -621,7 +621,8 @@ Prepare a statement on the client itself.
 
 #### Remarks
 
-- `db.prepare(...)` does the same thing as `runtime.prepare(...)`, but it passes you a SQL builder as the callback's first argument, so you do not need `db.sql`. The callback takes **two** arguments, `(sql, params)`. Build the query with `sql.public.<table>`.
+- The callback takes one argument, the declared `params`, as it does on `runtime.prepare(...)`. Build the query with the client's own `db.sql` or `db.orm`. Before `8.0.0-rc.12` the callback received a SQL builder as its first argument, `(sql, params)`; change such a callback to `(params)` and write `db.sql` where it wrote `sql`.
+- The callback can return a built SQL query, or an ORM query that ends in `.prepared.all()`, `.prepared.first()`, or `.prepared.aggregate(...)`. The ORM query is built once, and each `query(target, params)` call runs it with the new values and returns the same result shape as the ordinary call: rows for `all()`, a row or `null` for `first()`, and the aggregate object for `aggregate(...)`, or an array of groups after `groupBy(...)`.
 - `prepare()` starts the connection itself. Call `db.runtime()` for the runtime. `db.connect()` would throw an error whose `code` is `DRIVER.ALREADY_CONNECTED`, because `prepare()` already connected.
 
 #### Options
@@ -629,26 +630,43 @@ Prepare a statement on the client itself.
 | Name | Type | Required | Description |
 |---|---|---|---|
 | `declaration` | Object mapping param name to type id | Yes | The statement's parameters. |
-| `callback` | `(sql, params) => SqlQueryPlan` | Yes | Builds the query; `sql` is the client's SQL builder. |
+| `callback` | `(params) => SqlQueryPlan` or a prepared ORM query | Yes | Builds the query from the declared params, with `db.sql` or `db.orm`. |
 
 #### Return type
 
 | Return type | Example | Description |
 |---|---|---|
-| `Promise<PreparedStatement>` | `await db.prepare({ label: 'pg/text@1' }, (sql, params) => ...)` | A reusable prepared statement. |
+| `Promise<PreparedStatement>` | `await db.prepare({ label: 'pg/text@1' }, (params) => ...)` | A reusable prepared statement. |
 
 #### Examples
 
-##### Prepare off the client with the injected `sql` builder
+##### Prepare a SQL builder query off the client
 
 ```typescript
-const ps = await db.prepare({ label: 'pg/text@1' }, (sql, params) =>
-  sql.public.tag.select('id', 'label').where((f, fns) => fns.eq(f.label, params.label)).limit(1).build(),
+const ps = await db.prepare({ label: 'pg/text@1' }, (params) =>
+  db.sql.public.tag.select('id', 'label').where((f, fns) => fns.eq(f.label, params.label)).limit(1).build(),
 );
 
 const rows = await ps.query(db.runtime(), { label: 'typescript' });
 ```
 
+##### Prepare an ORM read and an aggregate
+
+```typescript title="src/prepared-reads.ts"
+const byLabel = await db.prepare({ label: 'pg/text@1' }, (params) =>
+  db.orm.public.Tag.select('id', 'label').prepared.first({ label: params.label }),
+);
+const tag = await byLabel.query(db.runtime(), { label: 'typescript' });
+// { id: '...', label: 'typescript' }, or null
+
+const countTags = await db.prepare({}, () =>
+  db.orm.public.Tag.prepared.aggregate((agg) => ({ total: agg.count() })),
+);
+const { total } = await countTags.query(db.runtime(), {});
+```
+
+A prepared parameter works in `where(...)` filters, in `include(...)` refinements, and in `.limit(...)` and `.offset(...)`, so the same statement can page through results.
+
 ### `PreparedStatement.query(target, params)`
 
 Run a prepared statement against a target, with the parameter values.
diff --git a/apps/docs/content/docs/orm/release-status.mdx b/apps/docs/content/docs/orm/release-status.mdx
index 52e36218a8..55098a87d1 100644
--- a/apps/docs/content/docs/orm/release-status.mdx
+++ b/apps/docs/content/docs/orm/release-status.mdx
@@ -40,10 +40,10 @@ The two packages have different version numbers, and that is normal: they are re
 | Package | Version today |
 | --- | --- |
 | `prisma` (the command-line tool) | `8.0.0-rc.15` |
-| `@prisma/orm-postgres` (the library) | `8.0.0-rc.11` |
-| `@prisma/orm-mongo` (the MongoDB library) | `8.0.0-rc.11` |
+| `@prisma/orm-postgres` (the library) | `8.0.0-rc.12` |
+| `@prisma/orm-mongo` (the MongoDB library) | `8.0.0-rc.12` |
 
-Versions were checked on 14 September 2026; run `npm view prisma dist-tags`, `npm view @prisma/orm-postgres dist-tags`, and `npm view @prisma/orm-mongo dist-tags` for today's, since the command-line tool and the libraries are versioned separately.
+Versions were checked on 24 September 2026; run `npm view prisma dist-tags`, `npm view @prisma/orm-postgres dist-tags`, and `npm view @prisma/orm-mongo dist-tags` for today's, since the command-line tool and the libraries are versioned separately.
 
 `@prisma/client`, the library that Prisma ORM 7 apps import, stays at `7.10.0`, because it belongs to Prisma ORM 7 and is not part of Prisma ORM 8.
 
diff --git a/apps/docs/cspell.json b/apps/docs/cspell.json
index a9930db88a..3b72dc1516 100644
--- a/apps/docs/cspell.json
+++ b/apps/docs/cspell.json
@@ -270,9 +270,11 @@
     "pgrowlocks",
     "pgstattuple",
     "pgvector",
+    "phraseto",
     "PKCE",
     "pkey",
     "PlanetScale",
+    "plainto",
     "planetscale",
     "plpgsql",
     "pois",
@@ -452,6 +454,7 @@
     "veroh",
     "waitlist",
     "walinspect",
+    "websearch",
     "windsurfrules",
     "workerd",
     "wrccj",

From 88717abc7ace4a563bd24d638e881d9a1ff6abfd Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Thu, 24 Sep 2026 22:05:05 +0200
Subject: [PATCH 02/16] docs(docs): the CLI is 8.0.0-rc.17, and contract emit
 also reads the prisma-next header

prisma 8.0.0-rc.17 is the release that bundles @prisma/cli-engine 0.6.1 and @prisma/orm-toolchain 8.0.0-rc.12, so the release-status table and the upgrade guide name it. contract emit accepts a file headed `// use prisma-next` as well as `// use prisma-8`, and the pages now say so. The snapshot-mismatch fix sits next to its own error instead of after the migration-hash one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx    | 2 +-
 apps/docs/content/docs/cli/configuration.mdx                  | 2 +-
 apps/docs/content/docs/cli/contract-emit.mdx                  | 2 +-
 .../content/docs/guides/upgrade-prisma-orm/postgresql.mdx     | 4 ++--
 .../content/docs/orm/contract-authoring/the-data-contract.mdx | 2 +-
 .../docs/content/docs/orm/migrations/applying-a-migration.mdx | 2 +-
 apps/docs/content/docs/orm/release-status.mdx                 | 2 +-
 7 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
index 0e8453f95d..a2409edd3c 100644
--- a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
+++ b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
@@ -43,7 +43,7 @@ npm install @prisma/orm-postgres dotenv
 npm install --save-dev prisma tsx typescript
 ```
 
-`@prisma/orm-postgres` is the library your code imports, and `prisma` is the command-line tool. `dotenv` loads `.env`, `tsx` runs `index.ts` without a build step, and `typescript` 5.9 or newer is a peer dependency of `@prisma/orm-postgres`. The two Prisma packages have different version numbers (for example `prisma` 8.0.0-rc.15 and `@prisma/orm-postgres` 8.0.0-rc.12); that is normal, and any two `latest` versions work together.
+`@prisma/orm-postgres` is the library your code imports, and `prisma` is the command-line tool. `dotenv` loads `.env`, `tsx` runs `index.ts` without a build step, and `typescript` 5.9 or newer is a peer dependency of `@prisma/orm-postgres`. The two Prisma packages have different version numbers (for example `prisma` 8.0.0-rc.17 and `@prisma/orm-postgres` 8.0.0-rc.12); that is normal, and any two `latest` versions work together.
 
 ## 2. Create the config file and `.env`
 
diff --git a/apps/docs/content/docs/cli/configuration.mdx b/apps/docs/content/docs/cli/configuration.mdx
index c96fb8986a..54218626dd 100644
--- a/apps/docs/content/docs/cli/configuration.mdx
+++ b/apps/docs/content/docs/cli/configuration.mdx
@@ -74,7 +74,7 @@ export default definePrismaConfig({
 });
 ```
 
-Every file the glob matches that starts with `// use prisma-8` becomes part of one schema, and `contract emit` builds one contract from them. A file without that first line is left out without a warning, and if no matched file has it, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. A new file joins the schema on the next emit, with no change to the config. The emitted files go in the fixed part of the glob, here `./prisma/contract.json` and `./prisma/contract.d.ts`.
+Every file the glob matches that starts with `// use prisma-8` becomes part of one schema, and `contract emit` builds one contract from them. `// use prisma-next`, from earlier release candidates, still counts. A file with neither first line is left out without a warning, and if no matched file has one, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. A new file joins the schema on the next emit, with no change to the config. The emitted files go in the fixed part of the glob, here `./prisma/contract.json` and `./prisma/contract.d.ts`.
 
 ## Use a Prisma ORM 7 schema
 
diff --git a/apps/docs/content/docs/cli/contract-emit.mdx b/apps/docs/content/docs/cli/contract-emit.mdx
index cfebc6b088..d67684ac45 100644
--- a/apps/docs/content/docs/cli/contract-emit.mdx
+++ b/apps/docs/content/docs/cli/contract-emit.mdx
@@ -10,7 +10,7 @@ metaDescription: Learn how to emit contract.json and contract.d.ts for Prisma OR
 
 The command is offline. It does not need a database connection.
 
-A PSL contract source can be one file or a glob that matches several files; see [Split the schema across several files](/cli/configuration#split-the-schema-across-several-files). `contract emit` reads only the `.prisma` files whose first line is `// use prisma-8`, and leaves any other file out without a warning. When no file has that line, it fails with `CONTRACT.SOURCE_LOAD_FAILED` and the finding `PSL_NO_OPTED_IN_SCHEMA_FILES`.
+A PSL contract source can be one file or a glob that matches several files; see [Split the schema across several files](/cli/configuration#split-the-schema-across-several-files). `contract emit` reads only the `.prisma` files whose first line is `// use prisma-8`, or `// use prisma-next` from earlier release candidates, and leaves any other file out without a warning. When no file has either line, it fails with `CONTRACT.SOURCE_LOAD_FAILED` and the finding `PSL_NO_OPTED_IN_SCHEMA_FILES`.
 
 ## Usage
 
diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
index 79a12f267e..b34df2921f 100644
--- a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
+++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
@@ -14,7 +14,7 @@ The guide covers **PostgreSQL only**. Guidance for other databases will follow.
 
 :::info
 
-This guide targets `prisma@latest`, `@prisma/orm-postgres@8.0.0-rc.12`, `@prisma/cli-engine@0.6.1`, and `@prisma/prisma7@7.10.0`, with a Prisma ORM 7 baseline on `7.9.1`. `prisma@latest` is the Prisma ORM 8 CLI, `8.0.0-rc.15` at the time of writing. It is versioned and released separately from the ORM packages, so its version number will not match theirs.
+This guide targets `prisma@latest`, `@prisma/orm-postgres@8.0.0-rc.12`, `@prisma/cli-engine@0.6.1`, and `@prisma/prisma7@7.10.0`, with a Prisma ORM 7 baseline on `7.9.1`. `prisma@latest` is the Prisma ORM 8 CLI, `8.0.0-rc.17` at the time of writing. It is versioned and released separately from the ORM packages, so its version number will not match theirs.
 
 :::
 
@@ -228,7 +228,7 @@ After this install, `npx prisma <command>` runs the Prisma ORM 8 CLI and `npx pr
 npx prisma --version
 ```
 
-**Expected result:** `8.0.0-rc.15` (or newer). The CLI's version line is separate from `@prisma/orm-postgres`'s.
+**Expected result:** `8.0.0-rc.17` (or newer). The CLI's version line is separate from `@prisma/orm-postgres`'s.
 
 ### 2.2. Create the Prisma ORM 8 config
 
diff --git a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
index 725a023e32..8c02e2a9b0 100644
--- a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
@@ -25,7 +25,7 @@ model Post {
 }
 ```
 
-`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema, and every `.prisma` contract file needs it. `contract emit` reads only the files that start with this line and leaves any other file out of the contract without a warning. When no file has it, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. The editor extension also looks for the line before it checks, completes, or formats the file. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
+`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema, and every `.prisma` contract file needs it. `contract emit` reads only the files that start with this line, or with `// use prisma-next` from earlier release candidates, and leaves any other file out of the contract without a warning. When no file has either line, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. The editor extension also looks for the line before it checks, completes, or formats the file. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
 
 `npx prisma contract emit` turns this file into two files that the CLI and your application read: `contract.json` and `contract.d.ts`. Your queries are type-checked against the contract, migrations are planned as changes to it, and `npx prisma db verify` checks a live database against it.
 
diff --git a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
index 5023589bae..43480a18c5 100644
--- a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
@@ -139,7 +139,7 @@ npx prisma db migrate --advance-ref db
 
 In development, add `--advance-ref db` so the next `migration plan` starts from what you just applied, and leave the flag off in CI and production, where you never plan a migration anyway. [The db ref](/orm/migrations/generating-a-migration#the-db-ref-skipping---from) covers what happens without it and how to fix a missed flag. If you edit `migration.ts` while reviewing the migration, recompile it with `node migrations/app/<dir>/migration.ts` before you apply, as [Editing a migration](/orm/migrations/editing-a-migration) explains.
 
-**In CI and production**, you never plan a migration, because migrations arrive through your repository, already reviewed and merged. For that to work, commit each migration's directory, the directories `migration plan` added under `migrations/snapshots/`, one per contract state, and `contract.prisma`, `contract.json`, and `contract.d.ts`. Deploy with the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed, because it fails with an error whose `code` is `MIGRATION.CHECK_HASH_MISMATCH` when a migration's files no longer match the hash stored when it was written, as [Editing a migration](/orm/migrations/editing-a-migration) explains. It fails with `MIGRATION.CHECK_SNAPSHOT_CONTENT_MISMATCH` when a contract snapshot under `migrations/snapshots/` no longer matches the hash it is filed under, and the other commands that read a snapshot stop with `MIGRATION.CONTRACT_SNAPSHOT_CONTENT_MISMATCH`. Restore an edited snapshot from Git. MongoDB snapshots are not checked yet. When that happens, either restore the migration's files from Git, or move the hand edit into `migration.ts` and recompile.
+**In CI and production**, you never plan a migration, because migrations arrive through your repository, already reviewed and merged. For that to work, commit each migration's directory, the directories `migration plan` added under `migrations/snapshots/`, one per contract state, and `contract.prisma`, `contract.json`, and `contract.d.ts`. Deploy with the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed, because it fails with an error whose `code` is `MIGRATION.CHECK_HASH_MISMATCH` when a migration's files no longer match the hash stored when it was written, as [Editing a migration](/orm/migrations/editing-a-migration) explains. When that happens, either restore the migration's files from Git, or move the hand edit into `migration.ts` and recompile. It fails with `MIGRATION.CHECK_SNAPSHOT_CONTENT_MISMATCH` when a contract snapshot under `migrations/snapshots/` no longer matches the hash it is filed under, and the other commands that read a snapshot stop with `MIGRATION.CONTRACT_SNAPSHOT_CONTENT_MISMATCH`. Recompiling `migration.ts` does not fix this; restore the edited snapshot from Git. MongoDB snapshots are not checked yet.
 
 If two deployments can run at once, what happens next depends on your database. On PostgreSQL, when two `db migrate` runs start against the same database, one of them waits for the other. On MongoDB, if another run updates the marker while yours is running, yours fails with `Marker was modified by another process during migration execution.` When that happens, run `npx prisma migration status` to see which contract state the database matches, and then run `db migrate` again.
 
diff --git a/apps/docs/content/docs/orm/release-status.mdx b/apps/docs/content/docs/orm/release-status.mdx
index 55098a87d1..fe236b694b 100644
--- a/apps/docs/content/docs/orm/release-status.mdx
+++ b/apps/docs/content/docs/orm/release-status.mdx
@@ -39,7 +39,7 @@ The two packages have different version numbers, and that is normal: they are re
 
 | Package | Version today |
 | --- | --- |
-| `prisma` (the command-line tool) | `8.0.0-rc.15` |
+| `prisma` (the command-line tool) | `8.0.0-rc.17` |
 | `@prisma/orm-postgres` (the library) | `8.0.0-rc.12` |
 | `@prisma/orm-mongo` (the MongoDB library) | `8.0.0-rc.12` |
 

From 7d0b9729a807e9e9c0275bc7a4bf2ebea9a75cbe Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Thu, 24 Sep 2026 22:13:14 +0200
Subject: [PATCH 03/16] docs(docs): state the contract header requirement as
 either line

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 .../content/docs/orm/contract-authoring/the-data-contract.mdx   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
index 8c02e2a9b0..63dbb01e3a 100644
--- a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
@@ -25,7 +25,7 @@ model Post {
 }
 ```
 
-`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema, and every `.prisma` contract file needs it. `contract emit` reads only the files that start with this line, or with `// use prisma-next` from earlier release candidates, and leaves any other file out of the contract without a warning. When no file has either line, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. The editor extension also looks for the line before it checks, completes, or formats the file. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
+`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema. Every `.prisma` contract file must start with this line or with `// use prisma-next`, the line earlier release candidates wrote. `contract emit` reads only those files and leaves any other file out of the contract without a warning. When no file has either line, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. The editor extension also looks for the line before it checks, completes, or formats the file. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
 
 `npx prisma contract emit` turns this file into two files that the CLI and your application read: `contract.json` and `contract.d.ts`. Your queries are type-checked against the contract, migrations are planned as changes to it, and `npx prisma db verify` checks a live database against it.
 

From b09dd62876e621eef91393fa143a1bdcde638dc3 Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Fri, 25 Sep 2026 07:07:32 +0200
Subject: [PATCH 04/16] docs(docs): address review: db verify comparison from
 the code, shorter schema-builder paragraphs

- db-verify: literal defaults are compared as values; any other default is a SQL expression compared as text, ignoring case and spaces. Check constraints and partial-index WHERE clauses are compared as exact text.
- configuration: define a glob, and say why the `// use prisma-8` line decides which files make up the schema.
- Drop the `// use prisma-next` notes this PR added.
- psl-syntax: plainer default-values rule; drop the paragraph about what a native enum column cannot do.
- typescript-schema-builder and contract-infer: split long paragraphs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 apps/docs/content/docs/cli/configuration.mdx           |  6 ++++--
 apps/docs/content/docs/cli/contract-emit.mdx           |  2 +-
 apps/docs/content/docs/cli/contract-infer.mdx          |  6 +++++-
 apps/docs/content/docs/cli/db-verify.mdx               |  6 +++++-
 .../docs/content/docs/orm/coming-from-prisma-orm-7.mdx |  2 +-
 .../content/docs/orm/contract-authoring/psl-syntax.mdx |  6 ++----
 .../docs/orm/contract-authoring/the-data-contract.mdx  |  2 +-
 .../contract-authoring/typescript-schema-builder.mdx   | 10 ++++++++--
 8 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/apps/docs/content/docs/cli/configuration.mdx b/apps/docs/content/docs/cli/configuration.mdx
index 54218626dd..99277e8533 100644
--- a/apps/docs/content/docs/cli/configuration.mdx
+++ b/apps/docs/content/docs/cli/configuration.mdx
@@ -61,7 +61,7 @@ A relative path in a config file, such as `contract`, `output`, or `migrations.d
 
 ## Split the schema across several files
 
-`contract` accepts a glob, so one schema can span several `.prisma` files:
+`contract` accepts a glob, a path pattern where `*` matches any file name and `**` matches any number of folders, so one schema can span several `.prisma` files:
 
 ```typescript title="prisma.config.ts"
 import { definePrismaConfig } from "prisma/config";
@@ -74,7 +74,9 @@ export default definePrismaConfig({
 });
 ```
 
-Every file the glob matches that starts with `// use prisma-8` becomes part of one schema, and `contract emit` builds one contract from them. `// use prisma-next`, from earlier release candidates, still counts. A file with neither first line is left out without a warning, and if no matched file has one, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. A new file joins the schema on the next emit, with no change to the config. The emitted files go in the fixed part of the glob, here `./prisma/contract.json` and `./prisma/contract.d.ts`.
+`contract emit` builds one contract from every matched file whose first line is `// use prisma-8`. It skips a matched file without that line and does not warn, so the line is what makes a file part of the schema. The Prisma editor extension uses the same rule, so the editor and `contract emit` agree on which files make up the schema. If no matched file starts with the line, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`, and the error's finding is `PSL_NO_OPTED_IN_SCHEMA_FILES`.
+
+A new file joins the schema the next time you run `contract emit`, with no change to the config. The emitted files go in the folder before the first wildcard, here `./prisma/contract.json` and `./prisma/contract.d.ts`.
 
 ## Use a Prisma ORM 7 schema
 
diff --git a/apps/docs/content/docs/cli/contract-emit.mdx b/apps/docs/content/docs/cli/contract-emit.mdx
index d67684ac45..13f6c062f7 100644
--- a/apps/docs/content/docs/cli/contract-emit.mdx
+++ b/apps/docs/content/docs/cli/contract-emit.mdx
@@ -10,7 +10,7 @@ metaDescription: Learn how to emit contract.json and contract.d.ts for Prisma OR
 
 The command is offline. It does not need a database connection.
 
-A PSL contract source can be one file or a glob that matches several files; see [Split the schema across several files](/cli/configuration#split-the-schema-across-several-files). `contract emit` reads only the `.prisma` files whose first line is `// use prisma-8`, or `// use prisma-next` from earlier release candidates, and leaves any other file out without a warning. When no file has either line, it fails with `CONTRACT.SOURCE_LOAD_FAILED` and the finding `PSL_NO_OPTED_IN_SCHEMA_FILES`.
+A PSL contract source can be one file or a glob that matches several files; see [Split the schema across several files](/cli/configuration#split-the-schema-across-several-files). `contract emit` reads only the `.prisma` files whose first line is `// use prisma-8`, and skips any other file without a warning. When no file starts with that line, it fails with `CONTRACT.SOURCE_LOAD_FAILED` and the finding `PSL_NO_OPTED_IN_SCHEMA_FILES`.
 
 ## Usage
 
diff --git a/apps/docs/content/docs/cli/contract-infer.mdx b/apps/docs/content/docs/cli/contract-infer.mdx
index f23060c6d5..961f4e234c 100644
--- a/apps/docs/content/docs/cli/contract-infer.mdx
+++ b/apps/docs/content/docs/cli/contract-infer.mdx
@@ -43,7 +43,11 @@ Inference gives you a starting point, not a finished design. Review:
 - defaults, indexes, and constraints
 - extension-backed column types
 
-The file starts with `// use prisma-8`, which `contract emit` needs. Each model is named after its table, and gets `@@map` only when the table name differs from the model name: a table `User` becomes `model User`, and a table `user_profile` becomes `model UserProfile` with `@@map("user_profile")`. Each column default is written in a form `contract emit` reads back: a JSON default as a `json` literal, a decimal as a bare number with every digit, and any other SQL expression as a `sql` literal, as [Default values](/orm/contract-authoring/psl-syntax#default-values) describes. A nullable list column is written `Type[]?`. If you keep an inferred contract in version control, running `contract infer` again can print the same database differently than earlier release candidates did; review the diff.
+The file starts with `// use prisma-8`, because `contract emit` reads only `.prisma` files that start with that line. Each model is named after its table, and gets `@@map` only when the table name differs from the model name: a table `User` becomes `model User`, and a table `user_profile` becomes `model UserProfile` with `@@map("user_profile")`.
+
+Every column default is written in a form `contract emit` accepts, so you can emit the file without editing it. [Default values](/orm/contract-authoring/psl-syntax#default-values) shows those forms. A nullable list column is written `Type[]?`.
+
+If you keep an inferred contract in version control, running `contract infer` again after an upgrade can write the same database differently, so review the diff before you commit it.
 
 The command stops at `contract.prisma`. Follow it with the emit and sign steps:
 
diff --git a/apps/docs/content/docs/cli/db-verify.mdx b/apps/docs/content/docs/cli/db-verify.mdx
index bbd5c4bc41..0807d698f0 100644
--- a/apps/docs/content/docs/cli/db-verify.mdx
+++ b/apps/docs/content/docs/cli/db-verify.mdx
@@ -63,4 +63,8 @@ Fix the database or contract, emit again if needed, then verify again.
 
 ## How PostgreSQL defaults are compared
 
-`db verify` compares a column default by its value, not by how PostgreSQL prints it, so `'-1'::integer`, `(5)::smallint`, an enum value cast to a type in another schema, a `timestamp` value without a time zone, and an `ARRAY[...]` list all compare equal to the default in your contract. It reads the database with `TimeZone = UTC` and ISO dates, whatever the server or role sets. A contract inferred from a server outside UTC before `8.0.0-rc.12` can therefore show one difference in a `timestamptz` value inside a check constraint or an index predicate. Emit the contract and run `db sign` once to clear it.
+When a column default is a literal value, `db verify` reads it as a value before it compares it with your contract, so the casts PostgreSQL adds when it prints the default do not cause a difference. This covers numbers such as `'-1'::integer` and `(5)::smallint`, text and enum values, including an enum value cast to a type in another PostgreSQL schema, `timestamp` values, `true`, `false`, `NULL`, JSON, and lists written as `'{...}'` or `ARRAY[...]`. `db verify` also recognizes `now()`, `clock_timestamp()`, `gen_random_uuid()`, and a sequence default, which it treats as `autoincrement()`.
+
+Any other default is a SQL expression. `db verify` cannot work out whether two SQL expressions give the same value, so it compares their text, ignoring letter case and spaces. PostgreSQL often rewrites an expression when it stores it, for example by adding casts, so write a `sql` default in your contract the way PostgreSQL stores it. To see that form, run `npx prisma contract infer --output ./inferred.prisma` and copy the column's `@default` from that file.
+
+`db verify` reads the database with the time zone set to UTC and dates in ISO format, whatever the server or your database role sets. It compares check constraints and the `WHERE` clause of a partial index as exact text. So if your contract was inferred before `8.0.0-rc.12` from a server that was not set to UTC, a `timestamptz` value inside a check constraint or an index's `WHERE` clause can be reported as a difference. Copy the new text from a fresh `npx prisma contract infer --output ./inferred.prisma` into your contract, emit the contract, and run `db sign`.
diff --git a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
index 7c86e1ea78..a2cba004db 100644
--- a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
+++ b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
@@ -37,7 +37,7 @@ The biggest visible change is in field types. Where Prisma ORM 7 wrote a Prisma
 | Prisma ORM 7 | Prisma ORM 8 | Notes |
 | --- | --- | --- |
 | `schema.prisma` | `contract.prisma` | |
-| (nothing) | `// use prisma-8` as the first line | `prisma orm init` writes it; add it yourself if you write the contract by hand. `prisma contract emit` reads only the files that start with it, and the [Prisma editor extension](/orm/contract-authoring/editor-support) does not recognise a file without it. Contracts from before `8.0.0-rc.10` say `// use prisma-next` instead, which still works; the editor extension rewrites it when you format |
+| (nothing) | `// use prisma-8` as the first line | `prisma orm init` writes it; add it yourself if you write the contract by hand. `prisma contract emit` reads only the files that start with it, and the [Prisma editor extension](/orm/contract-authoring/editor-support) does not recognise a file without it. |
 | `generator client { ... }` | removed | `emit` is the new word for `generate`. `prisma contract emit` writes two files next to your contract, `contract.json` and `contract.d.ts`. Commit both |
 | `datasource db { ... }` | the `orm` section of `prisma.config.ts` | the connection string and file paths live in the config file, not the schema. Example below |
 | `String @db.Text` | `String` | `String` is already stored as `text`. A known bug in one error message suggests `Text`; there is no such type |
diff --git a/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx b/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
index 68c24d6e35..00019192cc 100644
--- a/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
@@ -18,7 +18,7 @@ The `datasource` and `generator` blocks are gone: the connection URL and the fil
 
 ## A complete contract
 
-Every contract file starts with `// use prisma-8`. `contract emit` reads only the files that start with this line, so keep it at the top. A file without it is left out of the contract without a warning, and when no file has it, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. `// use prisma-next`, from earlier release candidates, still counts.
+Every contract file starts with `// use prisma-8`. `contract emit` reads only the files that start with this line, so keep it at the top. A file without it is left out of the contract without a warning, and when no file has it, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`.
 
 ```prisma title="src/prisma/contract.prisma" tab="PostgreSQL"
 // use prisma-8
@@ -172,7 +172,7 @@ On PostgreSQL the primary key is an ordinary column, so pick its type and defaul
 
 ### Default values
 
-A value you write in `@default(...)` has a data type, and how you write it decides which one. A column takes the value only if its own data type accepts that type; otherwise `contract emit` fails with `PSL_DEFAULT_TYPE_INCOMPATIBLE` and names the types the column accepts. A quoted string is text, so it does not work as a default for a JSON, decimal, or floating-point column:
+Write each default in a form its column can hold. A quoted string is text, for example, so it cannot be the default of a JSON, decimal, or floating-point column. When a default does not fit its column, `contract emit` fails with `PSL_DEFAULT_TYPE_INCOMPATIBLE` and names the types the column accepts. The examples below show the form for each kind of column:
 
 ```prisma title="src/prisma/contract.prisma (excerpt)"
 model Account {
@@ -323,8 +323,6 @@ model User {
 
 Each member needs a value. `pg` comes with `@prisma/orm-postgres`, so there is nothing to import. You do not create the PostgreSQL type yourself: `npx prisma migration plan` includes the `CREATE TYPE`.
 
-PostgreSQL has no `LIKE`, `ILIKE`, or text search for an `enum` type, so a `pg.enum(...)` column has no text operations: `like`, `ilike`, and the full-text operations are type errors on it. Compare it with `eq` or `in` instead. An `enum` block stored as text, such as `Priority` above, keeps every text operation.
-
 ## Value objects
 
 A `type` block declares a value object: a structured value stored inside its parent row, with no table of its own.
diff --git a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
index 63dbb01e3a..56560f90db 100644
--- a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
@@ -25,7 +25,7 @@ model Post {
 }
 ```
 
-`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema. Every `.prisma` contract file must start with this line or with `// use prisma-next`, the line earlier release candidates wrote. `contract emit` reads only those files and leaves any other file out of the contract without a warning. When no file has either line, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. The editor extension also looks for the line before it checks, completes, or formats the file. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
+`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema. Every `.prisma` contract file must start with this line. `contract emit` reads only files that start with it and skips any other file without a warning. When no file has the line, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. The editor extension also looks for the line before it checks, completes, or formats the file. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
 
 `npx prisma contract emit` turns this file into two files that the CLI and your application read: `contract.json` and `contract.d.ts`. Your queries are type-checked against the contract, migrations are planned as changes to it, and `npx prisma db verify` checks a live database against it.
 
diff --git a/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx b/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
index a3c02d5f93..e4e6ebe9fc 100644
--- a/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
@@ -199,9 +199,15 @@ The examples below use the PostgreSQL builder.
 
 There is no helper for a date without a time, or a time without a date. For a date-only column, name the type yourself: `field.column({ codecId: "pg/date-temporal@1", nativeType: "date" } as const)`. `field.column(...)` and the chained `.column(...)` below are different calls: `field.column(descriptor)` builds a field from a type description, and `.column(name)` on an existing field sets its column name. Extension packs add more helpers of their own.
 
-For a primary key whose value your app generates, use `field.id.uuidv4String()`, `field.id.uuidv7String()`, `field.id.ulid()`, `field.id.nanoid()`, `field.id.cuid2()`, or `field.id.ksuid()`. They all generate the ID in your app, and `uuidv4String` is the common choice. Each marks the field as the primary key for you, and `field.id.uuidv4Native()` and `field.id.uuidv7Native()` do the same in a `uuid` column. There is no auto-increment helper, so use one of those `field.id.*` helpers. For a key the database generates instead, write ``field.uuidNative().default(sql`gen_random_uuid()`).id()``, with `sql` imported from `@prisma/orm-postgres/contract-builder`.
+For a primary key your app generates, use a `field.id.*` helper. Each one marks the field as the primary key and generates the ID in your app when you create a row. `field.id.uuidv4String()` is the common choice, and the others are `field.id.uuidv7String()`, `field.id.ulid()`, `field.id.nanoid()`, `field.id.cuid2()`, and `field.id.ksuid()`. To store a UUID in a `uuid` column instead of a text column, use `field.id.uuidv4Native()` or `field.id.uuidv7Native()`.
 
-`field.temporal.createdAt()` sets the column to the current time when the row is created, while `field.temporal.updatedAt()` sets it on every create and every update. Prisma ORM sets both in the client, from your application's clock, so the column has no database default, and a row you insert with raw SQL must supply the value. For a value the database generates, use `field.dateTime().default(now())` instead. `field.temporal.timestamptzJsDate()` is a `timestamptz` column that reads and writes a JavaScript `Date`, with no `Temporal` polyfill, and `field.temporal.createdAtJsDate()` and `field.temporal.updatedAtJsDate()` are the matching presets. `field.namedType(x)` takes an enum or a type from an extension pack.
+For a key the database generates, chain `.default(...)` and `.id()` on a field. An integer that counts up is `field.int().default(autoincrement()).id()`, and a UUID is ``field.uuidNative().default(sql`gen_random_uuid()`).id()``. Import `autoincrement` and `sql` from `@prisma/orm-postgres/contract-builder`.
+
+`field.temporal.createdAt()` sets the column to the current time when the row is created, and `field.temporal.updatedAt()` sets it on every create and every update. Prisma ORM sets both in the client, from your application's clock, so the column has no database default. If you insert a row with raw SQL, you must supply the value yourself. For a time the database sets instead, use `field.dateTime().default(now())`.
+
+`field.temporal.timestamptzJsDate()` is a `timestamptz` column that your code reads and writes as a JavaScript `Date`, so it needs no `Temporal` polyfill. For creation and update times as a `Date`, use `field.temporal.createdAtJsDate()` and `field.temporal.updatedAtJsDate()`.
+
+`field.namedType(x)` takes an enum or a type from an extension pack.
 
 Every field builder supports chained modifiers:
 

From 89712ceab14906fb4ecbd8ba984bf23282e77a89 Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Fri, 25 Sep 2026 07:24:37 +0200
Subject: [PATCH 05/16] docs(docs): fix the reader-review findings on the rc.12
 pages

Every passage a cold reader could not follow is reworded, and every fact it
questioned is checked against the ORM source or the published packages:

- CLI: which commands read the orm section, how config files merge and what
  `parent` takes, what `--confirm` takes (the directory name), what `orm init`
  changes before its check, where emit findings appear in the JSON output.
- Upgrade guides: TypeScript 5.9 or newer; a `prisma7Schema` source needs no
  `// use prisma-8` line; complete raw-query and conflict-skip examples.
- Contract authoring: enum default forms, date and boolean defaults, the
  polyfill import, and that Temporal values are PostgreSQL only.
- Reference: `onConflict` goes in a second argument object; full-text
  `language` and options; `fns.cosineDistance`; `.prepared` with `groupBy`.
- Middleware: the fixture example matches the query structure, not SQL text,
  and skips mutation read-backs; what `lints` blocks on the ORM API.
- Migrations: the example hashes are the ones 8.0.0-rc.12 prints, and the
  pages agree on what `--from` takes and when `migration new` refuses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 .../docs/(index)/prisma-orm/from-scratch.mdx  |  2 +-
 apps/docs/content/docs/cli/configuration.mdx  | 28 ++++--
 apps/docs/content/docs/cli/contract-emit.mdx  |  4 +-
 apps/docs/content/docs/cli/migration-new.mdx  | 12 ++-
 apps/docs/content/docs/cli/migration-plan.mdx |  4 +-
 apps/docs/content/docs/cli/orm-init.mdx       | 12 ++-
 .../guides/upgrade-prisma-orm/mongodb.mdx     |  4 +-
 .../guides/upgrade-prisma-orm/postgresql.mdx  | 40 ++++++--
 .../docs/orm/coming-from-prisma-orm-7.mdx     | 99 ++++++++++++++++---
 .../orm/contract-authoring/editor-support.mdx |  2 +-
 .../orm/contract-authoring/psl-syntax.mdx     | 29 +++---
 .../the-contract-artifact.mdx                 |  2 +-
 .../contract-authoring/the-data-contract.mdx  |  6 +-
 .../typescript-schema-builder.mdx             |  6 +-
 .../content/docs/orm/data-modeling/index.mdx  |  2 +-
 .../docs/orm/extensions/using-extensions.mdx  |  8 +-
 .../orm/fundamentals/advanced-queries.mdx     |  2 +-
 .../docs/orm/fundamentals/transactions.mdx    | 16 ++-
 .../docs/orm/fundamentals/writing-data.mdx    |  4 +-
 .../authoring-custom-middleware.mdx           | 31 ++++--
 .../docs/orm/middleware/built-in-budgets.mdx  |  6 +-
 .../docs/orm/middleware/built-in-lints.mdx    | 19 +++-
 .../orm/middleware/how-middleware-works.mdx   |  4 +-
 .../orm/migrations/applying-a-migration.mdx   | 36 ++++---
 .../orm/migrations/editing-a-migration.mdx    | 30 +++---
 .../orm/migrations/generating-a-migration.mdx | 16 +--
 .../orm/migrations/how-migrations-work.mdx    | 28 ++++--
 .../orm/migrations/rollbacks-and-recovery.mdx |  4 +-
 .../orm/migrations/the-migration-graph.mdx    |  3 +-
 .../content/docs/orm/reference/orm-client.mdx | 58 +++++++----
 .../docs/orm/reference/sql-query-builder.mdx  | 18 +++-
 .../reference/transactions-and-runtime.mdx    |  9 +-
 apps/docs/content/docs/orm/release-status.mdx |  2 +-
 33 files changed, 391 insertions(+), 155 deletions(-)

diff --git a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
index a2409edd3c..753cfb1744 100644
--- a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
+++ b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
@@ -128,7 +128,7 @@ App space
 ✔ Advanced ref "db" → f4e1954fd8bed87828d13c3f1a02164dc9796ef1af76ed6f98184c01263169c5
 ```
 
-It also writes `migrations/app/refs/db.json` and a snapshot of the contract under `migrations/snapshots/`; commit both. If the command fails with `DRIVER.CONNECTION_FAILED`, `DATABASE_URL` in `.env` is wrong or the database is not reachable. A `SECURITY WARNING` about SSL modes comes from the `pg` driver and does not stop the command; change `sslmode=require` to `sslmode=verify-full` in `.env` to silence it.
+The `marker` line in the output is the record that signing stores in the database: the hash that identifies the version of the contract the database now matches. `db init` also writes `migrations/app/refs/db.json` and a snapshot of the contract under `migrations/snapshots/`; commit both. If the command fails with `DRIVER.CONNECTION_FAILED`, `DATABASE_URL` in `.env` is wrong or the database is not reachable. A `SECURITY WARNING` about SSL modes comes from the `pg` driver and does not stop the command; change `sslmode=require` to `sslmode=verify-full` in `.env` to silence it.
 
 ## 5. Write and read data
 
diff --git a/apps/docs/content/docs/cli/configuration.mdx b/apps/docs/content/docs/cli/configuration.mdx
index 99277e8533..f239a362c0 100644
--- a/apps/docs/content/docs/cli/configuration.mdx
+++ b/apps/docs/content/docs/cli/configuration.mdx
@@ -6,7 +6,7 @@ metaTitle: Prisma ORM CLI configuration
 metaDescription: 'Learn how Prisma ORM CLI commands find config, read database URLs, and format output.'
 ---
 
-Prisma ORM CLI commands read `prisma.config.ts`, starting in the directory you run them from. The file has one section per part of the CLI. The Prisma ORM data commands read the `orm` section; the [agent skills commands](/cli/skills) read the `skills` section.
+Prisma ORM CLI commands read `prisma.config.ts`, starting in the directory you run them from. The file has one section per part of the CLI. The `contract`, `db`, and `migration` commands read the `orm` section, and the [agent skills commands](/cli/skills) read the `skills` section.
 
 ## Config file
 
@@ -27,9 +27,9 @@ export default definePrismaConfig({
 });
 ```
 
-For MongoDB projects, import the section helper from `@prisma/orm-mongo/config` instead. The `defineConfig` you import from `@prisma/orm-postgres/config` or `@prisma/orm-mongo/config` keeps its name.
+For MongoDB projects, import the section helper from `@prisma/orm-mongo/config` instead. Both packages export this helper as `defineConfig`, and the examples on this page rename it to `ormConfig` when they import it.
 
-`defineConfig` from `@prisma/cli-engine` was the former name of `definePrismaConfig`, and `@prisma/cli-engine` 0.6.1 removed it. A config scaffolded by an earlier release candidate that imports it fails to load. Import `definePrismaConfig` instead, and call it in place of `defineConfig`.
+If you set up Prisma ORM 8 with a release candidate before `8.0.0-rc.12`, your config may import `defineConfig` from `@prisma/cli-engine`, the package the `prisma` CLI is built on. That was the old name of `definePrismaConfig`, and `@prisma/cli-engine` 0.6.1, which `8.0.0-rc.12` requires, no longer exports it, so the config fails to load. Import `definePrismaConfig` in its place and call it where you called `defineConfig`. You can import it from `prisma/config` or from `@prisma/cli-engine`, because `prisma/config` re-exports the same function.
 
 [`orm init`](/cli/orm-init) writes this file for you. Pass `--config` when your config file is not in the directory you run the command from:
 
@@ -39,7 +39,9 @@ npx prisma contract emit --config ./config/prisma.config.ts
 
 ## How the CLI finds the config
 
-The CLI looks for `prisma.config.ts` in the current directory, or starts from the file you pass to `--config`. It then looks in each parent directory, up to the root of the repository, which is the first directory that has a `.git` entry. It merges every `prisma.config.ts` it finds key by key, and where two files set the same key, the one nearest to the starting point wins.
+The CLI looks for `prisma.config.ts` in the current directory, or starts from the file you pass to `--config`. It then looks in each parent directory, up to the root of the repository, which is the first directory that has a `.git` entry. If neither the starting directory nor any directory above it has a `.git` entry, the CLI reads only the first file.
+
+The CLI combines the files it finds one section at a time. Inside a section such as `orm`, each top-level key, such as `contract`, `db`, or `migrations`, comes whole from the nearest file that sets it, and the keys nested inside it are not combined. So if a config higher up sets `db.connection` and your project's config sets only `contract`, the CLI uses your `contract` and the other file's `db`. `ormConfig` always sets `extensions`, to an empty list when you leave it out, so a project's `ormConfig` replaces any extension list set higher up.
 
 A project inside a larger repository therefore inherits any setting its own config leaves out from a `prisma.config.ts` higher up. To stop that, add `parent: false` to the project's config. The search then ends at that file:
 
@@ -55,7 +57,19 @@ export default definePrismaConfig({
 });
 ```
 
-`parent` also takes a path, which names the next config file to read instead of the one in the parent directory.
+`parent` can also be a path to another config file, which the CLI reads next in place of the one in the parent directory. The path is relative to the directory of the config file that sets it, and it may point outside the repository. After reading that file, the CLI goes on to search the directories above it in the usual way, unless that file sets `parent` too:
+
+```typescript title="prisma.config.ts"
+import { definePrismaConfig } from "prisma/config";
+import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";
+
+export default definePrismaConfig({
+  parent: "../shared/prisma.config.ts",
+  orm: ormConfig({
+    contract: "./prisma/contract.prisma",
+  }),
+});
+```
 
 A relative path in a config file, such as `contract`, `output`, or `migrations.dir`, resolves from the directory of the config file that sets it, not from the directory you run the command in. So `--config ./config/prisma.config.ts` with `contract: "./prisma/contract.prisma"` reads `./config/prisma/contract.prisma`.
 
@@ -97,9 +111,9 @@ export default definePrismaConfig({
 });
 ```
 
-`prisma7Schema` takes one schema file, or a directory of `.prisma` files as Prisma ORM 7 reads it. `contract emit` writes `contract.json` and `contract.d.ts` into the directory that holds the schema, here `prisma/`, unless you set `output`. Prisma ORM 7 keeps owning the database and its migrations: after each `prisma7 migrate dev` or `prisma7 migrate deploy`, run `npx prisma contract emit` and then `npx prisma db sign`.
+`prisma7Schema` takes one schema file, or a directory of `.prisma` files as Prisma ORM 7 reads it. `contract emit` writes `contract.json` and `contract.d.ts` into the directory that holds the schema, here `prisma/`, unless you set `output`. Prisma ORM 7 keeps owning the database and its migrations, and you run its commands as `prisma7`, the Prisma ORM 7 CLI that [`orm init --from-prisma7-schema`](/cli/orm-init#on-a-prisma-orm-7-project) installs next to Prisma ORM 8. After each Prisma ORM 7 migration, whether you ran `npx prisma7 migrate dev` or `npx prisma7 migrate deploy`, run `npx prisma contract emit` and then [`npx prisma db sign`](/cli/db-sign). `db sign` checks that the database matches the contract and then records that in the database, without changing your tables.
 
-Prisma ORM 8 describes each part of the schema exactly or refuses it. A part it cannot describe, such as a `view` block, `Unsupported(...)`, or `relationMode = "prisma"`, fails `contract emit` with an error that names the file, the line, and a Prisma ORM 7 edit that removes it. [`orm init --from-prisma7-schema`](/cli/orm-init#on-a-prisma-orm-7-project) writes this config for you.
+`contract emit` fails on any part of the schema that Prisma ORM 8 cannot represent exactly, such as a `view` block, `Unsupported(...)`, or `relationMode = "prisma"`. The error names the file and the line, and says how to change the Prisma ORM 7 schema so that the part is gone. Prisma ORM 8 has no views, so for a `view` block the error suggests removing the view or replacing it with a model over the table the view reads. `orm init --from-prisma7-schema` writes this config for you.
 
 ## Emit-only config
 
diff --git a/apps/docs/content/docs/cli/contract-emit.mdx b/apps/docs/content/docs/cli/contract-emit.mdx
index 13f6c062f7..0c04d75ba6 100644
--- a/apps/docs/content/docs/cli/contract-emit.mdx
+++ b/apps/docs/content/docs/cli/contract-emit.mdx
@@ -33,9 +33,9 @@ The command emits:
 - `contract.json`, the canonical machine-readable contract
 - `contract.d.ts`, the generated TypeScript contract declarations
 
-Do not edit these files by hand. Re-run `contract emit` after changing the contract source or extension pack list. `contract.d.ts` lists models, fields, and relations in the same order as `contract.json`.
+Do not edit these files by hand. Re-run `contract emit` after changing the contract source or extension pack list. The first emit after you upgrade to `8.0.0-rc.12` reorders the entries in `contract.d.ts` to follow the order in `contract.json`, which needs no change to your code.
 
-When the contract source cannot be read, the command fails with `CONTRACT.SOURCE_LOAD_FAILED`. The terminal prints each finding, and in `--json` output the error carries a `diagnostics` array with one entry per finding: its code, its summary, and, where known, its file and line.
+When the contract source cannot be read, the command fails with `CONTRACT.SOURCE_LOAD_FAILED` and prints each finding, meaning each problem it found in the source, with the file and line where it knows them. In `--json` output, the findings are the entries of the `envelope.diagnostics` array in the final `result` event, next to `envelope.error`. Each entry has a `code`, a `summary`, and, where known, `where.path` and `where.line`. A finding whose own code has no dot, such as `PSL_NO_OPTED_IN_SCHEMA_FILES`, has the `code` `CONTRACT.SOURCE_DIAGNOSTIC` and keeps its own code in `meta.code`.
 
 ## Run it automatically
 
diff --git a/apps/docs/content/docs/cli/migration-new.mdx b/apps/docs/content/docs/cli/migration-new.mdx
index e3c0b316aa..634c13af9d 100644
--- a/apps/docs/content/docs/cli/migration-new.mdx
+++ b/apps/docs/content/docs/cli/migration-new.mdx
@@ -21,20 +21,22 @@ npx prisma migration new --name split-name
 | Option | What it does |
 | --- | --- |
 | `--name <slug>` | Sets the migration directory name suffix. |
-| `--from <hash>` | Sets the starting contract: the target hash of an existing migration, or a unique prefix of one. Defaults to the `db` ref, as on [`migration plan`](/cli/migration-plan). A hash on an empty migrations directory, or a prefix that matches more than one migration, is refused. |
+| `--from <hash>` | Starts from the contract state an existing migration ends at: the `to` hash in that migration's `migration.json`, or a unique prefix of it. Without it, see [Where it starts](#where-it-starts). |
 | `--config <path>` | Read this config file instead of `./prisma.config.ts`. |
 | `--json` | Prints a machine-readable result. |
 
+`migration new` refuses `--from` when `migrations/app/` has no migrations, and refuses a prefix that matches more than one migration. Run `npx prisma migration list` to see the hashes of your migrations.
+
 ## Where it starts
 
-Without `--from`, `migration new` picks its starting point the way `migration plan` does:
+Without `--from`, `migration new` picks its starting point the way [`migration plan`](/cli/migration-plan) does. The result depends on whether the [`db` ref](/cli/migration-ref#the-db-ref) exists and whether `migrations/app/` has migrations. The `db` ref is the file `migrations/app/refs/db.json`, which records the contract state you expect your local database to match. `migrations/app/` is the folder for your application's own migrations, and each extension package that ships migrations has its own folder beside it.
 
 - When the `db` ref exists and `migrations/app/` has migrations, it starts from the `db` ref.
 - When there are no migrations and no `db` ref, it starts from an empty database.
-- When migrations exist but there is no `db` ref, it refuses with `MIGRATION.PLAN_ORIGIN_UNKNOWN`. Pass `--from` with the hash of the migration to build on, or set the ref with [`migration ref`](/cli/migration-ref). `npx prisma migration list` shows the hashes.
-- When the `db` ref exists but there are no migrations, it refuses and points you to `migration plan`, which writes the baseline first.
+- When migrations exist but there is no `db` ref, it refuses with `MIGRATION.PLAN_ORIGIN_UNKNOWN`. Pass `--from` with the `to` hash of the migration to build on, or point the `db` ref at the state your database is on with `npx prisma migration ref set db <contract>`, where `<contract>` is a hash or a migration directory name.
+- When the `db` ref exists but there are no migrations, it refuses with `MIGRATION.HASH_NOT_IN_GRAPH`. Run `migration plan` first: it writes a [baseline migration](/orm/migrations/the-migration-graph#baselines), a first migration from an empty database to the contract state the `db` ref names, and after that `migration new` can build on it.
 
-Before `8.0.0-rc.12`, `migration new` started from the newest migration. Scripts that relied on that should pass `--from`.
+Before `8.0.0-rc.12`, `migration new` started from the newest migration. Scripts that relied on that should pass `--from` with the newest migration's `to` hash.
 
 ## Examples
 
diff --git a/apps/docs/content/docs/cli/migration-plan.mdx b/apps/docs/content/docs/cli/migration-plan.mdx
index 116deeba78..5488ee2ab9 100644
--- a/apps/docs/content/docs/cli/migration-plan.mdx
+++ b/apps/docs/content/docs/cli/migration-plan.mdx
@@ -21,7 +21,9 @@ Keep the `db` ref current and you never see the refusal. [`db init`](/cli/db-ini
 
 When `migrations/app/` is empty and the `db` ref points at a contract whose snapshot is stored under `migrations/snapshots/`, one `migration plan` run writes a baseline package from nothing to the ref's contract and, when your emitted contract differs from the ref's, a second package with the delta. Expect one or two new directories in `git status`. The baseline is never replayed against a database that already carries a marker, because the runner starts from the marker and only applies edges past it.
 
-When the baseline would contain destructive operations, `migration plan` asks for consent before it writes it, as [`db update`](/cli/db-update) does. In a script, pass `--no-interactive --confirm <directory>`. It also warns when planning from the `db` ref would start a second branch in the migration history.
+If the baseline would contain destructive operations, which remove data when the migration is applied, `migration plan` lists them and asks you to confirm by typing the name of the directory you run the command in, usually your project directory, before it writes the baseline. In a script, pass that name instead, for example `--no-interactive --confirm my-app`. [`db update`](/cli/db-update) asks for consent the same way, with the database name.
+
+When the `db` ref points at a contract state that already has a migration leading away from it, planning from the ref starts a second branch in the migration history. This happens, for example, after `db migrate` without `--advance-ref db`, which applies migrations but does not update the `db` ref. `migration plan` still writes the migration and prints a warning. To build on the newest migration instead, pass `--from` with that migration's directory name.
 
 The command is offline. It does not need a database connection.
 
diff --git a/apps/docs/content/docs/cli/orm-init.mdx b/apps/docs/content/docs/cli/orm-init.mdx
index 71e1495451..2c77222db2 100644
--- a/apps/docs/content/docs/cli/orm-init.mdx
+++ b/apps/docs/content/docs/cli/orm-init.mdx
@@ -43,7 +43,7 @@ npx prisma@latest orm init --yes --target postgres --authoring psl
 The exact files depend on the target and authoring style, but a Postgres PSL setup normally includes:
 
 - `prisma.config.ts`
-- a starter contract file such as `src/prisma/contract.prisma`, whose first line is `// use prisma-8`
+- a starter contract file such as `src/prisma/contract.prisma`, whose first line is `// use prisma-8`. Keep that line, because `contract emit` reads only `.prisma` files that start with it.
 - emitted contract artifacts after installation runs
 - a runtime client file (`src/prisma/db.ts`) that imports `contract.json`
 - `.env.example`, `tsconfig.json`, and updated `package.json`
@@ -65,14 +65,18 @@ npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma
 
 A plain `orm init` offers the same setup when it finds a Prisma ORM 7 config, or a `prisma/schema.prisma` with a `datasource` block. The database target comes from the schema's `datasource` provider, and a `--target` that disagrees with it fails with `CLI.INIT_PRISMA7_TARGET_MISMATCH`.
 
-Before it changes any file, `orm init` installs `@prisma/orm-postgres` and checks that Prisma ORM 8 can read the schema. A schema it cannot read, for example one with a `view` block, stops the command with `CLI.INIT_PRISMA7_SCHEMA_REFUSED`, which lists each problem with its line and the Prisma ORM 7 edit that removes it. Then it asks for consent, which `--confirm <directory>` gives in a script, and:
+First, `orm init` installs `@prisma/orm-postgres` and `dotenv`, adding them to `package.json` if they are not there yet, and uses the installed package to check that Prisma ORM 8 can read the schema. Apart from that install, it changes nothing until the check passes. A schema it cannot read, for example one with a `view` block, stops the command with `CLI.INIT_PRISMA7_SCHEMA_REFUSED`, which lists each problem with its line and the Prisma ORM 7 edit that removes it, and gives the command that removes the packages it just added.
+
+When the check passes, `orm init` asks you to confirm by typing the name of the directory you run it in. In a script, pass that name instead, for example `--confirm my-app`. Then it:
 
 - renames the Prisma ORM 7 config to `prisma7.config.ts` and points its import at `@prisma/prisma7/config`
 - changes every `package.json` script that runs `prisma` to run `prisma7`
-- installs Prisma ORM 7 as `@prisma/prisma7`, next to `prisma@latest`
+- installs the latest Prisma ORM 7 release as `@prisma/prisma7`, next to `prisma@latest`
 - writes `prisma.config.ts` with `contract: prisma7Schema("<schema path>")`, plus `src/prisma/db.ts` and `prisma-8.md`
 
-It does not write a starter contract, and it does not change `prisma/` or the database. Prisma ORM 7 keeps owning the schema and its migrations. Set `DATABASE_URL` and run `npx prisma db sign` once. After each `prisma7 migrate dev`, run `npx prisma contract emit` and then `npx prisma db sign`. [Configuration](/cli/configuration#use-a-prisma-orm-7-schema) explains `prisma7Schema`, and [the upgrade guide](/guides/upgrade-prisma-orm/postgresql) covers the rest of the move.
+It does not write a starter contract, and it changes nothing in `prisma/` or in the database. Prisma ORM 7 keeps owning the schema and its migrations. From now on, `prisma` runs Prisma ORM 8 and `prisma7` runs Prisma ORM 7, so a Prisma ORM 7 command such as `migrate dev` becomes `npx prisma7 migrate dev`. Your application keeps using the Prisma ORM 7 client until you move its routes, one at a time, to the Prisma ORM 8 client in `src/prisma/db.ts`. If your `package.json` listed `@prisma/client` below version 7, `orm init` also installs `@prisma/client@7` to match `@prisma/prisma7`, so run `npx prisma7 generate` afterwards.
+
+To finish, set `DATABASE_URL` and run `npx prisma db sign` once. [`db sign`](/cli/db-sign) checks that the database matches the contract and then writes the marker, a record in the database of which contract it matches, without changing your tables. After each Prisma ORM 7 migration, whether you ran `npx prisma7 migrate dev` or `npx prisma7 migrate deploy`, run `npx prisma contract emit` and then `npx prisma db sign` again. [Configuration](/cli/configuration#use-a-prisma-orm-7-schema) explains `prisma7Schema`, and [the upgrade guide](/guides/upgrade-prisma-orm/postgresql) covers the rest of the move.
 
 ## Examples
 
diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx
index 5a892eb4ce..c7b4c575fc 100644
--- a/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx
+++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx
@@ -24,7 +24,7 @@ Install the companion [prisma-mongodb-upgrade](https://github.com/prisma/skills/
 
 :::info
 
-Prisma ORM MongoDB support evolves quickly, so check anything below against the `@prisma/orm-*` version you install. This guide targets `@prisma/orm-mongo@8.0.0-rc.12`.
+This guide is written for `@prisma/orm-mongo@8.0.0-rc.12`. MongoDB support in Prisma ORM 8 still changes between release candidates, so a newer version may behave differently from what this guide shows.
 
 :::
 
@@ -106,7 +106,7 @@ export { prisma };
 
 :::note
 
-Prisma ORM 8 addresses collections by **storage name**, not model name: `db.orm.users` (the `@@map` name, or the model name exactly as written), never `db.orm.User` when the model maps to `users`. Whatever you `@@map` in this step is the exact name every client call uses in step 3.
+On MongoDB, `db.orm` holds your models by collection name. The collection name is the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. So a model `User` with `@@map("users")` is `db.orm.users`, and `db.orm.User` does not exist. PostgreSQL works differently: there `db.orm` uses the model name, as in `db.orm.public.User`. Whatever you `@@map` in this step is the exact name every client call uses in step 3.
 
 :::
 
diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
index b34df2921f..c58e2f3acc 100644
--- a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
+++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
@@ -14,7 +14,7 @@ The guide covers **PostgreSQL only**. Guidance for other databases will follow.
 
 :::info
 
-This guide targets `prisma@latest`, `@prisma/orm-postgres@8.0.0-rc.12`, `@prisma/cli-engine@0.6.1`, and `@prisma/prisma7@7.10.0`, with a Prisma ORM 7 baseline on `7.9.1`. `prisma@latest` is the Prisma ORM 8 CLI, `8.0.0-rc.17` at the time of writing. It is versioned and released separately from the ORM packages, so its version number will not match theirs.
+This guide targets `prisma@latest`, `@prisma/orm-postgres@8.0.0-rc.12`, and `@prisma/prisma7@7.10.0`, and the example app in step 1.1 starts on Prisma ORM 7.10.0. `prisma@latest` is the Prisma ORM 8 CLI, `8.0.0-rc.17` at the time of writing. It is versioned and released separately from the ORM packages, so its version number will not match theirs. It installs `@prisma/cli-engine@0.6.1` as its own dependency, so you do not install that package yourself.
 
 :::
 
@@ -36,7 +36,7 @@ The [prisma8-and-7-example](https://github.com/prisma/prisma8-and-7-example) rep
 
 - **Node.js 22.18 or newer (on the 24 line, 24.11 or newer)**; Node.js 24 recommended
 - A working **Prisma ORM 7** application on PostgreSQL: `prisma.config.ts`, the `prisma-client` generator, and a driver adapter
-- **TypeScript 5.3+** with `"strict": true` and a `module` setting that supports import attributes, such as `"nodenext"`
+- **TypeScript 5.9+** with `"strict": true` and a `module` setting that supports import attributes, such as `"nodenext"`
 
 ## 1. Prepare Prisma ORM 7 for side-by-side operation
 
@@ -228,7 +228,7 @@ After this install, `npx prisma <command>` runs the Prisma ORM 8 CLI and `npx pr
 npx prisma --version
 ```
 
-**Expected result:** `8.0.0-rc.17` (or newer). The CLI's version line is separate from `@prisma/orm-postgres`'s.
+**Expected result:** the command prints `8.0.0-rc.17` or a newer version. That number does not match the version of `@prisma/orm-postgres`, because the CLI is released separately.
 
 ### 2.2. Create the Prisma ORM 8 config
 
@@ -269,17 +269,41 @@ npx prisma contract infer --output prisma8/contract.prisma
 
 :::tip[Read the Prisma ORM 7 schema instead]
 
-Prisma ORM 8 can also read `prisma/schema.prisma` directly, so you keep one schema file while Prisma ORM 7 owns migrations. Set `contract: prisma7Schema("prisma/schema.prisma")` in `prisma.config.ts`, with `prisma7Schema` imported from `@prisma/orm-postgres/config`, and skip steps 2.3 and 2.4. After each `prisma7 migrate dev`, run `npx prisma contract emit` and then `npx prisma db sign`. [`prisma orm init --from-prisma7-schema prisma/schema.prisma`](/cli/orm-init#on-a-prisma-orm-7-project) sets this up, and does phase 1 as well. [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema) lists what Prisma ORM 8 cannot read. The steps in phase 4 are written for the inferred `prisma8/contract.prisma`.
+Prisma ORM 8 can also read `prisma/schema.prisma` directly as its contract, so you keep one schema file while Prisma ORM 7 owns migrations. On this path `schema.prisma` does not need a `// use prisma-8` line. Skip steps 2.3 and 2.4, and change two lines in `prisma.config.ts`:
+
+```typescript title="prisma.config.ts"
+import "dotenv/config";
+import { definePrismaConfig } from "prisma/config";
+import { defineConfig as definePostgresConfig } from "@prisma/orm-postgres/config"; // [!code --]
+import { defineConfig as definePostgresConfig, prisma7Schema } from "@prisma/orm-postgres/config"; // [!code ++]
+
+export default definePrismaConfig({
+  orm: definePostgresConfig({
+    contract: "prisma8/contract.prisma", // [!code --]
+    contract: prisma7Schema("prisma/schema.prisma"), // [!code ++]
+    output: "generated/prisma8",
+    db: {
+      connection: process.env["DATABASE_URL"],
+    },
+  }),
+});
+```
+
+After step 2.5, run `npx prisma db sign`, which checks that the database matches the contract Prisma ORM 8 read from `schema.prisma` and records in the database that it does. Step 4.1 describes `db sign` in full. Because Prisma ORM 7 keeps changing the database on this path, run `npx prisma contract emit` and then `npx prisma db sign` again after each `prisma7 migrate dev`. [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema) lists the parts of a Prisma ORM 7 schema that Prisma ORM 8 cannot read.
+
+If you have not started phase 1 yet, [`prisma orm init --from-prisma7-schema prisma/schema.prisma`](/cli/orm-init#on-a-prisma-orm-7-project) does phase 1 and this setup in one command.
+
+Phase 4 is written for the inferred `prisma8/contract.prisma`, and does not yet cover a project that reads `schema.prisma` through `prisma7Schema(...)`.
 
 :::
 
 ### 2.4. Edit the inferred contract
 
-Delete the `PrismaMigrations` model. `contract infer` picks up Prisma ORM 7's `_prisma_migrations` ledger table. Prisma ORM 8 must not manage it, and extra tables in the database are fine. Remove the whole model.
+`contract infer` reads every table in the database, so it also writes a `PrismaMigrations` model for `_prisma_migrations`, the table where Prisma ORM 7 records which migrations it has applied. Delete that model from the contract, because Prisma ORM 8 must not manage the table. The table itself stays in the database, and an extra table that the contract does not describe is fine.
 
-The models need no `@@map`. A model without `@@map` names its table exactly as written, so `User` reads and writes the `"User"` table that Prisma ORM 7 created.
+You do not need to add `@@map` to the other models: a model without `@@map` uses its name, exactly as written, as its table name, so `User` reads and writes the `"User"` table that Prisma ORM 7 created.
 
-The finished contract:
+After that edit, the contract looks like this:
 
 ```prisma title="prisma8/contract.prisma"
 // use prisma-8
@@ -304,7 +328,7 @@ model Post {
 }
 ```
 
-Keep `// use prisma-8` as the first line: `contract emit` reads only files that start with it.
+Keep `// use prisma-8` as the first line of `prisma8/contract.prisma`, because `contract emit` reads only the `.prisma` files that start with it. A `schema.prisma` that Prisma ORM 8 reads through `prisma7Schema(...)`, as in the tip under step 2.3, does not need the line.
 
 ### 2.5. Emit the contract artifacts
 
diff --git a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
index a2cba004db..601cbb2cea 100644
--- a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
+++ b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
@@ -14,7 +14,15 @@ All examples use PostgreSQL.
 
 ## Before you start
 
-If you are adding Prisma ORM 8 to an application that runs Prisma ORM 7, follow [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql). It installs both versions side by side and takes over your existing database. Do not run the commands below in that project: `npm install prisma` installs version 8 and replaces the version 7 command-line tool. On PostgreSQL, [`prisma orm init --from-prisma7-schema prisma/schema.prisma`](/cli/orm-init#on-a-prisma-orm-7-project) does that setup for you, and Prisma ORM 8 then reads your `schema.prisma` as its contract.
+If you are adding Prisma ORM 8 to an application that runs Prisma ORM 7, do not run the new-project commands further down in that project, because `npm install prisma` installs version 8 in place of the version 7 command-line tool. Follow [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql) instead. It runs both versions side by side against your existing database without changing its data, and ends with Prisma ORM 8 managing its migrations.
+
+On PostgreSQL, the following command does the guide's first phase for you, and sets up Prisma ORM 8 to read your `schema.prisma` as its contract. `schema.prisma` does not need a `// use prisma-8` line for this.
+
+```npm
+npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma
+```
+
+It does not change `prisma/` or the database. [`orm init` on a Prisma ORM 7 project](/cli/orm-init#on-a-prisma-orm-7-project) lists what it changes, and the guide covers the rest of the move.
 
 In a new project, three commands set up Prisma ORM 8:
 
@@ -37,7 +45,7 @@ The biggest visible change is in field types. Where Prisma ORM 7 wrote a Prisma
 | Prisma ORM 7 | Prisma ORM 8 | Notes |
 | --- | --- | --- |
 | `schema.prisma` | `contract.prisma` | |
-| (nothing) | `// use prisma-8` as the first line | `prisma orm init` writes it; add it yourself if you write the contract by hand. `prisma contract emit` reads only the files that start with it, and the [Prisma editor extension](/orm/contract-authoring/editor-support) does not recognise a file without it. |
+| (nothing) | `// use prisma-8` as the first line | required in every contract file; see the note below the table |
 | `generator client { ... }` | removed | `emit` is the new word for `generate`. `prisma contract emit` writes two files next to your contract, `contract.json` and `contract.d.ts`. Commit both |
 | `datasource db { ... }` | the `orm` section of `prisma.config.ts` | the connection string and file paths live in the config file, not the schema. Example below |
 | `String @db.Text` | `String` | `String` is already stored as `text`. A known bug in one error message suggests `Text`; there is no such type |
@@ -49,17 +57,43 @@ The biggest visible change is in field types. Where Prisma ORM 7 wrote a Prisma
 | `updatedAt DateTime @updatedAt` | `updatedAt temporal.updatedAt()` | write `temporal.updatedAt()` where the type would go. It declares a `DateTime` field and sets it on every create and update. Any field name works. `temporal.` is part of the contract syntax; there is nothing to import |
 | `createdAt DateTime @default(now())` | the same, or `createdAt temporal.createdAt()` | both work. `@default(now())` is a database default. `temporal.createdAt()` is set by Prisma ORM from your application's clock and gives the column no database default |
 | `String @default(cuid())` | `String @default(cuid(2))` | `2` is the cuid version. Plain `cuid()` is rejected |
-| `@default(dbgenerated("gen_random_uuid()"))` | ``@default(sql`gen_random_uuid()`)`` | `dbgenerated` is rejected. Any SQL expression is a `sql` tagged literal, except `now()` and `autoincrement()`, which you write as those functions. [Default values](/orm/contract-authoring/psl-syntax#default-values) covers every kind of default |
+| `@default(dbgenerated("gen_random_uuid()"))` | ``@default(sql`gen_random_uuid()`)`` | `dbgenerated` is rejected. Write any SQL expression as `` sql`...` `` instead, but keep writing `now()` and `autoincrement()` as plain functions. [Default values](/orm/contract-authoring/psl-syntax#default-values) covers every kind of default |
 | `Json` | `Jsonb` | Prisma ORM 7's `Json` stored a PostgreSQL `jsonb` column, so write `Jsonb`. In Prisma ORM 8, `Json` means PostgreSQL's older `json` type, which you almost certainly do not want |
-| `Json @default("{}")` | ``Jsonb @default(json`{}`)`` | a JSON default is a `json` tagged literal. A quoted string is text, and a JSON column does not accept it |
+| `Json @default("{}")` | ``Jsonb @default(json`{}`)`` | write a JSON default as `` json`...` ``. A quoted string is text, and a JSON column does not accept it |
 | `enum Role { ADMIN USER }`, in a new database | `enum Role { ADMIN USER }` | same syntax. You can give members explicit values (`ADMIN = "admin"`). The column is stored as text, not as a PostgreSQL enum type |
-| `enum Role { ADMIN USER }` with a field `role Role`, in an existing Prisma ORM 7 database | `native_enum Role { ADMIN = "ADMIN" USER = "USER" }` with the field `role pg.enum(Role)` | your database already has a PostgreSQL enum type for it; `native_enum` keeps it. Every member needs an explicit value. You can switch to a plain `enum` later; that changes the column type, so it needs a migration. `pg.` is part of the contract syntax, like `temporal.`. A `pg.enum(...)` column has no `like` or `ilike`; compare it with `eq` or `in` |
+| `enum Role { ADMIN USER }` with a field `role Role`, in an existing Prisma ORM 7 database | `native_enum Role { ADMIN = "ADMIN" USER = "USER" }` with the field `role pg.enum(Role)` | your database already has a PostgreSQL enum type for it, and `native_enum` keeps it. See the note below the table |
 | `String[]` | `String[]` | unchanged on PostgreSQL. The list filters (`has`, `hasEvery`, `hasSome`, `isEmpty`) are not available; filter on a list with raw SQL for now (see below) |
 | `@@schema("billing")` | `namespace billing { model ... }` | a `namespace` block is a PostgreSQL schema; wrap the models in it. They become `db.orm.billing.Invoice` and so on |
 | implicit many-to-many (`Post[]` on `Tag` and `Tag[]` on `Post`, with no model for the join table) | the same two list fields, plus a model for the join table | you write the join table as a model yourself. Example below |
 | `@id`, `@unique`, `@default`, `@relation`, `@map`, `@@map`, `@@index`, `@@id`, `@@unique` | unchanged | a model without `@@map` names its table after the model, exactly as written, as in Prisma ORM 7 |
 | a required relation field over an optional foreign key, or the reverse | rejected | since `8.0.0-rc.10`, `contract emit` reports `PSL_RELATION_NULLABILITY_MISMATCH`. Give the relation field and its `@relation(fields: [...])` columns the same `?`, or none |
 
+:::note[The first line of a contract file]
+
+Every contract file must start with `// use prisma-8`. `prisma orm init` writes the line for you, so you add it yourself only when you create a contract file by hand. `prisma contract emit` reads only the `.prisma` files that start with this line and skips the others without a warning, and the [Prisma editor extension](/orm/contract-authoring/editor-support) does not recognize a file without it.
+
+:::
+
+:::note[Enums in a database that Prisma ORM 7 created]
+
+Prisma ORM 7 stored each `enum` as a PostgreSQL enum type. To keep that type, declare the enum with `native_enum`, give every member an explicit value, and write the field's type as `pg.enum(Role)`. Like `temporal.`, `pg.` is part of the contract syntax, so there is nothing to import.
+
+```prisma title="src/prisma/contract.prisma (excerpt)"
+native_enum Role {
+  ADMIN = "ADMIN"
+  USER  = "USER"
+}
+
+model User {
+  id   Int           @id @default(autoincrement())
+  role pg.enum(Role)
+}
+```
+
+Filter a `pg.enum(...)` field with `eq` or `in`, because it has no `like` or `ilike`. You can switch to a plain `enum` later, but that changes the column type, so it needs a migration.
+
+:::
+
 :::note[DateTime values and Node.js versions]
 
 The `DateTime` type reads and writes its values as `Temporal.Instant` objects. If you would rather work with the timestamp as a string, write `TimestamptzString` in place of `DateTime`.
@@ -122,7 +156,7 @@ export default definePrismaConfig({
 
 The `orm` section takes these keys:
 
-- `contract`: the path to your contract file, or a glob for a [contract in several files](/orm/contract-authoring/psl-syntax#split-the-contract-across-several-files). On PostgreSQL it can also be `prisma7Schema("prisma/schema.prisma")`, which reads your Prisma ORM 7 schema as it is; see [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema).
+- `contract`: the path to your contract file, or a glob for a [contract in several files](/orm/contract-authoring/psl-syntax#split-the-contract-across-several-files). On PostgreSQL it can also be `prisma7Schema("prisma/schema.prisma")`, with `prisma7Schema` imported from `@prisma/orm-postgres/config` next to `defineConfig`. It reads your Prisma ORM 7 schema as it is, with no `// use prisma-8` line; see [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema).
 - `db`: the connection.
 - `output` (optional): where `contract.json` and `contract.d.ts` are written. Default: next to the contract.
 - `extensions` (optional): database extensions, for example `extensions: [pgvector]` with `import pgvector from "@prisma/orm-extension-pgvector/control"`. See [Using extensions](/orm/extensions/using-extensions).
@@ -182,8 +216,8 @@ export const db = postgres<Contract>({
 `db` has these parts:
 
 - `db.orm`: your models, by model name (`db.orm.public.User`).
-- `db.sql`: your tables, by table name (`db.sql.public.User`; the table name is the model name, unless you set `@@map`). You need it only for raw SQL.
-- `db.raw.sql`: writes a raw SQL query.
+- `db.sql`: the [SQL query builder](/orm/reference/sql-query-builder), with your tables by table name (`db.sql.public.User`; the table name is the model name, unless you set `@@map`). On this page it appears only in the raw SQL examples, which take the type of each returned column from it.
+- `db.raw.sql`: writes a raw SQL query as text.
 - `db.runtime()`: the connection. It runs raw queries.
 - `db.transaction`: runs several queries in one transaction.
 
@@ -211,7 +245,7 @@ A query is a chain of calls that you `await` as a whole. The last call (`.all()`
 | `create({ data: { ..., posts: { create: [...] } } })` | `.create({ ..., posts: (p) => p.create([...]) })`; `connect` works the same way |
 | `createMany({ data: [...] })` | `.createAll([...])` to get the rows back, or `.createAndCount([...])` to get a count |
 | `createMany({ data: [...], skipDuplicates: true })` | `.createAll([...], { onConflict: "skip" })` or `.createAndCount([...], { onConflict: "skip" })` |
-| `where: { title: { search: "cat & dog" } }`, with the `fullTextSearchPostgres` preview feature | `.where((p) => p.title.fullTextMatches(toTsquery("cat & dog")))`, with `toTsquery` from `@prisma/orm-postgres/target/full-text`. `websearchToTsquery(input)` reads search-box text. Sort by relevance with `.orderBy((p) => p.title.fullTextRank(query).desc())`, where `query` is the same `toTsquery(...)` value. Add `@@fullTextIndex([title], name: "...")` to the model so PostgreSQL can use an index. See [Full-text search](/orm/reference/orm-client#full-text-search) |
+| `where: { title: { search: "cat & dog" } }`, with the `fullTextSearchPostgres` preview feature | `.where((p) => p.title.fullTextMatches(toTsquery("cat & dog")))`. See [Full-text search](#full-text-search) below |
 | `update({ where, data })` | `.where(...).update({ ... })` |
 | `updateMany({ where, data })` | `.where(...).updateAll({ ... })` for the rows, or `.updateAndCount({ ... })` for a count |
 | `delete({ where })` | `.where(...).delete()` |
@@ -285,7 +319,9 @@ const update = db.raw.sql`UPDATE "User" SET active = false WHERE id = ${id}`
 await db.runtime().execute(update);
 ```
 
-The table is `User`, as in Prisma ORM 7: a model without `@@map` names its table after the model. Every raw query that returns rows needs `.returnsRow(...)` with a type per column, and you take the type from the table, as above. For a computed column, write the type name instead, such as `pg/int4@1` or `pg/text@1`; the `@1` is a version number and is always `1` today. [Raw queries](/orm/reference/raw-queries) lists the names. Finish the query with `.build()` and pass it to `db.runtime().query()` for rows or `db.runtime().execute()` for a count.
+The table is `User`, as in Prisma ORM 7: a model without `@@map` names its table after the model. A value you put in the SQL with `${...}`, such as `${id}`, is sent to the database as a query parameter, not pasted into the SQL text, as with Prisma ORM 7's `$executeRaw`.
+
+Every raw query that returns rows needs `.returnsRow(...)` with a type per column, and you take the type from the table, as above. A computed column has no table column to take it from, so write the type name as a string instead: for `SELECT count(*) AS total FROM "User"`, write `.returnsRow({ total: "pg/int8@1" })`. [Raw queries](/orm/reference/raw-queries) lists the type names. Finish the query with `.build()` and pass it to `db.runtime().query()` for rows or `db.runtime().execute()` for a count. On PostgreSQL, `db.runtime()` returns the connection directly, so it needs no `await`; the MongoDB client's `db.runtime()` is the one you `await`.
 
 ### Transaction
 
@@ -304,13 +340,29 @@ const result = await db.transaction(async (tx) => {
 });
 ```
 
+### Full-text search
+
+Import the functions that build a search query from `@prisma/orm-postgres/target/full-text`. `toTsquery` takes PostgreSQL's operator syntax as written, such as `cat & dog`, and fails on text that is not valid syntax, so use it only for text your application writes. For text a user types into a search box, use `websearchToTsquery`, which accepts quoted phrases, `or`, and `-` in front of a word to exclude it. To sort by relevance, pass the same query to `fullTextRank`:
+
+```ts title="Prisma ORM 8"
+import { websearchToTsquery } from "@prisma/orm-postgres/target/full-text";
+
+const query = websearchToTsquery('"cat food" -dog');
+const posts = await db.orm.public.Post
+  .where((p) => p.title.fullTextMatches(query))
+  .orderBy((p) => p.title.fullTextRank(query).desc())
+  .all();
+```
+
+Add `@@fullTextIndex([title], name: "post_title_search")` to the `Post` model so PostgreSQL can use an index for the search. [Full-text search](/orm/reference/orm-client#full-text-search) covers the other options.
+
 ## Not available [#not-available-yet]
 
 Prisma ORM 7 features that have no direct form in Prisma ORM 8, with what to do instead. The status column says which: not available today, available in a different form, coming in the next release, or (for `$extends`) not coming.
 
 | Prisma ORM 7 feature | Status | What to do instead |
 | --- | --- | --- |
-| `skipDuplicates` on `createMany` | available in a different form | `.createAll(rows, { onConflict: "skip" })` or `.createAndCount(rows, { onConflict: "skip" })` skips each row that collides with a unique constraint; add `conflictOn: ["email"]` to name the constraint. `createAll` returns only the rows the database wrote. Run `prisma contract emit` once before you use it, because a contract emitted before `8.0.0-rc.12` does not list the capability it needs |
+| `skipDuplicates` on `createMany` | available in a different form | `.createAll(rows, { onConflict: "skip" })` or `.createAndCount(rows, { onConflict: "skip" })`. See the note below the table |
 | `{ increment: n }` / `{ decrement: n }` in an update | not available | write the arithmetic as raw SQL (see the example above), or read the value and write it back inside `db.transaction(...)` |
 | `findUniqueOrThrow` / `findFirstOrThrow` | not available on the query | the usual form is `.first()` and a `null` check. If you want the throw, write `await db.orm.public.User.where({ id }).all().firstOrThrow()`. It throws an error with code `RUNTIME.NO_ROWS` when nothing matches. Avoid it on a filter that can match many rows; it reads them all first |
 | `mode: "insensitive"` | available in a different form | on PostgreSQL, `.ilike("%alice%")` on a text field. You write the `%` wildcards yourself |
@@ -323,10 +375,33 @@ Prisma ORM 7 features that have no direct form in Prisma ORM 8, with what to do
 | `$use` middleware | available in a different form | pass `middleware: [...]` when you create the client in `db.ts` (example in the `db.ts` section above). [How middleware works](/orm/middleware/how-middleware-works) lists the hooks |
 | `$extends` | replaced by middleware | `$extends` will not be added. Middleware replaces it and can do more; see [How middleware works](/orm/middleware/how-middleware-works) |
 
+:::note[Skipping duplicate rows]
+
+With `{ onConflict: "skip" }`, `.createAll(...)` and `.createAndCount(...)` skip each row that collides with any unique constraint on the table, and `createAll` returns only the rows the database wrote. To watch only one unique constraint, list its fields in `conflictOn`:
+
+```ts
+const created = await db.orm.public.User.createAll(rows, {
+  onConflict: "skip",
+  conflictOn: ["email"],
+});
+```
+
+Here `conflictOn` is a list of field names. In `upsert` it is an object of fields and values instead. If you emitted your contract before `8.0.0-rc.12`, run `prisma contract emit` again before you use `onConflict`; otherwise the call fails with `ORM.CAPABILITY_MISSING`.
+
+:::
+
 Also not available today:
 
 - Nested writes other than `create`, `connect`, and `disconnect`: `connectOrCreate`, nested `update`, `updateMany`, `upsert`, `delete`, `deleteMany`, and `set` on a relation. Change the related rows through their own model instead, for example `db.orm.public.Post.where({ authorId }).updateAll({ ... })`, inside `db.transaction(...)` if it must be atomic.
-- The list filters `has`, `hasEvery`, `hasSome`, and `isEmpty` on `String[]` and other list fields. The fields themselves work; filter on them with raw SQL, for example ``db.raw.sql`SELECT id FROM "Post" WHERE ${tag} = ANY(tags)` ``.
+- The list filters `has`, `hasEvery`, `hasSome`, and `isEmpty` on `String[]` and other list fields. The fields themselves work, and you can filter on them with a raw SQL query written the same way as the [raw SQL example](#raw-sql) above. For a `Post` model with a `tags String[]` field:
+
+  ```ts
+  const post = db.sql.public.Post;
+  const query = db.raw.sql`SELECT id FROM "Post" WHERE ${tag} = ANY(tags)`
+    .returnsRow({ id: post.columns.id })
+    .build();
+  const rows = await db.runtime().query(query);
+  ```
 - Transaction options: `isolationLevel`, `timeout`, `maxWait`, and transactions inside transactions.
 - `omit`, `relationLoadStrategy`, `Prisma.skip`, and the automatic batching of `findUnique` calls.
 - The `P2002` / `P2025` style error codes. Errors carry a `code` such as `RUNTIME.NO_ROWS` instead, and a database error such as a unique-constraint violation carries the standard SQL state code in `error.sqlState` (`23505` for a unique violation, on every database), so catch it with `if (error instanceof Error && "sqlState" in error && error.sqlState === "23505")`. See the [error reference](/orm/reference/error-reference).
diff --git a/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx b/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx
index a793808427..18535a8795 100644
--- a/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx
@@ -28,7 +28,7 @@ Contracts from before `8.0.0-rc.10` start with `// use prisma-next`, the preview
 
 - **Errors** appear inline as you type. They are the same errors you would get from [`prisma contract emit`](/cli/contract-emit), the command that checks the contract and writes `contract.json` and `contract.d.ts`.
 - **Formatting** reformats the whole file. In VS Code, run **Format Document**.
-- **Completion** starts when you type `@` or `@@`. The editor lists attribute names such as `@id`, `@default`, and `@@index`, each with a short description. Inside an attribute, it lists the names of the arguments you have not filled in yet, and it suggests values for them, including values nested inside lists, records, and function calls. Where an attribute expects a field name, it suggests only scalar fields. When an attribute has required arguments, VS Code inserts them as placeholders named after each argument, which you tab through.
+- **Completion** starts when you type `@` or `@@`. The editor lists attribute names such as `@id`, `@default`, and `@@index`, each with a short description. Inside an attribute, it lists the names of the arguments you have not filled in yet, and it suggests values for them, including values you type inside `[ ]`, inside `{ }`, and inside a call such as `createdAt(sort: Desc)`. Where an attribute expects a field name, it suggests only scalar fields. When an attribute has required arguments, VS Code inserts them as placeholders named after each argument, which you tab through.
 - **Signature help** appears when you type `(` or `,` inside an attribute. It shows the attribute's arguments and describes the one you are typing.
 
 The list of attributes comes from your `prisma.config.ts`: the database it declares and the Prisma extension packs listed under `extensions`; see [Extension packs](/cli/configuration#extension-packs) for that config. Extension packs are add-on packages for database features such as [pgvector](/orm/extensions/using-extensions). If your config lists the pgvector pack, the editor also suggests pgvector's attributes. No database connection is needed.
diff --git a/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx b/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
index 00019192cc..7ec5e0aefa 100644
--- a/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
@@ -18,7 +18,7 @@ The `datasource` and `generator` blocks are gone: the connection URL and the fil
 
 ## A complete contract
 
-Every contract file starts with `// use prisma-8`. `contract emit` reads only the files that start with this line, so keep it at the top. A file without it is left out of the contract without a warning, and when no file has it, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`.
+The first non-blank line of every contract file is `// use prisma-8`, because `contract emit` reads only the `.prisma` files that start with it. When `contract` names one file and that file lacks the line, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`, and the error's finding is `PSL_NO_OPTED_IN_SCHEMA_FILES`. When `contract` is a [glob that matches several files](#split-the-contract-across-several-files), a file without the line is left out of the contract without a warning, and `contract emit` fails only when none of the files has it.
 
 ```prisma title="src/prisma/contract.prisma" tab="PostgreSQL"
 // use prisma-8
@@ -128,16 +128,18 @@ export default definePrismaConfig({
 
 ### Split the contract across several files
 
-Set `contract` to a glob, such as `"./src/prisma/**/*.prisma"`, to write the contract in several files. Every matching file that starts with `// use prisma-8` becomes part of one contract, and a file you add later joins it on the next `contract emit`, with no change to the config. A model in one file can refer to a model in another. `contract emit` writes `contract.json` and `contract.d.ts` into the fixed part of the glob, here `./src/prisma/`. See [Configuration](/cli/configuration#split-the-schema-across-several-files).
+Set `contract` to a glob, such as `"./src/prisma/**/*.prisma"`, to write the contract in several files. Every matching file that starts with `// use prisma-8` becomes part of one contract, and a file you add later joins it on the next `contract emit`, with no change to the config. A model in one file can refer to a model in another. `contract emit` writes `contract.json` and `contract.d.ts` into the folder before the first wildcard, here `./src/prisma/`. See [Configuration](/cli/configuration#split-the-schema-across-several-files).
 
 ## Models and fields
 
-Models declare fields with a type, an optional `?` marker, and attributes. [Scalar fields](/orm/data-modeling#scalar-fields) lists the types a field can hold, among them `String`, `Int`, `Boolean`, `Decimal`, `DateTime`, `Json`, and `Bytes`. You can write a PostgreSQL type wherever you would write `String` or `DateTime`. The PostgreSQL types you can write are `VarChar`, `Char`, `Numeric`, `Timestamp`, `Timestamptz`, `Time`, `Timetz`, `Date`, `Uuid`, `Inet`, `SmallInt`, and `Real`, plus `DateString`, `TimestampString`, `TimestamptzString`, and `TimeString`, which store the same columns but read back as text, and `TimestamptzJsDate`, a `timestamptz` column that reads and writes a JavaScript `Date` and needs no `Temporal` polyfill. A `Date` keeps only milliseconds. On PostgreSQL, plain `String` is a `text` column, `Int` is `int4`, and `DateTime` is `timestamptz`.
+Models declare fields with a type, an optional `?` marker, and attributes. [Scalar fields](/orm/data-modeling#scalar-fields) lists the types a field can hold, among them `String`, `Int`, `Boolean`, `Decimal`, `DateTime`, `Json`, and `Bytes`. On PostgreSQL, plain `String` is a `text` column, `Int` is `int4`, and `DateTime` is `timestamptz`, and you can write a PostgreSQL type wherever you would write `String` or `DateTime`: `VarChar`, `Char`, `Numeric`, `Timestamp`, `Timestamptz`, `Time`, `Timetz`, `Date`, `Uuid`, `Inet`, `SmallInt`, or `Real`.
+
+On PostgreSQL, `DateTime`, `Timestamp`, `Timestamptz`, `Time`, and `Date` reach your code as `Temporal` values, such as a `Temporal.Instant` for `DateTime`, so your app needs a global `Temporal` to read and write them; [Scalar fields](/orm/data-modeling#scalar-fields) says how to check for it. When you want a string instead, use `DateString`, a `date` column your code gets as a string, or `TimestampString`, `TimestamptzString`, and `TimeString`, which do the same for `timestamp`, `timestamptz`, and `time`. `TimestamptzJsDate` is a `timestamptz` column your code gets as a JavaScript `Date`, so it needs no `Temporal`, but a `Date` drops the microseconds PostgreSQL stores.
 
 - `@id` marks the primary key. `@@id([a, b])` declares a composite key.
 - `@unique` adds a unique constraint on one field. `@@unique([userId, title])` adds one across several fields.
 - `@@index([...])` declares a secondary index.
-- `@default(...)` sets a default. Database defaults are a literal, `@default(now())`, `@default(autoincrement())`, or a SQL expression written as a `sql` tagged literal, such as ``@default(sql`gen_random_uuid()`)``; the database fills them in. See [Default values](#default-values) for how to write each kind of literal. Generated defaults are `uuid()` (a version 4 UUID, the same as `uuid(4)`), `uuid(7)`, `cuid(2)`, `ulid()`, and `nanoid()`, where `nanoid(21)` sets the length to any value from 2 to 255; Prisma ORM computes them when it writes the row, and the database will not fill them in for you, so a row written by raw SQL or another application gets no value. Prisma ORM 7's `cuid()` is rejected with a hint to use `cuid(2)`.
+- `@default(...)` sets a default. Database defaults are a literal, `@default(now())`, `@default(autoincrement())`, or a SQL expression written as a `sql` tagged literal, such as ``@default(sql`gen_random_uuid()`)``; the database fills them in. See [Default values](#default-values) for how to write each kind of literal. Generated defaults are `uuid()` (a version 4 UUID, the same as `uuid(4)`), `uuid(7)`, `cuid(2)`, `ulid()`, and `nanoid()`, and `nanoid(n)` sets the length, from 2 to 255. Prisma ORM computes them when it writes the row, and the database will not fill them in for you, so a row written by raw SQL or another application gets no value. Prisma ORM 7's `cuid()` is rejected with a hint to use `cuid(2)`.
 - `@map("column_name")` sets a field's column name in the database. `@@map("table_name")` sets the table or collection name when it differs from the model name. Without `@@map`, the table or collection has the model's name exactly as written, so `model UserProfile` is the table `"UserProfile"`.
 - `@@check(expression: "total >= 0", name: "order_total_positive")` adds a check constraint of your own to the table. See [Check constraints](#check-constraints).
 - `@@control(observed)` says how far Prisma ORM manages the table. See [Control policy](#control-policy).
@@ -152,7 +154,7 @@ model Post {
 }
 ```
 
-Prisma ORM sets the field to the current time on every create and update. `temporal` is built in, so you do not import it or declare it. On PostgreSQL the column is `timestamptz`, and you can still set the field yourself on a write. `temporal.createdAt()` sets the field once, when the row is created. Both take the time from your application's clock, not from the database, so the column has no database default, and a row you insert with raw SQL must supply the value. For a value the database generates, use `DateTime @default(now())` instead. `temporal.createdAtJsDate()` and `temporal.updatedAtJsDate()` do the same with a JavaScript `Date` in place of a `Temporal` value. The `Temporal` presets need a global `Temporal` for writes as well as reads, so load a polyfill such as `temporal-polyfill/global` when your runtime has none.
+Prisma ORM sets the field to the current time on every create and update. `temporal` is built in, so you do not import it or declare it. On PostgreSQL the column is `timestamptz`, and you can still set the field yourself on a write. `temporal.createdAt()` sets the field once, when the row is created. Both take the time from your application's clock, not from the database, so the column has no database default, and a row you insert with raw SQL must supply the value. For a value the database generates, use `DateTime @default(now())` instead. `temporal.createdAtJsDate()` and `temporal.updatedAtJsDate()` do the same with a JavaScript `Date` in place of a `Temporal` value. `temporal.createdAt()` and `temporal.updatedAt()` need a global `Temporal` for writes as well as reads, so load a polyfill such as `temporal-polyfill/full/global` when your runtime has none.
 
 How IDs map differs by database:
 
@@ -182,18 +184,21 @@ model Account {
   price     Decimal  @default(1.50)
   ratio     Float    @default(NaN)
   role      String   @default("member")
+  active    Boolean  @default(true)
+  startsOn  Date     @default("2024-01-01")
   createdAt DateTime @default(now())
   expiresAt DateTime @default(sql`(now() + '00:03:00'::interval)`)
 }
 ```
 
-- A JSON default is a `json` tagged literal, whose body is the JSON document itself. A JSON list on a column that holds one JSON value is also one `json` literal, as `tags` shows.
+- A JSON default is a `json` tagged literal, whose body is the JSON document itself. A JSON array is also one `json` literal, as `tags` shows.
 - A decimal default is a bare number, and it keeps every digit you write, trailing zeros included.
-- `NaN`, `Infinity`, and `-Infinity` are written without quotes.
-- A text default, or the value of an enum member, is a quoted string.
+- `NaN`, `Infinity`, and `-Infinity` are written without quotes, and so are `true` and `false`.
+- A text default is a quoted string, and so is a fixed date or time, as `startsOn` shows. On a column that reads as a `Temporal` value, such as `Date` or `DateTime`, `contract emit` checks the date with `Temporal`, so the Node.js that runs `contract emit` needs a global `Temporal`.
+- On a field typed with an `enum` block, the default is the member's name without quotes, as in `@default(Low)`. On a `pg.enum(...)` field, it is the value the member stores, in quotes, as in `@default("admin")`. [Enums](#enums) covers both.
 - Any other SQL expression is a `sql` tagged literal, and it goes into the column default exactly as written. Write the current time as `now()` and a sequence as `autoincrement()`, not as `` sql`now()` `` or `` sql`autoincrement()` ``, which are refused.
 
-Prisma ORM 7's `dbgenerated("...")` is not accepted, and `contract emit` reports `PSL_UNKNOWN_DEFAULT_FUNCTION` with the replacement. [`contract infer`](/cli/contract-infer) writes every default in these forms.
+Prisma ORM 7's `dbgenerated("...")` is not accepted, and `contract emit` reports `PSL_UNKNOWN_DEFAULT_FUNCTION`. Write the same SQL as a `sql` tagged literal instead, so `@default(dbgenerated("gen_random_uuid()"))` becomes ``@default(sql`gen_random_uuid()`)``. [`contract infer`](/cli/contract-infer) writes every default in these forms.
 
 ### Indexes
 
@@ -228,7 +233,7 @@ model Post {
 }
 ```
 
-`language:` sets the text-search configuration and defaults to `english`. Give the index and the query operations the same language, because PostgreSQL does not use the index for a query in another language. `where:` makes it a partial index, as on `@@index`. A `pg.enum(...)` column cannot have a full-text index. PostgreSQL only.
+`language:` sets the text-search configuration and defaults to `english`. A search sets its language with the `language` option of `fullTextMatches` and `fullTextRank`, as in `fullTextMatches(query, { language: "german" })`, and that option also defaults to `english`. Give the index and the search the same language, because PostgreSQL does not use the index for a search in another language. `where:` makes it a partial index, as on `@@index`. A field typed `pg.enum(...)`, a PostgreSQL enum type as [Enums](#enums) describes, cannot have a full-text index. PostgreSQL only.
 
 ### Check constraints
 
@@ -426,7 +431,7 @@ namespace audit {
 }
 ```
 
-Models outside any block are in `public`. In queries, the block name is the segment after `db.orm`, so this model is `db.orm.audit.AuditLog`. Two `namespace` blocks with the same name in one file are one namespace, so you can open a block again further down the file. A relation can point at a model that another extension pack owns in a different schema, written `<pack>:<schema>.<Model>`, for example `supabase:auth.AuthUser`; the [Supabase extension](/orm/extensions) documents that form.
+Models outside any block are in `public`. In queries, the block name is the segment after `db.orm`, so this model is `db.orm.audit.AuditLog`. Two `namespace` blocks with the same name in one file are one namespace, so you can open a block again further down the file. A relation can also point at a model that an [extension pack](#extension-types), an npm package you add to your config, declares in a different schema. Write that model as `<pack>:<schema>.<Model>`, for example `supabase:auth.AuthUser`; the [Supabase extension](/orm/extensions) documents that form.
 
 ## Row-level security
 
@@ -508,7 +513,7 @@ model Bug {
 }
 ```
 
-A field name is written bare, as `type` is in `@@discriminator(type)`, and a database name is quoted, as in `@@map("task")`. Rows whose `type` column holds `"bug"` are `Bug` records. A variant reuses its base model's fields, so a `Bug` has `id`, `title`, and `type` as well as `severity` and `stepsToRepro`. The base model can be declared before or after its variants. A variant does not declare an `@id` of its own: it takes the base model's primary key.
+Field and model names are written bare, as `type` and `Task` are, while table names and discriminator values are quoted, as `"task"` and `"bug"` are. Rows whose `type` column holds `"bug"` are `Bug` records. A variant reuses its base model's fields, so a `Bug` has `id`, `title`, and `type` as well as `severity` and `stepsToRepro`. The base model can be declared before or after its variants. A variant does not declare an `@id` of its own: it takes the base model's primary key.
 
 You query a variant through the base model: `db.orm.public.Task.variant('Bug')` returns the `Bug` rows only, and `public` here is the PostgreSQL schema. Writing a row of a variant starts with the same `variant('Bug')` call. See [`variant()`](/orm/reference/orm-client#variant).
 
diff --git a/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx b/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx
index b298ed4b45..9ec1a15577 100644
--- a/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx
@@ -95,7 +95,7 @@ An abridged `contract.json` for a `User` and `Post` schema:
 The sections, top to bottom:
 
 - **`schemaVersion`, `targetFamily`, `target`**: the contract format version, whether the database is SQL or MongoDB, and which database this contract targets.
-- **`roots`**: one entry per table that stores a model. The key is the name of that table, so for a model `User` mapped to a table `users` the key is `users`. The value names the model. The [ORM reference](/orm/reference) covers both ways of reaching it, `db.sql.public.User` by table name and `db.orm.public.User` by model name. The two names are the same here because the model sets no `@@map`.
+- **`roots`**: one entry per table that stores a model. The key is the name of that table, so for a model `User` mapped to a table `users` the key is `users`. The value names the model. You can query the model's data in two ways: `db.sql.public.User` uses the table name, and `db.orm.public.User` uses the model name. In this example both are `User`, because the model sets no `@@map`. The [ORM reference](/orm/reference) covers both.
 - **`domain` and `storage`**: your application's view, then the database's view. Each scalar field in `domain` records whether it is nullable and its `codecId`. `nativeType` is the column type in the database. `codecId` names how Prisma ORM reads and writes the value, the PostgreSQL type plus a version. `storage` holds the tables with their columns, keys, indexes, constraints, and enum values. `prisma db verify` compares it to the live database.
 - **`capabilities`**: which database features this contract can use. `npx prisma contract emit` collects them from the adapter for your database and from the packages listed in `extensions: [...]` in `prisma.config.ts`, the config file `prisma orm init` writes. The query APIs check them before building a query that needs one. See [supported database features](/orm/contract-authoring/capabilities) and [extension types](/orm/contract-authoring/psl-syntax#extension-types).
 
diff --git a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
index 56560f90db..66cb41cdc2 100644
--- a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
@@ -25,7 +25,7 @@ model Post {
 }
 ```
 
-`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema. Every `.prisma` contract file must start with this line. `contract emit` reads only files that start with it and skips any other file without a warning. When no file has the line, `contract emit` fails with `PSL_NO_OPTED_IN_SCHEMA_FILES`. The editor extension also looks for the line before it checks, completes, or formats the file. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
+`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema. Every `.prisma` contract file must start with this line. `contract emit` reads only files that start with it and skips any other file without a warning. When no file has the line, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`, and the error's finding is `PSL_NO_OPTED_IN_SCHEMA_FILES`. The editor extension also looks for the line before it checks, completes, or formats the file. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
 
 `npx prisma contract emit` turns this file into two files that the CLI and your application read: `contract.json` and `contract.d.ts`. Your queries are type-checked against the contract, migrations are planned as changes to it, and `npx prisma db verify` checks a live database against it.
 
@@ -64,7 +64,7 @@ export default definePrismaConfig({
 
 To start a new project, run `npm create prisma@latest -- my-app`. To add Prisma ORM 8 to a project that has no Prisma ORM at all, run `npx prisma orm init`. If you already have a Prisma ORM 7 `schema.prisma`, follow the [PostgreSQL upgrade guide](/guides/upgrade-prisma-orm/postgresql) instead, and [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7) lists what changed. Both `npm create prisma@latest` and `npx prisma orm init` write `prisma.config.ts`, the contract file, and `src/prisma/db.ts`, and install the database package.
 
-The contract file is either a PSL file (`contract.prisma`) or a TypeScript file (`contract.ts`). The file extension selects the authoring mode, so to author in TypeScript you point `contract` at `./src/prisma/contract.ts`. A PSL contract can also span several files, when `contract` is a glob such as `./src/prisma/**/*.prisma`; see [Split the schema across several files](/cli/configuration#split-the-schema-across-several-files). Both modes describe the same things: models with fields and relations, the tables and columns they map to, named types, enums, and any types that [extension packages](/orm/contract-authoring/psl-syntax#extension-types) add. Extension packages are npm packages that add field types and database features, such as pgvector, a PostgreSQL extension for vector columns.
+The contract file is either a PSL file (`contract.prisma`) or a TypeScript file (`contract.ts`). The file extension selects the authoring mode, so to author in TypeScript you point `contract` at `./src/prisma/contract.ts`. You can also split a PSL contract across several files by setting `contract` to a glob such as `./src/prisma/**/*.prisma`, as [Configuration](/cli/configuration#split-the-schema-across-several-files) shows. Both modes describe the same things: models with fields and relations, the tables and columns they map to, named types, enums, and any types that [extension packages](/orm/contract-authoring/psl-syntax#extension-types) add. Extension packages are npm packages that add field types and database features, such as pgvector, a PostgreSQL extension for vector columns.
 
 After every change to the contract, run these three commands:
 
@@ -84,7 +84,7 @@ npx prisma db migrate
 
 Define models with the **[TypeScript builder](/orm/contract-authoring/typescript-schema-builder)** instead when you want to build them with code: reach for it when model definitions must be composed, generated, or shared as ordinary TypeScript modules. That page shows what a `contract.ts` file looks like.
 
-Both modes produce the same contract, so migrations, database checks, and `db` behave the same no matter which mode you write. A project has exactly one contract source, so do not keep both a `contract.prisma` and a `contract.ts`: the config names one source and Prisma ORM reads only that one, so edits to the other file do nothing. To switch modes, change the path in `contract` and delete the old file.
+Both modes produce the same contract, so migrations, database checks, and `db` behave the same no matter which mode you write. The config names either PSL files or one TypeScript file, never both, and Prisma ORM reads only the files it names. So do not keep both a `contract.prisma` and a `contract.ts`, because edits to the one the config does not name do nothing. To switch modes, change the path in `contract` and delete the old file.
 
 ## What the contract contains
 
diff --git a/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx b/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
index e4e6ebe9fc..fcf719e008 100644
--- a/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
@@ -205,14 +205,14 @@ For a key the database generates, chain `.default(...)` and `.id()` on a field.
 
 `field.temporal.createdAt()` sets the column to the current time when the row is created, and `field.temporal.updatedAt()` sets it on every create and every update. Prisma ORM sets both in the client, from your application's clock, so the column has no database default. If you insert a row with raw SQL, you must supply the value yourself. For a time the database sets instead, use `field.dateTime().default(now())`.
 
-`field.temporal.timestamptzJsDate()` is a `timestamptz` column that your code reads and writes as a JavaScript `Date`, so it needs no `Temporal` polyfill. For creation and update times as a `Date`, use `field.temporal.createdAtJsDate()` and `field.temporal.updatedAtJsDate()`.
+`field.dateTime()`, `field.temporal.createdAt()`, and `field.temporal.updatedAt()` give your code a `Temporal.Instant`, so your app needs a global `Temporal` to read and write them; [Scalar fields](/orm/data-modeling#scalar-fields) says how to check for it and which polyfill to load when it is missing. To get a JavaScript `Date` instead, and need no `Temporal`, use `field.temporal.timestamptzJsDate()` for a `timestamptz` column, and `field.temporal.createdAtJsDate()` and `field.temporal.updatedAtJsDate()` for creation and update times.
 
 `field.namedType(x)` takes an enum or a type from an extension pack.
 
 Every field builder supports chained modifiers:
 
 - `.optional()` makes the field nullable.
-- `.default(value)` sets a literal default. It also takes a default the database computes: `.default(now())`, `.default(autoincrement())`, or any other SQL expression as a `sql` template, such as ``.default(sql`gen_random_uuid()`)``. Import `now`, `autoincrement`, and `sql` from `@prisma/orm-postgres/contract-builder`. `` sql`now()` `` and `` sql`autoincrement()` `` are refused; use the named helpers. `.defaultSql(expression)` still works but is deprecated, and it will be removed in `8.0.0`.
+- `.default(value)` sets a literal default. Pass the value in the form your code reads from that column, so a decimal default is a string, as in `.default("1.50")`, and a JSON default is the object or array itself, as in `.default({ plan: "free" })`. It also takes a default the database computes: `.default(now())`, `.default(autoincrement())`, or any other SQL expression as a `sql` template, such as ``.default(sql`gen_random_uuid()`)``. Import `now`, `autoincrement`, and `sql` from `@prisma/orm-postgres/contract-builder`. `` sql`now()` `` and `` sql`autoincrement()` `` are refused; use the named helpers. `.defaultSql(expression)` still works but is deprecated, and it will be removed in the stable `8.0.0` release.
 - `.unique()` adds a unique constraint. `.id()` marks the primary key, for a key that is not generated, such as an integer you set yourself.
 - `.column("column_name")` sets the column name in the database when it differs from the field name.
 - `.many()` makes the field a list, stored as a PostgreSQL array column such as `text[]`. A list column gets a check constraint that rejects `NULL` elements.
@@ -312,7 +312,7 @@ Post.sql(({ cols }) => ({
 }));
 ```
 
-Give the index and the search operations the same `language`, which defaults to `english`; otherwise PostgreSQL does not use the index.
+`language` defaults to `english` on both the index and the search operations, and PostgreSQL uses the index only when the two match, so change both or neither.
 
 Two more keys go in the same object, in either the object form or the callback form: `checks`, a list of check constraints you write yourself, built with `check` from the package, and `control`, the model's [control policy](#control-policy):
 
diff --git a/apps/docs/content/docs/orm/data-modeling/index.mdx b/apps/docs/content/docs/orm/data-modeling/index.mdx
index ba36a8d8e8..1f44f4007b 100644
--- a/apps/docs/content/docs/orm/data-modeling/index.mdx
+++ b/apps/docs/content/docs/orm/data-modeling/index.mdx
@@ -145,7 +145,7 @@ A scalar field holds a single value. The common types:
 
 The PostgreSQL names in the table are the column types Prisma ORM creates. `ObjectId` is the only MongoDB-only type.
 
-Three types arrive in your code as something other than a plain JavaScript value. A `Decimal` reaches you as a string, so nothing is rounded through a JavaScript number, and a `Bytes` value reaches you as a `Uint8Array`. A `DateTime` reaches you as a `Temporal.Instant`, the standard JavaScript type for a point in time. `Temporal` is built into Node.js 26.8.2 and later, but Homebrew's build of Node.js 26 leaves it out, so check with `node -p "typeof Temporal"`. If that prints `undefined`, install the `temporal-polyfill` package and add `import "temporal-polyfill/full/global"` to your app's entry file, before any query runs. To work with a JavaScript `Date` instead, and need no polyfill, type the field `TimestamptzJsDate` on PostgreSQL. A `Date` keeps only milliseconds.
+A `Decimal` reaches your code as a string, so nothing is rounded through a JavaScript number, and a `Bytes` value reaches you as a `Uint8Array`. A `DateTime` is a JavaScript `Date` on MongoDB, but on PostgreSQL it reaches you as a `Temporal.Instant`, the standard JavaScript type for a point in time. `Temporal` is built into Node.js 26.8.2 and later, but Homebrew's build of Node.js 26 leaves it out, so check with `node -p "typeof Temporal"`. If that prints `undefined`, install the `temporal-polyfill` package and add `import "temporal-polyfill/full/global"` to your app's entry file, before any query runs. To work with a JavaScript `Date` on PostgreSQL instead, and need no polyfill, type the field `TimestamptzJsDate`, but a `Date` drops the microseconds PostgreSQL stores.
 
 `Json` and `Jsonb` are two separate types, and they differ in how you can filter on them. On a `Jsonb` field, `.where()` compares the whole value, so you can ask whether the column equals a given document but not whether a key inside it matches. A `Json` field cannot be compared in `.where()` at all, so use `Jsonb` unless you specifically need PostgreSQL's plain `json` column. When you need a path query into the document, reach for [raw SQL](/orm/reference/raw-queries). [Extensions](/orm/extensions) add more types, such as vectors or geometry.
 
diff --git a/apps/docs/content/docs/orm/extensions/using-extensions.mdx b/apps/docs/content/docs/orm/extensions/using-extensions.mdx
index e59110513e..128e7ee523 100644
--- a/apps/docs/content/docs/orm/extensions/using-extensions.mdx
+++ b/apps/docs/content/docs/orm/extensions/using-extensions.mdx
@@ -69,6 +69,8 @@ Now that pgvector is in `prisma.config.ts`, `npx prisma contract emit` accepts `
 
 The `pgvector` in `pgvector.Vector(1536)` is the name the extension registers its types under, and its page in the extension directory lists them. PostGIS, for example, gives you `postgis.Geometry(4326)`.
 
+The first line of the file, `// use prisma-8`, is required. `npx prisma contract emit` reads only `.prisma` files whose first line is `// use prisma-8` and skips any other file without a warning, so keep that line at the top when you add the `types` block.
+
 ```prisma title="src/prisma/contract.prisma"
 // use prisma-8
 
@@ -89,7 +91,7 @@ Getting the new column from your contract into your database takes these command
 
 1. `npx prisma contract emit`, so that `contract.json` and `contract.d.ts` pick up the new column. Run it again after every later change to `contract.prisma`.
 2. `npx prisma migration plan`, which writes the extension's own migration into `migrations/`, so commit it along with your other migrations. Skip this and the next command stops with an error whose `code` is `MIGRATION.CONTRACT_SPACE_LAYOUT_VIOLATION`.
-3. `npx prisma db init` on a new database, or `npx prisma db update` on one that already has tables, which [Applying a migration](/orm/migrations/applying-a-migration) covers. This runs the extension's migration and creates the `Post` table.
+3. `npx prisma db init` on a new database, or `npx prisma db update` on one that already has tables, which [Applying a migration](/orm/migrations/applying-a-migration) covers. This runs the extension's migration and makes the database match your contract: it creates the `Post` table, or adds the `embedding` column when the `Post` table already exists.
 
 The extension's migration is the `CREATE EXTENSION IF NOT EXISTS vector` statement, so you never write that statement yourself, but the PostgreSQL server has to have pgvector available for it to succeed. Both databases the quickstart offers have it: the local Prisma Postgres database that Composer starts, and a Prisma Postgres database from `npx create-db@latest`. A stock PostgreSQL image may not, and then the migration fails on that statement, so install pgvector on the server first, following [pgvector's own instructions](https://github.com/pgvector/pgvector).
 
@@ -206,7 +208,9 @@ export const db = await supabase<Contract>({
 
 `await db.asUser(jwt)` takes the user's Supabase JWT and gives you a client that runs as that user. `db.asAnon()` gives you one that runs as the anonymous role, and `db.asServiceRole()` one that bypasses row-level security. `db` itself has no `orm` or `sql`: those live on the three role-bound clients. The [runnable example](https://github.com/prisma/orm/tree/main/examples/supabase) shows the whole setup in one project.
 
-The extension's contract describes Supabase's `auth` and `storage` tables as they are in a reference Supabase build, supabase/postgres 17.6.1.106, check constraints included. If your build differs, `db verify` reports the difference. When an update to `@prisma/orm-extension-supabase` changes that contract, run `npx prisma db sign` again against every database signed with the earlier version. If you also re-emit your own contract, do that first.
+The extension's contract describes Supabase's `auth` and `storage` tables as they are in one reference Supabase build, supabase/postgres 17.6.1.106, check constraints included. Run [`npx prisma db verify`](/cli/db-verify) to compare your database with it: if your Supabase build has a different set of check constraints, `db verify` lists the ones it cannot find. You cannot fix that with a migration, because Prisma ORM never changes Supabase's own tables. Report the difference to Prisma instead, so the reference build can be updated.
+
+[`npx prisma db sign`](/cli/db-sign) checks that a database matches your contract and then records in the database which contract it matches. When an update to `@prisma/orm-extension-supabase` changes the extension's contract, that record no longer matches, so run `npx prisma db sign` again against every database you signed with the earlier version. If you are also re-emitting your own contract with `npx prisma contract emit`, run that before `db sign`.
 
 :::
 
diff --git a/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx b/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx
index 1d4a6a81a9..fc5e7da88e 100644
--- a/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx
@@ -74,7 +74,7 @@ A SQL builder query takes two steps: first you build it, then you run it. You de
 
 ### Build a query and run it
 
-Start from a table with `db.sql.public.<table>`. `db.sql` is the SQL query builder, keyed by table name. A table's name is the model's `@@map` value, or the model name exactly as written when the model has no `@@map`, and column names are the field names unless a field sets `@map`. `public` is the PostgreSQL schema your tables are in, unless the model sits in a `namespace billing { ... }` block in your contract, in which case the path is `db.sql.billing.<table>`.
+Start from a table with `db.sql.public.<table>`. `db.sql` is the SQL query builder, keyed by table name. A table's name is the model's `@@map` value, or the model name exactly as written when the model has no `@@map`, and column names are the field names unless a field sets `@map`. `public` is the PostgreSQL schema your tables are in. If you put a model inside a `namespace` block in your contract, the block's name is the PostgreSQL schema instead, so for a model inside `namespace billing { ... }` you write `billing` in place of `public`: `db.sql.billing.<table>`.
 
 `db.runtime()` is the database connection; call it whenever you run a query. `query()` always resolves to an array of rows, even when the query matches one row.
 
diff --git a/apps/docs/content/docs/orm/fundamentals/transactions.mdx b/apps/docs/content/docs/orm/fundamentals/transactions.mdx
index f7cecefa8f..0a8dbf103d 100644
--- a/apps/docs/content/docs/orm/fundamentals/transactions.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/transactions.mdx
@@ -119,8 +119,8 @@ await db.transaction(async (tx) => {
 });
 ```
 
-Two things differ from `tx.orm`. Under `tx.sql.public` the property name is the table name, not the model name. The table name is the model name exactly as written, so the model `Post` has the table `Post` and it is `tx.sql.public.Post`, unless the model sets `@@map`: a model with `@@map("post")` is `tx.sql.public.post`.
-The second difference is that you chain clauses and then call `.build()` to finish the query: `.build()` returns the query without running it, and `tx.execute(...)` runs it and returns `{ affectedRows }`, the number of rows it changed. The `.where(...)` callback receives two arguments: `f` holds the columns, and `fns` holds the operators (`lt` is less-than). [Advanced queries](/orm/fundamentals/advanced-queries#build-a-query-and-run-it) covers both.
+Under `tx.sql.public`, unlike under `tx.orm.public`, the property name is the table name: the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. So the model `Post` is `tx.sql.public.Post`, and a model with `@@map("post")` is `tx.sql.public.post`.
+The other difference from `tx.orm` is that you chain clauses and then call `.build()` to finish the query: `.build()` returns the query without running it, and `tx.execute(...)` runs it and returns `{ affectedRows }`, the number of rows it changed. The `.where(...)` callback receives two arguments: `f` holds the columns, and `fns` holds the operators (`lt` is less-than). [Advanced queries](/orm/fundamentals/advanced-queries#build-a-query-and-run-it) covers both.
 
 ## Transactions on MongoDB
 
@@ -172,7 +172,17 @@ try {
 const jane = await db.orm.users.where({ email: "jane@prisma.io" }).first();
 ```
 
-On MongoDB there is no schema segment in the path, and the property name is the collection name. The collection name is the model name exactly as written, so a model `User` is `db.orm.User`, unless the model sets `@@map`. `db.orm.users` above is the collection name; the model is `User` with `@@map("users")`.
+On MongoDB there is no schema segment in the path, and the property name is the collection name: the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. The example above assumes a `User` model mapped to the `users` collection, like the one below, so Prisma ORM reads it as `db.orm.users` and the driver code as `database.collection("users")`. Without the `@@map` line it would be `db.orm.User`.
+
+```prisma
+model User {
+  id    ObjectId @id @map("_id")
+  email String   @unique
+  name  String?
+  @@map("users")
+}
+```
+
 Writes you make through the driver skip the type-checking that Prisma ORM queries get, so put each driver transaction in its own small function, and write everything around it as Prisma ORM queries.
 
 ## Coming from Prisma ORM 7
diff --git a/apps/docs/content/docs/orm/fundamentals/writing-data.mdx b/apps/docs/content/docs/orm/fundamentals/writing-data.mdx
index 64cecfbdce..7b52bb2292 100644
--- a/apps/docs/content/docs/orm/fundamentals/writing-data.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/writing-data.mdx
@@ -12,7 +12,7 @@ Every example imports `db`. In a new project run `npm create prisma@latest -- my
 
 This page uses `db.orm`, which holds your models. The rest of `db` is `db.sql` for the SQL query builder, `db.raw.sql` for raw SQL, and `db.transaction` for running several writes together.
 
-On PostgreSQL the path to a model is `db.orm.<schema>.<ModelName>`, so the `User` model is `db.orm.public.User`. `public` is the PostgreSQL schema; you type it. It is `public` unless the model sits in a `namespace` block (shown under [Example schema](#example-schema)). On MongoDB there is no schema segment, and the path is `db.orm.<collectionName>`, so the model below is `db.orm.users`. The collection name is the model's `@@map(...)`, or the model name exactly as written.
+On PostgreSQL the path to a model is `db.orm.<schema>.<ModelName>`, so the `User` model is `db.orm.public.User`. `public` is the PostgreSQL schema that holds the model's table, and the path always includes the schema name. The schema is `public` unless you put the model inside a `namespace` block, as [Example schema](#example-schema) shows. On MongoDB there is no schema segment, and the path is `db.orm.<collectionName>`, so the model below is `db.orm.users`. The collection name is the model's `@@map(...)`, or the model name exactly as written.
 
 ## Example schema
 
@@ -296,7 +296,7 @@ const deletedCount = await db.orm.public.Post.where((p) => p.title.ilike("draft%
 
 The `AndCount` methods return a plain number, so if three posts match, `updatedCount` is `3`, not an object.
 
-To insert many records and skip the ones that would break a unique constraint, pass `{ onConflict: "skip" }` as the second argument to `createAll` or `createAndCount`, and optionally `conflictOn: ["email"]` to name the constraint. This replaces Prisma ORM 7's `skipDuplicates`, and it works on PostgreSQL and SQLite. `createAll` returns only the records the database wrote, and `createAndCount` counts only those. [`createAll()`](/orm/reference/orm-client#createall) in the reference covers the details.
+To insert many records and skip the ones that would break a unique constraint, pass `{ onConflict: "skip" }` as the second argument to `createAll` or `createAndCount`. That skips a record that breaks any unique constraint on the table. To skip only the records that clash on one constraint, add `conflictOn` to the same object with the names of that constraint's fields, as in `createAll(users, { onConflict: "skip", conflictOn: ["email"] })`. Here `conflictOn` takes field names, while in [`.upsert(...)`](#upsert-a-record) it takes the fields and their values. This replaces Prisma ORM 7's `skipDuplicates`, and it works on PostgreSQL and SQLite. `createAll` returns only the records the database wrote, and `createAndCount` counts only those. [`createAll()`](/orm/reference/orm-client#createall) in the reference covers the details.
 
 `.where((p) => p.title.ilike("draft%"))` is the callback form of a filter, for conditions an object cannot express. Its argument gives you one entry per field, and each field carries the comparisons you can apply to it. [Reading data](/orm/fundamentals/reading-data) covers the filters you can write.
 
diff --git a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
index 34eb276279..62cd1ab9ca 100644
--- a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
+++ b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
@@ -51,7 +51,7 @@ The `name` is the label Prisma ORM uses when it talks about your middleware, so
 
 If a call gives you back a count instead of rows, `afterQuery` is not called for it and `afterExecute` is called instead. On the ORM API the calls that return a count are `createAndCount`, `updateAndCount`, and `deleteAndCount`. Every other call returns rows and reaches `afterQuery`, including `create`, `update`, `delete`, `updateAll`, and `deleteAll`.
 
-The SQL query builder is the other way to write a query on the same client, `db.sql.public.User...` in place of `db.orm.public.User...`. With it you build a query and run it in two steps, and the step you run it with decides which hook you get. Calling `.build()` gives you the plan, and `db.runtime()` is the method on your client that runs one. `db.runtime().query(plan)` returns rows and reaches `afterQuery`, while `db.runtime().execute(plan)` reports how many rows the statement changed and reaches `afterExecute`.
+The SQL query builder is the other way to write a query on the same client, `db.sql.public.User...` in place of `db.orm.public.User...`. With it you build a query and run it in two steps: `.build()` gives you the query as a plain object, the plan, and a method on `db.runtime()` runs it. Which of the two methods you call decides which hook you get. `db.runtime().query(plan)` returns rows and reaches `afterQuery`, while `db.runtime().execute(plan)` reports how many rows the statement changed and reaches `afterExecute`.
 
 To have the logger cover the counting calls as well, add a second hook to the object `queryLogger()` returns in `src/prisma/query-logger.ts`, next to `afterQuery`:
 
@@ -246,6 +246,8 @@ export function scopeUserSelects(predicate: BinaryExpr): SqlMiddleware {
 
 The `kind` check on `from` keeps the middleware to plain tables: a `SELECT` that reads from a subquery has a `from` whose `kind` is `'derived-table-source'`, and one that reads from a function has `'function-source'`. The name it checks, `'User'`, is the table name in your database rather than the model name in your contract, because by this point the query is expressed in tables and columns. The two are the same unless the model sets `@@map`. `draft.ast.withWhere(where)` gives back a new tree with that `WHERE` and leaves the original alone.
 
+These checks read only the table in the query's own `FROM` clause, so `User` rows that a query reaches any other way do not get the condition. When you load related users with `.include(...)` from another model, such as the author of each post, the ORM API reads them inside that other model's query, whose `FROM` is the other table. A SQL query builder query that joins `User` onto another table is not filtered either, for the same reason.
+
 The condition itself is an object you build from the same classes, and you pass it in when you register the middleware. Put values through `ParamRef.of` rather than `LiteralExpr.of`, because a `ParamRef` becomes a bound parameter such as `$1` while a literal is pasted into the SQL text itself, so a value that came from one of your users could inject SQL of its own. A `ParamRef` you build by hand has to name the PostgreSQL type of the value with `codec: { codecId: ... }`, and the ids start with `pg/` and end with `@1`, so the `text` column `name` takes `pg/text@1`. Leave that out and the query fails with an error whose `code` is `RUNTIME.PARAM_REF_MISSING_CODEC`.
 
 ```ts title="src/prisma/db.ts"
@@ -267,11 +269,23 @@ export const db = postgres<Contract>({
 });
 ```
 
-Every `SELECT` on `User` now runs with `WHERE "User"."name" = $1` added, and a query that already had a `WHERE` clause keeps it, joined to yours with `AND`. Swap `name` for whatever column holds your tenant to get the tenant filter.
+Every `SELECT` on `User` now runs with `WHERE "User"."name" = $1` added, and a query that already had a `WHERE` clause keeps it, joined to yours with `AND`. The condition is built once, when you create the client, so every query on this client is filtered to the same value. Swap `name` for the column that holds your tenant and `'Mia'` for a tenant ID, and every `SELECT` on `User` through this client returns only that one tenant's rows.
 
 Copy each import as it is written, including the one that says `type` and the one that does not.
 
-A `uuid` column takes `pg/uuid@1`, and the other common ids are `pg/int4@1`, `pg/int8@1`, `pg/float8@1`, `pg/bool@1`, and `pg/timestamptz-temporal@1` for a `timestamptz` column. For a column whose type is not in that list, read the id off your own client: `db.sql.public.User.columns.name.codecId` is the id for the `name` column of the `User` table, so print it from any script that imports `db`. [`fns.raw` and `.returns()`](/orm/reference/sql-query-builder#fnsraw-and-returns) lists the ids in one place.
+The id depends on the field's type in your contract:
+
+| Type in your contract | Id |
+| --- | --- |
+| `String` | `pg/text@1` |
+| `Int` | `pg/int4@1` |
+| `BigInt` | `pg/int8@1` |
+| `Float` | `pg/float8@1` |
+| `Boolean` | `pg/bool@1` |
+| `DateTime` | `pg/timestamptz-temporal@1` |
+| `Uuid` | `pg/uuid@1` |
+
+For a field whose type is not in the table, read the id off your own client: `db.sql.public.User.columns.name.codecId` is the id for the `name` column of the `User` table, so print it from any script that imports `db`. [`fns.raw` and `.returns()`](/orm/reference/sql-query-builder#fnsraw-and-returns) lists the ids in one place.
 
 `BinaryExpr` has one method per comparison (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `in`, `notIn`), and `AndExpr.of` and `OrExpr.of` combine conditions. They all come from `@prisma/orm-postgres/relational-core/ast`, so your editor lists them once you import from there.
 
@@ -297,8 +311,11 @@ export function userFixture(): SqlMiddleware {
     name: 'user-fixture',
     familyId: 'sql',
 
-    async interceptQuery(plan) {
-      if (!plan.sql.includes('FROM "public"."User"')) return undefined;
+    async interceptQuery(plan, ctx) {
+      if (ctx.scope !== 'runtime') return undefined;
+      if (plan.ast.kind !== 'select') return undefined;
+      if (plan.ast.from?.kind !== 'table-source') return undefined;
+      if (plan.ast.from.name !== 'User') return undefined;
       return { rows: [{ id: 1, email: 'mia@prisma.io' }] };
     },
   };
@@ -307,7 +324,9 @@ export function userFixture(): SqlMiddleware {
 
 Prisma ORM decodes the rows you return the same way it decodes rows that came from the database, so your caller gets the types the contract gives those columns, even though you handed back plain driver values.
 
-Matching on `plan.sql` is the quick way to pick out one table, and it is enough for a fixture in a test. The reliable way is to read the table name out of the tree, which is `plan.ast.from.name` on a `SELECT` and `plan.ast.table.name` on an `UPDATE` or a `DELETE`. A hook cannot tell which model or which ORM call a query came from, so the table name in the tree is the only thing you have to match on.
+The last three checks answer only a `SELECT` that reads the `User` table directly, in the same way the `beforeCompile` example picks its queries. Matching on the SQL text instead, such as `plan.sql.includes('FROM "public"."User"')`, also catches `DELETE FROM "public"."User"`, so an ORM `.delete()` would get a made-up row back and delete nothing. On an `UPDATE` or a `DELETE` the table name is at `plan.ast.table.name`. A hook cannot tell which model or which ORM call a query came from, so the table name in the tree is the only thing you have to match on.
+
+The first check, on `ctx.scope`, leaves queries inside a transaction to the database, as the cache does. An ORM `.update()` or `.delete()` first reads the row it is about to change, inside a transaction, and if the fixture answered that read, the write would go to the row whose `id` is `1` rather than the row you asked for. [The context object](#the-context-object) covers `ctx.scope`.
 
 Return `undefined` and the query carries on to the database as usual. When several middleware implement `interceptQuery`, the first one in the array that returns rows answers the query and the rest are not called at all. `afterQuery` still runs either way, with `result.source` set to `'middleware'`, so your logging can tell which queries were answered without a trip to the database. For a call that returns a count, `interceptExecute` does the same job and returns `{ stats }`, which only ever holds `affectedRows`, as in `{ stats: { affectedRows: 0 } }`. The [cache middleware](/orm/middleware/built-in-cache) is the implementation to copy from.
 
diff --git a/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx b/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx
index e07f6926a4..f6fc218cf3 100644
--- a/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx
+++ b/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx
@@ -55,7 +55,7 @@ The built-in middleware is imported from `@prisma/orm-postgres/family-runtime`,
 
 The example sets `maxRows`, `defaultTableRows`, and `maxLatencyMs` to the values they already take by default, so that you can see where each one goes, and you can leave all three out. Set `maxRows` and `maxLatencyMs` to the largest number of rows and the longest time any single query in your app should ever need, because they are there to catch mistakes rather than to tune anything.
 
-The two numbers in `tableRows` are placeholders for how many rows your own tables really hold, so a `Post` table with two million rows in it is written `tableRows: { Post: 2_000_000 }`. A `count` from the database is enough to get each number, such as `select count(*) from "public"."User";` for the `User` table, and you can leave `tableRows` out altogether, in which case every table is assumed to hold `defaultTableRows` rows. Each key is the table name as it is in the database, which is the model name exactly as written, so the model `User` is keyed `User` and not `public.User`. If you renamed a table with `@@map` in your contract, use the name you mapped it to. If you misspell a table name, `budgets` silently uses `defaultTableRows` for that table and never warns you.
+The two numbers in `tableRows` are placeholders for how many rows your own tables really hold, so a `Post` table with two million rows in it is written `tableRows: { Post: 2_000_000 }`. A `count` from the database is enough to get each number, such as `select count(*) from "public"."User";` for the `User` table, and you can leave `tableRows` out altogether, in which case every table is assumed to hold `defaultTableRows` rows. Each key is the table name as it is in the database: the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. So the model `User` is keyed `User`, not `public.User`. If you misspell a table name, `budgets` silently uses `defaultTableRows` for that table and never warns you.
 
 Passing `budgets` to a MongoDB client throws an error whose `code` is `RUNTIME.MIDDLEWARE_FAMILY_MISMATCH` the first time that client is used, before any query of yours runs, and there is no MongoDB version of `budgets` to use instead.
 
@@ -148,7 +148,9 @@ Import that `db` in your export script and nowhere else, so the rest of your app
 
 The check that runs before your query never asks the database how big your tables are. It only knows the numbers you gave it in `tableRows` and `defaultTableRows`, so when your real tables are much larger than those numbers, a query can get past that first check and then fail part way through reading rows, once the rows the database returns pass `maxRows`.
 
-Say `maxRows` is `10_000` and you listed `User` at 5,000 rows, but the table really holds 5 million. A query with `.limit(50_000)` on it is estimated at 5,000 rows, because `budgets` takes the smaller of your limit and the size you gave for the table, so it passes the first check. The database then starts sending 50,000 rows and the count check throws at row 10,001, part way through your read. A query that used to work failing with `source: 'observed'` is your sign to put a fresh count into `tableRows`.
+Say `maxRows` is `10_000` and you listed `User` at 5,000 rows, but the table really holds 5 million. A query with `.limit(50_000)` on it is estimated at 5,000 rows, because `budgets` takes the smaller of your limit and the size you gave for the table, so it passes the first check. The database then starts sending 50,000 rows and the count check throws at row 10,001, part way through your read.
+
+When a query that used to work starts failing with `source: 'observed'`, the table has grown past the number you gave for it in `tableRows`. Put a fresh count there, and the check before the query then stops that query with `source: 'ast'` before the database does any work, rather than part way through the read. The query is still over budget either way, because its limit is larger than `maxRows`. To make it run, lower its `.limit(...)` to `maxRows` or less and read the rest a page at a time, or raise `maxRows`.
 
 :::
 
diff --git a/apps/docs/content/docs/orm/middleware/built-in-lints.mdx b/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
index 922c8aded9..0c5f8433f8 100644
--- a/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
+++ b/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
@@ -55,12 +55,13 @@ The rules are named after the SQL they are about, and you write your queries in
 | `.all()` with no `.limit(...)` before it | `LINT.NO_LIMIT` |
 | `.first(...)` | none, because it adds `LIMIT 1` for you |
 | a query where you never called `.select(...)` | `LINT.SELECT_STAR` |
-| `deleteAll()` or `updateAll()` | none, because TypeScript makes you write `.where(...)` first |
+| `deleteAll()` or `updateAll()` after a `.where(...)` with a condition in it | none |
+| `deleteAll()` or `updateAll()` after `.where({})` | `LINT.DELETE_WITHOUT_WHERE` or `LINT.UPDATE_WITHOUT_WHERE` |
 | the query builder's `delete()` or `update()` with no `where()` | `LINT.DELETE_WITHOUT_WHERE` or `LINT.UPDATE_WITHOUT_WHERE` |
 
 So `await db.orm.public.User.limit(50).all()` sets off `LINT.SELECT_STAR`, while `await db.orm.public.User.select('id', 'email').limit(50).all()` does not. In `db.orm.public.User`, `public` is the PostgreSQL schema and `User` is your model name. The SQL query builder reaches the same table by its name in the database, as `db.sql.public.User`. The model and the table have the same name here because the model sets no `@@map`.
 
-This is the record `lints` builds for a `warn` finding: the code of the rule, a message, and the table the query touched.
+For a `warn` finding, `lints` builds the record below, with the code of the rule, a message, and the table the query touched, and passes it to the client's logger. The `postgres(...)` client has no logger you can set yet, as the note above says, so today the record is thrown away and you cannot see it anywhere.
 
 ```text title="Lint warning"
 warn {
@@ -157,7 +158,7 @@ Because these are searches through the text rather than checks on the structure
 
 :::warning
 
-A severity you set in `severities` applies to a finding by its code wherever that finding came from, so it changes the raw defaults as well as the four rules. If you set `selectStar: 'warn'` to quiet the ORM-API rule, raw SQL's `select *` drops from `error` to `warn` along with it, and `select * from "User"` starts running instead of being blocked. To keep the ORM-API rule at `error` and still run a raw `select *`, give the code that runs it a `db` client of its own, in the way [Common gotchas](#common-gotchas) does for a backfill script.
+A severity you set in `severities` applies to a finding by its code wherever that finding came from, so it changes the raw defaults as well as the four rules. `selectStar` is `warn` by default for the ORM API and the SQL query builder, but `error` for raw SQL. So setting `selectStar: 'warn'` changes nothing for the ORM API, which is already at `warn`: its only effect is that raw SQL's `select *` drops from `error` to `warn`, and `select * from "User"` starts running instead of being blocked. Setting `selectStar: 'error'`, as under [Configure severities](#configure-severities), keeps a raw `select *` blocked. No setting makes the ORM-API rule `error` and lets a raw `select *` run, so if you need both, give the code that runs the raw `select *` a `db` client of its own, in the way [Common gotchas](#common-gotchas) does for a backfill script.
 
 :::
 
@@ -175,7 +176,15 @@ Sometimes you do mean to change every row, in a backfill script for example. `LI
 
 :::
 
-The first way is to write a `WHERE` clause that is true for every row, which states the intent in the query itself. In a query builder callback the first argument, `f`, has one property for each column, and the second, `fns`, holds the comparison helpers. Comparing a column to `null` gives you a null check rather than a comparison, so `fns.ne(f.id, null)` gives `id IS NOT NULL` and `fns.eq(f.id, null)` gives `id IS NULL`. On a table whose primary key is `id`, `IS NOT NULL` is true for every row:
+The first way is to write a `WHERE` clause that is true for every row, which states the intent in the query itself. On a table whose primary key is `id`, `id IS NOT NULL` is true for every row, and in the ORM API you write it with `isNotNull()`:
+
+```ts
+await db.orm.public.User.where((u) => u.id.isNotNull()).deleteAndCount();
+```
+
+An empty filter does not work for this. `.where({})` adds no condition, so `db.orm.public.User.where({}).deleteAll()` sends a `DELETE` with no `WHERE`, and `lints` blocks it with `LINT.DELETE_WITHOUT_WHERE`.
+
+With the SQL query builder, the callback's first argument, `f`, has one property for each column, and the second, `fns`, holds the comparison helpers. Comparing a column to `null` gives you a null check rather than a comparison, so `fns.ne(f.id, null)` gives `id IS NOT NULL` and `fns.eq(f.id, null)` gives `id IS NULL`:
 
 ```ts
 const plan = db.sql.public.User
@@ -185,7 +194,7 @@ const plan = db.sql.public.User
 await db.runtime().execute(plan);
 ```
 
-That delete passes the rule and runs, because the query has a `WHERE` clause and that is all `LINT.DELETE_WITHOUT_WHERE` looks for, so you can leave `lints` on its defaults in the script that runs it. An `UPDATE` takes the same shape, as in `db.sql.public.User.update({ name: 'x' }).where((f, fns) => fns.ne(f.id, null)).build()`.
+Both deletes pass the rule and run, because each query has a `WHERE` clause and that is all `LINT.DELETE_WITHOUT_WHERE` looks for, so you can leave `lints` on its defaults in the script that runs them. An `UPDATE` takes the same shape, as in `db.orm.public.User.where((u) => u.id.isNotNull()).updateAndCount({ name: 'x' })` or `db.sql.public.User.update({ name: 'x' }).where((f, fns) => fns.ne(f.id, null)).build()`.
 
 The second way is to build that script its own `db` client with the rule set to `warn`:
 
diff --git a/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx b/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
index 40deaf92a3..5015c56cc0 100644
--- a/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
+++ b/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
@@ -208,7 +208,9 @@ The rows you return are plain objects, keyed by the column aliases in the SQL, h
 { id: 3, email: 'mia+1@prisma.io', createdAt: '2026-09-17 08:00:08.775+00' }
 ```
 
-So for a query whose SQL is `SELECT "User"."id" AS "id", "User"."email" AS "email" FROM "public"."User" LIMIT 5`, `return { rows: [{ id: 1, email: 'mia@prisma.io' }] }` is a complete answer to it. Rows you return go through the same conversion as rows from the database, so a caller on the ORM API gets the types its contract says it should, even though you returned a string. This is how the cache serves repeated reads. Anything you checked in a before-hook has already run by the time either hook is called.
+So for a query whose SQL is `SELECT "User"."id" AS "id", "User"."email" AS "email" FROM "public"."User" LIMIT 5`, `return { rows: [{ id: 1, email: 'mia@prisma.io' }] }` is a complete answer to it. Prisma ORM converts the rows you return the same way it converts rows from the database, so a `createdAt` you return as a string reaches a caller on the ORM API as the type its contract gives `createdAt`, not as a string. This is how the cache serves repeated reads.
+
+Before-hooks still run on a query that an intercept hook answers, because every middleware's before-hooks run before any intercept hook, whatever order you list the middleware in. So in the setup at the top of this page, where the cache comes first in the array, `lints` still checks every query before the cache answers it.
 
 ### onRow: watch rows arrive
 
diff --git a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
index 43480a18c5..1055d71121 100644
--- a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
@@ -25,7 +25,7 @@ App space
 ├─ Add column "displayName" to "user"
 ├─ Data transform: backfill-user-displayName
 ├─ ⚠ Set NOT NULL on "user"."displayName"
-└─ marker e6b5c2849eca8d24ff1e8e88ab2a4234db8e74c497c035cb7ce42e814f31cd63
+└─ marker 866ab885a8a4bd8d9f5adc47784c068be7895a7182c55cc29f9f9967d3019484
 
 ⚠ This migration contains destructive operations that may cause data loss.
 ```
@@ -50,10 +50,10 @@ npx prisma db migrate --db "$PRODUCTION_DATABASE_URL"
 `npx prisma migration status --db "$PRODUCTION_DATABASE_URL"` never changes the database, so you can run it against production whenever you want to know which contract state that database matches. It draws your migration history, marks each migration as applied or pending, and shows which contract state the database matches:
 
 ```text
-○   925198f  @contract
-│↑  20260707T1006_add_user_phone  705b1a6 → 925198f  1 ops  ⧗ pending
-○   705b1a6  @db (db)
-│↑  20260707T1005_init                  ∅ → 705b1a6  2 ops  ✓ applied
+○   967cb9f  @contract
+│↑  20260707T1006_add_user_phone  2d2cec8 → 967cb9f  1 ops  ⧗ pending
+○   2d2cec8  @db (db)
+│↑  20260707T1005_init                  ∅ → 2d2cec8  2 ops  ✓ applied
 ○   ∅
 ```
 
@@ -68,15 +68,15 @@ When migrations are pending, `migration status` also prints a `db migrate --to <
 `db migrate --show` is the preview, and it changes nothing: it draws the same history, marks each migration it would apply with `will run`, and lists them in the order they would run:
 
 ```text
-○   925198f  @contract
-│↑  20260707T1006_add_user_phone  705b1a6 → 925198f  ↑ will run
-○   705b1a6  @db (db)
-│↑  20260707T1005_init                  ∅ → 705b1a6
+○   967cb9f  @contract
+│↑  20260707T1006_add_user_phone  2d2cec8 → 967cb9f  ↑ will run
+○   2d2cec8  @db (db)
+│↑  20260707T1005_init                  ∅ → 2d2cec8
 ○   ∅
 
 ℹ The following 1 migration will run:
 
-  20260707T1006_add_user_phone  705b1a6 → 925198f
+  20260707T1006_add_user_phone  2d2cec8 → 967cb9f
 ```
 
 `--show` tells you which migrations will run, but not what is inside them, so when you want one migration's operations and its SQL, run `npx prisma migration show 20260707T1006_add_user_phone` instead, as [Reviewing what you planned](/orm/migrations/generating-a-migration#reviewing-what-you-planned) shows.
@@ -85,8 +85,8 @@ After applying, `npx prisma migration log --db "$PRODUCTION_DATABASE_URL"` shows
 
 ```text
 Applied at                  Migration                     Change             Ops
-2026-07-07 10:05:32 +00:00  20260707T1005_init            ∅ → 705b1a6        2 ops
-2026-07-07 10:09:55 +00:00  20260707T1006_add_user_phone  705b1a6 → 925198f  1 ops
+2026-07-07 10:05:32 +00:00  20260707T1005_init            ∅ → 2d2cec8        2 ops
+2026-07-07 10:09:55 +00:00  20260707T1006_add_user_phone  2d2cec8 → 967cb9f  1 ops
 ```
 
 In a pipeline, nobody reads the preview, so the job is step 3 alone, with `--to <ref>` so it applies only the migrations someone has pointed the ref at; [Choosing a target](#choosing-a-target) explains refs. `db migrate` checks the marker before it runs anything and fails with `MIGRATION.MARKER_MISMATCH` when the marker names a state outside your history, and [Drift](/orm/migrations/rollbacks-and-recovery#drift-when-the-database-isnt-where-migrations-left-it) says what to do then. [Migrate a shared database from a workflow](/guides/integrations/github-actions#migrate-a-shared-database) shows the job.
@@ -139,7 +139,17 @@ npx prisma db migrate --advance-ref db
 
 In development, add `--advance-ref db` so the next `migration plan` starts from what you just applied, and leave the flag off in CI and production, where you never plan a migration anyway. [The db ref](/orm/migrations/generating-a-migration#the-db-ref-skipping---from) covers what happens without it and how to fix a missed flag. If you edit `migration.ts` while reviewing the migration, recompile it with `node migrations/app/<dir>/migration.ts` before you apply, as [Editing a migration](/orm/migrations/editing-a-migration) explains.
 
-**In CI and production**, you never plan a migration, because migrations arrive through your repository, already reviewed and merged. For that to work, commit each migration's directory, the directories `migration plan` added under `migrations/snapshots/`, one per contract state, and `contract.prisma`, `contract.json`, and `contract.d.ts`. Deploy with the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed, because it fails with an error whose `code` is `MIGRATION.CHECK_HASH_MISMATCH` when a migration's files no longer match the hash stored when it was written, as [Editing a migration](/orm/migrations/editing-a-migration) explains. When that happens, either restore the migration's files from Git, or move the hand edit into `migration.ts` and recompile. It fails with `MIGRATION.CHECK_SNAPSHOT_CONTENT_MISMATCH` when a contract snapshot under `migrations/snapshots/` no longer matches the hash it is filed under, and the other commands that read a snapshot stop with `MIGRATION.CONTRACT_SNAPSHOT_CONTENT_MISMATCH`. Recompiling `migration.ts` does not fix this; restore the edited snapshot from Git. MongoDB snapshots are not checked yet.
+**In CI and production**, you never plan a migration, because migrations arrive through your repository, already reviewed and merged. For that to work, commit these files:
+
+- each migration's directory under `migrations/app/`
+- the directories `migration plan` added under `migrations/snapshots/`, one per contract state
+- `contract.prisma`, `contract.json`, and `contract.d.ts`
+
+Deploy with the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed.
+
+When a migration's files no longer match the hash stored when it was written, `migration check` fails with an error whose `code` is `MIGRATION.CHECK_HASH_MISMATCH`, as [Editing a migration](/orm/migrations/editing-a-migration) explains. To fix it, either restore the migration's files from Git, or move the hand edit into `migration.ts` and recompile.
+
+When a contract snapshot under `migrations/snapshots/` no longer matches the hash in its directory name, `migration check` fails with `MIGRATION.CHECK_SNAPSHOT_CONTENT_MISMATCH`. A command that needs that snapshot, such as `migration plan --from` or `migration ref set` naming its contract state, stops with `MIGRATION.CONTRACT_SNAPSHOT_CONTENT_MISMATCH`. Recompiling `migration.ts` does not fix this, so restore the edited snapshot from Git. MongoDB snapshots are not checked yet.
 
 If two deployments can run at once, what happens next depends on your database. On PostgreSQL, when two `db migrate` runs start against the same database, one of them waits for the other. On MongoDB, if another run updates the marker while yours is running, yours fails with `Marker was modified by another process during migration execution.` When that happens, run `npx prisma migration status` to see which contract state the database matches, and then run `db migrate` again.
 
diff --git a/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx b/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
index b762028fe8..97057aad60 100644
--- a/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
@@ -35,12 +35,12 @@ npx prisma migration plan --name add_display_name
 ```text
 ⚠ Planned migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit
 
-from:       925198f3cc272c5fd19c24ac02f251661775ddac21cdac4e634bbc0dda8b2d72
-to:         e6b5c2849eca8d24ff1e8e88ab2a4234db8e74c497c035cb7ce42e814f31cd63
+from:       967cb9f63587c1d90f64716780f04eec22b263424e89f07139233fc2c3d710c4
+to:         866ab885a8a4bd8d9f5adc47784c068be7895a7182c55cc29f9f9967d3019484
 app space:  migrations/app/20260707T1008_add_display_name
 ```
 
-In that output, `self-emit` is what the CLI calls recompiling, and `app space` is the directory the new migration was written to. `migration plan` writes the change as three steps rather than one, because the column is required and the table already has rows: `addColumn` adds the column as nullable, `dataTransform` holds the backfill you write, and `setNotNull` makes the column required. The table is called `user` because the contract from [Generating a migration](/orm/migrations/generating-a-migration#your-first-migration) maps `User` to it with `@@map("user")`. Without `@@map`, the table name is the model name exactly as written:
+In that output, `self-emit` is what the CLI calls recompiling, and `app space` is the directory the new migration was written to. `migration plan` writes the change as three steps rather than one, because the column is required and the table already has rows: `addColumn` adds the column as nullable, `dataTransform` holds the backfill you write, and `setNotNull` makes the column required:
 
 ```ts title="migration.ts (as planned)"
 override get operations() {
@@ -59,14 +59,16 @@ override get operations() {
 }
 ```
 
+The table is called `user` because the contract from [Generating a migration](/orm/migrations/generating-a-migration#your-first-migration) maps `User` to it with `@@map("user")`. Without `@@map`, the table name is the model name exactly as written, so it would be `User`.
+
 A `dataTransform` is where you say what should happen to the rows already in the table, and it takes two callbacks. Each one returns a query built with the [`sql` query builder](/orm/reference/sql-query-builder), not a SQL string. `check` returns the rows that still need the backfill, which is how Prisma ORM tells whether there is any work left to do, and `run` is the query that changes them. Inside each `where`, `f` holds the table's columns and `fns` holds [functions](/orm/reference/sql-query-builder#expressions-and-functions) such as `eq`, which is why `fns.eq(f.displayName, null)` becomes `IS NULL`. When you want to set a column from another column, pass [`update()`](/orm/reference/sql-query-builder#update) a callback instead of a plain object: `update((f) => ({ displayName: f.email }))`. The imports at the top of the file below come from snapshots, which are copies of your contract that `migration plan` saves in `migrations/snapshots/<hash>/`, and this migration imports the snapshot from before it and the one from after it, so the queries you write are typed against the contract you mean.
 
 ```ts title="migration.ts (filled in)"
 #!/usr/bin/env -S node
-import type { Contract as End } from '../../snapshots/e6b5c2849eca8d24ff1e8e88ab2a4234db8e74c497c035cb7ce42e814f31cd63/contract';
-import endContractJson from '../../snapshots/e6b5c2849eca8d24ff1e8e88ab2a4234db8e74c497c035cb7ce42e814f31cd63/contract.json' with { type: 'json' };
-import type { Contract as Start } from '../../snapshots/925198f3cc272c5fd19c24ac02f251661775ddac21cdac4e634bbc0dda8b2d72/contract';
-import startContractJson from '../../snapshots/925198f3cc272c5fd19c24ac02f251661775ddac21cdac4e634bbc0dda8b2d72/contract.json' with { type: 'json' };
+import type { Contract as End } from '../../snapshots/866ab885a8a4bd8d9f5adc47784c068be7895a7182c55cc29f9f9967d3019484/contract';
+import endContractJson from '../../snapshots/866ab885a8a4bd8d9f5adc47784c068be7895a7182c55cc29f9f9967d3019484/contract.json' with { type: 'json' };
+import type { Contract as Start } from '../../snapshots/967cb9f63587c1d90f64716780f04eec22b263424e89f07139233fc2c3d710c4/contract';
+import startContractJson from '../../snapshots/967cb9f63587c1d90f64716780f04eec22b263424e89f07139233fc2c3d710c4/contract.json' with { type: 'json' };
 import { Migration, MigrationCLI, col } from '@prisma/orm-postgres/migration';
 import postgresAdapter from '@prisma/orm-postgres/adapter/runtime';
 import { sql } from '@prisma/orm-postgres/builder/runtime';
@@ -168,9 +170,9 @@ model User {
 }
 ```
 
-Keep `// use prisma-8` as the first line of the copy, because `contract emit` reads only files that start with it.
+Keep `// use prisma-8` as the first line of the copy. `contract emit` skips any `.prisma` file that does not start with it, and because `intermediate.prisma` is the only file in the intermediate contract, emitting it without that line fails with an error whose `code` is `CONTRACT.SOURCE_LOAD_FAILED`.
 
-In the same migration directory, add `intermediate.config.ts`, a second config file that names `intermediate.prisma` as the contract and needs no database connection. `parent: false` stops the CLI from also reading your project's `prisma.config.ts`, which it would otherwise find in a parent directory and merge in:
+In the same migration directory, add `intermediate.config.ts`, a second config file. Its `contract` is `intermediate.prisma`, and it has no `db` setting, because emitting a contract never connects to a database. `parent: false` makes the CLI use this file on its own. Without it, the CLI also loads your project's `prisma.config.ts` and adds that file's `orm` settings, such as `db`, to the ones written here:
 
 ```ts title="intermediate.config.ts"
 import { definePrismaConfig } from 'prisma/config';
@@ -178,12 +180,14 @@ import { defineConfig as ormConfig } from '@prisma/orm-postgres/config';
 export default definePrismaConfig({ parent: false, orm: ormConfig({ contract: './intermediate.prisma' }) });
 ```
 
-Emit the intermediate contract with `--config` pointing at that file. A relative path in a config file resolves from the directory of that file, so `./intermediate.prisma` is found wherever you run the command from. Commit all four `intermediate.*` files along with the migration, since the migration no longer recompiles without them.
+Emit the intermediate contract with `--config` pointing at that file. A relative path in a config file resolves from the directory of that file, so `./intermediate.prisma` is found wherever you run the command from:
 
 ```bash
 npx prisma contract emit --config migrations/app/20260708T0900_replace_is_admin/intermediate.config.ts
 ```
 
+The command writes `intermediate.json` and `intermediate.d.ts` next to `intermediate.prisma`, so the migration directory now holds four `intermediate.*` files. Commit all four along with the migration, because the migration no longer recompiles without them:
+
 ```text title="migrations/app/20260708T0900_replace_is_admin/"
 ├── intermediate.config.ts
 ├── intermediate.d.ts
@@ -200,8 +204,8 @@ Now fill in this migration's own planned `migration.ts`, rather than copying the
 #!/usr/bin/env -S node
 import type { Contract as End } from '../../snapshots/<end hash>/contract';
 import endContractJson from '../../snapshots/<end hash>/contract.json' with { type: 'json' };
-import type { Contract as Start } from '../../snapshots/e6b5c2849eca8d24ff1e8e88ab2a4234db8e74c497c035cb7ce42e814f31cd63/contract';
-import startContractJson from '../../snapshots/e6b5c2849eca8d24ff1e8e88ab2a4234db8e74c497c035cb7ce42e814f31cd63/contract.json' with { type: 'json' };
+import type { Contract as Start } from '../../snapshots/866ab885a8a4bd8d9f5adc47784c068be7895a7182c55cc29f9f9967d3019484/contract';
+import startContractJson from '../../snapshots/866ab885a8a4bd8d9f5adc47784c068be7895a7182c55cc29f9f9967d3019484/contract.json' with { type: 'json' };
 import type { Contract as Mid } from './intermediate';
 import midContractJson from './intermediate.json' with { type: 'json' };
 import { Migration, MigrationCLI, col } from '@prisma/orm-postgres/migration';
@@ -292,7 +296,7 @@ override get operations() {
 
 Not every migration comes from a contract change. When you want a data-only migration, which changes rows and leaves your contract state as it is, or a migration you intend to write entirely by hand, run `npx prisma migration new`. It writes an empty `ops.json`, a `migration.json`, and a `migration.ts` that already has the snapshot imports, the class, and an empty `operations` array. Nothing was planned for you, so there is no `placeholder` import to remove, but you do have to add the `@prisma/orm-postgres` imports and the `endContract`, `stack`, and `db` statements from the filled-in `displayName` listing.
 
-A data-only migration starts and ends at the contract state your database already matches. Without `--from`, `migration new` starts from the `db` ref, which is that state when you apply migrations with `--advance-ref db`. To start from another state, pass `--from` with the hash of the migration that ends there. `npx prisma migration graph` marks your contract's hash `@contract`. The [`migration new` reference](/cli/migration-new) lists the rest of the options:
+`migration new` always ends at the contract state in your `contract.json`, and a data-only migration starts there too, so you pass that state's hash with `--from`. If you leave `--from` off, `migration new` starts from the `db` ref, and when the ref already names your current contract, as it does after `npx prisma db migrate --advance-ref db`, the command stops with an error whose `code` is `MIGRATION.NO_CHANGES`. `--from` takes the contract hash in the `to` field of an existing migration's `migration.json`, or the first few characters of it. To find your current contract's hash, run `npx prisma migration graph` and look for the row labelled `@contract`. It shows the first 7 characters of the hash, and you can pass those to `--from`. The [`migration new` reference](/cli/migration-new) lists the rest of the options:
 
 ```npm
 npx prisma migration new --name backfill_scores --from <hash>
diff --git a/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx b/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
index 49de023f8a..0fa64a20e0 100644
--- a/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
@@ -26,6 +26,8 @@ model User {
 }
 ```
 
+Keep `// use prisma-8` as the first line of every `.prisma` file in your contract. `contract emit` and the Prisma editor extension read only the `.prisma` files that start with it and skip the others without a warning, and when no file starts with it, `contract emit` fails with an error whose `code` is `CONTRACT.SOURCE_LOAD_FAILED`.
+
 Run both commands, passing `--name init` so that the new migration directory is named `<timestamp>_init`:
 
 ```npm
@@ -46,7 +48,7 @@ migrations/app/20260707T1005_init
 └─ Create table "user"
 
 from:       (baseline)
-to:         705b1a62f26f0913caa4bfe3f8b7cb491a1b94bd47fc43471d8711bc480bcbb5
+to:         2d2cec8641643159cfc94e499e5eacbd75218e0389d938139b278f68618d6b13
 app space:  migrations/app/20260707T1005_init
 
 ℹ DDL preview
@@ -79,8 +81,8 @@ A migration is a directory, and there is no SQL file in it. `migration.ts` is th
 
 ```ts title="migrations/app/20260707T1005_init/migration.ts"
 #!/usr/bin/env -S node
-import type { Contract as End } from '../../snapshots/705b1a62f26f0913caa4bfe3f8b7cb491a1b94bd47fc43471d8711bc480bcbb5/contract';
-import endContract from '../../snapshots/705b1a62f26f0913caa4bfe3f8b7cb491a1b94bd47fc43471d8711bc480bcbb5/contract.json' with { type: 'json' };
+import type { Contract as End } from '../../snapshots/2d2cec8641643159cfc94e499e5eacbd75218e0389d938139b278f68618d6b13/contract';
+import endContract from '../../snapshots/2d2cec8641643159cfc94e499e5eacbd75218e0389d938139b278f68618d6b13/contract.json' with { type: 'json' };
 import { Migration, MigrationCLI, col, primaryKey } from '@prisma/orm-postgres/migration';
 
 export default class M extends Migration<never, End> {
@@ -129,8 +131,8 @@ npx prisma migration plan --name add_user_phone
 migrations/app/20260707T1006_add_user_phone
 └─ Add column "phone" to "user"
 
-from:       705b1a62f26f0913caa4bfe3f8b7cb491a1b94bd47fc43471d8711bc480bcbb5
-to:         925198f3cc272c5fd19c24ac02f251661775ddac21cdac4e634bbc0dda8b2d72
+from:       2d2cec8641643159cfc94e499e5eacbd75218e0389d938139b278f68618d6b13
+to:         967cb9f63587c1d90f64716780f04eec22b263424e89f07139233fc2c3d710c4
 app space:  migrations/app/20260707T1006_add_user_phone
 
 ℹ DDL preview
@@ -198,8 +200,8 @@ npx prisma migration plan --name add_display_name
 
 ⚠ Planned migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit
 
-from:       925198f3cc272c5fd19c24ac02f251661775ddac21cdac4e634bbc0dda8b2d72
-to:         e6b5c2849eca8d24ff1e8e88ab2a4234db8e74c497c035cb7ce42e814f31cd63
+from:       967cb9f63587c1d90f64716780f04eec22b263424e89f07139233fc2c3d710c4
+to:         866ab885a8a4bd8d9f5adc47784c068be7895a7182c55cc29f9f9967d3019484
 app space:  migrations/app/20260707T1008_add_display_name
 ```
 
diff --git a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
index 5d90bcc73b..4bb23281c7 100644
--- a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
+++ b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
@@ -19,7 +19,7 @@ You run this loop many times a day:
 3. **Review it**: before anything touches the database, run `npx prisma migration show <dir>` to see the operations and SQL that `db migrate` will run. If you want the migration to change rows as well, [edit `migration.ts` and recompile it](/orm/migrations/editing-a-migration) by running `node migrations/app/<dir>/migration.ts` from your project root, which rewrites `ops.json`. Nothing extra is needed to run that file, because the Prisma ORM CLI already requires Node.js 22.18 or later, which runs `migration.ts` directly.
 4. **Apply it**: `db migrate` starts by reading the database's marker, the record in the database of which contract state it matches, so it knows how much of your history the database has already seen, and then runs the migrations from that state to your current contract. In development, add [`--advance-ref db`](/orm/migrations/generating-a-migration#the-db-ref-skipping---from) so the next `migration plan` starts from what you just applied.
 
-With a database connection set up, as in the [quickstart](/prisma-orm/quickstart/postgresql), add an optional `phone String?` field to `User`, then run:
+Say your contract is the one in [Generating a migration](/orm/migrations/generating-a-migration#your-first-migration), whose `User` model is stored in the table `user` because it sets `@@map("user")`, and its first migration is applied. With a database connection set up, as in the [quickstart](/prisma-orm/quickstart/postgresql), add an optional `phone String?` field to `User`, then run:
 
 ```npm
 npx prisma contract emit
@@ -34,18 +34,26 @@ npx prisma db migrate --advance-ref db
 ✔ Planned 1 operation(s)
 
 migrations/app/20260707T1006_add_user_phone
-└─ Add column "phone" to "User"
+└─ Add column "phone" to "user"
 
-from:       705b1a62f26f0913caa4bfe3f8b7cb491a1b94bd47fc43471d8711bc480bcbb5
-to:         925198f3cc272c5fd19c24ac02f251661775ddac21cdac4e634bbc0dda8b2d72
+from:       2d2cec8641643159cfc94e499e5eacbd75218e0389d938139b278f68618d6b13
+to:         967cb9f63587c1d90f64716780f04eec22b263424e89f07139233fc2c3d710c4
 app space:  migrations/app/20260707T1006_add_user_phone
 
 ℹ DDL preview
 
-ALTER TABLE "public"."User" ADD COLUMN "phone" text;
+ALTER TABLE "public"."user" ADD COLUMN "phone" text;
 ```
 
-A table name is the model name exactly as written unless the model sets `@@map`, so `User` is the table `"User"` and `UserProfile` is `"UserProfile"`, the same names Prisma ORM 7 used. Before `8.0.0-rc.12`, a model without `@@map` named its table with a lowercase first letter, `"userProfile"`. If your tables were created with those names, run the `add-model-map` script from the [upgrade recipe](https://github.com/prisma/orm/blob/v8.0.0-rc.12/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.11-to-8.0.0-rc.12/) over every `.prisma` file, including the `contract.prisma` copies under `migrations/`, before you plan. It adds `@@map("<current table name>")` to each model that has none. Without it, `migration plan` stops with [`MIGRATION.TABLE_NAME_CASE_CHANGED`](/orm/reference/error-reference#MIGRATION.TABLE_NAME_CASE_CHANGED) rather than drop the table and create an empty one.
+A table name is the model name exactly as written unless the model sets `@@map`, so without `@@map("user")` this `User` model would be the table `"User"`, and a `UserProfile` model is the table `"UserProfile"`. These are the same names Prisma ORM 7 used.
+
+If you used a Prisma ORM 8 release before 8.0.0-rc.12, you have one more thing to do before you plan, because in those releases a model without `@@map` named its table with a lowercase first letter, such as `"userProfile"`. If your tables were created with those names, download the [`add-model-map` script](https://github.com/prisma/orm/blob/v8.0.0-rc.12/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.11-to-8.0.0-rc.12/scripts/psl-verbatim-table-names/add-model-map.mjs) and run it from your project root before you plan:
+
+```bash
+node <path to add-model-map.mjs> '**/*.prisma'
+```
+
+The script adds `@@map("<current table name>")` to each model that has none, in every `.prisma` file in your project, including any you keep in a migration directory. If you plan without running it, `migration plan` stops with [`MIGRATION.TABLE_NAME_CASE_CHANGED`](/orm/reference/error-reference#MIGRATION.TABLE_NAME_CASE_CHANGED) instead of dropping the table and creating an empty one.
 
 The `app space:` line tells you which migration history the new directory was written into. A contract space is a separate migration history, so your own migrations stay in `migrations/app/` while each [Prisma ORM extension package](/orm/migrations/applying-a-migration#extension-spaces) that ships migrations, such as pgvector, keeps its migrations in its own directory under `migrations/`.
 
@@ -103,11 +111,13 @@ Because that `from` hash is what ties one migration to another, your [migration
 
 Inside `ops.json`, an operation is not only the change itself: it also carries the checks that decide whether the change needs to run and whether it worked. Here are the parts of the operation that adds the `phone` column:
 
-- **Precheck**: confirms the database is in the state the change expects, here that `"User"` has no `phone` column.
-- **Execute**: the statements that make the change, here `ALTER TABLE "public"."User" ADD COLUMN "phone" text`.
+- **Precheck**: confirms the database is in the state the change expects, here that `"user"` has no `phone` column.
+- **Execute**: the statements that make the change, here `ALTER TABLE "public"."user" ADD COLUMN "phone" text`.
 - **Postcheck**: confirms the change is in the database, here that the `phone` column exists. Some operations have no postcheck. `db migrate` skips an operation only when its postcheck already passes, so an operation with no postcheck always runs.
 
-When `db migrate` reaches an operation, it runs the postcheck before the change as well as after, because if the postcheck already passes then the change is in the database and there is nothing to do, so the operation is skipped. If the postcheck does not pass, `db migrate` runs the precheck, then the statements, then the postcheck, and it stops the run if either check fails. Once the operations are done, it checks the database against the contract before it updates the marker, which catches a database that satisfied every individual operation but still doesn't match what you declared. Say `"User"` already has a `phone` column of another type: the postcheck only asks whether a `phone` column exists, so it passes, the operation is skipped, and that final contract check then fails the run.
+When `db migrate` reaches an operation, it runs the postcheck first. If the postcheck passes, the change is already in the database, so `db migrate` skips the operation. If it does not pass, `db migrate` runs the precheck, then the statements, then the postcheck again, and it stops the run if either check fails. Once the operations are done, it checks the database against the contract before it updates the marker, which catches a database that satisfied every individual operation but still doesn't match what you declared.
+
+Say `"user"` already has a `phone` column of another type. The postcheck only asks whether a `phone` column exists, so it passes and the operation is skipped. The check against the contract then finds the wrong type, and the run fails with an error whose `code` is `MIGRATION.RUNNER_FAILED` and whose explanation says the database schema does not satisfy the contract. To see which columns differ, run `npx prisma db verify --schema-only`. Change the `phone` column in the database to the type your contract declares, and run `db migrate` again.
 
 Each operation also has an `operationClass`, which says what kind of change the operation makes to the database and which you choose yourself when you write a raw SQL operation:
 
diff --git a/apps/docs/content/docs/orm/migrations/rollbacks-and-recovery.mdx b/apps/docs/content/docs/orm/migrations/rollbacks-and-recovery.mdx
index 45217ce578..7d279e4e72 100644
--- a/apps/docs/content/docs/orm/migrations/rollbacks-and-recovery.mdx
+++ b/apps/docs/content/docs/orm/migrations/rollbacks-and-recovery.mdx
@@ -31,8 +31,8 @@ migrations/app/20260707T1010_rollback_display_name
 
 ⚠ This migration contains destructive operations that may cause data loss.
 
-from:       e6b5c2849eca8d24ff1e8e88ab2a4234db8e74c497c035cb7ce42e814f31cd63
-to:         925198f3cc272c5fd19c24ac02f251661775ddac21cdac4e634bbc0dda8b2d72
+from:       866ab885a8a4bd8d9f5adc47784c068be7895a7182c55cc29f9f9967d3019484
+to:         967cb9f63587c1d90f64716780f04eec22b263424e89f07139233fc2c3d710c4
 app space:  migrations/app/20260707T1010_rollback_display_name
 
 ℹ DDL preview
diff --git a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
index a74cea8cdd..36fdac2028 100644
--- a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
+++ b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
@@ -180,7 +180,8 @@ The graph itself, the way `db migrate` chooses which migrations to run, refs, th
 
 - **No squash.** You cannot yet collapse a long chain of migrations into one.
 - **No split.** You cannot yet break one large migration into smaller ones after the fact.
-- **`migration new` starts from the `db` ref.** `npx prisma migration new` writes an empty migration for a change you write yourself, such as a data update, and without `--from` it starts where `migration plan` would: at the `db` ref. To build on another state, such as `e377d00` in the drawing above, pass a prefix of it: `npx prisma migration new --name backfill --from e377d00`.
+
+`npx prisma migration new` writes an empty migration for a change you write yourself, such as a data update. Without `--from` it starts where `migration plan` would, at the `db` ref. Its `--from` accepts less than the one on `migration plan`: it takes only the contract hash in the `to` field of an existing migration's `migration.json`, or the first few characters of it, and not a ref name, a migration directory name, or one of the `@` tokens. So to build on `e377d00` in the drawing above, run `npx prisma migration new --name backfill --from e377d00`.
 
 ## Common tasks
 
diff --git a/apps/docs/content/docs/orm/reference/orm-client.mdx b/apps/docs/content/docs/orm/reference/orm-client.mdx
index b73bc1f331..d41b6e8963 100644
--- a/apps/docs/content/docs/orm/reference/orm-client.mdx
+++ b/apps/docs/content/docs/orm/reference/orm-client.mdx
@@ -182,7 +182,7 @@ Some parts of the schema the examples rely on:
 - On MongoDB, `id ObjectId @id @map("_id")` renames the field to `_id` everywhere: you filter on `_id`, and the returned document has an `_id` key. That is why the MongoDB examples never say `id`.
 - `Uuid` is a built-in type for a PostgreSQL `uuid` column. You do not import it. `@default(uuid())` fills the id in when you insert a row.
 - `@@type("pg/text@1")` on an `enum` block stores the enum as a text column. The `@1` is the version of that storage format, and only version 1 exists today, so write it exactly like that. The MongoDB form of the same attribute is `@@type("mongo/string@1")`. This page calls an enum written this way a text-backed enum.
-- A `native_enum` block stores the same members as a real PostgreSQL enum type instead. Give every member a value. A member with no value is rejected. This page calls an enum written this way a native enum. The two sort differently; see [`orderBy()`](#orderby).
+- A `native_enum` block stores the same members as a real PostgreSQL enum type instead. Give every member a value. A member with no value is rejected. A field that uses it is typed `pg.enum(Priority)`. This page calls an enum written this way a native enum. The two sort differently; see [`orderBy()`](#orderby).
 
   ```prisma
   native_enum Priority {
@@ -190,6 +190,11 @@ Some parts of the schema the examples rely on:
     High   = "high"
     Urgent = "urgent"
   }
+
+  model Post {
+    id       Uuid              @id @default(uuid())
+    priority pg.enum(Priority)
+  }
   ```
 
 - An enum member's stored value is the string after `=`, or the member name when there is no `=`. That string is what you pass to `.eq()`. So `Urgent = "urgent"` is matched by `.eq('urgent')`, and a bare `admin` member is matched by `.eq('admin')`.
@@ -231,7 +236,7 @@ To give a model your own methods on top of the built-in ones, import `Collection
 
 ### MongoDB
 
-Create a MongoDB client with `mongo(...)`. `db.orm` holds your models by collection name, with no schema in between: `db.orm.users`, `db.orm.posts`, not `db.orm.User`. The collection name is the one you set with `@@map`, or the model name exactly as written when you did not set one. `dbName` is the MongoDB database name.
+Create a MongoDB client with `mongo(...)`. `db.orm` holds your models by collection name, with no schema in between. The collection name is the one you set with `@@map`, or the model name exactly as written when you did not set one. The example schema maps `User` to `users`, so it is `db.orm.users`, and `Post` is `db.orm.posts`. `dbName` is the MongoDB database name.
 
 ```typescript
 import mongo from '@prisma/orm-mongo/runtime';
@@ -914,7 +919,7 @@ const features = await tasks.Task.features().all();
 
 A write method changes the database. `create`, `createAll`, `createAndCount`, `update`, `updateAll`, `updateAndCount`, `delete`, `deleteAll`, `deleteAndCount`, and `upsert` are available on both databases, and the differences between the two are listed under each method.
 
-For Prisma ORM 7 users: `createMany` is `createAll()` or `createAndCount()`, `updateMany` is `updateAll()` or `updateAndCount()`, `deleteMany` is `deleteAll()` or `deleteAndCount()`, and `count` is [`aggregate()`](#grouped-aggregates) on PostgreSQL, or the two steps shown under [Read methods](#read-terminals) on MongoDB. There is no `skipDuplicates` option.
+For Prisma ORM 7 users: `createMany` is `createAll()` or `createAndCount()`, `updateMany` is `updateAll()` or `updateAndCount()`, `deleteMany` is `deleteAll()` or `deleteAndCount()`, and `count` is [`aggregate()`](#grouped-aggregates) on PostgreSQL, or the two steps shown under [Read methods](#read-terminals) on MongoDB. `skipDuplicates: true` is now `{ onConflict: 'skip' }`, which you pass to [`createAll()`](#createall) or [`createAndCount()`](#createandcount) on PostgreSQL as a second argument.
 
 To catch one of the errors named below, wrap the call in `try` and `catch`, then compare `error.code` with the string given here. For a task-oriented walkthrough, see [Writing data](/orm/fundamentals/writing-data). On MongoDB, a write method rejects a chain that already has `orderBy()`, `limit()`, or `offset()` on it, and every write except `updateAll()` and `deleteAll()` also rejects `include()`. Both throw an error whose `code` is `ORM.OPERATION_UNSUPPORTED`. For grouping several writes into one unit, see [Transactions](/orm/fundamentals/transactions).
 
@@ -1006,15 +1011,20 @@ Insert multiple rows and return them.
 - Available for PostgreSQL and MongoDB.
 - Returns an [`AsyncIterableResult`](#asynciterableresult): `await` for an array, or `for await` to stream inserted rows.
 - On PostgreSQL every row is inserted by one statement before the first row reaches you. Stopping the loop early does not undo an insert.
-- On PostgreSQL and SQLite, `{ onConflict: 'skip' }` as the second argument skips each row that collides with a unique constraint, and the result holds only the rows the database wrote. `conflictOn: ['email']` names the unique constraint by its columns; without it, a collision on any unique constraint skips the row. A variant stored in its own table refuses the option with `ORM.OPERATION_UNSUPPORTED`. The option needs capabilities that a contract emitted before `8.0.0-rc.12` does not list, so run `npx prisma contract emit` once first; otherwise it fails with `ORM.CAPABILITY_MISSING`.
+- To skip each row that would break a unique constraint, instead of failing the whole insert, pass `{ onConflict: 'skip' }` as the second argument. The result then holds only the rows the database wrote. This replaces `skipDuplicates: true` from Prisma ORM 7.
+- `onConflict` works on PostgreSQL, and on SQLite through the experimental `@prisma/orm-sqlite` package. On MongoDB, `createAll()` takes only the rows, so a second argument is a type error.
+- By default, a row is skipped when it breaks any unique constraint. To check only one constraint, list its fields in `conflictOn`. In the example schema, `Tag.label` is unique, so `conflictOn: ['label']` skips a tag whose label already exists.
+- `onConflict` does not work on a variant stored in its own table, such as `Bug`, which maps to `bug` while its base model `Task` maps to `task`. Passing it there throws an error whose `code` is `ORM.OPERATION_UNSUPPORTED`.
+- If your contract was emitted before `8.0.0-rc.12`, run `npx prisma contract emit` again before you use `onConflict`. Otherwise the call throws an error whose `code` is `ORM.CAPABILITY_MISSING`.
 
 #### Options
 
 | Name | Type | Required | Description |
 |---|---|---|---|
-| The rows | Array of field objects | Yes | The rows to insert, passed as the first argument. There is no `data` wrapper. |
-| `onConflict` | `'skip'` | No | Skip rows that collide with a unique constraint. PostgreSQL and SQLite. |
-| `conflictOn` | Array of field names | No | With `onConflict`, the columns of the unique constraint to check. |
+| First argument | Array of row objects | Yes | The rows to insert. There is no `data` wrapper. |
+| Second argument | `{ onConflict: 'skip', conflictOn? }` | No | Skip rows that break a unique constraint. Not available on MongoDB. |
+
+`conflictOn` is an array of field names, such as `['label']`. [`upsert()`](#upsert) also takes a `conflictOn`, but there it is an object of field values, such as `{ label: 'typescript' }`.
 
 #### Return type
 
@@ -1060,9 +1070,10 @@ Insert rows and return how many were inserted, without reading them back.
 
 | Name | Type | Required | Description |
 |---|---|---|---|
-| The rows | Array of field objects | Yes | The rows to insert, passed as the first argument. There is no `data` wrapper. |
-| `onConflict` | `'skip'` | No | Skip rows that collide with a unique constraint. PostgreSQL and SQLite. |
-| `conflictOn` | Array of field names | No | With `onConflict`, the columns of the unique constraint to check. |
+| First argument | Array of row objects | Yes | The rows to insert. There is no `data` wrapper. |
+| Second argument | `{ onConflict: 'skip', conflictOn? }` | No | Skip rows that break a unique constraint. Not available on MongoDB. |
+
+`conflictOn` is an array of field names, as on [`createAll()`](#createall).
 
 #### Return type
 
@@ -1683,7 +1694,7 @@ Comparison methods on a field.
 - `eq`, `neq`, `in`, and `notIn` are on a field whose values can be compared for equality.
 - `gt`, `lt`, `gte`, and `lte` are on a field whose values can be ordered.
 - `like` and `ilike` are on a text field.
-- `String` fields and enums stored as text have all of them. A native enum field (`pg.enum(...)`) has all but `like` and `ilike`, because PostgreSQL has no pattern match for an `enum` type. `Uuid` and `DateTime` have all but `like` and `ilike`. A `Boolean` field has only the equality methods, `isNull()`, and `isNotNull()`. A `Json` field has only `isNull()` and `isNotNull()`.
+- `String` fields and enums stored as text have all of them. A [native enum](#example-schema) field, typed `pg.enum(...)` in the contract, has all but `like` and `ilike`, because PostgreSQL has no pattern match for an `enum` type. `Uuid` and `DateTime` have all but `like` and `ilike`. A `Boolean` field has only the equality methods, `isNull()`, and `isNotNull()`. A `Json` field has only `isNull()` and `isNotNull()`.
 - `like()` matches a SQL pattern case-sensitively. `ilike()` matches the same pattern case-insensitively.
 - `in([])` matches no rows. `notIn([])` matches every row.
 
@@ -1736,19 +1747,30 @@ PostgreSQL full-text search on a text field.
 
 #### Remarks
 
-- PostgreSQL. A text field has `fullTextMatches(query, options?)` to filter and `fullTextRank(query, options?)` to sort by relevance. The [SQL query builder](/orm/reference/sql-query-builder) has the same operations as `fns.fullTextMatches(column, query)`, `fns.fullTextRank(column, query)`, and `fns.fullTextHeadline(column, query)`, which returns the matching text with each match marked.
-- `query` is a `tsquery`, not a string, and a bare string is a type error. Build it with a parser from `@prisma/orm-postgres/target/full-text`: `websearchToTsquery(text)` reads search-box text, `plaintoTsquery(text)` requires every word, and `phrasetoTsquery(text)` requires the words in order. `toTsquery(text)` takes PostgreSQL's operator syntax as written, so never pass user input to it.
-- For user input inside operator syntax, such as a prefix match while the user types, use the `tsquery` template tag from the same package: `` tsquery`${term}:*` ``. It turns each interpolated value into one quoted term, so the input cannot add operators. Do not put quotes around the interpolation yourself.
-- `language` sets the text-search configuration and defaults to `english`. The operation's `language` applies to the field, and each parser, and the tag as `` tsquery({ language })`...` ``, takes its own `language` for the query. Pass the same value to both.
-- Add [`@@fullTextIndex`](/orm/contract-authoring/psl-syntax#full-text-indexes) to the model, with the same `language`, so PostgreSQL can use an index for the search. Without it the query still works, with a sequential scan.
-- A native enum field (`pg.enum(...)`) has no full-text operations.
+- PostgreSQL. A text field has `fullTextMatches(query, options?)` to filter and `fullTextRank(query, options?)` to sort by relevance.
+- The [SQL query builder](/orm/reference/sql-query-builder) has both, as `fns.fullTextMatches(column, query)` and `fns.fullTextRank(column, query)`. It also has `fns.fullTextHeadline(column, query)`, which returns the matching text with each match marked. Use the SQL query builder when you want that text in your results, because the ORM's `select()` takes only field names.
+- The `query` argument is a parsed search query, which PostgreSQL calls a `tsquery`. Passing a plain string is a type error. Build the query with one of these functions from `@prisma/orm-postgres/target/full-text`: `websearchToTsquery(text)` reads text the way a web search box does, with quotes around a phrase, `or`, and `-` before a word to leave it out. `plaintoTsquery(text)` requires every word, and `phrasetoTsquery(text)` requires the words in order.
+- `toTsquery(text)` reads PostgreSQL's own search syntax, in which `&` means and, `|` means or, `!` means not, and `:*` after a word matches any word that starts with it. Text that breaks this syntax makes the query fail when it runs, so never pass user input to `toTsquery()`.
+- To add an operator to user text, such as `:*` for a prefix match while the user types, use the `tsquery` template tag from the same package: `` tsquery`${term}:*` ``. The tag puts each interpolated value in quotes as one search term, so the user's text cannot add operators of its own. Do not put quotes around the interpolation yourself.
+- `language` is the language whose rules PostgreSQL uses to match words, so that in `english` a search for `run` also finds `running`. It defaults to `english`. The method and the parser each take `language`, so pass the same value to both. The tag takes it as `` tsquery({ language: 'german' })`${input}:*` ``.
+
+  ```typescript
+  const q = websearchToTsquery(input, { language: 'german' });
+  const posts = await db.orm.public.Post.where((p) => p.title.fullTextMatches(q, { language: 'german' })).all();
+  ```
+
+- Add [`@@fullTextIndex`](/orm/contract-authoring/psl-syntax#full-text-indexes) to the model, with the same `language`, so PostgreSQL can use an index for the search. Without it the query still works, but PostgreSQL reads every row.
+- A native enum field, typed `pg.enum(...)` in the contract, has no full-text operations.
 
 #### Options
 
 | Method | Options | Description |
 |---|---|---|
 | `fullTextMatches(query, options?)` | `language` | Matches rows whose field matches `query`. |
-| `fullTextRank(query, options?)` | `language`, `normalization` (0 to 63), `coverDensity` | The relevance of the match, for `orderBy()`. `coverDensity: true` uses `ts_rank_cd` in place of `ts_rank`. |
+| `fullTextRank(query, options?)` | `language`, `normalization`, `coverDensity` | The relevance of the match, for `orderBy()`. |
+
+- `normalization` sets how the length of the text changes the rank. It is a whole number from 0 to 63, made by adding PostgreSQL's flags together. The default, 0, ignores length. `2` divides the rank by the length of the text, so of two titles with the same matches, the shorter one ranks higher. The PostgreSQL manual lists every flag under [Ranking search results](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-RANKING).
+- `coverDensity: true` also counts how close together the matching words are, so a row where they appear near each other ranks higher.
 
 #### Examples
 
diff --git a/apps/docs/content/docs/orm/reference/sql-query-builder.mdx b/apps/docs/content/docs/orm/reference/sql-query-builder.mdx
index 44da5ffefb..8a22fde62a 100644
--- a/apps/docs/content/docs/orm/reference/sql-query-builder.mdx
+++ b/apps/docs/content/docs/orm/reference/sql-query-builder.mdx
@@ -130,7 +130,9 @@ model Feature {
 
 In Prisma ORM 8 your `schema.prisma` is called `contract.prisma`. [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7) gets you from a Prisma ORM 7 project to that file, and has the rest of the setup steps. Install the client with `npm install @prisma/orm-postgres`. Run `npx prisma contract emit` to write `contract.json` and `contract.d.ts` beside `contract.prisma`. The examples below assume your own file is in `src/prisma/`, next to those two files, and they write the type import path as `./contract.d`, exactly like that.
 
-You build queries from the client's `sql` property. Create a Postgres client with `postgres(...)`, then reach tables through `db.sql.public`. `public` is the PostgreSQL schema your tables are in, and a model goes in `public` unless your contract puts it in a `namespace` block. Table accessors are keyed by table name, not model name. A table name is the model's `@@map` value, or the model name exactly as written when the model has no `@@map`, so the `User` model mapped to `user` is reached as `db.sql.public.user`, and the model for the `Post`/`Tag` join table, mapped to `post_tag`, is reached as `db.sql.public.post_tag`. Column names are the field names unless a field sets `@map`.
+You build queries from the client's `sql` property. Create a Postgres client with `postgres(...)`, then reach tables through `db.sql.public`. `public` is the PostgreSQL schema your tables are in. To put a model's table in another PostgreSQL schema, such as `auth`, wrap the model in a `namespace auth { ... }` block in your contract, and you then reach its table through `db.sql.auth` instead. See [Namespaces](/orm/contract-authoring/psl-syntax#namespaces).
+
+Table accessors are keyed by table name, not model name. A table name is the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. In the example schema, the `User` model is mapped to `user`, so you write `db.sql.public.user`. The `PostTag` model for the join table is mapped to `post_tag`, so you write `db.sql.public.post_tag`. Column names are the field names unless a field sets `@map`.
 
 ### The `db.sql` builder [#the-dbsql-facet]
 
@@ -923,9 +925,17 @@ Which aggregate functions exist depends on your database, and PostgreSQL gives y
 | `min(field)` | The input column's own type. A `VarChar` column gives a `String` (`text`) |
 | `max(field)` | The input column's own type. A `VarChar` column gives a `String` (`text`) |
 
-On PostgreSQL you also get `ilike(expr, pattern)` for text columns, as in `fns.ilike(f.displayName, '%alice%')`, but not for a native enum column (`pg.enum(...)`), which has no text operations.
+On PostgreSQL, `fns` also has `ilike(expr, pattern)`, a case-insensitive SQL `LIKE` match for text columns, as in `fns.ilike(f.displayName, '%alice%')`. There is no `fns.like`, so write a case-sensitive `LIKE` in a [`fns.raw`](#fnsraw-and-returns) fragment. `ilike` does not accept a column whose type is a native PostgreSQL enum, which a contract declares in a `native_enum` block and types as `pg.enum(...)`, because PostgreSQL cannot pattern-match an enum type. See [Enums](/orm/contract-authoring/psl-syntax#enums).
+
+Full-text search on PostgreSQL uses `fns.fullTextMatches(column, query)` to filter, `fns.fullTextRank(column, query)` to score, and `fns.fullTextHeadline(column, query)` to return the matching text with each match marked. Build `query` from the search text with `fns.websearchToTsquery(text)`, `fns.plaintoTsquery(text)`, `fns.phrasetoTsquery(text)`, or `fns.toTsquery(text)`, or with the `tsquery` template tag from `@prisma/orm-postgres/target/full-text`. [Full-text search](/orm/reference/orm-client#full-text-search) on the ORM client reference explains what each of these does, and the index that lets PostgreSQL search without reading every row.
+
+Each of the three full-text functions takes an options object as its last argument, and each accepts `language`. Give the parser the same `language`, as in `fns.fullTextMatches(f.title, fns.websearchToTsquery(q, { language: 'german' }), { language: 'german' })`. `fullTextRank` also takes `normalization` and `coverDensity`, which the ORM client reference describes. `fullTextHeadline` also takes these options:
+
+- `startSel` and `stopSel`: the text put before and after each match. PostgreSQL uses `<b>` and `</b>` when you leave them out.
+- `maxWords` and `minWords`: the longest and shortest headline, in words. `minWords` must be lower than `maxWords`.
+- `highlightAll: true`: return the whole text with every match marked, instead of a short excerpt around the matches.
 
-Full-text search on PostgreSQL uses `fns.fullTextMatches(column, query)` to filter, `fns.fullTextRank(column, query)` to score, and `fns.fullTextHeadline(column, query, options?)` to return the matching text with each match marked. `query` is a `tsquery`: build it with `fns.websearchToTsquery(text)`, `fns.plaintoTsquery(text)`, `fns.phrasetoTsquery(text)`, or `fns.toTsquery(text)`, or with the `tsquery` tag from `@prisma/orm-postgres/target/full-text`. `fullTextHeadline` takes `startSel`, `stopSel`, `maxWords`, `minWords`, and `highlightAll`, and all three take `language`. [Full-text search](/orm/reference/orm-client#full-text-search) on the ORM client reference covers the parsers, the options, and the index:
+This query returns each matching post with its rank and a headline that marks the matches with `<mark>`:
 
 ```ts title="src/search-posts.ts"
 const q = 'prisma orm';
@@ -941,7 +951,7 @@ const plan = db.sql.public.post
   .build();
 ```
 
-`cosineDistance(a, b)` compares two vector values and returns a `number`. It comes with pgvector, the PostgreSQL extension for vector columns, so it is there only if your contract composes pgvector. See [Extension types](/orm/contract-authoring/psl-syntax#extension-types).
+If your contract uses a pgvector type, such as `Embedding1536` in the example schema, `fns` also has `fns.cosineDistance(a, b)`. pgvector is the PostgreSQL extension for vector columns. `cosineDistance` returns the cosine distance between two vectors as a `number`. Each argument is a vector column or an array of numbers, as in `fns.cosineDistance(f.embedding, queryEmbedding)`. See [Extension types](/orm/contract-authoring/psl-syntax#extension-types).
 
 ### `fns.raw` and `.returns()`
 
diff --git a/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx b/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx
index cc85a5ceea..20cdad1487 100644
--- a/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx
+++ b/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx
@@ -622,7 +622,12 @@ Prepare a statement on the client itself.
 #### Remarks
 
 - The callback takes one argument, the declared `params`, as it does on `runtime.prepare(...)`. Build the query with the client's own `db.sql` or `db.orm`. Before `8.0.0-rc.12` the callback received a SQL builder as its first argument, `(sql, params)`; change such a callback to `(params)` and write `db.sql` where it wrote `sql`.
-- The callback can return a built SQL query, or an ORM query that ends in `.prepared.all()`, `.prepared.first()`, or `.prepared.aggregate(...)`. The ORM query is built once, and each `query(target, params)` call runs it with the new values and returns the same result shape as the ordinary call: rows for `all()`, a row or `null` for `first()`, and the aggregate object for `aggregate(...)`, or an array of groups after `groupBy(...)`.
+- The callback can return a built SQL query, or an ORM query that ends in `.prepared.all()`, `.prepared.first()`, or `.prepared.aggregate(...)`. `.prepared` always goes right before that last call, so a grouped aggregate is written `db.orm.public.Post.groupBy('userId').prepared.aggregate((agg) => ({ posts: agg.count() }))`.
+- The ORM query is built once. Each `query(target, params)` call runs it with the new values and returns what the same call without `.prepared` returns:
+  - `all()` returns the rows.
+  - `first()` returns a row, or `null`.
+  - `aggregate(...)` returns the aggregate object.
+  - `groupBy(...)` followed by `aggregate(...)` returns an array with one object per group.
 - `prepare()` starts the connection itself. Call `db.runtime()` for the runtime. `db.connect()` would throw an error whose `code` is `DRIVER.ALREADY_CONNECTED`, because `prepare()` already connected.
 
 #### Options
@@ -665,7 +670,7 @@ const countTags = await db.prepare({}, () =>
 const { total } = await countTags.query(db.runtime(), {});
 ```
 
-A prepared parameter works in `where(...)` filters, in `include(...)` refinements, and in `.limit(...)` and `.offset(...)`, so the same statement can page through results.
+In an ORM query, a prepared parameter works in `where(...)` filters, in the callback you pass to `include(...)`, and in `.limit(...)` and `.offset(...)`, so the same statement can page through results. Declare a page size or offset with a number type id that is not nullable, such as `{ take: 'pg/int4@1' }`, and pass `params.take` to `.limit(...)`. A nullable or text type id there is a type error.
 
 ### `PreparedStatement.query(target, params)`
 
diff --git a/apps/docs/content/docs/orm/release-status.mdx b/apps/docs/content/docs/orm/release-status.mdx
index fe236b694b..291fe07365 100644
--- a/apps/docs/content/docs/orm/release-status.mdx
+++ b/apps/docs/content/docs/orm/release-status.mdx
@@ -43,7 +43,7 @@ The two packages have different version numbers, and that is normal: they are re
 | `@prisma/orm-postgres` (the library) | `8.0.0-rc.12` |
 | `@prisma/orm-mongo` (the MongoDB library) | `8.0.0-rc.12` |
 
-Versions were checked on 24 September 2026; run `npm view prisma dist-tags`, `npm view @prisma/orm-postgres dist-tags`, and `npm view @prisma/orm-mongo dist-tags` for today's, since the command-line tool and the libraries are versioned separately.
+These were the `latest` versions on 24 September 2026. To see the `latest` version of each package today, run `npm view prisma dist-tags`, `npm view @prisma/orm-postgres dist-tags`, and `npm view @prisma/orm-mongo dist-tags`, and read the `latest` entry in each result. You need all three commands because the command-line tool and the libraries are versioned separately.
 
 `@prisma/client`, the library that Prisma ORM 7 apps import, stays at `7.10.0`, because it belongs to Prisma ORM 7 and is not part of Prisma ORM 8.
 

From d0d974efd25541dc9f9e23be9c4c35da90cbba50 Mon Sep 17 00:00:00 2001
From: "reviewer (Program)" <program@prisma.io>
Date: Fri, 25 Sep 2026 05:37:44 +0000
Subject: [PATCH 06/16] docs(docs): title the code blocks 89712ce added

The reader-review commit added seven code blocks without a title, which
raised the lint:code count from 6798 to 6805 while the PR body says the
change adds no untitled blocks. Title them the way each page titles its
neighbours: Terminal for commands, "Prisma ORM 8" on the migration page,
and file names elsewhere. lint:code is back at 6798, one below main.
---
 apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx     | 6 +++---
 apps/docs/content/docs/orm/fundamentals/transactions.mdx    | 2 +-
 apps/docs/content/docs/orm/middleware/built-in-lints.mdx    | 2 +-
 .../content/docs/orm/migrations/how-migrations-work.mdx     | 2 +-
 apps/docs/content/docs/orm/reference/orm-client.mdx         | 2 +-
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
index 601cbb2cea..77e0a7036a 100644
--- a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
+++ b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
@@ -26,7 +26,7 @@ It does not change `prisma/` or the database. [`orm init` on a Prisma ORM 7 proj
 
 In a new project, three commands set up Prisma ORM 8:
 
-```npm
+```npm title="Terminal"
 npm install --save-dev prisma
 npm install @prisma/orm-postgres
 npx prisma orm init --write-env
@@ -379,7 +379,7 @@ Prisma ORM 7 features that have no direct form in Prisma ORM 8, with what to do
 
 With `{ onConflict: "skip" }`, `.createAll(...)` and `.createAndCount(...)` skip each row that collides with any unique constraint on the table, and `createAll` returns only the rows the database wrote. To watch only one unique constraint, list its fields in `conflictOn`:
 
-```ts
+```ts title="Prisma ORM 8"
 const created = await db.orm.public.User.createAll(rows, {
   onConflict: "skip",
   conflictOn: ["email"],
@@ -395,7 +395,7 @@ Also not available today:
 - Nested writes other than `create`, `connect`, and `disconnect`: `connectOrCreate`, nested `update`, `updateMany`, `upsert`, `delete`, `deleteMany`, and `set` on a relation. Change the related rows through their own model instead, for example `db.orm.public.Post.where({ authorId }).updateAll({ ... })`, inside `db.transaction(...)` if it must be atomic.
 - The list filters `has`, `hasEvery`, `hasSome`, and `isEmpty` on `String[]` and other list fields. The fields themselves work, and you can filter on them with a raw SQL query written the same way as the [raw SQL example](#raw-sql) above. For a `Post` model with a `tags String[]` field:
 
-  ```ts
+  ```ts title="Prisma ORM 8"
   const post = db.sql.public.Post;
   const query = db.raw.sql`SELECT id FROM "Post" WHERE ${tag} = ANY(tags)`
     .returnsRow({ id: post.columns.id })
diff --git a/apps/docs/content/docs/orm/fundamentals/transactions.mdx b/apps/docs/content/docs/orm/fundamentals/transactions.mdx
index 0a8dbf103d..fcd1ab0e52 100644
--- a/apps/docs/content/docs/orm/fundamentals/transactions.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/transactions.mdx
@@ -174,7 +174,7 @@ const jane = await db.orm.users.where({ email: "jane@prisma.io" }).first();
 
 On MongoDB there is no schema segment in the path, and the property name is the collection name: the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. The example above assumes a `User` model mapped to the `users` collection, like the one below, so Prisma ORM reads it as `db.orm.users` and the driver code as `database.collection("users")`. Without the `@@map` line it would be `db.orm.User`.
 
-```prisma
+```prisma title="src/prisma/contract.prisma (excerpt)"
 model User {
   id    ObjectId @id @map("_id")
   email String   @unique
diff --git a/apps/docs/content/docs/orm/middleware/built-in-lints.mdx b/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
index 0c5f8433f8..480b419615 100644
--- a/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
+++ b/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
@@ -178,7 +178,7 @@ Sometimes you do mean to change every row, in a backfill script for example. `LI
 
 The first way is to write a `WHERE` clause that is true for every row, which states the intent in the query itself. On a table whose primary key is `id`, `id IS NOT NULL` is true for every row, and in the ORM API you write it with `isNotNull()`:
 
-```ts
+```ts title="scripts/backfill/delete-users.ts"
 await db.orm.public.User.where((u) => u.id.isNotNull()).deleteAndCount();
 ```
 
diff --git a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
index 4bb23281c7..355226f3ed 100644
--- a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
+++ b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
@@ -49,7 +49,7 @@ A table name is the model name exactly as written unless the model sets `@@map`,
 
 If you used a Prisma ORM 8 release before 8.0.0-rc.12, you have one more thing to do before you plan, because in those releases a model without `@@map` named its table with a lowercase first letter, such as `"userProfile"`. If your tables were created with those names, download the [`add-model-map` script](https://github.com/prisma/orm/blob/v8.0.0-rc.12/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.11-to-8.0.0-rc.12/scripts/psl-verbatim-table-names/add-model-map.mjs) and run it from your project root before you plan:
 
-```bash
+```bash title="Terminal"
 node <path to add-model-map.mjs> '**/*.prisma'
 ```
 
diff --git a/apps/docs/content/docs/orm/reference/orm-client.mdx b/apps/docs/content/docs/orm/reference/orm-client.mdx
index d41b6e8963..d020dda4de 100644
--- a/apps/docs/content/docs/orm/reference/orm-client.mdx
+++ b/apps/docs/content/docs/orm/reference/orm-client.mdx
@@ -1754,7 +1754,7 @@ PostgreSQL full-text search on a text field.
 - To add an operator to user text, such as `:*` for a prefix match while the user types, use the `tsquery` template tag from the same package: `` tsquery`${term}:*` ``. The tag puts each interpolated value in quotes as one search term, so the user's text cannot add operators of its own. Do not put quotes around the interpolation yourself.
 - `language` is the language whose rules PostgreSQL uses to match words, so that in `english` a search for `run` also finds `running`. It defaults to `english`. The method and the parser each take `language`, so pass the same value to both. The tag takes it as `` tsquery({ language: 'german' })`${input}:*` ``.
 
-  ```typescript
+  ```typescript title="src/search-posts.ts (excerpt)"
   const q = websearchToTsquery(input, { language: 'german' });
   const posts = await db.orm.public.Post.where((p) => p.title.fullTextMatches(q, { language: 'german' })).all();
   ```

From 743de8d29c05d7a0dc1f1b082fa6442b5cfb4fe7 Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Fri, 25 Sep 2026 07:43:16 +0200
Subject: [PATCH 07/16] docs(docs): fix the second reader-review round on the
 rc.12 pages

A second cold read of the rewritten passages found fewer and smaller problems. Each fix is checked against the ORM source.

- Middleware: the tenant-filter example now says it covers only a query whose own FROM names the table, and warns that rows loaded with include() or a join are not filtered.
- CLI: how to find the database state for `migration ref set db`, that `migration new --from` takes a hash but not a directory name, the full non-interactive `orm init` command, and where the marker is stored.
- Upgrade guides: the exact `orm init --from-prisma7-schema` command and where the guide continues after it; the prisma7Schema path stops after phase 3.
- Contract authoring: what each time type returns, the default string for a DateTime, and why `contract emit` needs Temporal for fixed date defaults.
- Reference: Prisma ORM 7 method names, what `conflictOn` does to other constraints, `@@fullTextIndex` syntax, and prepared `first()` results.
- Migrations: the commit list includes refs/ and extension folders, and each snapshot error names the command that gives it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 .../docs/(index)/prisma-orm/from-scratch.mdx  |  2 +-
 apps/docs/content/docs/cli/configuration.mdx  | 12 +++---
 apps/docs/content/docs/cli/contract-emit.mdx  |  4 +-
 apps/docs/content/docs/cli/contract-infer.mdx |  2 +-
 apps/docs/content/docs/cli/db-verify.mdx      |  6 ++-
 apps/docs/content/docs/cli/migration-new.mdx  |  6 +--
 apps/docs/content/docs/cli/migration-plan.mdx |  4 +-
 apps/docs/content/docs/cli/orm-init.mdx       | 12 ++++--
 .../guides/upgrade-prisma-orm/mongodb.mdx     |  4 +-
 .../guides/upgrade-prisma-orm/postgresql.mdx  | 36 ++++++++++--------
 .../docs/orm/coming-from-prisma-orm-7.mdx     | 20 +++++-----
 .../orm/contract-authoring/editor-support.mdx |  6 +--
 .../orm/contract-authoring/psl-syntax.mdx     | 32 +++++++++++-----
 .../the-contract-artifact.mdx                 |  2 +-
 .../contract-authoring/the-data-contract.mdx  |  4 +-
 .../typescript-schema-builder.mdx             | 13 ++++---
 .../content/docs/orm/data-modeling/index.mdx  |  4 +-
 .../docs/orm/extensions/using-extensions.mdx  |  4 +-
 .../orm/fundamentals/advanced-queries.mdx     |  2 +-
 .../docs/orm/fundamentals/transactions.mdx    | 18 ++++++++-
 .../docs/orm/fundamentals/writing-data.mdx    |  4 +-
 .../authoring-custom-middleware.mdx           | 30 +++++++++------
 .../docs/orm/middleware/built-in-budgets.mdx  | 19 +++++++++-
 .../docs/orm/middleware/built-in-lints.mdx    | 12 +++---
 .../orm/middleware/how-middleware-works.mdx   |  8 ++--
 .../orm/migrations/applying-a-migration.mdx   | 12 ++++--
 .../orm/migrations/editing-a-migration.mdx    | 20 ++++++----
 .../orm/migrations/generating-a-migration.mdx |  2 +-
 .../orm/migrations/how-migrations-work.mdx    | 25 +++++++-----
 .../orm/migrations/the-migration-graph.mdx    |  6 ++-
 .../content/docs/orm/reference/orm-client.mdx | 30 ++++++++++-----
 .../docs/orm/reference/sql-query-builder.mdx  | 38 ++++++++++++++++---
 .../reference/transactions-and-runtime.mdx    | 20 +++++-----
 apps/docs/content/docs/orm/release-status.mdx |  4 +-
 34 files changed, 274 insertions(+), 149 deletions(-)

diff --git a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
index 753cfb1744..b7b3c3fa1b 100644
--- a/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
+++ b/apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx
@@ -128,7 +128,7 @@ App space
 ✔ Advanced ref "db" → f4e1954fd8bed87828d13c3f1a02164dc9796ef1af76ed6f98184c01263169c5
 ```
 
-The `marker` line in the output is the record that signing stores in the database: the hash that identifies the version of the contract the database now matches. `db init` also writes `migrations/app/refs/db.json` and a snapshot of the contract under `migrations/snapshots/`; commit both. If the command fails with `DRIVER.CONNECTION_FAILED`, `DATABASE_URL` in `.env` is wrong or the database is not reachable. A `SECURITY WARNING` about SSL modes comes from the `pg` driver and does not stop the command; change `sslmode=require` to `sslmode=verify-full` in `.env` to silence it.
+The `marker` line in the output is the record that signing stores in the database: the hash that identifies the version of the contract the database now matches. `db init` also writes `migrations/app/refs/db.json`, called the `db` ref: a file that records which contract version your development database is at, so that `migration plan` in step 6 knows where to start. The `Advanced ref "db"` line in the output is `db init` writing it. Commit it, together with the snapshot of the contract that `db init` writes under `migrations/snapshots/`. If the command fails with `DRIVER.CONNECTION_FAILED`, `DATABASE_URL` in `.env` is wrong or the database is not reachable. A `SECURITY WARNING` about SSL modes comes from the `pg` driver and does not stop the command; change `sslmode=require` to `sslmode=verify-full` in `.env` to silence it.
 
 ## 5. Write and read data
 
diff --git a/apps/docs/content/docs/cli/configuration.mdx b/apps/docs/content/docs/cli/configuration.mdx
index f239a362c0..82230096bc 100644
--- a/apps/docs/content/docs/cli/configuration.mdx
+++ b/apps/docs/content/docs/cli/configuration.mdx
@@ -29,9 +29,9 @@ export default definePrismaConfig({
 
 For MongoDB projects, import the section helper from `@prisma/orm-mongo/config` instead. Both packages export this helper as `defineConfig`, and the examples on this page rename it to `ormConfig` when they import it.
 
-If you set up Prisma ORM 8 with a release candidate before `8.0.0-rc.12`, your config may import `defineConfig` from `@prisma/cli-engine`, the package the `prisma` CLI is built on. That was the old name of `definePrismaConfig`, and `@prisma/cli-engine` 0.6.1, which `8.0.0-rc.12` requires, no longer exports it, so the config fails to load. Import `definePrismaConfig` in its place and call it where you called `defineConfig`. You can import it from `prisma/config` or from `@prisma/cli-engine`, because `prisma/config` re-exports the same function.
+If you set up Prisma ORM 8 with a release candidate before `8.0.0-rc.12`, your config may import `defineConfig` from `@prisma/cli-engine`, the package the `prisma` CLI is built on. `8.0.0-rc.12` requires `@prisma/cli-engine` 0.6.1, which removed that export, so the config fails to load. Rename that import and its call to `definePrismaConfig`, which is the same function under its new name. You can import it from `prisma/config` or from `@prisma/cli-engine`, because `prisma/config` re-exports it. Leave the `defineConfig` import from `@prisma/orm-postgres/config` or `@prisma/orm-mongo/config` as it is: that is the helper for the `orm` section, and its name has not changed.
 
-[`orm init`](/cli/orm-init) writes this file for you. Pass `--config` when your config file is not in the directory you run the command from:
+[`orm init`](/cli/orm-init) writes this file for you. Without `--config`, the CLI looks for `prisma.config.ts` in the directory you run the command from and in the directories above it, as [How the CLI finds the config](#how-the-cli-finds-the-config) explains. Pass `--config` to use a config file in another place, such as a subdirectory:
 
 ```npm
 npx prisma contract emit --config ./config/prisma.config.ts
@@ -41,7 +41,7 @@ npx prisma contract emit --config ./config/prisma.config.ts
 
 The CLI looks for `prisma.config.ts` in the current directory, or starts from the file you pass to `--config`. It then looks in each parent directory, up to the root of the repository, which is the first directory that has a `.git` entry. If neither the starting directory nor any directory above it has a `.git` entry, the CLI reads only the first file.
 
-The CLI combines the files it finds one section at a time. Inside a section such as `orm`, each top-level key, such as `contract`, `db`, or `migrations`, comes whole from the nearest file that sets it, and the keys nested inside it are not combined. So if a config higher up sets `db.connection` and your project's config sets only `contract`, the CLI uses your `contract` and the other file's `db`. `ormConfig` always sets `extensions`, to an empty list when you leave it out, so a project's `ormConfig` replaces any extension list set higher up.
+The CLI combines the files it finds one section at a time. Inside a section such as `orm`, each top-level key, such as `contract`, `db`, or `migrations`, comes whole from the nearest file that sets it, and the keys nested inside it are not combined. So if a config higher up sets `db.connection` and your project's config sets only `contract`, the CLI uses your `contract` and the other file's `db`. Extensions are the exception: a project config that calls `ormConfig` does not inherit them from a config higher up, even when it leaves `extensions` out. List the extensions your contract uses in each project's own config.
 
 A project inside a larger repository therefore inherits any setting its own config leaves out from a `prisma.config.ts` higher up. To stop that, add `parent: false` to the project's config. The search then ends at that file:
 
@@ -111,9 +111,11 @@ export default definePrismaConfig({
 });
 ```
 
-`prisma7Schema` takes one schema file, or a directory of `.prisma` files as Prisma ORM 7 reads it. `contract emit` writes `contract.json` and `contract.d.ts` into the directory that holds the schema, here `prisma/`, unless you set `output`. Prisma ORM 7 keeps owning the database and its migrations, and you run its commands as `prisma7`, the Prisma ORM 7 CLI that [`orm init --from-prisma7-schema`](/cli/orm-init#on-a-prisma-orm-7-project) installs next to Prisma ORM 8. After each Prisma ORM 7 migration, whether you ran `npx prisma7 migrate dev` or `npx prisma7 migrate deploy`, run `npx prisma contract emit` and then [`npx prisma db sign`](/cli/db-sign). `db sign` checks that the database matches the contract and then records that in the database, without changing your tables.
+`prisma7Schema` takes one schema file, or a directory of `.prisma` files as Prisma ORM 7 reads it. It reads every `.prisma` file it is given, so these files do not need the `// use prisma-8` first line. `contract emit` writes `contract.json` and `contract.d.ts` into the directory that holds the schema, here `prisma/`, unless you set `output`. Prisma ORM 7 keeps owning the database and its migrations, and you run its commands as `prisma7`, the Prisma ORM 7 CLI that [`orm init --from-prisma7-schema`](/cli/orm-init#on-a-prisma-orm-7-project) installs next to Prisma ORM 8.
 
-`contract emit` fails on any part of the schema that Prisma ORM 8 cannot represent exactly, such as a `view` block, `Unsupported(...)`, or `relationMode = "prisma"`. The error names the file and the line, and says how to change the Prisma ORM 7 schema so that the part is gone. Prisma ORM 8 has no views, so for a `view` block the error suggests removing the view or replacing it with a model over the table the view reads. `orm init --from-prisma7-schema` writes this config for you.
+Once the config is in place, run `npx prisma contract emit` and then [`npx prisma db sign`](/cli/db-sign). `db sign` checks that the database matches the contract and then records that in the database, without changing your tables. Run both commands again after each Prisma ORM 7 migration, whether you ran `npx prisma7 migrate dev` or `npx prisma7 migrate deploy`, so that the record names the new contract.
+
+`contract emit` fails on any part of the schema that Prisma ORM 8 cannot represent exactly, such as a `view` block, `Unsupported(...)`, or `relationMode = "prisma"`. The error names the file and the line and suggests an edit to the Prisma ORM 7 schema. When that edit would also change the database on the next Prisma ORM 7 migration, the error says so. For example, removing an `Unsupported(...)` field drops its column, so for that field the error suggests adding `@@ignore` to the model instead, which leaves the next Prisma ORM 7 migration empty but removes the model from the Prisma ORM 7 client. Prisma ORM 8 has no views, so for a `view` block the error suggests removing the view or replacing it with a model over the table the view reads. `orm init --from-prisma7-schema` writes this config for you.
 
 ## Emit-only config
 
diff --git a/apps/docs/content/docs/cli/contract-emit.mdx b/apps/docs/content/docs/cli/contract-emit.mdx
index 0c04d75ba6..00d0a75f27 100644
--- a/apps/docs/content/docs/cli/contract-emit.mdx
+++ b/apps/docs/content/docs/cli/contract-emit.mdx
@@ -10,7 +10,7 @@ metaDescription: Learn how to emit contract.json and contract.d.ts for Prisma OR
 
 The command is offline. It does not need a database connection.
 
-A PSL contract source can be one file or a glob that matches several files; see [Split the schema across several files](/cli/configuration#split-the-schema-across-several-files). `contract emit` reads only the `.prisma` files whose first line is `// use prisma-8`, and skips any other file without a warning. When no file starts with that line, it fails with `CONTRACT.SOURCE_LOAD_FAILED` and the finding `PSL_NO_OPTED_IN_SCHEMA_FILES`.
+A Prisma schema source can be one `.prisma` file or a glob that matches several files; see [Split the schema across several files](/cli/configuration#split-the-schema-across-several-files). `contract emit` reads only the `.prisma` files whose first line is `// use prisma-8`, and skips any other file without a warning. When no file starts with that line, it fails with `CONTRACT.SOURCE_LOAD_FAILED` and reports the problem with the code `PSL_NO_OPTED_IN_SCHEMA_FILES`.
 
 ## Usage
 
@@ -35,7 +35,7 @@ The command emits:
 
 Do not edit these files by hand. Re-run `contract emit` after changing the contract source or extension pack list. The first emit after you upgrade to `8.0.0-rc.12` reorders the entries in `contract.d.ts` to follow the order in `contract.json`, which needs no change to your code.
 
-When the contract source cannot be read, the command fails with `CONTRACT.SOURCE_LOAD_FAILED` and prints each finding, meaning each problem it found in the source, with the file and line where it knows them. In `--json` output, the findings are the entries of the `envelope.diagnostics` array in the final `result` event, next to `envelope.error`. Each entry has a `code`, a `summary`, and, where known, `where.path` and `where.line`. A finding whose own code has no dot, such as `PSL_NO_OPTED_IN_SCHEMA_FILES`, has the `code` `CONTRACT.SOURCE_DIAGNOSTIC` and keeps its own code in `meta.code`.
+When the contract source cannot be read, the command fails with `CONTRACT.SOURCE_LOAD_FAILED` and prints each finding, meaning each problem it found in the source, with the file and line where it knows them. In `--json` output, the findings are the entries of the `envelope.diagnostics` array in the final `result` event, next to `envelope.error`. Each entry has a `code`, a `summary`, and, where known, `where.path` and `where.line`. If an entry's `code` is `CONTRACT.SOURCE_DIAGNOSTIC`, the code of the specific problem, such as `PSL_NO_OPTED_IN_SCHEMA_FILES`, is in its `meta.code`.
 
 ## Run it automatically
 
diff --git a/apps/docs/content/docs/cli/contract-infer.mdx b/apps/docs/content/docs/cli/contract-infer.mdx
index 961f4e234c..7099108188 100644
--- a/apps/docs/content/docs/cli/contract-infer.mdx
+++ b/apps/docs/content/docs/cli/contract-infer.mdx
@@ -45,7 +45,7 @@ Inference gives you a starting point, not a finished design. Review:
 
 The file starts with `// use prisma-8`, because `contract emit` reads only `.prisma` files that start with that line. Each model is named after its table, and gets `@@map` only when the table name differs from the model name: a table `User` becomes `model User`, and a table `user_profile` becomes `model UserProfile` with `@@map("user_profile")`.
 
-Every column default is written in a form `contract emit` accepts, so you can emit the file without editing it. [Default values](/orm/contract-authoring/psl-syntax#default-values) shows those forms. A nullable list column is written `Type[]?`.
+Every column default is written in a form `contract emit` accepts, so you can emit the file without editing it. [Default values](/orm/contract-authoring/psl-syntax#default-values) shows those forms. A list column that allows `NULL` is written `Type[]?`, and a list column that is `NOT NULL` is written `Type[]`.
 
 If you keep an inferred contract in version control, running `contract infer` again after an upgrade can write the same database differently, so review the diff before you commit it.
 
diff --git a/apps/docs/content/docs/cli/db-verify.mdx b/apps/docs/content/docs/cli/db-verify.mdx
index 0807d698f0..eaebf0e349 100644
--- a/apps/docs/content/docs/cli/db-verify.mdx
+++ b/apps/docs/content/docs/cli/db-verify.mdx
@@ -65,6 +65,8 @@ Fix the database or contract, emit again if needed, then verify again.
 
 When a column default is a literal value, `db verify` reads it as a value before it compares it with your contract, so the casts PostgreSQL adds when it prints the default do not cause a difference. This covers numbers such as `'-1'::integer` and `(5)::smallint`, text and enum values, including an enum value cast to a type in another PostgreSQL schema, `timestamp` values, `true`, `false`, `NULL`, JSON, and lists written as `'{...}'` or `ARRAY[...]`. `db verify` also recognizes `now()`, `clock_timestamp()`, `gen_random_uuid()`, and a sequence default, which it treats as `autoincrement()`.
 
-Any other default is a SQL expression. `db verify` cannot work out whether two SQL expressions give the same value, so it compares their text, ignoring letter case and spaces. PostgreSQL often rewrites an expression when it stores it, for example by adding casts, so write a `sql` default in your contract the way PostgreSQL stores it. To see that form, run `npx prisma contract infer --output ./inferred.prisma` and copy the column's `@default` from that file.
+Any other default is a SQL expression, which you write in your contract as a `sql` default, such as ``@default(sql`(now() + '00:03:00'::interval)`)``. [Default values](/orm/contract-authoring/psl-syntax#default-values) shows how to write one. `db verify` cannot work out whether two SQL expressions give the same value, so it compares their text, ignoring letter case and spaces. PostgreSQL often rewrites an expression when it stores it, for example by adding casts, so write a `sql` default in your contract the way PostgreSQL stores it. To see that form, run `npx prisma contract infer --output ./inferred.prisma` and copy the column's `@default` from that file.
 
-`db verify` reads the database with the time zone set to UTC and dates in ISO format, whatever the server or your database role sets. It compares check constraints and the `WHERE` clause of a partial index as exact text. So if your contract was inferred before `8.0.0-rc.12` from a server that was not set to UTC, a `timestamptz` value inside a check constraint or an index's `WHERE` clause can be reported as a difference. Copy the new text from a fresh `npx prisma contract infer --output ./inferred.prisma` into your contract, emit the contract, and run `db sign`.
+Check constraints and the `WHERE` clause of a partial index are compared more strictly than `sql` defaults: their text must match exactly, including letter case and spaces.
+
+If `db verify` reports a difference in a `timestamptz` value inside a check constraint or a partial index's `WHERE` clause, check whether your contract was inferred before `8.0.0-rc.12` from a server that was not set to UTC. `db verify` reads the database with the time zone set to UTC and dates in ISO format, whatever the server or your database role sets, so a value that your contract has in another time zone no longer matches as text. To fix it, copy the new text from a fresh `npx prisma contract infer --output ./inferred.prisma` into your contract, emit the contract, and run `db sign`.
diff --git a/apps/docs/content/docs/cli/migration-new.mdx b/apps/docs/content/docs/cli/migration-new.mdx
index 634c13af9d..72826fdadb 100644
--- a/apps/docs/content/docs/cli/migration-new.mdx
+++ b/apps/docs/content/docs/cli/migration-new.mdx
@@ -25,7 +25,7 @@ npx prisma migration new --name split-name
 | `--config <path>` | Read this config file instead of `./prisma.config.ts`. |
 | `--json` | Prints a machine-readable result. |
 
-`migration new` refuses `--from` when `migrations/app/` has no migrations, and refuses a prefix that matches more than one migration. Run `npx prisma migration list` to see the hashes of your migrations.
+`migration new --from` takes only a hash or a unique prefix of one. Unlike [`migration plan --from`](/cli/migration-plan#options), it does not accept a migration directory name or a ref name. It refuses `--from` when `migrations/app/` has no migrations, and refuses a prefix that matches more than one migration. Run `npx prisma migration list` to see the hashes of your migrations.
 
 ## Where it starts
 
@@ -33,8 +33,8 @@ Without `--from`, `migration new` picks its starting point the way [`migration p
 
 - When the `db` ref exists and `migrations/app/` has migrations, it starts from the `db` ref.
 - When there are no migrations and no `db` ref, it starts from an empty database.
-- When migrations exist but there is no `db` ref, it refuses with `MIGRATION.PLAN_ORIGIN_UNKNOWN`. Pass `--from` with the `to` hash of the migration to build on, or point the `db` ref at the state your database is on with `npx prisma migration ref set db <contract>`, where `<contract>` is a hash or a migration directory name.
-- When the `db` ref exists but there are no migrations, it refuses with `MIGRATION.HASH_NOT_IN_GRAPH`. Run `migration plan` first: it writes a [baseline migration](/orm/migrations/the-migration-graph#baselines), a first migration from an empty database to the contract state the `db` ref names, and after that `migration new` can build on it.
+- When migrations exist but there is no `db` ref, it refuses with `MIGRATION.PLAN_ORIGIN_UNKNOWN`. Pass `--from` with the `to` hash of the migration to build on, or point the `db` ref at the state your database is on. To find that state, run `npx prisma migration status --db "$DATABASE_URL" --json`: the `currentContract` of the `app` entry in `result.spaces` is the hash of the contract state your database matches. Then run `npx prisma migration ref set db <contract>`, where `<contract>` is that hash or the directory name of the migration that ends at it.
+- When the `db` ref exists but there are no migrations, it refuses with `MIGRATION.HASH_NOT_IN_GRAPH`, because there is no migration yet that ends at the state the `db` ref names. Run `migration plan` first. It writes a [baseline migration](/orm/migrations/the-migration-graph#baselines), a migration from an empty database to that state, and then `migration new` can start from it. `migration plan` reads that state from the copy saved under `migrations/snapshots/` by the command that set the `db` ref, and if the copy is missing, it fails and asks you to restore `migrations/snapshots/` from version control.
 
 Before `8.0.0-rc.12`, `migration new` started from the newest migration. Scripts that relied on that should pass `--from` with the newest migration's `to` hash.
 
diff --git a/apps/docs/content/docs/cli/migration-plan.mdx b/apps/docs/content/docs/cli/migration-plan.mdx
index 5488ee2ab9..44a619f9aa 100644
--- a/apps/docs/content/docs/cli/migration-plan.mdx
+++ b/apps/docs/content/docs/cli/migration-plan.mdx
@@ -21,9 +21,9 @@ Keep the `db` ref current and you never see the refusal. [`db init`](/cli/db-ini
 
 When `migrations/app/` is empty and the `db` ref points at a contract whose snapshot is stored under `migrations/snapshots/`, one `migration plan` run writes a baseline package from nothing to the ref's contract and, when your emitted contract differs from the ref's, a second package with the delta. Expect one or two new directories in `git status`. The baseline is never replayed against a database that already carries a marker, because the runner starts from the marker and only applies edges past it.
 
-If the baseline would contain destructive operations, which remove data when the migration is applied, `migration plan` lists them and asks you to confirm by typing the name of the directory you run the command in, usually your project directory, before it writes the baseline. In a script, pass that name instead, for example `--no-interactive --confirm my-app`. [`db update`](/cli/db-update) asks for consent the same way, with the database name.
+If the baseline would contain destructive operations, which remove data when the migration is applied, `migration plan` lists them and asks you to confirm by typing the name of the directory you run the command in, usually your project directory, before it writes the baseline. In a script, pass that name instead, for example `--no-interactive --confirm my-app`. [`db update`](/cli/db-update) asks for consent the same way, with the database name. Only the baseline needs this confirmation: `migration plan` writes the second package without asking, and its output marks each destructive operation in that package and warns that it may cause data loss.
 
-When the `db` ref points at a contract state that already has a migration leading away from it, planning from the ref starts a second branch in the migration history. This happens, for example, after `db migrate` without `--advance-ref db`, which applies migrations but does not update the `db` ref. `migration plan` still writes the migration and prints a warning. To build on the newest migration instead, pass `--from` with that migration's directory name.
+When the `db` ref points at a contract state that already has a migration starting from it, `migration plan` writes a second migration that starts from the same state, so the [migration history](/orm/migrations/the-migration-graph) splits into two branches. This happens, for example, after `db migrate` without `--advance-ref db`, which applies migrations but does not update the `db` ref. `migration plan` still writes the migration and prints a warning. A database that has already run the existing migration then has no migration leading to your new contract, so `db migrate` on that database fails with `MIGRATION.PATH_UNREACHABLE`. To build on the newest migration instead, pass `--from` with that migration's directory name.
 
 The command is offline. It does not need a database connection.
 
diff --git a/apps/docs/content/docs/cli/orm-init.mdx b/apps/docs/content/docs/cli/orm-init.mdx
index 2c77222db2..9fceed4586 100644
--- a/apps/docs/content/docs/cli/orm-init.mdx
+++ b/apps/docs/content/docs/cli/orm-init.mdx
@@ -67,16 +67,22 @@ A plain `orm init` offers the same setup when it finds a Prisma ORM 7 config, or
 
 First, `orm init` installs `@prisma/orm-postgres` and `dotenv`, adding them to `package.json` if they are not there yet, and uses the installed package to check that Prisma ORM 8 can read the schema. Apart from that install, it changes nothing until the check passes. A schema it cannot read, for example one with a `view` block, stops the command with `CLI.INIT_PRISMA7_SCHEMA_REFUSED`, which lists each problem with its line and the Prisma ORM 7 edit that removes it, and gives the command that removes the packages it just added.
 
-When the check passes, `orm init` asks you to confirm by typing the name of the directory you run it in. In a script, pass that name instead, for example `--confirm my-app`. Then it:
+When the check passes, `orm init` asks you to confirm by typing the name of the directory you run it in. In a script, where nobody can type, pass that name with `--confirm`, and add `--no-interactive` so that any other question takes its default answer. For a project in a directory named `my-app`:
+
+```npm title="Terminal"
+npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma --no-interactive --confirm my-app
+```
+
+After you confirm, `orm init`:
 
 - renames the Prisma ORM 7 config to `prisma7.config.ts` and points its import at `@prisma/prisma7/config`
 - changes every `package.json` script that runs `prisma` to run `prisma7`
 - installs the latest Prisma ORM 7 release as `@prisma/prisma7`, next to `prisma@latest`
 - writes `prisma.config.ts` with `contract: prisma7Schema("<schema path>")`, plus `src/prisma/db.ts` and `prisma-8.md`
 
-It does not write a starter contract, and it changes nothing in `prisma/` or in the database. Prisma ORM 7 keeps owning the schema and its migrations. From now on, `prisma` runs Prisma ORM 8 and `prisma7` runs Prisma ORM 7, so a Prisma ORM 7 command such as `migrate dev` becomes `npx prisma7 migrate dev`. Your application keeps using the Prisma ORM 7 client until you move its routes, one at a time, to the Prisma ORM 8 client in `src/prisma/db.ts`. If your `package.json` listed `@prisma/client` below version 7, `orm init` also installs `@prisma/client@7` to match `@prisma/prisma7`, so run `npx prisma7 generate` afterwards.
+It does not write a starter contract, and it changes nothing in `prisma/` or in the database. Prisma ORM 7 keeps owning the schema and its migrations. From now on, `prisma` runs Prisma ORM 8 and `prisma7` runs Prisma ORM 7, so a Prisma ORM 7 command such as `migrate dev` becomes `npx prisma7 migrate dev`. Your application keeps using the Prisma ORM 7 client until you move its routes, one at a time, to the Prisma ORM 8 client in `src/prisma/db.ts`. If the project still uses a Prisma ORM version before 7, so that your `package.json` lists `@prisma/client` below version 7, `orm init` upgrades `@prisma/client` to version 7, because the Prisma ORM 7 CLI it installs needs a client of the same major version. Run `npx prisma7 generate` afterwards to generate the upgraded client.
 
-To finish, set `DATABASE_URL` and run `npx prisma db sign` once. [`db sign`](/cli/db-sign) checks that the database matches the contract and then writes the marker, a record in the database of which contract it matches, without changing your tables. After each Prisma ORM 7 migration, whether you ran `npx prisma7 migrate dev` or `npx prisma7 migrate deploy`, run `npx prisma contract emit` and then `npx prisma db sign` again. [Configuration](/cli/configuration#use-a-prisma-orm-7-schema) explains `prisma7Schema`, and [the upgrade guide](/guides/upgrade-prisma-orm/postgresql) covers the rest of the move.
+To finish, set `DATABASE_URL` and run `npx prisma db sign` once. [`db sign`](/cli/db-sign) checks that the database matches the contract and then writes the marker, a row that records which contract the database matches. The row goes in the table `prisma_contract.marker`, which the first `db sign` creates in a PostgreSQL schema of its own named `prisma_contract`, so your own tables do not change. After each Prisma ORM 7 migration, whether you ran `npx prisma7 migrate dev` or `npx prisma7 migrate deploy`, run `npx prisma contract emit` and then `npx prisma db sign` again. [Configuration](/cli/configuration#use-a-prisma-orm-7-schema) explains `prisma7Schema`, and [the upgrade guide](/guides/upgrade-prisma-orm/postgresql) covers the rest of the move.
 
 ## Examples
 
diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx
index c7b4c575fc..f033ac4839 100644
--- a/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx
+++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/mongodb.mdx
@@ -24,7 +24,7 @@ Install the companion [prisma-mongodb-upgrade](https://github.com/prisma/skills/
 
 :::info
 
-This guide is written for `@prisma/orm-mongo@8.0.0-rc.12`. MongoDB support in Prisma ORM 8 still changes between release candidates, so a newer version may behave differently from what this guide shows.
+Install the `latest` version of `@prisma/orm-mongo`, which is what `orm init` in step 1 does. This guide was written for `8.0.0-rc.12`, and MongoDB support in Prisma ORM 8 still changes between release candidates, so a newer version may behave differently from what this guide shows. To see which version you have, run `npm ls @prisma/orm-mongo`.
 
 :::
 
@@ -122,7 +122,7 @@ You can use the [prisma-mongodb-upgrade](https://github.com/prisma/skills/tree/m
 
 | Concept | v6 (`schema.prisma`) | Prisma ORM 8 (`contract.prisma`) |
 |---------|----------------------|---------------------------------|
-| First line | (nothing) | `// use prisma-8`. `contract emit` reads only the files that start with it |
+| First line | (nothing) | `// use prisma-8`. Without it, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED` |
 | Datasource | `datasource db { provider = "mongodb" }` | no `provider` (configured in `prisma.config.ts`) |
 | Id field | `id String @id @default(auto()) @map("_id") @db.ObjectId` | `id ObjectId @id @map("_id")` |
 | Embedded document | `type Address { ... }` | `type Address { ... }` (unchanged) |
diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
index c58e2f3acc..8d49a7af7c 100644
--- a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
+++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
@@ -14,7 +14,7 @@ The guide covers **PostgreSQL only**. Guidance for other databases will follow.
 
 :::info
 
-This guide targets `prisma@latest`, `@prisma/orm-postgres@8.0.0-rc.12`, and `@prisma/prisma7@7.10.0`, and the example app in step 1.1 starts on Prisma ORM 7.10.0. `prisma@latest` is the Prisma ORM 8 CLI, `8.0.0-rc.17` at the time of writing. It is versioned and released separately from the ORM packages, so its version number will not match theirs. It installs `@prisma/cli-engine@0.6.1` as its own dependency, so you do not install that package yourself.
+Step 2.1 installs the `latest` version of both Prisma ORM 8 packages: `prisma`, the Prisma ORM 8 CLI, and `@prisma/orm-postgres`. This guide was written with `prisma` at `8.0.0-rc.17` and `@prisma/orm-postgres` at `8.0.0-rc.12`. The CLI is released separately from the ORM packages, so its version number will not match theirs. Prisma ORM 7 stays at `7.10.0`: the example app in step 1.1 starts on it, and step 1.2 installs `@prisma/prisma7@7.10.0`.
 
 :::
 
@@ -259,17 +259,9 @@ Both configs point at the **same** `DATABASE_URL`. Everything else is separate:
 
 Because the config carries the connection, the Prisma ORM 8 CLI commands below don't need a `--db` flag.
 
-### 2.3. Infer the contract from the live database
-
-Prisma ORM 8 describes your schema as a [contract](/orm/contract-authoring/the-data-contract). Generate it from the database Prisma ORM 7 built:
-
-```npm
-npx prisma contract infer --output prisma8/contract.prisma
-```
-
 :::tip[Read the Prisma ORM 7 schema instead]
 
-Prisma ORM 8 can also read `prisma/schema.prisma` directly as its contract, so you keep one schema file while Prisma ORM 7 owns migrations. On this path `schema.prisma` does not need a `// use prisma-8` line. Skip steps 2.3 and 2.4, and change two lines in `prisma.config.ts`:
+Instead of generating a contract file in steps 2.3 and 2.4, Prisma ORM 8 can read `prisma/schema.prisma` directly as its contract, so you keep one schema file while Prisma ORM 7 owns migrations. `schema.prisma` does not need the `// use prisma-8` first line that a contract file written for Prisma ORM 8 starts with (step 2.4 shows one). Skip steps 2.3 and 2.4, and change two lines in the `prisma.config.ts` you just wrote:
 
 ```typescript title="prisma.config.ts"
 import "dotenv/config";
@@ -289,14 +281,28 @@ export default definePrismaConfig({
 });
 ```
 
-After step 2.5, run `npx prisma db sign`, which checks that the database matches the contract Prisma ORM 8 read from `schema.prisma` and records in the database that it does. Step 4.1 describes `db sign` in full. Because Prisma ORM 7 keeps changing the database on this path, run `npx prisma contract emit` and then `npx prisma db sign` again after each `prisma7 migrate dev`. [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema) lists the parts of a Prisma ORM 7 schema that Prisma ORM 8 cannot read.
+After step 2.5, run `npx prisma db sign`. [`db sign`](/cli/db-sign) checks that the database matches the contract Prisma ORM 8 read from `schema.prisma` and records in the database that it does. On this path it does not hand migrations to Prisma ORM 8: Prisma ORM 7 keeps planning and applying them, so after each `prisma7 migrate dev`, run `npx prisma contract emit` and then `npx prisma db sign` again. If you emit without signing, the Prisma ORM 8 client still runs queries, but `npx prisma db verify` reports that the contract no longer matches the one recorded in the database. [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema) lists the parts of a Prisma ORM 7 schema that Prisma ORM 8 cannot read.
+
+If you have not started phase 1 yet, one command does phase 1 and this setup for you:
+
+```npm
+npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma
+```
 
-If you have not started phase 1 yet, [`prisma orm init --from-prisma7-schema prisma/schema.prisma`](/cli/orm-init#on-a-prisma-orm-7-project) does phase 1 and this setup in one command.
+Write `prisma@latest`, because in a Prisma ORM 7 project `npx prisma` runs version 7. The command moves Prisma ORM 7 to the `prisma7` command and `prisma7.config.ts`, installs the Prisma ORM 8 packages, writes `prisma.config.ts` and a Prisma ORM 8 client in `src/prisma/db.ts`, and emits the contract. [`orm init` on a Prisma ORM 7 project](/cli/orm-init#on-a-prisma-orm-7-project) lists what it changes. Then run `npx prisma db sign` and continue with phase 3, using the `db` client from `src/prisma/db.ts` instead of adding one to `src/db.ts` in step 3.1.
 
-Phase 4 is written for the inferred `prisma8/contract.prisma`, and does not yet cover a project that reads `schema.prisma` through `prisma7Schema(...)`.
+On this path, stop after phase 3: you can move every route to Prisma ORM 8, but Prisma ORM 7 keeps owning migrations, because phase 4 is written for the inferred `prisma8/contract.prisma` and does not yet cover a project that reads `schema.prisma` through `prisma7Schema(...)`.
 
 :::
 
+### 2.3. Infer the contract from the live database
+
+Prisma ORM 8 describes your schema as a [contract](/orm/contract-authoring/the-data-contract). Generate it from the database Prisma ORM 7 built:
+
+```npm
+npx prisma contract infer --output prisma8/contract.prisma
+```
+
 ### 2.4. Edit the inferred contract
 
 `contract infer` reads every table in the database, so it also writes a `PrismaMigrations` model for `_prisma_migrations`, the table where Prisma ORM 7 records which migrations it has applied. Delete that model from the contract, because Prisma ORM 8 must not manage the table. The table itself stays in the database, and an extra table that the contract does not describe is fine.
@@ -328,7 +334,7 @@ model Post {
 }
 ```
 
-Keep `// use prisma-8` as the first line of `prisma8/contract.prisma`, because `contract emit` reads only the `.prisma` files that start with it. A `schema.prisma` that Prisma ORM 8 reads through `prisma7Schema(...)`, as in the tip under step 2.3, does not need the line.
+Keep `// use prisma-8` as the first line of `prisma8/contract.prisma`. `contract emit` reads only `.prisma` files that start with this line, and this is the only file in your contract, so without it `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`. A `schema.prisma` that Prisma ORM 8 reads through `prisma7Schema(...)`, as in the tip at the end of step 2.2, does not need the line.
 
 ### 2.5. Emit the contract artifacts
 
@@ -340,7 +346,7 @@ npx prisma contract emit
 
 ### 2.6. Include the generated types
 
-The Prisma ORM 8 client imports `contract.json` with the `with { type: "json" }` import attribute. This syntax requires TypeScript 5.3 or later and a `module` setting that supports import attributes. The example project uses `"module": "nodenext"`, which supports them. `"esnext"` with `"moduleResolution": "bundler"` also works.
+The Prisma ORM 8 client imports `contract.json` with the `with { type: "json" }` import attribute, so besides TypeScript 5.9 from the prerequisites, you need a `module` setting that supports import attributes. The example project uses `"module": "nodenext"`, which supports them. `"esnext"` with `"moduleResolution": "bundler"` also works.
 
 Enable `resolveJsonModule` so TypeScript types the imported JSON, and include the generated declarations in the program:
 
diff --git a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
index 601cbb2cea..6ce53f3538 100644
--- a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
+++ b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
@@ -16,13 +16,13 @@ All examples use PostgreSQL.
 
 If you are adding Prisma ORM 8 to an application that runs Prisma ORM 7, do not run the new-project commands further down in that project, because `npm install prisma` installs version 8 in place of the version 7 command-line tool. Follow [Migrate from Prisma ORM 7 to 8](/guides/upgrade-prisma-orm/postgresql) instead. It runs both versions side by side against your existing database without changing its data, and ends with Prisma ORM 8 managing its migrations.
 
-On PostgreSQL, the following command does the guide's first phase for you, and sets up Prisma ORM 8 to read your `schema.prisma` as its contract. `schema.prisma` does not need a `// use prisma-8` line for this.
+On PostgreSQL, the following command moves Prisma ORM 7 to the `prisma7` command and `prisma7.config.ts`, and sets up Prisma ORM 8 to read your `schema.prisma` as its contract:
 
 ```npm
 npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma
 ```
 
-It does not change `prisma/` or the database. [`orm init` on a Prisma ORM 7 project](/cli/orm-init#on-a-prisma-orm-7-project) lists what it changes, and the guide covers the rest of the move.
+It does not change `prisma/` or the database. [`orm init` on a Prisma ORM 7 project](/cli/orm-init#on-a-prisma-orm-7-project) lists what it changes. Then run `npx prisma db sign` and continue with [phase 3 of the guide](/guides/upgrade-prisma-orm/postgresql#3-migrate-one-route), moving routes one at a time to the client in `src/prisma/db.ts`. The guide's phase 4, where Prisma ORM 8 takes over migrations, does not yet cover this setup, so Prisma ORM 7 keeps owning your migrations.
 
 In a new project, three commands set up Prisma ORM 8:
 
@@ -45,7 +45,7 @@ The biggest visible change is in field types. Where Prisma ORM 7 wrote a Prisma
 | Prisma ORM 7 | Prisma ORM 8 | Notes |
 | --- | --- | --- |
 | `schema.prisma` | `contract.prisma` | |
-| (nothing) | `// use prisma-8` as the first line | required in every contract file; see the note below the table |
+| (nothing) | `// use prisma-8` as the first line | required in every Prisma ORM 8 `.prisma` contract file; see the note below the table |
 | `generator client { ... }` | removed | `emit` is the new word for `generate`. `prisma contract emit` writes two files next to your contract, `contract.json` and `contract.d.ts`. Commit both |
 | `datasource db { ... }` | the `orm` section of `prisma.config.ts` | the connection string and file paths live in the config file, not the schema. Example below |
 | `String @db.Text` | `String` | `String` is already stored as `text`. A known bug in one error message suggests `Text`; there is no such type |
@@ -70,7 +70,7 @@ The biggest visible change is in field types. Where Prisma ORM 7 wrote a Prisma
 
 :::note[The first line of a contract file]
 
-Every contract file must start with `// use prisma-8`. `prisma orm init` writes the line for you, so you add it yourself only when you create a contract file by hand. `prisma contract emit` reads only the `.prisma` files that start with this line and skips the others without a warning, and the [Prisma editor extension](/orm/contract-authoring/editor-support) does not recognize a file without it.
+Every Prisma ORM 8 `.prisma` contract file must start with `// use prisma-8`. `prisma orm init` writes the line for you, so you add it yourself only when you create a contract file by hand. `prisma contract emit` reads only the `.prisma` files that start with this line and skips the others without a warning, and the [Prisma editor extension](/orm/contract-authoring/editor-support) does not recognize a file without it.
 
 :::
 
@@ -90,7 +90,7 @@ model User {
 }
 ```
 
-Filter a `pg.enum(...)` field with `eq` or `in`, because it has no `like` or `ilike`. You can switch to a plain `enum` later, but that changes the column type, so it needs a migration.
+A `pg.enum(...)` field supports the `eq` and `in` filters, not `like` or `ilike`. You can switch to a plain `enum` later, but that changes the column type, so it needs a migration.
 
 :::
 
@@ -156,7 +156,7 @@ export default definePrismaConfig({
 
 The `orm` section takes these keys:
 
-- `contract`: the path to your contract file, or a glob for a [contract in several files](/orm/contract-authoring/psl-syntax#split-the-contract-across-several-files). On PostgreSQL it can also be `prisma7Schema("prisma/schema.prisma")`, with `prisma7Schema` imported from `@prisma/orm-postgres/config` next to `defineConfig`. It reads your Prisma ORM 7 schema as it is, with no `// use prisma-8` line; see [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema).
+- `contract`: the path to your contract file, or a glob for a [contract in several files](/orm/contract-authoring/psl-syntax#split-the-contract-across-several-files). On PostgreSQL it can also be `prisma7Schema("prisma/schema.prisma")`, with `prisma7Schema` imported from `@prisma/orm-postgres/config` next to `defineConfig`. The schema stays in Prisma ORM 7 syntax, so the changes in the table above do not apply to it, and it needs no `// use prisma-8` line. `contract emit` fails on any part of it that Prisma ORM 8 cannot read, such as a `view` block, and the error names the line and the Prisma ORM 7 edit that removes it; see [Use a Prisma ORM 7 schema](/cli/configuration#use-a-prisma-orm-7-schema).
 - `db`: the connection.
 - `output` (optional): where `contract.json` and `contract.d.ts` are written. Default: next to the contract.
 - `extensions` (optional): database extensions, for example `extensions: [pgvector]` with `import pgvector from "@prisma/orm-extension-pgvector/control"`. See [Using extensions](/orm/extensions/using-extensions).
@@ -216,8 +216,8 @@ export const db = postgres<Contract>({
 `db` has these parts:
 
 - `db.orm`: your models, by model name (`db.orm.public.User`).
-- `db.sql`: the [SQL query builder](/orm/reference/sql-query-builder), with your tables by table name (`db.sql.public.User`; the table name is the model name, unless you set `@@map`). On this page it appears only in the raw SQL examples, which take the type of each returned column from it.
-- `db.raw.sql`: writes a raw SQL query as text.
+- `db.sql`: the [SQL query builder](/orm/reference/sql-query-builder). It holds your tables by table name, as in `db.sql.public.User`, and a table's name is its model's name unless you set `@@map`. On this page, the raw SQL examples use it only to give each column's type.
+- `db.raw.sql`: lets you write a SQL query as text.
 - `db.runtime()`: the connection. It runs raw queries.
 - `db.transaction`: runs several queries in one transaction.
 
@@ -319,7 +319,7 @@ const update = db.raw.sql`UPDATE "User" SET active = false WHERE id = ${id}`
 await db.runtime().execute(update);
 ```
 
-The table is `User`, as in Prisma ORM 7: a model without `@@map` names its table after the model. A value you put in the SQL with `${...}`, such as `${id}`, is sent to the database as a query parameter, not pasted into the SQL text, as with Prisma ORM 7's `$executeRaw`.
+The table is `User`, because a model without `@@map` names its table after the model. As in Prisma ORM 7, a value you put in the SQL with `${...}`, such as `${id}`, is sent to the database as a query parameter.
 
 Every raw query that returns rows needs `.returnsRow(...)` with a type per column, and you take the type from the table, as above. A computed column has no table column to take it from, so write the type name as a string instead: for `SELECT count(*) AS total FROM "User"`, write `.returnsRow({ total: "pg/int8@1" })`. [Raw queries](/orm/reference/raw-queries) lists the type names. Finish the query with `.build()` and pass it to `db.runtime().query()` for rows or `db.runtime().execute()` for a count. On PostgreSQL, `db.runtime()` returns the connection directly, so it needs no `await`; the MongoDB client's `db.runtime()` is the one you `await`.
 
@@ -386,7 +386,7 @@ const created = await db.orm.public.User.createAll(rows, {
 });
 ```
 
-Here `conflictOn` is a list of field names. In `upsert` it is an object of fields and values instead. If you emitted your contract before `8.0.0-rc.12`, run `prisma contract emit` again before you use `onConflict`; otherwise the call fails with `ORM.CAPABILITY_MISSING`.
+Here `conflictOn` is a list of field names. In `upsert` it is an object of fields and values instead. A contract emitted by an earlier release than `8.0.0-rc.12` makes the call fail with `ORM.CAPABILITY_MISSING`, so if your project used Prisma ORM 8 before that release, run `prisma contract emit` again before you use `onConflict`.
 
 :::
 
diff --git a/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx b/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx
index 18535a8795..04c4eb4a32 100644
--- a/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/editor-support.mdx
@@ -20,15 +20,13 @@ The extension only works on `.prisma` files whose first non-blank line is:
 // use prisma-8
 ```
 
-A file without that line gets no error checking, no completion, and no formatting, and [`prisma contract emit`](/cli/contract-emit) leaves it out of the contract. [`orm init`](/cli/orm-init) and [`contract infer`](/cli/contract-infer) write the line for you. Add it yourself when you create a contract by hand.
-
-Contracts from before `8.0.0-rc.10` start with `// use prisma-next`, the preview's name. The extension still accepts that line, and nothing breaks if you leave it. When you format the file, the extension rewrites that line to `// use prisma-8`.
+A file without that line gets no error checking, no completion, and no formatting. [`prisma contract emit`](/cli/contract-emit) also skips it without a warning, and when none of the files that the `contract` setting names has the line, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`. [`orm init`](/cli/orm-init) and [`contract infer`](/cli/contract-infer) write the line for you. Add it yourself when you create a contract by hand.
 
 ## What the editor does
 
 - **Errors** appear inline as you type. They are the same errors you would get from [`prisma contract emit`](/cli/contract-emit), the command that checks the contract and writes `contract.json` and `contract.d.ts`.
 - **Formatting** reformats the whole file. In VS Code, run **Format Document**.
-- **Completion** starts when you type `@` or `@@`. The editor lists attribute names such as `@id`, `@default`, and `@@index`, each with a short description. Inside an attribute, it lists the names of the arguments you have not filled in yet, and it suggests values for them, including values you type inside `[ ]`, inside `{ }`, and inside a call such as `createdAt(sort: Desc)`. Where an attribute expects a field name, it suggests only scalar fields. When an attribute has required arguments, VS Code inserts them as placeholders named after each argument, which you tab through.
+- **Completion** starts when you type `@` or `@@`. The editor lists attribute names such as `@id`, `@default`, and `@@index`, each with a short description. Inside an attribute, it lists the names of the arguments you have not filled in yet and suggests values for them. It also suggests values inside `[ ]` and `{ }`. In a MongoDB index's field list, it suggests the option and its values in the parentheses after a field name, such as `sort` and `Desc` in `@@index([createdAt(sort: Desc)])`. Where an attribute expects a field name, it suggests only scalar fields. When an attribute has required arguments, VS Code inserts them as placeholders named after each argument, which you tab through.
 - **Signature help** appears when you type `(` or `,` inside an attribute. It shows the attribute's arguments and describes the one you are typing.
 
 The list of attributes comes from your `prisma.config.ts`: the database it declares and the Prisma extension packs listed under `extensions`; see [Extension packs](/cli/configuration#extension-packs) for that config. Extension packs are add-on packages for database features such as [pgvector](/orm/extensions/using-extensions). If your config lists the pgvector pack, the editor also suggests pgvector's attributes. No database connection is needed.
diff --git a/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx b/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
index 7ec5e0aefa..2aea0beada 100644
--- a/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/psl-syntax.mdx
@@ -18,7 +18,7 @@ The `datasource` and `generator` blocks are gone: the connection URL and the fil
 
 ## A complete contract
 
-The first non-blank line of every contract file is `// use prisma-8`, because `contract emit` reads only the `.prisma` files that start with it. When `contract` names one file and that file lacks the line, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`, and the error's finding is `PSL_NO_OPTED_IN_SCHEMA_FILES`. When `contract` is a [glob that matches several files](#split-the-contract-across-several-files), a file without the line is left out of the contract without a warning, and `contract emit` fails only when none of the files has it.
+The first non-blank line of every contract file is `// use prisma-8`, because `contract emit` reads only the `.prisma` files that start with it. When the `contract` setting in `prisma.config.ts` names one file and that file lacks the line, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`, and the error's details include `PSL_NO_OPTED_IN_SCHEMA_FILES`. When `contract` is a [glob that matches several files](#split-the-contract-across-several-files), a file without the line is left out of the contract without a warning, and `contract emit` fails only when none of the files has it.
 
 ```prisma title="src/prisma/contract.prisma" tab="PostgreSQL"
 // use prisma-8
@@ -132,14 +132,15 @@ Set `contract` to a glob, such as `"./src/prisma/**/*.prisma"`, to write the con
 
 ## Models and fields
 
-Models declare fields with a type, an optional `?` marker, and attributes. [Scalar fields](/orm/data-modeling#scalar-fields) lists the types a field can hold, among them `String`, `Int`, `Boolean`, `Decimal`, `DateTime`, `Json`, and `Bytes`. On PostgreSQL, plain `String` is a `text` column, `Int` is `int4`, and `DateTime` is `timestamptz`, and you can write a PostgreSQL type wherever you would write `String` or `DateTime`: `VarChar`, `Char`, `Numeric`, `Timestamp`, `Timestamptz`, `Time`, `Timetz`, `Date`, `Uuid`, `Inet`, `SmallInt`, or `Real`.
+Models declare fields with a type, an optional `?` marker, and attributes. [Scalar fields](/orm/data-modeling#scalar-fields) lists the types a field can hold, among them `String`, `Int`, `Boolean`, `Decimal`, `DateTime`, `Json`, and `Bytes`. On PostgreSQL, plain `String` is a `text` column, `Int` is `int4`, and `DateTime` is `timestamptz`. You can also use one of these PostgreSQL types as the field type: `VarChar`, `Char`, `Numeric`, `Timestamp`, `Timestamptz`, `Time`, `Timetz`, `Date`, `Uuid`, `Inet`, `SmallInt`, or `Real`. Their arguments are optional: `VarChar(35)` and `Char(2)` set a length, `Numeric(10, 2)` sets a precision and scale, and `Timestamp(3)`, `Timestamptz(3)`, `Time(3)`, and `Timetz(3)` set how many digits of a second are kept. `Timestamptz` without an argument is the same column as `DateTime`, so use it only when you want to set that precision.
 
-On PostgreSQL, `DateTime`, `Timestamp`, `Timestamptz`, `Time`, and `Date` reach your code as `Temporal` values, such as a `Temporal.Instant` for `DateTime`, so your app needs a global `Temporal` to read and write them; [Scalar fields](/orm/data-modeling#scalar-fields) says how to check for it. When you want a string instead, use `DateString`, a `date` column your code gets as a string, or `TimestampString`, `TimestamptzString`, and `TimeString`, which do the same for `timestamp`, `timestamptz`, and `time`. `TimestamptzJsDate` is a `timestamptz` column your code gets as a JavaScript `Date`, so it needs no `Temporal`, but a `Date` drops the microseconds PostgreSQL stores.
+On PostgreSQL, the date and time types reach your code as `Temporal` values: `DateTime` and `Timestamptz` as a `Temporal.Instant`, `Timestamp` as a `Temporal.PlainDateTime`, `Date` as a `Temporal.PlainDate`, and `Time` as a `Temporal.PlainTime`. Your app needs a global `Temporal` to read and write them, and [Scalar fields](/orm/data-modeling#scalar-fields) says how to check for it. When you want a string instead, use `DateString`, a `date` column your code gets as a string, or `TimestampString`, `TimestamptzString`, and `TimeString`, which do the same for `timestamp`, `timestamptz`, and `time`. `TimestamptzJsDate` is a `timestamptz` column your code gets as a JavaScript `Date`, so it needs no `Temporal`, but a `Date` drops the microseconds PostgreSQL stores.
 
 - `@id` marks the primary key. `@@id([a, b])` declares a composite key.
 - `@unique` adds a unique constraint on one field. `@@unique([userId, title])` adds one across several fields.
 - `@@index([...])` declares a secondary index.
-- `@default(...)` sets a default. Database defaults are a literal, `@default(now())`, `@default(autoincrement())`, or a SQL expression written as a `sql` tagged literal, such as ``@default(sql`gen_random_uuid()`)``; the database fills them in. See [Default values](#default-values) for how to write each kind of literal. Generated defaults are `uuid()` (a version 4 UUID, the same as `uuid(4)`), `uuid(7)`, `cuid(2)`, `ulid()`, and `nanoid()`, and `nanoid(n)` sets the length, from 2 to 255. Prisma ORM computes them when it writes the row, and the database will not fill them in for you, so a row written by raw SQL or another application gets no value. Prisma ORM 7's `cuid()` is rejected with a hint to use `cuid(2)`.
+- `@default(...)` sets a default the database fills in when it is a literal, `now()`, `autoincrement()`, or any other SQL expression. Write the SQL as a `sql` tagged literal, which is `sql` followed by the SQL in backticks, such as ``@default(sql`gen_random_uuid()`)``. See [Default values](#default-values) for how to write each kind of literal.
+- `@default(...)` sets a default Prisma ORM generates when it is `uuid()` (a version 4 UUID, the same as `uuid(4)`), `uuid(7)`, `cuid(2)`, `ulid()`, or `nanoid()`, where `nanoid(n)` sets the length, from 2 to 255. Prisma ORM computes the value when it writes the row and the database will not fill it in for you, so a row written by raw SQL or another application gets no value. Prisma ORM 7's `cuid()` is rejected with a hint to use `cuid(2)`.
 - `@map("column_name")` sets a field's column name in the database. `@@map("table_name")` sets the table or collection name when it differs from the model name. Without `@@map`, the table or collection has the model's name exactly as written, so `model UserProfile` is the table `"UserProfile"`.
 - `@@check(expression: "total >= 0", name: "order_total_positive")` adds a check constraint of your own to the table. See [Check constraints](#check-constraints).
 - `@@control(observed)` says how far Prisma ORM manages the table. See [Control policy](#control-policy).
@@ -154,7 +155,7 @@ model Post {
 }
 ```
 
-Prisma ORM sets the field to the current time on every create and update. `temporal` is built in, so you do not import it or declare it. On PostgreSQL the column is `timestamptz`, and you can still set the field yourself on a write. `temporal.createdAt()` sets the field once, when the row is created. Both take the time from your application's clock, not from the database, so the column has no database default, and a row you insert with raw SQL must supply the value. For a value the database generates, use `DateTime @default(now())` instead. `temporal.createdAtJsDate()` and `temporal.updatedAtJsDate()` do the same with a JavaScript `Date` in place of a `Temporal` value. `temporal.createdAt()` and `temporal.updatedAt()` need a global `Temporal` for writes as well as reads, so load a polyfill such as `temporal-polyfill/full/global` when your runtime has none.
+Prisma ORM sets the field to the current time on every create and update. `temporal` is a built-in group of timestamp field types, such as `temporal.createdAt()` and `temporal.updatedAt()`, so you do not import it or declare it. On PostgreSQL the column is `timestamptz`, and you can still set the field yourself on a write. `temporal.createdAt()` sets the field once, when the row is created. Both take the time from your application's clock, not from the database, so the column has no database default, and a row you insert with raw SQL must supply the value. For a value the database generates, use `DateTime @default(now())` instead. `temporal.createdAtJsDate()` and `temporal.updatedAtJsDate()` do the same with a JavaScript `Date` in place of a `Temporal` value. `temporal.createdAt()` and `temporal.updatedAt()` need a global `Temporal` for writes as well as reads, so when your runtime has none, install `temporal-polyfill` and add `import "temporal-polyfill/full/global"` to your app's entry file.
 
 How IDs map differs by database:
 
@@ -191,10 +192,11 @@ model Account {
 }
 ```
 
-- A JSON default is a `json` tagged literal, whose body is the JSON document itself. A JSON array is also one `json` literal, as `tags` shows.
+- A JSON default is a `json` tagged literal: `json` followed by the JSON document in backticks. Write a JSON array the same way, as `tags` shows.
 - A decimal default is a bare number, and it keeps every digit you write, trailing zeros included.
 - `NaN`, `Infinity`, and `-Infinity` are written without quotes, and so are `true` and `false`.
-- A text default is a quoted string, and so is a fixed date or time, as `startsOn` shows. On a column that reads as a `Temporal` value, such as `Date` or `DateTime`, `contract emit` checks the date with `Temporal`, so the Node.js that runs `contract emit` needs a global `Temporal`.
+- A text default is a quoted string, and so is a fixed date or time, as `startsOn` shows. A `DateTime` default is a point in time with a UTC offset, such as `"2024-01-01T00:00:00Z"`, and a `Timestamp` default has no offset, such as `"2024-01-01 00:00:00"`.
+- A fixed default on a `Date`, `DateTime`, `Timestamp`, or `Time` field needs a global `Temporal` in the Node.js that runs `contract emit`, which uses it to check the value. Without one, `contract emit` fails with `PSL_INVALID_DEFAULT_LITERAL`. A polyfill imported in your app does not help here, so run the CLI on a Node.js version that has `Temporal` built in, or use `DateString`, `TimestampString`, `TimestamptzString`, or `TimeString`, which need no `Temporal`.
 - On a field typed with an `enum` block, the default is the member's name without quotes, as in `@default(Low)`. On a `pg.enum(...)` field, it is the value the member stores, in quotes, as in `@default("admin")`. [Enums](#enums) covers both.
 - Any other SQL expression is a `sql` tagged literal, and it goes into the column default exactly as written. Write the current time as `now()` and a sequence as `autoincrement()`, not as `` sql`now()` `` or `` sql`autoincrement()` ``, which are refused.
 
@@ -222,7 +224,7 @@ The `expression:` and `where:` strings go into the SQL as written, so they use c
 
 ### Full-text indexes
 
-`@@fullTextIndex([field])` creates the GIN index that PostgreSQL [full-text search](/orm/reference/orm-client#full-text-search) uses. It takes one text field, and a `name:` or a `map:`:
+`@@fullTextIndex([field])` creates the GIN index that PostgreSQL [full-text search](/orm/reference/orm-client#full-text-search) uses. It takes one text field, and it needs either `name:` or `map:`, but not both:
 
 ```prisma title="src/prisma/contract.prisma (excerpt)"
 model Post {
@@ -233,7 +235,7 @@ model Post {
 }
 ```
 
-`language:` sets the text-search configuration and defaults to `english`. A search sets its language with the `language` option of `fullTextMatches` and `fullTextRank`, as in `fullTextMatches(query, { language: "german" })`, and that option also defaults to `english`. Give the index and the search the same language, because PostgreSQL does not use the index for a search in another language. `where:` makes it a partial index, as on `@@index`. A field typed `pg.enum(...)`, a PostgreSQL enum type as [Enums](#enums) describes, cannot have a full-text index. PostgreSQL only.
+`language:` sets the text-search language, which tells PostgreSQL how to break the text into searchable words. It defaults to `english`, and you set it as in `@@fullTextIndex([title], name: "post_title_search", language: "german")`. In a query, you search with the text field's `fullTextMatches` and `fullTextRank` functions, which take the same `language` option, as in `p.title.fullTextMatches(query, { language: "german" })`, and that option also defaults to `english`. Give the index and the search the same language, because PostgreSQL does not use the index for a search in another language. `where:` makes it a partial index, as on `@@index`. A field typed `pg.enum(...)`, a PostgreSQL enum type as [Enums](#enums) describes, cannot have a full-text index. PostgreSQL only.
 
 ### Check constraints
 
@@ -431,7 +433,17 @@ namespace audit {
 }
 ```
 
-Models outside any block are in `public`. In queries, the block name is the segment after `db.orm`, so this model is `db.orm.audit.AuditLog`. Two `namespace` blocks with the same name in one file are one namespace, so you can open a block again further down the file. A relation can also point at a model that an [extension pack](#extension-types), an npm package you add to your config, declares in a different schema. Write that model as `<pack>:<schema>.<Model>`, for example `supabase:auth.AuthUser`; the [Supabase extension](/orm/extensions) documents that form.
+Models outside any block are in `public`. In queries, the block name is the segment after `db.orm`, so this model is `db.orm.audit.AuditLog`. Two `namespace` blocks with the same name in one file are one namespace, so you can open a block again further down the file. A relation can also point at a model that an [extension pack](#extension-types), an npm package you add to your config, declares in a different PostgreSQL schema. Write that model as the relation field's type, in the form `<pack>:<schema>.<Model>`, where `<schema>` is the PostgreSQL schema. For example, the Supabase pack declares `AuthUser` in the `auth` schema:
+
+```prisma
+model Profile {
+  id     Uuid                   @id @default(uuid())
+  userId Uuid                   @unique
+  user   supabase:auth.AuthUser @relation(fields: [userId], references: [id], onDelete: Cascade)
+}
+```
+
+The [Supabase extension](/orm/extensions) documents that form.
 
 ## Row-level security
 
diff --git a/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx b/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx
index 9ec1a15577..2bcc02c0a5 100644
--- a/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/the-contract-artifact.mdx
@@ -95,7 +95,7 @@ An abridged `contract.json` for a `User` and `Post` schema:
 The sections, top to bottom:
 
 - **`schemaVersion`, `targetFamily`, `target`**: the contract format version, whether the database is SQL or MongoDB, and which database this contract targets.
-- **`roots`**: one entry per table that stores a model. The key is the name of that table, so for a model `User` mapped to a table `users` the key is `users`. The value names the model. You can query the model's data in two ways: `db.sql.public.User` uses the table name, and `db.orm.public.User` uses the model name. In this example both are `User`, because the model sets no `@@map`. The [ORM reference](/orm/reference) covers both.
+- **`roots`**: one entry per table that stores a model. The key is the name of that table, so for a model `User` mapped to a table `users` the key is `users`. The value names the model. You can query the model's data in two ways. The [SQL query builder](/orm/reference/sql-query-builder), `db.sql`, reaches the table by its table name, and the ORM API, `db.orm`, reaches the model by its model name. In this example both names are `User`, because the model sets no `@@map`, so the calls are `db.sql.public.User` and `db.orm.public.User`. For a model `User` mapped to a table `users`, they are `db.sql.public.users` and `db.orm.public.User`. The [ORM reference](/orm/reference) covers both.
 - **`domain` and `storage`**: your application's view, then the database's view. Each scalar field in `domain` records whether it is nullable and its `codecId`. `nativeType` is the column type in the database. `codecId` names how Prisma ORM reads and writes the value, the PostgreSQL type plus a version. `storage` holds the tables with their columns, keys, indexes, constraints, and enum values. `prisma db verify` compares it to the live database.
 - **`capabilities`**: which database features this contract can use. `npx prisma contract emit` collects them from the adapter for your database and from the packages listed in `extensions: [...]` in `prisma.config.ts`, the config file `prisma orm init` writes. The query APIs check them before building a query that needs one. See [supported database features](/orm/contract-authoring/capabilities) and [extension types](/orm/contract-authoring/psl-syntax#extension-types).
 
diff --git a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
index 66cb41cdc2..ae7e400a7c 100644
--- a/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/the-data-contract.mdx
@@ -25,7 +25,7 @@ model Post {
 }
 ```
 
-`npx prisma orm init` writes the first line, `// use prisma-8`, into every `.prisma` contract. It marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema. Every `.prisma` contract file must start with this line. `contract emit` reads only files that start with it and skips any other file without a warning. When no file has the line, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`, and the error's finding is `PSL_NO_OPTED_IN_SCHEMA_FILES`. The editor extension also looks for the line before it checks, completes, or formats the file. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
+The first line, `// use prisma-8`, marks the file as a Prisma ORM 8 contract rather than a Prisma ORM 7 schema, and `npx prisma orm init` writes it into the `contract.prisma` file it creates. The first non-blank line of every `.prisma` contract file must be `// use prisma-8`, because `contract emit` reads only the files that have it and skips any other file without a warning. When no file has the line, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`. The editor extension also looks for the line before it checks, completes, or formats the file. A `contract.ts` file needs no header line. See [Editor support](/orm/contract-authoring/editor-support).
 
 `npx prisma contract emit` turns this file into two files that the CLI and your application read: `contract.json` and `contract.d.ts`. Your queries are type-checked against the contract, migrations are planned as changes to it, and `npx prisma db verify` checks a live database against it.
 
@@ -64,7 +64,7 @@ export default definePrismaConfig({
 
 To start a new project, run `npm create prisma@latest -- my-app`. To add Prisma ORM 8 to a project that has no Prisma ORM at all, run `npx prisma orm init`. If you already have a Prisma ORM 7 `schema.prisma`, follow the [PostgreSQL upgrade guide](/guides/upgrade-prisma-orm/postgresql) instead, and [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7) lists what changed. Both `npm create prisma@latest` and `npx prisma orm init` write `prisma.config.ts`, the contract file, and `src/prisma/db.ts`, and install the database package.
 
-The contract file is either a PSL file (`contract.prisma`) or a TypeScript file (`contract.ts`). The file extension selects the authoring mode, so to author in TypeScript you point `contract` at `./src/prisma/contract.ts`. You can also split a PSL contract across several files by setting `contract` to a glob such as `./src/prisma/**/*.prisma`, as [Configuration](/cli/configuration#split-the-schema-across-several-files) shows. Both modes describe the same things: models with fields and relations, the tables and columns they map to, named types, enums, and any types that [extension packages](/orm/contract-authoring/psl-syntax#extension-types) add. Extension packages are npm packages that add field types and database features, such as pgvector, a PostgreSQL extension for vector columns.
+The contract file is either a PSL file (`contract.prisma`) or a TypeScript file (`contract.ts`). The file extension selects the authoring mode, so to author in TypeScript you point `contract` at `./src/prisma/contract.ts`. You can also split a PSL contract across several files by setting `contract` to a glob such as `./src/prisma/**/*.prisma`, as [Configuration](/cli/configuration#split-the-schema-across-several-files) shows. Both modes describe the same things: models with fields and relations, the tables and columns they map to, named types, enums, and any types that [extension packages](/orm/contract-authoring/psl-syntax#extension-types) add. Extension packages are npm packages that add field types and database features. For example, `@prisma/orm-extension-pgvector` adds vector columns, which it stores with pgvector, a PostgreSQL extension.
 
 After every change to the contract, run these three commands:
 
diff --git a/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx b/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
index fcf719e008..825b7e2592 100644
--- a/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
+++ b/apps/docs/content/docs/orm/contract-authoring/typescript-schema-builder.mdx
@@ -199,11 +199,11 @@ The examples below use the PostgreSQL builder.
 
 There is no helper for a date without a time, or a time without a date. For a date-only column, name the type yourself: `field.column({ codecId: "pg/date-temporal@1", nativeType: "date" } as const)`. `field.column(...)` and the chained `.column(...)` below are different calls: `field.column(descriptor)` builds a field from a type description, and `.column(name)` on an existing field sets its column name. Extension packs add more helpers of their own.
 
-For a primary key your app generates, use a `field.id.*` helper. Each one marks the field as the primary key and generates the ID in your app when you create a row. `field.id.uuidv4String()` is the common choice, and the others are `field.id.uuidv7String()`, `field.id.ulid()`, `field.id.nanoid()`, `field.id.cuid2()`, and `field.id.ksuid()`. To store a UUID in a `uuid` column instead of a text column, use `field.id.uuidv4Native()` or `field.id.uuidv7Native()`.
+For a primary key your app generates, use a `field.id.*` helper. Each one marks the field as the primary key and generates the ID in your app when you create a row. `field.id.uuidv4String()` is the common choice, and the others are `field.id.uuidv7String()`, `field.id.ulid()`, `field.id.nanoid()`, `field.id.cuid2()`, and `field.id.ksuid()`. To store a UUID in a `uuid` column instead of a `character(36)` column, use `field.id.uuidv4Native()` or `field.id.uuidv7Native()`.
 
 For a key the database generates, chain `.default(...)` and `.id()` on a field. An integer that counts up is `field.int().default(autoincrement()).id()`, and a UUID is ``field.uuidNative().default(sql`gen_random_uuid()`).id()``. Import `autoincrement` and `sql` from `@prisma/orm-postgres/contract-builder`.
 
-`field.temporal.createdAt()` sets the column to the current time when the row is created, and `field.temporal.updatedAt()` sets it on every create and every update. Prisma ORM sets both in the client, from your application's clock, so the column has no database default. If you insert a row with raw SQL, you must supply the value yourself. For a time the database sets instead, use `field.dateTime().default(now())`.
+`field.temporal.createdAt()` sets the column to the current time when the row is created, and `field.temporal.updatedAt()` sets it on every create and every update. Prisma ORM sets both in the client, from your application's clock, so the column has no database default. If you insert a row with raw SQL, you must supply the value yourself. For a time the database sets instead, use `field.dateTime().default(now())`, with `now` imported from `@prisma/orm-postgres/contract-builder`.
 
 `field.dateTime()`, `field.temporal.createdAt()`, and `field.temporal.updatedAt()` give your code a `Temporal.Instant`, so your app needs a global `Temporal` to read and write them; [Scalar fields](/orm/data-modeling#scalar-fields) says how to check for it and which polyfill to load when it is missing. To get a JavaScript `Date` instead, and need no `Temporal`, use `field.temporal.timestamptzJsDate()` for a `timestamptz` column, and `field.temporal.createdAtJsDate()` and `field.temporal.updatedAtJsDate()` for creation and update times.
 
@@ -212,7 +212,8 @@ For a key the database generates, chain `.default(...)` and `.id()` on a field.
 Every field builder supports chained modifiers:
 
 - `.optional()` makes the field nullable.
-- `.default(value)` sets a literal default. Pass the value in the form your code reads from that column, so a decimal default is a string, as in `.default("1.50")`, and a JSON default is the object or array itself, as in `.default({ plan: "free" })`. It also takes a default the database computes: `.default(now())`, `.default(autoincrement())`, or any other SQL expression as a `sql` template, such as ``.default(sql`gen_random_uuid()`)``. Import `now`, `autoincrement`, and `sql` from `@prisma/orm-postgres/contract-builder`. `` sql`now()` `` and `` sql`autoincrement()` `` are refused; use the named helpers. `.defaultSql(expression)` still works but is deprecated, and it will be removed in the stable `8.0.0` release.
+- `.default(value)` sets a fixed default. A decimal default is a string, as in `.default("1.50")`, and a JSON default is the object or array itself, as in `.default({ plan: "free" })`. A `field.dateTime()` default is the time as a string with a UTC offset, as in `.default("2024-01-01T00:00:00Z")`, because `.default()` does not accept the `Temporal.Instant` your code reads from that column.
+- `.default(...)` also takes a default the database computes: `.default(now())`, `.default(autoincrement())`, or any other SQL expression as a `sql` template, such as ``.default(sql`gen_random_uuid()`)``. Import `now`, `autoincrement`, and `sql` from `@prisma/orm-postgres/contract-builder`. `` sql`now()` `` and `` sql`autoincrement()` `` are refused, so use the named helpers. `.defaultSql(expression)` still works but is deprecated, and it will be removed in the stable `8.0.0` release.
 - `.unique()` adds a unique constraint. `.id()` marks the primary key, for a key that is not generated, such as an integer you set yourself.
 - `.column("column_name")` sets the column name in the database when it differs from the field name.
 - `.many()` makes the field a list, stored as a PostgreSQL array column such as `text[]`. A list column gets a check constraint that rejects `NULL` elements.
@@ -299,9 +300,9 @@ indexes: [
 
 The `where` and `expression` strings go into the SQL as written, so they use column names, and you quote them yourself.
 
-The ids, unique constraints, indexes, and foreign keys of one model must all have different names. A name used twice is a type error at `defineContract`.
+The primary key, unique constraints, indexes, and foreign keys of one model must all have different names. A `name` used twice is a type error that your editor and `tsc` report, but `npx prisma contract emit` does not type-check the file, and it accepts the repeated `name` because each name gets a different hash on the end in the database. A `map` used twice makes `contract emit` fail with `CONTRACT.SOURCE_LOAD_FAILED`.
 
-For PostgreSQL [full-text search](/orm/reference/orm-client#full-text-search), `fullTextIndex` from `@prisma/orm-postgres/contract-builder` creates the GIN index the search operations use. It takes one text column and a `name` or `map`, plus optional `language` and `where`:
+For PostgreSQL [full-text search](/orm/reference/orm-client#full-text-search), `fullTextIndex` from `@prisma/orm-postgres/contract-builder` creates the GIN index that a text field's `fullTextMatches` and `fullTextRank` query functions use. It takes one text column and a `name` or `map`, plus optional `language` and `where`:
 
 ```typescript title="src/prisma/contract.ts (excerpt)"
 import { fullTextIndex } from "@prisma/orm-postgres/contract-builder";
@@ -312,7 +313,7 @@ Post.sql(({ cols }) => ({
 }));
 ```
 
-`language` defaults to `english` on both the index and the search operations, and PostgreSQL uses the index only when the two match, so change both or neither.
+`language` defaults to `english` on both the index and the query functions, and PostgreSQL uses the index only when the two match, so change both or neither. To search German text, for example, write `fullTextIndex(cols.title, { name: "post_title_search", language: "german" })` on the index and `p.title.fullTextMatches(query, { language: "german" })` in the query.
 
 Two more keys go in the same object, in either the object form or the callback form: `checks`, a list of check constraints you write yourself, built with `check` from the package, and `control`, the model's [control policy](#control-policy):
 
diff --git a/apps/docs/content/docs/orm/data-modeling/index.mdx b/apps/docs/content/docs/orm/data-modeling/index.mdx
index 1f44f4007b..5cb18159fa 100644
--- a/apps/docs/content/docs/orm/data-modeling/index.mdx
+++ b/apps/docs/content/docs/orm/data-modeling/index.mdx
@@ -145,11 +145,11 @@ A scalar field holds a single value. The common types:
 
 The PostgreSQL names in the table are the column types Prisma ORM creates. `ObjectId` is the only MongoDB-only type.
 
-A `Decimal` reaches your code as a string, so nothing is rounded through a JavaScript number, and a `Bytes` value reaches you as a `Uint8Array`. A `DateTime` is a JavaScript `Date` on MongoDB, but on PostgreSQL it reaches you as a `Temporal.Instant`, the standard JavaScript type for a point in time. `Temporal` is built into Node.js 26.8.2 and later, but Homebrew's build of Node.js 26 leaves it out, so check with `node -p "typeof Temporal"`. If that prints `undefined`, install the `temporal-polyfill` package and add `import "temporal-polyfill/full/global"` to your app's entry file, before any query runs. To work with a JavaScript `Date` on PostgreSQL instead, and need no polyfill, type the field `TimestamptzJsDate`, but a `Date` drops the microseconds PostgreSQL stores.
+A `Decimal` reaches your code as a string, so nothing is rounded through a JavaScript number, and a `Bytes` value reaches you as a `Uint8Array`. A `DateTime` is a JavaScript `Date` on MongoDB, but on PostgreSQL it reaches you as a `Temporal.Instant`, the standard JavaScript type for a point in time. `Temporal` is built into Node.js 26.8.2 and later, but Homebrew's build of Node.js 26 leaves it out, so check with `node -p "typeof Temporal"`. If that prints `undefined`, install the `temporal-polyfill` package and add `import "temporal-polyfill/full/global"` to your app's entry file, before any query runs. That import covers your app only, and `contract emit` needs its own `Temporal` when a date or time field has a fixed default, as [Default values](/orm/contract-authoring/psl-syntax#default-values) explains. To work with a JavaScript `Date` on PostgreSQL instead, and need no polyfill, type the field `TimestamptzJsDate`, but a `Date` drops the microseconds PostgreSQL stores.
 
 `Json` and `Jsonb` are two separate types, and they differ in how you can filter on them. On a `Jsonb` field, `.where()` compares the whole value, so you can ask whether the column equals a given document but not whether a key inside it matches. A `Json` field cannot be compared in `.where()` at all, so use `Jsonb` unless you specifically need PostgreSQL's plain `json` column. When you need a path query into the document, reach for [raw SQL](/orm/reference/raw-queries). [Extensions](/orm/extensions) add more types, such as vectors or geometry.
 
-A trailing `?` makes a field optional: `name String?`. A trailing `[]` makes it a list: `tags String[]`. A `@default(...)` must be written in a form the field's type accepts, such as ``@default(json`{}`)`` on a `Jsonb` field and `@default(1.50)` on a `Decimal` field; [Default values](/orm/contract-authoring/psl-syntax#default-values) lists them.
+A trailing `?` makes a field optional: `name String?`. A trailing `[]` makes it a list: `tags String[]`. A `@default(...)` must be written in a form the field's type accepts, such as the `json` literal ``@default(json`{}`)`` on a `Jsonb` field and `@default(1.50)` on a `Decimal` field; [Default values](/orm/contract-authoring/psl-syntax#default-values) lists them.
 
 A field can also hold one of a fixed set of values. Declare them in an `enum` block:
 
diff --git a/apps/docs/content/docs/orm/extensions/using-extensions.mdx b/apps/docs/content/docs/orm/extensions/using-extensions.mdx
index 128e7ee523..d6532f1271 100644
--- a/apps/docs/content/docs/orm/extensions/using-extensions.mdx
+++ b/apps/docs/content/docs/orm/extensions/using-extensions.mdx
@@ -208,9 +208,9 @@ export const db = await supabase<Contract>({
 
 `await db.asUser(jwt)` takes the user's Supabase JWT and gives you a client that runs as that user. `db.asAnon()` gives you one that runs as the anonymous role, and `db.asServiceRole()` one that bypasses row-level security. `db` itself has no `orm` or `sql`: those live on the three role-bound clients. The [runnable example](https://github.com/prisma/orm/tree/main/examples/supabase) shows the whole setup in one project.
 
-The extension's contract describes Supabase's `auth` and `storage` tables as they are in one reference Supabase build, supabase/postgres 17.6.1.106, check constraints included. Run [`npx prisma db verify`](/cli/db-verify) to compare your database with it: if your Supabase build has a different set of check constraints, `db verify` lists the ones it cannot find. You cannot fix that with a migration, because Prisma ORM never changes Supabase's own tables. Report the difference to Prisma instead, so the reference build can be updated.
+`@prisma/orm-extension-supabase` has a contract of its own, which describes Supabase's `auth` and `storage` tables, check constraints included. Prisma read those tables from one Supabase version, supabase/postgres 17.6.1.106, and a Supabase project on another version can have a different set of check constraints. [`npx prisma db verify`](/cli/db-verify) compares your database with the extension's contract as well as with yours, and when a check constraint the extension describes is missing from your database, `db verify` lists it and fails. You cannot fix that with a migration, because Prisma ORM never changes Supabase's own tables. Report the difference to Prisma instead, so the extension can be updated to match.
 
-[`npx prisma db sign`](/cli/db-sign) checks that a database matches your contract and then records in the database which contract it matches. When an update to `@prisma/orm-extension-supabase` changes the extension's contract, that record no longer matches, so run `npx prisma db sign` again against every database you signed with the earlier version. If you are also re-emitting your own contract with `npx prisma contract emit`, run that before `db sign`.
+[`npx prisma db sign`](/cli/db-sign) checks that a database matches your contract and then records in the database which contract it matches, and it records the extension's contract the same way. When an update to `@prisma/orm-extension-supabase` changes the extension's contract, that record no longer matches, and `npx prisma db verify` fails with `MIGRATION.CONTRACT_SPACE_VIOLATION` until you run `npx prisma db sign` again against every database you signed with the earlier version. The Prisma ORM release notes say when an update changes the extension's contract, as the notes for 8.0.0-rc.12 do. If you are also re-emitting your own contract with `npx prisma contract emit`, run that before `db sign`.
 
 :::
 
diff --git a/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx b/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx
index fc5e7da88e..81ccf52a17 100644
--- a/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/advanced-queries.mdx
@@ -312,7 +312,7 @@ All MongoDB aggregation happens here: the ORM API has no `.aggregate(...)` on Mo
 
 ### Build a pipeline and run it
 
-Start from a collection with `db.query.from(...)`, which takes the collection name as a string: the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. Every model above sets `@@map`, so the collections are `user`, `post`, `tag`, and `post_tag`. That is the same name the ORM API uses, as in `db.orm.post`.
+Start from a collection with `db.query.from(...)`, which takes the collection name as a string: the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. Every model above sets `@@map`, so the collections are `user`, `post`, `tag`, and `post_tag`. On MongoDB the ORM API uses the same name, as in `db.orm.post`.
 
 `acc` holds the aggregate functions you can use inside `.group(...)`, such as `acc.count()` and `acc.max(f.createdAt)`. In the pipeline builder, fields use their stored names, so the id is `_id` (see the note under the contract above), and `_id` is also the grouping key in `.group(...)`. On MongoDB `db.runtime()` returns a promise, so await it before you run anything. Chain stages, call `.build()`, and run the result:
 
diff --git a/apps/docs/content/docs/orm/fundamentals/transactions.mdx b/apps/docs/content/docs/orm/fundamentals/transactions.mdx
index 0a8dbf103d..d07b87c1f3 100644
--- a/apps/docs/content/docs/orm/fundamentals/transactions.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/transactions.mdx
@@ -119,9 +119,23 @@ await db.transaction(async (tx) => {
 });
 ```
 
-Under `tx.sql.public`, unlike under `tx.orm.public`, the property name is the table name: the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. So the model `Post` is `tx.sql.public.Post`, and a model with `@@map("post")` is `tx.sql.public.post`.
+`tx.orm` takes the model name and `tx.sql` takes the table name, which is the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. So the model `Post` is `tx.sql.public.Post`, and a model with `@@map("post")` is `tx.sql.public.post`.
+
 The other difference from `tx.orm` is that you chain clauses and then call `.build()` to finish the query: `.build()` returns the query without running it, and `tx.execute(...)` runs it and returns `{ affectedRows }`, the number of rows it changed. The `.where(...)` callback receives two arguments: `f` holds the columns, and `fns` holds the operators (`lt` is less-than). [Advanced queries](/orm/fundamentals/advanced-queries#build-a-query-and-run-it) covers both.
 
+To read rows, build a `SELECT` on `tx.sql` the same way and run it with `tx.query(...)`, which resolves to an array of rows:
+
+```typescript
+await db.transaction(async (tx) => {
+  const query = tx.sql.public.Post
+    .select("id", "title")
+    .where((f, fns) => fns.eq(f.published, false))
+    .limit(10)
+    .build();
+  const drafts = await tx.query(query);
+});
+```
+
 ## Transactions on MongoDB
 
 Prisma ORM does not support MongoDB transactions yet: there is no `db.transaction(...)` on the MongoDB client. To run a multi-document transaction today, use the MongoDB driver directly: share one `MongoClient` between Prisma ORM and your code, and group the writes in a driver session.
@@ -183,6 +197,8 @@ model User {
 }
 ```
 
+The `id` field has no `@default` because you never pass it: when you insert a document without an `_id`, MongoDB assigns one, and `insertOne` returns it as `insertedId`, which the example uses as the post's `authorId`.
+
 Writes you make through the driver skip the type-checking that Prisma ORM queries get, so put each driver transaction in its own small function, and write everything around it as Prisma ORM queries.
 
 ## Coming from Prisma ORM 7
diff --git a/apps/docs/content/docs/orm/fundamentals/writing-data.mdx b/apps/docs/content/docs/orm/fundamentals/writing-data.mdx
index 7b52bb2292..0f651ebcb3 100644
--- a/apps/docs/content/docs/orm/fundamentals/writing-data.mdx
+++ b/apps/docs/content/docs/orm/fundamentals/writing-data.mdx
@@ -12,7 +12,7 @@ Every example imports `db`. In a new project run `npm create prisma@latest -- my
 
 This page uses `db.orm`, which holds your models. The rest of `db` is `db.sql` for the SQL query builder, `db.raw.sql` for raw SQL, and `db.transaction` for running several writes together.
 
-On PostgreSQL the path to a model is `db.orm.<schema>.<ModelName>`, so the `User` model is `db.orm.public.User`. `public` is the PostgreSQL schema that holds the model's table, and the path always includes the schema name. The schema is `public` unless you put the model inside a `namespace` block, as [Example schema](#example-schema) shows. On MongoDB there is no schema segment, and the path is `db.orm.<collectionName>`, so the model below is `db.orm.users`. The collection name is the model's `@@map(...)`, or the model name exactly as written.
+On PostgreSQL the path to a model is `db.orm.<schema>.<ModelName>`, so the `User` model is `db.orm.public.User`. `public` is the PostgreSQL schema that holds the model's table, and the path always includes the schema name. The schema is `public` unless you put the model inside a `namespace` block, as [Example schema](#example-schema) shows. On MongoDB there is no schema segment, and the path is `db.orm.<collectionName>`, where the collection name is the model's `@@map(...)` value, or the model name when there is no `@@map`. The MongoDB `User` model in the example schema maps to `users`, so it is `db.orm.users`.
 
 ## Example schema
 
@@ -296,7 +296,7 @@ const deletedCount = await db.orm.public.Post.where((p) => p.title.ilike("draft%
 
 The `AndCount` methods return a plain number, so if three posts match, `updatedCount` is `3`, not an object.
 
-To insert many records and skip the ones that would break a unique constraint, pass `{ onConflict: "skip" }` as the second argument to `createAll` or `createAndCount`. That skips a record that breaks any unique constraint on the table. To skip only the records that clash on one constraint, add `conflictOn` to the same object with the names of that constraint's fields, as in `createAll(users, { onConflict: "skip", conflictOn: ["email"] })`. Here `conflictOn` takes field names, while in [`.upsert(...)`](#upsert-a-record) it takes the fields and their values. This replaces Prisma ORM 7's `skipDuplicates`, and it works on PostgreSQL and SQLite. `createAll` returns only the records the database wrote, and `createAndCount` counts only those. [`createAll()`](/orm/reference/orm-client#createall) in the reference covers the details.
+To insert many records and skip the ones that would break a unique constraint, pass `{ onConflict: "skip" }` as the second argument to `createAll` or `createAndCount`. That skips a record that breaks any unique constraint on the table. To skip only the records that clash on one constraint, add `conflictOn` to the same object with the names of that constraint's fields, as in `createAll(users, { onConflict: "skip", conflictOn: ["email"] })`. A record that clashes on any other unique constraint is not skipped, so the database rejects the insert and the call throws a unique-constraint error. Here `conflictOn` takes field names, while in [`.upsert(...)`](#upsert-a-record) it takes the fields and their values. This replaces Prisma ORM 7's `skipDuplicates`, and it works on PostgreSQL and SQLite. On MongoDB, `createAll` and `createAndCount` take only the records, with no second argument. `createAll` returns only the records the database wrote, and `createAndCount` counts only those. [`createAll()`](/orm/reference/orm-client#createall) in the reference covers the details.
 
 `.where((p) => p.title.ilike("draft%"))` is the callback form of a filter, for conditions an object cannot express. Its argument gives you one entry per field, and each field carries the comparisons you can apply to it. [Reading data](/orm/fundamentals/reading-data) covers the filters you can write.
 
diff --git a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
index 62cd1ab9ca..b3d9dbb833 100644
--- a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
+++ b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
@@ -51,7 +51,7 @@ The `name` is the label Prisma ORM uses when it talks about your middleware, so
 
 If a call gives you back a count instead of rows, `afterQuery` is not called for it and `afterExecute` is called instead. On the ORM API the calls that return a count are `createAndCount`, `updateAndCount`, and `deleteAndCount`. Every other call returns rows and reaches `afterQuery`, including `create`, `update`, `delete`, `updateAll`, and `deleteAll`.
 
-The SQL query builder is the other way to write a query on the same client, `db.sql.public.User...` in place of `db.orm.public.User...`. With it you build a query and run it in two steps: `.build()` gives you the query as a plain object, the plan, and a method on `db.runtime()` runs it. Which of the two methods you call decides which hook you get. `db.runtime().query(plan)` returns rows and reaches `afterQuery`, while `db.runtime().execute(plan)` reports how many rows the statement changed and reaches `afterExecute`.
+The SQL query builder is the other way to write a query on the same client, `db.sql.public.User...` in place of `db.orm.public.User...`. With it you build a query and run it in two steps: `.build()` gives you the query as a plain object, the plan, and a method on `db.runtime()` runs it. `db.runtime().query(plan)` returns rows and calls `afterQuery`, while `db.runtime().execute(plan)` reports how many rows the statement changed and calls `afterExecute`.
 
 To have the logger cover the counting calls as well, add a second hook to the object `queryLogger()` returns in `src/prisma/query-logger.ts`, next to `afterQuery`:
 
@@ -220,9 +220,9 @@ A hook you implement for one kind of call is never called for the other kind, so
 
 `beforeCompile` is where you change a query before it runs. It gives you the query as an AST, the abstract syntax tree, which is the query as a tree of typed objects rather than as text. A `SELECT` is one object whose `kind` is `'select'`, whose `from` is the table it reads, and whose `where` is its condition. The hook runs before Prisma ORM turns that tree into SQL text, so a changed tree changes the SQL that reaches the database.
 
-Its argument is called a draft because the SQL text does not exist yet. A draft has `ast`, the tree you change, and `meta`, which records where the query came from and which you pass through unchanged. You return a copy of the draft with a new `ast`, or `undefined` when there is nothing to change.
+Its argument is called a draft because the SQL text does not exist yet. A draft has `ast`, the tree you change, and `meta`, which you pass through unchanged. `meta.lane` says which API built the query: `'orm-client'` for the ORM API and `'dsl'` for the SQL query builder. You return a copy of the draft with a new `ast`, or `undefined` when there is nothing to change.
 
-The middleware below adds a condition to every `SELECT` on the `User` table:
+The middleware below adds a condition to every `SELECT` whose own `FROM` clause names the `User` table:
 
 ```ts title="src/prisma/scope-user-selects.ts"
 import type { SqlMiddleware } from '@prisma/orm-postgres/family-runtime';
@@ -269,13 +269,19 @@ export const db = postgres<Contract>({
 });
 ```
 
-Every `SELECT` on `User` now runs with `WHERE "User"."name" = $1` added, and a query that already had a `WHERE` clause keeps it, joined to yours with `AND`. The condition is built once, when you create the client, so every query on this client is filtered to the same value. Swap `name` for the column that holds your tenant and `'Mia'` for a tenant ID, and every `SELECT` on `User` through this client returns only that one tenant's rows.
+Every `SELECT` whose `FROM` clause names `User` now runs with `WHERE "User"."name" = $1` added, and a query that already had a `WHERE` clause keeps it, joined to yours with `AND`. The condition is built once, when you create the client, so every query on this client is filtered to the same value.
+
+:::warning
+
+Do not rely on this middleware alone to keep one tenant's rows away from another. If you swap `name` for a tenant column, a query that reads `User` in its own `FROM` clause returns only that tenant's rows, but `User` rows loaded with `.include(...)` or joined onto another table are not filtered, so they can belong to any tenant.
+
+:::
 
 Copy each import as it is written, including the one that says `type` and the one that does not.
 
-The id depends on the field's type in your contract:
+The `codecId` depends on the field's type in your contract:
 
-| Type in your contract | Id |
+| Type in your contract | `codecId` |
 | --- | --- |
 | `String` | `pg/text@1` |
 | `Int` | `pg/int4@1` |
@@ -285,7 +291,9 @@ The id depends on the field's type in your contract:
 | `DateTime` | `pg/timestamptz-temporal@1` |
 | `Uuid` | `pg/uuid@1` |
 
-For a field whose type is not in the table, read the id off your own client: `db.sql.public.User.columns.name.codecId` is the id for the `name` column of the `User` table, so print it from any script that imports `db`. [`fns.raw` and `.returns()`](/orm/reference/sql-query-builder#fnsraw-and-returns) lists the ids in one place.
+The `temporal` in the `DateTime` id means the value reaches your code as a JavaScript `Temporal.Instant` rather than a `Date`.
+
+For a field whose type is not in the table, read the `codecId` off your own client: `db.sql.public.User.columns.name.codecId` is the id for the `name` column of the `User` table, so print it from any script that imports `db`. [`fns.raw` and `.returns()`](/orm/reference/sql-query-builder#fnsraw-and-returns) lists the ids in one place.
 
 `BinaryExpr` has one method per comparison (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `in`, `notIn`), and `AndExpr.of` and `OrExpr.of` combine conditions. They all come from `@prisma/orm-postgres/relational-core/ast`, so your editor lists them once you import from there.
 
@@ -301,7 +309,7 @@ async onRow(row) {
 },
 ```
 
-For the `SELECT` in step 3, whose SQL is `SELECT "User"."id" AS "id", "User"."email" AS "email" FROM "public"."User" LIMIT 5`, a row object has an `id` key holding a number and an `email` key holding a string. The fixture below returns one row of that shape, and you register it the same way as the logger, with `middleware: [userFixture()]`:
+For the `SELECT` in step 3, whose SQL is `SELECT "User"."id" AS "id", "User"."email" AS "email" FROM "public"."User" LIMIT 5`, a row object has an `id` key holding a number and an `email` key holding a string. The middleware below is a test fixture: it returns one made-up row of that shape in place of the database's answer, so a test can run that query without data in the table. Add it to the same `middleware` array as the logger, either on its own as `middleware: [userFixture()]` or next to the logger as `middleware: [queryLogger(), userFixture()]`:
 
 ```ts title="src/prisma/user-fixture.ts"
 import type { SqlMiddleware } from '@prisma/orm-postgres/family-runtime';
@@ -324,9 +332,9 @@ export function userFixture(): SqlMiddleware {
 
 Prisma ORM decodes the rows you return the same way it decodes rows that came from the database, so your caller gets the types the contract gives those columns, even though you handed back plain driver values.
 
-The last three checks answer only a `SELECT` that reads the `User` table directly, in the same way the `beforeCompile` example picks its queries. Matching on the SQL text instead, such as `plan.sql.includes('FROM "public"."User"')`, also catches `DELETE FROM "public"."User"`, so an ORM `.delete()` would get a made-up row back and delete nothing. On an `UPDATE` or a `DELETE` the table name is at `plan.ast.table.name`. A hook cannot tell which model or which ORM call a query came from, so the table name in the tree is the only thing you have to match on.
+The last three checks make the fixture answer only a `SELECT` that reads the `User` table directly, in the same way the `beforeCompile` example picks its queries. Matching on the SQL text instead, such as `plan.sql.includes('FROM "public"."User"')`, also catches `DELETE FROM "public"."User"`, so an ORM `.delete()` would get a made-up row back and delete nothing. On an `UPDATE` or a `DELETE` the table name is at `plan.ast.table.name`. `plan.meta.lane` tells you which API built a query, but nothing on the plan says which model or which ORM call it came from, so the table name in the tree is the only thing you have to match on.
 
-The first check, on `ctx.scope`, leaves queries inside a transaction to the database, as the cache does. An ORM `.update()` or `.delete()` first reads the row it is about to change, inside a transaction, and if the fixture answered that read, the write would go to the row whose `id` is `1` rather than the row you asked for. [The context object](#the-context-object) covers `ctx.scope`.
+The first check, on `ctx.scope`, lets every query inside a transaction, or on a connection you took from the pool, go on to the database, so the fixture answers only queries sent on `db` directly. Keep it, because an ORM `.update()` or `.delete()` reads its row inside a transaction before it writes, and a made-up row there would send the write to the wrong row.
 
 Return `undefined` and the query carries on to the database as usual. When several middleware implement `interceptQuery`, the first one in the array that returns rows answers the query and the rest are not called at all. `afterQuery` still runs either way, with `result.source` set to `'middleware'`, so your logging can tell which queries were answered without a trip to the database. For a call that returns a count, `interceptExecute` does the same job and returns `{ stats }`, which only ever holds `affectedRows`, as in `{ stats: { affectedRows: 0 } }`. The [cache middleware](/orm/middleware/built-in-cache) is the implementation to copy from.
 
@@ -405,7 +413,7 @@ Timing itself does not need any of this, because `result.latencyMs` already tell
 Projects created with `npm create prisma@latest` install [Prisma ORM skills](/ai/tools/skills#available-skills-for-prisma-8) for your coding agent, so you can ask it for the middleware built in the steps above:
 
 - "Write a Prisma ORM middleware that logs every query slower than 250ms, and register it before budgets."
-- "Add a beforeCompile middleware that scopes every SELECT on the User table to the current tenant."
+- "Add a beforeCompile middleware that adds a fixed `orgId` condition to every SELECT that reads the User table in its FROM clause."
 - "Write an interceptQuery middleware that returns fixture rows for the products table in tests."
 
 ## Next steps
diff --git a/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx b/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx
index f6fc218cf3..435baf4db6 100644
--- a/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx
+++ b/apps/docs/content/docs/orm/middleware/built-in-budgets.mdx
@@ -55,7 +55,9 @@ The built-in middleware is imported from `@prisma/orm-postgres/family-runtime`,
 
 The example sets `maxRows`, `defaultTableRows`, and `maxLatencyMs` to the values they already take by default, so that you can see where each one goes, and you can leave all three out. Set `maxRows` and `maxLatencyMs` to the largest number of rows and the longest time any single query in your app should ever need, because they are there to catch mistakes rather than to tune anything.
 
-The two numbers in `tableRows` are placeholders for how many rows your own tables really hold, so a `Post` table with two million rows in it is written `tableRows: { Post: 2_000_000 }`. A `count` from the database is enough to get each number, such as `select count(*) from "public"."User";` for the `User` table, and you can leave `tableRows` out altogether, in which case every table is assumed to hold `defaultTableRows` rows. Each key is the table name as it is in the database: the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. So the model `User` is keyed `User`, not `public.User`. If you misspell a table name, `budgets` silently uses `defaultTableRows` for that table and never warns you.
+Every `SELECT` needs a `LIMIT` anyway, but a limit can still be larger than `maxRows`. The check before the query knows how big a table is only from the number you give it in `tableRows`, so with a real number there, a query like that on a big table fails before it runs rather than part way through reading its rows, as [Common gotchas](#common-gotchas) shows. The two numbers in the example are placeholders for how many rows your own tables really hold, so a `Post` table with two million rows in it is written `tableRows: { Post: 2_000_000 }`. A `count` from the database is enough to get each number, such as `select count(*) from "public"."User";` for the `User` table, and you can leave `tableRows` out altogether, in which case every table is assumed to hold `defaultTableRows` rows.
+
+Each key is the table name as it is in the database: the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. So the model `User` is keyed `User`, not `public.User`. `budgets` looks a table up by its name alone, so two tables with the same name in different PostgreSQL schemas share one key and one number. If you misspell a table name, `budgets` silently uses `defaultTableRows` for that table and never warns you.
 
 Passing `budgets` to a MongoDB client throws an error whose `code` is `RUNTIME.MIDDLEWARE_FAMILY_MISMATCH` the first time that client is used, before any query of yours runs, and there is no MongoDB version of `budgets` to use instead.
 
@@ -150,7 +152,20 @@ The check that runs before your query never asks the database how big your table
 
 Say `maxRows` is `10_000` and you listed `User` at 5,000 rows, but the table really holds 5 million. A query with `.limit(50_000)` on it is estimated at 5,000 rows, because `budgets` takes the smaller of your limit and the size you gave for the table, so it passes the first check. The database then starts sending 50,000 rows and the count check throws at row 10,001, part way through your read.
 
-When a query that used to work starts failing with `source: 'observed'`, the table has grown past the number you gave for it in `tableRows`. Put a fresh count there, and the check before the query then stops that query with `source: 'ast'` before the database does any work, rather than part way through the read. The query is still over budget either way, because its limit is larger than `maxRows`. To make it run, lower its `.limit(...)` to `maxRows` or less and read the rest a page at a time, or raise `maxRows`.
+When a query that used to work starts failing with `source: 'observed'`, the table has grown past the number you gave for it in `tableRows`. Put a fresh count there, and the check before the query then stops that query with `source: 'ast'` before the database does any work, rather than part way through the read. The query is still over budget either way, because its limit is larger than `maxRows`. To make it run, raise `maxRows`, or lower its `.limit(...)` to `maxRows` or less and read the rest a page at a time with `.offset(...)`, as [Sort and paginate](/orm/fundamentals/reading-data#sort-and-paginate) describes:
+
+```ts
+const pageSize = 10_000;
+for (let offset = 0; ; offset += pageSize) {
+  const page = await db.orm.public.User
+    .orderBy((u) => u.id.asc())
+    .limit(pageSize)
+    .offset(offset)
+    .all();
+  // handle this page of rows
+  if (page.length < pageSize) break;
+}
+```
 
 :::
 
diff --git a/apps/docs/content/docs/orm/middleware/built-in-lints.mdx b/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
index 0c5f8433f8..258066986b 100644
--- a/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
+++ b/apps/docs/content/docs/orm/middleware/built-in-lints.mdx
@@ -55,13 +55,13 @@ The rules are named after the SQL they are about, and you write your queries in
 | `.all()` with no `.limit(...)` before it | `LINT.NO_LIMIT` |
 | `.first(...)` | none, because it adds `LIMIT 1` for you |
 | a query where you never called `.select(...)` | `LINT.SELECT_STAR` |
-| `deleteAll()` or `updateAll()` after a `.where(...)` with a condition in it | none |
-| `deleteAll()` or `updateAll()` after `.where({})` | `LINT.DELETE_WITHOUT_WHERE` or `LINT.UPDATE_WITHOUT_WHERE` |
+| `deleteAll()`, `deleteAndCount()`, `updateAll()`, or `updateAndCount()` after a `.where(...)` with a condition in it | none |
+| `deleteAll()`, `deleteAndCount()`, `updateAll()`, or `updateAndCount()` after `.where({})` | `LINT.DELETE_WITHOUT_WHERE` or `LINT.UPDATE_WITHOUT_WHERE` |
 | the query builder's `delete()` or `update()` with no `where()` | `LINT.DELETE_WITHOUT_WHERE` or `LINT.UPDATE_WITHOUT_WHERE` |
 
-So `await db.orm.public.User.limit(50).all()` sets off `LINT.SELECT_STAR`, while `await db.orm.public.User.select('id', 'email').limit(50).all()` does not. In `db.orm.public.User`, `public` is the PostgreSQL schema and `User` is your model name. The SQL query builder reaches the same table by its name in the database, as `db.sql.public.User`. The model and the table have the same name here because the model sets no `@@map`.
+So `await db.orm.public.User.limit(50).all()` sets off `LINT.SELECT_STAR`, while `await db.orm.public.User.select('id', 'email').limit(50).all()` does not. In `db.orm.public.User`, `public` is the PostgreSQL schema and `User` is your model name. The SQL query builder reaches the same table by its name in the database, as `db.sql.public.User`. These examples assume a `User` model with no `@@map`, so the table has the same name as the model.
 
-For a `warn` finding, `lints` builds the record below, with the code of the rule, a message, and the table the query touched, and passes it to the client's logger. The `postgres(...)` client has no logger you can set yet, as the note above says, so today the record is thrown away and you cannot see it anywhere.
+Today a `warn` rule has no visible effect. `lints` builds a record like the one below, with the code of the rule, a message, and the table the query touched, and passes it to the client's logger, but the `postgres(...)` client has no logger you can set yet, as the note above says, so the record is thrown away.
 
 ```text title="Lint warning"
 warn {
@@ -154,11 +154,11 @@ await db.runtime().query(plan);
 
 It throws an error whose `code` is `LINT.SELECT_STAR` and whose `message` is `Raw SQL plan selects all columns via *`. `returnsRow` tells Prisma ORM the type of each column the statement gives back, written as `pg/` plus the PostgreSQL type name plus `@1`, and [`fns.raw` and `.returns()`](/orm/reference/sql-query-builder#fnsraw-and-returns) lists the ids you can use. The `severities` key for the last rule is `readOnlyMutation`, and there is no documented way to mark a query read-only, so you are unlikely to see that one.
 
-Because these are searches through the text rather than checks on the structure of the query, they can be wrong in both directions. The word `limit` anywhere in the statement counts as a `LIMIT`, including inside a string or a column name, and a `select *` inside a subquery counts for the whole statement. So when a raw statement produces a finding, go and read the query yourself before you change anything.
+Because these are searches through the text rather than checks on the structure of the query, they can be wrong in both directions. The word `limit` anywhere in the statement counts as a `LIMIT`, including inside a string or a column name, and a `select *` inside a subquery counts for the whole statement. So when a raw statement sets off one of these checks, go and read the query yourself before you change anything.
 
 :::warning
 
-A severity you set in `severities` applies to a finding by its code wherever that finding came from, so it changes the raw defaults as well as the four rules. `selectStar` is `warn` by default for the ORM API and the SQL query builder, but `error` for raw SQL. So setting `selectStar: 'warn'` changes nothing for the ORM API, which is already at `warn`: its only effect is that raw SQL's `select *` drops from `error` to `warn`, and `select * from "User"` starts running instead of being blocked. Setting `selectStar: 'error'`, as under [Configure severities](#configure-severities), keeps a raw `select *` blocked. No setting makes the ORM-API rule `error` and lets a raw `select *` run, so if you need both, give the code that runs the raw `select *` a `db` client of its own, in the way [Common gotchas](#common-gotchas) does for a backfill script.
+One `severities` key sets both the rule for the ORM API and the SQL query builder and the raw SQL check that has the same code, so it changes the raw defaults as well. `selectStar` is `warn` by default for the ORM API and the SQL query builder, but `error` for raw SQL. So setting `selectStar: 'warn'` changes nothing for the ORM API, which is already at `warn`: its only effect is that raw SQL's `select *` drops from `error` to `warn`, and `select * from "User"` starts running instead of being blocked. Setting `selectStar: 'error'`, as under [Configure severities](#configure-severities), keeps a raw `select *` blocked. No setting makes the ORM-API rule `error` and lets a raw `select *` run, so if you need both, give the code that runs the raw `select *` a `db` client of its own, in the way [Common gotchas](#common-gotchas) does for a backfill script.
 
 :::
 
diff --git a/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx b/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
index 5015c56cc0..5e2567f6b8 100644
--- a/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
+++ b/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
@@ -123,9 +123,9 @@ Prisma ORM calls your middleware in the order you listed them in the `middleware
 
 ### beforeCompile: rewrite the query
 
-Reach for `beforeCompile` when you want to change what a query asks for rather than only look at it. It runs on both kinds of query, and it hands you a draft with two fields: `meta`, the metadata Prisma ORM keeps about the query, and `ast`, the query as a tree of typed objects. The tree is the part you can change, because the SQL text has not been written yet. Return a copy of the draft with a changed `ast` and Prisma ORM runs your version instead, which is how you add a tenant filter to every `SELECT` without editing a single call site. Return `undefined` and the query goes through as written.
+Reach for `beforeCompile` when you want to change what a query asks for rather than only look at it. It runs on both kinds of query, and it hands you a draft with two fields: `meta`, the metadata Prisma ORM keeps about the query, and `ast`, the query as a tree of typed objects. The tree is the part you can change, because the SQL text has not been written yet. Return a copy of the draft with a changed `ast` and Prisma ORM runs your version instead, which is how you add a condition to queries without editing a single call site. Return `undefined` and the query goes through as written.
 
-The middleware below adds a condition to every `SELECT` that reads the `User` table:
+The middleware below adds a condition to every `SELECT` whose own `FROM` clause names the `User` table:
 
 ```ts title="src/prisma/scope-user-selects.ts"
 import type { SqlMiddleware } from '@prisma/orm-postgres/family-runtime';
@@ -149,6 +149,8 @@ export function scopeUserSelects(predicate: BinaryExpr): SqlMiddleware {
 
 The three checks above are how you say "only `SELECT`s, and only ones over the `User` table". `draft.ast.kind` is `'select'`, `'insert'`, `'update'`, `'delete'`, or `'raw-query'`, and `draft.ast.from.kind` is `'table-source'` when a `SELECT` reads a plain table rather than a subquery or a function. Use the table name as it is in your database rather than the model name in your contract. They are the same, `User`, unless the model sets `@@map`, in which case use the name it maps to. `withWhere` returns a new `SELECT` with that `WHERE` on it and leaves the original alone, which is why the hook returns a copy of the draft.
 
+These checks read only the table in the query's own `FROM` clause, so `User` rows that a query loads with `.include(...)` or through a join are not filtered. Do not rely on a middleware like this alone to keep one tenant's rows away from another.
+
 The `predicate` you pass in is a comparison you build yourself, and the types for building one come from `@prisma/orm-postgres/relational-core/ast`. A value you compare against needs its `codecId`, which says how the value is stored: `pg/` plus the PostgreSQL type name plus `@1`, so text is `pg/text@1` and a 32-bit integer is `pg/int4@1`:
 
 ```ts title="src/prisma/db.ts (excerpt)"
@@ -208,7 +210,7 @@ The rows you return are plain objects, keyed by the column aliases in the SQL, h
 { id: 3, email: 'mia+1@prisma.io', createdAt: '2026-09-17 08:00:08.775+00' }
 ```
 
-So for a query whose SQL is `SELECT "User"."id" AS "id", "User"."email" AS "email" FROM "public"."User" LIMIT 5`, `return { rows: [{ id: 1, email: 'mia@prisma.io' }] }` is a complete answer to it. Prisma ORM converts the rows you return the same way it converts rows from the database, so a `createdAt` you return as a string reaches a caller on the ORM API as the type its contract gives `createdAt`, not as a string. This is how the cache serves repeated reads.
+So for a query whose SQL is `SELECT "User"."id" AS "id", "User"."email" AS "email" FROM "public"."User" LIMIT 5`, `return { rows: [{ id: 1, email: 'mia@prisma.io' }] }` is a complete answer to it. Prisma ORM converts the rows you return the same way it converts rows from the database, so a `createdAt` you return as a string reaches a caller on the ORM API as a `Temporal.Instant`, the type a `DateTime` field has, not as a string. This is how the cache serves repeated reads.
 
 Before-hooks still run on a query that an intercept hook answers, because every middleware's before-hooks run before any intercept hook, whatever order you list the middleware in. So in the setup at the top of this page, where the cache comes first in the array, `lints` still checks every query before the cache answers it.
 
diff --git a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
index 1055d71121..f54f20403d 100644
--- a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
@@ -47,6 +47,8 @@ npx prisma db migrate --show --db "$PRODUCTION_DATABASE_URL"
 npx prisma db migrate --db "$PRODUCTION_DATABASE_URL"
 ```
 
+The output in the rest of this section comes from an earlier point in the same project than the run at the top of this page: the newest migration is `add_user_phone`, and the production database has applied only `init`, so `add_user_phone` is pending.
+
 `npx prisma migration status --db "$PRODUCTION_DATABASE_URL"` never changes the database, so you can run it against production whenever you want to know which contract state that database matches. It draws your migration history, marks each migration as applied or pending, and shows which contract state the database matches:
 
 ```text
@@ -139,17 +141,19 @@ npx prisma db migrate --advance-ref db
 
 In development, add `--advance-ref db` so the next `migration plan` starts from what you just applied, and leave the flag off in CI and production, where you never plan a migration anyway. [The db ref](/orm/migrations/generating-a-migration#the-db-ref-skipping---from) covers what happens without it and how to fix a missed flag. If you edit `migration.ts` while reviewing the migration, recompile it with `node migrations/app/<dir>/migration.ts` before you apply, as [Editing a migration](/orm/migrations/editing-a-migration) explains.
 
-**In CI and production**, you never plan a migration, because migrations arrive through your repository, already reviewed and merged. For that to work, commit these files:
+**In CI and production**, you never plan a migration, because migrations arrive through your repository, already reviewed and merged. For that to work, commit the whole `migrations/` directory and your contract files, which means:
 
 - each migration's directory under `migrations/app/`
+- the refs in `migrations/app/refs/`, such as `prod.json`, which `db migrate --to prod` reads
 - the directories `migration plan` added under `migrations/snapshots/`, one per contract state
+- one directory per [extension package](#extension-spaces) that ships migrations, such as `migrations/pgvector/`
 - `contract.prisma`, `contract.json`, and `contract.d.ts`
 
-Deploy with the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed.
+When you deploy by hand, run the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed. In a pipeline, the job runs only the last of them, `db migrate`, with `--to <ref>`, which that section explains.
 
-When a migration's files no longer match the hash stored when it was written, `migration check` fails with an error whose `code` is `MIGRATION.CHECK_HASH_MISMATCH`, as [Editing a migration](/orm/migrations/editing-a-migration) explains. To fix it, either restore the migration's files from Git, or move the hand edit into `migration.ts` and recompile.
+When a migration's `ops.json` or `migration.json` no longer matches the `migrationHash` in its `migration.json`, `migration check` fails with an error whose `code` is `MIGRATION.CHECK_HASH_MISMATCH`, as [Editing a migration](/orm/migrations/editing-a-migration) explains. To fix it, either restore the migration's files from Git, or move the hand edit into `migration.ts` and recompile. If the error comes back right after you recompile, and the migration's backfill updates a model with a `temporal.updatedAtString()` column, recompiling cannot fix it, and [Editing a migration](/orm/migrations/editing-a-migration#worked-example-making-a-column-required) shows how to write that backfill instead.
 
-When a contract snapshot under `migrations/snapshots/` no longer matches the hash in its directory name, `migration check` fails with `MIGRATION.CHECK_SNAPSHOT_CONTENT_MISMATCH`. A command that needs that snapshot, such as `migration plan --from` or `migration ref set` naming its contract state, stops with `MIGRATION.CONTRACT_SNAPSHOT_CONTENT_MISMATCH`. Recompiling `migration.ts` does not fix this, so restore the edited snapshot from Git. MongoDB snapshots are not checked yet.
+When a contract snapshot under `migrations/snapshots/` no longer matches the hash in its directory name, `migration check` fails with an error whose `code` is `MIGRATION.CHECK_SNAPSHOT_CONTENT_MISMATCH`. Other commands that read that snapshot, such as `migration plan --from <that state>` or `migration ref set prod <that state>`, fail with a different code, `MIGRATION.CONTRACT_SNAPSHOT_CONTENT_MISMATCH`. Recompiling `migration.ts` fixes neither error, so restore the edited snapshot from Git. MongoDB snapshots are not checked yet.
 
 If two deployments can run at once, what happens next depends on your database. On PostgreSQL, when two `db migrate` runs start against the same database, one of them waits for the other. On MongoDB, if another run updates the marker while yours is running, yours fails with `Marker was modified by another process during migration execution.` When that happens, run `npx prisma migration status` to see which contract state the database matches, and then run `db migrate` again.
 
diff --git a/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx b/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
index 97057aad60..e73f5387d7 100644
--- a/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
@@ -40,7 +40,7 @@ to:         866ab885a8a4bd8d9f5adc47784c068be7895a7182c55cc29f9f9967d3019484
 app space:  migrations/app/20260707T1008_add_display_name
 ```
 
-In that output, `self-emit` is what the CLI calls recompiling, and `app space` is the directory the new migration was written to. `migration plan` writes the change as three steps rather than one, because the column is required and the table already has rows: `addColumn` adds the column as nullable, `dataTransform` holds the backfill you write, and `setNotNull` makes the column required:
+In that output, `self-emit` is what the CLI calls recompiling, and `app space` is the directory the new migration was written to. `migration plan` writes the change as three steps rather than one, because rows that already exist need a value for the new required column: `addColumn` adds the column as nullable, `dataTransform` holds the backfill you write, and `setNotNull` makes the column required:
 
 ```ts title="migration.ts (as planned)"
 override get operations() {
@@ -153,7 +153,7 @@ The way out is to write the backfill against a contract of your own rather than
 
 ## When a backfill reads a column the migration removes
 
-Sooner or later a backfill has to read a column that the same migration takes away. Suppose the next migration replaces the boolean `isAdmin` on `User` with a required text column, `role`. Change your contract, run `npx prisma contract emit`, and plan the migration as in the `displayName` example. The backfill reads `isAdmin` to decide each row's `role`, and that is where the trouble starts, because the end contract has no `isAdmin` and the start contract has no `role`. If you build `db` from the end contract, TypeScript rejects `f.isAdmin`, and recompiling fails with an error that does not name the column, so the cause is hard to spot.
+Sooner or later a backfill has to read a column that the same migration takes away. Suppose the next migration replaces the boolean `isAdmin` on `User` with a required text column, `role`. Change your contract, run `npx prisma contract emit`, and plan the migration with `npx prisma migration plan --name replace_is_admin`. The examples below use the directory that command printed, `migrations/app/20260708T0900_replace_is_admin`, and yours has a different timestamp. The backfill reads `isAdmin` to decide each row's `role`, and that is where the trouble starts, because the end contract has no `isAdmin` and the start contract has no `role`. If you build `db` from the end contract, TypeScript rejects `f.isAdmin`, and recompiling fails with an error that does not name the column, so the cause is hard to spot.
 
 What you need instead is a contract that describes the database as it is while the backfill runs, and you write that one yourself. Copy your whole contract into the migration directory as `intermediate.prisma`, then in its `User` model add `isAdmin` back and make `role` optional, because at that point no row has a `role` yet.
 
@@ -172,7 +172,7 @@ model User {
 
 Keep `// use prisma-8` as the first line of the copy. `contract emit` skips any `.prisma` file that does not start with it, and because `intermediate.prisma` is the only file in the intermediate contract, emitting it without that line fails with an error whose `code` is `CONTRACT.SOURCE_LOAD_FAILED`.
 
-In the same migration directory, add `intermediate.config.ts`, a second config file. Its `contract` is `intermediate.prisma`, and it has no `db` setting, because emitting a contract never connects to a database. `parent: false` makes the CLI use this file on its own. Without it, the CLI also loads your project's `prisma.config.ts` and adds that file's `orm` settings, such as `db`, to the ones written here:
+In the same migration directory, add `intermediate.config.ts`, a second config file. Its `contract` is `intermediate.prisma`, and it has no `db.connection`, because emitting a contract never connects to a database. `parent: false` keeps this config apart from your project's config. Without it, the CLI also reads your project's `prisma.config.ts`, because that file is in a directory above this one, and takes from it every `orm` setting this file leaves out, such as `db.connection`:
 
 ```ts title="intermediate.config.ts"
 import { definePrismaConfig } from 'prisma/config';
@@ -180,7 +180,7 @@ import { defineConfig as ormConfig } from '@prisma/orm-postgres/config';
 export default definePrismaConfig({ parent: false, orm: ormConfig({ contract: './intermediate.prisma' }) });
 ```
 
-Emit the intermediate contract with `--config` pointing at that file. A relative path in a config file resolves from the directory of that file, so `./intermediate.prisma` is found wherever you run the command from:
+Emit the intermediate contract with `--config` pointing at that file. Run this from your project root, because the `--config` path starts there. The `./intermediate.prisma` path inside the config resolves from the directory the config file is in, so it names the copy in the migration directory:
 
 ```bash
 npx prisma contract emit --config migrations/app/20260708T0900_replace_is_admin/intermediate.config.ts
@@ -198,14 +198,14 @@ The command writes `intermediate.json` and `intermediate.d.ts` next to `intermed
 └── ops.json
 ```
 
-Now fill in this migration's own planned `migration.ts`, rather than copying the `displayName` file, whose snapshot imports point at other contracts. The listing below builds `db` from the intermediate contract and passes that same contract to `dataTransform`, and those two have to be the same contract: if you pass a different one, `node migration.ts` fails with an error whose `code` is `MIGRATION.DATA_TRANSFORM_CONTRACT_MISMATCH`. The listing also moves the planned `dropColumn` for `isAdmin` to after the backfill, so `isAdmin` is still there when the backfill reads it, and its two `run` callbacks run in the order you list them, so the second one sets `member` only on the rows the first one left empty.
+Now fill in this migration's own planned `migration.ts`, rather than copying the `displayName` file, whose snapshot imports point at other contracts. In the listing, `<start hash>` and `<end hash>` stand for the hashes your planned file already imports, so keep those imports as they are. The listing below builds `db` from the intermediate contract and passes that same contract to `dataTransform`, and those two have to be the same contract: if you pass a different one, `node migration.ts` fails with an error whose `code` is `MIGRATION.DATA_TRANSFORM_CONTRACT_MISMATCH`. The listing also moves the planned `dropColumn` for `isAdmin` to after the backfill, so `isAdmin` is still there when the backfill reads it, and its two `run` callbacks run in the order you list them, so the second one sets `member` only on the rows the first one left empty.
 
 ```ts title="migration.ts (filled in)"
 #!/usr/bin/env -S node
 import type { Contract as End } from '../../snapshots/<end hash>/contract';
 import endContractJson from '../../snapshots/<end hash>/contract.json' with { type: 'json' };
-import type { Contract as Start } from '../../snapshots/866ab885a8a4bd8d9f5adc47784c068be7895a7182c55cc29f9f9967d3019484/contract';
-import startContractJson from '../../snapshots/866ab885a8a4bd8d9f5adc47784c068be7895a7182c55cc29f9f9967d3019484/contract.json' with { type: 'json' };
+import type { Contract as Start } from '../../snapshots/<start hash>/contract';
+import startContractJson from '../../snapshots/<start hash>/contract.json' with { type: 'json' };
 import type { Contract as Mid } from './intermediate';
 import midContractJson from './intermediate.json' with { type: 'json' };
 import { Migration, MigrationCLI, col } from '@prisma/orm-postgres/migration';
@@ -296,12 +296,16 @@ override get operations() {
 
 Not every migration comes from a contract change. When you want a data-only migration, which changes rows and leaves your contract state as it is, or a migration you intend to write entirely by hand, run `npx prisma migration new`. It writes an empty `ops.json`, a `migration.json`, and a `migration.ts` that already has the snapshot imports, the class, and an empty `operations` array. Nothing was planned for you, so there is no `placeholder` import to remove, but you do have to add the `@prisma/orm-postgres` imports and the `endContract`, `stack`, and `db` statements from the filled-in `displayName` listing.
 
-`migration new` always ends at the contract state in your `contract.json`, and a data-only migration starts there too, so you pass that state's hash with `--from`. If you leave `--from` off, `migration new` starts from the `db` ref, and when the ref already names your current contract, as it does after `npx prisma db migrate --advance-ref db`, the command stops with an error whose `code` is `MIGRATION.NO_CHANGES`. `--from` takes the contract hash in the `to` field of an existing migration's `migration.json`, or the first few characters of it. To find your current contract's hash, run `npx prisma migration graph` and look for the row labelled `@contract`. It shows the first 7 characters of the hash, and you can pass those to `--from`. The [`migration new` reference](/cli/migration-new) lists the rest of the options:
+`migration new` always ends at the contract state in your `contract.json`, and a data-only migration starts there too, so you pass that state's hash with `--from`. `--from` takes the contract hash in the `to` field of an existing migration's `migration.json`, or any start of that hash that matches only one migration's `to` hash.
+
+To find your current contract's hash, run `npx prisma migration graph` and look for the row labelled `@contract`. It shows the first 7 characters of the hash, and you can pass those 7 characters to `--from`. The [`migration new` reference](/cli/migration-new) lists the rest of the options:
 
 ```npm
 npx prisma migration new --name backfill_scores --from <hash>
 ```
 
+If you leave `--from` off, `migration new` starts from the `db` ref, and after `npx prisma db migrate --advance-ref db` that ref names your current contract, so the migration would start and end at the same state. `migration new` refuses that case only when you leave `--from` off: it stops with an error whose `code` is `MIGRATION.NO_CHANGES`, which tells you to change your contract first, or to pass `--from` if you want a data-only migration. Passing the same hash with `--from` is how you tell it that starting and ending at the same state is what you want.
+
 Write your operations in the new `migration.ts` and recompile it. Until you do, the migration is still the empty one the command wrote, so `npx prisma migration check` and `npx prisma migration plan` both fail.
 
 ## Editing checklist
diff --git a/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx b/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
index 0fa64a20e0..27900c3013 100644
--- a/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
@@ -26,7 +26,7 @@ model User {
 }
 ```
 
-Keep `// use prisma-8` as the first line of every `.prisma` file in your contract. `contract emit` and the Prisma editor extension read only the `.prisma` files that start with it and skip the others without a warning, and when no file starts with it, `contract emit` fails with an error whose `code` is `CONTRACT.SOURCE_LOAD_FAILED`.
+Keep `// use prisma-8` as the first line of `contract.prisma`, and of every other `.prisma` file if you [split your contract across several files](/orm/contract-authoring/psl-syntax#split-the-contract-across-several-files). `contract emit` and the Prisma editor extension read only the `.prisma` files that start with it and skip the others without a warning, and when no file starts with it, `contract emit` fails with an error whose `code` is `CONTRACT.SOURCE_LOAD_FAILED`.
 
 Run both commands, passing `--name init` so that the new migration directory is named `<timestamp>_init`:
 
diff --git a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
index 4bb23281c7..e717d7302e 100644
--- a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
+++ b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
@@ -19,7 +19,7 @@ You run this loop many times a day:
 3. **Review it**: before anything touches the database, run `npx prisma migration show <dir>` to see the operations and SQL that `db migrate` will run. If you want the migration to change rows as well, [edit `migration.ts` and recompile it](/orm/migrations/editing-a-migration) by running `node migrations/app/<dir>/migration.ts` from your project root, which rewrites `ops.json`. Nothing extra is needed to run that file, because the Prisma ORM CLI already requires Node.js 22.18 or later, which runs `migration.ts` directly.
 4. **Apply it**: `db migrate` starts by reading the database's marker, the record in the database of which contract state it matches, so it knows how much of your history the database has already seen, and then runs the migrations from that state to your current contract. In development, add [`--advance-ref db`](/orm/migrations/generating-a-migration#the-db-ref-skipping---from) so the next `migration plan` starts from what you just applied.
 
-Say your contract is the one in [Generating a migration](/orm/migrations/generating-a-migration#your-first-migration), whose `User` model is stored in the table `user` because it sets `@@map("user")`, and its first migration is applied. With a database connection set up, as in the [quickstart](/prisma-orm/quickstart/postgresql), add an optional `phone String?` field to `User`, then run:
+Say your contract is the one in [Generating a migration](/orm/migrations/generating-a-migration#your-first-migration), whose `User` model is stored in the table `user` because it sets `@@map("user")`, and you applied its first migration with `npx prisma db migrate --advance-ref db`. With a database connection set up, as in the [quickstart](/prisma-orm/quickstart/postgresql), add an optional `phone String?` field to `User`, then run:
 
 ```npm
 npx prisma contract emit
@@ -47,14 +47,6 @@ ALTER TABLE "public"."user" ADD COLUMN "phone" text;
 
 A table name is the model name exactly as written unless the model sets `@@map`, so without `@@map("user")` this `User` model would be the table `"User"`, and a `UserProfile` model is the table `"UserProfile"`. These are the same names Prisma ORM 7 used.
 
-If you used a Prisma ORM 8 release before 8.0.0-rc.12, you have one more thing to do before you plan, because in those releases a model without `@@map` named its table with a lowercase first letter, such as `"userProfile"`. If your tables were created with those names, download the [`add-model-map` script](https://github.com/prisma/orm/blob/v8.0.0-rc.12/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.11-to-8.0.0-rc.12/scripts/psl-verbatim-table-names/add-model-map.mjs) and run it from your project root before you plan:
-
-```bash
-node <path to add-model-map.mjs> '**/*.prisma'
-```
-
-The script adds `@@map("<current table name>")` to each model that has none, in every `.prisma` file in your project, including any you keep in a migration directory. If you plan without running it, `migration plan` stops with [`MIGRATION.TABLE_NAME_CASE_CHANGED`](/orm/reference/error-reference#MIGRATION.TABLE_NAME_CASE_CHANGED) instead of dropping the table and creating an empty one.
-
 The `app space:` line tells you which migration history the new directory was written into. A contract space is a separate migration history, so your own migrations stay in `migrations/app/` while each [Prisma ORM extension package](/orm/migrations/applying-a-migration#extension-spaces) that ships migrations, such as pgvector, keeps its migrations in its own directory under `migrations/`.
 
 `db migrate` applies the migration and confirms what it applied:
@@ -67,6 +59,19 @@ The first time you run `migration plan`, there are no migrations and no `db` ref
 
 `db migrate` needs a database to talk to, and it takes that from `db.connection` in [`prisma.config.ts`](/orm/contract-authoring/the-data-contract), such as `db: { connection: process.env["DATABASE_URL"]! }`, unless you pass a URL with the `--db` flag. In CI and production, run plain `npx prisma db migrate`.
 
+:::note[If you used Prisma ORM 8 before 8.0.0-rc.12]
+
+In Prisma ORM 8 releases before 8.0.0-rc.12, a model without `@@map` named its table with a lowercase first letter, such as `"userProfile"` for a `UserProfile` model. If your tables were created with those names, download the [`add-model-map` script](https://github.com/prisma/orm/blob/v8.0.0-rc.12/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.11-to-8.0.0-rc.12/scripts/psl-verbatim-table-names/add-model-map.mjs) into your project root and run it there before you plan your next migration:
+
+```bash
+curl -O https://raw.githubusercontent.com/prisma/orm/v8.0.0-rc.12/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.11-to-8.0.0-rc.12/scripts/psl-verbatim-table-names/add-model-map.mjs
+node add-model-map.mjs '**/*.prisma'
+```
+
+The script adds `@@map` with the name the table has now, such as `@@map("userProfile")`, to each model that has no `@@map`, in every `.prisma` file in your project, including any you keep in a migration directory. If you plan without running it, `migration plan` stops with [`MIGRATION.TABLE_NAME_CASE_CHANGED`](/orm/reference/error-reference#MIGRATION.TABLE_NAME_CASE_CHANGED) instead of dropping the table and creating an empty one.
+
+:::
+
 ## What a migration contains
 
 A migration directory is named with a timestamp and the `--name` you passed. `migrations/` is in the directory you run commands from, normally your project root:
@@ -117,7 +122,7 @@ Inside `ops.json`, an operation is not only the change itself: it also carries t
 
 When `db migrate` reaches an operation, it runs the postcheck first. If the postcheck passes, the change is already in the database, so `db migrate` skips the operation. If it does not pass, `db migrate` runs the precheck, then the statements, then the postcheck again, and it stops the run if either check fails. Once the operations are done, it checks the database against the contract before it updates the marker, which catches a database that satisfied every individual operation but still doesn't match what you declared.
 
-Say `"user"` already has a `phone` column of another type. The postcheck only asks whether a `phone` column exists, so it passes and the operation is skipped. The check against the contract then finds the wrong type, and the run fails with an error whose `code` is `MIGRATION.RUNNER_FAILED` and whose explanation says the database schema does not satisfy the contract. To see which columns differ, run `npx prisma db verify --schema-only`. Change the `phone` column in the database to the type your contract declares, and run `db migrate` again.
+Say `"user"` already has a `phone` column of another type. The postcheck only asks whether a `phone` column exists, so it passes and the operation is skipped. The check against the contract then finds the wrong type, and the run fails with an error whose `code` is `MIGRATION.RUNNER_FAILED` and whose `why:` line reads `The resulting database schema does not satisfy the destination contract.` To see which columns differ, run `npx prisma db verify --schema-only`. Then change the column by hand to the type your contract declares, here `text`, with `ALTER TABLE "public"."user" ALTER COLUMN "phone" TYPE text;`, and run `db migrate` again. [Drift](/orm/migrations/rollbacks-and-recovery#drift-when-the-database-isnt-where-migrations-left-it) covers other changes made outside a migration.
 
 Each operation also has an `operationClass`, which says what kind of change the operation makes to the database and which you choose yourself when you write a raw SQL operation:
 
diff --git a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
index 36fdac2028..3a3615e9cd 100644
--- a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
+++ b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
@@ -174,6 +174,10 @@ Nothing above changes with your database, because the graph and the commands are
 - **PostgreSQL**: the marker is the `prisma_contract.marker` table and the ledger is the `prisma_contract.ledger` table.
 - **MongoDB**: the marker and ledger are documents in a `_prisma_migrations` collection, which is new in Prisma ORM 8 because Prisma ORM 7 had no migrations on MongoDB.
 
+## Adding a migration you write yourself
+
+`npx prisma migration new` writes an empty migration for a change you write yourself, such as a data update. It always ends at the contract state in your current `contract.json`, and without `--from` it starts where `migration plan` would, at the `db` ref. Its `--from` accepts less than the one on `migration plan`: it takes only the contract hash in the `to` field of an existing migration's `migration.json`, or any start of that hash that matches only one migration's `to` hash, such as the 7 characters `migration graph` shows. It does not take a ref name, a migration directory name, or one of the `@` tokens. So to start from `e377d00` in the drawing above, run `npx prisma migration new --name backfill --from e377d00`. Because `e377d00` is also the `@contract` state, that migration starts and ends at the same state, which is what a data-only migration does.
+
 ## Release-candidate limitations
 
 The graph itself, the way `db migrate` chooses which migrations to run, refs, the marker, and the ledger all work today. These are not built yet:
@@ -181,8 +185,6 @@ The graph itself, the way `db migrate` chooses which migrations to run, refs, th
 - **No squash.** You cannot yet collapse a long chain of migrations into one.
 - **No split.** You cannot yet break one large migration into smaller ones after the fact.
 
-`npx prisma migration new` writes an empty migration for a change you write yourself, such as a data update. Without `--from` it starts where `migration plan` would, at the `db` ref. Its `--from` accepts less than the one on `migration plan`: it takes only the contract hash in the `to` field of an existing migration's `migration.json`, or the first few characters of it, and not a ref name, a migration directory name, or one of the `@` tokens. So to build on `e377d00` in the drawing above, run `npx prisma migration new --name backfill --from e377d00`.
-
 ## Common tasks
 
 | Task | Command |
diff --git a/apps/docs/content/docs/orm/reference/orm-client.mdx b/apps/docs/content/docs/orm/reference/orm-client.mdx
index d41b6e8963..fb897a3486 100644
--- a/apps/docs/content/docs/orm/reference/orm-client.mdx
+++ b/apps/docs/content/docs/orm/reference/orm-client.mdx
@@ -182,7 +182,7 @@ Some parts of the schema the examples rely on:
 - On MongoDB, `id ObjectId @id @map("_id")` renames the field to `_id` everywhere: you filter on `_id`, and the returned document has an `_id` key. That is why the MongoDB examples never say `id`.
 - `Uuid` is a built-in type for a PostgreSQL `uuid` column. You do not import it. `@default(uuid())` fills the id in when you insert a row.
 - `@@type("pg/text@1")` on an `enum` block stores the enum as a text column. The `@1` is the version of that storage format, and only version 1 exists today, so write it exactly like that. The MongoDB form of the same attribute is `@@type("mongo/string@1")`. This page calls an enum written this way a text-backed enum.
-- A `native_enum` block stores the same members as a real PostgreSQL enum type instead. Give every member a value. A member with no value is rejected. A field that uses it is typed `pg.enum(Priority)`. This page calls an enum written this way a native enum. The two sort differently; see [`orderBy()`](#orderby).
+- A `native_enum` block stores the members as a PostgreSQL enum type, created with `CREATE TYPE`. Prisma ORM 7 stored every `enum` this way, so a database that Prisma ORM 7 created already has these types, and you keep them by declaring each one with `native_enum`, as [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7) shows. A plain `enum` block in Prisma ORM 8 is stored as text. Give every `native_enum` member a value, because a member with no value is rejected. A field that uses it is typed `pg.enum(Priority)`. This page calls an enum written this way a native enum. The two sort differently; see [`orderBy()`](#orderby).
 
   ```prisma
   native_enum Priority {
@@ -919,7 +919,7 @@ const features = await tasks.Task.features().all();
 
 A write method changes the database. `create`, `createAll`, `createAndCount`, `update`, `updateAll`, `updateAndCount`, `delete`, `deleteAll`, `deleteAndCount`, and `upsert` are available on both databases, and the differences between the two are listed under each method.
 
-For Prisma ORM 7 users: `createMany` is `createAll()` or `createAndCount()`, `updateMany` is `updateAll()` or `updateAndCount()`, `deleteMany` is `deleteAll()` or `deleteAndCount()`, and `count` is [`aggregate()`](#grouped-aggregates) on PostgreSQL, or the two steps shown under [Read methods](#read-terminals) on MongoDB. `skipDuplicates: true` is now `{ onConflict: 'skip' }`, which you pass to [`createAll()`](#createall) or [`createAndCount()`](#createandcount) on PostgreSQL as a second argument.
+For Prisma ORM 7 users: `createMany` is `createAndCount()`, which returns the count as a number instead of `{ count }`, and `createManyAndReturn` is `createAll()`. In the same way, `updateMany` is `updateAndCount()` and `updateManyAndReturn` is `updateAll()`. `deleteMany` is `deleteAndCount()`, and `deleteAll()` returns the deleted rows, which no Prisma ORM 7 method did. `count` is [`aggregate()`](#grouped-aggregates) on PostgreSQL, or the two steps shown under [Read methods](#read-terminals) on MongoDB. `skipDuplicates: true` is now `{ onConflict: 'skip' }`, which you pass to [`createAll()`](#createall) or [`createAndCount()`](#createandcount) on PostgreSQL as a second argument.
 
 To catch one of the errors named below, wrap the call in `try` and `catch`, then compare `error.code` with the string given here. For a task-oriented walkthrough, see [Writing data](/orm/fundamentals/writing-data). On MongoDB, a write method rejects a chain that already has `orderBy()`, `limit()`, or `offset()` on it, and every write except `updateAll()` and `deleteAll()` also rejects `include()`. Both throw an error whose `code` is `ORM.OPERATION_UNSUPPORTED`. For grouping several writes into one unit, see [Transactions](/orm/fundamentals/transactions).
 
@@ -1013,8 +1013,8 @@ Insert multiple rows and return them.
 - On PostgreSQL every row is inserted by one statement before the first row reaches you. Stopping the loop early does not undo an insert.
 - To skip each row that would break a unique constraint, instead of failing the whole insert, pass `{ onConflict: 'skip' }` as the second argument. The result then holds only the rows the database wrote. This replaces `skipDuplicates: true` from Prisma ORM 7.
 - `onConflict` works on PostgreSQL, and on SQLite through the experimental `@prisma/orm-sqlite` package. On MongoDB, `createAll()` takes only the rows, so a second argument is a type error.
-- By default, a row is skipped when it breaks any unique constraint. To check only one constraint, list its fields in `conflictOn`. In the example schema, `Tag.label` is unique, so `conflictOn: ['label']` skips a tag whose label already exists.
-- `onConflict` does not work on a variant stored in its own table, such as `Bug`, which maps to `bug` while its base model `Task` maps to `task`. Passing it there throws an error whose `code` is `ORM.OPERATION_UNSUPPORTED`.
+- By default, a row is skipped when it breaks any unique constraint. To check only one constraint, list its fields in `conflictOn`. In the example schema, `Tag.label` is unique, so `conflictOn: ['label']` skips a tag whose label already exists. A row that breaks a different unique constraint is then not skipped: the database rejects it, and the whole insert fails, so no row is written.
+- `onConflict` does not work on a variant stored in its own table, such as `Bug`, which maps to `bug` while its base model `Task` maps to `task`. Passing it there throws an error whose `code` is `ORM.OPERATION_UNSUPPORTED`. For such a variant, call `createAll()` with only the rows. A row that breaks a unique constraint then makes the call fail instead of being skipped.
 - If your contract was emitted before `8.0.0-rc.12`, run `npx prisma contract emit` again before you use `onConflict`. Otherwise the call throws an error whose `code` is `ORM.CAPABILITY_MISSING`.
 
 #### Options
@@ -1694,7 +1694,7 @@ Comparison methods on a field.
 - `eq`, `neq`, `in`, and `notIn` are on a field whose values can be compared for equality.
 - `gt`, `lt`, `gte`, and `lte` are on a field whose values can be ordered.
 - `like` and `ilike` are on a text field.
-- `String` fields and enums stored as text have all of them. A [native enum](#example-schema) field, typed `pg.enum(...)` in the contract, has all but `like` and `ilike`, because PostgreSQL has no pattern match for an `enum` type. `Uuid` and `DateTime` have all but `like` and `ilike`. A `Boolean` field has only the equality methods, `isNull()`, and `isNotNull()`. A `Json` field has only `isNull()` and `isNotNull()`.
+- `String` fields and text-backed enums have all of them. A [native enum](#example-schema) field, typed `pg.enum(...)` in the contract, has all but `like` and `ilike`, because PostgreSQL has no pattern match for an `enum` type. `Int`, `BigInt`, `Float`, `Decimal`, `Uuid`, and `DateTime` fields also have all but `like` and `ilike`. A `Boolean` field has only the equality methods, `isNull()`, and `isNotNull()`. A `Json` field has only `isNull()` and `isNotNull()`.
 - `like()` matches a SQL pattern case-sensitively. `ilike()` matches the same pattern case-insensitively.
 - `in([])` matches no rows. `notIn([])` matches every row.
 
@@ -1749,17 +1749,29 @@ PostgreSQL full-text search on a text field.
 
 - PostgreSQL. A text field has `fullTextMatches(query, options?)` to filter and `fullTextRank(query, options?)` to sort by relevance.
 - The [SQL query builder](/orm/reference/sql-query-builder) has both, as `fns.fullTextMatches(column, query)` and `fns.fullTextRank(column, query)`. It also has `fns.fullTextHeadline(column, query)`, which returns the matching text with each match marked. Use the SQL query builder when you want that text in your results, because the ORM's `select()` takes only field names.
-- The `query` argument is a parsed search query, which PostgreSQL calls a `tsquery`. Passing a plain string is a type error. Build the query with one of these functions from `@prisma/orm-postgres/target/full-text`: `websearchToTsquery(text)` reads text the way a web search box does, with quotes around a phrase, `or`, and `-` before a word to leave it out. `plaintoTsquery(text)` requires every word, and `phrasetoTsquery(text)` requires the words in order.
+- The `query` argument is a parsed search query, which PostgreSQL calls a `tsquery`. Passing a plain string is a type error. Build the query with one of these functions from `@prisma/orm-postgres/target/full-text`: `websearchToTsquery(text)` reads text the way a web search box does: the user puts a phrase in quotes, writes `or` between choices, and puts `-` before a word to leave it out. `plaintoTsquery(text)` requires every word, and `phrasetoTsquery(text)` requires the words in order.
 - `toTsquery(text)` reads PostgreSQL's own search syntax, in which `&` means and, `|` means or, `!` means not, and `:*` after a word matches any word that starts with it. Text that breaks this syntax makes the query fail when it runs, so never pass user input to `toTsquery()`.
-- To add an operator to user text, such as `:*` for a prefix match while the user types, use the `tsquery` template tag from the same package: `` tsquery`${term}:*` ``. The tag puts each interpolated value in quotes as one search term, so the user's text cannot add operators of its own. Do not put quotes around the interpolation yourself.
-- `language` is the language whose rules PostgreSQL uses to match words, so that in `english` a search for `run` also finds `running`. It defaults to `english`. The method and the parser each take `language`, so pass the same value to both. The tag takes it as `` tsquery({ language: 'german' })`${input}:*` ``.
+- To add an operator to user text, such as `:*` for a prefix match while the user types, use the `tsquery` template tag from the same package: `` tsquery`${term}:*` ``. Text inside `${}` is searched as plain words, so the user's text cannot add operators of its own. When it holds several words, they must appear next to each other and in that order, and `:*` applies to each word, so `` tsquery`${'new y'}:*` `` finds `new` followed by a word that starts with `y`. Do not put quotes around the `${}` yourself.
+- `language` is the language whose rules PostgreSQL uses to match words, so that in `english` a search for `run` also finds `running`. It defaults to `english`. Pass the same `language` to `fullTextMatches()` or `fullTextRank()` and to the function that builds the query, as in the example below. The tag takes it as `` tsquery({ language: 'german' })`${input}:*` ``.
 
   ```typescript
   const q = websearchToTsquery(input, { language: 'german' });
   const posts = await db.orm.public.Post.where((p) => p.title.fullTextMatches(q, { language: 'german' })).all();
   ```
 
-- Add [`@@fullTextIndex`](/orm/contract-authoring/psl-syntax#full-text-indexes) to the model, with the same `language`, so PostgreSQL can use an index for the search. Without it the query still works, but PostgreSQL reads every row.
+- Add [`@@fullTextIndex`](/orm/contract-authoring/psl-syntax#full-text-indexes) to the model, with the same `language`, so PostgreSQL can use an index for the search. Without it the query still works, but PostgreSQL reads every row. The attribute takes the one field to index and a `name:` for the index:
+
+  ```prisma title="src/prisma/contract.prisma (excerpt)"
+  model Post {
+    id    Uuid   @id @default(uuid())
+    title String
+
+    @@fullTextIndex([title], name: "post_title_search", language: "german")
+    @@map("post")
+  }
+  ```
+
+  Then run `npx prisma contract emit` and create the index the way you apply any other contract change: `npx prisma db update` while you are iterating, or `npx prisma migration plan` followed by `npx prisma db migrate`. See [How migrations work](/orm/migrations/how-migrations-work).
 - A native enum field, typed `pg.enum(...)` in the contract, has no full-text operations.
 
 #### Options
diff --git a/apps/docs/content/docs/orm/reference/sql-query-builder.mdx b/apps/docs/content/docs/orm/reference/sql-query-builder.mdx
index 8a22fde62a..7bd061d8f4 100644
--- a/apps/docs/content/docs/orm/reference/sql-query-builder.mdx
+++ b/apps/docs/content/docs/orm/reference/sql-query-builder.mdx
@@ -132,7 +132,7 @@ In Prisma ORM 8 your `schema.prisma` is called `contract.prisma`. [Coming from P
 
 You build queries from the client's `sql` property. Create a Postgres client with `postgres(...)`, then reach tables through `db.sql.public`. `public` is the PostgreSQL schema your tables are in. To put a model's table in another PostgreSQL schema, such as `auth`, wrap the model in a `namespace auth { ... }` block in your contract, and you then reach its table through `db.sql.auth` instead. See [Namespaces](/orm/contract-authoring/psl-syntax#namespaces).
 
-Table accessors are keyed by table name, not model name. A table name is the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. In the example schema, the `User` model is mapped to `user`, so you write `db.sql.public.user`. The `PostTag` model for the join table is mapped to `post_tag`, so you write `db.sql.public.post_tag`. Column names are the field names unless a field sets `@map`.
+Table accessors are keyed by table name, not model name. A table name is the model's `@@map` value, or the model name exactly as written when the model has no `@@map`. In the example schema, the `User` model is mapped to `user`, so you write `db.sql.public.user`. The `PostTag` model for the join table is mapped to `post_tag`, so you write `db.sql.public.post_tag`. Column names are the field names unless a field sets `@map`, and for a field that does, you write the `@map` name everywhere in the builder. A field declared `userId Uuid @map("user_id")` is `select('user_id')` and `f.user_id`, and each row you get back has a `user_id` key.
 
 ### The `db.sql` builder [#the-dbsql-facet]
 
@@ -152,6 +152,8 @@ const plan = db.sql.public.user.select('id', 'email').build();
 const users = await runtime.query(plan);
 ```
 
+The example schema's `Embedding1536` column is a pgvector type, so a client for that schema also needs pgvector in `extensions`, as [Built-in functions](#built-in-functions) shows.
+
 SQLite works the same way: create the client with `sqlite(...)` from `@prisma/orm-sqlite/runtime`. SQLite has no schemas, so there is no `public` in the path and the same table is `db.sql.user`. Of the SELECT methods on this page, `lateralJoin()`, `outerLateralJoin()`, and `distinctOn()` are not available on SQLite, but every other one is. The rest of this page shows PostgreSQL and writes the root as `db.sql.public`.
 
 ### Table access
@@ -925,11 +927,20 @@ Which aggregate functions exist depends on your database, and PostgreSQL gives y
 | `min(field)` | The input column's own type. A `VarChar` column gives a `String` (`text`) |
 | `max(field)` | The input column's own type. A `VarChar` column gives a `String` (`text`) |
 
-On PostgreSQL, `fns` also has `ilike(expr, pattern)`, a case-insensitive SQL `LIKE` match for text columns, as in `fns.ilike(f.displayName, '%alice%')`. There is no `fns.like`, so write a case-sensitive `LIKE` in a [`fns.raw`](#fnsraw-and-returns) fragment. `ilike` does not accept a column whose type is a native PostgreSQL enum, which a contract declares in a `native_enum` block and types as `pg.enum(...)`, because PostgreSQL cannot pattern-match an enum type. See [Enums](/orm/contract-authoring/psl-syntax#enums).
+On PostgreSQL, `fns` also has `ilike(expr, pattern)`, a case-insensitive SQL `LIKE` match for text columns, as in `fns.ilike(f.displayName, '%alice%')`. There is no `fns.like`, so write a case-sensitive `LIKE` in a [`fns.raw`](#fnsraw-and-returns) fragment that returns a boolean:
+
+```ts
+const plan = db.sql.public.user
+  .select('id', 'displayName')
+  .where((f, fns) => fns.raw`${f.displayName} LIKE ${'%Alice%'}`.returns('pg/bool@1'))
+  .build();
+```
+
+`ilike` does not work on a `native_enum` column, typed `pg.enum(...)`, because PostgreSQL cannot pattern-match an enum type. Passing one is a type error. See [Enums](/orm/contract-authoring/psl-syntax#enums).
 
-Full-text search on PostgreSQL uses `fns.fullTextMatches(column, query)` to filter, `fns.fullTextRank(column, query)` to score, and `fns.fullTextHeadline(column, query)` to return the matching text with each match marked. Build `query` from the search text with `fns.websearchToTsquery(text)`, `fns.plaintoTsquery(text)`, `fns.phrasetoTsquery(text)`, or `fns.toTsquery(text)`, or with the `tsquery` template tag from `@prisma/orm-postgres/target/full-text`. [Full-text search](/orm/reference/orm-client#full-text-search) on the ORM client reference explains what each of these does, and the index that lets PostgreSQL search without reading every row.
+Full-text search on PostgreSQL uses `fns.fullTextMatches(column, query)` to filter, `fns.fullTextRank(column, query)` to score, and `fns.fullTextHeadline(column, query)` to return the matching text with each match marked. Build `query` from the search text with `fns.websearchToTsquery(text)`, `fns.plaintoTsquery(text)`, `fns.phrasetoTsquery(text)`, or `fns.toTsquery(text)`, or with the `tsquery` template tag from `@prisma/orm-postgres/target/full-text`. Never pass user input to `fns.toTsquery()`, because text that breaks PostgreSQL's search syntax makes the query fail when it runs; use `fns.websearchToTsquery()` or the `tsquery` tag for user input. [Full-text search](/orm/reference/orm-client#full-text-search) on the ORM client reference explains what each of these does, and the index that lets PostgreSQL search without reading every row.
 
-Each of the three full-text functions takes an options object as its last argument, and each accepts `language`. Give the parser the same `language`, as in `fns.fullTextMatches(f.title, fns.websearchToTsquery(q, { language: 'german' }), { language: 'german' })`. `fullTextRank` also takes `normalization` and `coverDensity`, which the ORM client reference describes. `fullTextHeadline` also takes these options:
+Each of the three full-text functions takes an options object as its last argument, and each accepts `language`. Pass the same `language` to the function that builds `query`, as in `fns.fullTextMatches(f.title, fns.websearchToTsquery(q, { language: 'german' }), { language: 'german' })`. `fullTextRank` also takes `normalization` and `coverDensity`, which the ORM client reference describes. `fullTextHeadline` also takes these options:
 
 - `startSel` and `stopSel`: the text put before and after each match. PostgreSQL uses `<b>` and `</b>` when you leave them out.
 - `maxWords` and `minWords`: the longest and shortest headline, in words. `minWords` must be lower than `maxWords`.
@@ -949,9 +960,26 @@ const plan = db.sql.public.post
   .orderBy((f, fns) => fns.fullTextRank(f.title, fns.websearchToTsquery(q)), { direction: 'desc' })
   .limit(10)
   .build();
+
+const results = await runtime.query(plan);
+// { id: string; title: string; rank: number; headline: string }[]
+```
+
+`rank` is a `number`, and a higher rank is a better match. `headline` is a `string`: the title with each match between `<mark>` and `</mark>`.
+
+pgvector is the PostgreSQL extension for vector columns. If your contract uses a pgvector type, such as `Embedding1536` in the example schema, pass pgvector in `extensions` when you create the client, because without it `postgres(...)` throws an error whose `code` is `RUNTIME.MISSING_EXTENSION_PACK`:
+
+```ts
+import pgvector from '@prisma/orm-extension-pgvector/runtime';
+
+const db = postgres<Contract>({
+  contractJson,
+  url: process.env.DATABASE_URL,
+  extensions: [pgvector],
+});
 ```
 
-If your contract uses a pgvector type, such as `Embedding1536` in the example schema, `fns` also has `fns.cosineDistance(a, b)`. pgvector is the PostgreSQL extension for vector columns. `cosineDistance` returns the cosine distance between two vectors as a `number`. Each argument is a vector column or an array of numbers, as in `fns.cosineDistance(f.embedding, queryEmbedding)`. See [Extension types](/orm/contract-authoring/psl-syntax#extension-types).
+`fns` then also has `fns.cosineDistance(a, b)`, which returns the cosine distance between two vectors as a `number`. Each argument is a vector column or an array of numbers, as in `fns.cosineDistance(f.embedding, queryEmbedding)`. See [Extension types](/orm/contract-authoring/psl-syntax#extension-types).
 
 ### `fns.raw` and `.returns()`
 
diff --git a/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx b/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx
index 20cdad1487..8a9580c22b 100644
--- a/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx
+++ b/apps/docs/content/docs/orm/reference/transactions-and-runtime.mdx
@@ -55,7 +55,7 @@ Pass exactly one of `url`, `pg`, and `binding`.
 | `PostgresClient` | `postgres<Contract>({ contractJson, url })` | A client that has not connected yet. Its members are listed below. |
 
 - `.orm` holds your models by model name. See the [ORM client reference](/orm/reference/orm-client).
-- `.sql` is the SQL query builder, keyed by schema, then table name: `db.sql.public.tag`. The table name is the model's `@@map` value, or the model name exactly as written when the model sets no `@@map`. See the [SQL query builder reference](/orm/reference/sql-query-builder). `.raw` writes raw SQL as a template string. See the [raw queries reference](/orm/reference/raw-queries).
+- `.sql` is the SQL query builder, keyed by PostgreSQL schema, then by table name: `db.sql.public.tag`. The table name is the model's `@@map` value, or the model name exactly as written when the model sets no `@@map`. See the [SQL query builder reference](/orm/reference/sql-query-builder). Write raw SQL with ``db.raw.sql`...` ``, as the [raw queries reference](/orm/reference/raw-queries) shows.
 - `.enums` holds the enum values from your contract, by PostgreSQL schema: `db.enums.public.Role`. `.nativeEnums` holds the values of enum types that exist in PostgreSQL itself, created with `CREATE TYPE`, also by schema. Look the type up by name in brackets: `db.nativeEnums.auth['AalLevel'].values` is `['aal1', 'aal2', 'aal3']`.
 - `.contract` is the contract as an object. [`connect()`](#connect), [`runtime()`](#runtime), [`transaction()`](#dbtransactioncallback), [`prepare()`](#dbpreparedeclaration-callback), and [`close()`](#close) are documented on this page.
 
@@ -211,7 +211,7 @@ Pass exactly one of `url`, `uri`, `mongoClient`, and `binding`. `dbName` is sepa
 |---|---|---|
 | `MongoClient` | `mongo<Contract>({ contractJson, url, dbName })` | A client that has not connected yet. This is Prisma ORM's own type. The `mongodb` driver has a class of the same name, so when you import both, name this one `db`. |
 
-- `.orm` holds your models by collection name, with no schema segment: `db.orm.users`. The collection name is the model's `@@map` value, or the model name exactly as written when the model sets no `@@map`. The [example schema](/orm/reference/orm-client#example-schema) sets `@@map("users")` on `User`, which is why the key here is `users`. See the [ORM client reference](/orm/reference/orm-client).
+- `.orm` holds your models by collection name, with no `.public` in the path: `db.orm.users`. The collection name is the model's `@@map` value, or the model name exactly as written when the model sets no `@@map`. The [example schema](/orm/reference/orm-client#example-schema) sets `@@map("users")` on `User`, which is why the key here is `users`. See the [ORM client reference](/orm/reference/orm-client).
 - `.query` is the pipeline builder, which builds MongoDB aggregation pipelines. See the [pipeline builder reference](/orm/reference/pipeline-builder). `.raw` sends raw MongoDB commands. See the [raw queries reference](/orm/reference/raw-queries).
 - `.enums` holds the enum values from your contract, and `.contract` is the contract as an object. [MongoDB `connect()`](#connect-1), [MongoDB `runtime()`](#runtime-1), and [MongoDB `close()`](#close-1) are documented below.
 
@@ -621,13 +621,13 @@ Prepare a statement on the client itself.
 
 #### Remarks
 
-- The callback takes one argument, the declared `params`, as it does on `runtime.prepare(...)`. Build the query with the client's own `db.sql` or `db.orm`. Before `8.0.0-rc.12` the callback received a SQL builder as its first argument, `(sql, params)`; change such a callback to `(params)` and write `db.sql` where it wrote `sql`.
+- The callback takes one argument, the declared `params`, as it does on `runtime.prepare(...)`. Build the query with the client's own `db.sql` or `db.orm`.
 - The callback can return a built SQL query, or an ORM query that ends in `.prepared.all()`, `.prepared.first()`, or `.prepared.aggregate(...)`. `.prepared` always goes right before that last call, so a grouped aggregate is written `db.orm.public.Post.groupBy('userId').prepared.aggregate((agg) => ({ posts: agg.count() }))`.
-- The ORM query is built once. Each `query(target, params)` call runs it with the new values and returns what the same call without `.prepared` returns:
-  - `all()` returns the rows.
-  - `first()` returns a row, or `null`.
-  - `aggregate(...)` returns the aggregate object.
-  - `groupBy(...)` followed by `aggregate(...)` returns an array with one object per group.
+- The ORM query is built once. `db.prepare(...)` resolves to a prepared query, here called `ps`, and you run it with `ps.query(db.runtime(), values)`, where `values` holds a value for each declared parameter. A connection or a transaction also works in place of `db.runtime()`. Each run uses the new values and returns what the same call without `.prepared` returns:
+  - `all()` returns the rows, as an [`AsyncIterableResult`](#asynciterableresult) that you `await` for an array.
+  - `first()` returns a promise of one row, or of `null` when no row matches.
+  - `aggregate(...)` returns a promise of the aggregate object.
+  - `groupBy(...)` followed by `aggregate(...)` returns a promise of an array with one object per group.
 - `prepare()` starts the connection itself. Call `db.runtime()` for the runtime. `db.connect()` would throw an error whose `code` is `DRIVER.ALREADY_CONNECTED`, because `prepare()` already connected.
 
 #### Options
@@ -670,7 +670,7 @@ const countTags = await db.prepare({}, () =>
 const { total } = await countTags.query(db.runtime(), {});
 ```
 
-In an ORM query, a prepared parameter works in `where(...)` filters, in the callback you pass to `include(...)`, and in `.limit(...)` and `.offset(...)`, so the same statement can page through results. Declare a page size or offset with a number type id that is not nullable, such as `{ take: 'pg/int4@1' }`, and pass `params.take` to `.limit(...)`. A nullable or text type id there is a type error.
+In an ORM query, a prepared parameter works in `where(...)` filters, in the callback you pass to `include(...)`, and in `.limit(...)` and `.offset(...)`, so the same statement can page through results. Declare a page size or offset as `'pg/int4@1'`, as in `{ take: 'pg/int4@1' }`, and pass `params.take` to `.limit(...)`. A text type id such as `'pg/text@1'`, or a nullable one such as `{ codecId: 'pg/int4@1', nullable: true }`, is a type error there.
 
 ### `PreparedStatement.query(target, params)`
 
@@ -704,6 +704,8 @@ Run a prepared statement against a target, with the parameter values.
 |---|---|---|
 | `AsyncIterableResult<Row>` | `await ps.query(runtime, { label })` | The statement's rows. `await` the result for an array. |
 
+A prepared ORM query from [`db.prepare(...)`](#dbpreparedeclaration-callback) is different: its `query(...)` returns what the same ORM call returns, so a prepared `first()` gives a promise of one row or `null`.
+
 #### Examples
 
 ##### Run one prepared statement against a transaction and the runtime
diff --git a/apps/docs/content/docs/orm/release-status.mdx b/apps/docs/content/docs/orm/release-status.mdx
index 291fe07365..cb13c1cfcf 100644
--- a/apps/docs/content/docs/orm/release-status.mdx
+++ b/apps/docs/content/docs/orm/release-status.mdx
@@ -37,13 +37,13 @@ For MongoDB the library is `@prisma/orm-mongo`. [Supported databases](/orm/suppo
 
 The two packages have different version numbers, and that is normal: they are released separately, and the command-line tool gets more frequent releases. Install both at `latest`; any two `latest` versions work together, and you do not pair the numbers yourself.
 
-| Package | Version today |
+| Package | `latest` on 24 September 2026 |
 | --- | --- |
 | `prisma` (the command-line tool) | `8.0.0-rc.17` |
 | `@prisma/orm-postgres` (the library) | `8.0.0-rc.12` |
 | `@prisma/orm-mongo` (the MongoDB library) | `8.0.0-rc.12` |
 
-These were the `latest` versions on 24 September 2026. To see the `latest` version of each package today, run `npm view prisma dist-tags`, `npm view @prisma/orm-postgres dist-tags`, and `npm view @prisma/orm-mongo dist-tags`, and read the `latest` entry in each result. You need all three commands because the command-line tool and the libraries are versioned separately.
+To see the `latest` version of each package today, run `npm view prisma dist-tags`, `npm view @prisma/orm-postgres dist-tags`, and `npm view @prisma/orm-mongo dist-tags`, and read the `latest` entry in each result. You need all three commands because the command-line tool and the libraries are versioned separately.
 
 `@prisma/client`, the library that Prisma ORM 7 apps import, stays at `7.10.0`, because it belongs to Prisma ORM 7 and is not part of Prisma ORM 8.
 

From cc0ef4e846713a30e7ae15cd693ab1e5fbd3059a Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Fri, 25 Sep 2026 07:47:00 +0200
Subject: [PATCH 08/16] docs(docs): state where migration new starts when there
 is no db ref

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 apps/docs/content/docs/orm/migrations/the-migration-graph.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
index 3a3615e9cd..7bf91cd7ac 100644
--- a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
+++ b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
@@ -176,7 +176,7 @@ Nothing above changes with your database, because the graph and the commands are
 
 ## Adding a migration you write yourself
 
-`npx prisma migration new` writes an empty migration for a change you write yourself, such as a data update. It always ends at the contract state in your current `contract.json`, and without `--from` it starts where `migration plan` would, at the `db` ref. Its `--from` accepts less than the one on `migration plan`: it takes only the contract hash in the `to` field of an existing migration's `migration.json`, or any start of that hash that matches only one migration's `to` hash, such as the 7 characters `migration graph` shows. It does not take a ref name, a migration directory name, or one of the `@` tokens. So to start from `e377d00` in the drawing above, run `npx prisma migration new --name backfill --from e377d00`. Because `e377d00` is also the `@contract` state, that migration starts and ends at the same state, which is what a data-only migration does.
+`npx prisma migration new` writes an empty migration for a change you write yourself, such as a data update. It always ends at the contract state in your current `contract.json`, and without `--from` it starts where `migration plan` would: at the `db` ref, or from an empty database when there are no migrations and no `db` ref yet. When there are migrations but no `db` ref, it refuses and asks for `--from`. [`migration new`](/cli/migration-new) lists every case. Its `--from` accepts less than the one on `migration plan`: it takes only the contract hash in the `to` field of an existing migration's `migration.json`, or any start of that hash that matches only one migration's `to` hash, such as the 7 characters `migration graph` shows. It does not take a ref name, a migration directory name, or one of the `@` tokens. So to start from `e377d00` in the drawing above, run `npx prisma migration new --name backfill --from e377d00`. Because `e377d00` is also the `@contract` state, that migration starts and ends at the same state, which is what a data-only migration does.
 
 ## Release-candidate limitations
 

From 007d883828ab2ab4abdd2bac1bc9334b79266e1d Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Fri, 25 Sep 2026 11:31:48 +0200
Subject: [PATCH 09/16] docs(docs): answer the open questions from the ORM
 source

- migration plan: the automatic baseline is planned from an empty schema (contractToSchema(null)), so it only creates things and never asks for consent; drop the claim that it does.
- Editing a migration: parent: false changed nothing, because ormConfig always sets family, target, adapter, driver, extensions and contract, and emit reads no other key. Drop it, and say instead that the intermediate config must list the project's extensions.
- Custom middleware: the tenant example reads the value per query from an AsyncLocalStorage in the middleware's scope, so each request gets its own filter. Type-checked against the workspace packages.
- Upgrade guide: a prisma7Schema project reaches phase 4 by generating a contract file with steps 2.3 to 2.5 first, instead of stopping after phase 3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 apps/docs/content/docs/cli/migration-plan.mdx |  4 +-
 .../guides/upgrade-prisma-orm/postgresql.mdx  |  2 +-
 .../docs/orm/coming-from-prisma-orm-7.mdx     |  2 +-
 .../authoring-custom-middleware.mdx           | 37 ++++++++++++++-----
 .../orm/migrations/editing-a-migration.mdx    |  4 +-
 5 files changed, 34 insertions(+), 15 deletions(-)

diff --git a/apps/docs/content/docs/cli/migration-plan.mdx b/apps/docs/content/docs/cli/migration-plan.mdx
index 44a619f9aa..9a95702243 100644
--- a/apps/docs/content/docs/cli/migration-plan.mdx
+++ b/apps/docs/content/docs/cli/migration-plan.mdx
@@ -19,9 +19,9 @@ Keep the `db` ref current and you never see the refusal. [`db init`](/cli/db-ini
 
 ### The automatic baseline
 
-When `migrations/app/` is empty and the `db` ref points at a contract whose snapshot is stored under `migrations/snapshots/`, one `migration plan` run writes a baseline package from nothing to the ref's contract and, when your emitted contract differs from the ref's, a second package with the delta. Expect one or two new directories in `git status`. The baseline is never replayed against a database that already carries a marker, because the runner starts from the marker and only applies edges past it.
+When `migrations/app/` is empty and the `db` ref points at a contract whose snapshot is stored under `migrations/snapshots/`, one `migration plan` run writes a baseline package from nothing to the ref's contract and, when your emitted contract differs from the ref's, a second package with the delta. Expect one or two new directories in `git status`. The baseline is never applied to a database that already has a marker, because `db migrate` starts from the marker and applies only the migrations after it.
 
-If the baseline would contain destructive operations, which remove data when the migration is applied, `migration plan` lists them and asks you to confirm by typing the name of the directory you run the command in, usually your project directory, before it writes the baseline. In a script, pass that name instead, for example `--no-interactive --confirm my-app`. [`db update`](/cli/db-update) asks for consent the same way, with the database name. Only the baseline needs this confirmation: `migration plan` writes the second package without asking, and its output marks each destructive operation in that package and warns that it may cause data loss.
+The baseline only creates things, because it is planned from an empty database, so it never removes data. The second package can: `migration plan` writes it without asking, and its output marks each destructive operation in it and warns that it may cause data loss. Review that package before you apply it.
 
 When the `db` ref points at a contract state that already has a migration starting from it, `migration plan` writes a second migration that starts from the same state, so the [migration history](/orm/migrations/the-migration-graph) splits into two branches. This happens, for example, after `db migrate` without `--advance-ref db`, which applies migrations but does not update the `db` ref. `migration plan` still writes the migration and prints a warning. A database that has already run the existing migration then has no migration leading to your new contract, so `db migrate` on that database fails with `MIGRATION.PATH_UNREACHABLE`. To build on the newest migration instead, pass `--from` with that migration's directory name.
 
diff --git a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
index 2809c34de7..8d996b9112 100644
--- a/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
+++ b/apps/docs/content/docs/guides/upgrade-prisma-orm/postgresql.mdx
@@ -291,7 +291,7 @@ npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma
 
 Write `prisma@latest`, because in a Prisma ORM 7 project `npx prisma` runs version 7. The command moves Prisma ORM 7 to the `prisma7` command and `prisma7.config.ts`, installs the Prisma ORM 8 packages, writes `prisma.config.ts` and a Prisma ORM 8 client in `src/prisma/db.ts`, and emits the contract. [`orm init` on a Prisma ORM 7 project](/cli/orm-init#on-a-prisma-orm-7-project) lists what it changes. Then run `npx prisma db sign` and continue with phase 3, using the `db` client from `src/prisma/db.ts` instead of adding one to `src/db.ts` in step 3.1.
 
-On this path, stop after phase 3: you can move every route to Prisma ORM 8, but Prisma ORM 7 keeps owning migrations, because phase 4 is written for the inferred `prisma8/contract.prisma` and does not yet cover a project that reads `schema.prisma` through `prisma7Schema(...)`.
+Prisma ORM 7 keeps owning migrations on this path until you are ready for [phase 4](#4-transfer-migration-ownership), where Prisma ORM 8 takes them over. Phase 4 works from a Prisma ORM 8 contract file, so switch to one first: run steps 2.3 to 2.5, and change `contract:` in `prisma.config.ts` back to `"prisma8/contract.prisma"`. Then follow phase 4 as written. Its first step, `db sign`, checks the new contract against the database before Prisma ORM 8 takes over.
 
 :::
 
diff --git a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
index 545bf5d53a..4553ef6fce 100644
--- a/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
+++ b/apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx
@@ -22,7 +22,7 @@ On PostgreSQL, the following command moves Prisma ORM 7 to the `prisma7` command
 npx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma
 ```
 
-It does not change `prisma/` or the database. [`orm init` on a Prisma ORM 7 project](/cli/orm-init#on-a-prisma-orm-7-project) lists what it changes. Then run `npx prisma db sign` and continue with [phase 3 of the guide](/guides/upgrade-prisma-orm/postgresql#3-migrate-one-route), moving routes one at a time to the client in `src/prisma/db.ts`. The guide's phase 4, where Prisma ORM 8 takes over migrations, does not yet cover this setup, so Prisma ORM 7 keeps owning your migrations.
+It does not change `prisma/` or the database. [`orm init` on a Prisma ORM 7 project](/cli/orm-init#on-a-prisma-orm-7-project) lists what it changes. Then run `npx prisma db sign` and continue with [phase 3 of the guide](/guides/upgrade-prisma-orm/postgresql#3-migrate-one-route), moving routes one at a time to the client in `src/prisma/db.ts`. Prisma ORM 7 keeps owning your migrations until the guide's [phase 4](/guides/upgrade-prisma-orm/postgresql#4-transfer-migration-ownership), where Prisma ORM 8 takes them over. Phase 4 works from a Prisma ORM 8 contract file, so before it, generate one with the guide's steps 2.3 to 2.5 and point `contract:` at it.
 
 In a new project, three commands set up Prisma ORM 8:
 
diff --git a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
index b3d9dbb833..071cdf4b8e 100644
--- a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
+++ b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
@@ -228,7 +228,7 @@ The middleware below adds a condition to every `SELECT` whose own `FROM` clause
 import type { SqlMiddleware } from '@prisma/orm-postgres/family-runtime';
 import { AndExpr, type BinaryExpr } from '@prisma/orm-postgres/relational-core/ast';
 
-export function scopeUserSelects(predicate: BinaryExpr): SqlMiddleware {
+export function scopeUserSelects(condition: () => BinaryExpr | undefined): SqlMiddleware {
   return {
     name: 'scope-user-selects',
     familyId: 'sql',
@@ -237,6 +237,8 @@ export function scopeUserSelects(predicate: BinaryExpr): SqlMiddleware {
       if (draft.ast.kind !== 'select') return undefined;
       if (draft.ast.from?.kind !== 'table-source') return undefined;
       if (draft.ast.from.name !== 'User') return undefined;
+      const predicate = condition();
+      if (predicate === undefined) return undefined;
       const where = draft.ast.where ? AndExpr.of([draft.ast.where, predicate]) : predicate;
       return { ...draft, ast: draft.ast.withWhere(where) };
     },
@@ -248,28 +250,45 @@ The `kind` check on `from` keeps the middleware to plain tables: a `SELECT` that
 
 These checks read only the table in the query's own `FROM` clause, so `User` rows that a query reaches any other way do not get the condition. When you load related users with `.include(...)` from another model, such as the author of each post, the ORM API reads them inside that other model's query, whose `FROM` is the other table. A SQL query builder query that joins `User` onto another table is not filtered either, for the same reason.
 
-The condition itself is an object you build from the same classes, and you pass it in when you register the middleware. Put values through `ParamRef.of` rather than `LiteralExpr.of`, because a `ParamRef` becomes a bound parameter such as `$1` while a literal is pasted into the SQL text itself, so a value that came from one of your users could inject SQL of its own. A `ParamRef` you build by hand has to name the PostgreSQL type of the value with `codec: { codecId: ... }`, and the ids start with `pg/` and end with `@1`, so the `text` column `name` takes `pg/text@1`. Leave that out and the query fails with an error whose `code` is `RUNTIME.PARAM_REF_MISSING_CODEC`.
+The middleware calls `condition` for every query, so the condition can change from one request to the next. You build it from the same classes. Put values through `ParamRef.of` rather than `LiteralExpr.of`, because a `ParamRef` becomes a bound parameter such as `$1` while a literal is pasted into the SQL text itself, so a value that came from one of your users could inject SQL of its own. A `ParamRef` you build by hand has to name the PostgreSQL type of the value with `codec: { codecId: ... }`, and the ids start with `pg/` and end with `@1`, so the `text` column `name` takes `pg/text@1`. Leave that out and the query fails with an error whose `code` is `RUNTIME.PARAM_REF_MISSING_CODEC`.
+
+A request has no tenant of its own, so the middleware reads the value from something in its own scope. The example below keeps it in an `AsyncLocalStorage` from Node.js, which holds one value per request while that request's code runs:
 
 ```ts title="src/prisma/db.ts"
+import { AsyncLocalStorage } from 'node:async_hooks';
 import postgres from '@prisma/orm-postgres/runtime';
 import { BinaryExpr, ColumnRef, ParamRef } from '@prisma/orm-postgres/relational-core/ast';
 import { scopeUserSelects } from './scope-user-selects';
 import type { Contract } from './contract.d';
 import contractJson from './contract.json' with { type: 'json' };
 
-const onlyMia = BinaryExpr.eq(
-  ColumnRef.of('User', 'name'),
-  ParamRef.of('Mia', { codec: { codecId: 'pg/text@1' } }),
-);
+export const currentName = new AsyncLocalStorage<string>();
 
 export const db = postgres<Contract>({
   contractJson,
   url: process.env['DATABASE_URL']!,
-  middleware: [scopeUserSelects(onlyMia)],
+  middleware: [
+    scopeUserSelects(() => {
+      const name = currentName.getStore();
+      if (name === undefined) return undefined;
+      return BinaryExpr.eq(
+        ColumnRef.of('User', 'name'),
+        ParamRef.of(name, { codec: { codecId: 'pg/text@1' } }),
+      );
+    }),
+  ],
 });
 ```
 
-Every `SELECT` whose `FROM` clause names `User` now runs with `WHERE "User"."name" = $1` added, and a query that already had a `WHERE` clause keeps it, joined to yours with `AND`. The condition is built once, when you create the client, so every query on this client is filtered to the same value.
+Run each request's queries inside `currentName.run(...)`:
+
+```ts title="src/routes/users.ts"
+import { currentName, db } from '../prisma/db';
+
+const users = await currentName.run('Mia', () => db.orm.public.User.select('id', 'name').all());
+```
+
+Every `SELECT` whose `FROM` clause names `User` then runs with `WHERE "User"."name" = $1` added, and a query that already had a `WHERE` clause keeps it, joined to yours with `AND`. A query that runs outside `currentName.run(...)` gets no condition, because `getStore()` returns `undefined` there. If every query must have one, throw in the function instead of returning `undefined`.
 
 :::warning
 
@@ -413,7 +432,7 @@ Timing itself does not need any of this, because `result.latencyMs` already tell
 Projects created with `npm create prisma@latest` install [Prisma ORM skills](/ai/tools/skills#available-skills-for-prisma-8) for your coding agent, so you can ask it for the middleware built in the steps above:
 
 - "Write a Prisma ORM middleware that logs every query slower than 250ms, and register it before budgets."
-- "Add a beforeCompile middleware that adds a fixed `orgId` condition to every SELECT that reads the User table in its FROM clause."
+- "Add a beforeCompile middleware that adds an `orgId` condition, read per request from an AsyncLocalStorage, to every SELECT that reads the User table in its FROM clause."
 - "Write an interceptQuery middleware that returns fixture rows for the products table in tests."
 
 ## Next steps
diff --git a/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx b/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
index e73f5387d7..10de472d99 100644
--- a/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/editing-a-migration.mdx
@@ -172,12 +172,12 @@ model User {
 
 Keep `// use prisma-8` as the first line of the copy. `contract emit` skips any `.prisma` file that does not start with it, and because `intermediate.prisma` is the only file in the intermediate contract, emitting it without that line fails with an error whose `code` is `CONTRACT.SOURCE_LOAD_FAILED`.
 
-In the same migration directory, add `intermediate.config.ts`, a second config file. Its `contract` is `intermediate.prisma`, and it has no `db.connection`, because emitting a contract never connects to a database. `parent: false` keeps this config apart from your project's config. Without it, the CLI also reads your project's `prisma.config.ts`, because that file is in a directory above this one, and takes from it every `orm` setting this file leaves out, such as `db.connection`:
+In the same migration directory, add `intermediate.config.ts`, a second config file whose `contract` is `intermediate.prisma`. It needs no `db.connection`, because emitting a contract never connects to a database. If your contract uses an extension pack, such as pgvector, list the same `extensions` here as in your project's `prisma.config.ts`, because this file does not take them from it:
 
 ```ts title="intermediate.config.ts"
 import { definePrismaConfig } from 'prisma/config';
 import { defineConfig as ormConfig } from '@prisma/orm-postgres/config';
-export default definePrismaConfig({ parent: false, orm: ormConfig({ contract: './intermediate.prisma' }) });
+export default definePrismaConfig({ orm: ormConfig({ contract: './intermediate.prisma' }) });
 ```
 
 Emit the intermediate contract with `--config` pointing at that file. Run this from your project root, because the `--config` path starts there. The `./intermediate.prisma` path inside the config resolves from the directory the config file is in, so it names the copy in the migration directory:

From dec603665e01abe65f3db6e755b29b4d5598f31d Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Fri, 25 Sep 2026 11:33:38 +0200
Subject: [PATCH 10/16] docs(docs): migration check belongs in pull-request
 checks; the deploy job runs db migrate alone

db migrate loads migrations through the same integrity check and refuses a migration whose files no longer match its hash, so a deploy job that runs only db migrate is safe. The applying and graph pages now say the same thing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 apps/docs/content/docs/orm/migrations/applying-a-migration.mdx | 2 +-
 apps/docs/content/docs/orm/migrations/the-migration-graph.mdx  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
index f54f20403d..d1863339b1 100644
--- a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
@@ -149,7 +149,7 @@ In development, add `--advance-ref db` so the next `migration plan` starts from
 - one directory per [extension package](#extension-spaces) that ships migrations, such as `migrations/pgvector/`
 - `contract.prisma`, `contract.json`, and `contract.d.ts`
 
-When you deploy by hand, run the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed. In a pipeline, the job runs only the last of them, `db migrate`, with `--to <ref>`, which that section explains.
+When you deploy by hand, run the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed. In a pipeline, the deploy job runs only the last of them, `db migrate` with `--to <ref>`, which that section explains. That is safe, because `db migrate` also refuses to run when a migration's files no longer match its hash. Run `migration check` in your pull-request checks to catch the same problem before anything is deployed.
 
 When a migration's `ops.json` or `migration.json` no longer matches the `migrationHash` in its `migration.json`, `migration check` fails with an error whose `code` is `MIGRATION.CHECK_HASH_MISMATCH`, as [Editing a migration](/orm/migrations/editing-a-migration) explains. To fix it, either restore the migration's files from Git, or move the hand edit into `migration.ts` and recompile. If the error comes back right after you recompile, and the migration's backfill updates a model with a `temporal.updatedAtString()` column, recompiling cannot fix it, and [Editing a migration](/orm/migrations/editing-a-migration#worked-example-making-a-column-required) shows how to write that backfill instead.
 
diff --git a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
index 7bf91cd7ac..7b44bd05fa 100644
--- a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
+++ b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
@@ -109,7 +109,7 @@ When no chain of migrations leads from the marker to the target, the run fails w
 | Which contract state does my database match, and what would `db migrate` run next? | `npx prisma migration status` | Yes |
 | What has actually been applied, and when? | `npx prisma migration log` | Yes |
 
-`migration log` reads the **ledger**, so it tells you what actually ran rather than what should have run, and a rollback appears there as one more applied migration instead of erasing anything. Run `migration check` in CI before you deploy, because it catches a hand-edited migration file or a ref naming a state that does not exist, and it needs no database connection. See [Reviewing what you planned](/orm/migrations/generating-a-migration#reviewing-what-you-planned) for its exit codes.
+`migration log` reads the **ledger**, so it tells you what actually ran rather than what should have run, and a rollback appears there as one more applied migration instead of erasing anything. Run `migration check` in your pull-request checks, because it catches a hand-edited migration file or a ref naming a state that does not exist before anything is deployed, and it needs no database connection. `db migrate` also refuses to run a hand-edited migration file. See [Reviewing what you planned](/orm/migrations/generating-a-migration#reviewing-what-you-planned) for its exit codes.
 
 ### Try it on real fixtures
 

From 1de640de585ecf99aa04ca32a716b95ee220a298 Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Fri, 25 Sep 2026 11:33:57 +0200
Subject: [PATCH 11/16] docs(docs): say where to report a Supabase contract
 difference

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 apps/docs/content/docs/orm/extensions/using-extensions.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/docs/content/docs/orm/extensions/using-extensions.mdx b/apps/docs/content/docs/orm/extensions/using-extensions.mdx
index d6532f1271..6f3718dd14 100644
--- a/apps/docs/content/docs/orm/extensions/using-extensions.mdx
+++ b/apps/docs/content/docs/orm/extensions/using-extensions.mdx
@@ -208,7 +208,7 @@ export const db = await supabase<Contract>({
 
 `await db.asUser(jwt)` takes the user's Supabase JWT and gives you a client that runs as that user. `db.asAnon()` gives you one that runs as the anonymous role, and `db.asServiceRole()` one that bypasses row-level security. `db` itself has no `orm` or `sql`: those live on the three role-bound clients. The [runnable example](https://github.com/prisma/orm/tree/main/examples/supabase) shows the whole setup in one project.
 
-`@prisma/orm-extension-supabase` has a contract of its own, which describes Supabase's `auth` and `storage` tables, check constraints included. Prisma read those tables from one Supabase version, supabase/postgres 17.6.1.106, and a Supabase project on another version can have a different set of check constraints. [`npx prisma db verify`](/cli/db-verify) compares your database with the extension's contract as well as with yours, and when a check constraint the extension describes is missing from your database, `db verify` lists it and fails. You cannot fix that with a migration, because Prisma ORM never changes Supabase's own tables. Report the difference to Prisma instead, so the extension can be updated to match.
+`@prisma/orm-extension-supabase` has a contract of its own, which describes Supabase's `auth` and `storage` tables, check constraints included. Prisma read those tables from one Supabase version, supabase/postgres 17.6.1.106, and a Supabase project on another version can have a different set of check constraints. [`npx prisma db verify`](/cli/db-verify) compares your database with the extension's contract as well as with yours, and when a check constraint the extension describes is missing from your database, `db verify` lists it and fails. You cannot fix that with a migration, because Prisma ORM never changes Supabase's own tables. Instead, [open an issue on prisma/orm](https://github.com/prisma/orm/issues) with the output of `db verify` and your Supabase version, so the extension can be updated to match.
 
 [`npx prisma db sign`](/cli/db-sign) checks that a database matches your contract and then records in the database which contract it matches, and it records the extension's contract the same way. When an update to `@prisma/orm-extension-supabase` changes the extension's contract, that record no longer matches, and `npx prisma db verify` fails with `MIGRATION.CONTRACT_SPACE_VIOLATION` until you run `npx prisma db sign` again against every database you signed with the earlier version. The Prisma ORM release notes say when an update changes the extension's contract, as the notes for 8.0.0-rc.12 do. If you are also re-emitting your own contract with `npx prisma contract emit`, run that before `db sign`.
 

From 6e6c5c4ddb38c6e211b91e361b3dd02bab6dc766 Mon Sep 17 00:00:00 2001
From: prisma-robot <prisma-robot@users.noreply.github.com>
Date: Fri, 25 Sep 2026 09:41:55 +0000
Subject: [PATCH 12/16] docs(docs): await the scoped query inside
 currentName.run()

The AsyncLocalStorage example awaited the query outside the run()
callback. .all() returns a lazy AsyncIterableResult, so the query only
started on that outer await, where getStore() is undefined again, and
the middleware added no condition. Await inside the callback, and say
why it matters.
---
 .../docs/orm/middleware/authoring-custom-middleware.mdx   | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
index 071cdf4b8e..3cbbee7b0c 100644
--- a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
+++ b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
@@ -280,15 +280,17 @@ export const db = postgres<Contract>({
 });
 ```
 
-Run each request's queries inside `currentName.run(...)`:
+Run each request's queries inside `currentName.run(...)`, and `await` them inside its callback:
 
 ```ts title="src/routes/users.ts"
 import { currentName, db } from '../prisma/db';
 
-const users = await currentName.run('Mia', () => db.orm.public.User.select('id', 'name').all());
+const users = await currentName.run('Mia', async () => {
+  return await db.orm.public.User.select('id', 'name').all();
+});
 ```
 
-Every `SELECT` whose `FROM` clause names `User` then runs with `WHERE "User"."name" = $1` added, and a query that already had a `WHERE` clause keeps it, joined to yours with `AND`. A query that runs outside `currentName.run(...)` gets no condition, because `getStore()` returns `undefined` there. If every query must have one, throw in the function instead of returning `undefined`.
+Every `SELECT` whose `FROM` clause names `User` then runs with `WHERE "User"."name" = $1` added, and a query that already had a `WHERE` clause keeps it, joined to yours with `AND`. The `await` inside the callback matters: `.all()` returns the query without running it, and the query runs when you `await` it. With `currentName.run('Mia', () => db.orm.public.User.select('id', 'name').all())`, the `await` is outside the callback, so the query runs after `run(...)` has returned, `getStore()` gives `undefined`, and the query gets no condition. The same goes for any query that runs outside `currentName.run(...)`. If every query must have one, throw in the function instead of returning `undefined`.
 
 :::warning
 

From 89982502b013129710b8377bfaaaaa14661a120f Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Fri, 25 Sep 2026 11:53:23 +0200
Subject: [PATCH 13/16] docs(docs): a deploy pipeline runs db migrate alone

db migrate refuses a migration whose files no longer match its hash, so CI needs only db migrate --to <ref>. Every page that put migration check or db verify in the pipeline now shows the one command, and migration check is described as an offline check to run before committing a hand-edited migration. Also drops the claim that migration check notices a migration.ts that was not recompiled; it compares files with the stored hash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 .../content/docs/guides/database/data-migration.mdx    | 10 ++++------
 .../content/docs/guides/database/schema-changes.mdx    |  2 +-
 apps/docs/content/docs/orm/core-concepts.mdx           |  6 +++---
 .../docs/orm/migrations/applying-a-migration.mdx       |  2 +-
 .../docs/orm/migrations/generating-a-migration.mdx     |  2 +-
 .../docs/orm/migrations/how-migrations-work.mdx        |  2 +-
 .../docs/orm/migrations/the-migration-graph.mdx        |  4 ++--
 7 files changed, 13 insertions(+), 15 deletions(-)

diff --git a/apps/docs/content/docs/guides/database/data-migration.mdx b/apps/docs/content/docs/guides/database/data-migration.mdx
index 468732acfa..2cb3020314 100644
--- a/apps/docs/content/docs/guides/database/data-migration.mdx
+++ b/apps/docs/content/docs/guides/database/data-migration.mdx
@@ -39,7 +39,7 @@ Perform an expand-and-contract migration with Prisma ORM, following https://www.
 3. Open the planned `migration.ts` and append a `this.dataTransform(endContract, 'backfill-post-status', { check, run })` operation built with the typed SQL builder against the migration's own end contract: `check` selects `id` from `post` where `published = true AND status != 'Published'` with `limit(1)`, `run` updates those rows to `status = 'Published'`. Recompile with `node <migration-dir>/migration.ts`, confirm `ops.json` contains a `data` operation, then apply with `npx prisma db migrate --advance-ref db`. Verify with a query that every row with `published = true` now has `status = 'Published'`.
 4. Update application code to read and write `status` instead of `published`.
 5. Contract: remove `published` from the contract, run `contract emit`, `migration plan --name drop_published`, review the destructive warning, and apply with `npx prisma db migrate --advance-ref db`.
-6. For the production database, run `npx prisma migration check`, `npx prisma db migrate --show --db "$PRODUCTION_DATABASE_URL"`, then `npx prisma db migrate --db "$PRODUCTION_DATABASE_URL"`. Do not use `db update` against production.
+6. For the production database, run `npx prisma db migrate --db "$PRODUCTION_DATABASE_URL"`, adding `--show` first if you want to preview the route. Do not use `db update` against production.
 ```
 
 </AgentPrompt>
@@ -292,7 +292,7 @@ npx prisma migration show 20260910T1552_add_status
 }
 ```
 
-Commit `migration.ts`, `ops.json`, and `migration.json` together. `npx prisma migration check` fails in CI if they drift apart.
+Commit `migration.ts`, `ops.json`, and `migration.json` together. If `ops.json` or `migration.json` no longer matches the hash stored for the migration, `db migrate` refuses to run it, and `npx prisma migration check` reports the same problem before you commit.
 
 ## 4. Apply the expand migration
 
@@ -438,15 +438,13 @@ Applied at                  Migration                     Change             Ops
 
 ## 6. Deploy to production
 
-Production runs the same migrations from the same files; only the connection string changes. `db migrate` reads the database's marker, finds the path through the [migration graph](/orm/migrations/the-migration-graph), and applies whatever is pending, backfill included. Put three commands in your deploy pipeline:
+Production runs the same migrations from the same files; only the connection string changes. `db migrate` reads the database's marker, finds the path through the [migration graph](/orm/migrations/the-migration-graph), and applies whatever is pending, backfill included. Your deploy pipeline needs one command:
 
 ```npm
-npx prisma migration check
-npx prisma db migrate --show --db "$PRODUCTION_DATABASE_URL"
 npx prisma db migrate --db "$PRODUCTION_DATABASE_URL"
 ```
 
-`migration check` is offline and fails if any `ops.json` no longer matches its `migration.ts`. `--show` is a read-only preview of the route. Here is that preview against a production database that shipped the `init` migration and holds live rows, followed by the apply:
+It refuses to run a migration whose files no longer match the hash stored for it. To see the route before it runs, add `--show`, which previews it without changing anything. Here is that preview against a production database that shipped the `init` migration and holds live rows, followed by the apply:
 
 ```text no-copy
 ℹ The following 2 migrations will run:
diff --git a/apps/docs/content/docs/guides/database/schema-changes.mdx b/apps/docs/content/docs/guides/database/schema-changes.mdx
index 2734b15509..b9711043d9 100644
--- a/apps/docs/content/docs/guides/database/schema-changes.mdx
+++ b/apps/docs/content/docs/guides/database/schema-changes.mdx
@@ -589,7 +589,7 @@ App space
 ✔ All checks passed
 ```
 
-`migration check` is offline and verifies every migration's hash and the graph's integrity. Run it in CI on every pull request so a `migration.ts` edited without a recompile, or a `migration.json` edited by hand, fails before it reaches a shared database.
+`migration check` is offline and verifies every migration's hash and the graph's integrity. Run it after you edit a migration by hand, so an `ops.json` or `migration.json` that no longer matches its hash shows up before you commit. A pipeline does not need it, because `db migrate` refuses such a migration too.
 
 `migration check` reads only the files, so it cannot tell you whether a database matches them. `db verify` does. Run `npx prisma db verify --db "$DATABASE_URL"` after `db migrate`, and it fails if the database's marker or its tables differ from the contract you emitted. A pipeline that migrates a shared database runs `db migrate` alone; it refuses a database whose marker is outside your history with `MIGRATION.MARKER_MISMATCH` before it runs anything. [Migrate a shared database from a workflow](/guides/integrations/github-actions#migrate-a-shared-database) shows the job.
 
diff --git a/apps/docs/content/docs/orm/core-concepts.mdx b/apps/docs/content/docs/orm/core-concepts.mdx
index f0cc4eaab4..f2adc0441e 100644
--- a/apps/docs/content/docs/orm/core-concepts.mdx
+++ b/apps/docs/content/docs/orm/core-concepts.mdx
@@ -213,14 +213,14 @@ npx prisma contract emit
 npx prisma db init --db "$DATABASE_URL"
 ```
 
-**Checking in CI, deploying in CD.** [`migration check`](/cli#other-commands) verifies the migration files and graph offline, so it runs in CI with no database. [`db verify`](/cli/db-verify) is its live counterpart: a read-only check that a database satisfies the contract. A deploy pipeline pins environments with refs and migrates to them by name:
+**Deploying.** A deploy pipeline pins each environment with a ref and migrates to it by name, and that one command is all it needs. `db migrate` refuses to run a migration whose files no longer match its hash, so the pipeline needs no separate check:
 
 ```npm
-npx prisma migration check
-npx prisma db verify --db "$DATABASE_URL"
 npx prisma db migrate --db "$DATABASE_URL" --to production
 ```
 
+[`migration check`](/cli#other-commands) runs the same file checks offline, which is useful before you commit a migration you edited by hand, and [`db verify`](/cli/db-verify) checks, without changing anything, whether a database satisfies the contract.
+
 ## Prompt your coding agent
 
 Projects scaffolded with `create-prisma@latest` install [Prisma ORM skills](/ai/tools/skills#available-skills-for-prisma-8) for your coding agent. Ask your agent to:
diff --git a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
index d1863339b1..7864cbcf7c 100644
--- a/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/applying-a-migration.mdx
@@ -149,7 +149,7 @@ In development, add `--advance-ref db` so the next `migration plan` starts from
 - one directory per [extension package](#extension-spaces) that ships migrations, such as `migrations/pgvector/`
 - `contract.prisma`, `contract.json`, and `contract.d.ts`
 
-When you deploy by hand, run the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed. In a pipeline, the deploy job runs only the last of them, `db migrate` with `--to <ref>`, which that section explains. That is safe, because `db migrate` also refuses to run when a migration's files no longer match its hash. Run `migration check` in your pull-request checks to catch the same problem before anything is deployed.
+When you deploy by hand, run the three commands in [Check before, preview, then apply](#check-before-preview-then-apply). The point of the `migration check` step is to tell you that what you are about to apply is still what was reviewed. In a pipeline, the deploy job runs only the last of them, `db migrate` with `--to <ref>`, which that section explains. That one command is all the pipeline needs, because `db migrate` refuses to run when a migration's files no longer match its hash.
 
 When a migration's `ops.json` or `migration.json` no longer matches the `migrationHash` in its `migration.json`, `migration check` fails with an error whose `code` is `MIGRATION.CHECK_HASH_MISMATCH`, as [Editing a migration](/orm/migrations/editing-a-migration) explains. To fix it, either restore the migration's files from Git, or move the hand edit into `migration.ts` and recompile. If the error comes back right after you recompile, and the migration's backfill updates a model with a `temporal.updatedAtString()` column, recompiling cannot fix it, and [Editing a migration](/orm/migrations/editing-a-migration#worked-example-making-a-column-required) shows how to write that backfill instead.
 
diff --git a/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx b/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
index 27900c3013..ac85ee4746 100644
--- a/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
+++ b/apps/docs/content/docs/orm/migrations/generating-a-migration.mdx
@@ -220,7 +220,7 @@ npx prisma migration graph
 npx prisma migration check
 ```
 
-`migration check` is the one to run in CI, where you read its exit code rather than its output. `0` means every check passed, `4` means an integrity failure such as a missing file or an `ops.json` that someone edited by hand, and `2` means it could not find a migration you named. The one thing it cannot tell you is whether you remembered to [recompile](/orm/migrations/editing-a-migration) after your last edit. You can check that yourself by staging the migration with `git add` and then recompiling it, because if `git status` afterwards shows no unstaged change to `ops.json` or `migration.json`, they were already up to date. This does not work for a backfill on a model with an [`updatedAt` column](/orm/migrations/editing-a-migration#worked-example-making-a-column-required).
+`migration check` also tells you the result in its exit code, if you run it from a script. `0` means every check passed, `4` means an integrity failure such as a missing file or an `ops.json` that someone edited by hand, and `2` means it could not find a migration you named. The one thing it cannot tell you is whether you remembered to [recompile](/orm/migrations/editing-a-migration) after your last edit. You can check that yourself by staging the migration with `git add` and then recompiling it, because if `git status` afterwards shows no unstaged change to `ops.json` or `migration.json`, they were already up to date. This does not work for a backfill on a model with an [`updatedAt` column](/orm/migrations/editing-a-migration#worked-example-making-a-column-required).
 
 :::note[What's early]
 
diff --git a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
index 5e34b72877..31df4a586f 100644
--- a/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
+++ b/apps/docs/content/docs/orm/migrations/how-migrations-work.mdx
@@ -146,7 +146,7 @@ The migration commands are part of the [Prisma ORM CLI](/cli) and run as `npx pr
 | [`migration show <target>`](/cli/migration-show) | Print one migration's operations, DDL preview, and metadata            |
 | `migration list`          | List every on-disk migration                                            |
 | `migration graph`         | Draw your [migration history](/orm/migrations/the-migration-graph) as a graph |
-| `migration check`         | Check that each migration's `migrationHash` still matches its files and no files are missing, for example in CI |
+| `migration check`         | Check that each migration's `migrationHash` still matches its files and no files are missing, before you commit a hand edit |
 
 `<target>` is a migration's directory name, its path under `migrations/app/`, or the first 6 or more characters of its `migrationHash`.
 
diff --git a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
index 7b44bd05fa..e6fccaa09f 100644
--- a/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
+++ b/apps/docs/content/docs/orm/migrations/the-migration-graph.mdx
@@ -109,7 +109,7 @@ When no chain of migrations leads from the marker to the target, the run fails w
 | Which contract state does my database match, and what would `db migrate` run next? | `npx prisma migration status` | Yes |
 | What has actually been applied, and when? | `npx prisma migration log` | Yes |
 
-`migration log` reads the **ledger**, so it tells you what actually ran rather than what should have run, and a rollback appears there as one more applied migration instead of erasing anything. Run `migration check` in your pull-request checks, because it catches a hand-edited migration file or a ref naming a state that does not exist before anything is deployed, and it needs no database connection. `db migrate` also refuses to run a hand-edited migration file. See [Reviewing what you planned](/orm/migrations/generating-a-migration#reviewing-what-you-planned) for its exit codes.
+`migration log` reads the **ledger**, so it tells you what actually ran rather than what should have run, and a rollback appears there as one more applied migration instead of erasing anything. Run `migration check` after you edit a migration by hand or move a ref, because it catches a hand-edited migration file or a ref naming a state that does not exist, and it needs no database connection. A deploy pipeline does not need it: `db migrate --to <ref>` refuses a hand-edited migration file on its own. See [Reviewing what you planned](/orm/migrations/generating-a-migration#reviewing-what-you-planned) for its exit codes.
 
 ### Try it on real fixtures
 
@@ -199,7 +199,7 @@ The graph itself, the way `db migrate` chooses which migrations to run, refs, th
 | List the refs you have named | `npx prisma migration ref list` |
 | Plan a rollback of the migration in `<dir>` | `npx prisma migration plan --from <dir> --to <dir>^ --name <name>` |
 | Apply a rollback migration you planned | `npx prisma db migrate --to <earlier-ref-or-hash>` |
-| Check migration files and refs before you deploy | `npx prisma migration check` |
+| Check migration files and refs offline | `npx prisma migration check` |
 
 ## Prompt your coding agent
 

From 16ca57c323534cc3984958a5ce1749bf2922bf37 Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Fri, 25 Sep 2026 12:44:31 +0200
Subject: [PATCH 14/16] docs(docs): warn that a project config inherits db and
 migrations from a config higher up

Verified with prisma 8.0.0-rc.17: a project config without db or migrations uses the values of a prisma.config.ts in a parent directory, so db commands reach the other project's database and migration plan writes into its migrations folder. Until that changes in a later release, set both in every project config or add parent: false.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 apps/docs/content/docs/cli/configuration.mdx | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/apps/docs/content/docs/cli/configuration.mdx b/apps/docs/content/docs/cli/configuration.mdx
index 82230096bc..774c911c8d 100644
--- a/apps/docs/content/docs/cli/configuration.mdx
+++ b/apps/docs/content/docs/cli/configuration.mdx
@@ -43,7 +43,15 @@ The CLI looks for `prisma.config.ts` in the current directory, or starts from th
 
 The CLI combines the files it finds one section at a time. Inside a section such as `orm`, each top-level key, such as `contract`, `db`, or `migrations`, comes whole from the nearest file that sets it, and the keys nested inside it are not combined. So if a config higher up sets `db.connection` and your project's config sets only `contract`, the CLI uses your `contract` and the other file's `db`. Extensions are the exception: a project config that calls `ormConfig` does not inherit them from a config higher up, even when it leaves `extensions` out. List the extensions your contract uses in each project's own config.
 
-A project inside a larger repository therefore inherits any setting its own config leaves out from a `prisma.config.ts` higher up. To stop that, add `parent: false` to the project's config. The search then ends at that file:
+A project inside a larger repository therefore inherits any setting its own config leaves out from a `prisma.config.ts` higher up.
+
+:::warning[More than one project in a repository]
+
+If a `prisma.config.ts` higher up sets `db` or `migrations`, a project config that leaves them out uses that file's database and migrations folder. `db update`, `db migrate` and `db verify` then connect to the other project's database, and `migration plan` writes into the other project's migrations folder, without a warning. Set `db` and `migrations` in every project's own config, or add `parent: false` to it.
+
+:::
+
+To stop a project's config from inheriting anything, add `parent: false` to it. The search then ends at that file:
 
 ```typescript title="prisma.config.ts"
 import { definePrismaConfig } from "prisma/config";

From db8f82c98363b607a8f88a1ec71f6c0354b5dfe4 Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Fri, 25 Sep 2026 14:43:17 +0200
Subject: [PATCH 15/16] docs(docs): same scopeUserSelects signature on both
 middleware pages, and the empty-glob finding

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 apps/docs/content/docs/cli/configuration.mdx              | 2 +-
 .../content/docs/orm/middleware/how-middleware-works.mdx  | 8 +++++---
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/apps/docs/content/docs/cli/configuration.mdx b/apps/docs/content/docs/cli/configuration.mdx
index 774c911c8d..eb366b6f70 100644
--- a/apps/docs/content/docs/cli/configuration.mdx
+++ b/apps/docs/content/docs/cli/configuration.mdx
@@ -96,7 +96,7 @@ export default definePrismaConfig({
 });
 ```
 
-`contract emit` builds one contract from every matched file whose first line is `// use prisma-8`. It skips a matched file without that line and does not warn, so the line is what makes a file part of the schema. The Prisma editor extension uses the same rule, so the editor and `contract emit` agree on which files make up the schema. If no matched file starts with the line, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`, and the error's finding is `PSL_NO_OPTED_IN_SCHEMA_FILES`.
+`contract emit` builds one contract from every matched file whose first line is `// use prisma-8`. It skips a matched file without that line and does not warn, so the line is what makes a file part of the schema. The Prisma editor extension uses the same rule, so the editor and `contract emit` agree on which files make up the schema. If the glob matches files but none of them starts with the line, `contract emit` fails with `CONTRACT.SOURCE_LOAD_FAILED`, and the error's finding is `PSL_NO_OPTED_IN_SCHEMA_FILES`. If the glob matches no file at all, for example because of a typo in the pattern, the finding is `PSL_NO_SCHEMA_FILES_MATCHED` instead.
 
 A new file joins the schema the next time you run `contract emit`, with no change to the config. The emitted files go in the folder before the first wildcard, here `./prisma/contract.json` and `./prisma/contract.d.ts`.
 
diff --git a/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx b/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
index 5e2567f6b8..70e91dfffa 100644
--- a/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
+++ b/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
@@ -131,7 +131,7 @@ The middleware below adds a condition to every `SELECT` whose own `FROM` clause
 import type { SqlMiddleware } from '@prisma/orm-postgres/family-runtime';
 import { AndExpr, type BinaryExpr } from '@prisma/orm-postgres/relational-core/ast';
 
-export function scopeUserSelects(predicate: BinaryExpr): SqlMiddleware {
+export function scopeUserSelects(condition: () => BinaryExpr | undefined): SqlMiddleware {
   return {
     name: 'scope-user-selects',
     familyId: 'sql',
@@ -140,6 +140,8 @@ export function scopeUserSelects(predicate: BinaryExpr): SqlMiddleware {
       if (draft.ast.kind !== 'select') return undefined;
       if (draft.ast.from?.kind !== 'table-source') return undefined;
       if (draft.ast.from.name !== 'User') return undefined;
+      const predicate = condition();
+      if (predicate === undefined) return undefined;
       const where = draft.ast.where ? AndExpr.of([draft.ast.where, predicate]) : predicate;
       return { ...draft, ast: draft.ast.withWhere(where) };
     },
@@ -151,7 +153,7 @@ The three checks above are how you say "only `SELECT`s, and only ones over the `
 
 These checks read only the table in the query's own `FROM` clause, so `User` rows that a query loads with `.include(...)` or through a join are not filtered. Do not rely on a middleware like this alone to keep one tenant's rows away from another.
 
-The `predicate` you pass in is a comparison you build yourself, and the types for building one come from `@prisma/orm-postgres/relational-core/ast`. A value you compare against needs its `codecId`, which says how the value is stored: `pg/` plus the PostgreSQL type name plus `@1`, so text is `pg/text@1` and a 32-bit integer is `pg/int4@1`:
+The function you pass in returns the comparison to add, or `undefined` to add none, and the middleware calls it for every query. You build the comparison yourself, and the types for building one come from `@prisma/orm-postgres/relational-core/ast`. A value you compare against needs its `codecId`, which says how the value is stored: `pg/` plus the PostgreSQL type name plus `@1`, so text is `pg/text@1` and a 32-bit integer is `pg/int4@1`:
 
 ```ts title="src/prisma/db.ts (excerpt)"
 import { BinaryExpr, ColumnRef, ParamRef } from '@prisma/orm-postgres/relational-core/ast';
@@ -163,7 +165,7 @@ const onlyMia = BinaryExpr.eq(
 );
 ```
 
-Then `scopeUserSelects(onlyMia)` goes in the `middleware` array of your `postgres(...)` client, like any other entry. [Rewrite queries with beforeCompile](/orm/middleware/authoring-custom-middleware#rewrite-queries-with-beforecompile) covers the other comparisons and why a value has to go through `ParamRef.of`. `beforeCompile` is not available on MongoDB, because the tree it works on is made of SQL objects.
+Then `scopeUserSelects(() => onlyMia)` goes in the `middleware` array of your `postgres(...)` client, like any other entry. [Rewrite queries with beforeCompile](/orm/middleware/authoring-custom-middleware#rewrite-queries-with-beforecompile) shows how the function can return a different value for each request, and covers the other comparisons and why a value has to go through `ParamRef.of`. `beforeCompile` is not available on MongoDB, because the tree it works on is made of SQL objects.
 
 ### beforeQuery and beforeExecute: validate or block
 

From bac83ae0971ab401033676e81e7b62f32aeceaca Mon Sep 17 00:00:00 2001
From: willbot <w.a.madden+machine@gmail.com>
Date: Fri, 25 Sep 2026 15:21:16 +0200
Subject: [PATCH 16/16] docs(docs): the middleware calls the condition only for
 a matching SELECT

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>
---
 .../content/docs/orm/middleware/authoring-custom-middleware.mdx | 2 +-
 apps/docs/content/docs/orm/middleware/how-middleware-works.mdx  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
index 3cbbee7b0c..aeadc174b9 100644
--- a/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
+++ b/apps/docs/content/docs/orm/middleware/authoring-custom-middleware.mdx
@@ -250,7 +250,7 @@ The `kind` check on `from` keeps the middleware to plain tables: a `SELECT` that
 
 These checks read only the table in the query's own `FROM` clause, so `User` rows that a query reaches any other way do not get the condition. When you load related users with `.include(...)` from another model, such as the author of each post, the ORM API reads them inside that other model's query, whose `FROM` is the other table. A SQL query builder query that joins `User` onto another table is not filtered either, for the same reason.
 
-The middleware calls `condition` for every query, so the condition can change from one request to the next. You build it from the same classes. Put values through `ParamRef.of` rather than `LiteralExpr.of`, because a `ParamRef` becomes a bound parameter such as `$1` while a literal is pasted into the SQL text itself, so a value that came from one of your users could inject SQL of its own. A `ParamRef` you build by hand has to name the PostgreSQL type of the value with `codec: { codecId: ... }`, and the ids start with `pg/` and end with `@1`, so the `text` column `name` takes `pg/text@1`. Leave that out and the query fails with an error whose `code` is `RUNTIME.PARAM_REF_MISSING_CODEC`.
+The middleware calls `condition` for each `SELECT` whose `FROM` clause names `User`, after the checks above, so the condition can change from one request to the next. You build it from the same classes. Put values through `ParamRef.of` rather than `LiteralExpr.of`, because a `ParamRef` becomes a bound parameter such as `$1` while a literal is pasted into the SQL text itself, so a value that came from one of your users could inject SQL of its own. A `ParamRef` you build by hand has to name the PostgreSQL type of the value with `codec: { codecId: ... }`, and the ids start with `pg/` and end with `@1`, so the `text` column `name` takes `pg/text@1`. Leave that out and the query fails with an error whose `code` is `RUNTIME.PARAM_REF_MISSING_CODEC`.
 
 A request has no tenant of its own, so the middleware reads the value from something in its own scope. The example below keeps it in an `AsyncLocalStorage` from Node.js, which holds one value per request while that request's code runs:
 
diff --git a/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx b/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
index 70e91dfffa..f8f68402b4 100644
--- a/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
+++ b/apps/docs/content/docs/orm/middleware/how-middleware-works.mdx
@@ -153,7 +153,7 @@ The three checks above are how you say "only `SELECT`s, and only ones over the `
 
 These checks read only the table in the query's own `FROM` clause, so `User` rows that a query loads with `.include(...)` or through a join are not filtered. Do not rely on a middleware like this alone to keep one tenant's rows away from another.
 
-The function you pass in returns the comparison to add, or `undefined` to add none, and the middleware calls it for every query. You build the comparison yourself, and the types for building one come from `@prisma/orm-postgres/relational-core/ast`. A value you compare against needs its `codecId`, which says how the value is stored: `pg/` plus the PostgreSQL type name plus `@1`, so text is `pg/text@1` and a 32-bit integer is `pg/int4@1`:
+The function you pass in returns the comparison to add, or `undefined` to add none, and the middleware calls it for each `SELECT` whose `FROM` clause names `User`, after the three checks. You build the comparison yourself, and the types for building one come from `@prisma/orm-postgres/relational-core/ast`. A value you compare against needs its `codecId`, which says how the value is stored: `pg/` plus the PostgreSQL type name plus `@1`, so text is `pg/text@1` and a 32-bit integer is `pg/int4@1`:
 
 ```ts title="src/prisma/db.ts (excerpt)"
 import { BinaryExpr, ColumnRef, ParamRef } from '@prisma/orm-postgres/relational-core/ast';