@rebasepro/server-postgres 0.12.1-canary.gf5f1d39 → 0.13.1-canary.g18cfeb7

package/src/services/BranchService.ts

@@ -9,6 +9,7 @@
 
 import { sql } from "drizzle-orm";
 import { BranchInfo } from "@rebasepro/types";
+import { revokeInternalTableSql } from "@rebasepro/common";
 import { DrizzleClient } from "../interfaces";
 import { DatabasePoolManager } from "../databasePoolManager";
 import { extractPgError, extractCauseMessage } from "../utils/pg-error-utils";
@@ -64,20 +65,41 @@ function validateIdentifier(value: string, label: string): void {
 }
 
 /**
- * Sanitize a user-provided branch name to a safe PostgreSQL identifier.
- * Only allows alphanumeric characters and underscores.
+ * Postgres truncates identifiers at NAMEDATALEN-1 = 63 bytes, and does it
+ * silently. The prefix comes out of the same budget.
  */
-function sanitizeBranchName(name: string): string {
-    return name.replace(/[^a-zA-Z0-9_]/g, "");
+const MAX_BRANCH_NAME_LENGTH = 63 - BRANCH_DB_PREFIX.length;
+
+/**
+ * Check a user-provided branch name, and otherwise leave it exactly as given.
+ *
+ * This used to strip everything outside [a-zA-Z0-9_], so `my-feature` was
+ * quietly created as `myfeature`: the name you typed was not the name `list`
+ * gave back. Nothing ever needed that. Every identifier this service builds is
+ * double-quoted (see `CREATE DATABASE` below), which is what makes a hyphen
+ * safe, and `validateIdentifier` has always accepted hyphens for the `--from`
+ * source database — the two disagreed about the same character class.
+ *
+ * Refusing a name we cannot represent is better than representing a different
+ * one, which is also why the length is checked here rather than left to
+ * Postgres, whose answer to an over-long identifier is a silent rename.
+ */
+function assertValidBranchName(name: string): void {
+    validateIdentifier(name, "branch name");
+    if (name.length > MAX_BRANCH_NAME_LENGTH) {
+        throw new Error(
+            `Branch name "${name}" is too long: ${name.length} characters, maximum ${MAX_BRANCH_NAME_LENGTH}. ` +
+            "Postgres truncates identifiers past 63 bytes, which would give the branch a name you did not choose."
+        );
+    }
 }
 
 /**
  * Convert a user-facing branch name to the actual PostgreSQL database name.
  */
 function toBranchDbName(name: string): string {
-    const sanitized = sanitizeBranchName(name);
-    if (!sanitized) throw new Error("Branch name must contain at least one alphanumeric character.");
-    return `${BRANCH_DB_PREFIX}${sanitized}`;
+    assertValidBranchName(name);
+    return `${BRANCH_DB_PREFIX}${name}`;
 }
 
 export class BranchService {
@@ -103,6 +125,10 @@ export class BranchService {
                 metadata     JSONB DEFAULT '{}'
             );
         `));
+
+        // Not a collection, so no RLS — and it names every branch database on
+        // this server. The driver's schema-wide grant reaches it, so revoke.
+        await this.db.execute(sql.raw(revokeInternalTableSql("rebase", "branches")));
     }
 
     /**
@@ -120,15 +146,14 @@ export class BranchService {
         }
 
         const dbName = toBranchDbName(name);
-        const sanitizedName = sanitizeBranchName(name);
         const sourceDb = options?.source || this.poolManager.defaultDatabaseName;
 
         // Check if branch already exists
         const existing = await this.db.execute(
-            sql`SELECT name FROM rebase.branches WHERE name = ${sanitizedName} OR db_name = ${dbName}`
+            sql`SELECT name FROM rebase.branches WHERE name = ${name} OR db_name = ${dbName}`
         );
         if ((existing.rows as unknown[]).length > 0) {
-            throw new Error(`Branch "${sanitizedName}" already exists.`);
+            throw new Error(`Branch "${name}" already exists.`);
         }
 
         // Disconnect any idle pools to the source DB so TEMPLATE works.
@@ -158,12 +183,12 @@ export class BranchService {
         // Record metadata in the default database
         const now = new Date();
         await this.db.execute(
-            sql`INSERT INTO rebase.branches (name, db_name, parent_db, created_at) 
-                VALUES (${sanitizedName}, ${dbName}, ${sourceDb}, ${now.toISOString()})`
+            sql`INSERT INTO rebase.branches (name, db_name, parent_db, created_at)
+                VALUES (${name}, ${dbName}, ${sourceDb}, ${now.toISOString()})`
         );
 
         return {
-            name: sanitizedName,
+            name,
             parentDatabase: sourceDb,
             createdAt: now
         };
@@ -174,20 +199,35 @@ export class BranchService {
      * Cannot delete the main/default database.
      */
     async deleteBranch(name: string): Promise<void> {
-        const sanitizedName = sanitizeBranchName(name);
-        const dbName = toBranchDbName(name);
+        assertValidBranchName(name);
 
-        // Safety: never delete the default database
-        if (dbName === this.poolManager.defaultDatabaseName) {
+        // Safety, first pass: a request that would target the default database
+        // is refused before any metadata is read, so the answer costs nothing
+        // and cannot depend on what a row happens to say.
+        if (toBranchDbName(name) === this.poolManager.defaultDatabaseName) {
             throw new Error("Cannot delete the main database.");
         }
 
-        // Verify the branch exists in our metadata
+        // Verify the branch exists, and take the database name from the row
+        // rather than deriving it again. A branch created before names stopped
+        // being stripped is recorded as `rb_myfeature` while `my-feature` now
+        // derives `rb_my-feature`; re-deriving would drop a database this row
+        // never named — or, if that name happened to exist, somebody else's.
+        // The stored value is the only one that is true by construction.
         const existing = await this.db.execute(
-            sql`SELECT db_name FROM rebase.branches WHERE name = ${sanitizedName}`
+            sql`SELECT db_name FROM rebase.branches WHERE name = ${name}`
         );
-        if ((existing.rows as unknown[]).length === 0) {
-            throw new Error(`Branch "${sanitizedName}" not found.`);
+        const existingRows = existing.rows as Record<string, unknown>[];
+        if (existingRows.length === 0) {
+            throw new Error(`Branch "${name}" not found.`);
+        }
+        const dbName = existingRows[0].db_name as string;
+
+        // Safety, second pass: the first checked a name we derived, this checks
+        // the one we are about to drop. They differ for any row written under
+        // the old scheme, and it is this one that governs.
+        if (dbName === this.poolManager.defaultDatabaseName) {
+            throw new Error("Cannot delete the main database.");
         }
 
         // Disconnect any pools to this branch before dropping
@@ -201,7 +241,7 @@ export class BranchService {
             const pgError = extractPgError(err);
             if (pgError?.code === PG_OBJECT_IN_USE) {
                 throw new Error(
-                    `Cannot delete branch "${sanitizedName}": the database has active connections. ` +
+                    `Cannot delete branch "${name}": the database has active connections. ` +
                     "Close other clients and try again."
                 );
             }
@@ -210,7 +250,7 @@ export class BranchService {
 
         // Remove metadata
         await this.db.execute(
-            sql`DELETE FROM rebase.branches WHERE name = ${sanitizedName}`
+            sql`DELETE FROM rebase.branches WHERE name = ${name}`
         );
     }
 
@@ -242,15 +282,16 @@ export class BranchService {
      * Get info about a specific branch.
      */
     async getBranchInfo(name: string): Promise<BranchInfo | undefined> {
-        const sanitizedName = sanitizeBranchName(name);
+        assertValidBranchName(name);
 
         const result = await this.db.execute(sql`
-            SELECT 
+            SELECT
                 b.name,
+                b.db_name,
                 b.parent_db,
                 b.created_at
             FROM rebase.branches b
-            WHERE b.name = ${sanitizedName}
+            WHERE b.name = ${name}
         `);
 
         const rows = result.rows as Record<string, unknown>[];
@@ -258,10 +299,12 @@ export class BranchService {
 
         const row = rows[0];
 
-        // Attempt to get size — may fail if the DB was externally dropped
+        // Attempt to get size — may fail if the DB was externally dropped.
+        // Same reason as `deleteBranch`: the size of a re-derived name is the
+        // size of some other database, or of nothing.
         let sizeBytes: number | undefined;
         try {
-            const dbName = toBranchDbName(sanitizedName);
+            const dbName = row.db_name as string;
             const sizeResult = await this.db.execute(
                 sql`SELECT pg_database_size(${dbName}) as size_bytes`
             );

package/src/services/FetchService.ts

@@ -1,10 +1,10 @@
-import { and, asc, count, desc, eq, getTableName, gt, lt, or, SQL, TableRelationalConfig, TablesRelationalConfig } from "drizzle-orm";
+import { and, asc, count, desc, eq, getTableColumns, getTableName, gt, lt, or, SQL, TableRelationalConfig, TablesRelationalConfig } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import { CollectionConfig, FilterValues, ResolvedRelation, LogicalCondition, isManyToMany } from "@rebasepro/types";
 import type { VectorSearchParams } from "@rebasepro/types";
 import { resolveCollectionRelations, findRelation, createRelationRef, createRelationRefWithData } from "@rebasepro/common";
 import { generateForeignKeyName } from "@rebasepro/utils";
-import { DrizzleConditionBuilder, type FilterCompilationOptions } from "../utils/drizzle-conditions";
+import { DrizzleConditionBuilder, getUnknownFilterFieldsMode, type FilterCompilationOptions } from "../utils/drizzle-conditions";
 import {
     getCollectionByPath,
     getTableForCollection,
@@ -12,6 +12,7 @@ import {
     requirePrimaryKeys,
     deriveRowAddress,
     parseIdValues,
+    idCanAddressTable,
     buildCompositeId,
     COMPOSITE_ID_SEPARATOR
 } from "./collection-helpers";
@@ -20,9 +21,10 @@ import { RelationService } from "./RelationService";
 import { RelationalQueryBuilder } from "drizzle-orm/pg-core/query-builders/query";
 import { DrizzleClient } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
-import { toCmsRow, toRestRow, isJunctionRelation } from "./row-pipeline";
+import { toFlatRow, toRestRow, isJunctionRelation } from "./row-pipeline";
 import { isNestedPath, resolveNestedPath, type NestedPathHop } from "./nested-path";
-import { logger } from "@rebasepro/server";
+import { ApiError, logger } from "@rebasepro/server";
+import { reachedDatabase } from "../utils/pg-error-utils";
 
 /** Type-safe accessor for Drizzle's relational query API via dynamic table name */
 type DbQueryAccessor = Record<string, RelationalQueryBuilder<any, any>> | undefined;
@@ -129,12 +131,10 @@ export class FetchService {
         if (direct) return direct;
 
         // Owning relation, resolved: the relation names its own local key.
-        if (collection) {
-            const relation = resolveCollectionRelations(collection)[orderBy];
-            if (relation?.kind === "belongsTo") {
-                const foreignKey = columnAt(relation.localKey);
-                if (foreignKey) return foreignKey;
-            }
+        const declaredRelation = collection ? resolveCollectionRelations(collection)[orderBy] : undefined;
+        if (declaredRelation?.kind === "belongsTo") {
+            const foreignKey = columnAt(declaredRelation.localKey);
+            if (foreignKey) return foreignKey;
         }
 
         // No collection in hand — the two shapes an owning relation's key takes
@@ -145,7 +145,61 @@ export class FetchService {
             if (foreignKey) return foreignKey;
         }
 
-        return undefined;
+        // Nothing resolved. Returning `undefined` is exactly what the docblock
+        // above describes: the caller drops the ORDER BY and hands back rows in
+        // whatever order Postgres pleases, while the requester believes they
+        // are sorted. `?orderBy=titel` answered 200 with unsorted data and no
+        // hint that the sort had been ignored.
+        //
+        // A *filter* naming a field that does not exist is already refused for
+        // precisely this reason — it "used to widen results silently". An
+        // unresolvable sort field is the same drift between a query and the
+        // schema, so it answers the same way and honours the same switch: one
+        // knob, because a deployment that wants the lenient behaviour wants it
+        // for both.
+        const collectionName = collection?.slug ?? collection?.name;
+        const onCollection = collectionName ? ` on collection '${collectionName}'` : "";
+
+        // A declared to-many relation is a different mistake from a typo, and
+        // saying "unknown field" about a field the collection plainly declares
+        // sends the reader looking for a spelling error that is not there.
+        // There is simply no single value per row to order by — `posts.tags` is
+        // a set — so no ORDER BY exists to write, with or without a typo.
+        if (declaredRelation && declaredRelation.kind !== "belongsTo") {
+            throw ApiError.badRequest(
+                `Cannot sort by '${orderBy}'${onCollection}: it is a to-many relation ` +
+                `(${declaredRelation.kind}), which has no single value per row to order by.`,
+                "ORDER_BY_FIELD_NOT_SORTABLE",
+                { field: orderBy, kind: declaredRelation.kind, ...(collectionName && { collection: collectionName }) }
+            );
+        }
+
+        if (getUnknownFilterFieldsMode() === "warn") {
+            logger.warn(
+                `Sorting by field '${orderBy}'${onCollection}, but it does not exist in the table — ` +
+                "the ORDER BY was dropped and these rows are unsorted."
+            );
+            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.
+        }
+
+        throw ApiError.badRequest(
+            `Unknown orderBy field '${orderBy}'${onCollection}` +
+            (validFields.length > 0 ? `. Valid fields: ${validFields.join(", ")}` : ""),
+            "UNKNOWN_ORDER_BY_FIELD",
+            {
+                field: orderBy,
+                ...(collectionName && { collection: collectionName }),
+                ...(validFields.length > 0 && { validFields })
+            }
+        );
     }
 
     /**
@@ -536,6 +590,11 @@ idColumn };
             throw new Error(`ID field '${idInfo.fieldName}' not found in table for collection '${collectionPath}'`);
         }
 
+        // An address the key columns cannot hold names no row — the same answer
+        // as a well-formed id nobody has. Asking Postgres instead raises 22P02
+        // and aborts the transaction around this read.
+        if (!idCanAddressTable(id, table, idInfoArray)) return undefined;
+
         const parsedIdObj = parseIdValues(id, idInfoArray);
         const parsedId = parsedIdObj[idInfo.fieldName];
 
@@ -555,7 +614,7 @@ idColumn };
 
                 if (!row) return undefined;
 
-                const flatRow = toCmsRow(row, collection, this.registry);
+                const flatRow = toFlatRow(row, collection, this.registry);
 
                 // Post-fetch joinPath relations that Drizzle's `with` can't express
                 await this.resolveJoinPathRelations<M>(flatRow, collection, collectionPath, parsedId, databaseId);
@@ -566,6 +625,7 @@ idColumn };
                     logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
                     logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
                 }
+                if (reachedDatabase(e)) throw e;
                 logger.warn(`[FetchService] db.query.findFirst failed for ${collectionPath}, falling back to db.select`, { error: e });
             }
         }
@@ -682,7 +742,7 @@ idColumn };
                 const results = await qb.findMany(queryOpts as Parameters<NonNullable<typeof qb>["findMany"]>[0]);
 
                 const rows = (results as Record<string, unknown>[]).map(row =>
-                    toCmsRow(row, collection, this.registry)
+                    toFlatRow(row, collection, this.registry)
                 );
 
                 return rows;
@@ -691,6 +751,7 @@ idColumn };
                     logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
                     logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
                 }
+                if (reachedDatabase(e)) throw e;
                 logger.warn(`[FetchService] db.query.findMany failed for ${collectionPath}, falling back to db.select`, { error: e });
             }
         }
@@ -785,7 +846,7 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
     /**
      * Fallback path used when db.query is unavailable.
      *
-     * The primary path runs the results through `toCmsRow`, which maps
+     * The primary path runs the results through `toFlatRow`, which maps
      * relations from what drizzle already nested — no query per row. This one
      * has no nesting to read, so it resolves relations itself, in batches.
      *
@@ -893,6 +954,16 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
         collectionPath: string,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
+            /**
+             * An `or(...)`/`and(...)` group, applied alongside `filter`.
+             *
+             * `fetchRowsWithConditions` below has always applied this; it was
+             * simply absent from this signature, so the only callers that could
+             * pass one were the ones that went around this method. Realtime
+             * came through here, which is why a subscription filtered by a
+             * logical group was pushed every row in the table.
+             */
+            logical?: LogicalCondition;
             orderBy?: string;
             order?: "desc" | "asc";
             limit?: number;
@@ -942,6 +1013,7 @@ relatedTo: hop });
         collectionPath: string,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
+            logical?: LogicalCondition;
             searchString?: string;
             databaseId?: string;
         } = {}
@@ -973,6 +1045,13 @@ relatedTo: hop });
             if (filterConditions.length > 0) allConditions.push(...filterConditions);
         }
 
+        if (options.logical) {
+            const logicalCondition = DrizzleConditionBuilder.buildLogicalConditions(
+                options.logical, table, effectivePath, this.filterContext(effectivePath, table)
+            );
+            if (logicalCondition) allConditions.push(logicalCondition);
+        }
+
         if (allConditions.length > 0) {
             const finalCondition = DrizzleConditionBuilder.combineConditionsWithAnd(allConditions);
             if (finalCondition) query = query.where(finalCondition);
@@ -1043,6 +1122,8 @@ relatedTo: hop });
         collectionPath: string,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
+            /** An `or(...)`/`and(...)` group, applied alongside `filter`. */
+            logical?: LogicalCondition;
             orderBy?: string;
             order?: "desc" | "asc";
             limit?: number;
@@ -1111,6 +1192,7 @@ relatedTo: hop }, include
                     logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
                     logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
                 }
+                if (reachedDatabase(e)) throw e;
                 logger.warn(`[fetchCollectionForRest] db.query.findMany failed for ${collectionPath}, falling back`, { error: e });
             }
         }
@@ -1184,6 +1266,9 @@ relatedTo: hop }, include
         const idInfo = idInfoArray[0];
         const idField = table[idInfo.fieldName as keyof typeof table] as AnyPgColumn;
 
+        // See `fetchOne`: an unaddressable id is a 404, not a database error.
+        if (!idCanAddressTable(id, table, idInfoArray)) return null;
+
         const parsedIdObj = parseIdValues(id, idInfoArray);
         const parsedId = parsedIdObj[idInfo.fieldName];
 
@@ -1217,6 +1302,7 @@ relatedTo: hop }, include
                     logger.error(`[FetchService] ResolvedRelation inference error for collection '${collectionPath}': ${e.message}`);
                     logger.error("Hint: This usually means a relation in your drizzle schema is missing a reciprocal 'one()' or 'many()' definition. Run 'rebase schema generate' to fix this.");
                 }
+                if (reachedDatabase(e)) throw e;
                 logger.warn(`[fetchOneForRest] db.query.findFirst failed for ${collectionPath}, falling back`, { error: e });
             }
         }
@@ -1378,99 +1464,6 @@ _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
         return !!this.getQueryBuilder(tableName);
     }
 
-    /**
-     * Attempt to use Drizzle's relational query API (db.query.<table>.findMany)
-     * for efficient JOIN-based relation loading.
-     * Returns null if the API is not available or the query fails.
-     * Note: Primary path now uses `buildWithConfig` + `buildDrizzleQueryOptions`.
-     */
-    private async fetchWithDrizzleQuery<M extends Record<string, unknown>>(
-        collectionPath: string,
-        collection: CollectionConfig,
-        options: {
-            filter?: FilterValues<Extract<keyof M, string>>;
-            orderBy?: string;
-            order?: "desc" | "asc";
-            limit?: number;
-        },
-        include: string[],
-        idInfo: { fieldName: string; type: "string" | "number" },
-        idInfoArray?: { fieldName: string; type: "string" | "number" }[]
-    ): Promise<Record<string, unknown>[] | null> {
-        try {
-
-            const table = getTableForCollection(collection, this.registry);
-            const tableName = getTableName(table);
-            const queryTarget = this.getQueryBuilder(tableName);
-
-            if (!queryTarget?.findMany) return null;
-
-            // Build the `with` config from include array
-            const resolvedRelations = resolveCollectionRelations(collection);
-            const withConfig: Record<string, boolean> = {};
-            for (const [key, relation] of Object.entries(resolvedRelations)) {
-                if (include[0] === "*" || include.includes(key)) {
-                    // Use the Drizzle relation name (from the schema)
-                    const drizzleRelName = relation.relationName || key;
-                    withConfig[drizzleRelName] = true;
-                }
-            }
-
-            // Build query options
-            const queryOpts: Record<string, unknown> = { with: withConfig };
-            if (options.limit) queryOpts.limit = options.limit;
-
-            // Build where clause
-            if (options.filter) {
-                const filterConditions = this.buildFilterConditions(
-                    options.filter, table, collectionPath
-                );
-                if (filterConditions.length > 0) {
-                    queryOpts.where = and(...filterConditions);
-                }
-            }
-
-            // Build orderBy
-            if (options.orderBy) {
-                const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
-                if (orderByField) {
-                    queryOpts.orderBy = options.order === "asc" ? asc(orderByField) : desc(orderByField);
-                }
-            }
-
-
-            const results = await queryTarget.findMany(queryOpts as Parameters<NonNullable<typeof queryTarget>["findMany"]>[0]);
-
-            // Inline the nested Drizzle results, columns only — no synthesized id.
-            return results.map((row: Record<string, unknown>) => {
-                const flat: Record<string, unknown> = {};
-                for (const [k, v] of Object.entries(row)) {
-                    if (Array.isArray(v)) {
-                        // Many relation — inline each nested row
-                        flat[k] = v.map((item: Record<string, unknown>) => {
-                            // Junction table rows may have the target nested, unwrap those
-                            const keys = Object.keys(item);
-                            const nestedObj = keys.find(nk => typeof item[nk] === "object" && item[nk] !== null && !Array.isArray(item[nk]));
-                            if (nestedObj && keys.length <= 3) {
-                                return { ...(item[nestedObj] as Record<string, unknown>) };
-                            }
-                            return { ...item };
-                        });
-                    } else if (typeof v === "object" && v !== null) {
-                        // One-to-one relation — inline the target's columns
-                        flat[k] = { ...(v as Record<string, unknown>) };
-                    } else {
-                        flat[k] = v;
-                    }
-                }
-                return flat;
-            });
-        } catch (e) {
-            logger.warn(`[include] Drizzle relational query failed for '${collectionPath}', falling back`, { error: e });
-            return null;
-        }
-    }
-
     /**
      * Fallback path used when db.query is unavailable.
      * The primary path uses db.query.findMany with `with` config, which

package/src/services/PersistService.ts

@@ -1,7 +1,7 @@
 import { eq, and, sql, SQL } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 // import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { CollectionConfig, Properties, ResolvedRelation, type ResolvedManyToMany, isManyToMany } from "@rebasepro/types";
+import { CollectionConfig, Properties, ResolvedRelation, type ResolvedManyToMany, isManyToMany, hasForeignKeyOnTarget } from "@rebasepro/types";
 import { getTableName, resolveCollectionRelations } from "@rebasepro/common";
 import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
 import {
@@ -240,16 +240,30 @@ export class PersistService {
                     throw ApiError.notFound(`No row "${id}" in "${collectionPath}" to update.`);
                 }
             } else {
-                // One-to-many create: stamp the parent's id onto the child's FK.
+                // One-to-many create: stamp the parent's key onto the child's FK.
                 const targetColumnName = this.resolveParentForeignKeyColumn(hop);
 
                 if (targetColumnName) {
-                    const parsedParentId = parentIdForWrite();
+                    // Not necessarily the id in the path: a link with a
+                    // `sourceKey` is pointed at a column on the parent row, and
+                    // stamping the id would create a child that belongs to
+                    // nobody — a row the read path would never return again.
+                    const parentKeyValue = hasForeignKeyOnTarget(hop.relation)
+                        ? await this.relationService.parentKeyValue(hop.parentCollection, hop.relation, hop.parentId)
+                        : parentIdForWrite();
+
+                    if (parentKeyValue === undefined) {
+                        throw ApiError.badRequest(
+                            `Cannot create under "${collectionPath}": the parent row has no value in ` +
+                            `\`sourceKey\`, so the new row has nothing to point at.`
+                        );
+                    }
+
                     const existingValue = (effectiveValues as Record<string, unknown>)[targetColumnName];
-                    if (existingValue !== undefined && existingValue !== null && existingValue !== parsedParentId) {
-                        logger.warn(`Overriding provided value '${existingValue}' for FK '${targetColumnName}' with path parent id '${parsedParentId}'.`);
+                    if (existingValue !== undefined && existingValue !== null && existingValue !== parentKeyValue) {
+                        logger.warn(`Overriding provided value '${existingValue}' for FK '${targetColumnName}' with path parent key '${parentKeyValue}'.`);
                     }
-                    (effectiveValues as Record<string, unknown>)[targetColumnName] = parsedParentId;
+                    (effectiveValues as Record<string, unknown>)[targetColumnName] = parentKeyValue;
                 }
             }
         }
@@ -463,7 +477,20 @@ export class PersistService {
         const pgError = extractPgError(error);
 
         if (pgError) {
-            const { message } = pgErrorToFriendlyMessage(pgError, collectionSlug);
+            const { message, code } = pgErrorToFriendlyMessage(pgError, collectionSlug);
+            // This is the only layer that holds the SQLSTATE, so it is the only
+            // one that can say whose fault a failure was. Returning a bare
+            // `Error` threw that away, and the REST layer compensated by calling
+            // *every* unclassified error a 400 — so an unreachable database was
+            // reported to callers as a bad request. Classes 22 (data exception)
+            // and 23 (integrity constraint violation) are the caller's data;
+            // everything else — a dropped connection, a missing column, a
+            // permission problem — is ours, and stays a 500.
+            if (/^2[23]/.test(code)) {
+                return code === "23505"
+                    ? ApiError.conflict(message, `PG_${code}`)
+                    : ApiError.badRequest(message, `PG_${code}`);
+            }
             return new Error(message);
         }