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

package/dist/index.es.js

@@ -2,11 +2,11 @@ import { createRequire as __createRequire } from "module";
 import process from "process";
 __createRequire(import.meta.url);
 import { a as guardPoolAgainstDirtyRelease, i as createReadReplicaConnection, n as createDirectDatabaseConnection, o as pinSearchPath, r as createPostgresDatabaseConnection } from "./connection-BuZ97wsr.js";
-import { C as updateDateAutoValues, D as mergeDeep, E as getPolicyNamesForRule, M as hasForeignKeyOnTarget, N as isManyToMany, O as camelCase, P as Vector, S as normalizeToEntityRelation, _ as buildCompositeId, a as getJunctionSecurityRules, b as createRelationRef, c as policyToPostgres, d as findRelation, f as getColumnName, g as resolveCollectionRelations, h as getTableVarName, i as getJunctionCollectionConfig, k as toSnakeCase, l as securityRuleToConditions, m as getTableName$1, n as CollectionRegistry, o as resolveJunctionSpecs, p as getEnumVarName, r as resolveStringColumnLength, s as getEffectiveSecurityRules, t as buildSdkData, u as findAnonymousGrants, v as getDeclaredPrimaryKeys, w as generateForeignKeyName, x as createRelationRefWithData, y as parseIdValues } from "./src-BkdpiQdw.js";
+import { A as toSnakeCase, C as normalizeToEntityRelation, D as getPolicyNamesForRule, F as Vector, N as hasForeignKeyOnTarget, O as mergeDeep, P as isManyToMany, S as createRelationRefWithData, T as generateForeignKeyName, _ as buildCompositeId, a as getJunctionSecurityRules, b as parseIdValues, c as policyToPostgres, d as findRelation, f as getColumnName, g as resolveCollectionRelations, h as getTableVarName, i as getJunctionCollectionConfig, k as camelCase, l as securityRuleToConditions, m as getTableName$1, n as CollectionRegistry, o as resolveJunctionSpecs, p as getEnumVarName, r as resolveStringColumnLength, s as getEffectiveSecurityRules, t as buildSdkData, u as findAnonymousGrants, v as getDeclaredPrimaryKeys, w as updateDateAutoValues, x as createRelationRef, y as isAddressableId } from "./src-DlPBctw_.js";
 import { n as isPostgresCollectionConfig, r as isRelationalCollectionConfig } from "./src-DoU9yPqq.js";
 import { t as ANONYMOUS_USER_ID } from "./policy-CeA1JcxP.js";
 import { t as createPostgresWebSocket } from "./websocket-B2LsrINK.js";
-import { A as serverVersionNumToMajor, C as globalsFileForDump, D as parseDbNameFromUrl, E as parseBackupTimestamp, M as withDatabaseName, O as parsePgToolMajor, S as checkToolServerCompatibility, T as parseBackupDestination, _ as buildBackupFilename, a as detectToolMajor, b as buildPgRestoreArgs, c as listBackups, d as resolvePgBinary, f as restoreDump, g as selectBackupsToPrune, h as require_source, i as createDump, j as splitGlobalsStatements, k as resolveConnectionString, l as preflight, m as validateDump, n as applyGlobals, o as ensureDatabaseExists, p as uploadBackup, s as getServerVersionMajor, t as BackupToolError, u as pruneBackups, v as buildPgDumpArgs, w as joinStorageKey, x as buildPgRestoreListArgs, y as buildPgDumpallGlobalsArgs } from "./backup-service-DLb2drIH.js";
+import { A as parsePgToolMajor, C as checkToolServerCompatibility, D as parseBackupDestination, E as joinStorageKey, M as serverVersionNumToMajor, N as splitGlobalsStatements, O as parseBackupTimestamp, P as withDatabaseName, S as buildRowSecurityPgOptions, T as globalsFileForDump, _ as buildBackupFilename, a as detectToolMajor, b as buildPgRestoreArgs, c as listBackups, d as resolvePgBinary, f as restoreDump, g as selectBackupsToPrune, h as require_source, i as createDump, j as resolveConnectionString, k as parseDbNameFromUrl, l as preflight, m as validateDump, n as applyGlobals, o as ensureDatabaseExists, p as uploadBackup, s as getServerVersionMajor, t as BackupToolError, u as pruneBackups, v as buildPgDumpArgs, w as diagnoseRowSecurityDumpFailure, x as buildPgRestoreListArgs, y as buildPgDumpallGlobalsArgs } from "./backup-service-CD8o_1Sl.js";
 import { Client, Pool } from "pg";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { ApiError, createEmailService, loadCollectionsFromDirectory, logger } from "@rebasepro/server";
@@ -50,6 +50,39 @@ function resolveClientListLimit(rawLimit, opts = {}) {
 	return opts.vectorSearch ? opts.vectorDefaultLimit ?? 10 : opts.defaultLimit ?? 50;
 }
 //#endregion
+//#region ../common/src/util/email.ts
+/**
+* Email normalization — one implementation, because the database enforces it.
+*
+* `ensureAuthTablesExist` puts a `UNIQUE INDEX ON users (lower(email))` on the
+* auth table. That index decides what "the same address" means, and it does not
+* trim: to Postgres, `' foo@bar.com'` and `'foo@bar.com'` are two addresses and
+* both may exist. So every write that reaches the column has to agree with
+* every read, exactly, or the two disagree in the one direction that matters —
+* a row that exists and cannot be found.
+*
+* That is not hypothetical. The lookup path trimmed and the admin create paths
+* did not, so a user created through `POST /api/data/users` or
+* `POST /api/auth/admin/users` with a stray space was stored untrimmed,
+* survived the unique index alongside the real address, and was unreachable by
+* login forever after. The HTTP auth routes were unaffected only because Zod's
+* `.email()` happens to reject surrounding whitespace — a guard on a different
+* layer, for a different reason, that the admin paths do not sit behind.
+*
+* It lives in `common` because `server`, `server-postgres` and `server-mongo`
+* all write this column and must agree exactly, and `common` is the only
+* package all three already depend on.
+*/
+/**
+* Canonical form of an email address: trimmed, lower-cased.
+*
+* Non-strings pass through untouched, so this is safe to apply to a value out
+* of a partial update payload whose type is not known yet.
+*/
+function normalizeEmail(email) {
+	return typeof email === "string" ? email.trim().toLowerCase() : email;
+}
+//#endregion
 //#region ../common/src/util/callbacks.ts
 /**
 * Helper function to recursively check if there are any callbacks in the properties.
@@ -195,6 +228,27 @@ function getColumnMeta(col) {
 		primary: typeof raw.primary === "boolean" ? raw.primary : void 0
 	};
 }
+/**
+* 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`.
+*/
+function idCanAddressTable(id, table, idInfoArray) {
+	return isAddressableId(id, idInfoArray.map((info) => {
+		const col = table[info.fieldName];
+		const meta = col ? getColumnMeta(col) : void 0;
+		if (!meta?.columnType) return info;
+		return {
+			...info,
+			isUUID: meta.columnType === "PgUUID"
+		};
+	}));
+}
 function getCollectionByPath(collectionPath, registry) {
 	const collection = registry.getCollectionByPath(collectionPath);
 	if (!collection) {
@@ -282,6 +336,35 @@ function requirePrimaryKeys(collection, registry) {
 	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.
+*/
+function sourceKeyField(relation, sourceCollection, registry) {
+	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.
+*/
+function joinsOnNaturalKey(relation, sourceCollection, registry) {
+	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.
 *
@@ -452,7 +535,9 @@ var DrizzleConditionBuilder = class {
 			case "hasMany": {
 				const fkColumn = targetTable[relation.foreignKeyOnTarget];
 				if (!fkColumn) throw new Error(`Foreign key column '${relation.foreignKeyOnTarget}' not found in the target table of relation '${relation.relationName}'.`);
-				return eq(fkColumn, parentId);
+				if (!relation.sourceKey) return eq(fkColumn, parentId);
+				const { table, idColumn } = parent();
+				return sql`${fkColumn} = (SELECT ${sql.identifier(relation.sourceKey)} FROM ${table} WHERE ${idColumn} = ${parentId})`;
 			}
 			case "belongsTo": {
 				const { table, idColumn } = parent();
@@ -542,12 +627,16 @@ var DrizzleConditionBuilder = class {
 					column: foreignKey
 				};
 			}
-			if (relation && (hasForeignKeyOnTarget(relation) || isManyToMany(relation)) && registry && sourceIdColumn) return {
-				kind: "relation",
-				relation,
-				registry,
-				sourceIdColumn
-			};
+			if (relation && (hasForeignKeyOnTarget(relation) || isManyToMany(relation)) && registry && sourceIdColumn) {
+				const correlationColumn = hasForeignKeyOnTarget(relation) && relation.sourceKey ? columnAt(relation.sourceKey) : sourceIdColumn;
+				if (!correlationColumn) throw new Error(`\`sourceKey: "${relation.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
+				};
+			}
 		}
 		for (const guess of [`${field}_id`, generateForeignKeyName(field)]) {
 			const foreignKey = columnAt(guess);
@@ -1346,8 +1435,9 @@ async function parseDataFromServer(data, collection, db, registry) {
 			} else if (hasForeignKeyOnTarget(relation) && db && registry) try {
 				const targetCollection = relation.target();
 				const targetTable = registry.getTable(getTableName$1(targetCollection));
-				const currentId = buildCompositeId(data, getPrimaryKeys(collection, registry));
-				if (targetTable && currentId) {
+				const pks = getPrimaryKeys(collection, registry);
+				const currentId = relation.sourceKey ? data[relation.sourceKey] : buildCompositeId(data, pks);
+				if (targetTable && currentId !== void 0 && currentId !== null && currentId !== "") {
 					const foreignKeyColumn = targetTable[relation.foreignKeyOnTarget];
 					if (foreignKeyColumn) {
 						const relatedRows = await db.select().from(targetTable).where(eq(foreignKeyColumn, currentId)).limit(relation.cardinality === "one" ? 1 : 100);
@@ -1719,8 +1809,67 @@ var RelationService = class {
 	* reading. Left alone it would silently match on the first key column and
 	* hand a tenant's rows to its neighbour — say so instead.
 	*/
-	assertSingleKeyAddressable(parentCollection, parentPks, via) {
-		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.`);
+	assertSingleKeyAddressable(parentCollection, parentPks, via, relation) {
+		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 — 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, relation, parentId, db = this.db) {
+		const { keyByParentId } = await this.resolveSourceKeys(parentCollection, relation, [parentId], db);
+		return keyByParentId.get(String(parentId));
+	}
+	async resolveSourceKeys(parentCollection, relation, parentIds, db = this.db) {
+		const keyByParentId = /* @__PURE__ */ new Map();
+		const parentIdByKey = /* @__PURE__ */ new Map();
+		const parentPks = requirePrimaryKeys(parentCollection, this.registry);
+		if (!joinsOnNaturalKey(relation, parentCollection, this.registry)) {
+			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);
+		if (!parentTable[field]) 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) {
+			const keyValue = row[field];
+			if (keyValue === null || keyValue === void 0) continue;
+			const parentId = buildCompositeId(row, parentPks);
+			keyByParentId.set(String(parentId), keyValue);
+			const existing = parentIdByKey.get(String(keyValue));
+			if (existing !== void 0 && 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
@@ -1779,6 +1928,8 @@ var RelationService = class {
 			}
 			return rows;
 		}
+		const matchValue = hasForeignKeyOnTarget(relation) ? (await this.resolveSourceKeys(parentCollection, relation, [parentId])).keyByParentId.get(String(parentId)) : parsedParentId;
+		if (matchValue === void 0) return [];
 		let query = this.db.select().from(targetTable).$dynamic();
 		const additionalFilters = [];
 		if (options.searchString) {
@@ -1787,7 +1938,7 @@ var RelationService = class {
 			const searchCombined = DrizzleConditionBuilder.combineConditionsWithOr(searchConditions);
 			if (searchCombined) additionalFilters.push(searchCombined);
 		}
-		query = applyDynamicRelationQuery(query, query, relation, parsedParentId, targetTable, parentTable, parentIdCol, idField, this.registry, additionalFilters);
+		query = applyDynamicRelationQuery(query, query, relation, matchValue, targetTable, parentTable, parentIdCol, idField, this.registry, additionalFilters);
 		if (options.limit) query = query.limit(options.limit);
 		const results = await query;
 		if (!results || !Array.isArray(results)) return [];
@@ -1830,8 +1981,10 @@ var RelationService = class {
 		const parentTable = this.registry.getTable(getTableName$1(parentCollection));
 		if (!parentTable) throw new Error("Parent table not found");
 		const parentIdCol = parentTable[parentIdInfo.fieldName];
+		const matchValue = hasForeignKeyOnTarget(relation) ? (await this.resolveSourceKeys(parentCollection, relation, [parentId])).keyByParentId.get(String(parentId)) : parsedParentId;
+		if (matchValue === void 0) return 0;
 		let query = this.db.select({ count: sql`count(distinct ${targetIdField})` }).from(targetTable).$dynamic();
-		query = DrizzleConditionBuilder.buildRelationCountQuery(query, relation, parsedParentId, targetTable, parentTable, parentIdCol, targetIdField, this.registry, additionalFilters);
+		query = DrizzleConditionBuilder.buildRelationCountQuery(query, relation, matchValue, targetTable, parentTable, parentIdCol, targetIdField, this.registry, additionalFilters);
 		const result = await query;
 		return Number(result[0]?.count || 0);
 	}
@@ -1958,17 +2111,24 @@ var RelationService = class {
 			}
 			return resultMap;
 		}
-		this.assertSingleKeyAddressable(parentCollection, parentPks, hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName);
+		this.assertSingleKeyAddressable(parentCollection, parentPks, hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName, relation);
+		const { keyByParentId, parentIdByKey } = hasForeignKeyOnTarget(relation) ? await this.resolveSourceKeys(parentCollection, relation, parentIds) : {
+			keyByParentId: /* @__PURE__ */ new Map(),
+			parentIdByKey: /* @__PURE__ */ new Map()
+		};
+		const matchValues = hasForeignKeyOnTarget(relation) ? [...keyByParentId.values()] : parsedParentIds;
+		if (matchValues.length === 0) return /* @__PURE__ */ new Map();
 		let query = this.db.select().from(targetTable).$dynamic();
-		query = applyDynamicRelationQuery(query, query, relation, parsedParentIds, targetTable, parentTable, parentIdCol, targetIdField, this.registry, []);
+		query = applyDynamicRelationQuery(query, query, relation, matchValues, targetTable, parentTable, parentIdCol, targetIdField, this.registry, []);
 		const results = await query;
 		const resultMap = /* @__PURE__ */ new Map();
-		const parentIdSet = new Set(parsedParentIds.map(String));
 		for (const row of results) {
 			const targetRow = row[getTableName$1(targetCollection)] || row;
-			let parentId;
-			if (hasForeignKeyOnTarget(relation)) parentId = targetRow[relation.foreignKeyOnTarget];
-			if (parentId !== void 0 && parentIdSet.has(String(parentId))) resultMap.set(String(parentId), await this.toRelatedRow(targetRow, targetCollection, targetPks));
+			if (!hasForeignKeyOnTarget(relation)) continue;
+			const foreignKeyValue = targetRow[relation.foreignKeyOnTarget];
+			if (foreignKeyValue === void 0 || foreignKeyValue === null) continue;
+			const parentId = parentIdByKey.get(String(foreignKeyValue));
+			if (parentId !== void 0) resultMap.set(String(parentId), await this.toRelatedRow(targetRow, targetCollection, targetPks));
 		}
 		return resultMap;
 	}
@@ -2046,17 +2206,24 @@ var RelationService = class {
 			}
 			return resultMap;
 		}
-		this.assertSingleKeyAddressable(parentCollection, parentPks, hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName);
+		this.assertSingleKeyAddressable(parentCollection, parentPks, hasForeignKeyOnTarget(relation) ? relation.foreignKeyOnTarget : relation.relationName, relation);
+		const { keyByParentId, parentIdByKey } = hasForeignKeyOnTarget(relation) ? await this.resolveSourceKeys(parentCollection, relation, parentIds) : {
+			keyByParentId: /* @__PURE__ */ new Map(),
+			parentIdByKey: /* @__PURE__ */ new Map()
+		};
+		const matchValues = hasForeignKeyOnTarget(relation) ? [...keyByParentId.values()] : parsedParentIds;
+		if (matchValues.length === 0) return /* @__PURE__ */ new Map();
 		let query = this.db.select().from(targetTable).$dynamic();
-		query = applyDynamicRelationQuery(query, query, relation, parsedParentIds, targetTable, parentTable, parentIdCol, targetIdField, this.registry, []);
+		query = applyDynamicRelationQuery(query, query, relation, matchValues, targetTable, parentTable, parentIdCol, targetIdField, this.registry, []);
 		const results = await query;
 		const resultMap = /* @__PURE__ */ new Map();
-		const parentIdSet = new Set(parsedParentIds.map(String));
 		for (const row of results) {
 			const targetRow = row[getTableName$1(targetCollection)] || row;
-			let parentId;
-			if (hasForeignKeyOnTarget(relation)) parentId = targetRow[relation.foreignKeyOnTarget];
-			if (parentId !== void 0 && parentIdSet.has(String(parentId))) {
+			if (!hasForeignKeyOnTarget(relation)) continue;
+			const foreignKeyValue = targetRow[relation.foreignKeyOnTarget];
+			if (foreignKeyValue === void 0 || foreignKeyValue === null) continue;
+			const parentId = parentIdByKey.get(String(foreignKeyValue));
+			if (parentId !== void 0) {
 				const key = String(parentId);
 				const arr = resultMap.get(key) || [];
 				arr.push(await this.toRelatedRow(targetRow, targetCollection, targetPks));
@@ -2155,14 +2322,13 @@ var RelationService = class {
 					logger.warn(`Invalid inverse-many config for relation '${key}' in collection '${collection.slug}'`);
 					continue;
 				}
-				const parentPks = requirePrimaryKeys(collection, this.registry);
-				const parentIdInfo = parentPks[0];
-				const parsedParentId = parseIdValues(id, parentPks)[parentIdInfo.fieldName];
+				const parentKeyValue = (await this.resolveSourceKeys(collection, relation, [id], tx)).keyByParentId.get(String(id));
+				if (parentKeyValue === void 0) 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.`);
 				if (targetEntityIds.length > 0) {
 					const parsedTargetIds = targetEntityIds.map((id) => parseIdValues(id, targetPks)[targetIdInfo.fieldName]);
-					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(and(eq(fkCol, parsedParentId), sql`${targetIdCol} NOT IN (${sql.join(parsedTargetIds)})`));
-					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: parsedParentId }).where(inArray(targetIdCol, parsedTargetIds));
-				} else await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(fkCol, parsedParentId));
+					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(and(eq(fkCol, parentKeyValue), sql`${targetIdCol} NOT IN (${sql.join(parsedTargetIds)})`));
+					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: parentKeyValue }).where(inArray(targetIdCol, parsedTargetIds));
+				} else await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(fkCol, parentKeyValue));
 			} else logger.warn(`Many relation '${key}' in collection '${collection.slug}' lacks write configuration and will be skipped during save.`);
 		}
 	}
@@ -2177,8 +2343,7 @@ var RelationService = class {
 				const targetTable = getTableForCollection(targetCollection, this.registry);
 				const targetPks = requirePrimaryKeys(targetCollection, this.registry);
 				const targetIdInfo = targetPks[0];
-				const sourcePks = requirePrimaryKeys(sourceCollection, this.registry);
-				const sourceIdInfo = sourcePks[0];
+				requirePrimaryKeys(sourceCollection, this.registry)[0];
 				if (relation.kind === "via") {
 					await this.updateInverseJoinPathRelation(tx, sourceCollection, sourceEntityId, targetCollection, relation, newValue);
 					continue;
@@ -2200,13 +2365,14 @@ var RelationService = class {
 					logger.warn(`Foreign key column '${relation.foreignKeyOnTarget}' not found in target table for relation '${relation.relationName}'`);
 					continue;
 				}
-				const parsedSourceId = parseIdValues(sourceEntityId, sourcePks)[sourceIdInfo.fieldName];
-				if (newValue === null || newValue === void 0) await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(foreignKeyColumn, parsedSourceId));
+				const sourceKeyValue = (await this.resolveSourceKeys(sourceCollection, relation, [sourceEntityId], tx)).keyByParentId.get(String(sourceEntityId));
+				if (sourceKeyValue === void 0) 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 === void 0) await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(foreignKeyColumn, sourceKeyValue));
 				else {
 					const parsedNewTargetId = parseIdValues(newValue, targetPks)[targetIdInfo.fieldName];
 					const targetIdField = targetTable[targetIdInfo.fieldName];
-					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(foreignKeyColumn, parsedSourceId));
-					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: parsedSourceId }).where(eq(targetIdField, parsedNewTargetId));
+					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: null }).where(eq(foreignKeyColumn, sourceKeyValue));
+					await tx.update(targetTable).set({ [relation.foreignKeyOnTarget]: sourceKeyValue }).where(eq(targetIdField, parsedNewTargetId));
 				}
 			} catch (e) {
 				logger.warn(`Failed to update inverse relation '${relation.relationName}'`, { error: e });
@@ -2627,91 +2793,332 @@ function assertWritableThrough(hop, path) {
 	throw ApiError.badRequest(`"${path}" ends in the to-one relation '${hop.relationKey}', which cannot be written through: the foreign key for a to-one relation lives on '${hop.parentCollection.slug}', not on '${hop.targetCollection.slug}'. Write the target row at "${hop.targetCollection.slug}" and set '${hop.relationKey}' on the parent instead.`, "RELATION_NOT_WRITABLE");
 }
 //#endregion
-//#region src/services/FetchService.ts
+//#region src/utils/pg-error-utils.ts
 /**
-* Service for handling all row read operations.
-* Handles fetching, searching, counting, and filtering rows.
+* Shared PostgreSQL error extraction and user-friendly message formatting.
+*
+* Drizzle wraps native PG errors in a `.cause` chain. These utilities
+* unwrap that chain to get the real PostgreSQL error (identified by a
+* 5-character alphanumeric `code` such as `42P01`) and translate it into
+* a message that is safe and helpful to show to end-users.
 */
-var FetchService = class {
-	db;
-	registry;
-	relationService;
-	constructor(db, registry) {
-		this.db = db;
-		this.registry = registry;
-		this.relationService = new RelationService(db, registry);
+/**
+* Return the error when it is a deliberate 4xx, otherwise null.
+*
+* A thrown `ApiError` is a decision the server made about the request, not a
+* database failure: its message and code are already written for the client.
+*/
+function asClientFacingError(error) {
+	if (!(error instanceof Error)) return null;
+	const e = error;
+	if (typeof e.statusCode !== "number" || e.statusCode < 400 || e.statusCode >= 500) return null;
+	return e;
+}
+/**
+* Extract the underlying PostgreSQL error from a Drizzle wrapper.
+* Drizzle wraps PG errors in a `cause` property — this function
+* recursively walks the chain until it finds an object with a PG
+* error code (5-char alphanumeric, e.g. `42P01`).
+*/
+function extractPgError(error) {
+	if (!error || typeof error !== "object") return null;
+	if (!(error instanceof Error)) {
+		if ("cause" in error && error.cause && typeof error.cause === "object") return extractPgError(error.cause);
+		return null;
 	}
-	/**
-	* Get the relational query builder for a given table name.
-	* Safely narrows the DrizzleClient union type to access db.query[tableName].
-	*/
-	getQueryBuilder(tableName) {
-		return this.db.query?.[tableName];
+	if ("code" in error && typeof error.code === "string" && /^[0-9A-Z]{5}$/.test(error.code)) return error;
+	if (error.cause && typeof error.cause === "object") return extractPgError(error.cause);
+	return null;
+}
+/**
+* Whether the failure came back from Postgres rather than from building the
+* query — which decides whether a fallback query is worth issuing.
+*
+* Reads here run inside a transaction (that is where `SET LOCAL ROLE` binds
+* RLS). Once a statement raises, that transaction is aborted, and every later
+* statement on it returns `25P02` — "current transaction is aborted, commands
+* ignored until end of transaction block". So a retry after a database error
+* cannot succeed, and it replaces a precise diagnosis ("invalid input syntax
+* for type uuid") with a generic one. Rethrow instead.
+*
+* A query the driver could not even build — a missing reciprocal relation, say
+* — never reached Postgres, leaves the transaction usable, and is exactly what
+* the fallback paths exist for.
+*/
+function reachedDatabase(error) {
+	return extractPgError(error) !== null;
+}
+/**
+* Walk the error cause chain and return the deepest meaningful message.
+*/
+function extractCauseMessage(error) {
+	if (!error || typeof error !== "object") return null;
+	if (!(error instanceof Error)) return null;
+	if (error.cause && typeof error.cause === "object") {
+		const deeper = extractCauseMessage(error.cause);
+		if (deeper) return deeper;
+		if (error.cause instanceof Error && error.cause.message) return error.cause.message;
 	}
-	/**
-	* The context the condition builder needs to compile a filter key that is
-	* not a column name outright.
-	*
-	* Two such keys. An owning relation's key resolves through the collection's
-	* relations to its foreign-key column; a relation whose link lives on the
-	* target table or in a junction resolves to a correlated `EXISTS`, which
-	* needs the registry to reach that other table and this table's key column
-	* to correlate back.
-	*
-	* Looked up rather than passed: every read path already has the path, only
-	* some have the collection, and a path that names no registered collection
-	* (a nested/derived one) is not an error here — the builder simply falls
-	* back to guessing the default key shapes, and a relation filter it cannot
-	* compile stays unresolvable and so fails closed.
-	*/
-	filterContext(collectionPath, table) {
-		const collection = this.registry.getCollectionByPath(collectionPath) ?? void 0;
-		return {
-			collection,
-			registry: this.registry,
-			sourceIdColumn: collection ? this.resolveIdColumn(collection, table) : void 0
+	return null;
+}
+/**
+* Codes that mean "this connection will never work as configured".
+*
+* A wrong password or a database that does not exist is a settled fact about
+* the connection string, not a transient fault — retrying produces the same
+* answer forever.
+*/
+var UNRECOVERABLE_CONNECT_CODES = /* @__PURE__ */ new Set([
+	"28P01",
+	"28000",
+	"3D000",
+	"42501"
+]);
+/**
+* Describe a failed connection attempt in terms a developer can act on.
+*
+* The error a caller catches is Drizzle's wrapper: its message is
+* `Failed query: SELECT 1` and its stack runs through drizzle internals, while
+* the sentence that says what is actually wrong — "password authentication
+* failed for user …", "database … does not exist" — sits in `.cause`. Logging
+* the wrapper, as the bootstrapper used to, tells a developer with a typo in
+* their `DATABASE_URL` nothing at all.
+*/
+function classifyConnectFailure(error) {
+	const pgError = extractPgError(error);
+	const reason = pgError?.message ?? extractCauseMessage(error) ?? (error instanceof Error ? error.message : String(error));
+	return {
+		fatal: Boolean(pgError?.code && UNRECOVERABLE_CONNECT_CODES.has(pgError.code)),
+		reason,
+		code: pgError?.code
+	};
+}
+/**
+* Detect whether an error is specifically a role-switching permission failure
+* (e.g. "permission denied to set role" or "must be member of role"),
+* as opposed to a table-level permission denial.
+*
+* This is used by the backend driver to auto-disable role switching when the
+* connection user lacks SET ROLE privileges, rather than surfacing a confusing
+* error to the Studio SQL Editor user.
+*/
+function isRoleSwitchingPermissionError(error) {
+	const pgError = extractPgError(error);
+	if (!pgError || pgError.code !== "42501") return false;
+	const msg = pgError.message.toLowerCase();
+	return msg.includes("set role") || msg.includes("member of role");
+}
+/**
+* Translate a raw PostgreSQL error into a user-friendly message.
+*
+* @param pgError  - The extracted PostgreSQL error (from {@link extractPgError})
+* @param context  - A human-readable context string (e.g. collection slug or path)
+* @returns An object with a `message` safe for the client and the PG `code`.
+*/
+function pgErrorToFriendlyMessage(pgError, context) {
+	const detail = pgError.detail;
+	const hint = pgError.hint;
+	const constraint = pgError.constraint;
+	const column = pgError.column;
+	const table = pgError.table;
+	const dataType = pgError.dataType;
+	const pgMessage = pgError.message || "Unknown database error";
+	const code = pgError.code || "UNKNOWN";
+	const suffix = hint ? ` Hint: ${hint}` : "";
+	const tableRef = table ?? context;
+	switch (pgError.code) {
+		case "23503": return {
+			message: detail ? `Foreign key constraint violated: ${detail}${suffix}` : `Cannot complete operation: a foreign key constraint${constraint ? ` (${constraint})` : ""} was violated in "${context}".${suffix}`,
+			code
 		};
-	}
-	/**
-	* The table column this collection's rows are keyed by, or `undefined`.
-	*
-	* `getPrimaryKeys` rather than `requirePrimaryKeys`: a collection with no
-	* resolvable key is not an error on the filter path — it only means the
-	* relation filters that would correlate on it cannot be compiled, which
-	* the builder already handles by failing that field closed.
-	*/
-	resolveIdColumn(collection, table) {
-		const [idInfo] = getPrimaryKeys(collection, this.registry);
-		if (!idInfo) return void 0;
-		return table[idInfo.fieldName];
-	}
-	/**
-	* Build filter conditions from FilterValues
-	* Delegates to DrizzleConditionBuilder.buildFilterConditions
-	*/
-	buildFilterConditions(filter, table, collectionPath) {
-		return DrizzleConditionBuilder.buildFilterConditions(filter, table, collectionPath, this.filterContext(collectionPath, table));
-	}
-	/**
-	* Resolves the correct Drizzle column for sorting.
-	* Automatically maps owning relation property keys to their underlying foreign key column.
-	*
-	* The relation's own `localKey` is the authority for that foreign key, not
-	* `<field>_id`. The default local key comes from `generateForeignKeyName`,
-	* which snake-cases *and singularises* — `userProfile` → `user_profile_id`,
-	* `users` → `user_id` — and an author can override it outright. A wrong
-	* guess resolves to nothing, the caller drops the `ORDER BY`, and the rows
-	* come back in whatever order Postgres pleases: paging over that repeats
-	* and skips rows rather than erroring. The guesses stay, last, for a
-	* caller that hands over no collection to resolve against.
-	*/
-	resolveOrderByField(table, orderBy, collection) {
-		const columnAt = (key) => (key in table ? table[key] : void 0) || void 0;
-		const direct = columnAt(orderBy);
-		if (direct) return direct;
-		const declaredRelation = collection ? resolveCollectionRelations(collection)[orderBy] : void 0;
-		if (declaredRelation?.kind === "belongsTo") {
-			const foreignKey = columnAt(declaredRelation.localKey);
+		case "23505": return {
+			message: detail ? `Duplicate value: ${detail}${suffix}` : `Cannot complete operation: a unique constraint${constraint ? ` (${constraint})` : ""} was violated in "${context}".${suffix}`,
+			code
+		};
+		case "23502": return {
+			message: `Missing required field: "${column ?? "unknown"}" in "${tableRef}" cannot be empty.${suffix}`,
+			code
+		};
+		case "23514": return {
+			message: `Validation failed: a check constraint${constraint ? ` (${constraint})` : ""} was violated in "${context}".${suffix}`,
+			code
+		};
+		case "22P02": return {
+			message: `Invalid data format in "${context}": ${pgMessage}${suffix}`,
+			code
+		};
+		case "22001": return {
+			message: `Value too long for column "${column ?? "unknown"}" in "${tableRef}": ${pgMessage}${suffix}`,
+			code
+		};
+		case "22003": return {
+			message: `Numeric value out of range for column "${column ?? "unknown"}" in "${tableRef}": ${pgMessage}${suffix}`,
+			code
+		};
+		case "42703": return {
+			message: `Unknown column in "${tableRef}": ${pgMessage}. Check if your schema is up to date (run migrations).${suffix}`,
+			code
+		};
+		case "42P01": return {
+			message: `Table not found for "${context}": ${pgMessage}. Check if your schema is up to date (run migrations).${suffix}`,
+			code
+		};
+		case "42501": return {
+			message: `Permission denied on "${tableRef}". Check your database credentials and RLS policies.${suffix}`,
+			code
+		};
+		case "28000": return {
+			message: `Authorization failed for "${context}". Check your database credentials.${suffix}`,
+			code
+		};
+		default: {
+			const parts = [`Database error in "${context}" [${code}]: ${pgMessage}`];
+			if (detail) parts.push(`Detail: ${detail}`);
+			if (column) parts.push(`Column: ${column}`);
+			if (dataType) parts.push(`Data type: ${dataType}`);
+			if (constraint) parts.push(`Constraint: ${constraint}`);
+			if (hint) parts.push(`Hint: ${hint}`);
+			return {
+				message: parts.join(". "),
+				code
+			};
+		}
+	}
+}
+/**
+* Sanitize any error into a message safe and helpful for the client.
+*
+* A deliberate 4xx (`ApiError`) passes through untouched — the server already
+* decided what the client should read. Otherwise the PG error is extracted
+* from the Drizzle cause chain, falling back to a generic message that
+* doesn't leak SQL.
+*
+* @param error   - The raw caught error
+* @param context - A human-readable context string (e.g. collection path)
+* @returns An object with `message` (user-friendly) and optional `code`
+*          (the `ApiError` code, or the PG SQLSTATE).
+*/
+function sanitizeErrorForClient(error, context) {
+	const clientError = asClientFacingError(error);
+	if (clientError) {
+		const line = `[API ${clientError.statusCode} ${clientError.code ?? "BAD_REQUEST"}] in "${context}": ${clientError.message}`;
+		if (clientError.expected) logger.debug(line);
+		else logger.warn(`⚠️ ${line}`);
+		return {
+			message: clientError.message,
+			...clientError.code && { code: clientError.code }
+		};
+	}
+	const pgError = extractPgError(error);
+	if (pgError) {
+		logger.error(`[PG ${pgError.code}] Error in "${context}"`, {
+			code: pgError.code,
+			message: pgError.message,
+			detail: pgError.detail,
+			hint: pgError.hint,
+			column: pgError.column,
+			table: pgError.table,
+			constraint: pgError.constraint,
+			dataType: pgError.dataType,
+			drizzleMessage: error instanceof Error ? error.message : String(error)
+		});
+		return pgErrorToFriendlyMessage(pgError, context);
+	}
+	logger.error(`Database error in "${context}" (no PG error extracted)`, {
+		error: error instanceof Error ? error.message : String(error),
+		stack: error instanceof Error ? error.stack : void 0,
+		cause: error instanceof Error && error.cause ? error.cause instanceof Error ? error.cause.message : String(error.cause) : void 0
+	});
+	const causeMessage = extractCauseMessage(error);
+	if (causeMessage) return { message: `Database error in "${context}": ${causeMessage}` };
+	return { message: `Could not load data for "${context}". Check server logs for details.` };
+}
+//#endregion
+//#region src/services/FetchService.ts
+/**
+* Service for handling all row read operations.
+* Handles fetching, searching, counting, and filtering rows.
+*/
+var FetchService = class {
+	db;
+	registry;
+	relationService;
+	constructor(db, registry) {
+		this.db = db;
+		this.registry = registry;
+		this.relationService = new RelationService(db, registry);
+	}
+	/**
+	* Get the relational query builder for a given table name.
+	* Safely narrows the DrizzleClient union type to access db.query[tableName].
+	*/
+	getQueryBuilder(tableName) {
+		return this.db.query?.[tableName];
+	}
+	/**
+	* The context the condition builder needs to compile a filter key that is
+	* not a column name outright.
+	*
+	* Two such keys. An owning relation's key resolves through the collection's
+	* relations to its foreign-key column; a relation whose link lives on the
+	* target table or in a junction resolves to a correlated `EXISTS`, which
+	* needs the registry to reach that other table and this table's key column
+	* to correlate back.
+	*
+	* Looked up rather than passed: every read path already has the path, only
+	* some have the collection, and a path that names no registered collection
+	* (a nested/derived one) is not an error here — the builder simply falls
+	* back to guessing the default key shapes, and a relation filter it cannot
+	* compile stays unresolvable and so fails closed.
+	*/
+	filterContext(collectionPath, table) {
+		const collection = this.registry.getCollectionByPath(collectionPath) ?? void 0;
+		return {
+			collection,
+			registry: this.registry,
+			sourceIdColumn: collection ? this.resolveIdColumn(collection, table) : void 0
+		};
+	}
+	/**
+	* The table column this collection's rows are keyed by, or `undefined`.
+	*
+	* `getPrimaryKeys` rather than `requirePrimaryKeys`: a collection with no
+	* resolvable key is not an error on the filter path — it only means the
+	* relation filters that would correlate on it cannot be compiled, which
+	* the builder already handles by failing that field closed.
+	*/
+	resolveIdColumn(collection, table) {
+		const [idInfo] = getPrimaryKeys(collection, this.registry);
+		if (!idInfo) return void 0;
+		return table[idInfo.fieldName];
+	}
+	/**
+	* Build filter conditions from FilterValues
+	* Delegates to DrizzleConditionBuilder.buildFilterConditions
+	*/
+	buildFilterConditions(filter, table, collectionPath) {
+		return DrizzleConditionBuilder.buildFilterConditions(filter, table, collectionPath, this.filterContext(collectionPath, table));
+	}
+	/**
+	* Resolves the correct Drizzle column for sorting.
+	* Automatically maps owning relation property keys to their underlying foreign key column.
+	*
+	* The relation's own `localKey` is the authority for that foreign key, not
+	* `<field>_id`. The default local key comes from `generateForeignKeyName`,
+	* which snake-cases *and singularises* — `userProfile` → `user_profile_id`,
+	* `users` → `user_id` — and an author can override it outright. A wrong
+	* guess resolves to nothing, the caller drops the `ORDER BY`, and the rows
+	* come back in whatever order Postgres pleases: paging over that repeats
+	* and skips rows rather than erroring. The guesses stay, last, for a
+	* caller that hands over no collection to resolve against.
+	*/
+	resolveOrderByField(table, orderBy, collection) {
+		const columnAt = (key) => (key in table ? table[key] : void 0) || void 0;
+		const direct = columnAt(orderBy);
+		if (direct) return direct;
+		const declaredRelation = collection ? resolveCollectionRelations(collection)[orderBy] : void 0;
+		if (declaredRelation?.kind === "belongsTo") {
+			const foreignKey = columnAt(declaredRelation.localKey);
 			if (foreignKey) return foreignKey;
 		}
 		for (const guess of [`${orderBy}_id`, generateForeignKeyName(orderBy)]) {
@@ -2941,6 +3348,7 @@ var FetchService = class {
 		const idInfo = idInfoArray[0];
 		const idField = table[idInfo.fieldName];
 		if (!idField) throw new Error(`ID field '${idInfo.fieldName}' not found in table for collection '${collectionPath}'`);
+		if (!idCanAddressTable(id, table, idInfoArray)) return void 0;
 		const parsedId = parseIdValues(id, idInfoArray)[idInfo.fieldName];
 		const tableName = getTableName(table);
 		const qb = this.getQueryBuilder(tableName);
@@ -2959,6 +3367,7 @@ var FetchService = class {
 				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 });
 		}
 		const result = await this.db.select().from(table).where(eq(idField, parsedId)).limit(1);
@@ -3012,6 +3421,7 @@ var FetchService = class {
 				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 });
 		}
 		let vectorMeta;
@@ -3231,6 +3641,7 @@ var FetchService = class {
 				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 });
 		}
 		const rows = await this.fetchRowsWithConditionsRaw(collectionPath, options);
@@ -3276,6 +3687,7 @@ var FetchService = class {
 		const idInfoArray = requirePrimaryKeys(collection, this.registry);
 		const idInfo = idInfoArray[0];
 		const idField = table[idInfo.fieldName];
+		if (!idCanAddressTable(id, table, idInfoArray)) return null;
 		const parsedId = parseIdValues(id, idInfoArray)[idInfo.fieldName];
 		const tableName = getTableName(table);
 		const qb = this.getQueryBuilder(tableName);
@@ -3294,6 +3706,7 @@ var FetchService = class {
 				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 });
 		}
 		const result = await this.db.select().from(table).where(eq(idField, parsedId)).limit(1);
@@ -3323,357 +3736,134 @@ var FetchService = class {
 				logger.warn(`[include] Failed to load relation '${key}'`, { error: e });
 			}
 		}
-		return flatEntity;
-	}
-	/**
-	* Fetch raw rows without any relation processing (for REST fast path)
-	*/
-	async fetchRowsWithConditionsRaw(collectionPath, options = {}) {
-		const collection = getCollectionByPath(collectionPath, this.registry);
-		const table = getTableForCollection(collection, this.registry);
-		const idField = table[requirePrimaryKeys(collection, this.registry)[0].fieldName];
-		let vectorMeta;
-		if (options.vectorSearch) vectorMeta = DrizzleConditionBuilder.buildVectorSearchConditions(table, options.vectorSearch);
-		let query = vectorMeta ? this.db.select({
-			table_row: table,
-			_distance: vectorMeta.distanceSelect
-		}).from(table).$dynamic() : this.db.select().from(table).$dynamic();
-		const allConditions = [];
-		if (options.relatedTo) allConditions.push(this.buildRelationScope(options.relatedTo));
-		if (options.searchString) {
-			const searchConditions = DrizzleConditionBuilder.buildSearchConditions(options.searchString, collection.properties, table);
-			if (searchConditions.length === 0) return [];
-			allConditions.push(DrizzleConditionBuilder.combineConditionsWithOr(searchConditions));
-		}
-		if (options.filter) {
-			const filterConditions = this.buildFilterConditions(options.filter, table, collectionPath);
-			if (filterConditions.length > 0) allConditions.push(...filterConditions);
-		}
-		if (vectorMeta?.filter) allConditions.push(vectorMeta.filter);
-		if (allConditions.length > 0) {
-			const finalCondition = DrizzleConditionBuilder.combineConditionsWithAnd(allConditions);
-			if (finalCondition) query = query.where(finalCondition);
-		}
-		const orderExpressions = [];
-		if (vectorMeta) orderExpressions.push(asc(vectorMeta.orderBy));
-		else if (options.orderBy) {
-			const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
-			if (orderByField) orderExpressions.push(options.order === "asc" ? asc(orderByField) : desc(orderByField));
-		}
-		orderExpressions.push(desc(idField));
-		if (orderExpressions.length > 0) query = query.orderBy(...orderExpressions);
-		const limitValue = options.vectorSearch ? options.limit || 10 : options.searchString ? options.limit || 50 : options.limit;
-		if (limitValue) query = query.limit(limitValue);
-		if (options.offset && options.offset > 0) query = query.offset(options.offset);
-		const rawResults = await query;
-		if (vectorMeta) return rawResults.map((r) => ({
-			...r.table_row,
-			_distance: typeof r._distance === "number" ? r._distance : parseFloat(String(r._distance))
-		}));
-		return rawResults;
-	}
-	/**
-	* Check if the Drizzle instance has the relational query API available
-	* for a given collection path.
-	* Note: Primary path now uses inline `getQueryBuilder()` checks.
-	*/
-	hasDrizzleQueryAPI(collectionPath) {
-		if (!this.getQueryBuilder("__probe__")) return false;
-		const tableName = getTableName(getTableForCollection(getCollectionByPath(collectionPath, this.registry), this.registry));
-		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`.
-	*/
-	async fetchWithDrizzleQuery(collectionPath, collection, options, include, idInfo, idInfoArray) {
-		try {
-			const table = getTableForCollection(collection, this.registry);
-			const tableName = getTableName(table);
-			const queryTarget = this.getQueryBuilder(tableName);
-			if (!queryTarget?.findMany) return null;
-			const resolvedRelations = resolveCollectionRelations(collection);
-			const withConfig = {};
-			for (const [key, relation] of Object.entries(resolvedRelations)) if (include[0] === "*" || include.includes(key)) {
-				const drizzleRelName = relation.relationName || key;
-				withConfig[drizzleRelName] = true;
-			}
-			const queryOpts = { with: withConfig };
-			if (options.limit) queryOpts.limit = options.limit;
-			if (options.filter) {
-				const filterConditions = this.buildFilterConditions(options.filter, table, collectionPath);
-				if (filterConditions.length > 0) queryOpts.where = and(...filterConditions);
-			}
-			if (options.orderBy) {
-				const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
-				if (orderByField) queryOpts.orderBy = options.order === "asc" ? asc(orderByField) : desc(orderByField);
-			}
-			return (await queryTarget.findMany(queryOpts)).map((row) => {
-				const flat = {};
-				for (const [k, v] of Object.entries(row)) if (Array.isArray(v)) flat[k] = v.map((item) => {
-					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] };
-					return { ...item };
-				});
-				else if (typeof v === "object" && v !== null) flat[k] = { ...v };
-				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
-	* loads all relations in a single query.
-	*
-	* Batch fetch many-to-many related rows for multiple parent IDs.
-	* Groups results by parent ID to avoid N+1.
-	*/
-	async batchFetchManyRelatedRows(parentCollectionPath, parentIds, relationKey) {
-		if (parentIds.length === 0) return /* @__PURE__ */ new Map();
-		const relation = resolveCollectionRelations(getCollectionByPath(parentCollectionPath, this.registry))[relationKey];
-		if (!relation) {
-			logger.warn(`[batchFetchManyRelatedRows] ResolvedRelation '${relationKey}' not found, skipping`);
-			return /* @__PURE__ */ new Map();
-		}
-		const entityMap = await this.relationService.batchFetchRelatedEntitiesMany(parentCollectionPath, parentIds, relationKey, relation);
-		const flatMap = /* @__PURE__ */ new Map();
-		for (const [key, rows] of entityMap) flatMap.set(key, rows.map((e) => ({
-			...e.values,
-			id: e.id
-		})));
-		return flatMap;
-	}
-};
-//#endregion
-//#region src/utils/pg-error-utils.ts
-/**
-* Shared PostgreSQL error extraction and user-friendly message formatting.
-*
-* Drizzle wraps native PG errors in a `.cause` chain. These utilities
-* unwrap that chain to get the real PostgreSQL error (identified by a
-* 5-character alphanumeric `code` such as `42P01`) and translate it into
-* a message that is safe and helpful to show to end-users.
-*/
-/**
-* Return the error when it is a deliberate 4xx, otherwise null.
-*
-* A thrown `ApiError` is a decision the server made about the request, not a
-* database failure: its message and code are already written for the client.
-*/
-function asClientFacingError(error) {
-	if (!(error instanceof Error)) return null;
-	const e = error;
-	if (typeof e.statusCode !== "number" || e.statusCode < 400 || e.statusCode >= 500) return null;
-	return e;
-}
-/**
-* Extract the underlying PostgreSQL error from a Drizzle wrapper.
-* Drizzle wraps PG errors in a `cause` property — this function
-* recursively walks the chain until it finds an object with a PG
-* error code (5-char alphanumeric, e.g. `42P01`).
-*/
-function extractPgError(error) {
-	if (!error || typeof error !== "object") return null;
-	if (!(error instanceof Error)) {
-		if ("cause" in error && error.cause && typeof error.cause === "object") return extractPgError(error.cause);
-		return null;
-	}
-	if ("code" in error && typeof error.code === "string" && /^[0-9A-Z]{5}$/.test(error.code)) return error;
-	if (error.cause && typeof error.cause === "object") return extractPgError(error.cause);
-	return null;
-}
-/**
-* Walk the error cause chain and return the deepest meaningful message.
-*/
-function extractCauseMessage(error) {
-	if (!error || typeof error !== "object") return null;
-	if (!(error instanceof Error)) return null;
-	if (error.cause && typeof error.cause === "object") {
-		const deeper = extractCauseMessage(error.cause);
-		if (deeper) return deeper;
-		if (error.cause instanceof Error && error.cause.message) return error.cause.message;
-	}
-	return null;
-}
-/**
-* Codes that mean "this connection will never work as configured".
-*
-* A wrong password or a database that does not exist is a settled fact about
-* the connection string, not a transient fault — retrying produces the same
-* answer forever.
-*/
-var UNRECOVERABLE_CONNECT_CODES = /* @__PURE__ */ new Set([
-	"28P01",
-	"28000",
-	"3D000",
-	"42501"
-]);
-/**
-* Describe a failed connection attempt in terms a developer can act on.
-*
-* The error a caller catches is Drizzle's wrapper: its message is
-* `Failed query: SELECT 1` and its stack runs through drizzle internals, while
-* the sentence that says what is actually wrong — "password authentication
-* failed for user …", "database … does not exist" — sits in `.cause`. Logging
-* the wrapper, as the bootstrapper used to, tells a developer with a typo in
-* their `DATABASE_URL` nothing at all.
-*/
-function classifyConnectFailure(error) {
-	const pgError = extractPgError(error);
-	const reason = pgError?.message ?? extractCauseMessage(error) ?? (error instanceof Error ? error.message : String(error));
-	return {
-		fatal: Boolean(pgError?.code && UNRECOVERABLE_CONNECT_CODES.has(pgError.code)),
-		reason,
-		code: pgError?.code
-	};
-}
-/**
-* Detect whether an error is specifically a role-switching permission failure
-* (e.g. "permission denied to set role" or "must be member of role"),
-* as opposed to a table-level permission denial.
-*
-* This is used by the backend driver to auto-disable role switching when the
-* connection user lacks SET ROLE privileges, rather than surfacing a confusing
-* error to the Studio SQL Editor user.
-*/
-function isRoleSwitchingPermissionError(error) {
-	const pgError = extractPgError(error);
-	if (!pgError || pgError.code !== "42501") return false;
-	const msg = pgError.message.toLowerCase();
-	return msg.includes("set role") || msg.includes("member of role");
-}
-/**
-* Translate a raw PostgreSQL error into a user-friendly message.
-*
-* @param pgError  - The extracted PostgreSQL error (from {@link extractPgError})
-* @param context  - A human-readable context string (e.g. collection slug or path)
-* @returns An object with a `message` safe for the client and the PG `code`.
-*/
-function pgErrorToFriendlyMessage(pgError, context) {
-	const detail = pgError.detail;
-	const hint = pgError.hint;
-	const constraint = pgError.constraint;
-	const column = pgError.column;
-	const table = pgError.table;
-	const dataType = pgError.dataType;
-	const pgMessage = pgError.message || "Unknown database error";
-	const code = pgError.code || "UNKNOWN";
-	const suffix = hint ? ` Hint: ${hint}` : "";
-	const tableRef = table ?? context;
-	switch (pgError.code) {
-		case "23503": return {
-			message: detail ? `Foreign key constraint violated: ${detail}${suffix}` : `Cannot complete operation: a foreign key constraint${constraint ? ` (${constraint})` : ""} was violated in "${context}".${suffix}`,
-			code
-		};
-		case "23505": return {
-			message: detail ? `Duplicate value: ${detail}${suffix}` : `Cannot complete operation: a unique constraint${constraint ? ` (${constraint})` : ""} was violated in "${context}".${suffix}`,
-			code
-		};
-		case "23502": return {
-			message: `Missing required field: "${column ?? "unknown"}" in "${tableRef}" cannot be empty.${suffix}`,
-			code
-		};
-		case "23514": return {
-			message: `Validation failed: a check constraint${constraint ? ` (${constraint})` : ""} was violated in "${context}".${suffix}`,
-			code
-		};
-		case "22P02": return {
-			message: `Invalid data format in "${context}": ${pgMessage}${suffix}`,
-			code
-		};
-		case "22001": return {
-			message: `Value too long for column "${column ?? "unknown"}" in "${tableRef}": ${pgMessage}${suffix}`,
-			code
-		};
-		case "22003": return {
-			message: `Numeric value out of range for column "${column ?? "unknown"}" in "${tableRef}": ${pgMessage}${suffix}`,
-			code
-		};
-		case "42703": return {
-			message: `Unknown column in "${tableRef}": ${pgMessage}. Check if your schema is up to date (run migrations).${suffix}`,
-			code
-		};
-		case "42P01": return {
-			message: `Table not found for "${context}": ${pgMessage}. Check if your schema is up to date (run migrations).${suffix}`,
-			code
-		};
-		case "42501": return {
-			message: `Permission denied on "${tableRef}". Check your database credentials and RLS policies.${suffix}`,
-			code
-		};
-		case "28000": return {
-			message: `Authorization failed for "${context}". Check your database credentials.${suffix}`,
-			code
-		};
-		default: {
-			const parts = [`Database error in "${context}" [${code}]: ${pgMessage}`];
-			if (detail) parts.push(`Detail: ${detail}`);
-			if (column) parts.push(`Column: ${column}`);
-			if (dataType) parts.push(`Data type: ${dataType}`);
-			if (constraint) parts.push(`Constraint: ${constraint}`);
-			if (hint) parts.push(`Hint: ${hint}`);
-			return {
-				message: parts.join(". "),
-				code
-			};
-		}
+		return flatEntity;
 	}
-}
-/**
-* Sanitize any error into a message safe and helpful for the client.
-*
-* A deliberate 4xx (`ApiError`) passes through untouched — the server already
-* decided what the client should read. Otherwise the PG error is extracted
-* from the Drizzle cause chain, falling back to a generic message that
-* doesn't leak SQL.
-*
-* @param error   - The raw caught error
-* @param context - A human-readable context string (e.g. collection path)
-* @returns An object with `message` (user-friendly) and optional `code`
-*          (the `ApiError` code, or the PG SQLSTATE).
-*/
-function sanitizeErrorForClient(error, context) {
-	const clientError = asClientFacingError(error);
-	if (clientError) {
-		const line = `[API ${clientError.statusCode} ${clientError.code ?? "BAD_REQUEST"}] in "${context}": ${clientError.message}`;
-		if (clientError.expected) logger.debug(line);
-		else logger.warn(`⚠️ ${line}`);
-		return {
-			message: clientError.message,
-			...clientError.code && { code: clientError.code }
-		};
+	/**
+	* Fetch raw rows without any relation processing (for REST fast path)
+	*/
+	async fetchRowsWithConditionsRaw(collectionPath, options = {}) {
+		const collection = getCollectionByPath(collectionPath, this.registry);
+		const table = getTableForCollection(collection, this.registry);
+		const idField = table[requirePrimaryKeys(collection, this.registry)[0].fieldName];
+		let vectorMeta;
+		if (options.vectorSearch) vectorMeta = DrizzleConditionBuilder.buildVectorSearchConditions(table, options.vectorSearch);
+		let query = vectorMeta ? this.db.select({
+			table_row: table,
+			_distance: vectorMeta.distanceSelect
+		}).from(table).$dynamic() : this.db.select().from(table).$dynamic();
+		const allConditions = [];
+		if (options.relatedTo) allConditions.push(this.buildRelationScope(options.relatedTo));
+		if (options.searchString) {
+			const searchConditions = DrizzleConditionBuilder.buildSearchConditions(options.searchString, collection.properties, table);
+			if (searchConditions.length === 0) return [];
+			allConditions.push(DrizzleConditionBuilder.combineConditionsWithOr(searchConditions));
+		}
+		if (options.filter) {
+			const filterConditions = this.buildFilterConditions(options.filter, table, collectionPath);
+			if (filterConditions.length > 0) allConditions.push(...filterConditions);
+		}
+		if (vectorMeta?.filter) allConditions.push(vectorMeta.filter);
+		if (allConditions.length > 0) {
+			const finalCondition = DrizzleConditionBuilder.combineConditionsWithAnd(allConditions);
+			if (finalCondition) query = query.where(finalCondition);
+		}
+		const orderExpressions = [];
+		if (vectorMeta) orderExpressions.push(asc(vectorMeta.orderBy));
+		else if (options.orderBy) {
+			const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
+			if (orderByField) orderExpressions.push(options.order === "asc" ? asc(orderByField) : desc(orderByField));
+		}
+		orderExpressions.push(desc(idField));
+		if (orderExpressions.length > 0) query = query.orderBy(...orderExpressions);
+		const limitValue = options.vectorSearch ? options.limit || 10 : options.searchString ? options.limit || 50 : options.limit;
+		if (limitValue) query = query.limit(limitValue);
+		if (options.offset && options.offset > 0) query = query.offset(options.offset);
+		const rawResults = await query;
+		if (vectorMeta) return rawResults.map((r) => ({
+			...r.table_row,
+			_distance: typeof r._distance === "number" ? r._distance : parseFloat(String(r._distance))
+		}));
+		return rawResults;
 	}
-	const pgError = extractPgError(error);
-	if (pgError) {
-		logger.error(`[PG ${pgError.code}] Error in "${context}"`, {
-			code: pgError.code,
-			message: pgError.message,
-			detail: pgError.detail,
-			hint: pgError.hint,
-			column: pgError.column,
-			table: pgError.table,
-			constraint: pgError.constraint,
-			dataType: pgError.dataType,
-			drizzleMessage: error instanceof Error ? error.message : String(error)
-		});
-		return pgErrorToFriendlyMessage(pgError, context);
+	/**
+	* Check if the Drizzle instance has the relational query API available
+	* for a given collection path.
+	* Note: Primary path now uses inline `getQueryBuilder()` checks.
+	*/
+	hasDrizzleQueryAPI(collectionPath) {
+		if (!this.getQueryBuilder("__probe__")) return false;
+		const tableName = getTableName(getTableForCollection(getCollectionByPath(collectionPath, this.registry), this.registry));
+		return !!this.getQueryBuilder(tableName);
 	}
-	logger.error(`Database error in "${context}" (no PG error extracted)`, {
-		error: error instanceof Error ? error.message : String(error),
-		stack: error instanceof Error ? error.stack : void 0,
-		cause: error instanceof Error && error.cause ? error.cause instanceof Error ? error.cause.message : String(error.cause) : void 0
-	});
-	const causeMessage = extractCauseMessage(error);
-	if (causeMessage) return { message: `Database error in "${context}": ${causeMessage}` };
-	return { message: `Could not load data for "${context}". Check server logs for details.` };
-}
+	/**
+	* 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`.
+	*/
+	async fetchWithDrizzleQuery(collectionPath, collection, options, include, idInfo, idInfoArray) {
+		try {
+			const table = getTableForCollection(collection, this.registry);
+			const tableName = getTableName(table);
+			const queryTarget = this.getQueryBuilder(tableName);
+			if (!queryTarget?.findMany) return null;
+			const resolvedRelations = resolveCollectionRelations(collection);
+			const withConfig = {};
+			for (const [key, relation] of Object.entries(resolvedRelations)) if (include[0] === "*" || include.includes(key)) {
+				const drizzleRelName = relation.relationName || key;
+				withConfig[drizzleRelName] = true;
+			}
+			const queryOpts = { with: withConfig };
+			if (options.limit) queryOpts.limit = options.limit;
+			if (options.filter) {
+				const filterConditions = this.buildFilterConditions(options.filter, table, collectionPath);
+				if (filterConditions.length > 0) queryOpts.where = and(...filterConditions);
+			}
+			if (options.orderBy) {
+				const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
+				if (orderByField) queryOpts.orderBy = options.order === "asc" ? asc(orderByField) : desc(orderByField);
+			}
+			return (await queryTarget.findMany(queryOpts)).map((row) => {
+				const flat = {};
+				for (const [k, v] of Object.entries(row)) if (Array.isArray(v)) flat[k] = v.map((item) => {
+					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] };
+					return { ...item };
+				});
+				else if (typeof v === "object" && v !== null) flat[k] = { ...v };
+				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
+	* loads all relations in a single query.
+	*
+	* Batch fetch many-to-many related rows for multiple parent IDs.
+	* Groups results by parent ID to avoid N+1.
+	*/
+	async batchFetchManyRelatedRows(parentCollectionPath, parentIds, relationKey) {
+		if (parentIds.length === 0) return /* @__PURE__ */ new Map();
+		const relation = resolveCollectionRelations(getCollectionByPath(parentCollectionPath, this.registry))[relationKey];
+		if (!relation) {
+			logger.warn(`[batchFetchManyRelatedRows] ResolvedRelation '${relationKey}' not found, skipping`);
+			return /* @__PURE__ */ new Map();
+		}
+		const entityMap = await this.relationService.batchFetchRelatedEntitiesMany(parentCollectionPath, parentIds, relationKey, relation);
+		const flatMap = /* @__PURE__ */ new Map();
+		for (const [key, rows] of entityMap) flatMap.set(key, rows.map((e) => ({
+			...e.values,
+			id: e.id
+		})));
+		return flatMap;
+	}
+};
 //#endregion
 //#region src/services/PersistService.ts
 /**
@@ -3797,10 +3987,11 @@ var PersistService = class {
 			} else {
 				const targetColumnName = this.resolveParentForeignKeyColumn(hop);
 				if (targetColumnName) {
-					const parsedParentId = parentIdForWrite();
+					const parentKeyValue = hasForeignKeyOnTarget(hop.relation) ? await this.relationService.parentKeyValue(hop.parentCollection, hop.relation, hop.parentId) : parentIdForWrite();
+					if (parentKeyValue === void 0) 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[targetColumnName];
-					if (existingValue !== void 0 && existingValue !== null && existingValue !== parsedParentId) logger.warn(`Overriding provided value '${existingValue}' for FK '${targetColumnName}' with path parent id '${parsedParentId}'.`);
-					effectiveValues[targetColumnName] = parsedParentId;
+					if (existingValue !== void 0 && existingValue !== null && existingValue !== parentKeyValue) logger.warn(`Overriding provided value '${existingValue}' for FK '${targetColumnName}' with path parent key '${parentKeyValue}'.`);
+					effectiveValues[targetColumnName] = parentKeyValue;
 				}
 			}
 		}
@@ -4074,19 +4265,34 @@ function validateIdentifier(value, label) {
 	if (!/^[a-zA-Z0-9_-]+$/.test(value)) throw new Error(`Invalid ${label}: only letters, digits, underscores, and hyphens are allowed.`);
 }
 /**
-* 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.
+*/
+var MAX_BRANCH_NAME_LENGTH = 60;
+/**
+* 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 sanitizeBranchName(name) {
-	return name.replace(/[^a-zA-Z0-9_]/g, "");
+function assertValidBranchName(name) {
+	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) {
-	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}`;
 }
 var BranchService = class {
 	db;
@@ -4123,9 +4329,8 @@ var BranchService = class {
 	async createBranch(name, options) {
 		if (options?.source) validateIdentifier(options.source, "source database name");
 		const dbName = toBranchDbName(name);
-		const sanitizedName = sanitizeBranchName(name);
 		const sourceDb = options?.source || this.poolManager.defaultDatabaseName;
-		if ((await this.db.execute(sql`SELECT name FROM rebase.branches WHERE name = ${sanitizedName} OR db_name = ${dbName}`)).rows.length > 0) throw new Error(`Branch "${sanitizedName}" already exists.`);
+		if ((await this.db.execute(sql`SELECT name FROM rebase.branches WHERE name = ${name} OR db_name = ${dbName}`)).rows.length > 0) throw new Error(`Branch "${name}" already exists.`);
 		await this.poolManager.disconnectDatabase(sourceDb);
 		const safeDbName = dbName.replace(/"/g, "\"\"");
 		const safeSourceDb = sourceDb.replace(/"/g, "\"\"");
@@ -4136,10 +4341,10 @@ var BranchService = class {
 			throw describeBranchDdlError(err, dbName);
 		}
 		const now = /* @__PURE__ */ new Date();
-		await this.db.execute(sql`INSERT INTO rebase.branches (name, db_name, parent_db, created_at) 
-                VALUES (${sanitizedName}, ${dbName}, ${sourceDb}, ${now.toISOString()})`);
+		await this.db.execute(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
 		};
@@ -4149,19 +4354,21 @@ var BranchService = class {
 	* Cannot delete the main/default database.
 	*/
 	async deleteBranch(name) {
-		const sanitizedName = sanitizeBranchName(name);
-		const dbName = toBranchDbName(name);
+		assertValidBranchName(name);
+		if (toBranchDbName(name) === this.poolManager.defaultDatabaseName) throw new Error("Cannot delete the main database.");
+		const existingRows = (await this.db.execute(sql`SELECT db_name FROM rebase.branches WHERE name = ${name}`)).rows;
+		if (existingRows.length === 0) throw new Error(`Branch "${name}" not found.`);
+		const dbName = existingRows[0].db_name;
 		if (dbName === this.poolManager.defaultDatabaseName) throw new Error("Cannot delete the main database.");
-		if ((await this.db.execute(sql`SELECT db_name FROM rebase.branches WHERE name = ${sanitizedName}`)).rows.length === 0) throw new Error(`Branch "${sanitizedName}" not found.`);
 		await this.poolManager.disconnectDatabase(dbName);
 		const safeDbName = dbName.replace(/"/g, "\"\"");
 		try {
 			await this.db.execute(sql.raw(`DROP DATABASE "${safeDbName}"`));
 		} catch (err) {
-			if (extractPgError(err)?.code === PG_OBJECT_IN_USE) throw new Error(`Cannot delete branch "${sanitizedName}": the database has active connections. Close other clients and try again.`);
+			if (extractPgError(err)?.code === PG_OBJECT_IN_USE) throw new Error(`Cannot delete branch "${name}": the database has active connections. Close other clients and try again.`);
 			throw describeBranchDdlError(err, dbName);
 		}
-		await this.db.execute(sql`DELETE FROM rebase.branches WHERE name = ${sanitizedName}`);
+		await this.db.execute(sql`DELETE FROM rebase.branches WHERE name = ${name}`);
 	}
 	/**
 	* List all branches recorded in the metadata table.
@@ -4188,20 +4395,21 @@ var BranchService = class {
 	* Get info about a specific branch.
 	*/
 	async getBranchInfo(name) {
-		const sanitizedName = sanitizeBranchName(name);
+		assertValidBranchName(name);
 		const rows = (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}
         `)).rows;
 		if (rows.length === 0) return void 0;
 		const row = rows[0];
 		let sizeBytes;
 		try {
-			const dbName = toBranchDbName(sanitizedName);
+			const dbName = row.db_name;
 			const sizeRows = (await this.db.execute(sql`SELECT pg_database_size(${dbName}) as size_bytes`)).rows;
 			if (sizeRows.length > 0 && sizeRows[0].size_bytes != null) sizeBytes = Number(sizeRows[0].size_bytes);
 		} catch {}
@@ -5800,6 +6008,7 @@ var getDrizzleColumn = (propName, prop, collection, collections) => {
 			const isId = isIdProperty(propName, prop, collection);
 			let baseType = numProp.validation?.integer || isId ? `integer("${colName}")` : `numeric("${colName}")`;
 			if (numProp.columnType) if (numProp.columnType === "double precision") baseType = `doublePrecision("${colName}")`;
+			else if (numProp.columnType === "bigint" || numProp.columnType === "bigserial") baseType = `${numProp.columnType}("${colName}", { mode: "number" })`;
 			else baseType = `${numProp.columnType}("${colName}")`;
 			if ("isId" in numProp && numProp.isId === "increment") columnDefinition = `${baseType}.generatedByDefaultAsIdentity()`;
 			else if ("isId" in numProp && typeof numProp.isId === "string" && numProp.isId !== "manual") {
@@ -6152,8 +6361,9 @@ var generateSchema = async (collections, stripPolicies = false) => {
 						if (!emittedRelationNames.has(deduplicationKey)) {
 							const otherTableVar = getTableVarName(getTableName$1(otherCollection));
 							const drizzleFieldKey = resolvePropertyKeyForColumn(collection, otherRel.foreignKeyOnTarget);
+							const referencedKey = otherRel.sourceKey ? resolvePropertyKeyForColumn(otherCollection, otherRel.sourceKey) : getPrimaryKeyName(otherCollection);
 							const synthKey = `_synth_${otherTableVar}_${drizzleFieldKey}`;
-							tableRelations.push(`    "${synthKey}": one(${otherTableVar}, {\n        fields: [${tableVarName}.${drizzleFieldKey}],\n        references: [${otherTableVar}.${getPrimaryKeyName(otherCollection)}],\n        relationName: \"${drizzleRelationName}\"\n    })`);
+							tableRelations.push(`    "${synthKey}": one(${otherTableVar}, {\n        fields: [${tableVarName}.${drizzleFieldKey}],\n        references: [${otherTableVar}.${referencedKey}],\n        relationName: \"${drizzleRelationName}\"\n    })`);
 							emittedRelationNames.add(deduplicationKey);
 						}
 					}
@@ -7311,14 +7521,6 @@ function resolveChannelBusSetting(configured) {
 	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.
-*/
-function resolveChannelBusConfig(configured) {
-	return resolveChannelBusSetting(configured);
-}
-/**
 * Produce the bus a setting asks for.
 *
 * An instance is handed straight back — constructing it was the application's
@@ -8929,7 +9131,7 @@ function createBackupCron(config) {
 		enabled: config.enabled ?? true,
 		timeoutSeconds: 3600,
 		async handler({ log }) {
-			const { createDump, pruneBackups, uploadBackup, validateDump } = await import("./backup-service-DLb2drIH.js").then((n) => n.r);
+			const { createDump, pruneBackups, uploadBackup, validateDump } = await import("./backup-service-CD8o_1Sl.js").then((n) => n.r);
 			const { destination } = config;
 			if (destination.kind !== "local" && !config.storage) throw new Error(`Backup destination is ${destination.kind} but no storage controller was provided. Pass the backend's configured StorageController to createBackupCron({ storage }).`);
 			log(`Starting backup of "${dbName}"…`);
@@ -9060,6 +9262,11 @@ function findRelationDefects(collections, registry) {
 						problem: `\`foreignKeyOnTarget: "${relation.foreignKeyOnTarget}"\` is not a column on the target table \`${targetTableName}\``,
 						fix: `add the column, or set \`foreignKeyOnTarget\` to one of: ${quote(targetColumns)}`
 					});
+					if (relation.sourceKey && !sourceColumns.has(relation.sourceKey)) defects.push({
+						...at,
+						problem: `\`sourceKey: "${relation.sourceKey}"\` is not a column on \`${sourceTableName}\``,
+						fix: targetColumns.has(relation.sourceKey) ? `it is a column on the *target* table \`${targetTableName}\` — \`sourceKey\` names the column on this collection that the target's foreign key points at, so it must be one of: ${quote(sourceColumns)}` : `add the column, or set \`sourceKey\` to one of: ${quote(sourceColumns)}`
+					});
 					break;
 				case "manyToMany": {
 					const { table, sourceColumn, targetColumn } = relation.through;
@@ -9811,21 +10018,6 @@ async function ensureAuthTablesExist(db, collection) {
 }
 //#endregion
 //#region src/auth/services.ts
-function getColumnKey(table, ...keys) {
-	if (!table) return void 0;
-	for (const key of keys) {
-		if (key in table) return key;
-		const snake = toSnakeCase(key);
-		if (snake in table) return snake;
-		const camel = camelCase(key);
-		if (camel in table) return camel;
-	}
-}
-function getColumn(table, ...keys) {
-	if (!table) return void 0;
-	const key = getColumnKey(table, ...keys);
-	return key ? table[key] : void 0;
-}
 /**
 * The single definition of what an email address looks like in storage.
 *
@@ -9840,9 +10032,25 @@ function getColumn(table, ...keys) {
 *
 * Whitespace goes too: a trailing space survives the fold and reproduces the
 * problem exactly.
+*
+* Re-exported rather than defined here: `@rebasepro/server` and
+* `@rebasepro/server-mongo` write this column too, and a second copy of this
+* rule is the defect it exists to prevent.
 */
-function normalizeEmail(email) {
-	return typeof email === "string" ? email.trim().toLowerCase() : email;
+function getColumnKey(table, ...keys) {
+	if (!table) return void 0;
+	for (const key of keys) {
+		if (key in table) return key;
+		const snake = toSnakeCase(key);
+		if (snake in table) return snake;
+		const camel = camelCase(key);
+		if (camel in table) return camel;
+	}
+}
+function getColumn(table, ...keys) {
+	if (!table) return void 0;
+	const key = getColumnKey(table, ...keys);
+	return key ? table[key] : void 0;
 }
 /**
 * PostgreSQL implementation of UserRepository.
@@ -11183,6 +11391,31 @@ function humanize(snakeName) {
 	return snakeName.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
 //#endregion
+//#region src/schema/introspect-db-types.ts
+/**
+* The PostgreSQL type → Rebase property type mapping.
+*
+* Split out of `introspect-db-logic` so that the structural analysis can use it
+* without importing the generator, which imports the analysis. Re-exported from
+* `introspect-db-logic` so existing callers keep their import path.
+*/
+/**
+* Map a PostgreSQL data type to a Rebase property type.
+*/
+function mapPgType(dataType) {
+	const dt = dataType.toLowerCase();
+	if (dt === "interval") return "string";
+	if (dt === "array" || dt.startsWith("_")) return "array";
+	if (dt.includes("int") || dt.includes("numeric") || dt.includes("decimal") || dt.includes("serial") || dt === "real" || dt === "float4" || dt === "float8" || dt === "double precision" || dt === "money") return "number";
+	if (dt.includes("bool")) return "boolean";
+	if (dt.includes("time") || dt.includes("date")) return "date";
+	if (dt === "json" || dt === "jsonb") return "map";
+	if (dt === "bytea") return "binary";
+	if (dt === "inet" || dt === "cidr" || dt === "macaddr" || dt === "macaddr8") return "string";
+	if (dt === "uuid") return "string";
+	return "string";
+}
+//#endregion
 //#region src/schema/introspect-db-logic.ts
 var IRREGULAR_SINGULARS = {
 	people: "person",
@@ -11287,22 +11520,6 @@ function getIconForTable(tableName) {
 	if (table.includes("comment") || table.includes("review") || table.includes("feedback")) return "MessageCircle";
 	return "Database";
 }
-/**
-* Map a PostgreSQL data type to a Rebase property type.
-*/
-function mapPgType(dataType) {
-	const dt = dataType.toLowerCase();
-	if (dt === "interval") return "string";
-	if (dt === "array" || dt.startsWith("_")) return "array";
-	if (dt.includes("int") || dt.includes("numeric") || dt.includes("decimal") || dt.includes("serial") || dt === "real" || dt === "float4" || dt === "float8" || dt === "double precision" || dt === "money") return "number";
-	if (dt.includes("bool")) return "boolean";
-	if (dt.includes("time") || dt.includes("date")) return "date";
-	if (dt === "json" || dt === "jsonb") return "map";
-	if (dt === "bytea") return "binary";
-	if (dt === "inet" || dt === "cidr" || dt === "macaddr" || dt === "macaddr8") return "string";
-	if (dt === "uuid") return "string";
-	return "string";
-}
 function buildEnumMap(enumValues) {
 	const enumMap = /* @__PURE__ */ new Map();
 	for (const ev of enumValues) {
@@ -11322,6 +11539,20 @@ function buildTablesMap(tables, columns, pks, fks) {
 	});
 	return tablesMap;
 }
+/**
+* Join tables, identified by column name.
+*
+* Superseded for the CLI by `classifyTables` in `./introspect-db-structure`,
+* which asks the database instead: two single-column keys, unique together, no
+* payload column, nothing referencing the table. This rule folds away
+* `northwind.order_details` — which has the key shape and carries unit price,
+* quantity and discount — because it recognises `id`, `created_at` and
+* `updated_at` by name and calls everything else a foreign key.
+*
+* Still used by `./introspect-runtime`, which builds collections in memory from
+* a narrower set of catalog queries and has no unique-constraint or row-count
+* data to reason with.
+*/
 function identifyJoinTables(tablesMap) {
 	const joinTables = /* @__PURE__ */ new Set();
 	for (const [tableName, meta] of tablesMap.entries()) if (meta.fks.length === 2) {
@@ -12057,7 +12288,7 @@ function createPostgresBootstrapper(pgConfig) {
 		*/
 		async ensureCollectionSchema(collections, driverResult, log) {
 			const internals = driverResult.internals;
-			const { ensureCollectionTables } = await import("./ensure-collection-tables-CT6xHB1d.js");
+			const { ensureCollectionTables } = await import("./ensure-collection-tables-CBQdOETu.js");
 			const plan = await ensureCollectionTables({ async query(text) {
 				const result = await internals.db.execute(sql.raw(text));
 				return { rows: result.rows ?? (Array.isArray(result) ? result : []) };
@@ -12082,7 +12313,7 @@ function createPostgresBootstrapper(pgConfig) {
 		*/
 		async ensureCollectionPolicies(collections, driverResult, log) {
 			const internals = driverResult.internals;
-			const { ensureCollectionPolicies } = await import("./ensure-collection-policies-Dv21KDMJ.js");
+			const { ensureCollectionPolicies } = await import("./ensure-collection-policies-ViG8XiPn.js");
 			const outcome = await ensureCollectionPolicies({ async query(text) {
 				const result = await internals.db.execute(sql.raw(text));
 				return { rows: result.rows ?? (Array.isArray(result) ? result : []) };
@@ -12136,6 +12367,6 @@ function createPostgresAdapter(pgConfig) {
 	};
 }
 //#endregion
-export { AuthenticatedPostgresBackendDriver, BackupToolError, BranchService, CHANNEL_BUS_NOTIFY_CHANNEL, DEFAULT_BATCH_WINDOW_MS, DatabasePoolManager, DrizzleConditionBuilder, MemoryChannelBus, PG_NOTIFY_MAX_PAYLOAD_BYTES, PostgresBackendDriver, PostgresChannelBus, PostgresCollectionRegistry, PostgresConditionBuilder, PostgresRealtimeProvider, RealtimeService, appConfig, applyGlobals, backupCronConfigFromEnv, buildBackupFilename, buildPgDumpArgs, buildPgDumpallGlobalsArgs, buildPgRestoreArgs, buildPgRestoreListArgs, checkToolServerCompatibility, configureUnknownFilterFields, createAuthSchema, createBackupCron, createChannelBus, createDirectDatabaseConnection, createDump, createPostgresAdapter, createPostgresBootstrapper, createPostgresDatabaseConnection, createPostgresWebSocket, createReadReplicaConnection, detectToolMajor, ensureDatabaseExists, frameByteLength, generateSchema, getServerVersionMajor, getUnknownFilterFieldsMode, globalsFileForDump, guardPoolAgainstDirtyRelease, isChannelBusInstance, joinStorageKey, listBackups, magicLinkTokens, magicLinkTokensRelations, mfaChallenges, mfaChallengesRelations, mfaFactors, mfaFactorsRelations, parseBackupDestination, parseBackupTimestamp, parseChannelBusFrame, parseChannelBusPayload, parseDbNameFromUrl, parsePgToolMajor, passwordResetTokens, passwordResetTokensRelations, pinSearchPath, preflight, pruneBackups, recoveryCodes, recoveryCodesRelations, refreshTokens, refreshTokensRelations, resolveChannelBusConfig, resolveChannelBusSetting, resolveConnectionString, resolveDriftCheckName, resolvePgBinary, restoreDump, selectBackupsToPrune, serverVersionNumToMajor, splitGlobalsStatements, uploadBackup, userIdentities, userIdentitiesRelations, users, usersRelations, usersSchema, validateDump, withDatabaseName };
+export { AuthenticatedPostgresBackendDriver, BackupToolError, BranchService, CHANNEL_BUS_NOTIFY_CHANNEL, DEFAULT_BATCH_WINDOW_MS, DatabasePoolManager, DrizzleConditionBuilder, MemoryChannelBus, PG_NOTIFY_MAX_PAYLOAD_BYTES, PostgresBackendDriver, PostgresChannelBus, PostgresCollectionRegistry, PostgresConditionBuilder, PostgresRealtimeProvider, RealtimeService, appConfig, applyGlobals, backupCronConfigFromEnv, buildBackupFilename, buildPgDumpArgs, buildPgDumpallGlobalsArgs, buildPgRestoreArgs, buildPgRestoreListArgs, buildRowSecurityPgOptions, checkToolServerCompatibility, configureUnknownFilterFields, createAuthSchema, createBackupCron, createChannelBus, createDirectDatabaseConnection, createDump, createPostgresAdapter, createPostgresBootstrapper, createPostgresDatabaseConnection, createPostgresWebSocket, createReadReplicaConnection, detectToolMajor, diagnoseRowSecurityDumpFailure, ensureDatabaseExists, frameByteLength, generateSchema, getServerVersionMajor, getUnknownFilterFieldsMode, globalsFileForDump, guardPoolAgainstDirtyRelease, isChannelBusInstance, joinStorageKey, listBackups, magicLinkTokens, magicLinkTokensRelations, mfaChallenges, mfaChallengesRelations, mfaFactors, mfaFactorsRelations, parseBackupDestination, parseBackupTimestamp, parseChannelBusFrame, parseChannelBusPayload, parseDbNameFromUrl, parsePgToolMajor, passwordResetTokens, passwordResetTokensRelations, pinSearchPath, preflight, pruneBackups, recoveryCodes, recoveryCodesRelations, refreshTokens, refreshTokensRelations, resolveChannelBusSetting, resolveConnectionString, resolveDriftCheckName, resolvePgBinary, restoreDump, selectBackupsToPrune, serverVersionNumToMajor, splitGlobalsStatements, uploadBackup, userIdentities, userIdentitiesRelations, users, usersRelations, usersSchema, validateDump, withDatabaseName };
 
 //# sourceMappingURL=index.es.js.map