@vantreeseba/drizzle-graphql 14.0.0 → 15.1.0

package/README.md

@@ -2,17 +2,19 @@
 
 Automatically create GraphQL schema or customizable schema config fields from Drizzle ORM schema
 
+Site: [cubicecho.github.io/drizzle-graphql](https://cubicecho.github.io/drizzle-graphql/)
+
 ## Usage
 
--   Pass your drizzle database instance and schema into builder to generate `{ schema, entities }` object
--   Use `schema` if pre-built schema already satisfies all your neeeds. It's compatible witn any server that consumes `GraphQLSchema` class instance
+-   Pass your drizzle database instance into the builder to generate a `{ schema, entities }` object. The tables are read from the `relations` you gave the drizzle constructor (`drizzle({ client, relations })`), so a table missing from your relations config is not part of the generated schema
+-   Use `schema` if pre-built schema already satisfies all your needs. It's compatible with any server that consumes `GraphQLSchema` class instance
 
     Example: hosting schema using [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server)
 
     ```Typescript
     import { createServer } from 'node:http'
     import { createYoga } from 'graphql-yoga'
-    import { buildSchema } from 'drizzle-graphql'
+    import { buildSchema } from '@vantreeseba/drizzle-graphql'
 
     // db - your drizzle instance
     import { db } from './database'
@@ -20,6 +22,7 @@ Automatically create GraphQL schema or customizable schema config fields from Dr
     const { schema } = buildSchema(db)
 
     const yoga = createYoga({ schema })
+    const server = createServer(yoga)
 
     server.listen(4000, () => {
         console.info('Server is running on http://localhost:4000/graphql')
@@ -32,10 +35,11 @@ Automatically create GraphQL schema or customizable schema config fields from Dr
     import { createServer } from 'node:http'
     import { GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLSchema } from 'graphql'
     import { createYoga } from 'graphql-yoga'
-    import { buildSchema } from 'drizzle-graphql'
+    import { buildSchema } from '@vantreeseba/drizzle-graphql'
 
     // Schema contains 'Users' and 'Customers' tables
     import { db } from './database'
+    import { users } from './schema'
 
     const { entities } = buildSchema(db)
 
@@ -60,7 +64,7 @@ Automatically create GraphQL schema or customizable schema config fields from Dr
                     },
                     resolve: async (source, args, context, info) => {
                         // Your custom logic goes here...
-                        const result = await db.select(schema.Users).where()...
+                        const result = await db.select().from(users).where(/* … */)
 
                         return result
                     }
@@ -118,7 +122,7 @@ to leave that table with the default naming. The preset is exported as `singular
 so it can be wrapped:
 
 ```Typescript
-import { buildSchema, singularizeMapper } from 'drizzle-graphql'
+import { buildSchema, singularizeMapper } from '@vantreeseba/drizzle-graphql'
 
 const { schema } = buildSchema(db, {
     typeNameMapper: (table) => (table === 'auditLog' ? undefined : singularizeMapper(table)),
@@ -165,8 +169,9 @@ const { schema } = buildSchema(db, {
     turns the group-by queries off with it
 -   Turning off `insert` or `update` also drops the input type that only that mutation
     used (`Create<Type>Input` / `Update<Type>Input`)
--   Turning off all three mutation features omits the `Mutation` type entirely, the same as
-    `mutations: false`
+-   Turning off every mutation feature omits the `Mutation` type entirely, the same as
+    `mutations: false` — unless a table has `softDelete`, whose `restore` mutations are
+    generated regardless
 -   List and single queries are always generated, so `Query` is never empty
 
 ### Per-table operations
@@ -341,9 +346,7 @@ Together the two close the loop: `contextValues` decides which tenant a new row
 
 Names that match nothing throw at build time, the same as `exclude` — a renamed column fails the
 build instead of quietly ceasing to be scoped.
-> request who may see what is a job for [`graphql-shield`](https://the-guild.dev/graphql/shield)
-> or an equivalent layer above the schema, which has the request context this library
-> does not.
+
 ## Naming
 
 Type and field names are derived from the Drizzle schema keys. Three options change them.
@@ -460,7 +463,7 @@ Keyed by the **Drizzle schema key**, like `scope` and `exclude`. A function form
 accepted, for a convention applied across the schema:
 
 ```Typescript
-softDelete: (table, tableName) => ('deletedAt' in getTableColumns(table) ? 'deletedAt' : undefined)
+softDelete: (table, tableName) => ('deletedAt' in getColumns(table) ? 'deletedAt' : undefined)
 ```
 
 What a declared table gets:
@@ -606,8 +609,10 @@ generated SDL says what a field actually holds instead of falling back to `Strin
 | `json` / `jsonb` (and `mode: 'json'`)       | `JSON`       | the parsed value                     |
 | `bigint` (and `mode: 'bigint'`)             | `BigInt`     | a decimal string                     |
 | `uuid`                                      | `UUID`       | a validated UUID string              |
-| `timestamp` / `datetime`                    | `DateTime`   | an ISO-8601 string                   |
-| `date`                                      | `Date`       | a `YYYY-MM-DD` string                |
+| `timestamp` / `datetime` (either `mode`)    | `DateTime`   | an ISO-8601 string                   |
+| SQLite `integer({ mode: 'timestamp' })` / `'timestamp_ms'` | `DateTime` | an ISO-8601 string       |
+| `date` (either `mode`)                      | `Date`       | a `YYYY-MM-DD` string                |
+| `numeric` / `decimal`                       | `Decimal`    | a decimal string                     |
 
 ```graphql
 mutation {
@@ -625,15 +630,100 @@ mutation {
     `Number.MAX_SAFE_INTEGER` survive the round-trip. Integer literals are accepted on input;
     floats and non-numeric strings are rejected
 -   **`UUID`** validates the format on the way in, including inside `where` filters
+-   **`Decimal`** is a decimal string in both directions, so the precision the column declares
+    is not lost to a JS float. Non-numeric and non-finite input is rejected
+-   **`Date`** is a calendar day — no time, no offset — and is the same type in every position
+    a `date` column appears in: the object field, the create and update inputs, the
+    `DateFilter` operands, aggregate `min` / `max` and group keys. It takes and returns an
+    RFC 3339 `full-date` (`2026-09-15`) whichever `mode` the column is declared with; a
+    `mode: 'date'` column is read back from its JS `Date` as the UTC day, so no server timezone
+    shifts it. Input must name a real day: `2026-02-30`, `2026-13-45` and datetime strings like
+    `2026-09-15T10:00:00Z` are rejected. With `graphql-codegen`, map it as
+    `scalars: { Date: 'string' }`
+-   **`DateTime`** is an instant, and is likewise the same type in every position a Postgres
+    `timestamp`, MySQL `timestamp` / `datetime` or SQLite integer timestamp column appears in, with `DateTimeFilter` in
+    filters, whichever `mode` the column is declared with. It returns an ISO-8601 string in UTC.
+    MySQL stores these columns without an offset; the value is written and read as UTC
+    (`2026-09-15T10:00:00Z` is stored as `2026-09-15 10:00:00`) whatever the Node process's
+    timezone, the way drizzle itself treats them. Postgres `timestamp` without time zone is
+    treated the same way, in both modes; `timestamptz` stores the instant, and its text in
+    `mode: 'string'` (`2026-09-15 04:00:00-06`) is returned as the same instant in UTC. The
+    scalar carries milliseconds, so a `timestamp(6)` value's microseconds are truncated on read
+    and on write. A SQLite `integer({ mode: 'timestamp' })` or `integer({ mode: 'timestamp_ms' })`
+    column is `DateTime` too; it stores the instant as epoch seconds or milliseconds. Seconds
+    mode cannot hold a fraction, so it is floored (never rounded) on write —
+    `2026-09-15T10:00:00.999Z` is stored as `1789466400` and reads back as
+    `2026-09-15T10:00:00.000Z` — and filter operands on such a column are floored the same way,
+    so `eq` with the value you wrote finds the row you wrote it to
 
 The scalars are exported if you need them in a hand-written schema:
 
 ```Typescript
-import { GraphQLBigIntString, GraphQLDate, GraphQLDateTime, GraphQLJSON, GraphQLUUID } from 'drizzle-graphql'
+import { GraphQLBigIntString, GraphQLDate, GraphQLDateTime, GraphQLDecimalString, GraphQLJSON, GraphQLUUID } from '@vantreeseba/drizzle-graphql'
 ```
 
 `GraphQLBigIntString` is the `BigInt` scalar — named for what it does rather than what it is
-called in SDL, to avoid clashing with the language's own `BigInt`.
+called in SDL, to avoid clashing with the language's own `BigInt`. `GraphQLDate` is this
+library's own `Date` scalar, not `graphql-scalars`' (whose `parseValue` returns a JS `Date`).
+
+> **Upgrading — `date` columns.** A `date` column used to be typed differently depending on
+> where it appeared and which `mode` it was declared with. Both modes are now `Date` everywhere:
+>
+> | Drizzle column | position | before | now |
+> | --- | --- | --- | --- |
+> | `date(…, { mode: 'string' })` | output | `Date` | `Date` |
+> | | create / update input | `String` | `Date` |
+> | | filter | `StringFilter` | `DateFilter` |
+> | `date(…)` / `{ mode: 'date' }` (Postgres) | output, input, min/max, group keys | `DateTime` | `Date` |
+> | | filter | `DateTimeFilter` | `DateFilter` |
+> | `date(…, { mode: 'date' })` (MySQL) | output, input, min/max, group keys | `JSON` | `Date` |
+> | | filter | `JSONFilter` | `DateFilter` |
+> | `date(…, { mode: 'string' })` (MySQL) | output, input, min/max, group keys | `String` | `Date` |
+> | | filter | `StringFilter` | `DateFilter` |
+>
+> What to change:
+>
+> -   Variables typed `String` or `DateTime` for a date field become `Date`; filters on it are
+>     `DateFilter`, which has the `DateTimeFilter` operators (`eq` / `ne` / `lt` / `lte` / `gt` /
+>     `gte` / `inArray` / `notInArray` / `isNull` / `isNotNull`) and none of the string ones
+> -   Send `YYYY-MM-DD`. A datetime string such as `2026-09-15T00:00:00.000Z` used to be
+>     truncated to its date and is now rejected
+> -   A `mode: 'date'` column read `2026-09-15T00:00:00.000Z` and now reads `2026-09-15`
+> -   In `graphql-codegen`, map `scalars: { Date: 'string' }` — the value is a string in both
+>     directions
+> -   If you passed `graphql-scalars`' `GraphQLDate` as a column override, pass this library's
+>     exported `GraphQLDate` instead. They share the name `Date`, so a schema holding both
+>     fails to build with graphql's "multiple types named Date" error
+
+> **Upgrading — MySQL `timestamp` / `datetime` columns.** These used to fall through to
+> `JSON` in `mode: 'date'` and to `String` in `mode: 'string'`. All four are now `DateTime`, as
+> Postgres `timestamp` already was:
+>
+> | Drizzle column (MySQL) | position | before | now |
+> | --- | --- | --- | --- |
+> | `timestamp(…)` / `datetime(…)` (`mode: 'date'`) | output, input, min/max, group keys | `JSON` | `DateTime` |
+> | | filter | `JSONFilter` | `DateTimeFilter` |
+> | `timestamp(…)` / `datetime(…)` with `{ mode: 'string' }` | output, input, min/max, group keys | `String` | `DateTime` |
+> | | filter | `StringFilter` | `DateTimeFilter` |
+>
+> Variables for these fields become `DateTime` and their filters `DateTimeFilter`, which has no
+> `JSONFilter` / `StringFilter` operators such as `contains` or `like`. Input must be an ISO-8601
+> date-time (`2026-09-15T10:00:00Z`, or with an offset). A `mode: 'string'` column used to read
+> MySQL's own `2026-09-15 10:00:00` and now reads `2026-09-15T10:00:00.000Z`. In
+> `graphql-codegen`, map `DateTime` the way you already do for Postgres timestamps.
+
+> **Upgrading — SQLite integer timestamps.** `integer({ mode: 'timestamp' })` and
+> `integer({ mode: 'timestamp_ms' })` used to fall through to `JSON`. Both are now `DateTime`:
+>
+> | Drizzle column (SQLite) | position | before | now |
+> | --- | --- | --- | --- |
+> | `integer(…, { mode: 'timestamp' })` / `{ mode: 'timestamp_ms' }` | output, input, min/max, group keys | `JSON` | `DateTime` |
+> | | filter | `JSONFilter` | `DateTimeFilter` |
+>
+> Variables for these fields become `DateTime`, and their filters `DateTimeFilter`, which swaps
+> the JSON `path` operator for `lt` / `lte` / `gt` / `gte` / `inArray` / `notInArray`. Input must
+> be an ISO-8601 date-time; a JSON value such as a bare number is rejected. Reads are unchanged:
+> they were already ISO-8601 strings in UTC. The stored integers are unchanged too.
 
 ### Overriding a column's scalar
 
@@ -694,7 +784,7 @@ only has to handle the cases it cares about:
 ```Typescript
 const { schema } = buildSchema(db, {
     // `schema` is the Postgres schema the enum was declared in, if any; `values` is its
-    // value list. Everything but `enumName` is always present.
+    // value list. `enumName` and `schema` are undefined for an inline value list.
     enumNameMapper: ({ enumName, schema }) =>
         schema === 'reporting' ? `Reporting${enumName}Enum` : undefined,
 })
@@ -774,9 +864,40 @@ const { schema } = buildSchema(db, {
 
 -   `describeColumn` reaches every place the column appears: the object type, the create and
     update inputs, the filter input's field, `Min`/`Max` aggregates and `GroupKeys`
--   The hook receives the drizzle column itself, so a project that keeps its documentation in
-    the schema (a `.$type()` brand, a custom column property, a comment table) can read it
-    straight off
+-   `describeColumn` receives the drizzle column itself and `describeTable` the drizzle table
+    itself, so a project that keeps its documentation in the schema (a `WeakMap` keyed by
+    column/table, a custom property, a comment table) can read it straight off:
+
+    ```Typescript
+    import type { Table } from 'drizzle-orm';
+
+    const docs = new WeakMap<object, string>();
+
+    // Register docs on the *built* table and its columns. `text('email')` is only a builder:
+    // pgTable creates a new column object from it, so keying on the builder never matches.
+    const described = <T extends Table>(
+        table: T,
+        description: string,
+        columns: Partial<Record<keyof T['_']['columns'], string>> = {},
+    ): T => {
+        docs.set(table, description);
+        for (const [key, columnText] of Object.entries(columns)) {
+            docs.set((table as any)[key], columnText as string);
+        }
+        return table;
+    };
+
+    export const users = described(
+        pgTable('users', { id: integer('id').primaryKey(), email: text('email').notNull() }),
+        'A person who can sign in',
+        { email: 'Primary login address' },
+    );
+
+    buildSchema(db, {
+        describeColumn: (column) => docs.get(column),
+        describeTable: (_tableName, table) => docs.get(table),
+    });
+    ```
 -   `deprecateColumn` marks output fields and *optional* input fields. A required input field
     is skipped: GraphQL forbids deprecating one, and emitting it would make the schema invalid
 -   Filter and `orderBy` fields are never deprecated — filtering on a deprecated column is how
@@ -911,7 +1032,7 @@ no others. The set follows the column's data type, never its name:
 | column type | `eq` `ne` `inArray` `notInArray` `isNull` `isNotNull` | `lt` `lte` `gt` `gte` | pattern operators + `insensitive` |
 | --- | --- | --- | --- |
 | text / varchar | yes | yes | yes |
-| timestamp, date | yes | yes | — |
+| timestamp (`DateTimeFilter`), date (`DateFilter`) | yes | yes | — |
 | int, float, bigint, decimal | yes | yes | — |
 | uuid | yes | yes | — |
 | boolean | yes | — | — |
@@ -1003,7 +1124,8 @@ that column's `inArray` list instead of by the column's value:
 ## Filtering inside JSON documents
 
 `json` / `jsonb` columns get a `path` filter that compares the value at one path inside the
-document, alongside the whole-document `eq` / `ne` / `contains` operators:
+document, alongside the whole-document `eq` / `ne` operators and, on PostgreSQL and MySQL,
+structural `contains` (SQLite stores JSON as text and has no containment operator):
 
 ```graphql
 {
@@ -1169,9 +1291,10 @@ columns you group by.
 }
 ```
 
--   `having: { count: … }` filters on the row count; `avg` / `sum` / `min` / `max` /
-    `countNonNull` / `countDistinct` take one filter per column, over the same columns the
-    matching aggregate type exposes
+-   `having: { count: … }` filters on the row count; `avg` / `sum` / `min` / `max` take one
+    filter per numeric column (the comparison is numeric, so a `max` over a text or date
+    column has no `having` entry even though the aggregate type returns it),
+    `countNonNull` one per column, and `countDistinct` one per column `countDistinct` exposes
 -   Every entry in a `having` is ANDed together
 -   A group filter does not need to be in the selection — `having: { count: { gt: 3 } }` works
     whether or not you asked for `count`
@@ -1210,6 +1333,8 @@ can count or summarise related rows without fetching them:
 -   A parent with no related rows gets `count: 0` and `null` for every other aggregate
 -   To-one relations get no aggregate field — there is nothing to aggregate over
 -   The field is skipped if its name would collide with a column or another relation
+-   Set `features: { relationAggregates: false }` (globally or per table) to leave these
+    fields out
 
 All parents in a selection are aggregated with a single
 `SELECT <fk>, … WHERE <fk> IN (…) GROUP BY <fk>` per request, so `postsAggregate` on a list of
@@ -1233,7 +1358,8 @@ enum. Rows sharing the same combination of those columns collapse to one:
 ```
 
 -   Which row survives each group is decided by `orderBy` — the first one wins. With no
-    `orderBy`, that's the lowest primary key
+    `orderBy`, the table's [default ordering](#default-ordering) decides, and failing that the
+    lowest primary key
 -   `where` is applied **before** rows are collapsed; `limit` and `offset` are applied
     **after**, so `limit: 10` returns ten distinct rows
 -   Several columns are treated as one combined key, not as independent ones
@@ -1252,7 +1378,7 @@ or **SQLite 3.25+**), and a table with no primary key cannot use it.
 SQL gives no ordering guarantee for a query that has no `ORDER BY`, so paging through an
 unordered result can return the same row twice or skip one entirely. To keep pages stable,
 a query that returns only part of a table is ordered by its primary key when the request
-supplies no `orderBy`:
+supplies no `orderBy` and the table has no [default ordering](#default-ordering):
 
 -   list queries with `limit` and/or `offset`
 -   `<tableName>Single` queries, which are an implicit `limit 1`
@@ -1260,7 +1386,8 @@ supplies no `orderBy`:
     `orderBy` you do supply, so per-parent slices are deterministic)
 
 An explicit `orderBy` always takes precedence, composite primary keys are ordered by every
-key column, and an unpaginated list query is left unordered so no sort is paid for.
+key column, and an unpaginated list query of a table with no `defaults` entry is left
+unordered so no sort is paid for.
 
 ## Default ordering
 
@@ -1347,14 +1474,16 @@ field, and passing it back as `after` resumes strictly after that row.
     window
 -   `after` compiles to a keyset predicate built from drizzle's `and`/`or`/`gt`/`lt`
     comparisons (not SQL row-value syntax), so mixed-direction `orderBy` works
--   `NULL`s in ordered columns follow each dialect's native `ORDER BY` placement —
-    PostgreSQL sorts them largest (last in `asc`), MySQL and SQLite smallest (first in
-    `asc`) — and the predicate matches, so rows with `NULL` in an ordered column are paged
-    through, not skipped
+-   `NULL`s in ordered columns sort where the entry's `nulls: first | last` says or, without
+    it, at each dialect's native `ORDER BY` placement — PostgreSQL sorts them largest (last
+    in `asc`), MySQL and SQLite smallest (first in `asc`). The predicate matches either way,
+    so rows with `NULL` in an ordered column are paged through, not skipped, and `nulls` is
+    part of the ordering a cursor is tied to
 -   Dates and bigints round-trip losslessly through the cursor
 -   A cursor is only valid under the ordering it was issued for — reusing it with a
     different `orderBy` (or a malformed/corrupted cursor) returns a `GraphQLError`
--   `after` cannot be combined with `distinct` or with `matchFilterOrder`, and a table with
+-   `after` cannot be combined with `distinct`, with `matchFilterOrder`, or with an `orderBy`
+    that orders through a relation (`cursor` resolves to `null` there), and a table with
     no primary key cannot use cursor pagination (its `cursor` field resolves to `null`)
 -   If a table has a real column named `cursor`, the column wins and the meta field is
     skipped
@@ -1508,8 +1637,10 @@ mutation {
 }
 ```
 
--   `connect`, `disconnect` and `set` take the target's own `Filters` input, so they select
-    rows the same way a query does. A filter that matches everything is rejected rather than
+-   `connect`, `disconnect` and `set` take the target's own `Filters` input — a list of them
+    on a to-many relation, a single one that must match exactly one row on a to-one — so they
+    select rows the same way a query does. A to-one `disconnect` is just `disconnect: true`,
+    since there is only one row to detach. A filter that matches everything is rejected rather than
     attaching the whole table
 -   `set` replaces the relation wholesale — everything attached is detached first, then the
     filters attach. It runs before `create`, so a row created in the same write survives it
@@ -1857,8 +1988,8 @@ const yoga = createYoga({ schema, plugins: armor.protect().plugins });
 
 Armor's `costLimit` is its own document-shape estimate and does not read the `complexity`
 extensions above; the two compose, if you want a cheap static ceiling alongside row-count
-aware pricing. Neither one bounds an individual `limit` argument, so a single unbounded list
-query is still a full table scan — cap `limit` yourself if that matters.
+aware pricing. Neither one bounds an individual `limit` argument — a list query with no
+`limit` is still a full table scan unless you set a [`limits`](#bounding-page-size) policy.
 
 ## Authorization
 
@@ -1900,21 +2031,17 @@ request context actually lives.
     or through your own resolver wrapper, and let the ability answer the questions.
 
 What neither can do is **narrow** a query. They permit or deny a field; they do not append
-`WHERE user_id = …` to the SQL a generated resolver runs, and a permitted `users` query still
-returns every tenant's rows. Until row scoping is a first-class option here, the ways to get
-it are, in increasing order of effort:
-
--   supply the tenant predicate as an ordinary `where` argument from a trusted gateway, and
-    deny the raw generated fields to everyone else;
--   build the schema by hand from `entities`, exposing only the generated resolvers you have
-    wrapped;
--   put the scoped tables behind database row-level security and give the driver the
-    request's identity, so the narrowing happens below Drizzle entirely.
+`WHERE org_id = …` to the SQL a generated resolver runs, so a permitted `posts` query still
+returns every tenant's rows. That is what [`scope`](#row-scoping-and-multi-tenancy) is for: a
+per-table predicate built from the request context and ANDed onto every read and write of
+that table, nested relation fields included. Pair it with
+[`contextValues`](#columns-the-server-owns) so new rows are stamped with the caller's tenant.
+The usual split is shield (or CASL) to decide who may reach a field, and `scope` to decide
+which rows they see through it.
 
 None of this removes anything from introspection either — `deny` hides the data, not the
-shape. If the schema must not so much as mention a table, keep that table out of the Drizzle
-instance you pass to `buildSchema` (a second instance over a narrowed schema object is
-cheap).
+shape. If the schema must not so much as mention a table or column, leave it out with
+[`exclude`](#excluding-tables-and-columns).
 
 Nor is it a row bound: a complexity ceiling prices the `limit` a client asks for, it does not
 cap it. Use [`limits`](#bounding-page-size) for that.
@@ -2055,6 +2182,9 @@ are untouched.
 -   A document that mixes in mutation fields this build did not generate is left alone: their
     completion cannot be tracked, so no transaction is opened
 -   It never nests — an executor supplied on the context wins, as below
+-   A single mutation field can still run in a transaction of its own when it carries a
+    nested write or its table has an `onWrite` hook — those open one regardless of this
+    setting
 
 ### Supplying your own executor
 
@@ -2062,7 +2192,7 @@ To control the boundary yourself, open a transaction and put it on the GraphQL c
 the exported `drizzleExecutorKey`:
 
 ```Typescript
-import { buildSchema, drizzleExecutorKey } from 'drizzle-graphql'
+import { buildSchema, drizzleExecutorKey } from '@vantreeseba/drizzle-graphql'
 
 const { schema } = buildSchema(db)
 
@@ -2089,17 +2219,6 @@ example a pooled connection bound to a tenant, or a logging proxy around `db`. B
 key is created with `Symbol.for`, the ESM and CJS builds of this package agree on it when
 both end up loaded in one process.
 
-Or let the library open one per request: `transactions: 'auto'` wraps a document that fires
-more than one generated mutation in a single transaction, committed when the last one
-completes and rolled back if any of them fails.
-
-```Typescript
-buildSchema(db, { transactions: 'auto' })
-```
-
-A document with one mutation, or one that selects a mutation field this build did not
-generate, still runs unwrapped — there is nothing to keep atomic.
-
 ## Write hooks
 
 `onWrite` runs a hook **inside the mutation's transaction**, so its writes commit or roll back
@@ -2260,12 +2379,12 @@ Generated schemas resolve nested relations without N+1 query explosions:
     relation in a single round-trip using Drizzle's relational query builder
     (`with:`), including nested relations and per-relation `where` / `orderBy` /
     `limit` / `offset` arguments.
--   **Mutations (PostgreSQL & SQLite)** — after an insert or update, if the selection set
+-   **Mutations (PostgreSQL & SQLite)** — after an insert, upsert, update or `updateMany`, if the selection set
     includes relation fields, the affected rows are re-fetched by primary key through one
     relational query so their relations are eagerly loaded (single- and composite-column
-    primary keys are supported). `delete` mutations keep using the request-scoped batch
-    loader, since the rows no longer exist to re-fetch. MySQL mutations return only a
-    success flag (no row payload), so this step does not apply there.
+    primary keys are supported). `delete` and `restore` mutations keep using the
+    request-scoped batch loader. MySQL mutations return only a success flag (no row
+    payload), so this step does not apply there.
 -   **Custom schemas** — each relation field also has a standalone resolver, exported as
     `entities.fieldResolvers[TableName][relationName]`. When you wire generated types
     into your own schema and your root resolver does **not** pre-fetch relations, these
@@ -2282,9 +2401,8 @@ Generated schemas resolve nested relations without N+1 query explosions:
 
 > [!IMPORTANT]
 > Per-parent paginated relations (a to-many relation field with `limit` or `offset`)
-> rely on SQL window functions. These require **PostgreSQL**, **MySQL 8.0+**, or
-> **SQLite 3.25+**. Relations without pagination, and all other query/mutation paths,
-> have no such requirement.
+> and the `distinct` argument rely on SQL window functions. These require **PostgreSQL**,
+> **MySQL 8.0+**, or **SQLite 3.25+**. Everything else has no such requirement.
 
 ### Relation nullability
 
@@ -2345,7 +2463,9 @@ const finalSchema = addResolversToSchema({
     excludes that relation from `with:` (and from the mutation eager re-fetch).
 
 Opting a relation out does **not** remove its field — it keeps resolving lazily via the
-request-scoped batch loader, so the field still works even before you override it. Table
+request-scoped batch loader, so the field still works even before you override it. A
+many-to-many (`.through()`) relation whose junction has a composite key cannot be loaded
+lazily (`DRIZZLE_UNSUPPORTED_RELATION`); leave it eager-loaded. Table
 and relation names are the Drizzle schema keys (e.g. `Users`, `posts`), matching the keys
 of `entities.fieldResolvers`.
 
@@ -2388,9 +2508,10 @@ into its nested entry, and leaves `<relation>Aggregate` selections out — they
 `resolveSelection` additionally accepts `single`, `orderBy`, `limit`, `offset` and `after`,
 and returns the rows already remapped to their GraphQL transport forms.
 
-Both take a `typeNameMapper` option. If the schema was built with one, pass the same
-function here — the translation matches selections against GraphQL type names, so a build
-that renames its types has to say so.
+Both take the naming options the build used — `typeNameMapper`, `derivedTypeNameMapper`,
+`typeNamePrefix` and `typeNameSuffix`. The translation matches selections against the
+published GraphQL type names, so a build that renames its types has to say so here too. If
+the build used `typeNameMapper: 'singularize'`, pass the exported `singularizeMapper`.
 
 ## Identifying generated fields
 
@@ -2461,7 +2582,7 @@ that explains it, where there is one.
 | `mutations` | `true` | `false` omits the `Mutation` type entirely |
 | `features` | see [Choosing what gets generated](#choosing-what-gets-generated) | which operations are generated, per operation |
 | `exclude` | none | [tables and columns left out](#excluding-tables-and-columns) of the generated schema entirely |
-| `relationsDepthLimit` | unlimited | how deep relation fields are generated; `0` gives a flat, columns-only schema |
+| `relationsDepthLimit` | unlimited | `0` generates no relation fields (a flat, columns-only schema); any other value currently behaves like the default |
 | `prefixes` / `suffixes` / `typeNameMapper` | see [Naming](#naming) | operation and type names |
 | `typeNamePrefix` / `typeNameSuffix` / `derivedTypeNameMapper` | none | [names of the derived types](#renaming-the-derived-types) — filters, inputs, aggregates, shared inputs |
 | `scalars` / `mapColumnType` | built-in detection | [override a column's GraphQL type](#overriding-a-columns-scalar), by name or by rule |
@@ -2469,7 +2590,7 @@ that explains it, where there is one.
 | `enumValueNameMapper` | the stored value | [names the enum's values](#enum-value-names); `'constant'` for CONSTANT_CASE |
 | `describeColumn` / `describeTable` / `describeRelation` | none | [GraphQL descriptions](#documenting-the-schema) |
 | `deprecateColumn` | none | `@deprecated` on a column's output and optional input fields |
-| `conflictDoNothing` | `false` | PostgreSQL only — `ON CONFLICT DO NOTHING` on inserts, which makes `create<Table>Single` nullable |
+| `conflictDoNothing` | `false` | **Deprecated** — use [`onConflict: { action: NOTHING }`](#upsert) per request. PostgreSQL and SQLite: `ON CONFLICT DO NOTHING` on every insert, which makes `create<Table>Single` nullable; ignored on MySQL |
 | `complexity` | on | [cost hints](#query-cost) in field extensions; `false` turns them off |
 | `transactions` | `'none'` | `'auto'` wraps a multi-mutation request in one [transaction](#transactions) |
 | `limits` | unbounded | [default and maximum page size](#bounding-page-size), globally or per table |