@rebasepro/server-postgres 0.11.1-canary.gfd39654 → 0.12.0

package/src/utils/drizzle-conditions.ts

@@ -1,15 +1,109 @@
-import { and, eq, or, sql, SQL, ilike, inArray } from "drizzle-orm";
+import { and, eq, or, sql, SQL, ilike, inArray, getTableColumns } from "drizzle-orm";
 import { AnyPgColumn, PgTable, PgVarchar, PgText, PgChar } from "drizzle-orm/pg-core";
 import {
-    FilterValues, WhereFilterOp, JoinStep, LogicalCondition, FilterCondition,
-    ResolvedRelation, ResolvedBelongsTo, ResolvedHasOne, ResolvedHasMany
+    CollectionConfig, FilterValues, WhereFilterOp, JoinStep, LogicalCondition, FilterCondition,
+    ResolvedRelation, ResolvedBelongsTo, ResolvedHasOne, ResolvedHasMany,
+    ResolvedForeignKeyOnTarget, ResolvedManyToMany, hasForeignKeyOnTarget, isManyToMany
 } from "@rebasepro/types";
-import { getColumnName, normalizeToEntityRelation, resolveCollectionRelations } from "@rebasepro/common";
+import {
+    getColumnName, getTableName, normalizeToEntityRelation, resolveCollectionRelations
+} from "@rebasepro/common";
+import { generateForeignKeyName } from "@rebasepro/utils";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { ConditionBuilderStatic } from "../interfaces";
-import { logger } from "@rebasepro/server";
+import { ApiError, logger } from "@rebasepro/server";
 import { getColumnMeta } from "../services/collection-helpers";
 
+/**
+ * What to do with a filter field that resolves to no column at all.
+ *
+ *  - `"error"` (default) — reject the request. A filter that cannot be
+ *    compiled is *dropped*, and dropping a condition can only ever widen the
+ *    result set. On a data plane where row-level security is the last line of
+ *    defence, a typo'd or renamed filter key therefore runs the query without
+ *    that condition and returns everything RLS happens to allow.
+ *  - `"warn"` — the historical behaviour: log and silently drop the condition.
+ *    Only for a deployment that knowingly sends filter keys the table does not
+ *    have and has satisfied itself that widening is safe there.
+ */
+export type UnknownFilterFieldsMode = "error" | "warn";
+
+/**
+ * Process-wide default, set once when the driver is constructed.
+ *
+ * The condition builder is a set of *static* methods reached from a dozen
+ * `FetchService` call sites, none of which carry the driver's config — the
+ * service is built from `(db, registry)` alone. Threading an option from
+ * `createPostgresAdapter` down to each of them would mean touching every
+ * intermediate signature to plumb a value that is a single deployment-wide
+ * switch. A module-level default set at adapter construction, plus an explicit
+ * per-call override for callers that have one (tests, mainly), buys the same
+ * control for none of the churn. It is safe by default, so the only reason to
+ * set it at all is to opt *out*.
+ */
+let defaultUnknownFilterFieldsMode: UnknownFilterFieldsMode = "error";
+
+/** Set the process-wide behaviour for unresolvable filter fields. */
+export function configureUnknownFilterFields(mode: UnknownFilterFieldsMode): void {
+    defaultUnknownFilterFieldsMode = mode;
+}
+
+/** The process-wide behaviour for unresolvable filter fields. */
+export function getUnknownFilterFieldsMode(): UnknownFilterFieldsMode {
+    return defaultUnknownFilterFieldsMode;
+}
+
+/** Per-call context for compiling a filter into SQL. */
+export interface FilterCompilationOptions {
+    /**
+     * Overrides the process-wide {@link UnknownFilterFieldsMode} for this call.
+     */
+    unknownFields?: UnknownFilterFieldsMode;
+    /**
+     * The collection the filter is written against. Its resolved relations are
+     * what turn an owning-relation filter key into the foreign-key column it
+     * actually lives in; without it only the default key shapes can be guessed.
+     */
+    collection?: CollectionConfig;
+    /**
+     * The driver's registry, for relations whose link is not on this row at
+     * all. A `manyToMany` compiles to an `EXISTS` over its junction and a
+     * `hasMany`/`hasOne` to one over the target table — neither of which this
+     * builder can reach from the collection alone.
+     */
+    registry?: PostgresCollectionRegistry;
+    /**
+     * The key column of the table being filtered — what those `EXISTS`
+     * subqueries correlate back to.
+     *
+     * It has to be the Drizzle column object rather than a name: a column
+     * renders qualified with its own table, which is what binds it to the
+     * *outer* row instead of to the junction or target aliased inside the
+     * subquery. See {@link DrizzleConditionBuilder.buildRelationFilterCondition}.
+     */
+    sourceIdColumn?: AnyPgColumn;
+}
+
+/**
+ * What a filter field turns out to name.
+ *
+ * A field naming a column compiles to a comparison on it. A field naming a
+ * relation that owns no column here compiles to a whole `EXISTS` condition
+ * instead, so there is no column to hand back — which is why resolution
+ * answers with a discriminated result rather than a column. The caller cannot
+ * tell the two apart from the field name, and the difference is not cosmetic:
+ * one is `column <op> value`, the other is a correlated subquery.
+ */
+type FilterTarget =
+    | { kind: "column"; column: AnyPgColumn }
+    | {
+        kind: "relation";
+        relation: ResolvedForeignKeyOnTarget | ResolvedManyToMany;
+        /** Bound here so the compile step cannot be reached without them. */
+        registry: PostgresCollectionRegistry;
+        sourceIdColumn: AnyPgColumn;
+    };
+
 /**
  * Filter values may arrive as relation wire objects — `EntityRelation`
  * instances or their JSON form `{ __type: "relation", id, path }` — e.g. when
@@ -22,6 +116,23 @@ function unwrapRelationFilterValue(value: unknown): unknown {
     return relation ? relation.id : value;
 }
 
+/**
+ * The operand of `in`/`not-in`, as a list.
+ *
+ * A scalar is the one-element list, because that is what it means and because
+ * the wire produces one: `?filter=id.in.5` parses to the string `"5"`, not to
+ * `["5"]` — the REST dialect only builds an array when the value is
+ * parenthesised. Treating that as malformed and dropping the condition turned
+ * a perfectly ordinary query into an unfiltered read.
+ *
+ * The empty list stays empty. Callers must decide what "no candidates" means
+ * for their operator — it is `FALSE` for `in` and `TRUE` for `not-in` — and
+ * neither of those is "no condition at all".
+ */
+function toMembershipList(value: unknown): unknown[] {
+    return Array.isArray(value) ? value : [value];
+}
+
 /** Drizzle dynamic query builder — accepts innerJoin + where chaining */
 
 export interface DrizzleDynamicQuery {
@@ -99,7 +210,24 @@ export class DrizzleConditionBuilder {
                 // Correlated, not joined: a join through a junction multiplies
                 // the target rows by the number of matching links and silently
                 // breaks `limit`/`offset`.
-                return sql`EXISTS (SELECT 1 FROM ${junctionTable} WHERE ${targetCol} = ${targetIdColumn} AND ${sourceCol} = ${parentId})`;
+                //
+                // The junction is aliased and referenced by identifier, never as a
+                // Drizzle column. A column object carries no table qualifier of its
+                // own — it is rendered against whatever the surrounding builder
+                // thinks the current table is — so inside `db.query.findMany`, which
+                // aliases the root table, `${sourceCol}` came out qualified with the
+                // *target's* alias: `podcast.podcast_id`, a column that does not
+                // exist. That aborts the transaction, and the fallback read then
+                // fails on the poisoned transaction rather than on anything to do
+                // with the relation. Only `targetIdColumn` stays a column object,
+                // because that one *must* bind to the outer row to correlate.
+                //
+                // Aliasing also disambiguates a self-referential many-to-many, where
+                // the junction and the target are the same table.
+                const junctionAlias = "__rel_m2m";
+                const junctionRef = (column: AnyPgColumn) =>
+                    sql`${sql.identifier(junctionAlias)}.${sql.identifier(column.name)}`;
+                return sql`EXISTS (SELECT 1 FROM ${junctionTable} AS ${sql.identifier(junctionAlias)} WHERE ${junctionRef(targetCol)} = ${targetIdColumn} AND ${junctionRef(sourceCol)} = ${parentId})`;
             }
 
             case "hasOne":
@@ -203,40 +331,121 @@ export class DrizzleConditionBuilder {
         return sql`EXISTS (SELECT 1 FROM ${parentTable} AS ${sql.identifier(sourceAlias)}${joinsSql} WHERE ${sql.identifier(sourceAlias)}.${sql.identifier(parentIdColumn.name)} = ${parentId} AND ${correlation})`;
     }
 
+    /**
+     * What a filter field names, or `undefined` if it names nothing.
+     *
+     * Three ways a field resolves. It may address its column directly; it may
+     * be an owning relation, whose foreign key is a column here; or it may be
+     * a relation whose link lives on another table entirely, which compiles to
+     * a subquery instead of a column. Only a field that resolves to *none* of
+     * them is an error, and by default it is one: see
+     * {@link UnknownFilterFieldsMode} for why silently dropping it is a
+     * data-exposure primitive rather than a convenience.
+     *
+     * For an owning relation the relation's own `localKey` is the authority,
+     * not `<field>_id`. The default local key is `generateForeignKeyName`,
+     * which snake-cases *and singularises* — `userProfile` → `user_profile_id`,
+     * `users` → `user_id` — and it can be overridden outright. Guessing
+     * `<field>_id` therefore misses perfectly ordinary owning relations, and
+     * with this resolution failing closed that miss is a 400 on a filter that
+     * has nothing wrong with it. The guesses stay, last, for callers that hand
+     * over no collection to resolve against.
+     *
+     * The subquery kinds need a registry and the source table's key column on
+     * top of the collection. A caller that supplies neither gets the behaviour
+     * it had before they were compilable — unresolvable, and so fail-closed —
+     * rather than a half-built condition.
+     */
+    private static resolveFilterTarget(
+        table: PgTable<any>,
+        field: string,
+        collectionPath: string,
+        mode: UnknownFilterFieldsMode,
+        options: FilterCompilationOptions
+    ): FilterTarget | undefined {
+        const { collection, registry, sourceIdColumn } = options;
+
+        const columnAt = (key: string): AnyPgColumn | undefined =>
+            (key in table ? table[key as keyof typeof table] as AnyPgColumn : undefined) || undefined;
+
+        const direct = columnAt(field);
+        if (direct) return { kind: "column", column: direct };
+
+        if (collection) {
+            const relation = resolveCollectionRelations(collection)[field];
+
+            // Owning relation, resolved: the relation names its own local key.
+            if (relation?.kind === "belongsTo") {
+                const foreignKey = columnAt(relation.localKey);
+                if (foreignKey) return { kind: "column", column: foreignKey };
+            }
+
+            // The link is on the target table or in a junction. `via` is left
+            // out: its join path is authored source → target with no stated
+            // inverse, so reversing it into a filter is a different problem
+            // from the two shapes below rather than a third case of them.
+            if (relation && (hasForeignKeyOnTarget(relation) || isManyToMany(relation)) && registry && sourceIdColumn) {
+                return { kind: "relation", relation, registry, sourceIdColumn };
+            }
+        }
+
+        // No collection in hand — the two shapes an owning relation's key takes
+        // by default (e.g. `project` → `project_id`, `userProfile` →
+        // `user_profile_id`).
+        for (const guess of [`${field}_id`, generateForeignKeyName(field)]) {
+            const foreignKey = columnAt(guess);
+            if (foreignKey) return { kind: "column", column: foreignKey };
+        }
+
+        if (mode === "warn") {
+            logger.warn(`Filtering by field '${field}', but it does not exist in table for collection '${collectionPath}'`);
+            return undefined;
+        }
+
+        let validFields: string[] = [];
+        try {
+            validFields = Object.keys(getTableColumns(table)).sort();
+        } catch {
+            // A table stand-in without Drizzle's column symbols — the message
+            // is worth less without the list, but not worth failing over.
+        }
+
+        // Not `expected`: unlike an anonymous token refresh, this is never a
+        // routine outcome. It means a filter key and the schema have drifted
+        // apart, which used to widen results silently — exactly the thing an
+        // operator wants in the log at warn.
+        throw ApiError.badRequest(
+            `Unknown filter field '${field}' on collection '${collectionPath}'` +
+            (validFields.length > 0 ? `. Valid fields: ${validFields.join(", ")}` : ""),
+            "UNKNOWN_FILTER_FIELD",
+            { field, collection: collectionPath, ...(validFields.length > 0 && { validFields }) }
+        );
+    }
+
     /**
      * Build filter conditions from FilterValues
      */
     static buildFilterConditions<M extends Record<string, unknown>>(
         filter: FilterValues<Extract<keyof M, string>>,
         table: PgTable<any>,
-        collectionPath: string
+        collectionPath: string,
+        options: FilterCompilationOptions = {}
     ): SQL[] {
+        const mode = options.unknownFields ?? defaultUnknownFilterFieldsMode;
         const conditions: SQL[] = [];
 
         for (const [field, filterParam] of Object.entries(filter)) {
             if (!filterParam) continue;
 
-            let fieldColumn = table[field as keyof typeof table] as AnyPgColumn;
-
-            if (!fieldColumn) {
-                // Fallback for relations (e.g. project -> project_id)
-                const relationKey = `${field}_id`;
-                if (relationKey in table) {
-                    fieldColumn = table[relationKey as keyof typeof table] as AnyPgColumn;
-                }
-            }
-
-            if (!fieldColumn) {
-                logger.warn(`Filtering by field '${field}', but it does not exist in table for collection '${collectionPath}'`);
-                continue;
-            }
+            const target = this.resolveFilterTarget(table, field, collectionPath, mode, options);
+            if (!target) continue;
 
             const paramsList = Array.isArray(filterParam) && filterParam.length > 0 && Array.isArray(filterParam[0])
                 ? (filterParam as [WhereFilterOp, any][])
                 : [filterParam as [WhereFilterOp, any]];
 
             for (const [op, value] of paramsList) {
-                const condition = this.buildSingleFilterCondition(fieldColumn, op, value);
+                const condition = this.compileFilterTarget(target, op, value, field, collectionPath);
                 if (condition) {
                     conditions.push(condition);
                 }
@@ -252,28 +461,257 @@ export class DrizzleConditionBuilder {
     static buildLogicalConditions(
         cond: LogicalCondition | FilterCondition,
         table: PgTable<any>,
-        collectionPath: string
+        collectionPath: string,
+        options: FilterCompilationOptions = {}
     ): SQL | null {
         if ("type" in cond) {
             const subSQLs = cond.conditions
-                .map(c => this.buildLogicalConditions(c, table, collectionPath))
+                .map(c => this.buildLogicalConditions(c, table, collectionPath, options))
                 .filter((sql): sql is SQL => sql !== null);
             if (subSQLs.length === 0) return null;
             return (cond.type === "or" ? or(...subSQLs) : and(...subSQLs)) ?? null;
         } else {
-            let fieldColumn = table[cond.column as keyof typeof table] as AnyPgColumn;
-            if (!fieldColumn) {
-                const relationKey = `${cond.column}_id`;
-                if (relationKey in table) {
-                    fieldColumn = table[relationKey as keyof typeof table] as AnyPgColumn;
-                }
+            // A dropped leaf is worse here than in a flat filter: inside an
+            // `or(...)` the disjunction loses a branch, so the surviving
+            // branches match on their own and the result set widens by
+            // everything the dropped leaf would have excluded.
+            const target = this.resolveFilterTarget(
+                table,
+                cond.column,
+                collectionPath,
+                options.unknownFields ?? defaultUnknownFilterFieldsMode,
+                options
+            );
+            if (!target) return null;
+            return this.compileFilterTarget(
+                target, cond.operator as WhereFilterOp, cond.value, cond.column, collectionPath
+            );
+        }
+    }
+
+    /** Dispatch a resolved filter field onto the shape it actually compiles to. */
+    private static compileFilterTarget(
+        target: FilterTarget,
+        op: WhereFilterOp,
+        value: unknown,
+        field: string,
+        collectionPath: string
+    ): SQL | null {
+        return target.kind === "column"
+            ? this.buildSingleFilterCondition(target.column, op, value)
+            : this.buildRelationFilterCondition(
+                target.relation, op, value, target.sourceIdColumn, target.registry, field, collectionPath
+            );
+    }
+
+    /**
+     * A filter on a relation that owns no column on this row — `EXISTS` over
+     * the rows it reaches.
+     *
+     * `posts` filtered by `tags == <tagId>` is not a comparison on `posts`; it
+     * is a question about the junction:
+     *
+     *     EXISTS (SELECT 1 FROM posts_tags AS j
+     *             WHERE j.post_id = posts.id AND j.tag_id = <tagId>)
+     *
+     * which is {@link buildRelationScopeCondition}'s many-to-many shape with
+     * source and target swapped — there the junction's *target* column
+     * correlates and the source is pinned; here the *source* column correlates
+     * and the target is what the filter constrains.
+     *
+     * `hasMany`/`hasOne` are the same shape one table over: the target row
+     * carries the foreign key, so the correlation is on that key and the
+     * compared column is the target's own id.
+     *
+     * `EXISTS` and not a join, for the reason the scope condition gives: a join
+     * through a junction multiplies the outer rows by the number of matching
+     * links, which duplicates results and silently breaks `limit`/`offset`.
+     *
+     * Everything inside the subquery is referenced by identifier against a
+     * local alias, and only `sourceIdColumn` stays a Drizzle column object —
+     * again see {@link buildRelationScopeCondition}, which explains why a
+     * column object renders against whatever table the surrounding builder
+     * thinks is current and so cannot be used for the inner references. The
+     * alias is also what keeps a self-referential relation unambiguous
+     * (`categories.children`, or a many-to-many whose junction and target are
+     * the same table), where the subquery's table and the outer one coincide.
+     */
+    static buildRelationFilterCondition(
+        relation: ResolvedForeignKeyOnTarget | ResolvedManyToMany,
+        op: WhereFilterOp,
+        value: unknown,
+        sourceIdColumn: AnyPgColumn,
+        registry: PostgresCollectionRegistry,
+        field: string,
+        collectionPath: string
+    ): SQL {
+        const alias = "__rel_filter";
+        const ref = (column: AnyPgColumn) =>
+            sql`${sql.identifier(alias)}.${sql.identifier(column.name)}`;
+
+        let scanTable: PgTable<any>;
+        let correlation: SQL;
+        let comparedColumn: AnyPgColumn;
+
+        if (relation.kind === "manyToMany") {
+            const { table: junctionName, sourceColumn, targetColumn } = relation.through;
+            const junctionTable = registry.getTable(junctionName);
+            if (!junctionTable) {
+                throw new Error(`Junction table not found: ${junctionName}`);
             }
-            if (!fieldColumn) {
-                logger.warn(`Filtering by field '${cond.column}', but it does not exist in table for collection '${collectionPath}'`);
-                return null;
+            const sourceCol = junctionTable[sourceColumn as keyof typeof junctionTable] as AnyPgColumn;
+            const targetCol = junctionTable[targetColumn as keyof typeof junctionTable] as AnyPgColumn;
+            if (!sourceCol || !targetCol) {
+                throw new Error(
+                    `Junction columns '${sourceColumn}'/'${targetColumn}' not found in '${junctionName}'`
+                );
             }
-            return this.buildSingleFilterCondition(fieldColumn, cond.operator as WhereFilterOp, cond.value);
+            scanTable = junctionTable;
+            correlation = sql`${ref(sourceCol)} = ${sourceIdColumn}`;
+            comparedColumn = targetCol;
+        } else {
+            const targetCollection = relation.target();
+            const targetTable = registry.getTable(getTableName(targetCollection));
+            if (!targetTable) {
+                throw new Error(
+                    `Table not found for the target of relation '${relation.relationName}' ` +
+                    `(collection '${targetCollection.slug}')`
+                );
+            }
+            const fkColumn = targetTable[relation.foreignKeyOnTarget as keyof typeof targetTable] as AnyPgColumn;
+            if (!fkColumn) {
+                throw new Error(
+                    `Foreign key column '${relation.foreignKeyOnTarget}' not found in the target table of ` +
+                    `relation '${relation.relationName}'.`
+                );
+            }
+            // The filter value is a target row's id, so that is what the
+            // subquery compares — the foreign key is spent on the correlation.
+            const targetIdColumn = this.primaryKeyColumn(targetTable);
+            if (!targetIdColumn) {
+                throw new Error(
+                    `No primary key or "id" column in the target table of relation '${relation.relationName}', ` +
+                    `so a filter on it has nothing to match against.`
+                );
+            }
+            scanTable = targetTable;
+            correlation = sql`${ref(fkColumn)} = ${sourceIdColumn}`;
+            comparedColumn = targetIdColumn;
         }
+
+        const { predicate, negate } = this.buildRelationFilterPredicate(
+            ref(comparedColumn), op, value, field, collectionPath
+        );
+
+        const where = predicate ? sql`${correlation} AND ${predicate}` : correlation;
+        const exists = sql`EXISTS (SELECT 1 FROM ${scanTable} AS ${sql.identifier(alias)} WHERE ${where})`;
+        return negate ? sql`NOT ${exists}` : exists;
+    }
+
+    /**
+     * The inner predicate of a relation filter, and whether the `EXISTS`
+     * wrapping it is negated.
+     *
+     * Negation is `NOT EXISTS` of the *positive* predicate, never `EXISTS` of a
+     * negated one. On a many-valued relation the two are different questions:
+     * `EXISTS (… AND tag_id != X)` asks "does some tag differ from X", which is
+     * true of nearly every post with more than one tag and answers nothing
+     * anybody asked. `NOT EXISTS (… AND tag_id = X)` asks "is X absent", which
+     * is what unticking a value in a filter control means — and it makes `==`
+     * and `!=` partition the rows, the way a filter implies they do.
+     *
+     * `is-null`/`is-not-null` drop the predicate entirely: with nothing but the
+     * correlation left, they become "has no related row at all" and "has at
+     * least one", which is the only reading of null a link can have.
+     *
+     * Under RLS, "no related row" means *no row this reader can see*. A junction
+     * with row-level security but no `SELECT` policy for `rebase_user` is opaque
+     * to it, so every row comes back looking unlinked and `is-null` matches all
+     * of them. That is not a leak — the outer table's own policies still decide
+     * which rows exist at all, and the positive direction correctly returns
+     * nothing — but it over-reports, and the cause is a missing junction policy
+     * rather than anything here. Rebase derives one for a declared many-to-many;
+     * a hand-written schema has to supply it.
+     *
+     * `in`/`not-in` against a *null value* mean the same thing, rather than
+     * membership of an empty list. Membership against null is not a membership
+     * question, and the admin's "filter for null values" control emits the
+     * operator that happens to be selected — on a to-many relation that is
+     * always `in` or `not-in`, because those are the only ones the multi-select
+     * can produce. Reading `["in", null]` as an empty list would answer "posts
+     * with no tags" with no posts at all.
+     *
+     * An empty `in` list compiles to `FALSE` rather than being dropped. Dropped
+     * is what the column path does, and dropping a condition widens the result
+     * — the whole reason this resolution fails closed. `in []` matches nothing
+     * and `not-in []` matches everything, and `NOT EXISTS (… AND FALSE)` gives
+     * the second for free.
+     *
+     * Anything else is rejected. Returning `null` for an operator this cannot
+     * express would drop the condition, and the operators the admin offers for
+     * a relation are exactly the six below.
+     */
+    private static buildRelationFilterPredicate(
+        ref: SQL,
+        op: WhereFilterOp,
+        value: unknown,
+        field: string,
+        collectionPath: string
+    ): { predicate?: SQL; negate: boolean } {
+        value = unwrapRelationFilterValue(value);
+        const isNullish = value === null || value === undefined;
+
+        const equals = () => sql`${ref} = ${value}`;
+        const inList = () => {
+            // Same reading as the column path: a scalar is the one-element
+            // list, an empty list is `FALSE`. Here `FALSE` also gives
+            // `not-in []` its answer for free — `NOT EXISTS (… AND FALSE)`
+            // is true of every row, which is what excluding nothing means.
+            const values = toMembershipList(value);
+            return values.length === 0
+                ? sql`FALSE`
+                : sql`${ref} IN (${sql.join(values.map(v => sql`${v}`), sql`, `)})`;
+        };
+
+        switch (op) {
+            case "==":
+                return isNullish ? { negate: true } : { predicate: equals(), negate: false };
+            case "!=":
+                return isNullish ? { negate: false } : { predicate: equals(), negate: true };
+            case "in":
+                return isNullish ? { negate: true } : { predicate: inList(), negate: false };
+            case "not-in":
+                return isNullish ? { negate: false } : { predicate: inList(), negate: true };
+            case "is-null":
+                return { negate: true };
+            case "is-not-null":
+                return { negate: false };
+            // A to-many relation *is* the list, so the array operators ask the
+            // same two questions under different names: "contains X" is "some
+            // related row is X", and "contains any of [X, Y]" is `in`. They
+            // reach here because the admin offers them for a property that is
+            // an *array of* relations, and rejecting a question the shape
+            // answers perfectly well would put a 400 behind a working control.
+            case "array-contains":
+                return isNullish ? { negate: true } : { predicate: equals(), negate: false };
+            case "array-contains-any":
+                return isNullish ? { negate: true } : { predicate: inList(), negate: false };
+            default:
+                throw ApiError.badRequest(
+                    `Operator '${op}' cannot be applied to relation field '${field}' on collection ` +
+                    `'${collectionPath}'. A relation with no column on this row is filtered by ` +
+                    "membership: ==, !=, in, not-in, array-contains, array-contains-any, is-null, " +
+                    "is-not-null.",
+                    "UNSUPPORTED_RELATION_FILTER_OPERATOR",
+                    { field, collection: collectionPath, operator: op }
+                );
+        }
+    }
+
+    /** The column a table's rows are keyed by: its primary key, else `id`. */
+    private static primaryKeyColumn(table: PgTable<any>): AnyPgColumn | undefined {
+        return (Object.values(table).find((col: Record<string, unknown>) => col.primary)
+            ?? Object.values(table).find((col: Record<string, unknown>) => col.name === "id")) as AnyPgColumn | undefined;
     }
 
     /**
@@ -304,11 +742,25 @@ export class DrizzleConditionBuilder {
                 return sql`${column} < ${value}`;
             case "<=":
                 return sql`${column} <= ${value}`;
-            case "in":
-                if (Array.isArray(value) && value.length > 0) {
-                    return inArray(column, value);
+            case "in": {
+                // Membership against a null *value* is a null check, not an
+                // empty list — the admin's "filter for null values" control
+                // emits whichever operator is selected, so `["in", null]` is
+                // how it asks for a null foreign key when the user picked
+                // `in`. Reading it as an empty list dropped the condition
+                // outright, which widened the read to every row.
+                if (value === null || value === undefined) {
+                    return sql`${column} IS NULL`;
                 }
-                return null;
+                const values = toMembershipList(value);
+                // An empty list matches nothing. Returning no condition — what
+                // this did — matches *everything*, which is the same inversion
+                // one layer down from the one `UnknownFilterFieldsMode` exists
+                // for. It is the dangerous shape too: `filter: { id: ["in",
+                // teamIds] }` with no teams is how a caller asks for nothing,
+                // and it answered with the whole table.
+                return values.length === 0 ? sql`FALSE` : inArray(column, values);
+            }
             case "array-contains": {
                 const meta = getColumnMeta(column);
                 if (meta.dataType === "array" || meta.columnType === "PgArray") {
@@ -320,6 +772,13 @@ export class DrizzleConditionBuilder {
             case "array-contains-any": {
                 const meta = getColumnMeta(column);
                 const isNativeArray = meta.dataType === "array" || meta.columnType === "PgArray";
+                // "Overlaps nothing" is false, not a licence to skip the
+                // condition. The single-value fallback below is for a *scalar*
+                // operand; an empty array fell into it and built
+                // `@> ARRAY[$1]` around an empty binding.
+                if (Array.isArray(value) && value.length === 0) {
+                    return sql`FALSE`;
+                }
                 if (Array.isArray(value) && value.length > 0) {
                     if (isNativeArray) {
                         return sql`${column} && ARRAY[${sql.join(value.map(v => sql`${v}`), sql`, `)}]`;
@@ -335,11 +794,18 @@ export class DrizzleConditionBuilder {
                 }
                 return sql`${column} @> ${JSON.stringify([value])}`;
             }
-            case "not-in":
-                if (Array.isArray(value) && value.length > 0) {
-                    return sql`${column} NOT IN (${sql.join(value.map(v => sql`${v}`), sql`, `)})`;
+            case "not-in": {
+                // The mirror of `in` above, including the empty list — which
+                // excludes nothing, and so matches every row. Same condition
+                // the old code produced by accident, now on purpose and for
+                // the empty list only.
+                if (value === null || value === undefined) {
+                    return sql`${column} IS NOT NULL`;
                 }
-                return null;
+                const values = toMembershipList(value);
+                if (values.length === 0) return sql`TRUE`;
+                return sql`${column} NOT IN (${sql.join(values.map(v => sql`${v}`), sql`, `)})`;
+            }
             case "like":
                 return sql`${column} LIKE ${String(value)}`;
             case "ilike":
@@ -746,9 +1212,7 @@ whereConditions };
         if (relation.kind === "belongsTo") {
             // `parentId` is the foreign key's value, matched against the
             // target's own key.
-            const targetIdCol =
-                (Object.values(targetTable).find((col: Record<string, unknown>) => col.primary)
-                    ?? Object.values(targetTable).find((col: Record<string, unknown>) => col.name === "id")) as AnyPgColumn | undefined;
+            const targetIdCol = this.primaryKeyColumn(targetTable);
             if (!targetIdCol) {
                 throw new Error(
                     `No primary key or "id" column in the target table of relation '${relation.relationName}'.`