@atscript/db-postgres 0.1.38

package/dist/index.mjs

@@ -0,0 +1,1326 @@
+import { AtscriptDbView, BaseDbAdapter, DbError, DbSpace } from "@atscript/db";
+import { buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildInsert, buildSelect, buildUpdate, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, finalizeParams, refActionToSql } from "@atscript/db-sql-tools";
+import { AnnotationSpec } from "@atscript/core";
+
+//#region packages/db-postgres/src/sql-builder.ts
+function defaultValueForType$1(designType) {
+	if (designType === "boolean") return "false";
+	if (designType === "json" || designType === "object") return "'{}'";
+	if (designType === "array") return "'[]'";
+	return defaultValueForType(designType);
+}
+function defaultValueToSqlLiteral$1(designType, value) {
+	if (designType === "boolean") return value === "true" || value === "1" ? "true" : "false";
+	return defaultValueToSqlLiteral(designType, value);
+}
+function esc(name) {
+	return name.replace(/"/g, "\"\"");
+}
+function qi(name) {
+	return `"${esc(name)}"`;
+}
+function quoteTableName(name) {
+	const dot = name.indexOf(".");
+	if (dot >= 0) return `${qi(name.slice(0, dot))}.${qi(name.slice(dot + 1))}`;
+	return qi(name);
+}
+/** Converts JS values to SQL-bindable params, keeping booleans native. */ function toPgValue(value) {
+	if (value === undefined) return null;
+	if (value === null) return null;
+	if (value instanceof Date) return value.toISOString();
+	if (typeof value === "object") return JSON.stringify(value);
+	return value;
+}
+const pgDialect = {
+	quoteIdentifier(name) {
+		return qi(name);
+	},
+	quoteTable(name) {
+		return quoteTableName(name);
+	},
+	unlimitedLimit: "ALL",
+	toValue: toPgValue,
+	toParam(value) {
+		if (value === undefined) return null;
+		return value;
+	},
+	regex(quotedCol, value) {
+		const pattern = value instanceof RegExp ? value.source : String(value);
+		return {
+			sql: `${quotedCol} ~ ?`,
+			params: [pattern]
+		};
+	},
+	createViewPrefix: "CREATE OR REPLACE VIEW",
+	paramPlaceholder(index) {
+		return `$${index}`;
+	}
+};
+function buildInsert$1(table, data) {
+	return buildInsert(pgDialect, table, data);
+}
+function buildSelect$1(table, where, controls) {
+	return buildSelect(pgDialect, table, where, controls);
+}
+function buildUpdate$1(table, data, where, limit) {
+	return buildUpdate(pgDialect, table, data, where, limit);
+}
+function buildDelete$1(table, where, limit) {
+	return buildDelete(pgDialect, table, where, limit);
+}
+function buildCreateView$1(viewName, plan, columns, resolveFieldRef) {
+	return buildCreateView(pgDialect, viewName, plan, columns, resolveFieldRef);
+}
+function buildAggregateSelect$1(table, where, controls) {
+	return buildAggregateSelect(pgDialect, table, where, controls);
+}
+function buildAggregateCount$1(table, where, controls) {
+	return buildAggregateCount(pgDialect, table, where, controls);
+}
+function collationToPg(collation) {
+	switch (collation) {
+		case "binary": return "\"C\"";
+		case "nocase": return null;
+		case "unicode": return "\"und-x-icu\"";
+		default: return "\"und-x-icu\"";
+	}
+}
+/** Maps integer primitive tags to PostgreSQL integer types.
+* Unsigned types are promoted to the next-larger PG type because
+* PostgreSQL only has signed integer types:
+*   uint16 (0-65535) → INTEGER (not SMALLINT which caps at 32767)
+*   uint32 (0-4.3B)  → BIGINT  (not INTEGER which caps at ~2.1B)
+*/ function intTypeFromTags(tags) {
+	if (tags?.has("int8") || tags?.has("byte")) return "SMALLINT";
+	if (tags?.has("uint8")) return "SMALLINT";
+	if (tags?.has("int16") || tags?.has("port")) return "SMALLINT";
+	if (tags?.has("uint16")) return "INTEGER";
+	if (tags?.has("int32")) return "INTEGER";
+	if (tags?.has("uint32")) return "BIGINT";
+	if (tags?.has("int64") || tags?.has("uint64")) return "BIGINT";
+	return "INTEGER";
+}
+function pgTypeFromField(field) {
+	if (field.fkTargetField) return pgTypeFromField(field.fkTargetField);
+	const tags = field.type?.type?.tags;
+	const metadata = field.type?.metadata;
+	const pgTypeOverride = metadata?.get("db.pg.type");
+	if (pgTypeOverride) return pgTypeOverride;
+	const precision = metadata?.get("db.column.precision");
+	switch (field.designType) {
+		case "number": {
+			if (precision) return `NUMERIC(${precision.precision},${precision.scale})`;
+			if (field.defaultValue?.kind === "fn" && field.defaultValue.fn === "increment") return "BIGINT";
+			if (field.defaultValue?.kind === "fn" && field.defaultValue.fn === "now") return "BIGINT";
+			if (tags?.has("int")) return intTypeFromTags(tags);
+			return "DOUBLE PRECISION";
+		}
+		case "integer": return intTypeFromTags(tags);
+		case "decimal": {
+			if (precision) return `NUMERIC(${precision.precision},${precision.scale})`;
+			return "NUMERIC(10,2)";
+		}
+		case "boolean": return "BOOLEAN";
+		case "string": {
+			if (field.collate === "nocase" && !metadata?.get("db.pg.collate")) return "CITEXT";
+			if (tags?.has("char")) return "CHAR(1)";
+			const maxLen = metadata?.get("expect.maxLength")?.length;
+			if (maxLen !== undefined) return `VARCHAR(${maxLen})`;
+			if (field.isPrimaryKey || field.defaultValue) return "VARCHAR(255)";
+			return "TEXT";
+		}
+		case "json":
+		case "object":
+		case "array": return "JSONB";
+		default: {
+			if (field.isPrimaryKey || field.defaultValue) return "VARCHAR(255)";
+			return "TEXT";
+		}
+	}
+}
+function buildCreateTable(table, fields, foreignKeys, options) {
+	const colDefs = [];
+	const primaryKeys = fields.filter((f) => f.isPrimaryKey);
+	for (const field of fields) {
+		if (field.ignored) continue;
+		const sqlType = options?.typeMapper?.(field) ?? pgTypeFromField(field);
+		let def = `${qi(field.physicalName)} ${sqlType}`;
+		if (options?.incrementFields?.has(field.physicalName)) {
+			const start = options.autoIncrementStart;
+			def += start !== undefined ? ` 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.defaultValue?.kind === "value") def += ` DEFAULT ${defaultValueToSqlLiteral$1(field.designType, field.defaultValue.value)}`;
+else if (field.defaultValue?.kind === "fn") {
+			if (field.defaultValue.fn === "uuid") def += " DEFAULT gen_random_uuid()";
+else if (field.defaultValue.fn === "now") def += " DEFAULT (extract(epoch from now()) * 1000)::bigint";
+		}
+		const nativeCollate = field.type?.metadata?.get("db.pg.collate");
+		if (nativeCollate) def += ` COLLATE "${nativeCollate}"`;
+else if (field.collate) {
+			const pgCollate = collationToPg(field.collate);
+			if (pgCollate) def += ` COLLATE ${pgCollate}`;
+		}
+		colDefs.push(def);
+	}
+	if (primaryKeys.length === 1) {
+		const pkCol = qi(primaryKeys[0].physicalName);
+		for (let i = 0; i < colDefs.length; i++) if (colDefs[i].startsWith(`${pkCol} `)) {
+			colDefs[i] += " PRIMARY KEY";
+			break;
+		}
+	} else if (primaryKeys.length > 1) {
+		const pkCols = primaryKeys.map((pk) => qi(pk.physicalName)).join(", ");
+		colDefs.push(`PRIMARY KEY (${pkCols})`);
+	}
+	if (foreignKeys) for (const fk of foreignKeys.values()) {
+		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 ${refActionToSql(fk.onDelete)}`;
+		if (fk.onUpdate) constraint += ` ON UPDATE ${refActionToSql(fk.onUpdate)}`;
+		colDefs.push(constraint);
+	}
+	return `CREATE TABLE IF NOT EXISTS ${quoteTableName(table)} (${colDefs.join(", ")})`;
+}
+function offsetPlaceholders(fragment, offset) {
+	if (offset === 0) return fragment;
+	const sql = fragment.sql.replace(/\$(\d+)/g, (_, n) => `$${Number(n) + offset}`);
+	return {
+		sql,
+		params: fragment.params
+	};
+}
+
+//#endregion
+//#region packages/db-postgres/src/filter-builder.ts
+function buildWhere(filter) {
+	return buildWhere$1(pgDialect, filter);
+}
+
+//#endregion
+//#region packages/db-postgres/src/postgres-adapter.ts
+function _define_property$1(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+else obj[key] = value;
+	return obj;
+}
+/** PostgreSQL COUNT() may return string (bigint) — parse to number. */ function parseCount(value) {
+	if (typeof value === "string") return Number.parseInt(value, 10);
+	return value ?? 0;
+}
+var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
+	/** Schema name for queries (null falls through to 'public'). */ get _schema() {
+		return this._table.schema ?? null;
+	}
+	async _beginTransaction() {
+		const conn = await this.driver.getConnection();
+		try {
+			await conn.exec("BEGIN");
+			this._log("BEGIN");
+			return conn;
+		} catch (err) {
+			conn.release();
+			throw err;
+		}
+	}
+	async _commitTransaction(state) {
+		const conn = state;
+		try {
+			this._log("COMMIT");
+			await conn.exec("COMMIT");
+		} finally {
+			conn.release();
+		}
+	}
+	async _rollbackTransaction(state) {
+		const conn = state;
+		try {
+			this._log("ROLLBACK");
+			await conn.exec("ROLLBACK");
+		} finally {
+			conn.release();
+		}
+	}
+	/**
+	* Returns the active executor: dedicated connection if inside a transaction,
+	* otherwise the pool-based driver.
+	*/ _exec() {
+		const txState = this._getTransactionState();
+		return txState ?? this.driver;
+	}
+	/** PostgreSQL enforces FK constraints natively. */ supportsNativeForeignKeys() {
+		return true;
+	}
+	prepareId(id, _fieldType) {
+		return id;
+	}
+	supportsNativeValueDefaults() {
+		return true;
+	}
+	nativeDefaultFns() {
+		return PostgresAdapter.NATIVE_DEFAULT_FNS;
+	}
+	onBeforeFlatten(_type) {}
+	onAfterFlatten() {
+		for (const fd of this._table.fieldDescriptors) if (fd.collate === "nocase") this._nocaseColumns.add(fd.physicalName);
+	}
+	onFieldScanned(field, _type, metadata) {
+		if (metadata.has("db.default.increment")) {
+			this._incrementFields.add(field);
+			const startVal = metadata.get("db.default.increment");
+			if (typeof startVal === "number") this._autoIncrementStart = startVal;
+		}
+		const vectorMeta = metadata.get("db.search.vector");
+		if (vectorMeta) {
+			const indexName = vectorMeta.indexName || field;
+			this._vectorFields.set(field, {
+				dimensions: vectorMeta.dimensions,
+				similarity: vectorMeta.similarity || "cosine",
+				indexName
+			});
+			const threshold = metadata.get("db.search.vector.threshold");
+			if (threshold !== undefined) this._vectorThresholds.set(indexName, threshold);
+		}
+	}
+	getDesiredTableOptions() {
+		return [];
+	}
+	async getExistingTableOptions() {
+		return [];
+	}
+	/**
+	* Converts vector fields between JavaScript `number[]` and pgvector text format `[1,2,3]`.
+	* The pg driver serializes JS arrays as PostgreSQL array literals `{1,2,3}` which is
+	* invalid for the pgvector `vector` type — it expects bracket-delimited `[1,2,3]`.
+	*/ formatValue(field) {
+		if (!this._vectorFields.has(field.path)) return undefined;
+		return {
+			toStorage: (value) => Array.isArray(value) ? `[${value.join(",")}]` : value,
+			fromStorage: (value) => typeof value === "string" ? JSON.parse(value) : value
+		};
+	}
+	/**
+	* Wraps an async write operation to catch PostgreSQL constraint errors
+	* and rethrow as structured `DbError`.
+	*
+	* PostgreSQL uses SQLSTATE codes:
+	* - 23505 = unique_violation
+	* - 23503 = foreign_key_violation
+	*/ async _wrapConstraintError(fn) {
+		try {
+			return await fn();
+		} catch (error) {
+			if (error && typeof error === "object" && "code" in error) {
+				const err = error;
+				if (err.code === "23505") {
+					const field = this._extractFieldFromConstraint(err.constraint) ?? "";
+					throw new DbError("CONFLICT", [{
+						path: field,
+						message: err.detail ?? err.message
+					}]);
+				}
+				if (err.code === "23503") {
+					const errors = this._mapFkError(err.detail ?? err.message, err.constraint);
+					throw new DbError("FK_VIOLATION", errors);
+				}
+			}
+			throw error;
+		}
+	}
+	_extractFieldFromConstraint(constraint) {
+		if (!constraint) return undefined;
+		const tableName = this._table.tableName;
+		if (constraint.startsWith(`${tableName}_`) && constraint.endsWith("_key")) {
+			const fieldPart = constraint.slice(tableName.length + 1, -4);
+			const fd = this._table.fieldDescriptors.find((f) => f.physicalName === fieldPart);
+			if (fd) return fd.path;
+		}
+		return constraint;
+	}
+	_mapFkError(detail, constraint) {
+		const fkMatch = detail.match(/Key \(([^)]+)\)/);
+		if (fkMatch) {
+			const physicalCol = fkMatch[1].split(",")[0].trim();
+			const field = this._table.fieldDescriptors.find((f) => f.physicalName === physicalCol);
+			return [{
+				path: field?.path ?? physicalCol,
+				message: detail
+			}];
+		}
+		return [{
+			path: constraint ?? "",
+			message: detail
+		}];
+	}
+	async insertOne(data) {
+		let { sql, params } = buildInsert$1(this.resolveTableName(), data);
+		const pkCols = this._table.primaryKeys.map((pk) => qi(pk));
+		if (pkCols.length > 0) sql += ` RETURNING ${pkCols.join(", ")}`;
+		this._log(sql, params);
+		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
+		const returned = result.rows?.[0];
+		return { insertedId: this._resolveInsertedId(data, returned ? Object.values(returned)[0] : undefined) };
+	}
+	async insertMany(data) {
+		if (data.length === 0) return {
+			insertedCount: 0,
+			insertedIds: []
+		};
+		return this.withTransaction(async () => {
+			const tableName = this.resolveTableName();
+			const pkCols = this._table.primaryKeys;
+			const returningSuffix = pkCols.length > 0 ? ` RETURNING ${pkCols.map((pk) => qi(pk)).join(", ")}` : "";
+			const keys = Object.keys(data[0]);
+			const colsClause = keys.map((k) => qi(k)).join(", ");
+			const paramsPerRow = keys.length;
+			const maxRowsPerBatch = paramsPerRow > 0 ? Math.floor(6e4 / paramsPerRow) : data.length;
+			const allIds = [];
+			for (let offset = 0; offset < data.length; offset += maxRowsPerBatch) {
+				const batchEnd = Math.min(offset + maxRowsPerBatch, data.length);
+				const batchSize = batchEnd - offset;
+				const params = [];
+				const valuesClauses = [];
+				for (let i = offset; i < batchEnd; i++) {
+					const row = data[i];
+					const rowPlaceholders = [];
+					for (const k of keys) {
+						params.push(pgDialect.toValue(row[k]));
+						rowPlaceholders.push(`$${params.length}`);
+					}
+					valuesClauses.push(`(${rowPlaceholders.join(", ")})`);
+				}
+				const sql = `INSERT INTO ${quoteTableName(tableName)} (${colsClause}) VALUES ${valuesClauses.join(", ")}${returningSuffix}`;
+				this._log(sql, params);
+				const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
+				for (let i = 0; i < batchSize; i++) {
+					const returned = result.rows?.[i];
+					allIds.push(this._resolveInsertedId(data[offset + i], returned ? Object.values(returned)[0] : undefined));
+				}
+			}
+			return {
+				insertedCount: allIds.length,
+				insertedIds: allIds
+			};
+		});
+	}
+	async findOne(query) {
+		const where = buildWhere(query.filter);
+		const controls = {
+			...query.controls,
+			$limit: 1
+		};
+		const { sql, params } = buildSelect$1(this.resolveTableName(), where, controls);
+		this._log(sql, params);
+		return this._exec().get(sql, params);
+	}
+	async findMany(query) {
+		const where = buildWhere(query.filter);
+		const { sql, params } = buildSelect$1(this.resolveTableName(), where, query.controls);
+		this._log(sql, params);
+		return this._exec().all(sql, params);
+	}
+	async count(query) {
+		const where = buildWhere(query.filter);
+		const tableName = this.resolveTableName();
+		const raw = {
+			sql: `SELECT COUNT(*) as cnt FROM ${quoteTableName(tableName)} WHERE ${where.sql}`,
+			params: where.params
+		};
+		const { sql, params } = finalizeParams(pgDialect, raw);
+		this._log(sql, params);
+		const row = await this._exec().get(sql, params);
+		return parseCount(row?.cnt);
+	}
+	async aggregate(query) {
+		const where = buildWhere(query.filter);
+		const tableName = this.resolveTableName();
+		if (query.controls.$count) {
+			const { sql: sql$1, params: params$1 } = buildAggregateCount$1(tableName, where, query.controls);
+			this._log(sql$1, params$1);
+			const row = await this._exec().get(sql$1, params$1);
+			const count = parseCount(row?.count);
+			return [{ count }];
+		}
+		const { sql, params } = buildAggregateSelect$1(tableName, where, query.controls);
+		this._log(sql, params);
+		return this._exec().all(sql, params);
+	}
+	async updateOne(filter, data) {
+		const where = buildWhere(filter);
+		const tableName = this.resolveTableName();
+		const keys = Object.keys(data);
+		const setClauses = keys.map((k, i) => `${qi(k)} = $${i + 1}`);
+		const setParams = keys.map((k) => pgDialect.toValue(data[k]));
+		const finalizedWhere = finalizeParams(pgDialect, where);
+		const offsetWhere = offsetPlaceholders(finalizedWhere, keys.length);
+		const sql = `UPDATE ${quoteTableName(tableName)} SET ${setClauses.join(", ")} WHERE ctid = (SELECT ctid FROM ${quoteTableName(tableName)} WHERE ${offsetWhere.sql} LIMIT 1)`;
+		const params = [...setParams, ...where.params];
+		this._log(sql, params);
+		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
+		return {
+			matchedCount: result.affectedRows,
+			modifiedCount: result.affectedRows
+		};
+	}
+	async updateMany(filter, data) {
+		const where = buildWhere(filter);
+		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where);
+		this._log(sql, params);
+		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
+		return {
+			matchedCount: result.affectedRows,
+			modifiedCount: result.affectedRows
+		};
+	}
+	async replaceOne(filter, data) {
+		return this.updateOne(filter, data);
+	}
+	async replaceMany(filter, data) {
+		return this.updateMany(filter, data);
+	}
+	async deleteOne(filter) {
+		const where = buildWhere(filter);
+		const tableName = this.resolveTableName();
+		const raw = {
+			sql: `DELETE FROM ${quoteTableName(tableName)} WHERE ctid = (SELECT ctid FROM ${quoteTableName(tableName)} WHERE ${where.sql} LIMIT 1)`,
+			params: where.params
+		};
+		const { sql, params } = finalizeParams(pgDialect, raw);
+		this._log(sql, params);
+		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
+		return { deletedCount: result.affectedRows };
+	}
+	async deleteMany(filter) {
+		const where = buildWhere(filter);
+		const { sql, params } = buildDelete$1(this.resolveTableName(), where);
+		this._log(sql, params);
+		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
+		return { deletedCount: result.affectedRows };
+	}
+	async ensureTable() {
+		if (this._nocaseColumns.size > 0 && !this._citextProvisioned) try {
+			await this._exec().exec("CREATE EXTENSION IF NOT EXISTS citext");
+			this._citextProvisioned = true;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`Failed to create citext extension for @db.collate 'nocase' columns: ${msg}. ` + `Either run 'CREATE EXTENSION citext' as a superuser, or use @db.pg.type "CITEXT" after provisioning the extension manually.`);
+		}
+		if (this._supportsVector === undefined && this._vectorFields.size > 0) await this._detectVectorSupport();
+		if (this._table instanceof AtscriptDbView) return this._ensureView();
+		const sql = buildCreateTable(this.resolveTableName(), this._table.fieldDescriptors, this._table.foreignKeys, {
+			incrementFields: this._incrementFields,
+			autoIncrementStart: this._autoIncrementStart,
+			typeMapper: (field) => this.typeMapper(field)
+		});
+		this._log(sql);
+		await this._exec().exec(sql);
+	}
+	async _ensureView() {
+		const view = this._table;
+		const sql = buildCreateView$1(this.resolveTableName(), view.viewPlan, view.getViewColumnMappings(), (ref) => view.resolveFieldRef(ref, qi));
+		this._log(sql);
+		await this._exec().exec(sql);
+	}
+	async getExistingColumns() {
+		return this.getExistingColumnsForTable(this._table.tableName);
+	}
+	async getExistingColumnsForTable(tableName) {
+		const schema = this._schema;
+		const rows = await this._exec().all(`SELECT c.column_name, c.data_type, c.udt_name, c.character_maximum_length, c.numeric_precision, c.numeric_scale, c.is_nullable, c.column_default, c.is_identity,
+              format_type(a.atttypid, a.atttypmod) AS formatted_type
+       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')
+       ORDER BY c.ordinal_position`, [tableName, schema]);
+		const pkRows = await this._exec().all(`SELECT kcu.column_name
+       FROM information_schema.table_constraints tc
+       JOIN information_schema.key_column_usage kcu
+         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+       WHERE tc.table_name = $1 AND tc.table_schema = COALESCE($2, 'public')
+         AND tc.constraint_type = 'PRIMARY KEY'`, [tableName, schema]);
+		const pkSet = new Set(pkRows.map((r) => r.column_name));
+		return rows.map((r) => ({
+			name: r.column_name,
+			type: normalizePgType(r.data_type, r.character_maximum_length, r.numeric_precision, r.numeric_scale, r.udt_name, r.formatted_type),
+			notnull: r.is_nullable === "NO",
+			pk: pkSet.has(r.column_name),
+			dflt_value: normalizePgDefault(r.column_default, r.is_identity)
+		}));
+	}
+	async syncColumns(diff) {
+		if (this._nocaseColumns.size > 0) await this._exec().exec("CREATE EXTENSION IF NOT EXISTS citext");
+		const tableName = this.resolveTableName();
+		const added = [];
+		const renamed = [];
+		for (const { field, oldName } of diff.renamed ?? []) {
+			const ddl = `ALTER TABLE ${quoteTableName(tableName)} RENAME COLUMN ${qi(oldName)} TO ${qi(field.physicalName)}`;
+			this._log(ddl);
+			await this._exec().exec(ddl);
+			renamed.push(field.physicalName);
+		}
+		for (const field of diff.added) {
+			const sqlType = this.typeMapper(field);
+			let ddl = `ALTER TABLE ${quoteTableName(tableName)} ADD COLUMN ${qi(field.physicalName)} ${sqlType}`;
+			if (field.defaultValue?.kind === "fn" && field.defaultValue.fn === "increment") ddl += " GENERATED BY DEFAULT AS IDENTITY";
+else {
+				if (!field.optional && !field.isPrimaryKey) ddl += " NOT NULL";
+				if (field.defaultValue?.kind === "value") ddl += ` DEFAULT ${defaultValueToSqlLiteral$1(field.designType, field.defaultValue.value)}`;
+else if (field.defaultValue?.kind === "fn") {
+					if (field.defaultValue.fn === "uuid") ddl += " DEFAULT gen_random_uuid()";
+else if (field.defaultValue.fn === "now") ddl += " DEFAULT (extract(epoch from now()) * 1000)::bigint";
+				} else if (!field.optional && !field.isPrimaryKey) ddl += ` DEFAULT ${defaultValueForType$1(field.designType)}`;
+			}
+			if (field.collate) {
+				const nativeCollate = field.type?.metadata?.get("db.pg.collate");
+				if (nativeCollate) ddl += ` COLLATE "${nativeCollate}"`;
+else {
+					const pgCollate = collationToPg(field.collate);
+					if (pgCollate) ddl += ` COLLATE ${pgCollate}`;
+				}
+			}
+			this._log(ddl);
+			await this._exec().exec(ddl);
+			added.push(field.physicalName);
+		}
+		for (const { field } of diff.typeChanged ?? []) {
+			const sqlType = this.typeMapper(field);
+			const col = qi(field.physicalName);
+			const ddl = `ALTER TABLE ${quoteTableName(tableName)} ALTER COLUMN ${col} TYPE ${sqlType} USING ${col}::text::${sqlType}`;
+			this._log(ddl);
+			await this._exec().exec(ddl);
+		}
+		for (const { field } of diff.nullableChanged ?? []) {
+			if (!field.optional) {
+				const fallback = field.defaultValue?.kind === "value" ? defaultValueToSqlLiteral$1(field.designType, field.defaultValue.value) : defaultValueForType$1(field.designType);
+				const backfill = `UPDATE ${quoteTableName(tableName)} SET ${qi(field.physicalName)} = ${fallback} WHERE ${qi(field.physicalName)} IS NULL`;
+				this._log(backfill);
+				await this._exec().exec(backfill);
+			}
+			const nullability = field.optional ? "DROP NOT NULL" : "SET NOT NULL";
+			const ddl = `ALTER TABLE ${quoteTableName(tableName)} ALTER COLUMN ${qi(field.physicalName)} ${nullability}`;
+			this._log(ddl);
+			await this._exec().exec(ddl);
+		}
+		for (const { field } of diff.defaultChanged ?? []) {
+			let ddl;
+			if (field.defaultValue?.kind === "value") ddl = `ALTER TABLE ${quoteTableName(tableName)} ALTER COLUMN ${qi(field.physicalName)} SET DEFAULT ${defaultValueToSqlLiteral$1(field.designType, field.defaultValue.value)}`;
+else if (field.defaultValue?.kind === "fn") {
+				const fnExpr = field.defaultValue.fn === "now" ? "(extract(epoch from now()) * 1000)::bigint" : field.defaultValue.fn === "uuid" ? "gen_random_uuid()" : `${field.defaultValue.fn}()`;
+				ddl = `ALTER TABLE ${quoteTableName(tableName)} ALTER COLUMN ${qi(field.physicalName)} SET DEFAULT ${fnExpr}`;
+			} else ddl = `ALTER TABLE ${quoteTableName(tableName)} ALTER COLUMN ${qi(field.physicalName)} DROP DEFAULT`;
+			this._log(ddl);
+			await this._exec().exec(ddl);
+		}
+		return {
+			added,
+			renamed
+		};
+	}
+	async recreateTable() {
+		const tableName = this.resolveTableName();
+		const schema = this._schema;
+		const baseTempName = `${this._table.tableName}__tmp_${Date.now()}`;
+		const tempName = schema ? `${schema}.${baseTempName}` : baseTempName;
+		const conn = await this.driver.getConnection();
+		try {
+			await conn.exec("BEGIN");
+			const fkRefs = await conn.all(`SELECT tc.constraint_name, tc.table_name, tc.table_schema,
+                kcu.column_name, kcur.column_name AS ref_column_name,
+                rc.delete_rule, rc.update_rule
+         FROM information_schema.referential_constraints rc
+         JOIN information_schema.table_constraints tc
+           ON rc.constraint_name = tc.constraint_name AND rc.constraint_schema = tc.constraint_schema
+         JOIN information_schema.key_column_usage kcu
+           ON kcu.constraint_name = tc.constraint_name AND kcu.table_schema = tc.table_schema
+         JOIN information_schema.key_column_usage kcur
+           ON kcur.constraint_name = rc.unique_constraint_name AND kcur.table_schema = rc.unique_constraint_schema
+              AND kcur.ordinal_position = kcu.ordinal_position
+         WHERE rc.unique_constraint_schema = COALESCE($1, 'public')
+           AND rc.unique_constraint_name IN (
+             SELECT constraint_name FROM information_schema.table_constraints
+             WHERE table_name = $2 AND table_schema = COALESCE($1, 'public') AND constraint_type = 'PRIMARY KEY'
+           )`, [schema, this._table.tableName]);
+			const fkByName = new Map();
+			for (const fk of fkRefs) {
+				let entry = fkByName.get(fk.constraint_name);
+				if (!entry) {
+					entry = {
+						schema: fk.table_schema,
+						table: fk.table_name,
+						cols: [],
+						refCols: [],
+						onDelete: fk.delete_rule,
+						onUpdate: fk.update_rule
+					};
+					fkByName.set(fk.constraint_name, entry);
+				}
+				entry.cols.push(fk.column_name);
+				entry.refCols.push(fk.ref_column_name);
+			}
+			for (const [name, fk] of fkByName) {
+				const ddl = `ALTER TABLE ${qi(fk.schema)}.${qi(fk.table)} DROP CONSTRAINT IF EXISTS ${qi(name)}`;
+				this._log(ddl);
+				await conn.exec(ddl);
+			}
+			const createSql = buildCreateTable(tempName, this._table.fieldDescriptors, this._table.foreignKeys, {
+				incrementFields: this._incrementFields,
+				autoIncrementStart: this._autoIncrementStart,
+				typeMapper: (field) => this.typeMapper(field)
+			});
+			this._log(createSql);
+			await conn.exec(createSql);
+			const oldColRows = await conn.all(`SELECT column_name FROM information_schema.columns
+         WHERE table_name = $1 AND table_schema = COALESCE($2, 'public')
+         ORDER BY ordinal_position`, [this._table.tableName, schema]);
+			const newCols = this._table.fieldDescriptors.filter((f) => !f.ignored).map((f) => f.physicalName);
+			const oldColSet = new Set(oldColRows.map((c) => c.column_name));
+			const commonCols = newCols.filter((c) => oldColSet.has(c));
+			if (commonCols.length > 0) {
+				const fieldsByName = new Map(this._table.fieldDescriptors.map((f) => [f.physicalName, f]));
+				const colNames = commonCols.map((c) => qi(c)).join(", ");
+				const selectExprs = commonCols.map((c) => {
+					const field = fieldsByName.get(c);
+					if (field && !field.optional && !field.isPrimaryKey) {
+						const fallback = field.defaultValue?.kind === "value" ? defaultValueToSqlLiteral$1(field.designType, field.defaultValue.value) : defaultValueForType$1(field.designType);
+						return `COALESCE(${qi(c)}, ${fallback}) AS ${qi(c)}`;
+					}
+					return qi(c);
+				}).join(", ");
+				const copySql = `INSERT INTO ${quoteTableName(tempName)} (${colNames}) SELECT ${selectExprs} FROM ${quoteTableName(tableName)}`;
+				this._log(copySql);
+				await conn.exec(copySql);
+			}
+			await conn.exec(`DROP TABLE IF EXISTS ${quoteTableName(tableName)} CASCADE`);
+			await conn.exec(`ALTER TABLE ${quoteTableName(tempName)} RENAME TO ${qi(this._table.tableName)}`);
+			const resolvedTable = this.resolveTableName();
+			for (const [, fk] of fkByName) {
+				const localCols = fk.cols.map((c) => qi(c)).join(", ");
+				const refCols = fk.refCols.map((c) => qi(c)).join(", ");
+				let ddl = `ALTER TABLE ${qi(fk.schema)}.${qi(fk.table)} ADD FOREIGN KEY (${localCols}) REFERENCES ${quoteTableName(resolvedTable)} (${refCols})`;
+				if (fk.onDelete !== "NO ACTION") ddl += ` ON DELETE ${fk.onDelete}`;
+				if (fk.onUpdate !== "NO ACTION") ddl += ` ON UPDATE ${fk.onUpdate}`;
+				this._log(ddl);
+				await conn.exec(ddl);
+			}
+			await conn.exec("COMMIT");
+			await this._resetIdentitySequences();
+		} catch (err) {
+			await conn.exec("ROLLBACK").catch(() => {});
+			throw err;
+		} finally {
+			conn.release();
+		}
+	}
+	async afterSyncTable() {
+		await this._resetIdentitySequences();
+	}
+	/**
+	* Resets IDENTITY sequences to MAX(column) so that the next auto-generated
+	* value doesn't conflict with existing data. PostgreSQL's GENERATED BY DEFAULT
+	* AS IDENTITY does not advance the sequence when rows are inserted with explicit
+	* values, so this is needed after data seeding, bulk imports, or recreateTable().
+	*/ async _resetIdentitySequences() {
+		if (this._incrementFields.size === 0) return;
+		const tableName = this.resolveTableName();
+		const emptyFallback = this._autoIncrementStart ?? 1;
+		for (const field of this._incrementFields) {
+			const col = this._table.fieldDescriptors.find((f) => f.path === field)?.physicalName ?? field;
+			const sql = `SELECT setval(pg_get_serial_sequence('${tableName}', '${col}'), COALESCE(MAX(${qi(col)}), ${emptyFallback}), MAX(${qi(col)}) IS NOT NULL) FROM ${quoteTableName(tableName)}`;
+			this._log(sql);
+			await this._exec().run(sql);
+		}
+	}
+	async tableExists() {
+		const row = 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]);
+		return row?.exists ?? false;
+	}
+	async dropTable() {
+		const ddl = `DROP TABLE IF EXISTS ${quoteTableName(this.resolveTableName())} CASCADE`;
+		this._log(ddl);
+		await this._exec().exec(ddl);
+	}
+	async dropColumns(columns) {
+		const tableName = this.resolveTableName();
+		const drops = columns.map((col) => `DROP COLUMN ${qi(col)}`).join(", ");
+		const ddl = `ALTER TABLE ${quoteTableName(tableName)} ${drops}`;
+		this._log(ddl);
+		await this._exec().exec(ddl);
+	}
+	async dropTableByName(tableName) {
+		const ddl = `DROP TABLE IF EXISTS ${quoteTableName(tableName)} CASCADE`;
+		this._log(ddl);
+		await this._exec().exec(ddl);
+	}
+	async dropViewByName(viewName) {
+		const ddl = `DROP VIEW IF EXISTS ${quoteTableName(viewName)}`;
+		this._log(ddl);
+		await this._exec().exec(ddl);
+	}
+	async renameTable(oldName) {
+		const newName = this._table.tableName;
+		const ddl = `ALTER TABLE ${quoteTableName(oldName)} RENAME TO ${qi(newName)}`;
+		this._log(ddl);
+		await this._exec().exec(ddl);
+	}
+	typeMapper(field) {
+		if (this._vectorFields.has(field.path)) {
+			const vec = this._vectorFields.get(field.path);
+			return this._supportsVector ? `vector(${vec.dimensions})` : "JSONB";
+		}
+		return pgTypeFromField(field);
+	}
+	async syncIndexes() {
+		const tableName = this._table.tableName;
+		const schema = this._schema;
+		await this.syncIndexesWithDiff({
+			listExisting: async () => this._exec().all(`SELECT indexname AS name FROM pg_indexes
+           WHERE tablename = $1 AND schemaname = COALESCE($2, 'public')`, [tableName, schema]),
+			createIndex: async (index) => {
+				if (index.type === "fulltext") {
+					const tsvectorExpr = this._buildTsvectorExpr(index.fields);
+					const sql$1 = `CREATE INDEX IF NOT EXISTS ${qi(index.key)} ON ${quoteTableName(this.resolveTableName())} USING gin(to_tsvector('english', ${tsvectorExpr}))`;
+					this._log(sql$1);
+					await this._exec().exec(sql$1);
+					return;
+				}
+				const unique = index.type === "unique" ? "UNIQUE " : "";
+				const cols = index.fields.map((f) => `${qi(f.name)} ${f.sort === "desc" ? "DESC" : "ASC"}`).join(", ");
+				const sql = `CREATE ${unique}INDEX IF NOT EXISTS ${qi(index.key)} ON ${quoteTableName(this.resolveTableName())} (${cols})`;
+				this._log(sql);
+				await this._exec().exec(sql);
+			},
+			dropIndex: async (name) => {
+				const schemaPrefix = schema ? `${qi(schema)}.` : "";
+				const sql = `DROP INDEX IF EXISTS ${schemaPrefix}${qi(name)}`;
+				this._log(sql);
+				await this._exec().exec(sql);
+			}
+		});
+		if (this._supportsVector) for (const [field, vec] of this._vectorFields) {
+			const indexName = `atscript__vec_${vec.indexName}`;
+			const opsClass = similarityToPgOps(vec.similarity);
+			const sql = `CREATE INDEX IF NOT EXISTS ${qi(indexName)} ON ${quoteTableName(this.resolveTableName())} USING hnsw (${qi(field)} ${opsClass})`;
+			this._log(sql);
+			await this._exec().exec(sql);
+		}
+	}
+	async syncForeignKeys() {
+		const existingByName = await this._getExistingFkConstraints();
+		const desiredFkKeys = new Set();
+		for (const fk of this._table.foreignKeys.values()) desiredFkKeys.add([...fk.fields].sort().join(","));
+		for (const [constraintName, columns] of existingByName) {
+			const key = [...columns].sort().join(",");
+			if (!desiredFkKeys.has(key)) {
+				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP CONSTRAINT ${qi(constraintName)}`;
+				this._log(ddl);
+				await this._exec().exec(ddl);
+			}
+		}
+		const existingKeys = new Set([...existingByName.values()].map((cols) => cols.sort().join(",")));
+		for (const fk of this._table.foreignKeys.values()) {
+			const key = [...fk.fields].sort().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 ${refActionToSql(fk.onDelete)}`;
+				if (fk.onUpdate) ddl += ` ON UPDATE ${refActionToSql(fk.onUpdate)}`;
+				this._log(ddl);
+				await this._exec().exec(ddl);
+			}
+		}
+	}
+	async dropForeignKeys(fkFieldKeys) {
+		if (fkFieldKeys.length === 0) return;
+		const keySet = new Set(fkFieldKeys);
+		const existingByName = await this._getExistingFkConstraints();
+		for (const [constraintName, cols] of existingByName) {
+			const key = cols.sort().join(",");
+			if (keySet.has(key)) {
+				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP CONSTRAINT ${qi(constraintName)}`;
+				this._log(ddl);
+				await this._exec().exec(ddl);
+			}
+		}
+	}
+	/** Queries information_schema for existing FK constraints. */ async _getExistingFkConstraints() {
+		const rows = await this._exec().all(`SELECT kcu.constraint_name, kcu.column_name
+       FROM information_schema.table_constraints tc
+       JOIN information_schema.key_column_usage kcu
+         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+       WHERE tc.table_name = $1 AND tc.table_schema = COALESCE($2, 'public')
+         AND tc.constraint_type = 'FOREIGN KEY'`, [this._table.tableName, this._schema]);
+		const byName = new Map();
+		for (const row of rows) {
+			let cols = byName.get(row.constraint_name);
+			if (!cols) {
+				cols = [];
+				byName.set(row.constraint_name, cols);
+			}
+			cols.push(row.column_name);
+		}
+		return byName;
+	}
+	getSearchIndexes() {
+		const indexes = [];
+		for (const index of this._table.indexes.values()) if (index.type === "fulltext") indexes.push({
+			name: index.key,
+			description: `GIN tsvector index on ${index.fields.map((f) => f.name).join(", ")}`,
+			type: "text"
+		});
+		for (const [field, vec] of this._vectorFields) indexes.push({
+			name: vec.indexName,
+			description: `vector(${vec.dimensions}) on ${field}, ${vec.similarity}`,
+			type: "vector"
+		});
+		return indexes;
+	}
+	async search(text, query, indexName) {
+		if (!text.trim()) return [];
+		const combinedWhere = this._buildSearchWhere(text, query, indexName);
+		const { sql, params } = buildSelect$1(this.resolveTableName(), combinedWhere, query.controls);
+		this._log(sql, params);
+		return this._exec().all(sql, params);
+	}
+	async searchWithCount(text, query, indexName) {
+		if (!text.trim()) return {
+			data: [],
+			count: 0
+		};
+		const combinedWhere = this._buildSearchWhere(text, query, indexName);
+		const tableName = this.resolveTableName();
+		const selectPromise = (async () => {
+			const { sql, params } = buildSelect$1(tableName, combinedWhere, query.controls);
+			this._log(sql, params);
+			return this._exec().all(sql, params);
+		})();
+		const countPromise = (async () => {
+			const raw = {
+				sql: `SELECT COUNT(*) as cnt FROM ${quoteTableName(tableName)} WHERE ${combinedWhere.sql}`,
+				params: combinedWhere.params
+			};
+			const { sql, params } = finalizeParams(pgDialect, raw);
+			this._log(sql, params);
+			const row = await this._exec().get(sql, params);
+			return parseCount(row?.cnt);
+		})();
+		const [data, count] = await Promise.all([selectPromise, countPromise]);
+		return {
+			data,
+			count
+		};
+	}
+	_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 where = buildWhere(query.filter);
+		const tsqueryClause = `to_tsvector('english', ${tsvectorExpr}) @@ plainto_tsquery('english', ?)`;
+		return {
+			sql: where.sql === "1=1" ? tsqueryClause : `${where.sql} AND ${tsqueryClause}`,
+			params: [...where.params, text]
+		};
+	}
+	/** Builds the tsvector SQL expression for a fulltext index's fields. Must match between index DDL and queries. */ _buildTsvectorExpr(fields) {
+		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;
+		}
+		return undefined;
+	}
+	/**
+	* Detects pgvector support by attempting to enable the extension.
+	* Idempotent — safe to call multiple times.
+	*/ async _detectVectorSupport() {
+		if (this._supportsVector !== undefined) return this._supportsVector;
+		try {
+			await this._exec().exec("CREATE EXTENSION IF NOT EXISTS vector");
+			this._supportsVector = true;
+		} catch {
+			this._supportsVector = false;
+		}
+		return this._supportsVector;
+	}
+	isVectorSearchable() {
+		return this._supportsVector === true && this._vectorFields.size > 0;
+	}
+	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);
+		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);
+		this._log(sql, params);
+		this._log(countSql, countParams);
+		const [data, countRow] = await Promise.all([this._exec().all(sql, params), this._exec().get(countSql, countParams)]);
+		const count = parseCount(countRow?.cnt);
+		return {
+			data,
+			count
+		};
+	}
+	/** Resolves vector field and computes shared context for vector search SQL builders. */ _prepareVectorSearch(vector, query, indexName) {
+		let field;
+		let vec;
+		if (indexName) {
+			let found = false;
+			for (const [f, v] of this._vectorFields) if (v.indexName === indexName) {
+				field = f;
+				vec = v;
+				found = true;
+				break;
+			}
+			if (!found) throw new Error(`Vector index "${indexName}" not found`);
+		} else {
+			const first = this._vectorFields.entries().next();
+			if (first.done) throw new Error("No vector fields defined");
+			field = first.value[0];
+			vec = first.value[1];
+		}
+		const distanceOp = similarityToPgOp(vec.similarity);
+		const where = buildWhere(query.filter);
+		const controls = query.controls || {};
+		const threshold = this._resolveVectorThreshold(controls, vec.indexName);
+		return {
+			field,
+			vec,
+			distanceOp,
+			where,
+			controls,
+			threshold,
+			tableName: this.resolveTableName(),
+			vectorStr: vectorToString(vector)
+		};
+	}
+	_buildVectorSearchQuery(vector, query, indexName) {
+		const ctx = this._prepareVectorSearch(vector, query, indexName);
+		let inner = `SELECT *, (${qi(ctx.field)} ${ctx.distanceOp} $1::vector) AS _distance FROM ${quoteTableName(ctx.tableName)} WHERE ${offsetPlaceholders(finalizeParams(pgDialect, ctx.where), 1).sql}`;
+		const params = [ctx.vectorStr, ...ctx.where.params];
+		let sql = `SELECT * FROM (${inner}) _v`;
+		if (ctx.threshold !== undefined) {
+			sql += ` WHERE _distance <= $${params.length + 1}`;
+			params.push(thresholdToDistance(ctx.threshold, ctx.vec.similarity));
+		}
+		sql += ` ORDER BY _distance ASC`;
+		if (ctx.controls.$skip) {
+			sql += ` LIMIT $${params.length + 1} OFFSET $${params.length + 2}`;
+			params.push(ctx.controls.$limit || 1e3, ctx.controls.$skip);
+		} else {
+			sql += ` LIMIT $${params.length + 1}`;
+			params.push(ctx.controls.$limit || 20);
+		}
+		return {
+			sql,
+			params
+		};
+	}
+	_buildVectorSearchCountQuery(vector, query, indexName) {
+		const ctx = this._prepareVectorSearch(vector, query, indexName);
+		let inner = `SELECT (${qi(ctx.field)} ${ctx.distanceOp} $1::vector) AS _distance FROM ${quoteTableName(ctx.tableName)} WHERE ${offsetPlaceholders(finalizeParams(pgDialect, ctx.where), 1).sql}`;
+		const params = [ctx.vectorStr, ...ctx.where.params];
+		let sql = `SELECT COUNT(*) AS cnt FROM (${inner}) _v`;
+		if (ctx.threshold !== undefined) {
+			sql += ` WHERE _distance <= $${params.length + 1}`;
+			params.push(thresholdToDistance(ctx.threshold, ctx.vec.similarity));
+		}
+		return {
+			sql,
+			params
+		};
+	}
+	/** Resolves threshold: query-time $threshold > schema-level @db.search.vector.threshold. */ _resolveVectorThreshold(controls, indexName) {
+		const queryThreshold = controls.$threshold;
+		if (queryThreshold !== undefined) return queryThreshold;
+		return this._vectorThresholds.get(indexName);
+	}
+	constructor(driver) {
+		super(), _define_property$1(this, "driver", void 0), _define_property$1(this, "supportsColumnModify", void 0), _define_property$1(this, "_incrementFields", void 0), _define_property$1(this, "_autoIncrementStart", void 0), _define_property$1(this, "_nocaseColumns", void 0), _define_property$1(this, "_citextProvisioned", void 0), _define_property$1(this, "_supportsVector", void 0), _define_property$1(this, "_vectorFields", void 0), _define_property$1(this, "_vectorThresholds", void 0), this.driver = driver, this.supportsColumnModify = true, this._incrementFields = new Set(), this._nocaseColumns = new Set(), this._citextProvisioned = false, this._vectorFields = new Map(), this._vectorThresholds = new Map();
+	}
+};
+_define_property$1(PostgresAdapter, "NATIVE_DEFAULT_FNS", new Set([
+	"now",
+	"uuid",
+	"increment"
+]));
+/**
+* Normalizes PostgreSQL information_schema data_type values
+* to match the format produced by `pgTypeFromField()`.
+*/ function normalizePgType(dataType, maxLength, numericPrecision, numericScale, udtName, formattedType) {
+	const dt = dataType.toLowerCase();
+	switch (dt) {
+		case "character varying": return maxLength ? `VARCHAR(${maxLength})` : "VARCHAR(255)";
+		case "character": return maxLength ? `CHAR(${maxLength})` : "CHAR(1)";
+		case "integer": return "INTEGER";
+		case "smallint": return "SMALLINT";
+		case "bigint": return "BIGINT";
+		case "double precision": return "DOUBLE PRECISION";
+		case "numeric": return numericPrecision != null && numericScale != null ? `NUMERIC(${numericPrecision},${numericScale})` : "NUMERIC";
+		case "boolean": return "BOOLEAN";
+		case "text": return "TEXT";
+		case "jsonb": return "JSONB";
+		case "json": return "JSON";
+		case "timestamp with time zone": return "TIMESTAMPTZ";
+		case "timestamp without time zone": return "TIMESTAMP";
+		case "uuid": return "UUID";
+		case "user-defined": {
+			if (udtName === "vector") return formattedType;
+			if (udtName === "citext") return "CITEXT";
+			return udtName?.toUpperCase() ?? "USER-DEFINED";
+		}
+		default: return dataType.toUpperCase();
+	}
+}
+/**
+* Normalizes PostgreSQL column_default values to match the format
+* produced by `serializeDefaultValue()`.
+*/ function normalizePgDefault(value, isIdentity) {
+	if (isIdentity === "YES") return "fn:increment";
+	if (value === null) return undefined;
+	let cleaned = value;
+	while (cleaned.startsWith("(") && cleaned.endsWith(")")) cleaned = cleaned.slice(1, -1);
+	const lower = cleaned.toLowerCase();
+	if (lower === "true") return "1";
+	if (lower === "false") return "0";
+	if (lower === "current_timestamp" || lower === "now()" || lower.startsWith("current_timestamp::") || lower.startsWith("now()::")) return "fn:now";
+	if (lower.includes("extract") && lower.includes("epoch") && lower.includes("now()")) return "fn:now";
+	if (lower === "gen_random_uuid()") return "fn:uuid";
+	if (lower.startsWith("nextval(")) return "fn:increment";
+	const castMatch = cleaned.match(/^'(.*)'::[\w\s]+$/);
+	if (castMatch) return castMatch[1].replace(/''/g, "'");
+	if (cleaned.startsWith("'") && cleaned.endsWith("'")) return cleaned.slice(1, -1).replace(/''/g, "'");
+	return cleaned;
+}
+/**
+* Converts a normalized similarity threshold (0-1) to a pgvector max distance.
+*
+* The threshold is a normalized score matching MongoDB Atlas semantics:
+*   cosine score = (1 + cosine_similarity) / 2, range [0, 1]
+* pgvector cosine distance = 1 - cosine_similarity, range [0, 2]
+*
+* Conversion: distance = 2 * (1 - score)
+*/ function thresholdToDistance(threshold, similarity) {
+	switch (similarity) {
+		case "euclidean": return threshold;
+		case "dotProduct": return -threshold;
+		default: return 2 * (1 - threshold);
+	}
+}
+/** Maps generic similarity metric to PostgreSQL distance operator. */ function similarityToPgOp(similarity) {
+	switch (similarity) {
+		case "euclidean": return "<->";
+		case "dotProduct": return "<#>";
+		default: return "<=>";
+	}
+}
+/** Maps generic similarity metric to pgvector index ops class. */ function similarityToPgOps(similarity) {
+	switch (similarity) {
+		case "euclidean": return "vector_l2_ops";
+		case "dotProduct": return "vector_ip_ops";
+		default: return "vector_cosine_ops";
+	}
+}
+/** Formats a number[] vector as pgvector input: '[1.0, 2.0, ...]'. */ function vectorToString(vector) {
+	return `[${vector.join(",")}]`;
+}
+
+//#endregion
+//#region packages/db-postgres/src/pg-driver.ts
+function _define_property(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+else obj[key] = value;
+	return obj;
+}
+/** pg rejects `undefined` in bind arrays — coerce to `null`. */ function sanitizeParams(params) {
+	if (!params) return [];
+	return params.map((v) => v === undefined ? null : v);
+}
+/** Parses TIMESTAMP/TIMESTAMPTZ to epoch milliseconds. */ function parseTimestamp(val) {
+	const ms = new Date(val).getTime();
+	return Number.isNaN(ms) ? val : ms;
+}
+/** Parses NUMERIC to number. */ function parseNumeric(val) {
+	const n = Number.parseFloat(val);
+	return Number.isNaN(n) ? val : n;
+}
+/** Parses INT8/BIGINT to number. Returns string if value exceeds safe integer range. */ function parseBigInt(val) {
+	const n = Number.parseInt(val, 10);
+	return Number.isNaN(n) || !Number.isSafeInteger(n) ? val : n;
+}
+/** OIDs for types we override. */ const TIMESTAMP_OID = 1114;
+const TIMESTAMPTZ_OID = 1184;
+const NUMERIC_OID = 1700;
+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)
+* - NUMERIC → number (not string)
+* - INT8/BIGINT → number (for JS-safe range)
+*/ function createCustomTypes(pgTypes) {
+	const overrides = new Map([
+		[TIMESTAMP_OID, parseTimestamp],
+		[TIMESTAMPTZ_OID, parseTimestamp],
+		[NUMERIC_OID, parseNumeric],
+		[INT8_OID, parseBigInt]
+	]);
+	return { getTypeParser(oid, format) {
+		const custom = overrides.get(oid);
+		if (custom) return custom;
+		return pgTypes.getTypeParser(oid, format);
+	} };
+}
+var PgDriver = class {
+	getPool() {
+		return this.pool || this.poolInit;
+	}
+	async run(sql, params) {
+		const pool = await this.getPool();
+		const result = await pool.query(sql, sanitizeParams(params));
+		return {
+			affectedRows: result.rowCount ?? 0,
+			rows: result.rows ?? []
+		};
+	}
+	async all(sql, params) {
+		const pool = await this.getPool();
+		const result = await pool.query(sql, sanitizeParams(params));
+		return result.rows;
+	}
+	async get(sql, params) {
+		const pool = await this.getPool();
+		const result = await pool.query(sql, sanitizeParams(params));
+		return result.rows[0] ?? null;
+	}
+	async exec(sql) {
+		const pool = await this.getPool();
+		await pool.query(sql);
+	}
+	async getConnection() {
+		const pool = await this.getPool();
+		const client = await pool.connect();
+		return {
+			async run(sql, params) {
+				const result = await client.query(sql, sanitizeParams(params));
+				return {
+					affectedRows: result.rowCount ?? 0,
+					rows: result.rows ?? []
+				};
+			},
+			async all(sql, params) {
+				const result = await client.query(sql, sanitizeParams(params));
+				return result.rows;
+			},
+			async get(sql, params) {
+				const result = await client.query(sql, sanitizeParams(params));
+				return result.rows[0] ?? null;
+			},
+			async exec(sql) {
+				await client.query(sql);
+			},
+			release() {
+				client.release();
+			}
+		};
+	}
+	async close() {
+		const pool = await this.getPool();
+		await pool.end();
+	}
+	constructor(poolOrConfig) {
+		_define_property(this, "pool", void 0);
+		_define_property(this, "poolInit", void 0);
+		if (typeof poolOrConfig === "object" && typeof poolOrConfig.query === "function") this.pool = poolOrConfig;
+else this.poolInit = import("pg").then((pg) => {
+			const Pool = pg.default?.Pool ?? pg.Pool;
+			const types = pg.default?.types ?? pg.types;
+			const customTypes = types ? createCustomTypes(types) : undefined;
+			if (typeof poolOrConfig === "string") this.pool = new Pool({
+				connectionString: poolOrConfig,
+				types: customTypes
+			});
+else this.pool = new Pool({
+				...poolOrConfig,
+				types: customTypes
+			});
+			return this.pool;
+		});
+	}
+};
+
+//#endregion
+//#region packages/db-postgres/src/plugin/annotations.ts
+const annotations = {
+	type: new AnnotationSpec({
+		description: "Overrides the native PostgreSQL column type.\n\n```atscript\n@db.pg.type \"CITEXT\"\nname: string\n```",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "type",
+			type: "string",
+			description: "Native PostgreSQL column type (e.g., \"CITEXT\", \"INET\", \"MACADDR\")."
+		}
+	}),
+	schema: new AnnotationSpec({
+		description: "Specifies the PostgreSQL schema for the table.\n\n**Default:** `\"public\"`\n\n```atscript\n@db.pg.schema \"analytics\"\nexport interface Events { ... }\n```",
+		nodeType: ["interface"],
+		multiple: false,
+		argument: {
+			name: "schema",
+			type: "string",
+			description: "PostgreSQL schema name (e.g., \"public\", \"analytics\")."
+		}
+	}),
+	collate: new AnnotationSpec({
+		description: "Specifies a native PostgreSQL collation (overrides portable `@db.column.collate`).\n\n```atscript\n@db.pg.collate \"tr-x-icu\"\nname: string\n```",
+		nodeType: ["interface", "prop"],
+		multiple: false,
+		argument: {
+			name: "collation",
+			type: "string",
+			description: "Native PostgreSQL collation name (e.g., \"tr-x-icu\", \"C\", \"und-x-icu\")."
+		}
+	})
+};
+
+//#endregion
+//#region packages/db-postgres/src/plugin/index.ts
+const PostgresPlugin = () => ({
+	name: "postgres",
+	config() {
+		return { annotations: { db: { pg: annotations } } };
+	}
+});
+
+//#endregion
+//#region packages/db-postgres/src/index.ts
+function createAdapter(uri, options) {
+	const driver = new PgDriver({
+		connectionString: uri,
+		...options
+	});
+	return new DbSpace(() => new PostgresAdapter(driver));
+}
+
+//#endregion
+export { PgDriver, PostgresAdapter, PostgresPlugin, buildWhere, createAdapter };