@rebasepro/server-postgres 0.12.1-canary.g4e7bcbf → 0.12.1-canary.g52d71ee

package/src/services/RelationService.ts

@@ -1,7 +1,7 @@
 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, ResolvedRelation, ResolvedManyToMany } from "@rebasepro/types";
+import { CollectionConfig, FilterValues, ResolvedRelation, ResolvedManyToMany, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { getTableName, resolveCollectionRelations, findRelation } from "@rebasepro/common";
 import { hasForeignKeyOnTarget, isManyToMany, type ResolvedVia } from "@rebasepro/types";
 import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
@@ -11,6 +11,8 @@ import {
     requirePrimaryKeys,
     parseIdValues,
     buildCompositeId,
+    joinsOnNaturalKey,
+    sourceKeyField,
     type PrimaryKeyInfo
 } from "./collection-helpers";
 import { parseDataFromServer } from "../data-transformer";
@@ -168,18 +170,122 @@ export class RelationService {
     private assertSingleKeyAddressable(
         parentCollection: CollectionConfig,
         parentPks: PrimaryKeyInfo[],
-        via: string
+        via: string,
+        relation?: ResolvedRelation
     ): void {
+        // A `sourceKey` names the single column the link actually points at, so
+        // the parent's key can be as wide as it likes — nothing here references
+        // it. That is the one way out of this error, and the message below now
+        // has to say so.
+        if (relation && hasForeignKeyOnTarget(relation) && relation.sourceKey) return;
+
         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 ` +
+                `One column cannot reference a composite key — give the relation a \`sourceKey\` naming ` +
+                `a single unique column to point at, or express it with \`joinPath\`, whose ` +
                 `\`on.from\`/\`on.to\` take every key column.`
             );
         }
     }
 
+    /**
+     * What the target's foreign key holds, for each of these parent rows.
+     *
+     * Ordinarily the parent's id, and then this is free. When the relation
+     * declares a `sourceKey` the two are different values, and the mapping
+     * between them lives in the source table — so it costs one SELECT, issued
+     * once for the whole batch rather than per parent.
+     *
+     * Both directions come back because both are needed and deriving one from
+     * the other by hand is how a batch loader ends up attributing a child to the
+     * wrong parent: reads translate id → key to build the WHERE, and then
+     * translate key → id to attribute each row that comes back.
+     */
+    /**
+     * The value a related row's foreign key must hold to belong to this parent.
+     *
+     * `undefined` when the parent's source key is null — which is not an error
+     * here, only in the callers that were about to write it. Exposed for
+     * {@link PersistService}, which stamps this onto a child created under a
+     * nested path and would otherwise write the id and lose the row.
+     */
+    async parentKeyValue(
+        parentCollection: CollectionConfig,
+        relation: ResolvedHasOne | ResolvedHasMany,
+        parentId: string | number,
+        db: DrizzleClient = this.db
+    ): Promise<string | number | undefined> {
+        const { keyByParentId } = await this.resolveSourceKeys(parentCollection, relation, [parentId], db);
+        return keyByParentId.get(String(parentId));
+    }
+
+    private async resolveSourceKeys(
+        parentCollection: CollectionConfig,
+        relation: ResolvedHasOne | ResolvedHasMany,
+        parentIds: (string | number)[],
+        // Writes pass their transaction: reading the source key on the pool
+        // while the same transaction is holding an uncommitted change to it
+        // would translate the id against a stale value.
+        db: DrizzleClient = this.db
+    ): Promise<{ keyByParentId: Map<string, string | number>; parentIdByKey: Map<string, string | number> }> {
+        const keyByParentId = new Map<string, string | number>();
+        const parentIdByKey = new Map<string, string | number>();
+
+        const parentPks = requirePrimaryKeys(parentCollection, this.registry);
+
+        if (!joinsOnNaturalKey(relation, parentCollection, this.registry)) {
+            // The ordinary case, and it must stay free of a round-trip: the
+            // key IS the id. Parsed, not passed through — an id arrives as the
+            // string from a URL, and comparing "7" against an integer column is
+            // how this returns nothing at all.
+            for (const id of parentIds) {
+                const value = parseIdValues(id, parentPks)[parentPks[0].fieldName];
+                keyByParentId.set(String(id), value);
+                parentIdByKey.set(String(value), id);
+            }
+            return { keyByParentId, parentIdByKey };
+        }
+
+        const field = sourceKeyField(relation, parentCollection, this.registry);
+        const parentTable = getTableForCollection(parentCollection, this.registry);
+        const keyColumn = parentTable[field as keyof typeof parentTable] as AnyPgColumn;
+        if (!keyColumn) {
+            throw new Error(
+                `\`sourceKey: "${field}"\` on relation '${relation.relationName}' is not a column on ` +
+                `'${parentCollection.slug}'. It names a column on the source table, not on the target.`
+            );
+        }
+
+        const rows = await db
+            .select()
+            .from(parentTable)
+            .where(this.parentKeyCondition(parentTable, parentPks, parentIds));
+
+        for (const row of rows as Array<Record<string, unknown>>) {
+            const keyValue = row[field] as string | number | null;
+            if (keyValue === null || keyValue === undefined) continue;
+            const parentId = buildCompositeId(row, parentPks);
+            keyByParentId.set(String(parentId), keyValue);
+            // A duplicate here means the source key is not unique, which makes
+            // "which parent does this child belong to" unanswerable. Refuse
+            // rather than pick the last one seen.
+            const existing = parentIdByKey.get(String(keyValue));
+            if (existing !== undefined && String(existing) !== String(parentId)) {
+                throw new Error(
+                    `\`sourceKey: "${field}"\` on relation '${relation.relationName}' is not unique on ` +
+                    `'${parentCollection.slug}': rows '${existing}' and '${parentId}' both hold ` +
+                    `'${keyValue}'. Add a unique constraint — a link that addresses more than one source ` +
+                    `row cannot say which one a related row belongs to.`
+                );
+            }
+            parentIdByKey.set(String(keyValue), parentId);
+        }
+
+        return { keyByParentId, parentIdByKey };
+    }
+
     /**
      * Fetch rows related to a parent row through a specific relation
      */
@@ -292,7 +398,21 @@ export class RelationService {
             return rows;
         }
 
-        // Handle other relation types
+        // Handle other relation types.
+        //
+        // The query builder compares the target's foreign key against a value,
+        // and for a link on a natural key that value is not the id in the URL.
+        // Resolved first, before anything is built, so a parent that reaches
+        // nothing costs one statement rather than two.
+        const matchValue = hasForeignKeyOnTarget(relation)
+            ? (await this.resolveSourceKeys(parentCollection, relation, [parentId]))
+                .keyByParentId.get(String(parentId))
+            : parsedParentId;
+
+        // A parent whose source key is null reaches nothing: NULL never equals
+        // a foreign key. Say so with an empty list rather than an `= NULL`.
+        if (matchValue === undefined) return [];
+
         let query = this.db.select().from(targetTable).$dynamic();
 
         // Build additional filter conditions
@@ -322,7 +442,7 @@ export class RelationService {
             query,
             query,
             relation,
-            parsedParentId,
+            matchValue,
             targetTable,
             parentTable,
             parentIdCol,
@@ -400,6 +520,16 @@ export class RelationService {
         if (!parentTable) throw new Error("Parent table not found");
         const parentIdCol = parentTable[parentIdInfo.fieldName as keyof typeof parentTable] as AnyPgColumn;
 
+        // Same translation the listing does, and it has to be: `isRelated`
+        // gates writes on this count, so a count built from a different value
+        // than the read would authorise rows the read never returned.
+        const matchValue = hasForeignKeyOnTarget(relation)
+            ? (await this.resolveSourceKeys(parentCollection, relation, [parentId]))
+                .keyByParentId.get(String(parentId))
+            : parsedParentId;
+
+        if (matchValue === undefined) return 0;
+
         // Start count with distinct to avoid duplicates from junction tables
         let query = this.db.select({ count: sql<number>`count(distinct ${targetIdField})` }).from(targetTable).$dynamic();
 
@@ -407,7 +537,7 @@ export class RelationService {
         query = DrizzleConditionBuilder.buildRelationCountQuery(
             query,
             relation,
-            parsedParentId,
+            matchValue,
             targetTable,
             parentTable,
             parentIdCol,
@@ -640,8 +770,22 @@ export class RelationService {
         this.assertSingleKeyAddressable(
             parentCollection,
             parentPks,
-            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName
+            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName,
+            relation
         );
+
+        // One lookup for the whole batch, both directions: the WHERE is built
+        // from the source-key values, and each row that comes back carries one
+        // of those values rather than a parent id.
+        const { keyByParentId, parentIdByKey } = hasForeignKeyOnTarget(relation)
+            ? await this.resolveSourceKeys(parentCollection, relation, parentIds)
+            : { keyByParentId: new Map<string, string | number>(), parentIdByKey: new Map<string, string | number>() };
+
+        const matchValues = hasForeignKeyOnTarget(relation)
+            ? [...keyByParentId.values()]
+            : parsedParentIds;
+        if (matchValues.length === 0) return new Map();
+
         let query = this.db.select().from(targetTable).$dynamic();
 
         // Build the relation query with ALL parent IDs
@@ -649,7 +793,7 @@ export class RelationService {
             query,
             query,
             relation,
-            parsedParentIds, // Pass array instead of single ID
+            matchValues, // Pass array instead of single ID
             targetTable,
             parentTable,
             parentIdCol,
@@ -661,28 +805,24 @@ export class RelationService {
         const results = await query;
         const resultMap = new Map<string, RelatedRow<Record<string, unknown>>>();
 
-        // Build a Set<string> for O(1) parent-ID lookups that is immune to
-        // number-vs-string type mismatches (Drizzle may return either depending
-        // on the column type and driver).
-        const parentIdSet = new Set(parsedParentIds.map(String));
-
         // Map results back to parent rows
         for (const row of results as Array<Record<string, unknown>>) {
             const targetRow = (row[getTableName(targetCollection)] || row) as Record<string, unknown>;
 
-            // Determine the parent ID this result belongs to based on the relation type
-            let parentId: string | number | undefined;
-
             // The parent's key is on the target row, in the relation's own
             // column. There used to be a second branch here that guessed the
             // column by appending `_id` to `inverseRelationName`, reached only
             // when the foreign key had not been resolved — which cannot happen
             // now that resolution fills it in.
-            if (hasForeignKeyOnTarget(relation)) {
-                parentId = targetRow[relation.foreignKeyOnTarget] as string | number | undefined;
-            }
+            if (!hasForeignKeyOnTarget(relation)) continue;
+
+            // Keyed by string throughout: Drizzle returns a numeric column as a
+            // number or a string depending on the column type and the driver.
+            const foreignKeyValue = targetRow[relation.foreignKeyOnTarget] as string | number | undefined;
+            if (foreignKeyValue === undefined || foreignKeyValue === null) continue;
 
-            if (parentId !== undefined && parentIdSet.has(String(parentId))) {
+            const parentId = parentIdByKey.get(String(foreignKeyValue));
+            if (parentId !== undefined) {
                 resultMap.set(String(parentId), await this.toRelatedRow(targetRow, targetCollection, targetPks));
             }
         }
@@ -811,15 +951,26 @@ export class RelationService {
         this.assertSingleKeyAddressable(
             parentCollection,
             parentPks,
-            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName
+            hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName,
+            relation
         );
+
+        const { keyByParentId, parentIdByKey } = hasForeignKeyOnTarget(relation)
+            ? await this.resolveSourceKeys(parentCollection, relation, parentIds)
+            : { keyByParentId: new Map<string, string | number>(), parentIdByKey: new Map<string, string | number>() };
+
+        const matchValues = hasForeignKeyOnTarget(relation)
+            ? [...keyByParentId.values()]
+            : parsedParentIds;
+        if (matchValues.length === 0) return new Map();
+
         let query = this.db.select().from(targetTable).$dynamic();
 
         query = applyDynamicRelationQuery(
             query,
             query,
             relation,
-            parsedParentIds,
+            matchValues,
             targetTable,
             parentTable,
             parentIdCol,
@@ -831,23 +982,18 @@ export class RelationService {
         const results = await query;
         const resultMap = new Map<string, RelatedRow<Record<string, unknown>>[]>();
 
-        // Build a Set<string> for O(1) parent-ID lookups that is immune to
-        // number-vs-string type mismatches (Drizzle may return either depending
-        // on the column type and driver).
-        const parentIdSet = new Set(parsedParentIds.map(String));
-
         for (const row of results as Array<Record<string, unknown>>) {
             const targetRow = (row[getTableName(targetCollection)] || row) as Record<string, unknown>;
 
-            let parentId: string | number | undefined;
-
             // Junction-backed relations returned earlier in this method, so
             // what reaches here names the parent with a column on the target.
-            if (hasForeignKeyOnTarget(relation)) {
-                parentId = targetRow[relation.foreignKeyOnTarget] as string | number | undefined;
-            }
+            if (!hasForeignKeyOnTarget(relation)) continue;
+
+            const foreignKeyValue = targetRow[relation.foreignKeyOnTarget] as string | number | undefined;
+            if (foreignKeyValue === undefined || foreignKeyValue === null) continue;
 
-            if (parentId !== undefined && parentIdSet.has(String(parentId))) {
+            const parentId = parentIdByKey.get(String(foreignKeyValue));
+            if (parentId !== undefined) {
                 const key = String(parentId);
                 const arr = resultMap.get(key) || [];
                 arr.push(await this.toRelatedRow(targetRow, targetCollection, targetPks));
@@ -994,10 +1140,19 @@ export class RelationService {
                     continue;
                 }
 
-                const parentPks = requirePrimaryKeys(collection, this.registry);
-                const parentIdInfo = parentPks[0];
-                const parsedParentIdObj = parseIdValues(id, parentPks);
-                const parsedParentId = parsedParentIdObj[parentIdInfo.fieldName];
+                // What the children's foreign key must hold — the parent's id
+                // unless the link declares a `sourceKey`, and then the value of
+                // that column on this parent row.
+                const parentKeyValue = (await this.resolveSourceKeys(collection, relation, [id], tx))
+                    .keyByParentId.get(String(id));
+
+                if (parentKeyValue === undefined) {
+                    throw new Error(
+                        `Cannot write relation '${key}' on '${collection.slug}': row '${id}' has no value in ` +
+                        `\`sourceKey: "${sourceKeyField(relation, collection, this.registry)}"\`, so there is ` +
+                        "nothing for the related rows to point at."
+                    );
+                }
 
                 // Clear existing links not in the new set
                 if (targetEntityIds.length > 0) {
@@ -1005,19 +1160,19 @@ export class RelationService {
                     await tx
                         .update(targetTable)
                         .set({ [relation.foreignKeyOnTarget]: null })
-                        .where(and(eq(fkCol, parsedParentId), sql`${targetIdCol} NOT IN (${sql.join(parsedTargetIds)})`));
+                        .where(and(eq(fkCol, parentKeyValue), sql`${targetIdCol} NOT IN (${sql.join(parsedTargetIds)})`));
 
                     // Set FK for the provided targets
                     await tx
                         .update(targetTable)
-                        .set({ [relation.foreignKeyOnTarget]: parsedParentId })
+                        .set({ [relation.foreignKeyOnTarget]: parentKeyValue })
                         .where(inArray(targetIdCol as AnyPgColumn, parsedTargetIds as unknown[]));
                 } else {
                     // If empty array provided, clear all existing links for this parent
                     await tx
                         .update(targetTable)
                         .set({ [relation.foreignKeyOnTarget]: null })
-                        .where(eq(fkCol, parsedParentId));
+                        .where(eq(fkCol, parentKeyValue));
                 }
             } else {
                 logger.warn(`Many relation '${key}' in collection '${collection.slug}' lacks write configuration and will be skipped during save.`);
@@ -1095,14 +1250,25 @@ export class RelationService {
                     continue;
                 }
 
-                const parsedSourceIdObj = parseIdValues(sourceEntityId, sourcePks);
-                const parsedSourceId = parsedSourceIdObj[sourceIdInfo.fieldName];
+                // The value the target's foreign key holds: this row's id, or
+                // the column named by `sourceKey` when the link joins on one.
+                const sourceKeyValue = (await this.resolveSourceKeys(sourceCollection, relation, [sourceEntityId], tx))
+                    .keyByParentId.get(String(sourceEntityId));
+
+                if (sourceKeyValue === undefined) {
+                    throw new Error(
+                        `Cannot write relation '${relation.relationName}' on '${sourceCollection.slug}': row ` +
+                        `'${sourceEntityId}' has no value in \`sourceKey: ` +
+                        `"${sourceKeyField(relation, sourceCollection, this.registry)}"\`, so there is nothing ` +
+                        "for the related row to point at."
+                    );
+                }
 
                 if (newValue === null || newValue === undefined) {
                     await tx
                         .update(targetTable)
                         .set({ [relation.foreignKeyOnTarget!]: null })
-                        .where(eq(foreignKeyColumn, parsedSourceId));
+                        .where(eq(foreignKeyColumn, sourceKeyValue));
                 } else {
                     const parsedNewTargetIdObj = parseIdValues(newValue as string | number, targetPks);
                     const parsedNewTargetId = parsedNewTargetIdObj[targetIdInfo.fieldName];
@@ -1112,12 +1278,12 @@ export class RelationService {
                     await tx
                         .update(targetTable)
                         .set({ [relation.foreignKeyOnTarget!]: null })
-                        .where(eq(foreignKeyColumn, parsedSourceId));
+                        .where(eq(foreignKeyColumn, sourceKeyValue));
 
                     // Then, update the new target row to point to this source row
                     await tx
                         .update(targetTable)
-                        .set({ [relation.foreignKeyOnTarget!]: parsedSourceId })
+                        .set({ [relation.foreignKeyOnTarget!]: sourceKeyValue })
                         .where(eq(targetIdField, parsedNewTargetId));
                 }
             } catch (e) {

package/src/services/channel-bus/index.ts

@@ -80,15 +80,6 @@ export function resolveChannelBusSetting(configured?: ChannelBusSetting): Channe
     return raw === "memory" ? { type: "memory" } : { type: "postgres" };
 }
 
-/**
- * @deprecated Use {@link resolveChannelBusSetting}, which also accepts a
- * supplied {@link ChannelBus} instance. Kept as a narrow alias so existing
- * config-only callers keep their exact types.
- */
-export function resolveChannelBusConfig(configured?: ChannelBusConfig): ChannelBusConfig {
-    return resolveChannelBusSetting(configured) as ChannelBusConfig;
-}
-
 /**
  * Produce the bus a setting asks for.
  *

package/src/services/collection-helpers.ts

@@ -1,5 +1,5 @@
 import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
-import { CollectionConfig, Property } from "@rebasepro/types";
+import { CollectionConfig, Property, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { getTableName } from "@rebasepro/common";
 import { logger } from "@rebasepro/server";
@@ -7,9 +7,9 @@ import { logger } from "@rebasepro/server";
 // Row identity is derived on both sides of the wire — the driver parses an
 // incoming address into key columns, the admin derives one from a served row —
 // so the implementation lives in `common` and both agree by construction.
-export { buildCompositeId, parseIdValues, COMPOSITE_ID_SEPARATOR } from "@rebasepro/common";
+export { buildCompositeId, parseIdValues, isAddressableId, COMPOSITE_ID_SEPARATOR } from "@rebasepro/common";
 export type { PrimaryKeyInfo } from "@rebasepro/common";
-import { buildCompositeId, COMPOSITE_ID_SEPARATOR, getDeclaredPrimaryKeys } from "@rebasepro/common";
+import { buildCompositeId, COMPOSITE_ID_SEPARATOR, getDeclaredPrimaryKeys, isAddressableId } from "@rebasepro/common";
 import type { PrimaryKeyInfo } from "@rebasepro/common";
 
 /**
@@ -40,6 +40,33 @@ export function getColumnMeta(col: AnyPgColumn): DrizzleColumnMeta {
     };
 }
 
+/**
+ * Whether an address could name a row in this table, judged by the columns.
+ *
+ * {@link getPrimaryKeys} lets a config's `isId: "uuid"` win over the schema, so
+ * its `isUUID` is a claim rather than a fact — right for deriving addresses,
+ * wrong for refusing a query. Here the Drizzle column type decides, because it
+ * is what Postgres will enforce: a `uuid` column meets `/c/products/new` with
+ * `22P02`, which aborts the surrounding transaction and turns every later
+ * statement into an unrelated-looking `25P02`.
+ */
+export function idCanAddressTable(
+    id: string | number,
+    table: PgTable,
+    idInfoArray: PrimaryKeyInfo[]
+): boolean {
+    const columnBacked = idInfoArray.map(info => {
+        const col = table[info.fieldName as keyof typeof table] as AnyPgColumn | undefined;
+        const meta = col ? getColumnMeta(col) : undefined;
+        // No column to ask (a key the schema does not carry) leaves the id
+        // addressable: refusing on a guess would 404 rows that do exist.
+        if (!meta?.columnType) return info;
+        return { ...info,
+            isUUID: meta.columnType === "PgUUID" };
+    });
+    return isAddressableId(id, columnBacked);
+}
+
 export function getCollectionByPath(collectionPath: string, registry: PostgresCollectionRegistry): CollectionConfig {
     const collection = registry.getCollectionByPath(collectionPath);
     if (!collection) {
@@ -149,6 +176,45 @@ export function requirePrimaryKeys(collection: CollectionConfig, registry: Postg
     return keys;
 }
 
+/**
+ * The column on the *source* table that a `hasOne`/`hasMany` link points at.
+ *
+ * `sourceKey` is authored when the two sides join on a natural key — an
+ * external identity id, a SKU — and left off when they join on the row id,
+ * which is the overwhelming majority. That makes `undefined` the only optional
+ * field on a resolved relation, so it gets exactly one reader: this function.
+ * Every consumer that needs the column asks here, and none of them re-derives
+ * "or else the primary key" for itself. That is the whole point — the fallback
+ * chains this codebase removed from relation resolution were dangerous because
+ * they were *duplicated* and could disagree, not because they existed.
+ */
+export function sourceKeyField(
+    relation: ResolvedHasOne | ResolvedHasMany,
+    sourceCollection: CollectionConfig,
+    registry: PostgresCollectionRegistry
+): string {
+    if (relation.sourceKey) return relation.sourceKey;
+    return requirePrimaryKeys(sourceCollection, registry)[0].fieldName;
+}
+
+/**
+ * Whether this link joins on something other than the source's primary key.
+ *
+ * Callers that hold a parent *id* — which is most of them, since an id is what
+ * a URL carries — must translate it to the source key's value before it can be
+ * compared with the target's foreign key. Those that hold the parent *row*, or
+ * that build a correlated subquery over the source table, can read the column
+ * directly and skip the lookup.
+ */
+export function joinsOnNaturalKey(
+    relation: ResolvedHasOne | ResolvedHasMany,
+    sourceCollection: CollectionConfig,
+    registry: PostgresCollectionRegistry
+): boolean {
+    if (!relation.sourceKey) return false;
+    return relation.sourceKey !== requirePrimaryKeys(sourceCollection, registry)[0].fieldName;
+}
+
 /**
  * Collections whose key the *browser* cannot resolve, and what it will do
  * instead.

package/src/utils/connection-string.ts

@@ -0,0 +1,58 @@
+/**
+ * Connection-string rewrites for the tools Rebase shells out to.
+ *
+ * Pure and dependency-free: `pg-tools` builds argument vectors without a live
+ * server, and these have to be usable from there.
+ */
+
+/**
+ * The `sslmode` values libpq accepts. `no-verify` is conspicuously not one.
+ */
+const LIBPQ_SSLMODES = new Set(["disable", "allow", "prefer", "require", "verify-ca", "verify-full"]);
+
+/**
+ * Make a connection string safe to hand to a libpq program.
+ *
+ * `sslmode=no-verify` is a node-postgres convention — encrypt, but do not check
+ * the certificate — and libpq does not have it. It does not degrade or warn:
+ *
+ *     psql: error: invalid sslmode value: "no-verify"
+ *
+ * which means a `DATABASE_URL` that works perfectly for the app makes `psql`,
+ * `pg_dump`, `pg_restore` and Atlas all refuse to start, with an error that
+ * points at the value rather than at the convention it comes from. It has cost
+ * this project time more than once.
+ *
+ * `require` is the honest translation: libpq's `require` encrypts and does not
+ * verify the certificate either, which is exactly what `no-verify` asks for.
+ * Nothing is relaxed by the rewrite — `verify-ca` and `verify-full` are left
+ * alone, so a connection string that asked for verification still gets it.
+ *
+ * Only `sslmode` is touched, and only when it is a value libpq would reject.
+ * Anything unparseable is returned as given: a connection that works
+ * unverified beats one this corrupted.
+ */
+export function forLibpq(connectionString: string): string {
+    let url: URL;
+    try {
+        url = new URL(connectionString);
+    } catch {
+        // Key/value DSNs and anything else we cannot parse. A `sslmode` in one
+        // of those is space-separated rather than a query parameter, and
+        // rewriting it with a regex is how a password containing "sslmode="
+        // gets mangled.
+        return connectionString;
+    }
+    if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") return connectionString;
+
+    const sslmode = url.searchParams.get("sslmode");
+    if (sslmode === null || LIBPQ_SSLMODES.has(sslmode)) return connectionString;
+
+    url.searchParams.set("sslmode", "require");
+    // Re-serialize by hand for the reason `pinSearchPath` does: URLSearchParams
+    // writes a space as `+`, which node-postgres decodes and libpq does not.
+    url.search = Array.from(url.searchParams.entries())
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+        .join("&");
+    return url.toString();
+}

package/src/utils/drizzle-conditions.ts

@@ -175,10 +175,11 @@ export class DrizzleConditionBuilder {
     static buildRelationScopeCondition(
         relation: ResolvedRelation,
         /**
-         * Lazy: only `via` and `belongsTo` need the parent's own table. A
-         * foreign key on the target and a junction are both expressible from
-         * the parent's *id* alone, and requiring the table for them would make
-         * a child listing fail on a parent whose table isn't registered.
+         * Lazy: `via`, `belongsTo`, and a foreign key that points at a
+         * `sourceKey` need the parent's own table. A junction and a plain
+         * foreign key are expressible from the parent's *id* alone, and
+         * requiring the table for them would make a child listing fail on a
+         * parent whose table isn't registered.
          */
         parent: () => { table: PgTable<any>; idColumn: AnyPgColumn },
         parentId: string | number,
@@ -239,7 +240,16 @@ export class DrizzleConditionBuilder {
                         `relation '${relation.relationName}'.`
                     );
                 }
-                return eq(fkColumn, parentId);
+                if (!relation.sourceKey) return eq(fkColumn, parentId);
+
+                // A link on a natural key: the foreign key holds a column of the
+                // parent row, not its id, so the parent has to be read. As a
+                // subquery rather than a prior SELECT, for the same reason
+                // `belongsTo` below is — one statement sees one snapshot, and a
+                // scope condition that read the key separately could be built
+                // from a value the very next statement no longer agrees with.
+                const { table, idColumn } = parent();
+                return sql`${fkColumn} = (SELECT ${sql.identifier(relation.sourceKey)} FROM ${table} WHERE ${idColumn} = ${parentId})`;
             }
 
             case "belongsTo": {
@@ -385,7 +395,22 @@ export class DrizzleConditionBuilder {
             // 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 };
+                // The `EXISTS` correlates the target's foreign key with a column
+                // on *this* table, and that is the primary key only when the
+                // link joins on it. A `sourceKey` names a different one, and
+                // correlating on the id anyway silently matches nothing —
+                // "filter by this relation" would quietly return zero rows.
+                const correlationColumn = hasForeignKeyOnTarget(relation) && relation.sourceKey
+                    ? columnAt(relation.sourceKey)
+                    : sourceIdColumn;
+                if (!correlationColumn) {
+                    throw new Error(
+                        `\`sourceKey: "${(relation as ResolvedForeignKeyOnTarget).sourceKey}"\` on relation ` +
+                        `'${relation.relationName}' is not a column on '${collectionPath}', so a filter on ` +
+                        "that relation has nothing to correlate against."
+                    );
+                }
+                return { kind: "relation", relation, registry, sourceIdColumn: correlationColumn };
             }
         }