@vantreeseba/drizzle-graphql 15.1.6 → 16.0.0

package/README.md

@@ -154,7 +154,7 @@ const { schema } = buildSchema(db, {
         nestedWrites: true,       // relation fields on the create/update inputs (off by default)
         fieldUpdateOperations: true, // increment/push operations on the update input (off by default)
         countMutations: true,     // update<Table>Count / delete<Table>Count mutations (off by default)
-        requireWhere: true,       // make `where` non-null on plural update/delete (off by default)
+        requireWhere: true,       // require a `where` on plural update/delete/updateMany (off by default)
         uniqueKeyFilters: true,   // a `where` field per compound unique constraint (off by default)
     },
 })
@@ -238,7 +238,7 @@ An excluded **column** disappears from every surface at once:
 | `<Type>OrderBy` | field removed |
 | `<Type>MinAggregate` / `<Type>MaxAggregate` / … | field removed |
 | `<Type>DistinctColumn` / `<Type>GroupByColumn` | value removed |
-| `<Type>ConflictColumn` (upsert targets) | value removed |
+| `<Type>ConflictTarget` / `<Type>UpdateColumn` (upsert `onConflict`) | value removed |
 
 Two details worth stating plainly:
 
@@ -313,7 +313,9 @@ Two things it deliberately does not do:
 
 A relation filter or an ordering through a relation sees exactly the rows the relation field
 would return. Through a `.through()` relation, the junction table's own `scope` and soft delete
-apply as well. A scope that returns a filter object is the server's own predicate, so the
+apply as well — to the relation field, its `<relation>Aggregate` and a relation filter alike,
+so a link row the caller cannot read links nothing on any of them (see
+[junction rows](#junction-rows)). A scope that returns a filter object is the server's own predicate, so the
 relations it reaches through are read without their targets' scopes.
 
 Returning `undefined` means *no restriction for this context*, so one hook can let an
@@ -566,6 +568,27 @@ field shows. They take no `deleted` argument of their own.
 `scope` changes reads only. A nested `connect` / `disconnect` / `set` still refuses to attach a
 marked row under either setting, and the table's own writes are unaffected.
 
+#### Junction rows
+
+A `.through()` relation links only through the junction rows the junction table's own `scope`
+and soft delete keep, on every path that reads it: the relation field (eager or batched,
+paginated or `distinct`), `<relation>Aggregate`, and a relation filter. A marked junction row is
+a removed link, so the junction is always read at `EXCLUDE`:
+
+-   The relation's `deleted` argument is about the **target** rows. `tags(deleted: INCLUDE)`
+    brings back marked tags that are still linked, never a tag whose link was marked.
+-   The junction's own `softDelete.scope` only decides what the junction table's own fields
+    return. `'root'` keeps a retired row rendering where a relation points *at* it; a relation
+    passes *through* a junction row and never renders it, so there is nothing for `'root'` to
+    keep, and a marked link stays hidden under either setting.
+
+Drizzle's `with:` joins the junction itself and offers no way to add a condition to it, so a
+relation whose junction has a `scope` or soft delete is loaded by its field resolver's batch
+loader rather than with its parent — still one query per relation per request, not one per
+parent. A junction joined on more than one column per side cannot be loaded that way, so
+selecting such a relation while its junction has a policy fails with
+`DRIZZLE_UNSUPPORTED_RELATION` instead of returning links the policy hides.
+
 ### Purging a row
 
 Soft delete and purge are not alternatives — emptying the trash, reclaiming a unique key and
@@ -681,6 +704,36 @@ mutation {
     `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
 
+Some columns map to built-in GraphQL types rather than a custom scalar:
+
+| Drizzle column | GraphQL type | Transported as |
+| --- | --- | --- |
+| SQLite `integer()` (number mode) | `Float` | a JS number, exact up to 2^53 |
+| Postgres `bytea`, SQLite `blob({ mode: 'buffer' })` | `[Int!]` | the bytes, each 0–255 |
+| Postgres `point` / `line` (tuple mode), PostGIS `geometry` (tuple mode), `vector`, `halfvec` | `[Float!]` | the tuple or vector |
+| Postgres `point({ mode: 'xy' })`, `line({ mode: 'abc' })` | `JSON` | the object, `{ x, y }` / `{ a, b, c }` |
+
+-   **SQLite `integer()`** holds any 64-bit integer, a rowid primary key included, so it is a
+    `Float`: GraphQL's `Int` is 32-bit and cannot serialize anything past 2^31. Drizzle reads
+    the column as a JS number, so values are exact up to `Number.MAX_SAFE_INTEGER`; declare it
+    `blob({ mode: 'bigint' })` (a `BigInt`) for more. Its `'boolean'` and `'timestamp'` modes
+    keep `Boolean` and `DateTime`
+-   A **tuple** must have its type's length — 2 for a point, 3 for a line — or the write is
+    rejected
+-   An **array column** (`bigint().array()`, `timestamp().array()`, …) is a list of its element
+    type, and each element is converted as a single value would be, in writes and in the `has` /
+    `hasSome` / `hasEvery` operands alike
+
+> **Upgrading — SQLite `integer()` columns.** A SQLite `integer()` column in number mode (the
+> default) used to be `Int`, and reading a value past 2^31 failed with "Int cannot represent
+> non 32-bit signed integer value". It is now `Float` in every position: the object field, the
+> create / update inputs, primary-key and unique-key arguments, `FloatFilter` operands, aggregate
+> `min` / `max` and group keys, and `FloatFieldUpdate`. Variables typed `Int` for these fields
+> become `Float` (an `Int` variable is a validation error in a `Float` position); literals and
+> the values themselves are unchanged. `integer({ mode: 'boolean' })` and the timestamp modes are
+> not affected. A SQLite `blob({ mode: 'buffer' })` column, which used to be `JSON` and could
+> not be written, is now `[Int!]`.
+
 The scalars are exported if you need them in a hand-written schema:
 
 ```Typescript
@@ -797,11 +850,16 @@ type Posts {
 
 -   One type, one filter input (`StatusEnumFilter`), so a client variable typed `StatusEnum!`
     is passable to either table
--   The declared name is PascalCased and suffixed: `user_status` → `UserStatusEnum`
+-   The declared name is PascalCased and suffixed: `user_status` → `UserStatusEnum`. A name
+    that would start with a digit gets a leading underscore: `2fa_mode` → `_2faModeEnum`
 -   A column that lists its values inline (`text('tier', { enum: ['free', 'paid'] })`) has no
     declared name to share, so it keeps a per-column type — `UsersTierEnum`
 -   Two different enums that would land on the same GraphQL name (`status` in two Postgres
     schemas) fail the build rather than silently sharing a type
+-   Ordering by an enum column, its `min` / `max`, and cursor pages over it follow the
+    database's own rule. PostgreSQL and MySQL sort an enum by declaration order (`active` before
+    `archived` because it is declared first). SQLite has no enum type — the column is `text`
+    with the values checked by Drizzle — so there it sorts alphabetically
 
 `enumNameMapper` overrides the name. Returning `undefined` keeps the default, so a mapper
 only has to handle the cases it cares about:
@@ -831,8 +889,10 @@ lists is the build-time error above.
 ### Enum value names
 
 A value's GraphQL name is the stored value itself, or `Option<index>` when the stored value
-is not a usable GraphQL name. `enumValueNameMapper` renames the values — most often to follow
-GraphQL's SCREAMING_CASE convention while the database keeps its lowercase values:
+is not a usable GraphQL name — one with a character outside `[_a-zA-Z0-9]` (`hot-fix`), one
+that starts with a digit (`2xl`), or `true` / `false` / `null`. `enumValueNameMapper` renames
+the values — most often to follow GraphQL's SCREAMING_CASE convention while the database keeps
+its lowercase values:
 
 ```Typescript
 export const Runs = pgTable('runs', {
@@ -1052,6 +1112,27 @@ by hand. Under `insensitive` the operand stays a literal and stays a bound param
         from the numeric, uuid, boolean, timestamp and enum filters (see
         [Which operators a column gets](#which-operators-a-column-gets))
 
+**On MySQL, plain comparisons may already ignore case.** MySQL compares strings under the
+column's collation, and its default (`utf8mb4_0900_ai_ci`, like every `*_ai_ci` collation) is
+case- **and** accent-insensitive. So without `insensitive`, `eq: "dan"` matches `Dan` and `dän`
+there, and the same holds for `ne`, the ordering comparisons, `inArray`, `orderBy`, `min` /
+`max`, `distinct`, `groupBy` and the `like` / `startsWith` / `endsWith` / `contains` operators.
+PostgreSQL compares exactly. That is the database's configured behaviour, not something this
+library adds: give a column a binary or `*_as_cs` collation (`varchar(…) COLLATE utf8mb4_bin`)
+where it has to compare exactly.
+
+### Case sensitivity of the pattern operators on SQLite
+
+`like` / `notLike` and the safe `startsWith` / `endsWith` / `contains` are case-sensitive, as
+they are on PostgreSQL: `contains: "App"` matches `Apple` and not `apple`. SQLite's own `LIKE`
+folds ASCII case, so on SQLite they compile to `GLOB` instead, with `%` / `_` translated to its
+`*` / `?` and every other wildcard in the operand matched literally. The `i`-prefixed operators
+and `insensitive: true` fold case on SQLite as everywhere else.
+
+> **Upgrading — SQLite.** These operators used to compile to `LIKE` on SQLite and so matched
+> case-insensitively. Queries that relied on that should use the `i`-prefixed operator or
+> `insensitive: true`.
+
 ## Which operators a column gets
 
 A filter input carries the operators that can express a question about that column type, and
@@ -1068,7 +1149,8 @@ no others. The set follows the column's data type, never its name:
 
 The pattern operators are `like` / `notLike` / `ilike` / `notIlike`, the safe
 `startsWith` / `endsWith` / `contains` and their `i`-prefixed forms, plus the `insensitive`
-flag that modifies them.
+flag that modifies them. MySQL and SQLite have no `ILIKE`, so there `ilike` / `notIlike`
+compile to `lower(column) LIKE lower(pattern)`, the same form `insensitive` uses.
 
 An operand of `null` leaves its operator out, as though it had not been sent. `false` is an
 ordinary value: `active: { eq: false }` matches the rows that are false, `ne: false` the rows
@@ -1211,6 +1293,23 @@ each one — Postgres errors outright on a bad `::numeric`, MySQL quietly casts
 string to `0`, and SQLite's cross-type ordering would otherwise sort every string above every
 number.
 
+SQLite has no boolean type, and its `json_extract` hands a JSON `true` / `false` back as `1` /
+`0`, so its path reads check `json_type` as well: `eq: true` matches only a JSON `true`, never
+the number `1`, a number operand never matches a boolean, and a text read sees `"true"` /
+`"false"`, as PostgreSQL's does.
+
+**Whole-document `eq` / `ne`** compare documents, not their text. Object key order and
+whitespace do not matter; array order does, and so does the difference between `1` and `true`.
+PostgreSQL compares as `jsonb` (so a plain `json` column, which has no `=` of its own, works
+too), MySQL against `CAST(? AS JSON)`, and SQLite by matching the two documents' nodes both ways.
+Like `=` / `<>` on any column, neither matches a row whose column is SQL `NULL`.
+
+**JSON columns cannot be ordered.** A JSON document has no meaningful order — PostgreSQL's
+`json` has none at all, and MySQL's JSON ordering is not one a cursor can resume from — so
+JSON columns are left out of `<Type>OrderBy` (and so out of cursor pagination and every relation
+`orderBy`) and out of `<Type>DistinctColumn`, and naming one in `defaults.<table>.orderBy` fails
+the build. Order by a generated column or a path you extract yourself instead.
+
 Note that `contains` means different things at the two levels, because a path names a scalar:
 on the column it is structural JSON containment (Postgres `@>` / MySQL `JSON_CONTAINS`),
 inside a `path` filter it is substring matching on the extracted value.
@@ -1252,13 +1351,19 @@ following the same naming rules as the other generated queries:
 ```
 
 -   `count` — number of matching rows (`Int!`)
--   `avg` / `sum` — one nullable `Float` field per numeric column
+-   `avg` / `sum` — one nullable `Float` field per numeric column. On MySQL `avg` is computed
+    as a `DOUBLE`, since MySQL's own `AVG` over an integer column is a `DECIMAL` rounded to four
+    places
 -   `min` / `max` — one field per orderable column (numbers, strings, enums, dates, bigints),
-    typed exactly like that column is in the table's own type
+    typed exactly like that column is in the table's own type. PostgreSQL `uuid`, `macaddr`,
+    `macaddr8` and `bit` columns are left out, because PostgreSQL has no `min` / `max` for them,
+    and so is a SQLite `blob({ mode: 'bigint' })` column, whose bytes compare as text (`9` above
+    `10`)
 -   `countNonNull` — `Int!` per column: how many matching rows have a non-null value there.
     Every column qualifies, since `count(col)` is valid whatever the type
 -   `countDistinct` — `Int!` per column: how many distinct non-null values there are. Limited to
-    the same columns as `min` / `max`, because counting distinct values needs an equality operator
+    the columns with an equality operator: the `min` / `max` columns plus the ones listed above
+    that compare but have no `min` / `max`
 
 Columns that have no meaningful ordering — booleans, arrays, JSON, buffers, and geometry —
 are left out of these types, and the `avg` / `sum` / `min` / `max` fields themselves are
@@ -1299,7 +1404,7 @@ columns you group by.
 ```
 
 -   `groupBy` is required and takes one or more values of the table's `<Type>GroupByColumn`
-    enum. It holds the orderable columns plus booleans — anything the database can group on.
+    enum. It holds the `countDistinct` columns plus booleans — anything the database can group on.
     An empty list is an error, and repeated columns are ignored
 -   `group` is a `<Type>GroupKeys!` object with one nullable field per groupable column, typed
     like the table's own column. Columns the query did not group by come back as `null`, which
@@ -1328,6 +1433,9 @@ columns you group by.
     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
+-   The operand is a `Float` whatever the aggregate's own type, so `count: { gt: 1.5 }` works:
+    on PostgreSQL, where an integer aggregate would otherwise give the parameter its integer
+    type, the aggregate is compared as `numeric`
 -   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`
@@ -1406,6 +1514,8 @@ enum. Rows sharing the same combination of those columns collapse to one:
     distinct value **per parent** — the window is partitioned by the foreign key as well as
     the requested columns
 -   `distinct` is not on single queries — those return one row either way
+-   JSON columns are not in `<Type>DistinctColumn` (see
+    [Filtering inside JSON documents](#filtering-inside-json-documents))
 
 It runs as an extra `row_number() over (partition by …)` query that picks the surviving
 rows' primary keys, after which the main query is narrowed to them — so it needs the same
@@ -1422,12 +1532,25 @@ 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`
 -   to-many relation fields with `limit` and/or `offset` (as a tiebreak appended to any
-    `orderBy` you do supply, so per-parent slices are deterministic)
+    `orderBy` you do supply or [default ordering](#default-ordering) the target has — and under
+    `orderBy: {}` too — so per-parent slices are deterministic and the eager and lazy paths
+    return the same slice)
 
 An explicit `orderBy` always takes precedence, composite primary keys are ordered by every
 key column, and an unpaginated list query of a table with no `defaults` entry is left
 unordered so no sort is paid for.
 
+`offset` works without `limit` on every dialect. SQLite and MySQL only accept `OFFSET` after a
+`LIMIT`, so there an offset-only page is sent with a limit meaning "no limit" (`-1` on SQLite,
+2^53 - 1 on MySQL).
+
+`<Type>OrderBy` offers every column that has a meaningful order. JSON columns (see
+[Filtering inside JSON documents](#filtering-inside-json-documents)) and SQLite
+`blob({ mode: 'bigint' })` columns, whose bytes sort as text, are left out. A table left with
+nothing to order by — no such column, and no to-one relation to a table that has one — gets no
+`<Type>OrderBy` and no `orderBy` argument, on its lists or on relation fields pointing at it, and
+likewise no `<Type>DistinctColumn` or `distinct` argument when no column qualifies for that.
+
 ## Default ordering
 
 A table usually has one ordering that is right nearly every time it is read — newest first,
@@ -1615,7 +1738,10 @@ mutation {
     exclusion constraint matching" error
 -   `target` can be a partial unique index — the `WHERE deleted_at IS NULL` companion of
     [soft delete](#soft-delete), say. Its predicate goes into `ON CONFLICT (…) WHERE …`, so a
-    conflict is detected only against the rows the index covers
+    conflict is detected only against the rows the index covers. On SQLite the predicate is
+    written with its values inline (SQLite matches it to the index as written, so
+    `status = 'active'` works), and `action: NOTHING` on such a target is spelled as an update
+    that matches no row, since SQLite cannot parse the predicate before `DO NOTHING`
 -   `contextValues` columns are never overwritten on conflict — see
     [columns the server owns](#columns-the-server-owns)
 -   `action: NOTHING` inserts nothing and returns nothing for the conflicting row. An `UPDATE`
@@ -1655,7 +1781,9 @@ Dialect differences:
     no predicate, so `<Type>OnConflict` there has only `action` and `update`. Because the
     conflict can be on any unique key, the default overwrite leaves out the primary key as well
     — copying a new row's key over the conflicting row's would move it. `action: NOTHING`
-    becomes `INSERT IGNORE`, and the mutations return `MutationReturn` like every other MySQL
+    becomes a no-op `ON DUPLICATE KEY UPDATE <key> = <key>` rather than `INSERT IGNORE`, so
+    only a duplicate key is skipped: a value too long for its column or a foreign-key violation
+    still fails the write. The mutations return `MutationReturn` like every other MySQL
     mutation
 
 The build-wide `conflictDoNothing` option is deprecated in favour of this: it applies to every
@@ -1728,6 +1856,11 @@ mutation {
 -   When the parent write produces no row — an update whose `where` matched nothing, an
     insert or upsert a conflict turned into a no-op — whatever a parent-side `create` inserted
     for it is rolled back too, so no orphan is left. In a batch only that entry is undone
+-   An upsert whose conflict branch does not write the parent's join column (an
+    `onConflict.update` that leaves it out) would update the existing row without attaching
+    what a parent-side `create` or `connect` produced. That fails with
+    `DRIZZLE_NESTED_WRITE_INVALID` and rolls the write back; list the column in
+    `onConflict.update`, or leave `update` unset so every supplied column is written
 -   The returned rows reflect the nested write: on a self-referencing relation
     (`reports: { connect: … }` on the row itself), where a child-side statement rewrites the
     parent row, the parent rows are read back after it
@@ -1740,7 +1873,9 @@ A relation declared with a `where` (`publishedPosts: r.many.posts({ …, where:
 is written through the same way it is read: only the rows it shows.
 
 -   `disconnect`, `set`, and the detaching a to-one attach does, reach only rows that satisfy
-    the `where` — `publishedPosts: { set: [] }` leaves the drafts attached
+    the `where` — `publishedPosts: { set: [] }` leaves the drafts attached. On a to-one whose
+    key is on the parent, `disconnect` leaves a key that points at a row the `where` hides,
+    and a `connect` that would replace such a key fails with `DRIZZLE_NESTED_WRITE_INVALID`
 -   `connect` and `set` attach only rows that satisfy it, so the relation shows what was
     attached. A to-one `connect` must match exactly one such row
 -   There is no `create`: the inserted row is attached whether or not it satisfies the
@@ -1749,7 +1884,9 @@ is written through the same way it is read: only the rows it shows.
 -   A many-to-many `set` unlinks only the links to rows the `where` shows
 -   A relation that inherits its `where` from the other side (declared without `from` / `to`)
     filters the parent rather than the target. Writing through it on a parent row it is
-    hidden for fails with `DRIZZLE_NESTED_WRITE_INVALID`
+    hidden for fails with `DRIZZLE_NESTED_WRITE_INVALID`. When the key is on the parent
+    (`connect`, `create` or `disconnect` on a to-one), the row is judged as the write leaves
+    it, so a write that also makes the row visible goes through
 
 ### The target table's own rules
 
@@ -1945,7 +2082,9 @@ deliberate rather than accidental:
 The plural mutations still accept a missing `where` (a full-table write) by default. To rule
 that out at the type level, `features: { requireWhere: true }` makes `where` non-null on
 `update<Table>` / `delete<Table>` and rejects a `where` with no filters, exactly like the
-Single variants. It defaults to `false` for backwards compatibility.
+Single variants. It also covers `update<Table>Many`: an entry without a `where`, or with one
+that has no filters, rejects the whole batch with `DRIZZLE_WHERE_REQUIRED` before any entry
+runs. It defaults to `false` for backwards compatibility.
 
 ## Bounding page size
 
@@ -2014,8 +2153,8 @@ So `users(limit: 20) { id posts(limit: 5) { id } }` costs `20 * (1 + 5 * 1)` = 1
 same query without limits costs `10 * (1 + 10 * 1)` = 110.
 
 A [limit policy](#bounding-page-size) feeds into the hint: a field with no `limit` is priced at
-its `defaultLimit` rather than `defaultListSize`, and nothing is priced above `maxLimit`, so the
-cost matches the rows the query can actually pull.
+its `defaultLimit` (or at `maxLimit` when the policy sets only that) rather than `defaultListSize`,
+and nothing is priced above `maxLimit`, so the cost matches the rows the query can actually pull.
 
 The hints do nothing until you install a complexity rule, so they are generated by default:
 
@@ -2274,7 +2413,13 @@ are untouched.
     does this) — it keys the per-request transaction state
 -   `timeoutMs` (default `30000`) rolls back an abandoned transaction, e.g. when the host
     server stopped calling resolvers because of a non-null completion error, instead of
-    leaking the connection
+    leaking the connection. It must be a positive integer up to `2147483647` (the longest
+    delay `setTimeout` honours), or `Infinity` to turn the timer off; `buildSchema` throws for
+    anything else. With the timer off an abandoned transaction keeps its connection, so prefer
+    a finite value. Fields after a timeout fail with `DRIZZLE_TRANSACTION_ABORTED`, naming the
+    timeout as the cause
+-   A root field whose arguments fail to coerce is answered with an error without its resolver
+    running, so it is not waited for: the transaction commits once the other fields complete
 -   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
@@ -2412,6 +2557,10 @@ The payload:
     not have to know which.
 -   **Throwing rolls the mutation back.** A hook that can only log is what a logging plugin
     already does.
+-   **SQLite needs an asynchronous driver** (libsql, D1). A synchronous one (better-sqlite3,
+    `node:sqlite`) commits before an awaited hook runs, so a throw could not roll anything
+    back; `buildSchema` throws for `onWrite` on one, as it does for `nestedWrites` and
+    `transactions: 'auto'`.
 -   **`rows` is empty** at the `before` position, and on MySQL, whose mutations return no rows.
     The `before` position and `args` still work there.
 -   With `nestedWrites`, the hooks of **every table a nested write reaches** fire too —
@@ -2569,7 +2718,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. A
+request-scoped batch loader, so the field still works even before you override it — in a
+mutation payload as well, where the write returns the join column the relation correlates on
+even though the selection never named 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