@atscript/db-postgres 0.1.146 → 0.1.148

package/dist/index.cjs

@@ -3,6 +3,77 @@ let _atscript_db = require("@atscript/db");
 let _atscript_db_agg = require("@atscript/db/agg");
 let _atscript_db_sql_tools = require("@atscript/db-sql-tools");
 let _uniqu_core = require("@uniqu/core");
+//#region src/insert-ignore.ts
+/**
+* Whether two key values are the same value written differently: a number
+* and its decimal text (`5` / `"5.00"` of a NUMERIC column), a string and its
+* blank-padded form (`"ab"` / `"ab   "` of a CHAR(n) column), or in another
+* letter case (`uuid`, `citext`).
+*/
+function looselySame(a, b) {
+	const textA = typeof a === "number" || typeof a === "string" ? `${a}` : void 0;
+	const textB = typeof b === "number" || typeof b === "string" ? `${b}` : void 0;
+	if (textA === void 0 || textB === void 0) return false;
+	const na = Number(textA);
+	const nb = Number(textB);
+	if (textA.trim() !== "" && textB.trim() !== "" && Number.isFinite(na) && na === nb) return true;
+	return typeof a === "string" && typeof b === "string" && a.trimEnd().toLowerCase() === b.trimEnd().toLowerCase();
+}
+/** A key value the server may store in another form than it was sent (NUMERIC / decimal rounding). */
+function mayNormalize(value, col, formCols) {
+	if (typeof value === "string" && col !== void 0 && formCols?.has(col)) return true;
+	return typeof value === "number" && !Number.isInteger(value) || typeof value === "string" && /^-?\d+\.\d+$/.test(value);
+}
+/**
+* Maps the rows a batched `INSERT … ON CONFLICT DO NOTHING RETURNING <keys>`
+* returned back to the batch's input rows.
+*
+* PostgreSQL returns the inserted rows in VALUES order and omits skipped ones,
+* so `returned` is an in-order subsequence of `batch`. A row is inserted
+* exactly when the next returned row carries EVERY key set the row fully
+* defines (key sets with an absent / null input component are never compared:
+* a generated key's value is unknown to the input). Result: per input row, the
+* index of its returned row, or `-1` when it was skipped.
+*
+* `undefined` when the mapping is not provably exact — a row that defines no
+* complete key set (it may match a returned row only by a generated value), a
+* skipped-looking row whose key a server could have normalized (non-integer
+* numbers / decimals), a key equal to the returned one only when written
+* differently (`5` / `"5.00"`, blank-padded CHAR, a `uuid` / `citext` in another
+* letter case — the server lower-cases a returned uuid, so `"AAA"` / `"aaa"` could
+* swap the mapping), or returned rows left unaccounted for (counts or keys that
+* do not line up with an in-order subsequence). The caller must then redo the
+* chunk row by row. An empty `returned` (everything skipped) and a fully-returned
+* batch (everything inserted) are exact without any matching.
+*
+* @param keySets Physical column names of the primary key and every unique index.
+* @param formCols Key columns whose physical type is not text (uuid, inet, cidr,
+*   macaddr, …, `@db.pg.type` overrides): a string key there may come back
+*   normalized, so a skipped-looking row of such a key is ambiguous.
+*/
+function mapIgnoredBatch(batch, returned, keySets, formCols) {
+	if (returned.length === 0) return batch.map(() => -1);
+	if (returned.length === batch.length) return batch.map((_, i) => i);
+	const out = [];
+	let next = 0;
+	for (const row of batch) {
+		const tuples = keySets.map((cols) => (0, _atscript_db.uniqueKeyTuple)(row, cols));
+		if (tuples.every((t) => t === void 0)) return void 0;
+		const candidate = returned[next];
+		if (candidate !== void 0) {
+			const strict = keySets.map((cols, k) => tuples[k] === void 0 || tuples[k] === (0, _atscript_db.uniqueKeyTuple)(candidate, cols));
+			if (strict.every(Boolean)) {
+				out.push(next++);
+				continue;
+			}
+			if (keySets.every((cols, k) => tuples[k] === void 0 || strict[k] || cols.every((c) => looselySame(row[c], candidate[c])))) return void 0;
+		}
+		if (keySets.some((cols, k) => tuples[k] !== void 0 && cols.some((c) => mayNormalize(row[c], c, formCols)))) return;
+		out.push(-1);
+	}
+	return next === returned.length ? out : void 0;
+}
+//#endregion
 //#region src/sql-builder.ts
 /**
 * PostgreSQL-aware default value for a given design type.
@@ -79,6 +150,27 @@ const pgDialect = {
 	},
 	calendarBucket: pgCalendarBucket,
 	jsonExtract: pgJsonExtract,
+	castDouble: (expr) => `CAST(${expr} AS DOUBLE PRECISION)`,
+	anyValue: pgAnyValue,
+	booleanAggregates: {
+		min: "BOOL_AND",
+		max: "BOOL_OR"
+	},
+	/**
+	* SQLSTATE 22003 (`numeric_value_out_of_range`), a double overflow in
+	* aggregate arithmetic, is `INVALID_QUERY`; SQLSTATE 22023
+	* (`invalid_parameter_value`, `time zone "…" not recognized`), raised by a
+	* calendar bucket's `AT TIME ZONE '<tz>'`, is `BUCKET_TZ_UNAVAILABLE` — the
+	* zone passed the core's IANA validation, so the server's tz database is
+	* older than the runtime's.
+	*/
+	mapQueryError(error, arithmetic) {
+		const err = error;
+		if (err?.code === "22003") return arithmetic ? (0, _atscript_db_sql_tools.arithOverflowError)() : (0, _atscript_db_sql_tools.numericOutOfRangeError)();
+		const zone = err?.code === "22023" && typeof err.message === "string" ? /time zone "([^"]*)" not recognized/.exec(err.message)?.[1] : void 0;
+		return zone === void 0 ? void 0 : (0, _atscript_db.bucketTimeZoneUnavailable)(`PostgreSQL does not recognize time zone "${zone}" — update the server's time zone data`);
+	},
+	nullsSortLargest: true,
 	createViewPrefix: "CREATE OR REPLACE VIEW",
 	paramPlaceholder(index) {
 		return `$${index}`;
@@ -105,33 +197,47 @@ function pgJsonExtract(quotedCol, path, type) {
 /**
 * Calendar-bucket label over an epoch-ms column (BIGINT for
 * `@db.default.now`, DOUBLE PRECISION otherwise): TEXT `'YYYY-MM-DD'` — the
-* local date of the bucket's first day in `b.tz` — or NULL for a NULL source
-* or one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
+* local date of the bucket's first day in `b.tz` — or, for `hour`,
+* `'YYYY-MM-DDTHH:00'` — the local wall-clock hour — or NULL for a NULL
+* source or one outside `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
 *
-* The local date is `(to_timestamp(col / 1000) AT TIME ZONE '<tz>')::date`:
-* `timestamptz AT TIME ZONE` yields the wall time in that zone, independent
-* of the session `TimeZone`. Truncation is calendar arithmetic on that date —
-* the week uses the generic `(isodow - weekStart + 7) % 7` formula
-* (`date_trunc('week')` is Monday-only). `date_trunc` and `to_char` get an
-* explicit `::timestamp`: a bare `date` resolves to their `timestamptz`
-* overloads, which would route through the session zone.
+* The wall time is `to_timestamp(col / 1000) AT TIME ZONE '<tz>'`:
+* `timestamptz AT TIME ZONE` yields the (zone-less) wall time in that zone,
+* independent of the session `TimeZone` — so a `+05:30` zone's hour starts at
+* :30 UTC and a DST fall-back's repeated hour is one label. The hour is
+* formatted from it; the other units truncate its `::date` with calendar
+* arithmetic — the week uses the generic `(isodow - weekStart + 7) % 7`
+* formula (`date_trunc('week')` is Monday-only). `date_trunc` and `to_char`
+* get an explicit `::timestamp`: a bare `date` resolves to their
+* `timestamptz` overloads, which would route through the session zone.
 *
 * Parameter-free (the zone is an inlined, charset-checked literal), so the
 * SELECT and GROUP BY renderings match structurally.
 */
 function pgCalendarBucket(quotedCol, b) {
-	const local = `(to_timestamp(${quotedCol}::double precision / 1000) AT TIME ZONE ${(0, _atscript_db_sql_tools.sqlTimeZoneLiteral)(b.tz)})::date`;
-	let first;
+	const wall = `(to_timestamp(${quotedCol}::double precision / 1000) AT TIME ZONE ${(0, _atscript_db_sql_tools.sqlTimeZoneLiteral)(b.tz)})`;
+	const local = `${wall}::date`;
+	let value;
+	let format = "YYYY-MM-DD";
 	switch (b.unit) {
+		case "hour":
+			value = wall;
+			format = "YYYY-MM-DD\"T\"HH24\":00\"";
+			break;
 		case "day":
-			first = local;
+			value = local;
 			break;
 		case "week":
-			first = `(${local} - ((EXTRACT(ISODOW FROM ${local})::int - ${b.weekStartIso} + 7) % 7))`;
+			value = `(${local} - ((EXTRACT(ISODOW FROM ${local})::int - ${b.weekStartIso} + 7) % 7))`;
 			break;
-		default: first = `date_trunc('${b.unit}', ${local}::timestamp)`;
+		case "month":
+		case "quarter":
+		case "year":
+			value = `date_trunc('${b.unit}', ${local}::timestamp)`;
+			break;
+		default: throw new Error(`Unhandled calendar bucket unit "${String(b.unit)}"`);
 	}
-	return `CASE WHEN ${quotedCol} >= ${_uniqu_core.BUCKET_MIN_INSTANT} AND ${quotedCol} < ${_uniqu_core.BUCKET_MAX_INSTANT} THEN ${`to_char(${first}::timestamp, 'YYYY-MM-DD')`} END`;
+	return `CASE WHEN ${quotedCol} >= ${_uniqu_core.BUCKET_MIN_INSTANT} AND ${quotedCol} < ${_uniqu_core.BUCKET_MAX_INSTANT} THEN ${`to_char(${value}::timestamp, '${format}')`} END`;
 }
 /**
 * Distance-in-meters expression from a geography column to a query point.
@@ -241,6 +347,30 @@ function intTypeFromTags(tags) {
 	if (tags?.has("int64") || tags?.has("uint64")) return "BIGINT";
 	return "INTEGER";
 }
+/** Physical types `MIN` aggregates (base name, lower-cased): the streaming pick applies. */
+const MIN_ORDERED_TYPE = /^(smallint|int2|integer|int|int4|bigint|int8|real|float4|double precision|float8|numeric|decimal|money|text|varchar|character varying|char|character|bpchar|date|time|timetz|timestamp|timestamptz|interval|time (with|without) time zone|timestamp (with|without) time zone)\b/;
+/** Text key types: a value comes back in the form it was sent (modulo case for `citext`), so a returned key maps to its input row. */
+const TEXT_KEY_TYPE = /^(text|varchar|character varying|char|character|bpchar|citext)\b/;
+/** `true` when the physical column type `type` is a text type (see {@link TEXT_KEY_TYPE}). */
+function isTextKeyType(type) {
+	return TEXT_KEY_TYPE.test(type.trim().toLowerCase());
+}
+/**
+* The "any value of the group" pick of a `first` / `last` derived column
+* (constant within its group) over a PostgreSQL column: `MIN` (streaming — one
+* accumulator per group) for the ordered types and for every array column
+* (`MIN(anyarray)`; `ARRAY_AGG` over arrays builds a 2-D array and rejects NULL /
+* empty ones), `BOOL_AND` for a boolean, and `(ARRAY_AGG(x))[1]` only where the
+* physical type has no `MIN` (uuid, bytea, point, json / jsonb, citext,
+* `@db.pg.type` overrides, …) or is unknown.
+*/
+function pgAnyValue(expr, field) {
+	const type = field ? pgTypeFromField(field).trim().toLowerCase() : "";
+	if (type.endsWith("[]")) return `MIN(${expr})`;
+	if (/^bool(ean)?\b/.test(type)) return `BOOL_AND(${expr})`;
+	if (MIN_ORDERED_TYPE.test(type)) return `MIN(${expr})`;
+	return `(ARRAY_AGG(${expr}))[1]`;
+}
 /**
 * Maps an Atscript field descriptor to a PostgreSQL column type.
 *
@@ -296,11 +426,11 @@ function buildCreateTable(table, fields, foreignKeys, options) {
 			continue;
 		}
 		let def = `${qi(field.physicalName)} ${sqlType}`;
-		if (options?.incrementFields?.has(field.physicalName)) {
+		if (options?.incrementFields?.has(field.path)) {
 			const start = options.autoIncrementStart;
 			def += start !== void 0 ? ` GENERATED BY DEFAULT AS IDENTITY (START WITH ${start})` : " GENERATED BY DEFAULT AS IDENTITY";
 		}
-		if (!field.optional && !field.isPrimaryKey && !options?.incrementFields?.has(field.physicalName)) def += " NOT NULL";
+		if (!field.optional && !field.isPrimaryKey && !options?.incrementFields?.has(field.path)) def += " NOT NULL";
 		if (field.defaultValue?.kind === "value") def += ` DEFAULT ${defaultValueToSqlLiteral(field.designType, field.defaultValue.value)}`;
 		else if (field.defaultValue?.kind === "fn") {
 			if (field.defaultValue.fn === "uuid") def += " DEFAULT gen_random_uuid()";
@@ -321,12 +451,7 @@ function buildCreateTable(table, fields, foreignKeys, options) {
 	}
 	if (foreignKeys) for (const fk of foreignKeys.values()) {
 		if (options?.deferForeignKeysTo?.has(fk.targetTable)) continue;
-		const localCols = fk.fields.map((f) => qi(f)).join(", ");
-		const targetCols = fk.targetFields.map((f) => qi(f)).join(", ");
-		let constraint = `FOREIGN KEY (${localCols}) REFERENCES ${qi(fk.targetTable)} (${targetCols})`;
-		if (fk.onDelete) constraint += ` ON DELETE ${(0, _atscript_db_sql_tools.refActionToSql)(fk.onDelete)}`;
-		if (fk.onUpdate) constraint += ` ON UPDATE ${(0, _atscript_db_sql_tools.refActionToSql)(fk.onUpdate)}`;
-		colDefs.push(constraint);
+		colDefs.push((0, _atscript_db_sql_tools.foreignKeySql)(qi, fk));
 	}
 	return `CREATE TABLE IF NOT EXISTS ${quoteTableName(table)} (${colDefs.join(", ")})`;
 }
@@ -341,9 +466,15 @@ function buildCreateTable(table, fields, foreignKeys, options) {
 *
 * Case-insensitive columns (`@db.collate 'nocase'`) are handled by CITEXT
 * column type at the storage level — no query-side wrapping needed.
+*
+* Relational predicates (`$some` / `$none`) render as correlated `EXISTS`
+* subqueries referencing the outer table by `opts.qualifier` (default: the
+* source table) — a statement with an aliased FROM must pass its alias.
+*
+* @param opts - since 0.1.147
 */
-function buildWhere(filter) {
-	return (0, _atscript_db_sql_tools.buildWhere)(pgDialect, filter);
+function buildWhere(filter, opts) {
+	return (0, _atscript_db_sql_tools.buildWhere)(pgDialect, filter, opts);
 }
 //#endregion
 //#region src/postgres-adapter.ts
@@ -369,6 +500,8 @@ function parseCount(value) {
 * ```
 */
 /** The suffix PostgreSQL gives an auto-named constraint of each `pg_constraint.contype`. */
+/** Savepoint guarding one `insertManyIgnore` chunk (see {@link PostgresAdapter.insertManyIgnore}). */
+const IGNORE_SAVEPOINT = "atscript_ignore_chunk";
 const PG_CONSTRAINT_LABELS = {
 	p: "pkey",
 	u: "key",
@@ -426,7 +559,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	_vectorThresholds = /* @__PURE__ */ new Map();
 	/**
 	* Schema name for catalog queries and qualification — `@db.schema` of the
-	* bound table, or `null` (→ `'public'`, the same default the bound path
+	* bound table, or `null` (→ the connection's `current_schema()`, the same default the bound path
 	* uses) when the table declares none or the adapter is an administrative
 	* one with no readable (the name-taking schema-sync primitives run on such
 	* an adapter).
@@ -482,6 +615,15 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	_exec() {
 		return this._txConnection() ?? this.driver;
 	}
+	/**
+	* Relational predicates (`$some` / `$none`) render as correlated
+	* `[NOT] EXISTS` subqueries — in reads and in mutation filters alike.
+	*
+	* @since 0.1.147
+	*/
+	supportsRelationFilters(_mode) {
+		return true;
+	}
 	/** PostgreSQL enforces FK constraints natively. */
 	supportsNativeForeignKeys() {
 		return true;
@@ -502,10 +644,18 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	calendarBucketUnits() {
 		return _atscript_db.ALL_BUCKET_UNITS;
 	}
-	/** Every aggregate function, `countDistinct` included. */
+	/** Every aggregate function: `countDistinct`, `first` and `last` included. */
 	aggregateFns() {
 		return _atscript_db.ALL_AGGREGATE_FNS;
 	}
+	/** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
+	supportsAggregateExpressions() {
+		return true;
+	}
+	/** Computed view columns and first-row joins. */
+	viewCapabilities() {
+		return _atscript_db.ALL_VIEW_CAPABILITIES;
+	}
 	onBeforeFlatten(_type) {}
 	onAfterFlatten() {
 		for (const fd of this._table.fieldDescriptors) if (fd.collate === "nocase") this._nocaseColumns.add(fd.physicalName);
@@ -571,17 +721,21 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		try {
 			return await fn();
 		} catch (error) {
-			if (error && typeof error === "object" && "code" in error) {
-				const err = error;
-				if (err.code === "23505") throw new _atscript_db.DbError("CONFLICT", [{
-					path: this._extractFieldFromConstraint(err.constraint) ?? "",
-					message: err.detail ?? err.message
-				}]);
-				if (err.code === "23503") throw new _atscript_db.DbError("FK_VIOLATION", this._mapFkError(err.detail ?? err.message, err.constraint));
-			}
-			throw error;
+			return this._mapConstraintError(error);
 		}
 	}
+	/** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+	_mapConstraintError(error) {
+		if (error && typeof error === "object" && "code" in error) {
+			const err = error;
+			if (err.code === "23505") throw new _atscript_db.DbError("CONFLICT", [{
+				path: this._extractFieldFromConstraint(err.constraint) ?? "",
+				message: err.detail ?? err.message
+			}]);
+			if (err.code === "23503") throw new _atscript_db.DbError("FK_VIOLATION", this._mapFkError(err.detail ?? err.message, err.constraint));
+		}
+		throw error;
+	}
 	_extractFieldFromConstraint(constraint) {
 		if (!constraint) return;
 		const tableName = this._table.tableName;
@@ -608,7 +762,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	}
 	async insertOne(data) {
 		let { sql, params } = buildInsert(this.resolveTableName(), data);
-		const pkCols = this._table.primaryKeys.map((pk) => qi(pk));
+		const pkCols = this._pkColumns().map((pk) => qi(pk));
 		if (pkCols.length > 0) sql += ` RETURNING ${pkCols.join(", ")}`;
 		this._log(sql, params);
 		const returned = (await this._wrapConstraintError(() => this._exec().run(sql, params))).rows?.[0];
@@ -621,13 +775,11 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		};
 		return this.withTransaction(async () => {
 			const tableName = this.resolveTableName();
-			const pkCols = this._table.primaryKeys;
+			const pkCols = this._pkColumns();
 			const returningSuffix = pkCols.length > 0 ? ` RETURNING ${pkCols.map((pk) => qi(pk)).join(", ")}` : "";
-			const columns = (0, _atscript_db_sql_tools.insertManyColumns)(data);
-			const maxRowsPerBatch = columns.length > 0 ? Math.floor(6e4 / columns.length) : data.length;
+			const { columns, batches } = (0, _atscript_db_sql_tools.chunkInsertRows)(data);
 			const allIds = [];
-			for (let offset = 0; offset < data.length; offset += maxRowsPerBatch) {
-				const batch = data.slice(offset, offset + maxRowsPerBatch);
+			for (const batch of batches) {
 				const insert = buildInsertMany(tableName, batch, columns);
 				const sql = insert.sql + returningSuffix;
 				const params = insert.params;
@@ -644,6 +796,56 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 			};
 		});
 	}
+	supportsInsertIgnore() {
+		return true;
+	}
+	/**
+	* Batched `INSERT … VALUES (…), (…) ON CONFLICT DO NOTHING RETURNING <pk +
+	* unique key columns>`: one statement per chunk (a conflict never raises, so
+	* the surrounding transaction survives). Skipped rows are the ones missing
+	* from RETURNING — mapped back by key values, see {@link mapIgnoredBatch}.
+	* Each chunk runs inside a SAVEPOINT: when the mapping is ambiguous (a key
+	* the server returns in another form than it was sent) the chunk is rolled
+	* back to the savepoint and redone row by row with the same
+	* `ON CONFLICT DO NOTHING`, so the result is always exact.
+	*/
+	async insertManyIgnore(data) {
+		if (data.length === 0) return [];
+		return this.withTransaction(async () => {
+			const tableName = this.resolveTableName();
+			const pkCols = this._pkColumns();
+			const keySets = this._table.uniqueKeySets;
+			const returning = [...new Set(keySets.flat())];
+			const returningCols = new Set(returning);
+			const nonTextKeyCols = new Set(this._table.fieldDescriptors.filter((f) => returningCols.has(f.physicalName) && !isTextKeyType(this.typeMapper(f))).map((f) => f.physicalName));
+			const returningSuffix = returning.length > 0 ? ` RETURNING ${returning.map((c) => qi(c)).join(", ")}` : "";
+			const insertedId = (row, returned) => ({ insertedId: this._resolveInsertedId(row, pkCols.length > 0 ? returned?.[pkCols[0]] : void 0) });
+			const { columns, batches } = (0, _atscript_db_sql_tools.chunkInsertRows)(data);
+			const slots = [];
+			for (const batch of batches) {
+				const insert = buildInsertMany(tableName, batch, columns);
+				const sql = `${insert.sql} ON CONFLICT DO NOTHING${returningSuffix}`;
+				await this._exec().run(`SAVEPOINT ${IGNORE_SAVEPOINT}`);
+				this._log(sql, insert.params);
+				const returned = (await this._wrapConstraintError(() => this._exec().run(sql, insert.params))).rows ?? [];
+				const mapping = returning.length === 0 ? batch.map((_, i) => i) : mapIgnoredBatch(batch, returned, keySets, nonTextKeyCols);
+				if (mapping) {
+					await this._exec().run(`RELEASE SAVEPOINT ${IGNORE_SAVEPOINT}`);
+					mapping.forEach((hit, i) => slots.push(hit < 0 ? null : insertedId(batch[i], returned[hit])));
+					continue;
+				}
+				await this._exec().run(`ROLLBACK TO SAVEPOINT ${IGNORE_SAVEPOINT}`);
+				for (const row of batch) {
+					const single = buildInsert(tableName, row);
+					const rowSql = `${single.sql} ON CONFLICT DO NOTHING${returningSuffix}`;
+					this._log(rowSql, single.params);
+					const rowResult = await this._wrapConstraintError(() => this._exec().run(rowSql, single.params));
+					slots.push(rowResult.rows?.length ? insertedId(row, rowResult.rows[0]) : null);
+				}
+			}
+			return slots;
+		});
+	}
 	async findOne(query) {
 		const where = buildWhere(query.filter);
 		const controls = {
@@ -660,6 +862,16 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		this._log(sql, params);
 		return this._exec().all(sql, params);
 	}
+	/**
+	* `$skip` / `$limit` per partition in one statement: a `ROW_NUMBER()`
+	* window over `partitionBy` (the generic `$with` loader's per-parent page).
+	*/
+	async findManyPerPartition(query, partitionBy) {
+		const where = buildWhere(query.filter);
+		const { sql, params } = (0, _atscript_db_sql_tools.buildPartitionedSelect)(pgDialect, this.resolveTableName(), where, query.controls, partitionBy);
+		this._log(sql, params);
+		return (0, _atscript_db_sql_tools.stripPartitionRowNumber)(await this._exec().all(sql, params));
+	}
 	async count(query) {
 		const where = buildWhere(query.filter);
 		const { sql, params } = (0, _atscript_db_sql_tools.finalizeParams)(pgDialect, {
@@ -676,28 +888,15 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		if (query.controls.$count) {
 			const { sql, params } = buildAggregateCount(tableName, where, query.controls);
 			this._log(sql, params);
-			return [{ count: parseCount((await this._wrapBucketZoneError(() => this._exec().get(sql, params)))?.count) }];
+			return [{ count: parseCount((await (0, _atscript_db_sql_tools.mapQueryErrors)(pgDialect, () => this._exec().get(sql, params), query.controls))?.count) }];
 		}
 		const { sql, params } = buildAggregateSelect(tableName, where, query.controls);
 		this._log(sql, params);
-		return this._wrapBucketZoneError(() => this._exec().all(sql, params));
+		return (0, _atscript_db_sql_tools.mapQueryErrors)(pgDialect, () => this._exec().all(sql, params), query.controls);
 	}
-	/**
-	* Maps PostgreSQL's unknown-zone error — SQLSTATE 22023
-	* (`invalid_parameter_value`), `time zone "…" not recognized` — raised by a
-	* calendar bucket's `AT TIME ZONE '<tz>'` to `BUCKET_TZ_UNAVAILABLE`. The
-	* zone passed the core's IANA validation, so the server's tz database is
-	* older than the runtime's. Other errors propagate unchanged.
-	*/
-	async _wrapBucketZoneError(fn) {
-		try {
-			return await fn();
-		} catch (error) {
-			const err = error;
-			const zone = err?.code === "22023" && typeof err.message === "string" ? /time zone "([^"]*)" not recognized/.exec(err.message)?.[1] : void 0;
-			if (zone !== void 0) throw (0, _atscript_db.bucketTimeZoneUnavailable)(`PostgreSQL does not recognize time zone "${zone}" — update the server's time zone data`);
-			throw error;
-		}
+	/** Physical primary-key columns (`@db.column` renames applied). */
+	_pkColumns() {
+		return this._table.primaryKeys.map((key) => this._table.physicalPath(key));
 	}
 	/**
 	* The predicate that narrows a single-row UPDATE/DELETE to the first row
@@ -708,7 +907,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	* existing behavior rather than guess.
 	*/
 	_limitOnePredicate(quotedTable, whereSql) {
-		const pkCols = this._table.primaryKeys;
+		const pkCols = this._pkColumns();
 		const quotedKeys = pkCols.length > 0 ? pkCols.map((c) => qi(c)) : ["ctid"];
 		const colList = quotedKeys.join(", ");
 		return `${quotedKeys.length === 1 ? `${colList} =` : `(${colList}) IN`} (SELECT ${colList} FROM ${quotedTable} WHERE ${whereSql} LIMIT 1)`;
@@ -818,7 +1017,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
        JOIN pg_class cl ON cl.oid = c.conrelid
        JOIN pg_class rcl ON rcl.oid = c.confrelid
        JOIN pg_namespace rn ON rn.oid = rcl.relnamespace
-       WHERE c.contype = 'f' AND rcl.relname = $1 AND rn.nspname = COALESCE($2, 'public')
+       WHERE c.contype = 'f' AND rcl.relname = $1 AND rn.nspname = COALESCE($2, current_schema())
        ORDER BY cl.relname, c.conname`, [tableName, this._schema])).map((r) => ({
 			table: r.table_name,
 			fields: r.columns ?? [],
@@ -828,7 +1027,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	async getObjectKind(name) {
 		switch ((await this._exec().get(`SELECT c.relkind FROM pg_class c
        JOIN pg_namespace n ON n.oid = c.relnamespace
-       WHERE c.relname = $1 AND n.nspname = COALESCE($2, 'public')
+       WHERE c.relname = $1 AND n.nspname = COALESCE($2, current_schema())
          AND c.relkind IN ('r', 'p', 'v', 'm')`, [name, this._schema]))?.relkind) {
 			case "r":
 			case "p": return "table";
@@ -856,7 +1055,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 			const row = await this._exec().get(`SELECT c.conname FROM pg_constraint c
          JOIN pg_class cl ON cl.oid = c.conrelid
          JOIN pg_namespace n ON n.oid = cl.relnamespace
-         WHERE c.contype = 'p' AND cl.relname = $1 AND n.nspname = COALESCE($2, 'public')`, [this._table.tableName, this._schema]);
+         WHERE c.contype = 'p' AND cl.relname = $1 AND n.nspname = COALESCE($2, current_schema())`, [this._table.tableName, this._schema]);
 			if (row?.conname) clauses.push(`DROP CONSTRAINT ${qi(row.conname)}`);
 		}
 		if (change.to.length > 0) clauses.push(`ADD PRIMARY KEY (${change.to.map((c) => qi(c)).join(", ")})`);
@@ -888,8 +1087,8 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
               ) AS is_pk
        FROM information_schema.columns c
        JOIN pg_attribute a ON a.attname = c.column_name
-         AND a.attrelid = (SELECT oid FROM pg_class WHERE relname = $1 AND relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = COALESCE($2, 'public')))
-       WHERE c.table_name = $1 AND c.table_schema = COALESCE($2, 'public')
+         AND a.attrelid = (SELECT oid FROM pg_class WHERE relname = $1 AND relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = COALESCE($2, current_schema())))
+       WHERE c.table_name = $1 AND c.table_schema = COALESCE($2, current_schema())
        ORDER BY c.ordinal_position`, [tableName, schema])).map((r) => {
 			const column = {
 				name: r.column_name,
@@ -1009,10 +1208,10 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
          CROSS JOIN LATERAL unnest(c.conkey, c.confkey) WITH ORDINALITY AS k(attnum, refattnum, ord)
          JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.attnum
          JOIN pg_attribute ra ON ra.attrelid = c.confrelid AND ra.attnum = k.refattnum
-         WHERE c.contype = 'f' AND rcl.relname = $2 AND rn.nspname = COALESCE($1, 'public')
+         WHERE c.contype = 'f' AND rcl.relname = $2 AND rn.nspname = COALESCE($1, current_schema())
          ORDER BY n.nspname, cl.relname, c.conname, k.ord`, [schema, this._table.tableName]);
 			const inboundFks = /* @__PURE__ */ new Map();
-			const ownSchema = schema ?? "public";
+			const ownSchema = schema ?? (await conn.get("SELECT current_schema() AS s"))?.s ?? "public";
 			for (const fk of fkRefs) {
 				if (fk.table_schema === ownSchema && fk.table_name === this._table.tableName) continue;
 				const key = `${fk.table_schema}.${fk.table_name}.${fk.constraint_name}`;
@@ -1107,7 +1306,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
        FROM pg_constraint c
        JOIN pg_class cl ON cl.oid = c.conrelid
        JOIN pg_namespace n ON n.oid = cl.relnamespace
-       WHERE cl.relname = $1 AND n.nspname = COALESCE($2, 'public')
+       WHERE cl.relname = $1 AND n.nspname = COALESCE($2, current_schema())
        ORDER BY c.conname`, [table, this._schema]);
 		const taken = new Set(rows.map((r) => r.conname));
 		for (const { conname, contype, columns } of rows) {
@@ -1131,7 +1330,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	async _relationExists(conn, name) {
 		return (await conn.get(`SELECT true AS present FROM pg_class c
        JOIN pg_namespace n ON n.oid = c.relnamespace
-       WHERE c.relname = $1 AND n.nspname = COALESCE($2, 'public')`, [name, this._schema]))?.present ?? false;
+       WHERE c.relname = $1 AND n.nspname = COALESCE($2, current_schema())`, [name, this._schema]))?.present ?? false;
 	}
 	async afterSyncTable() {
 		await this._resetIdentitySequences();
@@ -1154,7 +1353,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		}
 	}
 	async tableExists() {
-		return (await this._exec().get(`SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = $1 AND table_schema = COALESCE($2, 'public')) AS "exists"`, [this._table.tableName, this._schema]))?.exists ?? false;
+		return (await this._exec().get(`SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = $1 AND table_schema = COALESCE($2, current_schema())) AS "exists"`, [this._table.tableName, this._schema]))?.exists ?? false;
 	}
 	/**
 	* No CASCADE: when something outside the sync inventory (a user view, an
@@ -1183,7 +1382,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
        JOIN pg_class i ON i.oid = x.indexrelid
        JOIN pg_namespace n ON n.oid = t.relnamespace
        JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(x.indkey)
-       WHERE t.relname = $1 AND n.nspname = COALESCE($2, 'public')
+       WHERE t.relname = $1 AND n.nspname = COALESCE($2, current_schema())
          AND i.relname LIKE 'atscript__%' AND a.attname = ANY($3)`, [
 			tableName,
 			schema,
@@ -1235,7 +1434,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
            JOIN pg_class t ON t.oid = x.indrelid
            JOIN pg_class i ON i.oid = x.indexrelid
            JOIN pg_namespace n ON n.oid = t.relnamespace
-           WHERE t.relname = $1 AND n.nspname = COALESCE($2, 'public')`, [tableName, schema])).map((r) => ({
+           WHERE t.relname = $1 AND n.nspname = COALESCE($2, current_schema())`, [tableName, schema])).map((r) => ({
 					name: r.name,
 					columns: r.columns ?? void 0
 				}));
@@ -1281,7 +1480,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	async syncForeignKeys() {
 		const existingByName = await this._getExistingFkConstraints();
 		const desiredFkKeys = /* @__PURE__ */ new Set();
-		for (const fk of this._table.foreignKeys.values()) desiredFkKeys.add([...fk.fields].toSorted().join(","));
+		for (const fk of this._table.foreignKeys.values()) desiredFkKeys.add([...(0, _atscript_db.fkColumns)(fk).fields].toSorted().join(","));
 		for (const [constraintName, columns] of existingByName) {
 			const key = [...columns].toSorted().join(",");
 			if (!desiredFkKeys.has(key)) {
@@ -1292,13 +1491,9 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		}
 		const existingKeys = new Set([...existingByName.values()].map((cols) => cols.toSorted().join(",")));
 		for (const fk of this._table.foreignKeys.values()) {
-			const key = [...fk.fields].toSorted().join(",");
+			const key = [...(0, _atscript_db.fkColumns)(fk).fields].toSorted().join(",");
 			if (!existingKeys.has(key)) {
-				const localCols = fk.fields.map((f) => qi(f)).join(", ");
-				const targetCols = fk.targetFields.map((f) => qi(f)).join(", ");
-				let ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} ADD FOREIGN KEY (${localCols}) REFERENCES ${qi(fk.targetTable)} (${targetCols})`;
-				if (fk.onDelete) ddl += ` ON DELETE ${(0, _atscript_db_sql_tools.refActionToSql)(fk.onDelete)}`;
-				if (fk.onUpdate) ddl += ` ON UPDATE ${(0, _atscript_db_sql_tools.refActionToSql)(fk.onUpdate)}`;
+				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} ADD ${(0, _atscript_db_sql_tools.foreignKeySql)(qi, fk)}`;
 				this._log(ddl);
 				await this._exec().exec(ddl);
 			}
@@ -1325,7 +1520,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
        JOIN pg_namespace n ON n.oid = cl.relnamespace
        CROSS JOIN LATERAL unnest(c.conkey) WITH ORDINALITY AS k(attnum, ord)
        JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.attnum
-       WHERE c.contype = 'f' AND cl.relname = $1 AND n.nspname = COALESCE($2, 'public')
+       WHERE c.contype = 'f' AND cl.relname = $1 AND n.nspname = COALESCE($2, current_schema())
        ORDER BY c.conname, k.ord`, [this._table.tableName, this._schema]);
 		const byName = /* @__PURE__ */ new Map();
 		for (const row of rows) {
@@ -1470,7 +1665,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 			vec = first.value[1];
 		}
 		const distanceOp = similarityToPgOp(vec.similarity);
-		const where = buildWhere(query.filter);
+		const where = buildWhere(query.filter, { qualifier: pgDialect.quoteTable(_atscript_db_sql_tools.SEARCH_SOURCE_ALIAS) });
 		const controls = query.controls || {};
 		const threshold = this._resolveVectorThreshold(controls, vec.indexName);
 		return {
@@ -1563,7 +1758,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		const controls = query.controls ?? {};
 		return {
 			tableName: this.resolveTableName(),
-			where: buildWhere(query.filter),
+			where: buildWhere(query.filter, { qualifier: pgDialect.quoteTable(_atscript_db_sql_tools.SEARCH_SOURCE_ALIAS) }),
 			dist: pgGeoDistanceExpr(qi(column), point),
 			window: (0, _atscript_db_sql_tools.geoWindowFromControls)(controls),
 			controls
@@ -1816,8 +2011,10 @@ var PgDriver = class {
 			}
 		};
 	}
-	async close() {
-		await (await this.getPool()).end();
+	_closing;
+	/** Idempotent: every call returns the first call's promise. */
+	close() {
+		return this._closing ??= Promise.resolve(this.getPool()).then((pool) => pool.end());
 	}
 };
 //#endregion
@@ -1834,7 +2031,7 @@ function createAdapter(uri, options) {
 		connectionString: uri,
 		...options
 	});
-	return new _atscript_db.DbSpace(() => new PostgresAdapter(driver));
+	return new _atscript_db.DbSpace(() => new PostgresAdapter(driver), { onClose: () => driver.close() });
 }
 //#endregion
 exports.PgDriver = PgDriver;