@vantreeseba/drizzle-graphql 15.0.0 → 15.1.0

package/README.md

@@ -6,7 +6,7 @@ Site: [cubicecho.github.io/drizzle-graphql](https://cubicecho.github.io/drizzle-
 
 ## Usage
 
--   Pass your drizzle database instance and schema into builder to generate `{ schema, entities }` object
+-   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)
@@ -39,6 +39,7 @@ Site: [cubicecho.github.io/drizzle-graphql](https://cubicecho.github.io/drizzle-
 
     // Schema contains 'Users' and 'Customers' tables
     import { db } from './database'
+    import { users } from './schema'
 
     const { entities } = buildSchema(db)
 
@@ -63,7 +64,7 @@ Site: [cubicecho.github.io/drizzle-graphql](https://cubicecho.github.io/drizzle-
                     },
                     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
                     }
@@ -168,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
@@ -344,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.
@@ -463,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:
@@ -612,6 +612,7 @@ generated SDL says what a field actually holds instead of falling back to `Strin
 | `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 {
@@ -629,6 +630,8 @@ 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
@@ -656,7 +659,7 @@ mutation {
 The scalars are exported if you need them in a hand-written schema:
 
 ```Typescript
-import { GraphQLBigIntString, GraphQLDate, GraphQLDateTime, GraphQLJSON, GraphQLUUID } from '@vantreeseba/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
@@ -781,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,
 })
@@ -861,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
@@ -1090,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
 {
@@ -1256,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`
@@ -1297,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
@@ -1320,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
@@ -1339,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`
@@ -1347,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
 
@@ -1434,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
@@ -1595,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
@@ -1944,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
 
@@ -1987,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.
@@ -2142,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
 
@@ -2176,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
@@ -2347,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
@@ -2369,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
 
@@ -2432,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`.
 
@@ -2475,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
 
@@ -2548,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 |
@@ -2556,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 |

package/dist/index.cjs

@@ -1813,6 +1813,48 @@ const extractRelationJoinColumns = (relEntry, parentTable, targetTable) => {
 	};
 };
 /**
+* The junction table and its two columns for a `.through()` (many-to-many) relation:
+* `sourceCol` holds the parent's key, `targetCol` the target's. `undefined` for a relation
+* with no junction; `null` for one whose junction cannot be used here — more than one column
+* on either side, or columns that are not on the junction table.
+*/
+const extractJunctionColumns = (relEntry) => {
+	const rel = relEntry.relation ?? relEntry;
+	const junction = rel?.throughTable;
+	if (!junction) return;
+	const sourceEntries = rel.through?.source;
+	const targetEntries = rel.through?.target;
+	if (sourceEntries?.length !== 1 || targetEntries?.length !== 1) return null;
+	const junctionCols = Object.values((0, drizzle_orm.getColumns)(junction));
+	const sourceCol = unwrapRelationColumn(sourceEntries[0]);
+	const targetCol = unwrapRelationColumn(targetEntries[0]);
+	if (!sourceCol || !targetCol || !junctionCols.includes(sourceCol) || !junctionCols.includes(targetCol)) return null;
+	return {
+		table: junction,
+		sourceCol,
+		targetCol
+	};
+};
+/**
+* The relation's own declared `where` as a condition on a query that reads the target table,
+* or `undefined` when it has none. The eager path gets this from drizzle's `with:`; the batched
+* field resolver and `<relation>Aggregate` read the target table directly, so they have to add
+* it themselves or they return rows the relation hides.
+*
+* A reversed filter (inherited from the relation on the other side) is written against the
+* parent table, so it is applied as "the row's parent key belongs to a parent that passes it".
+* `parentKeyCol` is the parent's join column and `groupCol` the column in the query that holds
+* the parent key for each row — the target's foreign key, or the junction's source column.
+*/
+const relationOwnCondition = (relEntry, parentTable, targetTable, parentKeyCol, groupCol) => {
+	const rel = relEntry.relation ?? relEntry;
+	const ownWhere = relationOwnWhere(rel);
+	if (!ownWhere) return;
+	if (!isRelationFilterReversed(rel)) return (0, drizzle_orm.relationsFilterToSQL)(targetTable, ownWhere);
+	const parentFilter = (0, drizzle_orm.relationsFilterToSQL)(parentTable, ownWhere);
+	return drizzle_orm.sql`${groupCol} in (select ${parentKeyCol} from ${parentTable} where ${parentFilter})`;
+};
+/**
 * Whether a to-one relation can back a relation orderBy hop. `.through()` (junction)
 * relations are excluded — the ordering subquery only joins the direct target, never the
 * junction table. (Relation *filters* do support `.through()` — this guard is orderBy-only.)
@@ -2976,6 +3018,11 @@ const getUniqueColumnSets = (table, getTableConfig) => {
 //#endregion
 //#region src/util/builders/common/distinct.ts
 /**
+* Alias the parent key comes back under when the pass runs through a junction table. See
+* `selectDistinctKeys`' `junction` parameter.
+*/
+const DISTINCT_PARENT = "__dgql_distinct_parent";
+/**
 * Keeps the first row of each distinct combination of the requested columns, following the
 * query's own ordering, then applies `limit`/`offset` to what survives — and returns the
 * surviving rows' primary key values in that order.
@@ -2988,9 +3035,14 @@ const getUniqueColumnSets = (table, getTableConfig) => {
 * `partitionBy` prepends extra columns to the window's partition. A to-many relation field
 * uses it to pass the foreign key, which makes the pass distinct *within each parent* rather
 * than across the whole batch — the same meaning `distinct` has on a root list.
+*
+* `junction` is for a many-to-many relation: the target is joined to the junction `on` the
+* given condition, and each returned key also carries the parent it was kept for, under
+* {@link DISTINCT_PARENT}. A target row linked to several parents can be kept for one and
+* dropped for another, so a key alone cannot narrow such a batch.
 */
 const selectDistinctKeys = async (params) => {
-	const { db, table, tableName, distinct, pkNames, where, orderBy, limit, offset, partitionBy } = params;
+	const { db, table, tableName, distinct, pkNames, where, orderBy, limit, offset, partitionBy, junction } = params;
 	const cols = (0, drizzle_orm.getColumns)(table);
 	if (!pkNames.length) throw drizzleError(`Table ${tableName} has no primary key, so 'distinct' cannot be applied to it.`, { code: "DRIZZLE_INVALID_DISTINCT" });
 	const requestedCols = distinct.map((name) => cols[name]).filter(Boolean);
@@ -2999,12 +3051,17 @@ const selectDistinctKeys = async (params) => {
 	const orderEntries = orderBy ? orderByEntries(orderBy) : [];
 	const windowOrder = [...orderEntries.flatMap(([column, direction, nulls]) => orderExpressions(cols[column], direction, nulls, cols[column])), ...primaryKeyOrderExprs(table, pkNames)];
 	const rowNumber = drizzle_orm.sql`row_number() over (partition by ${drizzle_orm.sql.join(partitionCols, drizzle_orm.sql`, `)} order by ${drizzle_orm.sql.join(windowOrder, drizzle_orm.sql`, `)})`.as(DISTINCT_RN);
-	const sub = db.select({
+	const selected = db.select({
 		...cols,
+		...junction ? { [DISTINCT_PARENT]: junction.parentKey } : {},
 		[DISTINCT_RN]: rowNumber
-	}).from(table).where(where).as("__dgql_distinct");
+	}).from(table);
+	const sub = (junction ? selected.innerJoin(junction.table, junction.on) : selected).where(where).as("__dgql_distinct");
 	const outerOrder = [...orderEntries.flatMap(([column, direction, nulls]) => orderExpressions(sub[column], direction, nulls, cols[column])), ...pkNames.filter((name) => sub[name]).map((name) => (0, drizzle_orm.asc)(sub[name]))];
-	let query = db.select(Object.fromEntries(pkNames.map((name) => [name, sub[name]]))).from(sub).where((0, drizzle_orm.eq)(sub[DISTINCT_RN], 1)).orderBy(...outerOrder);
+	let query = db.select({
+		...Object.fromEntries(pkNames.map((name) => [name, sub[name]])),
+		...junction ? { [DISTINCT_PARENT]: sub[DISTINCT_PARENT] } : {}
+	}).from(sub).where((0, drizzle_orm.eq)(sub[DISTINCT_RN], 1)).orderBy(...outerOrder);
 	if (offset) query = query.offset(offset);
 	if (limit != null) query = query.limit(limit);
 	return await query;
@@ -4625,16 +4682,17 @@ const identifyRows = (field, args) => {
 * Window functions require PostgreSQL, MySQL >= 8.0, or SQLite >= 3.25.
 * Returns raw rows (NOT remapped); the caller groups + remaps them.
 */
-const batchedPaginatedRelationQuery = async (db, targetTable, foreignCol, whereCondition, orderByArg, limit, offset, pkNames, columns, orderCtx, whereArgs) => {
+const batchedPaginatedRelationQuery = async (db, targetTable, foreignCol, whereCondition, orderByArg, limit, offset, pkNames, columns, orderCtx, whereArgs, junction) => {
 	const cols = columns ?? (0, drizzle_orm.getColumns)(targetTable);
 	const orderExprs = [...orderByArg ? extractOrderBy(targetTable, orderByArg, orderCtx, whereArgs) : [], ...primaryKeyOrderExprs(targetTable, pkNames)];
 	const orderClause = orderExprs.length ? drizzle_orm.sql` order by ${drizzle_orm.sql.join(orderExprs, drizzle_orm.sql`, `)}` : drizzle_orm.sql``;
 	const RN = "__drizzle_graphql_rn";
-	const rowNumber = drizzle_orm.sql`row_number() over (partition by ${foreignCol}${orderClause})`.as(RN);
-	const sub = db.select({
+	const partitionCol = junction ? junction.sourceCol : foreignCol;
+	const rowNumber = drizzle_orm.sql`row_number() over (partition by ${partitionCol}${orderClause})`.as(RN);
+	const sub = withJunction(db.select({
 		...cols,
 		[RN]: rowNumber
-	}).from(targetTable).where(whereCondition).as("__paginated");
+	}).from(targetTable), junction, foreignCol).where(whereCondition).as("__paginated");
 	const lower = offset ?? 0;
 	const windowConds = [(0, drizzle_orm.gt)(sub[RN], lower)];
 	if (limit != null) windowConds.push((0, drizzle_orm.lte)(sub[RN], lower + limit));
@@ -4643,6 +4701,14 @@ const batchedPaginatedRelationQuery = async (db, targetTable, foreignCol, whereC
 	return rows;
 };
 /**
+* Alias the parent key is selected under when a relation goes through a junction table. The
+* key lives on the junction, not the target, so it has to be selected explicitly to group the
+* rows by parent — and a target row linked to several parents comes back once per parent.
+*/
+const PARENT_KEY = "__drizzle_graphql_parent";
+/** `from(target)`, joined to the junction table when the relation has one. */
+const withJunction = (query, junction, foreignCol) => junction ? query.innerJoin(junction.table, (0, drizzle_orm.eq)(junction.targetCol, foreignCol)) : query;
+/**
 * Creates a RelationResolverFactory that generates field-level resolvers for each relation.
 * Each resolver:
 *   1. Returns pre-fetched data if the parent resolver already included it (eager path, zero cost).
@@ -4664,6 +4730,10 @@ const createRelationResolverFactory = (db, tables, nullOrdering, filterCtx, limi
 	const joinCols = extractRelationJoinColumns(relEntry, parentTable, targetTable);
 	if (!joinCols) return;
 	const { localColPropName, foreignCol, foreignColPropName } = joinCols;
+	const junction = extractJunctionColumns(relEntry);
+	const groupCol = junction ? junction.sourceCol : foreignCol;
+	const groupKey = junction ? PARENT_KEY : foreignColPropName;
+	const ownCondition = relationOwnCondition(relEntry, parentTable, targetTable, (0, drizzle_orm.getColumns)(parentTable)[localColPropName], groupCol);
 	const defaultDeleted = relationDeletedDefault(policies?.softDelete, targetTableName, isOne && relEntry.relation?.optional === false);
 	const limitPolicy = isOne ? void 0 : limits?.(targetTableName);
 	const targetPkNames = relEntry.targetPkNames ?? [];
@@ -4741,11 +4811,12 @@ const createRelationResolverFactory = (db, tables, nullOrdering, filterCtx, limi
 				loaderKey: `${tableName}::${relationName}::${argsKey}`
 			};
 		});
+		if (junction === null) throw drizzleError(`Relation '${tableName}.${relationName}' goes through a junction with a composite key, which can only be loaded together with its parent. Leave it to eager loading (eagerLoadRelations).`, { code: "DRIZZLE_UNSUPPORTED_RELATION" });
 		return getOrCreateLoader(context, loaderKey, async (parentIds) => {
 			const executor = resolveExecutor(db, context);
 			const uniqueIds = [...new Set(parentIds)];
 			const scope = resolveScope(policies, context, filterCtx);
-			let whereCondition = withScope(scope, targetTableName, targetTable, (0, drizzle_orm.and)((0, drizzle_orm.inArray)(foreignCol, uniqueIds), whereArg ? extractFilters(targetTable, targetTableName, whereArg, relationFilterCtx(filterCtx, targetTableName)) : void 0, cursorValues ? buildCursorCondition(targetTable, cursorEntries, cursorValues, nullOrdering) : void 0), deleted ?? defaultDeleted);
+			let whereCondition = withScope(scope, targetTableName, targetTable, (0, drizzle_orm.and)((0, drizzle_orm.inArray)(groupCol, uniqueIds), ownCondition, whereArg ? extractFilters(targetTable, targetTableName, whereArg, relationFilterCtx(filterCtx, targetTableName)) : void 0, cursorValues ? buildCursorCondition(targetTable, cursorEntries, cursorValues, nullOrdering) : void 0), deleted ?? defaultDeleted);
 			if (distinct) {
 				const keys = await selectDistinctKeys({
 					db: executor,
@@ -4755,27 +4826,41 @@ const createRelationResolverFactory = (db, tables, nullOrdering, filterCtx, limi
 					pkNames: targetPkNames,
 					where: whereCondition,
 					orderBy: orderByArg,
-					partitionBy: [foreignCol]
+					partitionBy: [groupCol],
+					junction: junction ? {
+						table: junction.table,
+						on: (0, drizzle_orm.eq)(junction.targetCol, foreignCol),
+						parentKey: groupCol
+					} : void 0
 				});
 				if (!keys.length) return parentIds.map(() => isOne ? null : []);
-				whereCondition = (0, drizzle_orm.and)(whereCondition, primaryKeyRestriction(targetTable, targetPkNames, keys));
+				whereCondition = (0, drizzle_orm.and)(whereCondition, junction ? (0, drizzle_orm.or)(...keys.map((key) => (0, drizzle_orm.and)((0, drizzle_orm.eq)(groupCol, key[DISTINCT_PARENT]), primaryKeyRestriction(targetTable, targetPkNames, [key])))) : primaryKeyRestriction(targetTable, targetPkNames, keys));
 			}
+			const selection = junction ? {
+				...columns ?? (0, drizzle_orm.getColumns)(targetTable),
+				[PARENT_KEY]: groupCol
+			} : columns;
 			let rows;
-			if (limit != null || offset != null) rows = await batchedPaginatedRelationQuery(executor, targetTable, foreignCol, whereCondition, orderByArg, limit ?? null, offset ?? null, targetPkNames, columns, relationFilterCtx(filterCtx, targetTableName), whereArg);
+			if (limit != null || offset != null) rows = await batchedPaginatedRelationQuery(executor, targetTable, foreignCol, whereCondition, orderByArg, limit ?? null, offset ?? null, targetPkNames, selection, relationFilterCtx(filterCtx, targetTableName), whereArg, junction);
 			else {
-				let q = (columns ? executor.select(columns) : executor.select()).from(targetTable).where(whereCondition);
+				let q = withJunction((selection ? executor.select(selection) : executor.select()).from(targetTable), junction, foreignCol).where(whereCondition);
 				const orderExprs = cursorEntries ? cursorOrderExprs(targetTable, cursorEntries) : orderByArg ? extractOrderBy(targetTable, orderByArg, relationFilterCtx(filterCtx, targetTableName), whereArg) : [];
 				if (orderExprs.length) q = q.orderBy(...orderExprs);
 				rows = await q;
 			}
 			if (cursorEntries) attachRowCursors(rows, cursorEntries);
+			const keyOf = (row) => {
+				const key = String(row[groupKey]);
+				if (junction) delete row[PARENT_KEY];
+				return key;
+			};
 			if (isOne) {
-				const byKey = new Map(rows.map((row) => [String(row[foreignColPropName]), row]));
+				const byKey = new Map(rows.map((row) => [keyOf(row), row]));
 				remapToGraphQLArrayOutput(rows, targetTableName, targetTable);
 				return parentIds.map((id) => byKey.get(String(id)) ?? null);
 			}
 			const grouped = new Map(uniqueIds.map((id) => [String(id), []]));
-			for (const row of rows) grouped.get(String(row[foreignColPropName]))?.push(row);
+			for (const row of rows) grouped.get(keyOf(row))?.push(row);
 			remapToGraphQLArrayOutput(rows, targetTableName, targetTable);
 			return parentIds.map((id) => grouped.get(String(id)) ?? []);
 		}).load(localValue);
@@ -5110,7 +5195,7 @@ const generateSelectFields = (tables, tableName, relationMap, fromTableName, fro
 		});
 		const shell = new graphql.GraphQLObjectType({
 			name: typeName,
-			description: cacheCtx.docs.describeTable?.(tableName),
+			description: cacheCtx.docs.describeTable?.(tableName, table),
 			fields: () => ({
 				...tableFields,
 				...container.fields
@@ -5144,7 +5229,7 @@ const generateSelectFields = (tables, tableName, relationMap, fromTableName, fro
 						defaultName: resolveTypeName(targetTableName, typeNameMapper),
 						table: targetTableName
 					}),
-					description: cacheCtx.docs.describeTable?.(targetTableName),
+					description: cacheCtx.docs.describeTable?.(targetTableName, targetTable),
 					fields: () => ({
 						...targetTableFields,
 						...capturedTargetContainer.fields
@@ -5295,7 +5380,7 @@ const generateTableTypes = (tableName, tables, relationMap, withReturning, relat
 			defaultName: resolveTypeName(tableName, typeNameMapper),
 			table: tableName
 		}),
-		description: cacheCtx.docs.describeTable?.(tableName),
+		description: cacheCtx.docs.describeTable?.(tableName, tables[tableName]),
 		fields: {
 			...tableFields,
 			...relationFields
@@ -5862,6 +5947,10 @@ const createRelationAggregateFactory = (db, tables, cacheCtx, typeNameMapper, fi
 			return;
 		}
 		const { localColPropName, foreignCol } = joinCols;
+		const junction = extractJunctionColumns(relEntry);
+		if (junction === null) return;
+		const groupCol = junction ? junction.sourceCol : foreignCol;
+		const ownCondition = relationOwnCondition(relEntry, parentTable, targetTable, (0, drizzle_orm.getColumns)(parentTable)[localColPropName], groupCol);
 		const defaultDeleted = relationDeletedDefault(policies?.softDelete, targetTableName, false);
 		const targetTypeName = resolveTypeName(targetTableName, typeNameMapper);
 		const type = generateAggregateTypes(targetTable, targetTableName, targetTypeName, cacheCtx);
@@ -5892,11 +5981,12 @@ const createRelationAggregateFactory = (db, tables, cacheCtx, typeNameMapper, fi
 				const loader = getOrCreateLoader(context, loaderKey, async (parentIds) => {
 					const executor = resolveExecutor(db, context);
 					const uniqueIds = [...new Set(parentIds)];
-					const whereCondition = withScope(resolveScope(policies, context, filterCtx), targetTableName, targetTable, (0, drizzle_orm.and)((0, drizzle_orm.inArray)(foreignCol, uniqueIds), whereArg ? extractFilters(targetTable, targetTableName, whereArg, relationFilterCtx(filterCtx, targetTableName)) : void 0), deleted ?? defaultDeleted);
-					const rows = await executor.select({
-						[GROUP_KEY]: foreignCol,
+					const whereCondition = withScope(resolveScope(policies, context, filterCtx), targetTableName, targetTable, (0, drizzle_orm.and)((0, drizzle_orm.inArray)(groupCol, uniqueIds), ownCondition, whereArg ? extractFilters(targetTable, targetTableName, whereArg, relationFilterCtx(filterCtx, targetTableName)) : void 0), deleted ?? defaultDeleted);
+					const selected = executor.select({
+						[GROUP_KEY]: groupCol,
 						...request.selection
-					}).from(targetTable).where(whereCondition).groupBy(foreignCol);
+					}).from(targetTable);
+					const rows = await (junction ? selected.innerJoin(junction.table, (0, drizzle_orm.eq)(junction.targetCol, foreignCol)) : selected).where(whereCondition).groupBy(groupCol);
 					const byKey = new Map(rows.map((row) => [row[GROUP_KEY], row]));
 					return parentIds.map((id) => byKey.get(id) ?? {});
 				});