@prisma/orm-mongo 8.0.0-rc.5 → 8.0.0-rc.5-dev.2

package/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.1-to-8.0.0-rc.2/instructions.md

@@ -0,0 +1,588 @@
+---
+from: "8.0.0-rc.1"
+to: "8.0.0-rc.2"
+changes:
+  - id: check-constraints-are-opaque-expressions
+    summary: |
+      CHECK constraints in `contract.json` changed shape: `{ name, column, valueSet }` became
+      `{ name, prefix, expression }`, where `expression` is the raw SQL predicate and `name`
+      is a content-addressed wire name (`<prefix>_<8hex>`, the same convention indexes and RLS
+      policies already use). Run `prisma-next contract emit` to regenerate `contract.json` and
+      `contract.d.ts` — an old-shape contract is rejected on read, so this is not optional.
+      Regeneration also changes the physical names of your enum CHECK constraints, because the
+      hash suffix is new: `prisma-next migration plan` will show a DROP of the old unsuffixed
+      constraint plus an ADD of the wire-named one. That plan needs `destructive` to drop the
+      stale constraint; under an additive-only policy the new constraint installs and the old
+      one survives, and `prisma-next db verify --strict` reports it as an undeclared extra
+      until you allow the drop. Every list (`many`) column now also carries a declared
+      element-non-null CHECK that the planner previously invented behind your back; it appears
+      in the contract and in the plan for the first time.
+      Introspection also stopped parsing predicates, so every CHECK constraint on a managed
+      table is now visible — including hand-written ones (`price > 0`, a composite `AND`, a
+      `NOT VALID` constraint) that earlier versions could not see at all. An undeclared check
+      is an extra: `prisma-next db verify --strict` reports it, and a plan run under a policy
+      that allows `destructive` emits a `dropCheckConstraint` operation for it. Read the first
+      plan for `dropCheckConstraint` operations naming constraints you wrote by hand. There is
+      To keep one, declare it: `@@check(expression: "…", map: "<its physical name>")` adopts the
+      constraint under the name it already has, after which `db verify` is clean and no plan drops
+      it. `contract infer` writes that form for you, so re-running a pull is the quickest route.
+      Let a drop through only when the constraint is deliberately retired. Running the table under
+      an additive-only policy also keeps it, but leaves it reported by `--strict` as undeclared.
+    detection:
+      glob: "**/contract.json"
+      contains:
+        - '"valueSet"'
+        - '"checks"'
+      anyMatch: true
+  - id: add-check-constraint-takes-an-expression
+    summary: |
+      In committed migration files, `this.addCheckConstraint({ schema, table, constraint,
+      column, values })` is now `this.addCheckConstraint({ schema, table, constraint,
+      expression })`. Replace the `column` and `values` pair with the predicate they used to
+      describe — `column: 'kind', values: ['admin', 'user']` becomes
+      `` expression: `"kind" IN ('admin', 'user')` `` — and use the wire name from your
+      regenerated contract as `constraint`. If the constraint was created by the same
+      migration's `createTable`, prefer moving it inline: add
+      `checkExpression(<name>, <expression>)` to that table's `constraints` array and delete
+      the follow-up `addCheckConstraint` call, which is what a freshly planned migration now
+      produces. Import `checkExpression` from the same migration entrypoint as `col` and
+      `primaryKey`.
+    detection:
+      glob: "**/migrations/**/*.ts"
+      contains:
+        - 'addCheckConstraint'
+      anyMatch: true
+  - id: specifier-default-control-policy-requires-create-namespace
+    summary: |
+      If your `prisma.config.ts` passes `defaultControlPolicy` in the options bag of
+      `typescriptContract` or `typescriptContractFromPath`, that bag now also requires
+      `createNamespace`. Stamping a default policy strips derived CHECK constraints from
+      tables the policy leaves non-managed, and the strip rebuilds storage namespaces through
+      the target's factory, so the two options travel together.
+      `typescriptContract(contract, output, { defaultControlPolicy: 'external' })` becomes
+      `typescriptContract(contract, output, { defaultControlPolicy: 'external',
+      createNamespace: postgresCreateNamespace })`, with `postgresCreateNamespace` imported
+      from the Postgres target's types entrypoint (`@internal/target-postgres/types`) — the
+      same factory the PSL specifier already takes. Calls without an options bag are
+      unchanged, and `emptyContract` already took `createNamespace`.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      contains:
+        - 'typescriptContract'
+        - 'defaultControlPolicy'
+      anyMatch: false
+  - id: int-backed-enums-fail-at-authoring
+    summary: |
+      An `enumType()` whose codec is numeric (e.g. `pg/int4@1`) used to build fine and fail
+      later, at migrate time. It now throws `CONTRACT.ENUM_INVALID` while the contract is being
+      built, because a numeric member set cannot be rendered as a CHECK predicate. If
+      `prisma-next contract emit` fails with "numeric-enum CHECK constraints are not yet
+      supported", change that enum's codec to a text one (`pg/text@1`) and give each member a
+      string value, or replace it with a Postgres native enum (`pg.enum`), which enforces
+      membership through the column type and needs no CHECK at all.
+    detection:
+      glob: "**/*.{ts,mts,cts,prisma}"
+      contains:
+        - 'enumType'
+      anyMatch: true
+  - id: aggregate-methods-come-from-the-emitted-contract
+    summary: |
+      The aggregate methods — `count`, `sum`, `avg`, `min`, `max` — are no longer declared on the
+      ORM and SQL-builder surfaces outright. Each surface is derived from the operation names in
+      the emitted `contract.d.ts`'s `AggregateTypes` block, so a target or extension can contribute
+      an operation and it appears under its own name with no client change. Deriving the surface
+      neither adds nor removes a method by itself, but the block a re-emit produces is not the
+      list it was: PostgreSQL now contributes eight operations and SQLite seven, and every bare
+      result type moved — `count-over-a-field-counts-that-field` and
+      `aggregate-defaults-are-js-native-numbers` cover that, so work them too. If it is not — you author it
+      in code with `defineContract(...)` and hand that value straight to the client (the no-emit
+      flow), or you have not re-emitted since before 8.0.0-rc.1 — every aggregate surface resolves
+      to `AggregateOperationsUnavailable`, an empty type, and each call becomes
+      `Property 'count' does not exist on type 'AggregateOperationsUnavailable'`. That covers
+      `aggregate()`, `groupBy().aggregate()`, `groupBy().having()`, the `include(...)` reducers,
+      and `sql()`'s `fns.count` / `fns.sum` / … Runtime behaviour is unchanged; this is a
+      compile-time change. Re-emit the contract, or cast the builder to a dynamic record.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      contains:
+        - "defineContract"
+        - ".aggregate("
+        - ".having("
+        - "fns.count"
+      anyMatch: true
+  - id: count-over-a-field-counts-that-field
+    summary: |
+      `aggregate.count(field)` renders `COUNT(<column>)`. It used to accept the argument, discard
+      it, and render `COUNT(*)`. PostgreSQL declares `count` over any input, so the derived method
+      carries both arities honestly: `count()` counts rows, `count(field)` counts that field's
+      non-null values. No previously type-safe call changes meaning — `count` took no argument
+      before, so the field-taking form never typechecked. What changes is a call that got past
+      the types: a `@ts-expect-error` above a `count(...)`, a `count(x as never)`, or dynamic
+      dispatch. Those now count a column instead of rows, which differs whenever the column holds
+      NULLs. Sweep them and drop the argument wherever `COUNT(*)` was what you meant.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      contains:
+        - "count("
+        - ".aggregate("
+      anyMatch: true
+  - id: aggregate-defaults-are-js-native-numbers
+    summary: |
+      `count()`, `sum()` over an integer column, and `avg()` over an integer column all return
+      `number`. On PostgreSQL they returned, respectively, a `bigint`; a `bigint` or a decimal
+      string depending on the column's width; and a decimal string. On SQLite the first two
+      returned a `bigint` and `avg()` was already a `number`. The lossless results moved to three new
+      operations beside them — `countBigInt()` → `bigint`, `sumBigInt()` → `bigint` (on
+      PostgreSQL exact past 2^63 over a `BigInt` / `BigIntNumber` / `UnboundedInt` column, whose
+      total the database computes as `numeric`; over the narrower integers the total is an `int8`
+      and PostgreSQL raises `bigint out of range` past 2^63), `avgDecimal()` → decimal string
+      (PostgreSQL only; SQLite has no
+      decimal type and contributes none). An empty input set answers `count()` with `0`, not `0n`.
+      A `count()`, or a `sum()` over an integer column, whose value passes ±(2^53 − 1) raises
+      `RUNTIME.DECODE_FAILED` instead of returning a rounded number — on the `.include()` path as
+      well as the top level — so switch that call to `countBigInt()` / `sumBigInt()` wherever the
+      magnitude is real. No other result is guarded: a `sum` outside the integer columns keeps its
+      own family, and `avg` is a fraction that rounds as any double does.
+      Unchanged: `min` / `max`, `sum` / `avg` over a float column, `sum` over `numeric` (still a
+      decimal string), `sum` over `UnboundedInt` (still a `bigint`), and the ORM's `having(...)`
+      operands, which the ORM types as `number` whatever the aggregate's result type is. The SQL
+      builder's comparison operands are the other case, and they do move: `fns.gt(a, b)` types
+      both sides from one codec, so `fns.gt(fns.count(), 1n)` becomes `fns.gt(fns.count(), 1)`.
+      Sweep aggregate results for
+      `2n`-style literals, `String(count)` serialisation, `Number(...)` unwrapping, and `?? '0'`
+      coalescing, and write each as the plain number it now is. Then re-emit with
+      `prisma-next contract emit`: `contract.d.ts`'s `AggregateTypes` block carries the new
+      result codecs and the three new operations, and until you re-emit, the types describe the
+      old results and the new methods do not exist.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      contains:
+        - ".aggregate("
+        - ".count()"
+        - ".groupBy("
+        - ".include("
+      anyMatch: true
+  - id: integer-columns-refuse-the-wrong-js-type
+    summary: |
+      A `BigInt` or `UnboundedInt` column refuses a JS `number`, and a `BigIntNumber` column
+      refuses a `bigint`, with `RUNTIME.ENCODE_FAILED` and a message naming the type that
+      arrived: `pg/int8@1 value must be a bigint, got number 9`. The wide-integer codecs used to
+      accept a number and stringify it, which let a fractional value such as `1.5` reach an
+      integer column unremarked. No typed call site changes — a `BigInt` column's application
+      type has always been `bigint` — so sweep the ones that bypassed the types: a
+      `// @ts-expect-error` over a create/update value, an `as never` / `as any` argument, a
+      value that came out of `JSON.parse` (which yields numbers, never bigints), and dynamic
+      dispatch. Convert each to the column's own type, `BigInt(value)` for a `bigint` column.
+      Schema-written literal defaults are unaffected: `BigInt @default(0)` still emits, because
+      the JSON side of these codecs accepts a safe-integer number and only the wire side does not.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      contains:
+        - "bigint"
+        - "BigInt"
+      anyMatch: true
+  - id: authored-check-constraints
+    summary: |
+      A CHECK constraint can now be declared in the contract: `@@check(expression: "…", name: "…")`
+      in PSL, `check({ expression, name })` in the TypeScript builder. `name:` is a wire-name
+      prefix — the physical constraint becomes `name_<8hex>`, hashed over the predicate, and
+      compared by name, so Postgres reprinting the expression never causes drift. Use `map:`
+      instead to adopt a constraint that already exists under its own physical name; that form
+      compares the predicate byte-for-byte, and warns whenever the body was not captured from the
+      database — including on contracts `contract infer` wrote, which warn on the next
+      `contract emit`. `contract infer` now writes the `map:` form for you: pulling a database
+      emits `@@check` for every live check Prisma Next did not derive, so a hand-written constraint
+      is declared from the first pull instead of reading as an undeclared extra that a plan allowing
+      destructive changes would drop. Nothing is required of an existing contract — the surface is
+      additive.
+    detection:
+      glob: "**/*.{prisma,ts}"
+      contains:
+        - '@@check'
+      anyMatch: true
+  - id: runtime-query-execute-hard-cut
+    summary: |
+      Runtime row execution uses `query()`, while rc.1 prepared rows use `target.queryPrepared(prepared, params, options?)` and rc.2 uses `prepared.query(target, params, options?)`. Classify each call by its consumed result rather than replacing every `execute`: move row plans to `query`, prepared rows to `prepared.query(target, params, options?)`, and keep non-returning writes on `execute` while reading `affectedRows` when needed. Middleware uses operation-specific `beforeQuery` / `interceptQuery` / `afterQuery` and `beforeExecute` / `interceptExecute` / `afterExecute` hooks, with shared `beforeCompile`; interception returns `{ rows }` for queries and `{ stats }` for execution. There is no operation discriminator, compatibility alias, or generic fallback hook. The Mongo facade keeps static `db.query` and removes row `db.execute`; execute a built row plan through `(await db.runtime()).query(plan)`.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      contains:
+        - ".execute("
+        - ".queryPrepared("
+        - "beforeQuery"
+        - "interceptExecute"
+      anyMatch: true
+  - id: config-file-is-prisma-config-with-an-orm-section
+    summary: |
+      The CLI config file is `prisma.config.ts` — the `prisma-next.config.ts` name is
+      deprecated — and the config value is engine-shaped: `defineConfig` from
+      `@prisma/cli-engine` wraps the whole ORM config as its `orm` section. Rename the file,
+      then wrap the existing export: alias the current `defineConfig` import (from the target
+      facade or CLI config-types) as `ormConfig` and write
+      `export default defineConfig({ orm: ormConfig({ ...existing config... }) })`, adding
+      `@prisma/cli-engine` to devDependencies. Both the deprecated filename and the flat shape
+      still load, each printing a deprecation warning on stderr, so the two steps can land
+      separately; anything asserting clean stderr around CLI invocations sees the warning
+      until both are done.
+    detection:
+      glob: "**/prisma*.config.*"
+      contains:
+        - "defineConfig"
+      anyMatch: true
+  - id: published-prisma-next-bin-retired
+    summary: |
+      Nothing published ships a `prisma-next` bin anymore: `@prisma/orm-toolchain` publishes
+      the `orm` command family at `@prisma/orm-toolchain/cli` and no bin, and the database
+      facades forward no launcher. The only user-facing binary is the unified `prisma` CLI
+      (the prisma-cli distribution), which mounts the same commands. Replace
+      `prisma-next <command>` invocations in package scripts and CI with the unified CLI's
+      equivalent, and drop any dependency that was taken only to put the bin on PATH.
+    detection:
+      glob: "**/package.json"
+      contains:
+        - "prisma-next"
+      anyMatch: true
+  - id: raw-is-a-reserved-storage-namespace
+    summary: |
+      A storage namespace named `raw` is refused: the SQL surface exposes the whole-query raw
+      statement tag as `db.sql.raw`, so a namespace of that name would be unreachable through
+      the builder while the emitted types still promised its tables. Building the client raises
+      `ORM.NAMESPACE_RESERVED` naming the namespace. Rename the namespace in your schema —
+      `@@schema("raw")` becomes any other name — re-emit the contract, and plan the rename
+      against the database as you would any other namespace rename. Only `raw` is reserved; every other namespace name is unaffected.
+    detection:
+      glob: "**/*.{prisma,json}"
+      contains:
+        - '@@schema("raw")'
+        - '"raw": {'
+      anyMatch: true
+  - id: codec-ids-are-checked-where-they-are-authored
+    summary: |
+      A codec id you write in a prepared declaration or in a contract-bound raw fragment is
+      now checked against your contract's codec map, so an id the contract does not carry is
+      a compile error where before it compiled and failed at execution with
+      `RUNTIME.PARAM_REF_MISSING_CODEC`. The usual cause is an unversioned id:
+      `db.prepare({ id: 'pg/int4' }, ...)` becomes `db.prepare({ id: 'pg/int4@1' }, ...)`, and
+      `fns.raw\`...\`.returns('pg/text')` becomes `.returns('pg/text@1')`. Take the id from your
+      emitted `contract.d.ts` — every id it carries now completes at both positions, so the
+      editor offers the correct spelling rather than accepting a wrong one. Raw fragments
+      built through a contract-free lane are unaffected; they have no map to check against.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      contains:
+        - "prepare({"
+        - ".returns('pg/"
+        - ".returns(\"pg/"
+      anyMatch: true
+---
+
+# 8.0.0-rc.1 → 8.0.0-rc.2 — User upgrade instructions
+
+## `aggregate-methods-come-from-the-emitted-contract`
+
+Which aggregate methods exist is now the contract's answer rather than a fixed list in the client. The emitted `contract.d.ts` carries an `AggregateTypes` block naming every operation your target and extensions declare, and each surface below is derived from it:
+
+| Surface | What it offers |
+| --- | --- |
+| `db.orm.User.aggregate((a) => …)` | one selector method per declared operation |
+| `db.orm.User.groupBy('kind').aggregate((a) => …)` | the same |
+| `db.orm.User.groupBy('kind').having((h) => …)` | the same, restricted to `count` / `sum` / `avg` / `min` / `max` |
+| `db.orm.User.include('posts', (posts) => posts.count())` | one reducer per declared operation |
+| `db.sql.public.user.select('n', (f, fns) => fns.count())` | one function per declared operation |
+
+**If your contract is emitted, re-emit it — and keep reading.** Deriving the surface takes nothing away on its own: whatever the composed targets and extensions declare is what the block names. But the built-in targets changed what they declare in this same release. PostgreSQL now contributes eight operations and SQLite seven, and the bare results over integer columns moved — `count`, `sum`, and `avg`. `min` / `max` did not, nor did `sum` and `avg` over a float, `numeric`, or temporal column, nor `sum` over an `UnboundedInt` column. Two entries below carry those changes, and a re-emitted contract lands you in both: [`count-over-a-field-counts-that-field`](#count-over-a-field-counts-that-field) and [`aggregate-defaults-are-js-native-numbers`](#aggregate-defaults-are-js-native-numbers).
+
+**If your contract's block is unknown, the surfaces are empty.** Two situations reach that state:
+
+- You author the contract in TypeScript with `defineContract(...)` and pass the value straight to the client, never running `prisma-next contract emit`. A contract value built in code carries no emitted type maps.
+- You are still using a `contract.d.ts` emitted before 8.0.0-rc.1, when the `AggregateTypes` block did not exist yet.
+
+Either way the call is a compile error:
+
+```text
+Property 'count' does not exist on type 'AggregateOperationsUnavailable'.
+```
+
+The type is an empty interface whose name is the diagnosis; hovering it shows the reason. Nothing changes at runtime — the client installs its aggregate methods from the composed target and extensions, exactly as it always has.
+
+**Preferred fix: emit the contract.** Run
+
+```bash
+prisma-next contract emit
+```
+
+and type the client from the emitted `Contract`. That gives you the whole aggregate surface back, plus the per-operation result types and the field names each operation admits.
+
+**Alternative, where the contract is deliberately un-emitted:** cast the builder and dispatch by name.
+
+```ts
+import type { AggregateSpec } from '@prisma/orm-postgres/orm-client';
+
+type DynamicAggregates = Record<string, (field?: string) => AggregateSpec[string]>;
+
+const stats = await db.User.aggregate((aggregate) => {
+  const dynamic = aggregate as DynamicAggregates;
+  return { total: dynamic['sum']!('views'), peak: dynamic['max']!('views') };
+});
+```
+
+If you previously widened the *argument* instead — `aggregate.sum('views' as never)`, which compiled because the admitted field names were already `never` for such a contract — move the cast from the argument to the builder and pass the field name as a plain string.
+
+## `count-over-a-field-counts-that-field`
+
+```ts
+await db.User.aggregate((aggregate) => ({ all: aggregate.count() }));
+// SELECT COUNT(*) …
+
+await db.User.aggregate((aggregate) => ({ withEmail: aggregate.count('email') }));
+// SELECT COUNT("email") … — rows whose email is NULL are not counted
+```
+
+The second form used to render `COUNT(*)`: the argument was accepted and thrown away. Both arities are now read off what the target declares for `count` — PostgreSQL declares it over any input, which means both a call with a value and a call without one — so the argument is honoured.
+
+No previously type-safe call changes meaning, because `count` took no argument and the field-taking form did not typecheck. Sweep instead for calls that bypassed the types:
+
+- a `// @ts-expect-error` directly above a `count(...)` call — where the argument is a field your contract admits, that suppression is now unused and TypeScript flags the unused directive;
+- `count(field as never)` or `count(field as any)`;
+- dynamic dispatch through a `Record<string, …>` cast.
+
+For each, decide which count you meant: `count()` for rows, `count(field)` for that field's non-null values.
+
+## `aggregate-defaults-are-js-native-numbers`
+
+The aggregate vocabulary is split in two. The bare operations answer in the type a JS developer expects; three new suffixed operations answer losslessly.
+
+| Call | Reads as | Empty input set |
+| --- | --- | --- |
+| `count()` | `number` | `0` |
+| `countBigInt()` | `bigint` | `0n` |
+| `sum(field)` over `Int` / `BigInt` / `BigIntNumber` | `number \| null` | `null` |
+| `sumBigInt(field)` over any integer column | `bigint \| null` | `null` |
+| `avg(field)` over any integer column | `number \| null` | `null` |
+| `avgDecimal(field)` over any integer or `Decimal` column | decimal `string \| null` | `null` |
+
+These do not move: `min` / `max` keep the column's own type; `sum` and `avg` over a float column stay `number`; `sum` over `Decimal` stays a decimal string; `sum` over `UnboundedInt` stays a `bigint`; and the ORM's `having(...)` operands stay plain numbers, because the ORM types a HAVING comparand as `number` whatever result type the aggregate carries.
+
+The SQL builder's comparison operands are the other case, and they do move. `fns.gt(a, b)` types both sides from one codec, so a literal compared against an aggregate follows that aggregate's result codec:
+
+```ts
+// before
+.having((_f, fns) => fns.gt(fns.count(), 1n))
+// after
+.having((_f, fns) => fns.gt(fns.count(), 1))
+```
+
+Make the same one-token change wherever a `fns.count()` or an integer `fns.sum(...)` meets a literal — in `having(...)`, in `where(...)`, and inside a larger expression.
+
+SQLite states the same policy in its own terms — `count`, integer `sum`, and `avg` are all `number`, with `countBigInt` and `sumBigInt` beside them. **SQLite has no `avgDecimal`**: an exact mean needs a decimal type the database does not have, so the method is absent from a SQLite contract and calling it is a type error.
+
+### What to change
+
+1. **Re-emit first.** `prisma-next contract emit` rewrites the `AggregateTypes` block. Until you do, the types describe the old results and the three new methods do not exist.
+2. **Unwrap the bigint handling around bare aggregates.** Each of these is now noise or a type error:
+
+   ```ts
+   const { total } = await db.User.aggregate((a) => ({ total: a.count() }));
+
+   total === 2n              // ← was needed; now `total === 2`
+   Number(total)             // ← was needed; `total` is already a number
+   String(total)             // ← was needed for JSON; JSON.stringify handles it now
+   JSON.stringify(rows, (_k, v) => typeof v === 'bigint' ? String(v) : v)
+   //                        ↑ the replacer can go
+   ```
+
+3. **Change the method, not the value, where you need exactness.** A decimal-string average was doing real work in a money or reporting path; `avgDecimal(field)` returns exactly what `avg(field)` used to, and `countBigInt()` exactly what `count()` used to.
+
+   `sumBigInt(field)` matches the old `sum(field)` everywhere but one column class. On PostgreSQL, a `BigInt` or `BigIntNumber` column's `sum` used to be a decimal `string`, because the database totals a 64-bit column as `numeric`; `sumBigInt` reads that same total as a `bigint`. So a money path summing a `BigInt` column gets a `bigint` where it had a string — exact either way, but a different type. Convert at the consumption site (`String(total)`) if a decimal library or a string comparison is downstream. Over every other integer column, and on SQLite, `sumBigInt` is the old `sum` unchanged.
+
+### The bare operations throw rather than round
+
+A `count()`, or a `sum()` over an integer column, whose value passes ±(2^53 − 1) raises a structured error instead of answering with a rounded one:
+
+```text
+RUNTIME.DECODE_FAILED: pg/int8number@1 value must be an integer within
+the safe integer range, got 9007199254740992
+```
+
+That is the trade these defaults make: a value you can compare, serialise, and do arithmetic with, and a loud failure rather than a quietly wrong total. It fires on the `.include()` path too — the reducer's value travels as a JSON number, but the guard runs after the parse, and rounding is monotone, so a value that was outside the range is still outside it after parsing.
+
+Those two are the results a guarded integer codec produces. A `sum` over a `Decimal`, `UnboundedInt`, or float column stays in that column's own family and has no such guard, and neither does `avg`, which is a fraction already and rounds as any double does — reach for `avgDecimal` where the exact mean matters.
+
+Totals cross the boundary in practice where counts do not: summing 64-bit IDs, or cent amounts across a large table. If a `sum` in your code can plausibly get there, move it to `sumBigInt` now rather than waiting for the error in production.
+
+### If you are upgrading from before 8.0.0-rc.1
+
+You cross two hops, and the aggregate result types move in both. The `0.17 → 8.0.0-rc.1` step changes `count()` to `bigint` and integer averages to decimal strings; this step changes those same calls to `number` and adds the suffixed variants. Apply the steps in order — that is what the upgrade skill does — but do the sweeping once, at the end: for `count()` and integer `sum()` / `avg()`, the destination is `number`, which is where a pre-8.0.0-rc.1 codebase already was. What genuinely changed for you across both hops is the throw outside ±(2^53 − 1) on `count()` and integer `sum()`, and the three new operations; the empty-relation `count` ends where it started, at `0`.
+
+## `integer-columns-refuse-the-wrong-js-type`
+
+Writing a JS `number` to a `BigInt` or `UnboundedInt` column now fails before any SQL runs:
+
+```text
+RUNTIME.ENCODE_FAILED: pg/int8@1 value must be a bigint, got number 9
+```
+
+The codec used to accept the number and stringify it, so `9` wrote `9` and `1.5` wrote `1.5` — a fractional value in an integer column, unremarked. The mirror case reports as clearly: passing `9n` to a `BigIntNumber` column names the type that arrived rather than complaining about a range the value is plainly inside.
+
+No typed call site changes, because a `BigInt` column's application type has always been `bigint`. Sweep the ones that got past the types:
+
+- a `// @ts-expect-error` over a `create(...)` / `update(...)` value;
+- `value as never` or `value as any` in a write;
+- a value that came out of `JSON.parse`, which yields numbers and never bigints;
+- dynamic dispatch through a `Record<string, unknown>`.
+
+Convert each to the column's own type — `BigInt(value)` for a `bigint` column, and a plain number for a `BigIntNumber` one.
+
+Schema-written defaults need nothing. `BigInt @default(0)` still emits and still migrates: the JSON side of these codecs accepts a safe-integer number, because a schema language writes no `bigint` literal, and only the query-parameter side requires the exact type.
+
+
+## `config-file-is-prisma-config-with-an-orm-section`
+
+Two mechanical steps, in either order:
+
+1. `git mv prisma-next.config.ts prisma.config.ts` (same for `.mts` / `.mjs` variants).
+2. Wrap the flat export in the engine shape:
+
+```ts
+// before
+import { defineConfig } from '@prisma/orm-postgres/config';
+export default defineConfig({ ... });
+
+// after
+import { defineConfig } from '@prisma/cli-engine';
+import { defineConfig as ormConfig } from '@prisma/orm-postgres/config';
+export default defineConfig({ orm: ormConfig({ ... }) });
+```
+
+Add `@prisma/cli-engine` to `devDependencies`. The inner config is unchanged — only the file
+name and the outer wrapper move. The loader still discovers the deprecated filename and still
+accepts the flat shape, each with a stderr deprecation warning, so nothing breaks mid-rename;
+finish both steps to silence the warnings.
+
+## `published-prisma-next-bin-retired`
+
+`prisma-next ...` in a package script resolved through a bin the database facades forwarded
+from the toolchain. That chain is gone: the published toolchain is bin-less and exports the
+`orm` command family at `@prisma/orm-toolchain/cli` for the unified `prisma` CLI (the
+prisma-cli distribution) to mount. Point scripts and CI at the unified CLI, which serves the
+same command paths.
+
+<!--
+PR #30049: `changes: []`. The 8.0.0-rc.2 release cut. The example diff is the lockstep version bump, the `@prisma/cli-engine` peer moving to 0.1.1, and the supabase contract fixtures re-emitted so their embedded extension version matches. No user API, contract, configuration, generated-artifact, or source translation follows from it — the consumer-facing changes this release ships are the entries above, recorded by the PRs that made them.
+PR #29910: `changes: []`. The example changes repair test instrumentation and fixture/runtime isolation after the driver SPI split; they require no user API, contract, configuration, generated-artifact, or source translation.
+PR #29902: `changes: []`. Generated contracts gain additive aggregate rows for new opt-in integer representation codecs, but existing schemas and source require no migration; users re-emit only when adopting the new target-scoped types.
+PR #29950: `changes: []`. The demo applications adopt the integer representation types and the precision-preserving aggregates on their own models, and the reference docs gain the matching examples; the diff is confined to example apps and documentation and requires no user API, contract, configuration, generated-artifact, or source translation.
+PR #29939: `changes: []`. Dependabot's weekly runtime-dependency bumps (`ws`, `lucide-react`, `postcss`, `uniku`, `@vercel/detect-agent`, and the `@types/node` / `@types/pg` / `tsx` catalog entries). The example diff is dependency version strings, and requires no user API, contract, configuration, generated-artifact, or source translation.
+PR #29940: `changes: []`. Dependabot's weekly dev-dependency bumps (type packages, wrangler, biome, test tooling) plus the matching `biome.jsonc` `$schema` realignment; the example diffs are devDependency version strings and a schema URL, and require no user API, contract, configuration, generated-artifact, or source translation.
+PR #29965: `changes: []`. Dependabot's dev-dependency bumps (`wrangler`, `@cloudflare/vitest-pool-workers`, `@biomejs/biome`) plus the matching `biome.jsonc` `$schema` realignment to 2.5.7; the example diffs are devDependency version strings and a schema URL, and require no user API, contract, configuration, generated-artifact, or source translation.
+PR #30031: `changes: []`. Dependabot's weekly runtime-dependency bumps (`esbuild`, `evlog`, `next`). The example diff is dependency version strings, and requires no user API, contract, configuration, generated-artifact, or source translation.
+-->
+
+## Regenerating is the first step
+
+`prisma-next contract emit` rewrites `contract.json` / `contract.d.ts` into the new check shape
+and mints the wire names every later step refers to. Do it before editing migration files, so
+the constraint names you paste into `addCheckConstraint` / `checkExpression` are the ones the
+contract actually declares.
+## What the first plan after upgrading looks like
+
+For each enum-restricted column: a DROP of the old unsuffixed constraint and an ADD of the
+wire-named one. For each list column: an ADD of an element-non-null constraint that was
+previously created without ever being declared. Neither is a data change — but the DROP is
+classified `destructive`, so a plan run under an additive-only policy converges only partway
+and `db verify --strict` will report the leftovers until you allow it.
+
+There may also be a third kind of operation, and it is the one to read carefully. Introspection
+no longer parses predicates: it captures every CHECK constraint on a managed table verbatim,
+including the hand-written and platform-installed ones that earlier versions were structurally
+unable to see. A check the contract does not declare is an undeclared extra, so
+`db verify --strict` reports it and a plan run under a policy that allows `destructive` emits a
+`dropCheckConstraint` for it — a constraint you wrote by hand and that has been enforcing your
+data all along. Grep the first plan for `dropCheckConstraint` and check every constraint named:
+
+- to keep it, run plans for that table under an additive-only policy. The constraint stays in
+  place and keeps enforcing; plain `db verify` tolerates it, and only `--strict` reports it as
+  an undeclared extra. Better: declare it with `@@check(expression: "…", map: "<physical name>")`,
+  or re-run `contract infer`, which now emits exactly that for every live check Prisma Next did
+  not derive — the constraint becomes declared and stops being an extra at all;
+- if it was already dead, let the drop through under the destructive plan.
+
+Nothing drops silently — an additive-only policy never emits the operation at all — but the
+first plan after upgrading is the moment to look, because it is the first plan that can see
+these constraints.
+
+## `runtime-query-execute-hard-cut`
+
+Runtime operations state whether the caller expects rows or statement statistics. Do not apply a global `execute` → `query` replacement: an insert, update, or delete that does not return rows belongs on `execute`, while a select, a returning write, a Mongo command-result plan, or any plan whose result is iterated, awaited as an array, indexed, decoded, or otherwise read belongs on `query`.
+
+| 8.0.0-rc.1 | 8.0.0-rc.2 |
+| --- | --- |
+| `await runtime.execute(rowPlan)` | `await runtime.query(rowPlan)` |
+| `runtime.execute(rowPlan).toArray()` | `runtime.query(rowPlan).toArray()` |
+| `await target.queryPrepared(prepared, params, options?)` | `await prepared.query(target, params, options?)` |
+| `await runtime.execute(nonReturningWrite)` with ignored rows | `await runtime.execute(nonReturningWrite)` and ignore the returned statistics |
+| A count or status derived from rows returned by a non-returning write | `const stats = await runtime.execute(writePlan)` and use `stats.affectedRows` |
+
+Apply the same classification to connection and transaction scopes. `query()` and `prepared.query(target, params, options?)` remain lazy row results, so consume them inside the scope when their connection or transaction must remain valid. `execute()` is eager and resolves to `{ affectedRows: number }`; it does not return an iterable, and `affectedRows` must not be synthesized from a row array's length.
+
+If the application defines runtime middleware, use the operation-specific hooks: query interception returns `{ rows }`, execute interception returns `{ stats }`, and completion handlers use their matching `afterQuery` or `afterExecute` result. `beforeQuery` / `interceptQuery` / `onRow` / `afterQuery` and `beforeExecute` / `interceptExecute` / `afterExecute` are distinct capabilities, while `beforeCompile` remains shared. Hook selection carries the operation distinction; contexts and results have no operation discriminator. Row-oriented middleware must not derive statistics from rows, and no compatibility aliases or generic fallback hooks are provided.
+
+Tests that observe row queries should spy on `driver.query`, not `driver.execute`; statistics tests should observe `driver.execute`. Keep separate row-result and statistics queues so a wrong route fails loudly. Behavior intended for both operations assigns one private implementation to both corresponding hook names. Mongo keeps `db.query` as the static builder and has no row-execution `db.execute` facade method: build with `db.query`, obtain the connected runtime, then query through `(await db.runtime()).query(plan)`.
+
+Search broadly for `.execute(` and retired prepared execution, then inspect each candidate's plan and downstream use. Rows being iterated, indexed, decoded, compared as arrays, or passed to a row mapper identify `query`; reads of `affectedRows` or ignored results from non-returning DML identify `execute`. Leave unrelated APIs such as migration runners alone.
+
+## `raw-is-a-reserved-storage-namespace`
+
+The SQL surface answers `db.sql.raw` with the whole-query raw statement tag, so `raw` is no
+longer available as a storage namespace name. A contract that declares one is refused where the
+client is built, before any query runs:
+
+```text
+ORM.NAMESPACE_RESERVED: The SQL surface exposes the raw statement tag as "db.raw", so a storage
+namespace named "raw" cannot be reached through it. Rename the namespace in the schema.
+```
+
+Rename the namespace and re-emit:
+
+```prisma
+// Before: unreachable through the builder
+model Event {
+  id String @id
+  @@schema("raw")
+}
+
+// After: any other name
+model Event {
+  id String @id
+  @@schema("ingest")
+}
+```
+
+Then re-emit the contract, and plan the rename against the database as you would any
+other namespace rename — the physical schema still carries the old name until a plan moves it.
+Only `raw` is reserved; no other namespace name is affected.
+
+## `codec-ids-are-checked-where-they-are-authored`
+
+Two places where you write a codec id by hand now check it against the codec map your
+contract emitted: the declaration passed to `db.prepare(...)`, and `.returns(...)` on a raw
+fragment built from a contract-bound tag.
+
+```ts
+// Before: compiled, then failed at execution with RUNTIME.PARAM_REF_MISSING_CODEC
+await db.prepare({ id: 'pg/int4' }, (sql, params) => ...);
+const upper = fns.raw`UPPER(${f.email})`.returns('pg/text');
+
+// After: the id is the one your contract carries
+await db.prepare({ id: 'pg/int4@1' }, (sql, params) => ...);
+const upper = fns.raw`UPPER(${f.email})`.returns('pg/text@1');
+```
+
+The compile error is the messenger, not the injury: an id no codec registry carries could
+never have executed. If a declaration or fragment of yours stops compiling, the id in it was
+already wrong at runtime.
+
+Read the correct spelling off your emitted `contract.d.ts`, or let the editor offer it — the
+ids now complete at both positions, which is the other half of this change.
+
+A raw fragment built through a contract-free lane keeps accepting any string: that lane has
+no contract map to check an id against.

package/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.2-to-8.0.0-rc.3/instructions.md

@@ -0,0 +1,5 @@
+---
+from: "8.0.0-rc.2"
+to: "8.0.0-rc.3"
+changes: []
+---