@rebasepro/server-postgres 0.12.1-canary.g7f1150f → 0.12.1-canary.g802486a

package/dist/index.es.js

@@ -1,11 +1,12 @@
 import { createRequire as __createRequire } from "module";
 import process from "process";
 __createRequire(import.meta.url);
-import { a as guardPoolAgainstDirtyRelease, i as createReadReplicaConnection, n as createDirectDatabaseConnection, r as createPostgresDatabaseConnection } from "./connection-B5Wndbr1.js";
-import { C as updateDateAutoValues, D as camelCase, E as mergeDeep, M as hasForeignKeyOnTarget, N as isManyToMany, O as toSnakeCase, P as Vector, S as normalizeToEntityRelation, T as getPolicyNamesForRule, _ 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, j as ANONYMOUS_USER_ID, 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-DihrDFuP.js";
+import { a as guardPoolAgainstDirtyRelease, i as createReadReplicaConnection, n as createDirectDatabaseConnection, o as pinSearchPath, r as createPostgresDatabaseConnection } from "./connection-BuZ97wsr.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 createPostgresWebSocket } from "./websocket-BKcGvILX.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-DH9kPg-E.js";
+import { t as ANONYMOUS_USER_ID } from "./policy-CeA1JcxP.js";
+import { t as createPostgresWebSocket } from "./websocket-B2LsrINK.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";
@@ -49,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.
@@ -194,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) {
@@ -281,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.
 *
@@ -451,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();
@@ -541,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);
@@ -1345,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);
@@ -1614,6 +1705,33 @@ function normalizeDbValues(data, collection) {
 //#endregion
 //#region src/services/RelationService.ts
 /**
+* The ids in a to-many relation write, whatever shape the caller sent.
+*
+* A membership list is written as either the related rows (`[{ id: 1 }]`, what
+* the admin UI sends back after reading them) or as bare keys (`[1]`, `["t-1"]`,
+* what anyone writing the API by hand sends). Only the first was read, via a
+* blind `.map(rel => rel.id)`, and a bare key therefore became `undefined`:
+* on a numeric-keyed target that surfaced as `Invalid numeric ID: undefined`,
+* and on a string-keyed one it did not surface at all — `String(undefined)`
+* wrote a junction row pointing at the literal `"undefined"`, which no read
+* would ever match. Both shapes are accepted here, in one place, because both
+* call sites had the same assumption.
+*
+* An element that carries no key is refused rather than skipped: dropping it
+* would silently write a shorter membership list than the caller asked for.
+*/
+function relationTargetIds(value, relationName, collectionSlug) {
+	if (!Array.isArray(value)) return [];
+	return value.map((element, index) => {
+		if (typeof element === "string" || typeof element === "number") return element;
+		if (element && typeof element === "object") {
+			const id = element.id;
+			if (typeof id === "string" || typeof id === "number") return id;
+		}
+		throw new Error(`Cannot write relation "${relationName}" on "${collectionSlug}": element ${index} carries no id. Pass either the related rows (\`[{ id: … }]\`) or their keys (\`[1, 2]\`), not ${element === null ? "null" : typeof element}.`);
+	});
+}
+/**
 * Typed wrapper for Drizzle dynamic query innerJoin.
 * Drizzle's `$dynamic()` queries lose the `innerJoin` method from
 * their static type, but it exists at runtime. This helper bridges
@@ -1691,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
@@ -1751,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) {
@@ -1759,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 [];
@@ -1802,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);
 	}
@@ -1930,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;
 	}
@@ -2018,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));
@@ -2045,7 +2240,7 @@ var RelationService = class {
 		for (const [key, value] of Object.entries(relationValues)) {
 			const relation = findRelation(resolvedRelations, key);
 			if (!relation || relation.cardinality !== "many") continue;
-			const targetEntityIds = value && Array.isArray(value) ? value.map((rel) => rel.id) : [];
+			const targetEntityIds = relationTargetIds(value, key, collection.slug);
 			const targetCollection = relation.target();
 			if (relation.kind === "via") {
 				const parentTableName = getTableName$1(collection);
@@ -2127,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.`);
 		}
 	}
@@ -2149,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;
@@ -2172,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 });
@@ -2225,7 +2419,7 @@ var RelationService = class {
 				if (newValue && Array.isArray(newValue) && newValue.length > 0) {
 					const targetPks = requirePrimaryKeys(targetCollection, this.registry);
 					const targetIdInfo = targetPks[0];
-					const newLinks = newValue.map((rel) => typeof rel === "object" && rel !== null ? rel.id : rel).map((id) => parseIdValues(id, targetPks)[targetIdInfo.fieldName]).map((targetId) => ({
+					const newLinks = relationTargetIds(newValue, relation.relationName, sourceCollection.slug).map((id) => parseIdValues(id, targetPks)[targetIdInfo.fieldName]).map((targetId) => ({
 						[sourceJunctionColumn.name]: parsedSourceId,
 						[targetJunctionColumn.name]: targetId
 					}));
@@ -2269,7 +2463,7 @@ var RelationService = class {
 			if (newValue && Array.isArray(newValue) && newValue.length > 0) {
 				const targetPks = requirePrimaryKeys(targetCollection, this.registry);
 				const targetIdInfo = targetPks[0];
-				const newLinks = newValue.map((rel) => rel.id).map((id) => parseIdValues(id, targetPks)[targetIdInfo.fieldName]).map((targetId) => ({
+				const newLinks = relationTargetIds(newValue, relation.relationName, sourceCollection.slug).map((id) => parseIdValues(id, targetPks)[targetIdInfo.fieldName]).map((targetId) => ({
 					[sourceJunctionColumn.name]: parsedSourceId,
 					[targetJunctionColumn.name]: targetId
 				}));
@@ -2484,7 +2678,7 @@ function relationTargetAddress(targetRow, targetCollection, registry) {
 * expects real types. The row's own address is *not* among the columns — it is
 * derived by the consumer from the collection's primary keys.
 */
-function toCmsRow(row, collection, registry) {
+function toFlatRow(row, collection, registry) {
 	const resolvedRelations = resolveCollectionRelations(collection);
 	const normalized = normalizeDbValues(row, collection);
 	for (const [key, relation] of Object.entries(resolvedRelations)) {
@@ -2599,235 +2793,494 @@ 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);
-	}
-	/**
-	* 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;
-		if (collection) {
-			const relation = resolveCollectionRelations(collection)[orderBy];
-			if (relation?.kind === "belongsTo") {
-				const foreignKey = columnAt(relation.localKey);
-				if (foreignKey) return foreignKey;
-			}
-		}
-		for (const guess of [`${orderBy}_id`, generateForeignKeyName(orderBy)]) {
-			const foreignKey = columnAt(guess);
-			if (foreignKey) return foreignKey;
-		}
-	}
-	/**
-	* Build the `with` config for Drizzle's relational query API.
-	* Converts collection relations to a Drizzle-compatible `with` object.
-	*
-	* When `include` is provided, only those relations are loaded.
-	* When `include` is absent, ALL relations are loaded (the admin path).
-	*
-	* Automatically detects many-to-many junction tables and nests
-	* the target relation so actual row data is returned.
-	*/
-	buildWithConfig(collection, include) {
-		const resolvedRelations = resolveCollectionRelations(collection);
-		const withConfig = {};
-		const shouldInclude = (key) => !include || include.length === 0 || include[0] === "*" || include.includes(key);
-		for (const [key, relation] of Object.entries(resolvedRelations)) {
-			if (!shouldInclude(key)) continue;
-			const drizzleRelName = relation.relationName || key;
-			if (relation.kind === "via") continue;
-			if (relation.cardinality === "many" && isJunctionRelation(relation)) {
-				const targetFkName = this.getJunctionTargetRelationName(relation, collection);
-				if (targetFkName) withConfig[drizzleRelName] = { with: { [targetFkName]: true } };
-				else withConfig[drizzleRelName] = true;
-			} else withConfig[drizzleRelName] = true;
-		}
-		return withConfig;
-	}
-	/**
-	* Get the Drizzle relation name on the junction table that points to the actual target row.
-	* For example, for posts_tags junction, this returns "tag_id" (the relation pointing to tags).
-	*/
-	getJunctionTargetRelationName(relation, _collection) {
-		if (isManyToMany(relation)) return relation.through.targetColumn.replace(/_id$/, "_id");
+/**
+* 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;
 	}
-	/**
-	* Post-fetch joinPath relations for a single flat row.
-	* joinPath relations cannot be expressed via Drizzle's `with` config,
-	* so they must be loaded separately after the primary query.
-	*/
-	async resolveJoinPathRelations(row, collection, collectionPath, parsedId, _databaseId) {
-		const resolvedRelations = resolveCollectionRelations(collection);
-		const promises = Object.entries(resolvedRelations).filter(([key, relation]) => relation.kind === "via").map(async ([key, relation]) => {
-			try {
-				const relatedRows = await this.relationService.fetchRelatedEntities(collectionPath, parsedId, key, { limit: relation.cardinality === "one" ? 1 : void 0 });
-				if (relation.cardinality === "one" && relatedRows.length > 0) {
-					const e = relatedRows[0];
-					row[key] = createRelationRefWithData(e.id, e.path, e);
-				} else if (relation.cardinality === "many") row[key] = relatedRows.map((e) => createRelationRefWithData(e.id, e.path, e));
-			} catch (e) {
-				logger.warn(`Could not resolve joinPath relation '${key}'`, { error: e });
-			}
-		});
-		await Promise.all(promises);
+	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;
 	}
-	/**
-	* Resolves joinPath relations for raw REST rows and directly injects them.
-	* Uses RelationService to query the database and maps results back to the flattened objects.
-	*/
-	async resolveJoinPathRelationsBatchRest(rows, collection, collectionPath, idInfoArray, include) {
-		if (rows.length === 0) return;
-		const resolvedRelations = resolveCollectionRelations(collection);
-		const propertyKeys = new Set(Object.keys(collection.properties || {}));
-		const shouldInclude = (key) => !include || include.length === 0 || include[0] === "*" || include.includes(key);
-		const joinPathRelations = Object.entries(resolvedRelations).filter(([key, relation]) => relation.kind === "via" && propertyKeys.has(key) && shouldInclude(key));
-		if (joinPathRelations.length === 0) return;
-		const parentIdOf = (row) => {
-			const address = buildCompositeId(row, idInfoArray);
-			return address && address.split(":::").some((part) => part !== "") ? address : 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
 		};
-		for (const [key, relation] of joinPathRelations) try {
-			const addressable = rows.filter((r) => parentIdOf(r) !== void 0 && parentIdOf(r) !== null);
-			if (addressable.length === 0) continue;
-			const rowIds = addressable.map((r) => parentIdOf(r));
-			if (relation.cardinality === "one") {
-				const resultMap = await this.relationService.batchFetchRelatedEntities(collectionPath, rowIds, key, relation);
-				for (const row of addressable) {
-					const relatedRow = resultMap.get(String(parentIdOf(row)));
-					row[key] = relatedRow ? { ...relatedRow.values } : null;
-				}
-			} else if (relation.cardinality === "many") {
-				const resultMap = await this.relationService.batchFetchRelatedEntitiesMany(collectionPath, rowIds, key, relation);
-				for (const row of addressable) row[key] = (resultMap.get(String(parentIdOf(row))) || []).map((e) => ({ ...e.values }));
-			}
-		} catch (e) {
-			logger.warn(`Could not batch resolve joinPath relation '${key}' for REST`, { error: e });
+		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);
+	}
 	/**
-	* Build db.query-compatible options from standard fetch options.
-	* Handles filter, search, orderBy, limit, and cursor-based pagination.
+	* Get the relational query builder for a given table name.
+	* Safely narrows the DrizzleClient union type to access db.query[tableName].
 	*/
-	buildDrizzleQueryOptions(table, idField, idInfo, options, collectionPath, withConfig, scopeCondition) {
-		const queryOpts = {};
-		if (withConfig) queryOpts.with = withConfig;
-		const allConditions = [];
-		if (scopeCondition) allConditions.push(scopeCondition);
-		if (options.searchString) {
-			const collection = getCollectionByPath(collectionPath, this.registry);
-			const searchConditions = DrizzleConditionBuilder.buildSearchConditions(options.searchString, collection.properties, table);
-			if (searchConditions.length === 0) {
-				queryOpts.where = and(eq(idField, -99999999));
-				return queryOpts;
-			}
-			allConditions.push(DrizzleConditionBuilder.combineConditionsWithOr(searchConditions));
-		}
-		if (options.filter) {
-			const filterConditions = this.buildFilterConditions(options.filter, table, collectionPath);
-			if (filterConditions.length > 0) allConditions.push(...filterConditions);
-		}
-		if (options.logical) {
-			const logicalCondition = DrizzleConditionBuilder.buildLogicalConditions(options.logical, table, collectionPath, this.filterContext(collectionPath, table));
-			if (logicalCondition) allConditions.push(logicalCondition);
-		}
-		if (options.startAfter) {
-			const cursorConditions = this.buildCursorConditions(table, idField, idInfo, options, collectionPath);
-			if (cursorConditions.length > 0) allConditions.push(...cursorConditions);
-		}
-		if (allConditions.length > 0) queryOpts.where = and(...allConditions);
-		const orderExpressions = [];
-		if (options.orderBy) {
-			const collection = getCollectionByPath(collectionPath, this.registry);
-			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) queryOpts.orderBy = orderExpressions;
-		const limitValue = options.searchString ? options.limit || 50 : options.limit;
-		if (limitValue) queryOpts.limit = limitValue;
-		if (options.offset && options.offset > 0) queryOpts.offset = options.offset;
-		return queryOpts;
+	getQueryBuilder(tableName) {
+		return this.db.query?.[tableName];
 	}
 	/**
-	* Extract cursor pagination conditions from startAfter options.
-	*/
-	buildCursorConditions(table, idField, idInfo, options, collectionPath) {
+	* 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)]) {
+			const foreignKey = columnAt(guess);
+			if (foreignKey) return foreignKey;
+		}
+		const collectionName = collection?.slug ?? collection?.name;
+		const onCollection = collectionName ? ` on collection '${collectionName}'` : "";
+		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;
+		}
+		let validFields = [];
+		try {
+			validFields = Object.keys(getTableColumns(table)).sort();
+		} catch {}
+		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 }
+		});
+	}
+	/**
+	* Build the `with` config for Drizzle's relational query API.
+	* Converts collection relations to a Drizzle-compatible `with` object.
+	*
+	* When `include` is provided, only those relations are loaded.
+	* When `include` is absent, ALL relations are loaded (the admin path).
+	*
+	* Automatically detects many-to-many junction tables and nests
+	* the target relation so actual row data is returned.
+	*/
+	buildWithConfig(collection, include) {
+		const resolvedRelations = resolveCollectionRelations(collection);
+		const withConfig = {};
+		const shouldInclude = (key) => !include || include.length === 0 || include[0] === "*" || include.includes(key);
+		for (const [key, relation] of Object.entries(resolvedRelations)) {
+			if (!shouldInclude(key)) continue;
+			const drizzleRelName = relation.relationName || key;
+			if (relation.kind === "via") continue;
+			if (relation.cardinality === "many" && isJunctionRelation(relation)) {
+				const targetFkName = this.getJunctionTargetRelationName(relation, collection);
+				if (targetFkName) withConfig[drizzleRelName] = { with: { [targetFkName]: true } };
+				else withConfig[drizzleRelName] = true;
+			} else withConfig[drizzleRelName] = true;
+		}
+		return withConfig;
+	}
+	/**
+	* Get the Drizzle relation name on the junction table that points to the actual target row.
+	* For example, for posts_tags junction, this returns "tag_id" (the relation pointing to tags).
+	*/
+	getJunctionTargetRelationName(relation, _collection) {
+		if (isManyToMany(relation)) return relation.through.targetColumn.replace(/_id$/, "_id");
+		return null;
+	}
+	/**
+	* Post-fetch joinPath relations for a single flat row.
+	* joinPath relations cannot be expressed via Drizzle's `with` config,
+	* so they must be loaded separately after the primary query.
+	*/
+	async resolveJoinPathRelations(row, collection, collectionPath, parsedId, _databaseId) {
+		const resolvedRelations = resolveCollectionRelations(collection);
+		const promises = Object.entries(resolvedRelations).filter(([key, relation]) => relation.kind === "via").map(async ([key, relation]) => {
+			try {
+				const relatedRows = await this.relationService.fetchRelatedEntities(collectionPath, parsedId, key, { limit: relation.cardinality === "one" ? 1 : void 0 });
+				if (relation.cardinality === "one" && relatedRows.length > 0) {
+					const e = relatedRows[0];
+					row[key] = createRelationRefWithData(e.id, e.path, e);
+				} else if (relation.cardinality === "many") row[key] = relatedRows.map((e) => createRelationRefWithData(e.id, e.path, e));
+			} catch (e) {
+				logger.warn(`Could not resolve joinPath relation '${key}'`, { error: e });
+			}
+		});
+		await Promise.all(promises);
+	}
+	/**
+	* Resolves joinPath relations for raw REST rows and directly injects them.
+	* Uses RelationService to query the database and maps results back to the flattened objects.
+	*/
+	async resolveJoinPathRelationsBatchRest(rows, collection, collectionPath, idInfoArray, include) {
+		if (rows.length === 0) return;
+		const resolvedRelations = resolveCollectionRelations(collection);
+		const propertyKeys = new Set(Object.keys(collection.properties || {}));
+		const shouldInclude = (key) => !include || include.length === 0 || include[0] === "*" || include.includes(key);
+		const joinPathRelations = Object.entries(resolvedRelations).filter(([key, relation]) => relation.kind === "via" && propertyKeys.has(key) && shouldInclude(key));
+		if (joinPathRelations.length === 0) return;
+		const parentIdOf = (row) => {
+			const address = buildCompositeId(row, idInfoArray);
+			return address && address.split(":::").some((part) => part !== "") ? address : void 0;
+		};
+		for (const [key, relation] of joinPathRelations) try {
+			const addressable = rows.filter((r) => parentIdOf(r) !== void 0 && parentIdOf(r) !== null);
+			if (addressable.length === 0) continue;
+			const rowIds = addressable.map((r) => parentIdOf(r));
+			if (relation.cardinality === "one") {
+				const resultMap = await this.relationService.batchFetchRelatedEntities(collectionPath, rowIds, key, relation);
+				for (const row of addressable) {
+					const relatedRow = resultMap.get(String(parentIdOf(row)));
+					row[key] = relatedRow ? { ...relatedRow.values } : null;
+				}
+			} else if (relation.cardinality === "many") {
+				const resultMap = await this.relationService.batchFetchRelatedEntitiesMany(collectionPath, rowIds, key, relation);
+				for (const row of addressable) row[key] = (resultMap.get(String(parentIdOf(row))) || []).map((e) => ({ ...e.values }));
+			}
+		} catch (e) {
+			logger.warn(`Could not batch resolve joinPath relation '${key}' for REST`, { error: e });
+		}
+	}
+	/**
+	* Build db.query-compatible options from standard fetch options.
+	* Handles filter, search, orderBy, limit, and cursor-based pagination.
+	*/
+	buildDrizzleQueryOptions(table, idField, idInfo, options, collectionPath, withConfig, scopeCondition) {
+		const queryOpts = {};
+		if (withConfig) queryOpts.with = withConfig;
+		const allConditions = [];
+		if (scopeCondition) allConditions.push(scopeCondition);
+		if (options.searchString) {
+			const collection = getCollectionByPath(collectionPath, this.registry);
+			const searchConditions = DrizzleConditionBuilder.buildSearchConditions(options.searchString, collection.properties, table);
+			if (searchConditions.length === 0) {
+				queryOpts.where = and(eq(idField, -99999999));
+				return queryOpts;
+			}
+			allConditions.push(DrizzleConditionBuilder.combineConditionsWithOr(searchConditions));
+		}
+		if (options.filter) {
+			const filterConditions = this.buildFilterConditions(options.filter, table, collectionPath);
+			if (filterConditions.length > 0) allConditions.push(...filterConditions);
+		}
+		if (options.logical) {
+			const logicalCondition = DrizzleConditionBuilder.buildLogicalConditions(options.logical, table, collectionPath, this.filterContext(collectionPath, table));
+			if (logicalCondition) allConditions.push(logicalCondition);
+		}
+		if (options.startAfter) {
+			const cursorConditions = this.buildCursorConditions(table, idField, idInfo, options, collectionPath);
+			if (cursorConditions.length > 0) allConditions.push(...cursorConditions);
+		}
+		if (allConditions.length > 0) queryOpts.where = and(...allConditions);
+		const orderExpressions = [];
+		if (options.orderBy) {
+			const collection = getCollectionByPath(collectionPath, this.registry);
+			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) queryOpts.orderBy = orderExpressions;
+		const limitValue = options.searchString ? options.limit || 50 : options.limit;
+		if (limitValue) queryOpts.limit = limitValue;
+		if (options.offset && options.offset > 0) queryOpts.offset = options.offset;
+		return queryOpts;
+	}
+	/**
+	* Extract cursor pagination conditions from startAfter options.
+	*/
+	buildCursorConditions(table, idField, idInfo, options, collectionPath) {
 		if (!options.startAfter) return [];
 		const cursor = options.startAfter;
 		if (options.orderBy) {
@@ -2895,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);
@@ -2905,7 +3359,7 @@ var FetchService = class {
 				with: withConfig
 			});
 			if (!row) return void 0;
-			const flatRow = toCmsRow(row, collection, this.registry);
+			const flatRow = toFlatRow(row, collection, this.registry);
 			await this.resolveJoinPathRelations(flatRow, collection, collectionPath, parsedId, databaseId);
 			return flatRow;
 		} catch (e) {
@@ -2913,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);
@@ -2960,12 +3415,13 @@ var FetchService = class {
 		const hasRelations = withConfig && Object.keys(withConfig).length > 0;
 		if (qb && !options.searchString && !hasRelations && !options.vectorSearch) try {
 			const queryOpts = this.buildDrizzleQueryOptions(table, idField, idInfo, options, collectionPath, void 0, scopeCondition);
-			return (await qb.findMany(queryOpts)).map((row) => toCmsRow(row, collection, this.registry));
+			return (await qb.findMany(queryOpts)).map((row) => toFlatRow(row, collection, this.registry));
 		} catch (e) {
 			if (e instanceof Error && e.message.includes("not enough information to infer relation")) {
 				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;
@@ -3023,7 +3479,7 @@ var FetchService = class {
 	/**
 	* 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.
 	*
@@ -3116,6 +3572,10 @@ var FetchService = class {
 			const filterConditions = this.buildFilterConditions(options.filter, table, effectivePath);
 			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);
@@ -3181,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);
@@ -3226,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);
@@ -3244,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);
@@ -3284,346 +3747,123 @@ var FetchService = class {
 		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
-			};
+		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;
 	}
-}
-/**
-* 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 }
-		};
+	/**
+	* 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);
 	}
-	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);
+	/**
+	* 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;
+		}
 	}
-	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.` };
-}
+	/**
+	* 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
 /**
@@ -3747,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;
 				}
 			}
 		}
@@ -4024,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.
 */
-function sanitizeBranchName(name) {
-	return name.replace(/[^a-zA-Z0-9_]/g, "");
+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 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;
@@ -4073,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, "\"\"");
@@ -4086,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
 		};
@@ -4099,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.
@@ -4138,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 {}
@@ -5028,9 +5286,10 @@ var PostgresBackendDriver = class PostgresBackendDriver {
 	async checkUniqueField(path, name, value, id, collection) {
 		return this.dataService.checkUniqueField(path, name, value, id, collection?.databaseId);
 	}
-	async count({ path, collection, filter, searchString }) {
+	async count({ path, collection, filter, logical, searchString }) {
 		return this.dataService.count(path, {
 			filter,
+			logical,
 			searchString
 		});
 	}
@@ -5399,7 +5658,7 @@ var DatabasePoolManager = class {
 		const url = new URL(this.rootConnectionString);
 		url.pathname = `/${databaseName}`;
 		const pool = new Pool({
-			connectionString: url.toString(),
+			connectionString: pinSearchPath(url.toString()),
 			max: 10,
 			idleTimeoutMillis: 1e4,
 			allowExitOnIdle: true
@@ -5749,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") {
@@ -5987,8 +6247,7 @@ var generateSchema = async (collections, stripPolicies = false) => {
 		const tableVarName = getTableVarName(tableName);
 		if (isJunction && relation && sourceCollection && isManyToMany(relation)) {
 			const targetCollection = relation.target();
-			const schema = (isPostgresCollectionConfig(targetCollection) ? targetCollection.schema : void 0) || (isPostgresCollectionConfig(sourceCollection) ? sourceCollection.schema : void 0);
-			const tableCreator = schema ? `${schema}Schema.table` : "pgTable";
+			const tableCreator = "pgTable";
 			const baseTableName = tableName.includes(".") ? tableName.split(".").pop() : tableName;
 			const { sourceColumn, targetColumn } = relation.through;
 			const refOptions = `{ onDelete: \"${relation.onDelete ?? "cascade"}\" }`;
@@ -6102,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);
 						}
 					}
@@ -7261,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
@@ -7745,7 +7997,7 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 		if (this.driver) {
 			const collection = this.registry.getCollectionByPath(notifyPath);
 			const activeAuth = authContext || {
-				uid: "anon",
+				uid: "anonymous",
 				roles: ["anon"]
 			};
 			return await this.db.transaction(async (tx) => {
@@ -7874,7 +8126,7 @@ var RealtimeService = class RealtimeService extends EventEmitter {
 		if (this.driver) {
 			const collection = this.registry.getCollectionByPath(notifyPath);
 			const activeAuth = authContext || {
-				uid: "anon",
+				uid: "anonymous",
 				roles: ["anon"]
 			};
 			return await this.db.transaction(async (tx) => {
@@ -8879,7 +9131,7 @@ function createBackupCron(config) {
 		enabled: config.enabled ?? true,
 		timeoutSeconds: 3600,
 		async handler({ log }) {
-			const { createDump, pruneBackups, uploadBackup, validateDump } = await import("./backup-service-DH9kPg-E.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}"…`);
@@ -9010,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;
@@ -9761,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.
 *
@@ -9790,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.
@@ -11133,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",
@@ -11148,6 +11431,36 @@ var IRREGULAR_SINGULARS = {
 	criteria: "criterion",
 	phenomena: "phenomenon"
 };
+/**
+* Plurals in "-ves" whose singular really ends in f/fe, and which of the two.
+*
+* A blanket "-ves" -> "-f" rule gets `knives` -> `knif`, and mangles every
+* ordinary "-ive" noun that happens to be plural along with it: `archives` ->
+* `archif`, `objectives` -> `objectif`. The set of English words that genuinely
+* swap f/fe for ves is small and closed, so it is listed rather than guessed —
+* anything else ending in "ves" drops the trailing 's' like any other plural.
+*
+* Matched on the whole word, not on the suffix: `olives` ends in `lives`.
+*/
+var VES_SINGULAR_ENDINGS = {
+	calves: "f",
+	dwarves: "f",
+	elves: "f",
+	halves: "f",
+	hooves: "f",
+	leaves: "f",
+	loaves: "f",
+	scarves: "f",
+	selves: "f",
+	sheaves: "f",
+	shelves: "f",
+	thieves: "f",
+	wharves: "f",
+	wolves: "f",
+	knives: "fe",
+	lives: "fe",
+	wives: "fe"
+};
 /** Words ending in 's' that are already singular. */
 var UNCOUNTABLE = /* @__PURE__ */ new Set([
 	"status",
@@ -11186,7 +11499,7 @@ function singularize(word) {
 	if (UNCOUNTABLE.has(lower)) return word;
 	if (lower.endsWith("ices") && lower.length > 5) return word.slice(0, -4) + "ex";
 	if (lower.endsWith("ies") && lower.length > 3) return word.slice(0, -3) + "y";
-	if (lower.endsWith("ves")) return word.slice(0, -3) + "f";
+	if (VES_SINGULAR_ENDINGS[lower]) return word.slice(0, -3) + VES_SINGULAR_ENDINGS[lower];
 	if (lower.endsWith("ches") || lower.endsWith("shes") || lower.endsWith("sses") || lower.endsWith("xes") || lower.endsWith("zes")) return word.slice(0, -2);
 	if (lower.endsWith("ses") && !lower.endsWith("sses")) return word.slice(0, -1);
 	if (lower.endsWith("s") && !lower.endsWith("ss") && !lower.endsWith("us") && !lower.endsWith("is")) return word.slice(0, -1);
@@ -11207,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) {
@@ -11242,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) {
@@ -11620,6 +11931,32 @@ function isEconnrefused(err) {
 * Implements the `BackendBootstrapper` interface for PostgreSQL.
 */
 /**
+* Which table name the boot-time drift check should look for, for one collection.
+*
+* A declared `table` IS the table name, not a hint to be second-guessed. This
+* used to ask the registry whether it had indexed the declared name and fall
+* back to the SLUG when it had not — but "the registry does not know this table"
+* is exactly the condition the drift check exists to report, so the fallback
+* fired precisely when it was most harmful.
+*
+* A collection with `slug: "usage-daily", table: "usage_daily"` was reported as
+* missing table `usage-daily`: a name that does not exist, should never exist,
+* and that nobody can find by looking. Worse, the remediation the caller prints
+* says to run `rebase db push` — which would then CREATE that invented table
+* beside the correct one, the same "second copy" hazard the misplaced-schema
+* branch further down exists to prevent. Seen in production, where a correctly
+* migrated database reported drift on every boot.
+*
+* The slug is used only when nothing was declared, which is the config shape
+* where the slug genuinely is the table name.
+*
+* Exported for its own test: the caller needs a live pool and a real database,
+* and this is the part that was wrong.
+*/
+function resolveDriftCheckName(col, registeredTableNames) {
+	return (isRelationalCollectionConfig(col) ? col.table : void 0) ?? registeredTableNames.find((k) => k === col.slug) ?? col.slug;
+}
+/**
 * Default PostgreSQL bootstrapper.
 *
 * Use it to register Postgres with `initializeRebaseBackend()`:
@@ -11708,7 +12045,7 @@ function createPostgresBootstrapper(pgConfig) {
 			let readDb;
 			const readUrl = process.env.DATABASE_READ_URL;
 			if (readUrl && readUrl !== pgConfig.connectionString) try {
-				const { createReadReplicaConnection } = await import("./connection-B5Wndbr1.js").then((n) => n.t);
+				const { createReadReplicaConnection } = await import("./connection-BuZ97wsr.js").then((n) => n.t);
 				readDb = createReadReplicaConnection(readUrl, mergedSchema).db;
 				logger.info("📖 [PostgresBootstrapper] Read replica connection established");
 			} catch (err) {
@@ -11810,39 +12147,59 @@ function createPostgresBootstrapper(pgConfig) {
 			try {
 				const registeredCollections = registry.getCollections();
 				if (registeredCollections.length > 0) {
-					const schemasList = Array.from(new Set(registeredCollections.map((c) => "schema" in c && c.schema ? c.schema : "public"))).map((s) => `'${s}'`).join(",");
 					const result = await schemaAwareDb.execute(sql.raw(`
                         SELECT table_name, table_schema
                         FROM information_schema.tables
-                        WHERE table_schema IN (${schemasList})
+                        WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
                           AND table_type = 'BASE TABLE'
                     `));
+					const tablesByName = /* @__PURE__ */ new Map();
+					for (const row of result.rows) {
+						const schemas = tablesByName.get(row.table_name) ?? [];
+						schemas.push(row.table_schema);
+						tablesByName.set(row.table_name, schemas);
+					}
 					const dbTables = new Set(result.rows.map((r) => r.table_schema === "public" ? r.table_name : `${r.table_schema}.${r.table_name}`));
 					const missing = [];
 					for (const col of registeredCollections) {
 						if (col.auth?.enabled) continue;
 						const schemaName = "schema" in col && col.schema ? col.schema : "public";
-						const declaredTable = isRelationalCollectionConfig(col) ? col.table : void 0;
-						const tableName = registry.hasTableForCollection(declaredTable ?? col.slug) ? declaredTable ?? col.slug : col.slug;
-						const checkName = registry.getTableNames().find((k) => k === tableName || k === col.slug) ?? tableName;
+						const checkName = resolveDriftCheckName(col, registry.getTableNames());
 						const fullCheckName = schemaName === "public" ? checkName : `${schemaName}.${checkName}`;
 						if (!dbTables.has(fullCheckName)) missing.push({
 							slug: col.slug,
-							table: fullCheckName
+							table: fullCheckName,
+							foundIn: (tablesByName.get(checkName) ?? []).filter((s) => s !== schemaName)
 						});
 					}
 					if (missing.length > 0) {
-						const lines = missing.map((m) => `    • collection "${m.slug}" → table "${m.table}"`);
+						const lines = missing.map((m) => `    • collection "${m.slug}" → table "${m.table}"` + (m.foundIn.length > 0 ? ` — but a table of that name exists in ${m.foundIn.map((s) => `"${s}"`).join(", ")}` : ""));
+						const misplaced = missing.filter((m) => m.foundIn.length > 0);
+						const misplacedHelp = misplaced.length === 0 ? [] : [
+							"  Those tables exist — in the wrong schema. Unqualified SQL run by a",
+							"  role whose name matches a schema (`rebase` is both, by default)",
+							"  resolves through search_path's \"$user\" and creates there. Move them:",
+							...misplaced.map((m) => `      ALTER TABLE "${m.foundIn[0]}"."${m.table.split(".").pop()}" SET SCHEMA "${m.table.includes(".") ? m.table.split(".")[0] : "public"}";`),
+							"  and qualify the SQL that created them, or pin search_path in DATABASE_URL",
+							"  (`?options=-c%20search_path%3Dpublic`).",
+							""
+						];
 						logger.warn([
 							"",
 							"⚠️  SCHEMA DRIFT — the database is missing tables this backend serves:",
 							...lines,
 							"",
+							...misplacedHelp,
 							"  This runtime applies the collection schema at boot unless",
 							"  REBASE_MIGRATE_ON_BOOT=none. Check the \"Collection schema\" / \"policies\"",
 							"  log lines above — this drift means that step was off, skipped, or failed.",
-							"    • Managed cloud: redeploy (or restart) with REBASE_MIGRATE_ON_BOOT",
-							"      unset or \"ensure\"; the runtime applies the schema to the tenant DB.",
+							"    • Managed cloud: redeploy with REBASE_MIGRATE_ON_BOOT unset or",
+							"      \"ensure\"; the runtime applies the schema to the tenant DB.",
+							"      If the log above says the driver does not implement collection-table",
+							"      creation, THIS driver is too old to do it. A driver is installed from",
+							"      your bundle's dependencies, not supplied by the platform image, so a",
+							"      newer runtime will not update it: bump \"@rebasepro/server-postgres\"",
+							"      in your project's package.json and redeploy.",
 							"    • Self-host: run `rebase db push` (dev) or `rebase db migrate` (prod)",
 							"      against DATABASE_URL.",
 							""
@@ -11931,7 +12288,7 @@ function createPostgresBootstrapper(pgConfig) {
 		*/
 		async ensureCollectionSchema(collections, driverResult, log) {
 			const internals = driverResult.internals;
-			const { ensureCollectionTables } = await import("./ensure-collection-tables-DmOzh_G6.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 : []) };
@@ -11956,7 +12313,7 @@ function createPostgresBootstrapper(pgConfig) {
 		*/
 		async ensureCollectionPolicies(collections, driverResult, log) {
 			const internals = driverResult.internals;
-			const { ensureCollectionPolicies } = await import("./ensure-collection-policies-t875gSJF.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 : []) };
@@ -11970,7 +12327,7 @@ function createPostgresBootstrapper(pgConfig) {
 		},
 		mountRoutes(app, basePath, driverResult) {},
 		async initializeWebsockets(server, realtimeService, driver, config, adapter) {
-			const { createPostgresWebSocket } = await import("./websocket-BKcGvILX.js").then((n) => n.n);
+			const { createPostgresWebSocket } = await import("./websocket-B2LsrINK.js").then((n) => n.n);
 			createPostgresWebSocket(server, realtimeService, driver, config, adapter);
 		}
 	};
@@ -11996,8 +12353,8 @@ function createPostgresAdapter(pgConfig) {
 		async initializeHistory(config, driverResult) {
 			if (bootstrapper.initializeHistory) return bootstrapper.initializeHistory(config, driverResult);
 		},
-		initializeWebsockets(server, realtimeService, driver, config) {
-			if (bootstrapper.initializeWebsockets) return bootstrapper.initializeWebsockets(server, realtimeService, driver, config);
+		initializeWebsockets(server, realtimeService, driver, config, adapter) {
+			if (bootstrapper.initializeWebsockets) return bootstrapper.initializeWebsockets(server, realtimeService, driver, config, adapter);
 		},
 		ensureCollectionSchema: bootstrapper.ensureCollectionSchema ? (collections, driverResult, log) => bootstrapper.ensureCollectionSchema(collections, driverResult, log) : void 0,
 		ensureCollectionPolicies: bootstrapper.ensureCollectionPolicies ? (collections, driverResult, log) => bootstrapper.ensureCollectionPolicies(collections, driverResult, log) : void 0,
@@ -12010,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, preflight, pruneBackups, recoveryCodes, recoveryCodesRelations, refreshTokens, refreshTokensRelations, resolveChannelBusConfig, resolveChannelBusSetting, resolveConnectionString, 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