@atscript/db-postgres 0.1.149 → 0.1.151

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, bucketTimeZoneUnavailable, fkColumns, isColumnTypeChanged, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
+import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, bucketTimeZoneUnavailable, defaultFulltextIndex, describeFulltext, fkColumns, isColumnTypeChanged, searchTermInteger, splitFulltextFields, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
 import { resolveAggregateSearch } from "@atscript/db/agg";
-import { SEARCH_SOURCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere as buildWhere$1, chunkInsertRows, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, parseRegexString, quotedJsonPathSegments, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, vectorDistanceSource } from "@atscript/db-sql-tools";
+import { SEARCH_SOURCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere as buildWhere$1, chunkInsertRows, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, foreignKeySql, geoWindowFromControls, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orFragment, parseRegexString, quotedJsonPathSegments, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, stripPartitionRowNumber, vectorDistanceSource } from "@atscript/db-sql-tools";
 import { BUCKET_MAX_INSTANT, BUCKET_MIN_INSTANT } from "@uniqu/core";
 //#region src/insert-ignore.ts
 /**
@@ -109,10 +109,30 @@ function quoteTableName(name) {
 	if (dot >= 0) return `${qi(name.slice(0, dot))}.${qi(name.slice(dot + 1))}`;
 	return qi(name);
 }
+/**
+* A `db.geoPoint` value written or filtered on before the adapter knows the
+* physical type of its column — a PostGIS `geography` / `geometry` column
+* (EWKT) or the JSONB fallback (`raw`, what the JSONB path binds). Whichever
+* adapter executes the statement resolves it right before it runs (the
+* marker may come from another table's formatter, e.g. a relational filter):
+* `native` answers for the column the marker was formatted for, probing the
+* catalog on `exec` when not known yet.
+*/
+var PendingGeoPoint = class {
+	point;
+	raw;
+	native;
+	constructor(point, raw, native) {
+		this.point = point;
+		this.raw = raw;
+		this.native = native;
+	}
+};
 /** Converts JS values to SQL-bindable params, keeping booleans native. */
 function toPgValue(value) {
 	if (value === void 0) return null;
 	if (value === null) return null;
+	if (value instanceof PendingGeoPoint) return new PendingGeoPoint(value.point, toPgValue(value.raw), value.native);
 	if (value instanceof Date) return value.toISOString();
 	if (typeof value === "object") return JSON.stringify(value);
 	return value;
@@ -137,6 +157,7 @@ const pgDialect = {
 			params: [pattern]
 		};
 	},
+	integerText: (expr) => `CAST(CAST(${expr} AS BIGINT) AS TEXT)`,
 	geoWithin(quotedCol, circle) {
 		return {
 			sql: `ST_DWithin(${quotedCol}, ST_SetSRID(ST_MakePoint(?, ?), 4326)::geography, ?)`,
@@ -477,6 +498,53 @@ function buildWhere(filter, opts) {
 }
 //#endregion
 //#region src/postgres-adapter.ts
+/**
+* Read-only geo facts of one table, in one round trip: PostGIS presence and
+* the physical type of the named columns (`{ column: type }`, a domain
+* reported as its base type; `null` when the relation does not exist). Catalog
+* reads only — no privileges needed, never aborts a transaction.
+*/
+const GEO_PROBE_SQL = `SELECT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'postgis') AS "postgis",
+  (SELECT json_object_agg(a.attname, COALESCE(b.typname, t.typname))
+     FROM pg_attribute a
+     JOIN pg_type t ON t.oid = a.atttypid
+     LEFT JOIN pg_type b ON b.oid = NULLIF(t.typbasetype, 0)
+    WHERE a.attrelid = to_regclass($1::text) AND a.attnum > 0 AND NOT a.attisdropped
+      AND a.attname = ANY($2::text[])) AS "columns"`;
+/** A PostGIS column type — a geo value binds as EWKT. Anything else (JSONB, TEXT) takes the JSON form. */
+const POSTGIS_TYPES = new Set(["geography", "geometry"]);
+/** The SQL `$geoWithin` renders (`pgDialect.geoWithin`) — PostGIS only. */
+const GEO_WITHIN_SQL = "ST_DWithin(";
+/** Index of the first {@link PendingGeoPoint} in `params`, or -1. */
+function firstPendingGeo(params) {
+	if (params) {
+		for (let i = 0; i < params.length; i++) if (params[i] instanceof PendingGeoPoint) return i;
+	}
+	return -1;
+}
+/**
+* A copy of `params` with every {@link PendingGeoPoint} (from `from` on)
+* resolved for its own column — EWKT for a PostGIS column, the JSON form
+* otherwise — each marker's column probe running on `exec`, the statement's.
+*/
+async function resolvePendingGeo(params, from, exec) {
+	const out = params.slice();
+	for (let i = from; i < out.length; i++) {
+		const value = out[i];
+		if (value instanceof PendingGeoPoint) {
+			const native = value.native(exec);
+			out[i] = (typeof native === "boolean" ? native : await native) ? geoPointToEwkt(value.point) : value.raw;
+		}
+	}
+	return out;
+}
+/** `GEO_NOT_SUPPORTED` — geo search / `$geoWithin` without PostGIS. */
+function geoNotSupported(path, message) {
+	return new DbError("GEO_NOT_SUPPORTED", [{
+		path,
+		message
+	}]);
+}
 /** PostgreSQL COUNT() may return string (bigint) — parse to number. */
 function parseCount(value) {
 	if (typeof value === "string") return Number.parseInt(value, 10);
@@ -548,8 +616,42 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	_nocaseColumns = /* @__PURE__ */ new Set();
 	/** Whether citext extension has been provisioned (avoids redundant round-trips). */
 	_citextProvisioned = false;
-	/** Whether the connected PostgreSQL instance has the PostGIS extension. */
+	/**
+	* Whether the connected PostgreSQL instance has the PostGIS extension —
+	* `undefined` until known: set by schema sync ({@link prepareTypeMapper},
+	* which installs it), or by the read-only geo probe ({@link _probeGeo}).
+	* Decides DDL and geo search; how a geo VALUE binds is decided per column
+	* ({@link _geoNative}).
+	*/
 	_supportsGeo;
+	/** Whether {@link _detectGeoSupport} (the installing detection) already ran. */
+	_geoInstallTried = false;
+	/** Memo of {@link _hasGeoPointFields}. */
+	_geoFields;
+	/** Physical names of the unencrypted `db.geoPoint` columns (set with the metadata). */
+	_geoColumnNames = [];
+	/**
+	* Physical geo column → whether it is a PostGIS column (`geography` /
+	* `geometry`: EWKT) or not (JSONB: the JSON form). Learned from the catalog
+	* — after schema sync ({@link afterSyncTable}) or before the first statement
+	* binding a geo value — never from the extension alone: a JSONB column
+	* created before PostGIS was installed stays JSONB until a sync migrates
+	* it. Cleared by every DDL path ({@link _geoSchemaChanged}).
+	*/
+	_geoNative = /* @__PURE__ */ new Map();
+	/** The in-flight shared geo probe and the executor it runs on. */
+	_geoProbe;
+	/** Bumped by {@link _geoSchemaChanged}: a probe started before a DDL caches nothing. */
+	_geoSchemaGen = 0;
+	/** The pool executor with geo-marker resolution (built once). */
+	_poolExec;
+	/** The last transaction connection's wrapped executor. */
+	_txExec;
+	_pkColumnsMemo;
+	_replaceColumnsMemo;
+	_ignorePlanMemo;
+	_fulltextMemo;
+	_searchIndexesMemo;
 	/** Whether the connected PostgreSQL instance has the pgvector extension. */
 	_supportsVector;
 	/** Vector fields: physical field name → { dimensions, similarity, indexName }. */
@@ -612,7 +714,41 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	* otherwise the pool-based driver.
 	*/
 	_exec() {
-		return this._txConnection() ?? this.driver;
+		const conn = this._txConnection();
+		if (!conn) return this._poolExec ??= this._geoResolvingExec(this.driver);
+		if (this._txExec?.conn !== conn) this._txExec = {
+			conn,
+			exec: this._geoResolvingExec(conn)
+		};
+		return this._txExec.exec;
+	}
+	/**
+	* `exec` resolving `PendingGeoPoint` params before the statement runs. Every
+	* adapter wraps — not only geo tables: a relational filter on another
+	* table's geo column carries that table's markers into this one's
+	* statement. A statement without markers runs as is (one param scan).
+	*/
+	_geoResolvingExec(exec) {
+		const prep = (sql, params, run) => {
+			if (this._geoFields && this._supportsGeo !== true && sql.includes(GEO_WITHIN_SQL)) return this._assertGeoWithin(exec).then(() => prep(sql, params, run));
+			const at = firstPendingGeo(params);
+			return at < 0 ? run(params) : resolvePendingGeo(params, at, exec).then(run);
+		};
+		return {
+			run: (sql, params) => prep(sql, params, (p) => exec.run(sql, p)),
+			all: (sql, params) => prep(sql, params, (p) => exec.all(sql, p)),
+			get: (sql, params) => prep(sql, params, (p) => exec.get(sql, p)),
+			exec: (sql) => exec.exec(sql).finally(() => this._geoSchemaChanged())
+		};
+	}
+	/**
+	* `$geoWithin` passed the core guard while PostGIS presence was unknown
+	* ({@link isGeoSearchable} answers optimistically then): learn it, and
+	* refuse like the guard would have when it is absent.
+	*/
+	async _assertGeoWithin(exec) {
+		if (this._supportsGeo === void 0) await this._probeGeo(exec);
+		if (this._supportsGeo !== true) throw geoNotSupported("", "$geoWithin requires the PostGIS extension");
 	}
 	/**
 	* Relational predicates (`$some` / `$none`) render as correlated
@@ -657,7 +793,13 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	}
 	onBeforeFlatten(_type) {}
 	onAfterFlatten() {
-		for (const fd of this._table.fieldDescriptors) if (fd.collate === "nocase") this._nocaseColumns.add(fd.physicalName);
+		const geo = [];
+		for (const fd of this._table.fieldDescriptors) {
+			if (fd.collate === "nocase") this._nocaseColumns.add(fd.physicalName);
+			if (fd.isGeoPoint === true && !fd.encrypted) geo.push(fd.physicalName);
+		}
+		this._geoColumnNames = geo;
+		this._geoFields = geo.length > 0;
 	}
 	onFieldScanned(field, _type, metadata) {
 		if (metadata.has("db.default.increment")) {
@@ -693,20 +835,27 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 			toStorage: (value) => Array.isArray(value) ? `[${value.join(",")}]` : value,
 			fromStorage: (value) => typeof value === "string" ? JSON.parse(value) : value
 		};
-		if (field.isGeoPoint && !field.encrypted) return {
-			toStorage: (value) => {
-				if (!this._supportsGeo) return value;
-				const point = normalizeGeoPointValue(value);
-				return point ? geoPointToEwkt(point) : value;
-			},
-			fromStorage: (value) => {
-				if (typeof value === "string") {
-					const point = parseEwkbPointHex(value);
-					if (point) return point;
+		if (field.isGeoPoint && !field.encrypted) {
+			const column = field.physicalName;
+			const native = (exec) => this._geoColumnNative(column, exec);
+			return {
+				toStorage: (value) => {
+					if (this._supportsGeo === false) return value;
+					const point = normalizeGeoPointValue(value);
+					if (!point) return value;
+					const known = this._geoNative.get(column);
+					if (known === void 0) return new PendingGeoPoint(point, value, native);
+					return known ? geoPointToEwkt(point) : value;
+				},
+				fromStorage: (value) => {
+					if (typeof value === "string") {
+						const point = parseEwkbPointHex(value);
+						if (point) return point;
+					}
+					return value;
 				}
-				return value;
-			}
-		};
+			};
+		}
 	}
 	/**
 	* Wraps an async write operation to catch PostgreSQL constraint errors
@@ -760,9 +909,9 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		}];
 	}
 	async insertOne(data) {
-		let { sql, params } = buildInsert$1(this.resolveTableName(), data);
-		const pkCols = this._pkColumns().map((pk) => qi(pk));
-		if (pkCols.length > 0) sql += ` RETURNING ${pkCols.join(", ")}`;
+		const insert = buildInsert$1(this.resolveTableName(), data);
+		const sql = insert.sql + this._pk().returning;
+		const params = insert.params;
 		this._log(sql, params);
 		const returned = (await this._wrapConstraintError(() => this._exec().run(sql, params))).rows?.[0];
 		return { insertedId: this._resolveInsertedId(data, returned ? Object.values(returned)[0] : void 0) };
@@ -772,11 +921,10 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 			insertedCount: 0,
 			insertedIds: []
 		};
-		return this.withTransaction(async () => {
+		const { columns, batches } = chunkInsertRows(data);
+		const run = async () => {
 			const tableName = this.resolveTableName();
-			const pkCols = this._pkColumns();
-			const returningSuffix = pkCols.length > 0 ? ` RETURNING ${pkCols.map((pk) => qi(pk)).join(", ")}` : "";
-			const { columns, batches } = chunkInsertRows(data);
+			const returningSuffix = this._pk().returning;
 			const allIds = [];
 			for (const batch of batches) {
 				const insert = buildInsertMany$1(tableName, batch, columns);
@@ -793,7 +941,8 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 				insertedCount: allIds.length,
 				insertedIds: allIds
 			};
-		});
+		};
+		return batches.length === 1 ? run() : this.withTransaction(run);
 	}
 	supportsInsertIgnore() {
 		return true;
@@ -803,33 +952,34 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	* 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.
+	* A multi-row chunk of a keyed table 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. A
+	* one-row chunk (or a table without keys) maps exactly by construction, so
+	* it needs no savepoint — and a single such chunk no transaction either.
 	*/
 	async insertManyIgnore(data) {
 		if (data.length === 0) return [];
-		return this.withTransaction(async () => {
+		const plan = this._ignorePlan();
+		const { columns, batches } = chunkInsertRows(data);
+		const needsSavepoint = (batch) => batch.length > 1 && plan.returning.length > 0;
+		const run = 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 { keySets, returning, nonTextKeyCols, returningSuffix } = plan;
+			const pkCols = this._pk().cols;
 			const insertedId = (row, returned) => ({ insertedId: this._resolveInsertedId(row, pkCols.length > 0 ? returned?.[pkCols[0]] : void 0) });
-			const { columns, batches } = chunkInsertRows(data);
 			const slots = [];
 			for (const batch of batches) {
 				const insert = buildInsertMany$1(tableName, batch, columns);
 				const sql = `${insert.sql} ON CONFLICT DO NOTHING${returningSuffix}`;
-				await this._exec().run(`SAVEPOINT ${IGNORE_SAVEPOINT}`);
+				const savepoint = needsSavepoint(batch);
+				if (savepoint) 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}`);
+					if (savepoint) await this._exec().run(`RELEASE SAVEPOINT ${IGNORE_SAVEPOINT}`);
 					mapping.forEach((hit, i) => slots.push(hit < 0 ? null : insertedId(batch[i], returned[hit])));
 					continue;
 				}
@@ -843,7 +993,32 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 				}
 			}
 			return slots;
-		});
+		};
+		return batches.length === 1 && !needsSavepoint(batches[0]) ? run() : this.withTransaction(run);
+	}
+	/**
+	* The key columns of a conflict-ignoring insert (built once per table):
+	* every primary / unique key set, their RETURNING list, and the key columns
+	* whose physical type is not text (see {@link mapIgnoredBatch}). Keyed on the
+	* detected extension state the type mapper reads.
+	*/
+	_ignorePlan() {
+		const key = `${this._supportsGeo}|${this._supportsVector}`;
+		const memo = this._ignorePlanMemo;
+		if (memo?.key === key) return memo;
+		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(", ")}` : "";
+		this._ignorePlanMemo = {
+			key,
+			keySets,
+			returning,
+			nonTextKeyCols,
+			returningSuffix
+		};
+		return this._ignorePlanMemo;
 	}
 	async findOne(query) {
 		const where = buildWhere(query.filter);
@@ -893,9 +1068,48 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		this._log(sql, params);
 		return mapQueryErrors(pgDialect, () => this._exec().all(sql, params), query.controls);
 	}
-	/** Physical primary-key columns (`@db.column` renames applied). */
-	_pkColumns() {
-		return this._table.primaryKeys.map((key) => this._table.physicalPath(key));
+	/**
+	* Physical primary-key columns (`@db.column` renames applied) and their
+	* ` RETURNING …` clause (empty without a PK) — built once per table.
+	*/
+	_pk() {
+		const src = this._table.primaryKeys;
+		let memo = this._pkColumnsMemo;
+		if (memo?.src !== src) {
+			const cols = src.map((key) => this._table.physicalPath(key));
+			const returning = cols.length > 0 ? ` RETURNING ${cols.map((c) => qi(c)).join(", ")}` : "";
+			memo = this._pkColumnsMemo = {
+				src,
+				cols,
+				returning
+			};
+		}
+		return memo;
+	}
+	/**
+	* Whether `filter` pins at most one row by itself: a plain object holding
+	* exactly the primary-key columns, each equal to a scalar (`{ id: 5 }` or
+	* `{ id: { $eq: 5 } }`) — what the core sends for a by-id write. Such a
+	* filter needs no `LIMIT 1` re-keying subquery: the outer predicate is the
+	* PK equality either way.
+	*/
+	_isExactPkFilter(filter) {
+		const pk = this._pk().cols;
+		if (pk.length === 0 || typeof filter !== "object" || filter === null || Array.isArray(filter)) return false;
+		const f = filter;
+		if (Object.keys(f).length !== pk.length) return false;
+		for (const col of pk) {
+			if (!Object.hasOwn(f, col)) return false;
+			let value = f[col];
+			if (typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype) {
+				const ops = Object.keys(value);
+				if (ops.length !== 1 || ops[0] !== "$eq") return false;
+				value = value.$eq;
+			}
+			const t = typeof value;
+			if (t !== "string" && t !== "number" && t !== "bigint" && t !== "boolean") return false;
+		}
+		return true;
 	}
 	/**
 	* The predicate that narrows a single-row UPDATE/DELETE to the first row
@@ -906,21 +1120,18 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	* existing behavior rather than guess.
 	*/
 	_limitOnePredicate(quotedTable, whereSql) {
-		const pkCols = this._pkColumns();
+		const pkCols = this._pk().cols;
 		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)`;
 	}
-	async updateOne(filter, data, ops, expectedVersion) {
+	async updateOne(filter, data, ops, expectedVersion, opts) {
 		const where = buildWhere(filter);
 		const tableName = this.resolveTableName();
-		const quotedTable = quoteTableName(tableName);
-		const limitedWhere = {
-			sql: this._limitOnePredicate(quotedTable, where.sql),
+		const { sql, params } = buildUpdate$1(tableName, data, this._isExactPkFilter(filter) ? where : {
+			sql: this._limitOnePredicate(quoteTableName(tableName), where.sql),
 			params: where.params
-		};
-		const versionColumn = this._table.versionColumnPhysical;
-		const { sql, params } = buildUpdate$1(tableName, data, limitedWhere, void 0, ops, versionColumn, expectedVersion);
+		}, void 0, ops, this._versionColumnFor(opts, expectedVersion), expectedVersion);
 		this._log(sql, params);
 		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
 		return {
@@ -928,9 +1139,9 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 			modifiedCount: result.affectedRows
 		};
 	}
-	async updateMany(filter, data, ops) {
+	async updateMany(filter, data, ops, opts) {
 		const where = buildWhere(filter);
-		const versionColumn = this._table.versionColumnPhysical;
+		const versionColumn = this._versionColumnFor(opts);
 		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, void 0, ops, versionColumn);
 		this._log(sql, params);
 		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
@@ -940,14 +1151,25 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		};
 	}
 	async replaceOne(filter, data, expectedVersion) {
-		const full = fillReplacePayload(data, replaceColumnsFor(this._table.fieldDescriptors, this.nativeDefaultFns()), this._table.versionColumnPhysical);
+		const full = fillReplacePayload(data, this._replaceColumns(), this._table.versionColumnPhysical);
 		return this.updateOne(filter, full, void 0, expectedVersion);
 	}
+	/** The columns a full replace assigns (`replaceColumnsFor`), built once per table. */
+	_replaceColumns() {
+		const src = this._table.fieldDescriptors;
+		let memo = this._replaceColumnsMemo;
+		if (memo?.src !== src) memo = this._replaceColumnsMemo = {
+			src,
+			cols: replaceColumnsFor(src, this.nativeDefaultFns())
+		};
+		return memo.cols;
+	}
 	async replaceMany(filter, data) {
 		return this.updateMany(filter, data);
 	}
 	async deleteOne(filter) {
 		const where = buildWhere(filter);
+		if (this._isExactPkFilter(filter)) return this._deleteWhere(where);
 		const quotedTable = quoteTableName(this.resolveTableName());
 		const { sql, params } = finalizeParams(pgDialect, {
 			sql: `DELETE FROM ${quotedTable} WHERE ${where.sql} AND ${this._limitOnePredicate(quotedTable, where.sql)}`,
@@ -957,18 +1179,24 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		return { deletedCount: (await this._wrapConstraintError(() => this._exec().run(sql, params))).affectedRows };
 	}
 	async deleteMany(filter) {
-		const where = buildWhere(filter);
+		return this._deleteWhere(buildWhere(filter));
+	}
+	async _deleteWhere(where) {
 		const { sql, params } = buildDelete$1(this.resolveTableName(), where);
 		this._log(sql, params);
 		return { deletedCount: (await this._wrapConstraintError(() => this._exec().run(sql, params))).affectedRows };
 	}
 	async prepareTypeMapper() {
 		if (this._supportsVector === void 0 && this._vectorFields.size > 0) await this._detectVectorSupport();
-		if (this._supportsGeo === void 0 && this._hasGeoPointFields()) await this._detectGeoSupport();
+		if (!this._geoInstallTried && this._hasGeoPointFields()) await this._detectGeoSupport();
 	}
-	/** Whether the table declares any `db.geoPoint` fields (unencrypted). */
+	/**
+	* Whether the table declares any `db.geoPoint` fields (unencrypted) — set
+	* when the metadata is built (`false` before, and on an administrative
+	* adapter: no geo value can be formatted without built metadata).
+	*/
 	_hasGeoPointFields() {
-		return this._table.fieldDescriptors.some((fd) => fd.isGeoPoint && !fd.encrypted);
+		return this._geoFields === true;
 	}
 	async ensureTable(opts) {
 		if (this._nocaseColumns.size > 0 && !this._citextProvisioned) try {
@@ -1275,9 +1503,11 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 				await conn.exec(ddl);
 			}
 			await conn.exec("COMMIT");
+			this._geoSchemaChanged();
 			await this._resetIdentitySequences();
 		} catch (err) {
 			await conn.exec("ROLLBACK").catch(() => {});
+			this._geoSchemaChanged();
 			const detail = err.detail;
 			if (err instanceof Error && typeof detail === "string" && detail.length > 0) err.message = `${err.message} — ${detail}`;
 			throw err;
@@ -1333,6 +1563,7 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	}
 	async afterSyncTable() {
 		await this._resetIdentitySequences();
+		if (this._geoFields && this._supportsGeo === true && this._geoNative.size === 0) await this._probeGeo(this._txConnection() ?? this.driver).catch(() => void 0);
 	}
 	/**
 	* Resets IDENTITY sequences to MAX(column) so that the next auto-generated
@@ -1440,7 +1671,9 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 			},
 			createIndex: async (index) => {
 				if (index.type === "fulltext") {
-					const tsvectorExpr = this._buildTsvectorExpr(index.fields);
+					const textFields = splitFulltextFields(index).text;
+					if (textFields.length === 0) return;
+					const tsvectorExpr = this._buildTsvectorExpr(textFields);
 					const sql = `CREATE INDEX IF NOT EXISTS ${qi(index.key)} ON ${quoteTableName(this.resolveTableName())} USING gin(to_tsvector('english', ${tsvectorExpr}))`;
 					this._log(sql);
 					await this._exec().exec(sql);
@@ -1533,13 +1766,23 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		return byName;
 	}
 	getSearchIndexes() {
+		const src = this._table.indexes;
+		let memo = this._searchIndexesMemo;
+		if (memo?.src !== src) memo = this._searchIndexesMemo = {
+			src,
+			list: this._buildSearchIndexes()
+		};
+		return [...memo.list];
+	}
+	_buildSearchIndexes() {
 		const indexes = [];
-		for (const index of this._table.indexes.values()) if (index.type === "fulltext") indexes.push({
+		const { all: ftAll, def: ftDefault } = this._fulltextIndexes();
+		for (const index of ftAll) indexes.push({
 			name: index.key,
-			description: `GIN tsvector index on ${index.fields.map((f) => f.name).join(", ")}`,
+			description: describeFulltext(index, (names) => `GIN tsvector index on ${names}`),
 			type: "text",
 			fields: this._indexLogicalPaths(index),
-			isDefault: indexes.length === 0
+			isDefault: index === ftDefault
 		});
 		let firstVector = true;
 		for (const [field, vec] of this._vectorFields) {
@@ -1590,12 +1833,24 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	_buildSearchWhere(text, query, indexName) {
 		const fulltextIndex = this._getFulltextIndex(indexName);
 		if (!fulltextIndex) throw new Error("No fulltext index found for search");
-		const tsvectorExpr = this._buildTsvectorExpr(fulltextIndex.fields);
+		const { text: textFields, integer: integerFields } = splitFulltextFields(fulltextIndex);
 		const where = buildWhere(query.filter);
-		const tsqueryClause = `to_tsvector('english', ${tsvectorExpr}) @@ plainto_tsquery('english', ?)`;
+		const n = integerFields.length > 0 ? searchTermInteger(text) : void 0;
+		const parts = [];
+		const params = [];
+		if (textFields.length > 0) {
+			const tsvectorExpr = this._buildTsvectorExpr(textFields);
+			parts.push(`to_tsvector('english', ${tsvectorExpr}) @@ plainto_tsquery('english', ?)`);
+			params.push(text);
+		}
+		if (n !== void 0) for (const f of integerFields) {
+			parts.push(`${qi(f.name)} = CAST(? AS BIGINT)`);
+			params.push(n);
+		}
+		const clause = orFragment(parts, params);
 		return {
-			sql: where.sql === "1=1" ? tsqueryClause : `${where.sql} AND ${tsqueryClause}`,
-			params: [...where.params, text]
+			sql: where.sql === "1=1" ? clause.sql : `${where.sql} AND ${clause.sql}`,
+			params: [...where.params, ...clause.params]
 		};
 	}
 	/** Builds the tsvector SQL expression for a fulltext index's fields. Must match between index DDL and queries. */
@@ -1603,9 +1858,23 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		return fields.map((f) => `coalesce(${qi(f.name)}, '')`).join(" || ' ' || ");
 	}
 	_getFulltextIndex(indexName) {
-		for (const index of this._table.indexes.values()) if (index.type === "fulltext") {
-			if (!indexName || index.key === indexName) return index;
+		const { all, def } = this._fulltextIndexes();
+		if (!indexName) return def;
+		return all.find((index) => index.key === indexName);
+	}
+	/** The table's fulltext indexes and the default one, built once per table. */
+	_fulltextIndexes() {
+		const src = this._table.indexes;
+		let memo = this._fulltextMemo;
+		if (memo?.src !== src) {
+			const all = [...src.values()].filter((i) => i.type === "fulltext");
+			memo = this._fulltextMemo = {
+				src,
+				all,
+				def: defaultFulltextIndex(all)
+			};
 		}
+		return memo;
 	}
 	/**
 	* Detects pgvector support by attempting to enable the extension.
@@ -1627,15 +1896,16 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	async vectorSearch(vector, query, indexName) {
 		await this._detectVectorSupport();
 		if (!this._supportsVector) throw new Error("Vector search requires the pgvector extension");
-		const { sql, params } = this._buildVectorSearchQuery(vector, query, indexName);
+		const { sql, params } = this._buildVectorSearchQuery(this._prepareVectorSearch(vector, query, indexName));
 		this._log(sql, params);
 		return this._exec().all(sql, params);
 	}
 	async vectorSearchWithCount(vector, query, indexName) {
 		await this._detectVectorSupport();
 		if (!this._supportsVector) throw new Error("Vector search requires the pgvector extension");
-		const { sql, params } = this._buildVectorSearchQuery(vector, query, indexName);
-		const { sql: countSql, params: countParams } = this._buildVectorSearchCountQuery(vector, query, indexName);
+		const ctx = this._prepareVectorSearch(vector, query, indexName);
+		const { sql, params } = this._buildVectorSearchQuery(ctx);
+		const { sql: countSql, params: countParams } = this._buildVectorSearchCountQuery(ctx);
 		this._log(sql, params);
 		this._log(countSql, countParams);
 		const [data, countRow] = await Promise.all([this._exec().all(sql, params), this._exec().get(countSql, countParams)]);
@@ -1689,8 +1959,7 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 			maxDistance: ctx.threshold === void 0 ? void 0 : thresholdToDistance(ctx.threshold, ctx.vec.similarity)
 		};
 	}
-	_buildVectorSearchQuery(vector, query, indexName) {
-		const ctx = this._prepareVectorSearch(vector, query, indexName);
+	_buildVectorSearchQuery(ctx) {
 		const { source, maxDistance } = this._vectorSearchSource(ctx, true);
 		const skip = Number(ctx.controls.$skip) || 0;
 		return buildVectorSearchSelect(pgDialect, source, {
@@ -1700,8 +1969,8 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 			maxDistance
 		});
 	}
-	_buildVectorSearchCountQuery(vector, query, indexName) {
-		const { source, maxDistance } = this._vectorSearchSource(this._prepareVectorSearch(vector, query, indexName), false);
+	_buildVectorSearchCountQuery(ctx) {
+		const { source, maxDistance } = this._vectorSearchSource(ctx, false);
 		return buildVectorSearchCount(pgDialect, source, { maxDistance });
 	}
 	/** Resolves threshold: query-time $threshold > schema-level @db.search.vector.threshold. */
@@ -1711,11 +1980,13 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		return this._vectorThresholds.get(indexName);
 	}
 	/**
-	* Detects PostGIS support by attempting to enable the extension.
-	* Idempotent — safe to call multiple times.
+	* Detects PostGIS support by attempting to enable the extension — schema
+	* sync's detection ({@link prepareTypeMapper}). Runs once; a probe that
+	* already found PostGIS skips it.
 	*/
 	async _detectGeoSupport() {
-		if (this._supportsGeo !== void 0) return this._supportsGeo;
+		if (this._geoInstallTried || this._supportsGeo === true) return this._supportsGeo === true;
+		this._geoInstallTried = true;
 		try {
 			await this._exec().exec("CREATE EXTENSION IF NOT EXISTS postgis");
 			this._supportsGeo = true;
@@ -1725,17 +1996,92 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		}
 		return this._supportsGeo;
 	}
+	/**
+	* Whether geo column `column` is a PostGIS column (EWKT) — synchronously
+	* when known, else after {@link _probeGeo} on `exec` (the statement's own
+	* executor). A column the catalog does not show (table not created yet)
+	* follows PostGIS presence — what sync would create — and is probed again
+	* next time.
+	*/
+	_geoColumnNative(column, exec) {
+		if (this._supportsGeo === false) return false;
+		const known = this._geoNative.get(column);
+		if (known !== void 0) return known;
+		return this._probeGeo(exec).then((probe) => probe.columns.get(column) ?? this._supportsGeo ?? probe.postgis);
+	}
+	/**
+	* The read-only geo probe ({@link GEO_PROBE_SQL}) of this table on `exec`:
+	* records PostGIS presence when not known yet, and caches the type of every
+	* geo column the catalog shows (unless a DDL path ran meanwhile).
+	*
+	* Concurrent callers on the SAME executor share one probe; a caller on
+	* another executor runs its own — waiting on a probe queued for a pool
+	* connection while holding a transaction connection could deadlock a
+	* small pool, and a transaction's failure (an aborted one) never reaches
+	* callers outside it. A failed probe is not cached, and a caller that
+	* joined it retries once (a pool probe may have hit a broken connection).
+	*/
+	_probeGeo(exec) {
+		const shared = this._geoProbe;
+		if (shared?.exec === exec) return shared.promise.catch(() => this._runGeoProbe(exec));
+		const promise = this._runGeoProbe(exec);
+		const entry = {
+			exec,
+			promise
+		};
+		this._geoProbe = entry;
+		const clear = () => {
+			if (this._geoProbe === entry) this._geoProbe = void 0;
+		};
+		promise.then(clear, clear);
+		return promise;
+	}
+	async _runGeoProbe(exec) {
+		const gen = this._geoSchemaGen;
+		const row = await exec.get(GEO_PROBE_SQL, [quoteTableName(this.resolveTableName()), this._geoColumnNames]);
+		const postgis = row?.postgis === true;
+		const raw = typeof row?.columns === "string" ? JSON.parse(row.columns) : row?.columns;
+		const columns = /* @__PURE__ */ new Map();
+		if (raw && typeof raw === "object") for (const [name, type] of Object.entries(raw)) columns.set(name, POSTGIS_TYPES.has(String(type)));
+		this._supportsGeo ??= postgis;
+		if (gen === this._geoSchemaGen) for (const [name, native] of columns) this._geoNative.set(name, native);
+		return {
+			postgis,
+			columns
+		};
+	}
+	/**
+	* A DDL path ran (create / alter / recreate / rename / drop): the geo
+	* column types are learned anew, and a probe in flight caches nothing.
+	*/
+	_geoSchemaChanged() {
+		if (this._geoFields) {
+			this._geoNative.clear();
+			this._geoSchemaGen++;
+			this._geoProbe = void 0;
+		}
+	}
+	/**
+	* PostGIS presence when known; while unknown (no sync, no statement yet),
+	* a table with geo columns answers `true` — the geo paths learn presence
+	* before they run and refuse with `GEO_NOT_SUPPORTED` then, so the first
+	* geo search of a process that never syncs is not refused up front.
+	*/
 	isGeoSearchable() {
-		return this._supportsGeo === true;
+		return this._supportsGeo ?? this._hasGeoPointFields();
+	}
+	/** PostGIS presence, probed when not known yet (geo search entry points). */
+	async _ensureGeoKnown() {
+		if (this._supportsGeo === void 0) await this._probeGeo(this._txConnection() ?? this.driver);
 	}
 	async geoSearch(point, query, indexName) {
-		await this._detectGeoSupport();
+		await this._ensureGeoKnown();
 		const { sql, params } = this._buildGeoSearchSelect(this._prepareGeoSearch(point, query, indexName));
 		this._log(sql, params);
 		return (await this._exec().all(sql, params)).map((row) => renameGeoDistance(row));
 	}
 	async geoSearchWithCount(point, query, indexName) {
-		await this._detectGeoSupport();
+		await this._ensureGeoKnown();
 		const ctx = this._prepareGeoSearch(point, query, indexName);
 		const { sql, params } = this._buildGeoSearchSelect(ctx);
 		const countFrag = buildGeoSearchCount(pgDialect, ctx.tableName, ctx.where, ctx.dist, ctx.window);
@@ -1749,10 +2095,7 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	}
 	/** Resolves the shared parts of a geo search once (column, filter, distance, window). */
 	_prepareGeoSearch(point, query, indexName) {
-		if (!this._supportsGeo) throw new DbError("GEO_NOT_SUPPORTED", [{
-			path: "",
-			message: "Geo search requires the PostGIS extension"
-		}]);
+		if (!this._supportsGeo) throw geoNotSupported("", "Geo search requires the PostGIS extension");
 		const column = this._resolveGeoColumn(indexName);
 		const controls = query.controls ?? {};
 		return {
@@ -1870,16 +2213,39 @@ function vectorToString(vector) {
 }
 //#endregion
 //#region src/pg-driver.ts
-/** pg rejects `undefined` in bind arrays — coerce to `null`. */
+const NO_PARAMS = [];
+/**
+* pg rejects `undefined` in bind arrays — coerce to `null`. Copies only when
+* there is one (an array hole counts): the common case binds `params` as is
+* (pg never mutates the bind array).
+*/
 function sanitizeParams(params) {
-	if (!params) return [];
-	return params.map((v) => v === void 0 ? null : v);
+	if (!params) return NO_PARAMS;
+	return params.includes(void 0) ? Array.from(params, (v) => v === void 0 ? null : v) : params;
 }
-/** Parses TIMESTAMP/TIMESTAMPTZ to epoch milliseconds. */
+/** Parses TIMESTAMPTZ (its text carries the UTC offset) to epoch milliseconds. */
 function parseTimestamp(val) {
 	const ms = new Date(val).getTime();
 	return Number.isNaN(ms) ? val : ms;
 }
+/** PostgreSQL's text form of a `timestamp without time zone` (AD, finite): `YYYY-MM-DD HH:MM:SS[.ffffff]`. */
+const TIMESTAMP_TEXT = /^(\d{4,})-(\d\d)-(\d\d) (\d\d):(\d\d):(\d\d)(?:\.(\d{1,6}))?$/;
+/**
+* Parses TIMESTAMP (without time zone) to epoch milliseconds, reading the
+* wall time as UTC — the same instant whatever the process time zone (since
+* 0.1.151; it used to be the process's local time). Matches the MySQL
+* adapter's DATETIME reading. Sub-millisecond digits are truncated; other
+* forms (`infinity`, BC dates) keep the previous parse.
+*/
+function parseTimestampUtc(val) {
+	const m = TIMESTAMP_TEXT.exec(val);
+	if (!m) return parseTimestamp(val);
+	const d = /* @__PURE__ */ new Date(0);
+	d.setUTCFullYear(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+	d.setUTCHours(Number(m[4]), Number(m[5]), Number(m[6]), m[7] ? Number(m[7].padEnd(3, "0").slice(0, 3)) : 0);
+	const ms = d.getTime();
+	return Number.isNaN(ms) ? val : ms;
+}
 /** Parses NUMERIC to number. */
 function parseNumeric(val) {
 	const n = Number.parseFloat(val);
@@ -1899,13 +2265,14 @@ const INT8_OID = 20;
 * Creates a per-pool custom types config that overrides specific parsers
 * without mutating the global `pg.types`.
 *
-* - TIMESTAMP/TIMESTAMPTZ → epoch milliseconds (number)
+* - TIMESTAMPTZ → epoch milliseconds (number); TIMESTAMP → epoch ms of its
+*   wall time read as UTC (independent of the process time zone)
 * - NUMERIC → number (not string)
 * - INT8/BIGINT → number (for JS-safe range)
 */
 function createCustomTypes(pgTypes) {
 	const overrides = new Map([
-		[TIMESTAMP_OID, parseTimestamp],
+		[TIMESTAMP_OID, parseTimestampUtc],
 		[TIMESTAMPTZ_OID, parseTimestamp],
 		[NUMERIC_OID, parseNumeric],
 		[INT8_OID, parseBigInt]