@rebasepro/server-postgres 0.9.1-canary.58368ce → 0.9.1-canary.682a9cf

package/src/services/RelationService.ts

@@ -1,4 +1,4 @@
-import { and, eq, inArray, sql, SQL } from "drizzle-orm";
+import { and, eq, inArray, or, sql, SQL } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import { DrizzleClient } from "../interfaces";
 import { CollectionConfig, FilterValues, Relation } from "@rebasepro/types";
@@ -7,9 +7,10 @@ import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
 import {
     getCollectionByPath,
     getTableForCollection,
-    getPrimaryKeys,
+    requirePrimaryKeys,
     parseIdValues,
-    buildCompositeId
+    buildCompositeId,
+    type PrimaryKeyInfo
 } from "./collection-helpers";
 import { parseDataFromServer } from "../data-transformer";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
@@ -56,6 +57,94 @@ export interface RelatedRow<M extends Record<string, unknown> = Record<string, u
 export class RelationService {
     constructor(private db: DrizzleClient, private registry: PostgresCollectionRegistry) { }
 
+    /**
+     * One target row, as the {@link RelatedRow} everything here returns.
+     *
+     * Eight sites built this by hand, which is how the address came to be the
+     * target's first key column in all eight — one edit, eight places to miss.
+     *
+     * `resolveNested` is the one thing they did not agree on, and the
+     * disagreement was invisible: the single-parent fetches pass `db` and
+     * `registry` to `parseDataFromServer`, so the target's *own* relations get
+     * resolved too, while the batch paths deliberately do not — a query per
+     * target row is the N+1 the batching exists to avoid. Naming the parameter
+     * makes that a decision rather than a difference between two call sites
+     * nobody was comparing.
+     */
+    private async toRelatedRow<M extends Record<string, unknown>>(
+        targetRow: Record<string, unknown>,
+        targetCollection: CollectionConfig,
+        targetPks: PrimaryKeyInfo[],
+        options?: { resolveNested?: boolean }
+    ): Promise<RelatedRow<M>> {
+        const values = options?.resolveNested
+            ? await parseDataFromServer(targetRow, targetCollection, this.db, this.registry)
+            : await parseDataFromServer(targetRow, targetCollection);
+
+        return {
+            // The whole key: a composite target addressed by its first column
+            // names every row that shares it.
+            id: buildCompositeId(targetRow, targetPks),
+            path: targetCollection.slug,
+            values: values as M
+        };
+    }
+
+    /**
+     * A WHERE matching any of `parentIds`, by the whole key.
+     *
+     * A single key is an `IN (…)`. A composite one cannot be: matching
+     * `tenant_id IN (1, 1)` collects every row of tenant 1, so two parents that
+     * share their first column each receive the other's relations. It becomes
+     * an OR of ANDs — one exact address per parent — which Postgres indexes the
+     * same way it would a multi-column key lookup.
+     */
+    private parentKeyCondition(
+        parentTable: PgTable,
+        parentPks: PrimaryKeyInfo[],
+        parentIds: (string | number)[]
+    ): SQL {
+        const columnFor = (fieldName: string) => {
+            const col = parentTable[fieldName as keyof typeof parentTable] as AnyPgColumn;
+            if (!col) throw new Error(`Key column '${fieldName}' not found in parent table`);
+            return col;
+        };
+
+        if (parentPks.length === 1) {
+            const values = parentIds.map(id => parseIdValues(id, parentPks)[parentPks[0].fieldName]);
+            return inArray(columnFor(parentPks[0].fieldName), values);
+        }
+
+        const perParent = parentIds.map(id => {
+            const values = parseIdValues(id, parentPks);
+            return and(...parentPks.map(pk => eq(columnFor(pk.fieldName), values[pk.fieldName])));
+        });
+        return or(...perParent) as SQL;
+    }
+
+    /**
+     * Reject a relation that cannot express a composite-keyed parent.
+     *
+     * `localKey` and `foreignKeyOnTarget` are single column names: one column
+     * cannot reference a two-column key, so such a relation has no correct
+     * reading. Left alone it would silently match on the first key column and
+     * hand a tenant's rows to its neighbour — say so instead.
+     */
+    private assertSingleKeyAddressable(
+        parentCollection: CollectionConfig,
+        parentPks: PrimaryKeyInfo[],
+        via: string
+    ): void {
+        if (parentPks.length > 1) {
+            throw new Error(
+                `Relation on '${parentCollection.slug}' uses '${via}', a single foreign-key column, but ` +
+                `'${parentCollection.slug}' is keyed on ${parentPks.map(k => `'${k.fieldName}'`).join(" + ")}. ` +
+                `One column cannot reference a composite key — express this relation with \`joinPath\`, whose ` +
+                `\`on.from\`/\`on.to\` take every key column.`
+            );
+        }
+    }
+
     /**
      * Fetch rows related to a parent row through a specific relation
      */
@@ -104,10 +193,10 @@ export class RelationService {
     ): Promise<RelatedRow<M>[]> {
         const targetCollection = relation.target();
         const targetTable = getTableForCollection(targetCollection, this.registry);
-        const idInfo = getPrimaryKeys(targetCollection, this.registry);
+        const idInfo = requirePrimaryKeys(targetCollection, this.registry);
         const idField = targetTable[idInfo[0].fieldName as keyof typeof targetTable] as AnyPgColumn;
 
-        const parentPks = getPrimaryKeys(parentCollection, this.registry);
+        const parentPks = requirePrimaryKeys(parentCollection, this.registry);
         const parentIdInfo = parentPks[0];
         const parsedParentIdObj = parseIdValues(parentId, parentPks);
         const parsedParentId = parsedParentIdObj[parentIdInfo.fieldName];
@@ -148,7 +237,7 @@ export class RelationService {
             }
 
             // Add where condition for the parent row
-            const parentIdField = parentTable[getPrimaryKeys(parentCollection, this.registry)[0].fieldName as keyof typeof parentTable] as AnyPgColumn;
+            const parentIdField = parentTable[requirePrimaryKeys(parentCollection, this.registry)[0].fieldName as keyof typeof parentTable] as AnyPgColumn;
             query = query.where(eq(parentIdField, parsedParentId));
 
             if (options.limit) {
@@ -162,15 +251,7 @@ export class RelationService {
             const rows: RelatedRow<M>[] = [];
             for (const row of results as Array<Record<string, unknown>>) {
                 const targetRow = (row[targetTableName] as Record<string, unknown>) || row;
-                const parsedValues = await parseDataFromServer(targetRow, targetCollection, this.db, this.registry);
-
-                rows.push({
-                    // The whole key: the first column of a composite one names
-                    // every row that shares it.
-                    id: buildCompositeId(targetRow, idInfo),
-                    path: targetCollection.slug,
-                    values: parsedValues as M
-                });
+                rows.push(await this.toRelatedRow<M>(targetRow, targetCollection, idInfo, { resolveNested: true }));
             }
 
             return rows;
@@ -229,13 +310,7 @@ export class RelationService {
         const rows: RelatedRow<M>[] = [];
         for (const row of results) {
             const targetRow = row[getTableName(targetCollection)] || row;
-            const parsedValues = await parseDataFromServer(targetRow, targetCollection, this.db, this.registry);
-
-            rows.push({
-                id: buildCompositeId(targetRow as Record<string, unknown>, idInfo),
-                path: targetCollection.slug,
-                values: parsedValues as M
-            });
+            rows.push(await this.toRelatedRow<M>(targetRow as Record<string, unknown>, targetCollection, idInfo, { resolveNested: true }));
         }
 
         return rows;
@@ -260,11 +335,11 @@ export class RelationService {
 
         const targetCollection = relation.target();
         const targetTable = getTableForCollection(targetCollection, this.registry);
-        const targetPks = getPrimaryKeys(targetCollection, this.registry);
+        const targetPks = requirePrimaryKeys(targetCollection, this.registry);
         const targetIdInfo = targetPks[0];
         const targetIdField = targetTable[targetIdInfo.fieldName as keyof typeof targetTable] as AnyPgColumn;
 
-        const parentPks = getPrimaryKeys(parentCollection, this.registry);
+        const parentPks = requirePrimaryKeys(parentCollection, this.registry);
         const parentIdInfo = parentPks[0];
         const parsedParentIdObj = parseIdValues(parentId, parentPks);
         const parsedParentId = parsedParentIdObj[parentIdInfo.fieldName];
@@ -309,11 +384,11 @@ export class RelationService {
         const parentCollection = getCollectionByPath(parentCollectionPath, this.registry);
         const targetCollection = relation.target();
         const targetTable = getTableForCollection(targetCollection, this.registry);
-        const targetPks = getPrimaryKeys(targetCollection, this.registry);
+        const targetPks = requirePrimaryKeys(targetCollection, this.registry);
         const targetIdInfo = targetPks[0];
         const targetIdField = targetTable[targetIdInfo.fieldName as keyof typeof targetTable] as AnyPgColumn;
 
-        const parentPks = getPrimaryKeys(parentCollection, this.registry);
+        const parentPks = requirePrimaryKeys(parentCollection, this.registry);
         const parentIdInfo = parentPks[0];
         const parentTable = this.registry.getTable(getTableName(parentCollection));
         if (!parentTable) throw new Error("Parent table not found");
@@ -354,27 +429,23 @@ export class RelationService {
                 currentTable = joinTable;
             }
 
-            // Add where condition for ALL parent rows at once
-            const parentIdField = parentTable[getPrimaryKeys(parentCollection, this.registry)[0].fieldName as keyof typeof parentTable] as AnyPgColumn;
-            query = query.where(inArray(parentIdField, parsedParentIds));
+            // Match every parent at once, each by its whole key.
+            query = query.where(this.parentKeyCondition(parentTable, parentPks, parentIds));
 
             const results = await query;
             const targetTableName = relation.joinPath[relation.joinPath.length - 1].table;
             const resultMap = new Map<string, RelatedRow<Record<string, unknown>>>();
 
-            // Group results by parent ID
+            // Group by the parent's address — the same token the caller looks
+            // results up by, derived the same way on both sides.
             for (const row of results as Array<Record<string, unknown>>) {
                 const parentRow = (row[getTableName(parentCollection)] || row) as Record<string, unknown>;
                 const targetRow = (row[targetTableName] || row) as Record<string, unknown>;
-                const parentId = parentRow[parentIdInfo.fieldName] as string | number;
-
-                const parsedValues = await parseDataFromServer(targetRow, targetCollection);
 
-                resultMap.set(String(parentId), {
-                    id: buildCompositeId(targetRow, targetPks),
-                    path: targetCollection.slug,
-                    values: parsedValues as Record<string, unknown>
-                });
+                resultMap.set(
+                    buildCompositeId(parentRow, parentPks),
+                    await this.toRelatedRow(targetRow, targetCollection, targetPks)
+                );
             }
 
             return resultMap;
@@ -387,6 +458,7 @@ export class RelationService {
         //   2. Query the target table with unique FK values
         //   3. Map results back to parent rows via their FK values
         if (relation.direction === "owning" && relation.localKey) {
+            this.assertSingleKeyAddressable(parentCollection, parentPks, relation.localKey);
             const localKeyCol = parentTable[relation.localKey as keyof typeof parentTable] as AnyPgColumn;
             if (!localKeyCol) {
                 throw new Error(`Local key column '${relation.localKey}' not found in parent table`);
@@ -436,19 +508,21 @@ export class RelationService {
             for (const [parentIdStr, fkValue] of parentToFk) {
                 const targetRow = targetById.get(String(fkValue));
                 if (targetRow) {
-                    const parsedValues = await parseDataFromServer(targetRow, targetCollection);
-                    resultMap.set(parentIdStr, {
-                        id: buildCompositeId(targetRow, targetPks),
-                        path: targetCollection.slug,
-                        values: parsedValues as Record<string, unknown>
-                    });
+                    resultMap.set(parentIdStr, await this.toRelatedRow(targetRow, targetCollection, targetPks));
                 }
             }
 
             return resultMap;
         }
 
-        // Handle inverse relation types with batching
+        // Handle inverse relation types with batching. The parent is named by a
+        // single FK column on the target, so a composite-keyed parent has no
+        // correct reading here either.
+        this.assertSingleKeyAddressable(
+            parentCollection,
+            parentPks,
+            relation.foreignKeyOnTarget ?? `${relation.inverseRelationName}_id`
+        );
         let query = this.db.select().from(targetTable).$dynamic();
 
         // Build the relation query with ALL parent IDs
@@ -488,12 +562,7 @@ export class RelationService {
             }
 
             if (parentId !== undefined && parentIdSet.has(String(parentId))) {
-                const parsedValues = await parseDataFromServer(targetRow, targetCollection);
-                resultMap.set(String(parentId), {
-                    id: buildCompositeId(targetRow, targetPks),
-                    path: targetCollection.slug,
-                    values: parsedValues as Record<string, unknown>
-                });
+                resultMap.set(String(parentId), await this.toRelatedRow(targetRow, targetCollection, targetPks));
             }
         }
 
@@ -516,11 +585,11 @@ export class RelationService {
         const parentCollection = getCollectionByPath(parentCollectionPath, this.registry);
         const targetCollection = relation.target();
         const targetTable = getTableForCollection(targetCollection, this.registry);
-        const targetPks = getPrimaryKeys(targetCollection, this.registry);
+        const targetPks = requirePrimaryKeys(targetCollection, this.registry);
         const targetIdInfo = targetPks[0];
         const targetIdField = targetTable[targetIdInfo.fieldName as keyof typeof targetTable] as AnyPgColumn;
 
-        const parentPks = getPrimaryKeys(parentCollection, this.registry);
+        const parentPks = requirePrimaryKeys(parentCollection, this.registry);
         const parentIdInfo = parentPks[0];
         const parentTable = this.registry.getTable(getTableName(parentCollection));
         if (!parentTable) throw new Error("Parent table not found");
@@ -550,8 +619,7 @@ export class RelationService {
                 currentTable = joinTable;
             }
 
-            const parentIdField = parentTable[getPrimaryKeys(parentCollection, this.registry)[0].fieldName as keyof typeof parentTable] as AnyPgColumn;
-            query = query.where(inArray(parentIdField, parsedParentIds));
+            query = query.where(this.parentKeyCondition(parentTable, parentPks, parentIds));
 
             const results = await query;
             const targetTableName = relation.joinPath[relation.joinPath.length - 1].table;
@@ -560,15 +628,9 @@ export class RelationService {
             for (const row of results as Array<Record<string, unknown>>) {
                 const parentRow = (row[getTableName(parentCollection)] || row) as Record<string, unknown>;
                 const targetRow = (row[targetTableName] || row) as Record<string, unknown>;
-                const parentId = String(parentRow[parentIdInfo.fieldName]);
-                const parsedValues = await parseDataFromServer(targetRow, targetCollection);
-
+                const parentId = buildCompositeId(parentRow, parentPks);
                 const arr = resultMap.get(parentId) || [];
-                arr.push({
-                    id: buildCompositeId(targetRow, targetPks),
-                    path: targetCollection.slug,
-                    values: parsedValues as Record<string, unknown>
-                });
+                arr.push(await this.toRelatedRow(targetRow, targetCollection, targetPks));
                 resultMap.set(parentId, arr);
             }
 
@@ -579,6 +641,9 @@ export class RelationService {
         // This is the standard path for posts→tags style relations where
         // sanitizeRelation populated the `through` config.
         if (relation.through && relation.cardinality === "many" && relation.direction === "owning") {
+            // The junction names its parent with one column, so the same
+            // single-key limit applies as for a direct foreign key.
+            this.assertSingleKeyAddressable(parentCollection, parentPks, `${relation.through.table}.${relation.through.sourceColumn}`);
             const junctionTable = this.registry.getTable(relation.through.table);
             if (!junctionTable) {
                 logger.warn(`[batchFetchRelatedEntitiesMany] Junction table '${relation.through.table}' not found`);
@@ -612,21 +677,21 @@ export class RelationService {
                 const targetData = (row[targetTableName] || row) as Record<string, unknown>;
 
                 const parentId = String(junctionData[relation.through.sourceColumn]);
-                const parsedValues = await parseDataFromServer(targetData, targetCollection);
-
                 const arr = resultMap.get(parentId) || [];
-                arr.push({
-                    id: buildCompositeId(targetData, targetPks),
-                    path: targetCollection.slug,
-                    values: parsedValues as Record<string, unknown>
-                });
+                arr.push(await this.toRelatedRow(targetData, targetCollection, targetPks));
                 resultMap.set(parentId, arr);
             }
 
             return resultMap;
         }
 
-        // Handle FK-based relations (one-to-many inverse)
+        // Handle FK-based relations (one-to-many inverse). One column on the
+        // target names the parent, so a composite-keyed parent cannot be named.
+        this.assertSingleKeyAddressable(
+            parentCollection,
+            parentPks,
+            relation.foreignKeyOnTarget ?? `${relation.inverseRelationName}_id`
+        );
         let query = this.db.select().from(targetTable).$dynamic();
 
         query = applyDynamicRelationQuery(
@@ -668,14 +733,9 @@ export class RelationService {
             }
 
             if (parentId !== undefined && parentIdSet.has(String(parentId))) {
-                const parsedValues = await parseDataFromServer(targetRow, targetCollection);
                 const key = String(parentId);
                 const arr = resultMap.get(key) || [];
-                arr.push({
-                    id: buildCompositeId(targetRow, targetPks),
-                    path: targetCollection.slug,
-                    values: parsedValues as Record<string, unknown>
-                });
+                arr.push(await this.toRelatedRow(targetRow, targetCollection, targetPks));
                 resultMap.set(key, arr);
             }
         }
@@ -746,7 +806,7 @@ export class RelationService {
                     continue;
                 }
 
-                const parentPks = getPrimaryKeys(collection, this.registry);
+                const parentPks = requirePrimaryKeys(collection, this.registry);
                 const parentIdInfo = parentPks[0];
                 const parsedParentIdObj = parseIdValues(id, parentPks);
                 const parsedParentId = parsedParentIdObj[parentIdInfo.fieldName];
@@ -755,7 +815,7 @@ export class RelationService {
                 await tx.delete(junctionTable).where(eq(sourceJunctionColumn, parsedParentId));
 
                 if (targetEntityIds.length > 0) {
-                    const targetPks = getPrimaryKeys(targetCollection, this.registry);
+                    const targetPks = requirePrimaryKeys(targetCollection, this.registry);
                     const targetIdInfo = targetPks[0];
                     const parsedTargetIds = targetEntityIds.map(id => parseIdValues(id, targetPks)[targetIdInfo.fieldName]);
 
@@ -784,7 +844,7 @@ export class RelationService {
                     continue;
                 }
 
-                const parentPks = getPrimaryKeys(collection, this.registry);
+                const parentPks = requirePrimaryKeys(collection, this.registry);
                 const parentIdInfo = parentPks[0];
                 const parsedParentIdObj = parseIdValues(id, parentPks);
                 const parsedParentId = parsedParentIdObj[parentIdInfo.fieldName];
@@ -793,7 +853,7 @@ export class RelationService {
                 await tx.delete(junctionTable).where(eq(sourceJunctionColumn, parsedParentId));
 
                 if (targetEntityIds.length > 0) {
-                    const targetPks = getPrimaryKeys(targetCollection, this.registry);
+                    const targetPks = requirePrimaryKeys(targetCollection, this.registry);
                     const targetIdInfo = targetPks[0];
                     const parsedTargetIds = targetEntityIds.map(id => parseIdValues(id, targetPks)[targetIdInfo.fieldName]);
 
@@ -813,7 +873,7 @@ export class RelationService {
             } else if (relation.cardinality === "many" && relation.direction === "inverse" && relation.foreignKeyOnTarget) {
                 // Handle one-to-many (inverse) by updating target FK to point to parent
                 const targetTable = getTableForCollection(targetCollection, this.registry);
-                const targetPks = getPrimaryKeys(targetCollection, this.registry);
+                const targetPks = requirePrimaryKeys(targetCollection, this.registry);
                 const targetIdInfo = targetPks[0];
                 const targetIdCol = targetTable[targetIdInfo.fieldName as keyof typeof targetTable] as AnyPgColumn;
                 const fkCol = targetTable[relation.foreignKeyOnTarget as keyof typeof targetTable] as AnyPgColumn;
@@ -823,7 +883,7 @@ export class RelationService {
                     continue;
                 }
 
-                const parentPks = getPrimaryKeys(collection, this.registry);
+                const parentPks = requirePrimaryKeys(collection, this.registry);
                 const parentIdInfo = parentPks[0];
                 const parsedParentIdObj = parseIdValues(id, parentPks);
                 const parsedParentId = parsedParentIdObj[parentIdInfo.fieldName];
@@ -873,9 +933,9 @@ export class RelationService {
             try {
                 const targetCollection = relation.target();
                 const targetTable = getTableForCollection(targetCollection, this.registry);
-                const targetPks = getPrimaryKeys(targetCollection, this.registry);
+                const targetPks = requirePrimaryKeys(targetCollection, this.registry);
                 const targetIdInfo = targetPks[0];
-                const sourcePks = getPrimaryKeys(sourceCollection, this.registry);
+                const sourcePks = requirePrimaryKeys(sourceCollection, this.registry);
                 const sourceIdInfo = sourcePks[0];
 
                 // Handle inverse relations with joinPath
@@ -1032,7 +1092,7 @@ export class RelationService {
                 }
 
                 // Perform the junction table update
-                const sourcePks = getPrimaryKeys(sourceCollection, this.registry);
+                const sourcePks = requirePrimaryKeys(sourceCollection, this.registry);
                 const sourceIdInfo = sourcePks[0];
                 const parsedSourceIdObj = parseIdValues(sourceEntityId, sourcePks);
                 const parsedSourceId = parsedSourceIdObj[sourceIdInfo.fieldName];
@@ -1042,7 +1102,7 @@ export class RelationService {
 
                 // Add new entries if newValue is provided
                 if (newValue && Array.isArray(newValue) && newValue.length > 0) {
-                    const targetPks = getPrimaryKeys(targetCollection, this.registry);
+                    const targetPks = requirePrimaryKeys(targetCollection, this.registry);
                     const targetIdInfo = targetPks[0];
                     const targetEntityIds = (newValue as Array<{ id: string | number } | string | number>).map((rel) => typeof rel === "object" && rel !== null ? rel.id : rel);
                     const parsedTargetIds = targetEntityIds.map(id => parseIdValues(id, targetPks)[targetIdInfo.fieldName]);
@@ -1057,7 +1117,7 @@ export class RelationService {
                     }
                 } else if (newValue && !Array.isArray(newValue)) {
                     // Single value for one-to-one
-                    const targetPks = getPrimaryKeys(targetCollection, this.registry);
+                    const targetPks = requirePrimaryKeys(targetCollection, this.registry);
                     const targetIdInfo = targetPks[0];
                     const targetId = typeof newValue === "object" && newValue !== null ? (newValue as Record<string, unknown>).id as string | number : newValue as string | number;
                     const parsedTargetIdObj = parseIdValues(targetId, targetPks);
@@ -1104,7 +1164,7 @@ export class RelationService {
                 return;
             }
 
-            const sourcePks = getPrimaryKeys(sourceCollection, this.registry);
+            const sourcePks = requirePrimaryKeys(sourceCollection, this.registry);
             const sourceIdInfo = sourcePks[0];
             const parsedSourceIdObj = parseIdValues(sourceEntityId, sourcePks);
             const parsedSourceId = parsedSourceIdObj[sourceIdInfo.fieldName];
@@ -1114,7 +1174,7 @@ export class RelationService {
 
             // Add new entries if newValue is provided
             if (newValue && Array.isArray(newValue) && newValue.length > 0) {
-                const targetPks = getPrimaryKeys(targetCollection, this.registry);
+                const targetPks = requirePrimaryKeys(targetCollection, this.registry);
                 const targetIdInfo = targetPks[0];
                 const targetEntityIds = (newValue as Array<{ id: string | number }>).map((rel) => rel.id);
                 const parsedTargetIds = targetEntityIds.map(id => parseIdValues(id, targetPks)[targetIdInfo.fieldName]);
@@ -1151,14 +1211,14 @@ export class RelationService {
             const { relation, newTargetId } = upd;
             const targetCollection = relation.target();
             const targetTable = getTableForCollection(targetCollection, this.registry);
-            const targetPks = getPrimaryKeys(targetCollection, this.registry);
+            const targetPks = requirePrimaryKeys(targetCollection, this.registry);
             const targetIdInfo = targetPks[0];
             const targetIdCol = targetTable[targetIdInfo.fieldName as keyof typeof targetTable] as AnyPgColumn;
 
             // Determine mapping of columns
             const { targetFKColName, parentSourceColName } = this.resolveJoinPathWriteMapping(parentCollection, relation);
             const parentTable = getTableForCollection(parentCollection, this.registry);
-            const parentPks = getPrimaryKeys(parentCollection, this.registry);
+            const parentPks = requirePrimaryKeys(parentCollection, this.registry);
             const parentIdInfo = parentPks[0];
             const parsedParentIdObj = parseIdValues(parentId, parentPks);
             const parsedParentId = parsedParentIdObj[parentIdInfo.fieldName];
@@ -1283,7 +1343,7 @@ parentSourceColName };
             }
 
             // Parse the new row ID to the correct type
-            const targetPks = getPrimaryKeys(targetCollection, this.registry);
+            const targetPks = requirePrimaryKeys(targetCollection, this.registry);
             const targetIdInfo = targetPks[0];
             const parsedNewEntityIdObj = parseIdValues(newEntityId, targetPks);
             const parsedNewEntityId = parsedNewEntityIdObj[targetIdInfo.fieldName];

package/src/services/collection-helpers.ts

@@ -58,10 +58,27 @@ export function getTableForCollection(collection: CollectionConfig, registry: Po
     return table;
 }
 
+/**
+ * The key columns a collection's rows are addressed by.
+ *
+ * Three tiers, in order: properties marked `isId`, the primary keys of the
+ * drizzle schema, and finally a column literally named `id`. Only the first is
+ * visible to the browser, which is why a key known only to drizzle is reported
+ * at boot — see {@link warnOnKeysTheAdminCannotResolve}.
+ *
+ * Returns `[]` when nothing resolves, rather than throwing. It used to open by
+ * resolving the table, which throws when there is none — so the `isId` tier,
+ * which needs no table at all, was unreachable for exactly the collections
+ * most likely to have no table registered. Every caller that wanted "no keys"
+ * to mean "no keys" had to spell that out in a try/catch.
+ *
+ * Callers that cannot proceed without a key must say so themselves, naming the
+ * collection: an empty array here means "this collection has no address", which
+ * is a different answer in a notification (broadcast a wildcard) than in a save
+ * (fail).
+ */
 export function getPrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): PrimaryKeyInfo[] {
-    const table = getTableForCollection(collection, registry);
-
-    // Fallback to explicitly defined isId properties
+    // Explicitly declared `isId` properties win, and need no table.
     if (collection.properties) {
         const idProps = Object.entries(collection.properties)
             .filter(([_, prop]) => "isId" in (prop as object) && Boolean((prop as { isId?: unknown }).isId))
@@ -76,6 +93,12 @@ export function getPrimaryKeys(collection: CollectionConfig, registry: PostgresC
         }
     }
 
+    // The remaining tiers read the drizzle schema, so they need the table. A
+    // collection without one — another engine's, or simply unregistered — has
+    // nothing more to offer.
+    const table = registry.getTable(getTableName(collection));
+    if (!table) return [];
+
     // Otherwise infer from Drizzle schema
     const keys: PrimaryKeyInfo[] = [];
     for (const [key, colRaw] of Object.entries(table)) {
@@ -105,6 +128,27 @@ isUUID });
     return keys;
 }
 
+/**
+ * The key columns, for callers that cannot do their job without one.
+ *
+ * {@link getPrimaryKeys} answers "what keys, if any" and returns `[]` for a
+ * collection with no address. Most of this driver, though, is building a WHERE
+ * clause and has no meaning without a key — for those, an empty array is not an
+ * answer, and indexing `[0]` into it produces `Cannot read properties of
+ * undefined` three frames from where the real problem is. This says what is
+ * wrong and which collection it is wrong about.
+ */
+export function requirePrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): PrimaryKeyInfo[] {
+    const keys = getPrimaryKeys(collection, registry);
+    if (keys.length === 0) {
+        throw new Error(
+            `Collection '${collection.slug}' has no primary key, so its rows cannot be addressed. ` +
+            `Mark the key property with \`isId\` in its config, or register a table whose schema declares one.`
+        );
+    }
+    return keys;
+}
+
 /**
  * Collections whose key the *browser* cannot resolve, and what it will do
  * instead.
@@ -138,14 +182,9 @@ export function findUnresolvableKeyCollections(
         // Declared `isId` is the tier both sides share: if it is there, they agree.
         if (getDeclaredPrimaryKeys(collection).length > 0) continue;
 
-        let keys: PrimaryKeyInfo[];
-        try {
-            keys = getPrimaryKeys(collection, registry);
-        } catch {
-            // No registered table — nothing resolved here either, so there is no
-            // disagreement to report.
-            continue;
-        }
+        // No registered table resolves to no keys, and a collection this cannot
+        // resolve a key for is one it has nothing to say about.
+        const keys = getPrimaryKeys(collection, registry);
         if (keys.length === 0) continue;
 
         // A single key named `id` is the last tier on both sides: they agree
@@ -207,28 +246,21 @@ export function warnOnKeysTheAdminCannotResolve(
  * The address of a row: derived from the collection's primary keys, because a
  * row does not carry one — it is exactly its columns.
  *
- * Falls back to a literal `id` column, which covers the two cases where the
- * keys cannot be resolved: a row that reached us from somewhere other than the
- * postgres driver, and a collection whose table the registry cannot look up
- * (`getPrimaryKeys` throws for an unregistered table rather than returning
- * nothing). Returns `""` when there is no key and no `id` — callers decide what
- * that means, since "unaddressable" is a different answer in a notification
- * (broadcast a wildcard) than in a save (fail).
+ * Falls back to a literal `id` column, for a row that reached us from somewhere
+ * other than this driver. Returns `""` when there is no key and no `id` —
+ * callers decide what that means, since "unaddressable" is a different answer
+ * in a notification (broadcast a wildcard) than in a save (fail).
  */
 export function deriveRowAddress(
     row: Record<string, unknown>,
     collection: CollectionConfig,
     registry: PostgresCollectionRegistry
 ): string {
-    try {
-        const composite = buildCompositeId(row, getPrimaryKeys(collection, registry));
-        // An all-empty composite is indistinguishable from a missing key, and
-        // `buildCompositeId` returns "" for no keys at all.
-        if (composite && composite.split(COMPOSITE_ID_SEPARATOR).some(part => part !== "")) {
-            return composite;
-        }
-    } catch {
-        /* unresolvable table or keys — fall through to the literal column */
+    const composite = buildCompositeId(row, getPrimaryKeys(collection, registry));
+    // An all-empty composite is indistinguishable from a missing key, and
+    // `buildCompositeId` returns "" for no keys at all.
+    if (composite && composite.split(COMPOSITE_ID_SEPARATOR).some(part => part !== "")) {
+        return composite;
     }
     if (row.id !== undefined && row.id !== null) return String(row.id);
     return "";

package/src/services/realtimeService.ts

@@ -963,8 +963,10 @@ roles: activeAuth.roles },
             const keys = getPrimaryKeys(collection, this.registry);
             return keys.length > 0 ? keys : undefined;
         } catch {
-            // Unregistered table, or a relation path with no collection of its
-            // own: the client keeps its pre-existing `id` behaviour.
+            // `getCollectionByPath` throws on a path it cannot walk — and this
+            // is called for parent paths too, which include entity paths like
+            // `posts/1` that name no collection. Telling the subscriber nothing
+            // is right here; letting it throw would drop the notification.
             return undefined;
         }
     }