@prisma/orm-mongo 8.0.0-rc.4-dev.17 → 8.0.0-rc.5-dev.1

package/skills/prisma-8/upgrading/extension/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: []
+---

package/skills/prisma-8/upgrading/extension/upgrades/8.0.0-rc.3-to-8.0.0-rc.4/instructions.md

@@ -0,0 +1,137 @@
+---
+from: "8.0.0-rc.3"
+to: "8.0.0-rc.4"
+changes:
+  - id: prisma-config-hard-cut-and-top-level-commands
+    summary: |
+      The deprecated fallbacks are gone: the CLI no longer reads
+      `prisma-next.config.ts`, no longer accepts the flat (un-nested) config shape, and the
+      `prisma-next` command no longer exists. The unified CLI (`@prisma/cli`, installed from
+      the `next` dist-tag; its binary is currently `prisma-cli`) runs the ORM commands at the
+      top level — `contract emit`, `db init`, `migration plan`, `migrate` — with only `init`
+      under the `orm` group (`orm init`), and the only config it reads is `prisma.config.ts`
+      in the engine envelope shape.
+
+      1. Rename `prisma-next.config.ts` to `prisma.config.ts` if you have not already.
+      2. Rewrite the export to the envelope shape. Old flat shape:
+         `import { defineConfig } from '@prisma/orm-postgres/config';`
+         `export default defineConfig({ contract: '…', db: { connection: … } });`
+         New shape:
+         `import { definePrismaConfig } from '@prisma/cli-engine';`
+         `import { defineConfig as ormConfig } from '@prisma/orm-postgres/config';`
+         `export default definePrismaConfig({ orm: ormConfig({ contract: '…', db: { connection: … } }) });`
+         The options object moves into the target helper unchanged. The same pattern applies
+         to `@prisma/orm-sqlite/config` and `@prisma/orm-mongo/config`.
+      3. If the config reads `process.env`, keep (or add) `import 'dotenv/config';` as the
+         first import — the loader does not read `.env` for you.
+      4. In `package.json`, replace the `prisma-next` devDependency with `@prisma/cli@next`
+         plus `@prisma/cli-engine` at the exact version that `@prisma/cli` names in its own
+         dependencies, and update your extension's contract-space
+         build and emit scripts from `prisma-next contract emit` to `prisma-cli contract emit`.
+      5. Run `prisma-cli contract emit` to confirm the config loads and to regenerate the
+         artifacts (their generated-file headers change with this release).
+    detection:
+      glob: "**/prisma-next.config.ts"
+  - id: facades-compose-the-raw-lane
+    summary: |
+      A facade no longer gets the whole-query raw tag from the builder. `Db<C>` is a pure
+      namespace map now, so the `raw` key it used to answer is gone, and the tag is composed at
+      client build instead.
+
+      Build it with `createRawLane({ context, rawCodecInferer })` from
+      `@internal/sql-builder/runtime`, typed `RawLane<TContract>` from
+      `@internal/sql-builder/types`, and expose it as your client's `raw`. Callers then write
+      ``client.raw.sql`SELECT ...` ``. A client that binds per role or per scope builds one lane
+      per bound context, the way it already builds one `sql` per context. A static context —
+      the no-runtime shape that returns `context`, `contract` and `sql` — builds one too and
+      returns it as `raw`.
+
+      If your `raw` property was the contract-free expression tag (`createRawSql(inferer)`), it
+      changes shape from a callable to `{ sql }`. That breaks your own surface, so note it in
+      your release.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      regex:
+        - 'createRawSql\('
+        - 'RawSqlTag'
+        # `fns.raw` is a fragment call site and is deliberately excluded:
+        # fragments are unchanged by this release.
+        - '(?<!(?<![\w$])fns)\.raw`'
+      anyMatch: true
+  - id: reserved-raw-namespace-check-removed
+    summary: |
+      `sql()` no longer refuses a contract whose storage declares a namespace named `raw`, and
+      `ORM.NAMESPACE_RESERVED` leaves the error catalogue. Nothing raises the code now, so drop
+      any branch that matched it: a test asserting the refusal, a doc listing the code, an
+      error mapping of your own.
+    detection:
+      glob: "**/*.{ts,mts,cts,md}"
+      contains:
+        - "ORM.NAMESPACE_RESERVED"
+      anyMatch: true
+  - id: contract-fixture-restamp
+    summary: |
+      Committed contract artifacts (`contract.json` / `contract.d.ts`, including test
+      fixtures) embed the toolchain version, which moves to 8.0.0-rc.4. Regenerate them
+      with your emit script (`build:contract-space` or equivalent) after upgrading, or
+      fixture comparisons fail on the version stamp alone.
+    detection:
+      glob: "**/contract.json"
+      contains:
+        - '"version": "8.0.0-rc.3"'
+---
+
+# 8.0.0-rc.3 → 8.0.0-rc.4 — Extension-author upgrade instructions
+
+## `facades-compose-the-raw-lane`
+
+`Db<C>` is a namespace map and nothing else, so a facade composes the whole-query raw tag itself
+and exposes it as the raw lane:
+
+```ts
+import { createRawLane, sql } from '@internal/sql-builder/runtime';
+import type { Db, RawLane } from '@internal/sql-builder/types';
+
+const sqlDb: Db<TContract> = sql<TContract>({ context, rawCodecInferer });
+const raw: RawLane<TContract> = createRawLane<TContract>({ context, rawCodecInferer });
+```
+
+Callers reach the tag at `client.raw.sql`. A client that binds per role or per scope builds one
+lane per bound context, exactly as it already builds one `sql` per context.
+
+A static context does the same. If your facade ships a no-runtime surface — the shape that
+returns `context`, `contract`, `sql` and friends without opening a connection — build the lane
+there too and return it as `raw`:
+
+```ts
+export interface YourStaticContext<TContract extends Contract<SqlStorage>> {
+  readonly sql: Db<TContract>;
+  readonly raw: RawLane<TContract>;
+  // …context, contract, enums
+}
+
+const raw: RawLane<TContract> = createRawLane<TContract>({ context, rawCodecInferer });
+```
+
+Its `raw` property changes type from the contract-free tag to `RawLane<TContract>`, the same
+change the connected client makes, so a consumer reads both surfaces the same way.
+
+Two shapes change for your consumers. Anyone who wrote ``client.sql.raw`...` `` writes
+``client.raw.sql`...` ``. Anyone who called `client.raw` as an expression tag calls
+`client.raw.sql`...`.returns(codecId)` instead, or `fns.raw` inside a builder callback. Both are
+breaking changes to your own surface, so note them in your release.
+
+The detector looks for `createRawSql(`, `RawSqlTag`, and `raw` used as a tag. It skips the
+receiver `fns` exactly, including `x.fns.raw`, because that is a fragment call site and needs no
+change. A receiver that merely ends in those letters, such as `myfns.raw`, still matches, as
+does a functions object aliased to another name.
+
+## `reserved-raw-namespace-check-removed`
+
+`sql()` used to refuse a contract whose storage declared a namespace named `raw`, raising
+`ORM.NAMESPACE_RESERVED` at client construction. The check is gone with the constraint it
+enforced: the lane is composed by the client, not answered by the namespace map, so no contract
+can shadow it.
+
+Drop any branch that matched the code — a test asserting the refusal, an error mapping, a doc
+that lists it. The code no longer exists in the catalogue, and nothing raises it.

package/skills/prisma-8/upgrading/extension/upgrades/8.0.0-rc.4-to-8.0.0-rc.5/instructions.md

@@ -0,0 +1,129 @@
+---
+from: "8.0.0-rc.4"
+to: "8.0.0-rc.5"
+changes:
+  - id: wrap-pg-constructions-with-suppress-idle-connection-errors
+    summary: |
+      Wrap every pg `Pool` or `Client` your extension constructs with `suppressIdleConnectionErrors`, newly exported from `@internal/driver-postgres/runtime` (canonical home `@internal/utils/suppress-idle-connection-errors`). node-postgres emits 'error' on the pool or client when an idle connection drops; with no listener Node kills the host process. The helper attaches a no-op listener, is idempotent per emitter, and returns the same instance. Bindings handed to the driver (`pgPool`/`pgClient`/`url`) are wrapped by the driver itself since rc.5, so this applies to pg handles your extension uses outside a driver binding.
+    detection:
+      glob: "**/*.ts"
+      contains:
+        - "new Pool("
+        - "new Client("
+        - "new pg.Pool("
+        - "new pg.Client("
+      anyMatch: true
+  - id: distinct-on-requires-postgres-capability
+    summary: |
+      `Collection#distinctOn(...)` now requires the contract to declare the `postgres.distinctOn`
+      capability, mirroring the sql-builder lane's existing gate. A contract without it (e.g.
+      SQLite-only) makes the call a compile error — the parameter type narrows to `never` — where
+      it used to compile and silently produce undeduped rows at runtime, since the target's
+      renderer never rendered `DISTINCT ON` for a target that cannot express it.
+
+      Every `.distinctOn(...)` call your code makes on a `Collection` was already wrong on any
+      target lacking `postgres.distinctOn`; the type error is the fix surfacing at compile time
+      instead of a silently wrong result set at runtime. Move the call to a contract that
+      declares `postgres.distinctOn`, or remove it — there is no runtime opt-out.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      regex:
+        - '\.distinctOn\('
+      anyMatch: true
+  - id: groupby-pre-group-pagination-now-scopes-rows
+    summary: |
+      `take()`, `skip()`, `cursor()`, `distinct()`, `distinctOn()`, and `orderBy()` written before
+      `.groupBy(...)` on a `Collection` now scope the rows that get grouped, instead of being
+      silently dropped. `db.orm.<Model>.take(10).groupBy('x').aggregate(...)` used to group every
+      matching row; it now groups only the first 10 (by whatever `orderBy()` is active).
+
+      There is no reliable static pattern that separates a call site whose answer just became
+      correct from one whose answer is now different from before — both look identical in source.
+      Any test asserting values on a `.groupBy(...)` chain with a pre-group pagination clause
+      needs re-checking against the new (correct) numbers by hand.
+  - id: groupby-post-group-pagination-requires-order-by
+    summary: |
+      `GroupedCollection` gained its own `take()` / `skip()` / `orderBy()`, which page the grouped
+      rows themselves when written *after* `.groupBy(...)`. Post-group `take()` / `skip()` require
+      a prior post-group `orderBy()` — without one they are a compile error, the parameter type
+      narrows to `never`, because a database may return groups in any order and "the first n
+      groups" is undefined without one.
+
+      This is not a rote find-and-replace: `db.orm.<Model>.groupBy('x').take(10)` needs a caller
+      to pick what "first" means for their groups, which is a decision only they can make. Add an
+      `.orderBy(...)` naming one of the fields passed to `groupBy(...)` before the `take()` /
+      `skip()` call.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      regex:
+        - '\.groupBy\('
+      anyMatch: true
+---
+
+# 8.0.0-rc.4 → 8.0.0-rc.5 — Extension author upgrade instructions
+
+## `wrap-pg-constructions-with-suppress-idle-connection-errors`
+
+Walk every file matched by `detection.glob`. For each pg `Pool` or `Client` the extension constructs, wrap the construction:
+
+```ts
+import { suppressIdleConnectionErrors } from '@internal/driver-postgres/runtime';
+
+const pool = suppressIdleConnectionErrors(
+  new Pool({ connectionString: options.url }),
+);
+```
+
+This is the same translation applied to the in-repo `@internal/postgres` and `@internal/extension-supabase` runtimes in this transition. The helper only attaches a no-op `'error'` listener (connect/query failures still reject their own promises), so behavior is otherwise unchanged; without it, a dropped idle connection crashes the process that hosts the extension.
+
+If your extension's test suite fakes the `pg` module, the fakes need an `on` method (`on = vi.fn().mockReturnThis()` on a class fake, or `on: vi.fn()` on an object literal) — the runtime now calls `.on('error', ...)` on every pool, client, and checked-out pool client.
+## `distinct-on-requires-postgres-capability`
+
+`Collection#distinctOn(...)` used to compile and run on any target, but only Postgres ever
+rendered its `DISTINCT ON` clause — a call on any other target (SQLite) compiled clean and
+silently returned undeduped rows at runtime. The method now carries the same capability gate the
+sql-builder lane already enforces: its parameter type narrows to `never` unless the contract
+declares `postgres.distinctOn`, so the same call is a compile error on a contract that lacks it,
+and a runtime error carrying `ORM.CAPABILITY_MISSING` if reached dynamically (e.g. through a
+hand-built `CollectionState`).
+
+Find every `.distinctOn(...)` call your code makes on a `Collection` and check whether the
+contract it runs against declares `postgres.distinctOn`. If it does, nothing changes — the call
+already worked correctly and keeps compiling. If it does not, the call was already producing the
+wrong result set; either move the collection onto a Postgres-capable contract, or remove the
+`.distinctOn(...)` call and accept the undeduped rows it was silently returning before.
+
+`Collection#distinct(...)` is unaffected — it lowers to a portable `ROW_NUMBER` dedup and needs
+no capability, on any target.
+
+## `groupby-pre-group-pagination-now-scopes-rows`
+
+Any `.take(...)`, `.skip(...)`, `.cursor(...)`, `.distinct(...)`, `.distinctOn(...)`, or
+`.orderBy(...)` your extension calls *before* `.groupBy(...)` on a `Collection` used to be
+silently dropped once `.groupBy(...)` joined the chain — the aggregate reduced over every
+matching row, ignoring the pagination clause entirely. It now scopes the rows that get grouped,
+the same way root `.aggregate()` scopes its rows (see the sibling entry for that fix, already
+shipped in `8.0.0-rc.4` → `8.0.0-rc.5`'s predecessor window).
+
+There is no detection regex for this one worth writing: the call sites that need re-checking
+look identical, in source, to the call sites that already worked correctly (a chain built with
+this scoping in mind, versus one that assumed the pagination clause was a no-op). Grep for
+`.groupBy(` and read every match with a pre-group pagination clause; if the test asserting its
+result seeds fewer distinct groups than pagination scope allows, or asserts totals computed over
+every row rather than the paginated window, the expected values need updating to match the now-
+correct behavior.
+
+## `groupby-post-group-pagination-requires-order-by`
+
+`GroupedCollection` (what `.groupBy(...)` returns) gained `take()`, `skip()`, and `orderBy()`,
+which page the *grouped* rows when written after `.groupBy(...)` — previously `.groupBy(...)` had
+no chain of its own past `.having(...)`. Calling post-group `take()` or `skip()` without a prior
+post-group `orderBy()` is a compile error: the parameter type narrows to `never`, because a
+database may return groups in any order and "the first n groups" has no defined meaning without
+one.
+
+If your extension's own code (or its test suite) calls `.groupBy(...).take(...)` or
+`.groupBy(...).skip(...)` with no `.orderBy(...)` between them, it will fail to compile after this
+upgrade. There is no default ordering to insert automatically — add an `.orderBy(...)` naming one
+of the fields you passed to `groupBy(...)` (ascending or descending is your call; whichever
+matches what "the first n groups" should mean for that query) before the `take()` / `skip()` call.