@atscript/db-postgres 0.1.160 → 0.1.162

package/dist/index.cjs

@@ -152,6 +152,7 @@ const pgDialect = {
 		return quoteTableName(name);
 	},
 	unlimitedLimit: "ALL",
+	stringLiteral: _atscript_db_sql_tools.sqlStringLiteral,
 	toValue: toPgValue,
 	toParam(value) {
 		if (value === void 0) return null;
@@ -310,8 +311,8 @@ function buildInsert(table, data) {
 function buildInsertMany(table, rows, columns) {
 	return (0, _atscript_db_sql_tools.buildInsertMany)(pgDialect, table, rows, columns);
 }
-function buildSelect(table, where, controls) {
-	return (0, _atscript_db_sql_tools.buildSelect)(pgDialect, table, where, controls);
+function buildSelect(table, where, controls, lock) {
+	return (0, _atscript_db_sql_tools.buildSelect)(pgDialect, table, where, controls, lock);
 }
 function buildUpdate(table, data, where, limit, ops, versionColumn, expectedVersion) {
 	return (0, _atscript_db_sql_tools.buildUpdate)(pgDialect, table, data, where, limit, ops, versionColumn, expectedVersion);
@@ -613,6 +614,8 @@ function truncateBytes(s, bytes) {
 	while (byteLength(out) > bytes) out = out.slice(0, -1);
 	return out;
 }
+/** Name prefix of the pgvector HNSW indexes (managed outside the model's `indexes`). */
+const PG_VECTOR_INDEX_PREFIX = "atscript__vec_";
 /**
 * The name PostgreSQL generates for an unnamed constraint (`makeObjectName`):
 * `<table>_<columns joined by _>_<label>`, with the table and column parts
@@ -708,11 +711,12 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	_txConnection() {
 		return this._getTransactionState();
 	}
-	async _beginTransaction() {
+	async _beginTransaction(opts) {
 		const conn = await this.driver.getConnection();
 		try {
-			await conn.exec("BEGIN");
-			this._log("BEGIN");
+			const sql = opts?.isolation ? `BEGIN ISOLATION LEVEL ${opts.isolation.toUpperCase()}` : "BEGIN";
+			await conn.exec(sql);
+			this._log(sql);
 			return conn;
 		} catch (err) {
 			conn.release();
@@ -819,6 +823,18 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 	supportsNullsPlacement() {
 		return true;
 	}
+	/**
+	* Locking reads: `SELECT … FOR UPDATE` / `FOR SHARE` [`NOWAIT` /
+	* `SKIP LOCKED`]. Under REPEATABLE READ / SERIALIZABLE, locking a row that
+	* changed since the snapshot fails with `SERIALIZATION_FAILURE`. @since 0.1.162
+	*/
+	supportsReadLocks() {
+		return true;
+	}
+	/** Every level, via `BEGIN ISOLATION LEVEL …`. @since 0.1.162 */
+	isolationLevels() {
+		return _atscript_db.ALL_ISOLATION_LEVELS;
+	}
 	/** Computed view columns and first-row joins. */
 	viewCapabilities() {
 		return _atscript_db.ALL_VIEW_CAPABILITIES;
@@ -1086,7 +1102,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 			if (clauses.length === 0) continue;
 			const sql = `SELECT ${selectCols} FROM ${quoteTableName(this.resolveTableName())} WHERE ${clauses.join(" OR ")} ORDER BY ${order} FOR UPDATE`;
 			this._log(sql, params);
-			const found = await this._wrapConstraintError(() => this._exec().all(sql, params));
+			const found = await this._exec().all(sql, params).catch((error) => this._mapConstraintError(error));
 			for (const doc of found) keySets.forEach((fields, k) => {
 				const tuple = (0, _atscript_db.uniqueKeyTuple)(doc, fields);
 				if (tuple !== void 0) lockedTuples[k].add(tuple);
@@ -1128,15 +1144,15 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 			...query.controls,
 			$limit: 1
 		};
-		const { sql, params } = buildSelect(this.resolveTableName(), where, controls);
+		const { sql, params } = buildSelect(this.resolveTableName(), where, controls, query.lock);
 		this._log(sql, params);
-		return this._exec().get(sql, params);
+		return this._exec().get(sql, params).catch((error) => this._mapConstraintError(error));
 	}
 	async findMany(query) {
 		const where = buildWhere(query.filter);
-		const { sql, params } = buildSelect(this.resolveTableName(), where, query.controls);
+		const { sql, params } = buildSelect(this.resolveTableName(), where, query.controls, query.lock);
 		this._log(sql, params);
-		return this._exec().all(sql, params);
+		return this._exec().all(sql, params).catch((error) => this._mapConstraintError(error));
 	}
 	/**
 	* `$skip` / `$limit` per partition in one statement: a `ROW_NUMBER()`
@@ -1241,8 +1257,21 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 			modifiedCount: result.affectedRows
 		};
 	}
+	/**
+	* Bounded writes (since 0.1.162): PostgreSQL has no `UPDATE/DELETE … LIMIT`,
+	* so the statement is re-keyed on the primary key through an ordered,
+	* limited subquery — the `deleteOne` / `updateOne` pattern with `n` rows.
+	*/
+	supportsWriteLimit() {
+		return true;
+	}
+	/** `where` narrowed to a bounded write's rows, or `where` itself when unbounded. */
+	_boundedWhere(where, bound) {
+		if (!bound) return where;
+		return (0, _atscript_db_sql_tools.writeLimitWhere)(pgDialect, quoteTableName(this.resolveTableName()), this._pk().cols.map((c) => qi(c)), where, bound);
+	}
 	async updateMany(filter, data, ops, opts) {
-		const where = buildWhere(filter);
+		const where = this._boundedWhere(buildWhere(filter), opts?.limit);
 		const versionColumn = this._versionColumnFor(opts);
 		const { sql, params } = buildUpdate(this.resolveTableName(), data, where, void 0, ops, versionColumn);
 		this._log(sql, params);
@@ -1253,8 +1282,8 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		};
 	}
 	async replaceOne(filter, data, expectedVersion) {
-		const full = (0, _atscript_db_sql_tools.fillReplacePayload)(data, this._replaceColumns(), this._table.versionColumnPhysical);
-		return this.updateOne(filter, full, void 0, expectedVersion);
+		const full = (0, _atscript_db_sql_tools.fillReplacePayload)(data, this._replaceColumns(), this._table.versionColumnPhysical, this._table.onUpdateIncPhysical);
+		return this.updateOne(filter, full, this._onUpdateIncOps(), expectedVersion);
 	}
 	/** The columns a full replace assigns (`replaceColumnsFor`), built once per table. */
 	_replaceColumns() {
@@ -1267,7 +1296,7 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		return memo.cols;
 	}
 	async replaceMany(filter, data) {
-		return this.updateMany(filter, data);
+		return this.updateMany(filter, data, this._onUpdateIncOps());
 	}
 	async deleteOne(filter) {
 		const where = buildWhere(filter);
@@ -1280,8 +1309,8 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		this._log(sql, params);
 		return { deletedCount: (await this._wrapConstraintError(() => this._exec().run(sql, params))).affectedRows };
 	}
-	async deleteMany(filter) {
-		return this._deleteWhere(buildWhere(filter));
+	async deleteMany(filter, opts) {
+		return this._deleteWhere(this._boundedWhere(buildWhere(filter), opts?.limit));
 	}
 	async _deleteWhere(where) {
 		const { sql, params } = buildDelete(this.resolveTableName(), where);
@@ -1773,13 +1802,23 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 		if (field.isGeoPoint) return this._supportsGeo ? "geography(Point,4326)" : pgTypeFromField(field);
 		return pgTypeFromField(field);
 	}
-	async syncIndexes() {
+	async _syncIndexes(dryRun) {
 		const tableName = this._table.tableName;
 		const schema = this._schema;
 		await this.prepareTypeMapper();
-		await this.syncIndexesWithDiff({
+		const dropIndex = async (name) => {
+			const sql = `DROP INDEX IF EXISTS ${schema ? `${qi(schema)}.` : ""}${qi(name)}`;
+			this._log(sql);
+			await this._exec().exec(sql);
+		};
+		/** Every index name on the table (read by `listExisting`) — the vector pass checks it. */
+		let liveNames = /* @__PURE__ */ new Set();
+		const changes = await this.syncIndexesWithDiff({
+			dryRun,
+			isUnmanaged: (name) => name.startsWith(PG_VECTOR_INDEX_PREFIX),
+			skipIndex: (index) => index.type === "geo" && !this._supportsGeo ? `[postgres] geo index "${index.name}" declared but PostGIS is not available — skipped` : void 0,
 			listExisting: async () => {
-				return (await this._exec().all(`SELECT i.relname AS name,
+				const rows = await this._exec().all(`SELECT i.relname AS name,
                   (SELECT array_agg(a.attname::text ORDER BY k.ord)
                    FROM unnest(x.indkey) WITH ORDINALITY AS k(attnum, ord)
                    JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum
@@ -1788,7 +1827,9 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
            JOIN pg_class t ON t.oid = x.indrelid
            JOIN pg_class i ON i.oid = x.indexrelid
            JOIN pg_namespace n ON n.oid = t.relnamespace
-           WHERE t.relname = $1 AND n.nspname = COALESCE($2, current_schema())`, [tableName, schema])).map((r) => ({
+           WHERE t.relname = $1 AND n.nspname = COALESCE($2, current_schema())`, [tableName, schema]);
+				liveNames = new Set(rows.map((r) => r.name));
+				return rows.map((r) => ({
 					name: r.name,
 					columns: r.columns ?? void 0
 				}));
@@ -1804,10 +1845,6 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 					return;
 				}
 				if (index.type === "geo") {
-					if (!this._supportsGeo) {
-						this.logger.warn(`[postgres] geo index "${index.name}" declared but PostGIS is not available — skipped`);
-						return;
-					}
 					const sql = `CREATE INDEX IF NOT EXISTS ${qi(index.key)} ON ${quoteTableName(this.resolveTableName())} USING gist (${qi(index.fields[0].name)})`;
 					this._log(sql);
 					await this._exec().exec(sql);
@@ -1819,54 +1856,57 @@ var PostgresAdapter = class PostgresAdapter extends _atscript_db.BaseDbAdapter {
 				this._log(sql);
 				await this._exec().exec(sql);
 			},
-			dropIndex: async (name) => {
-				const sql = `DROP INDEX IF EXISTS ${schema ? `${qi(schema)}.` : ""}${qi(name)}`;
-				this._log(sql);
-				await this._exec().exec(sql);
-			}
+			dropIndex
 		});
+		const desiredVector = new Set(this._supportsVector ? [...this._vectorFields.values()].map((v) => `${PG_VECTOR_INDEX_PREFIX}${v.indexName}`) : []);
+		const vector = (0, _atscript_db.createChangeRecorder)(dryRun);
+		for (const name of liveNames) if (name.startsWith(PG_VECTOR_INDEX_PREFIX) && !desiredVector.has(name)) await vector.apply({
+			name,
+			action: "drop"
+		}, name, () => dropIndex(name));
 		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);
+			const indexName = `${PG_VECTOR_INDEX_PREFIX}${vec.indexName}`;
+			if (liveNames.has(indexName)) continue;
+			await vector.apply({
+				name: indexName,
+				action: "add"
+			}, indexName, async () => {
+				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);
+			});
 		}
+		return [...changes, ...vector.changes];
 	}
 	async syncForeignKeys() {
-		const existingByName = await this._getExistingFkConstraints();
-		const desiredFkKeys = /* @__PURE__ */ new Set();
-		for (const fk of this._table.foreignKeys.values()) desiredFkKeys.add([...(0, _atscript_db.fkColumns)(fk).fields].toSorted().join(","));
-		for (const [constraintName, columns] of existingByName) {
-			const key = [...columns].toSorted().join(",");
-			if (!desiredFkKeys.has(key)) {
-				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.toSorted().join(",")));
-		for (const fk of this._table.foreignKeys.values()) {
-			const key = [...(0, _atscript_db.fkColumns)(fk).fields].toSorted().join(",");
-			if (!existingKeys.has(key)) {
+		return this._syncForeignKeys(false);
+	}
+	/** The FK changes {@link syncForeignKeys} would make — no DDL. */
+	async planForeignKeys() {
+		return this._syncForeignKeys(true);
+	}
+	_syncForeignKeys(dryRun) {
+		return this.syncForeignKeysWithDiff({
+			dryRun,
+			listExisting: () => this._getExistingFkConstraints(),
+			dropConstraint: (name) => this._dropFkConstraint(name),
+			addConstraint: async (fk) => {
 				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} ADD ${(0, _atscript_db_sql_tools.foreignKeySql)(qi, fk)}`;
 				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.toSorted().join(",");
-			if (keySet.has(key)) {
-				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP CONSTRAINT ${qi(constraintName)}`;
-				this._log(ddl);
-				await this._exec().exec(ddl);
-			}
-		}
+		for (const [constraintName, cols] of await this._getExistingFkConstraints()) if (keySet.has((0, _atscript_db.fkKey)(cols))) await this._dropFkConstraint(constraintName);
+	}
+	async _dropFkConstraint(name) {
+		const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP CONSTRAINT ${qi(name)}`;
+		this._log(ddl);
+		await this._exec().exec(ddl);
 	}
 	/** Queries information_schema for existing FK constraints. */
 	async _getExistingFkConstraints() {
@@ -2304,10 +2344,8 @@ function normalizePgDefault(value, isIdentity) {
 	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;
+	const castMatch = cleaned.match(/^('.*')::[\w\s]+$/);
+	return (0, _atscript_db_sql_tools.unquoteSqlStringLiteral)(castMatch ? castMatch[1] : cleaned) ?? cleaned;
 }
 /**
 * Converts a normalized similarity threshold (0-1) to a pgvector max distance.

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TGenericLogger, TJsonCopyTarget, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteManyOptions, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbIsolationLevel, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TForeignKeyChange, TGenericLogger, TIndexChange, TJsonCopyTarget, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTransactionOptions, TValueFormatterPair, TViewCapability } from "@atscript/db";
 import { TMetadataMap } from "@atscript/typescript/utils";
 import { TFilterVisitorOptions, TSqlFragment } from "@atscript/db-sql-tools";
 
@@ -134,7 +134,7 @@ declare class PostgresAdapter extends BaseDbAdapter {
   protected _transactionOwner(): unknown;
   /** The dedicated connection of this pool's open transaction, if any. */
   private _txConnection;
-  protected _beginTransaction(): Promise<TPgConnection>;
+  protected _beginTransaction(opts?: TTransactionOptions): Promise<TPgConnection>;
   protected _commitTransaction(state: unknown): Promise<void>;
   protected _rollbackTransaction(state: unknown): Promise<void>;
   /**
@@ -178,6 +178,14 @@ declare class PostgresAdapter extends BaseDbAdapter {
   supportsAggregateExpressions(): boolean;
   /** `$nulls` / `@db.sort.nulls` NULL placement — `NULLS FIRST` / `NULLS LAST`. */
   supportsNullsPlacement(): boolean;
+  /**
+   * Locking reads: `SELECT … FOR UPDATE` / `FOR SHARE` [`NOWAIT` /
+   * `SKIP LOCKED`]. Under REPEATABLE READ / SERIALIZABLE, locking a row that
+   * changed since the snapshot fails with `SERIALIZATION_FAILURE`. @since 0.1.162
+   */
+  supportsReadLocks(): boolean;
+  /** Every level, via `BEGIN ISOLATION LEVEL …`. @since 0.1.162 */
+  isolationLevels(): ReadonlySet<TDbIsolationLevel>;
   /** Computed view columns and first-row joins. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
@@ -274,13 +282,21 @@ declare class PostgresAdapter extends BaseDbAdapter {
    */
   private _limitOnePredicate;
   updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
+  /**
+   * Bounded writes (since 0.1.162): PostgreSQL has no `UPDATE/DELETE … LIMIT`,
+   * so the statement is re-keyed on the primary key through an ordered,
+   * limited subquery — the `deleteOne` / `updateOne` pattern with `n` rows.
+   */
+  supportsWriteLimit(): boolean;
+  /** `where` narrowed to a bounded write's rows, or `where` itself when unbounded. */
+  private _boundedWhere;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
   replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;
   /** The columns a full replace assigns (`replaceColumnsFor`), built once per table. */
   private _replaceColumns;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
-  deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
+  deleteMany(filter: FilterExpr, opts?: TDbDeleteManyOptions): Promise<TDbDeleteResult>;
   private _deleteWhere;
   prepareTypeMapper(): Promise<void>;
   /**
@@ -356,9 +372,13 @@ declare class PostgresAdapter extends BaseDbAdapter {
   dropViewByName(viewName: string): Promise<void>;
   renameTable(oldName: string): Promise<void>;
   typeMapper(field: TDbFieldMeta): string;
-  syncIndexes(): Promise<void>;
-  syncForeignKeys(): Promise<void>;
+  protected _syncIndexes(dryRun: boolean): Promise<TIndexChange[]>;
+  syncForeignKeys(): Promise<TForeignKeyChange[]>;
+  /** The FK changes {@link syncForeignKeys} would make — no DDL. */
+  planForeignKeys(): Promise<TForeignKeyChange[]>;
+  private _syncForeignKeys;
   dropForeignKeys(fkFieldKeys: string[]): Promise<void>;
+  private _dropFkConstraint;
   /** Queries information_schema for existing FK constraints. */
   private _getExistingFkConstraints;
   getSearchIndexes(): TSearchIndexInfo[];

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TGenericLogger, TJsonCopyTarget, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteManyOptions, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbIsolationLevel, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TForeignKeyChange, TGenericLogger, TIndexChange, TJsonCopyTarget, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTransactionOptions, TValueFormatterPair, TViewCapability } from "@atscript/db";
 import { TFilterVisitorOptions, TSqlFragment } from "@atscript/db-sql-tools";
 import { TMetadataMap } from "@atscript/typescript/utils";
 
@@ -134,7 +134,7 @@ declare class PostgresAdapter extends BaseDbAdapter {
   protected _transactionOwner(): unknown;
   /** The dedicated connection of this pool's open transaction, if any. */
   private _txConnection;
-  protected _beginTransaction(): Promise<TPgConnection>;
+  protected _beginTransaction(opts?: TTransactionOptions): Promise<TPgConnection>;
   protected _commitTransaction(state: unknown): Promise<void>;
   protected _rollbackTransaction(state: unknown): Promise<void>;
   /**
@@ -178,6 +178,14 @@ declare class PostgresAdapter extends BaseDbAdapter {
   supportsAggregateExpressions(): boolean;
   /** `$nulls` / `@db.sort.nulls` NULL placement — `NULLS FIRST` / `NULLS LAST`. */
   supportsNullsPlacement(): boolean;
+  /**
+   * Locking reads: `SELECT … FOR UPDATE` / `FOR SHARE` [`NOWAIT` /
+   * `SKIP LOCKED`]. Under REPEATABLE READ / SERIALIZABLE, locking a row that
+   * changed since the snapshot fails with `SERIALIZATION_FAILURE`. @since 0.1.162
+   */
+  supportsReadLocks(): boolean;
+  /** Every level, via `BEGIN ISOLATION LEVEL …`. @since 0.1.162 */
+  isolationLevels(): ReadonlySet<TDbIsolationLevel>;
   /** Computed view columns and first-row joins. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
@@ -274,13 +282,21 @@ declare class PostgresAdapter extends BaseDbAdapter {
    */
   private _limitOnePredicate;
   updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
+  /**
+   * Bounded writes (since 0.1.162): PostgreSQL has no `UPDATE/DELETE … LIMIT`,
+   * so the statement is re-keyed on the primary key through an ordered,
+   * limited subquery — the `deleteOne` / `updateOne` pattern with `n` rows.
+   */
+  supportsWriteLimit(): boolean;
+  /** `where` narrowed to a bounded write's rows, or `where` itself when unbounded. */
+  private _boundedWhere;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
   replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;
   /** The columns a full replace assigns (`replaceColumnsFor`), built once per table. */
   private _replaceColumns;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
-  deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
+  deleteMany(filter: FilterExpr, opts?: TDbDeleteManyOptions): Promise<TDbDeleteResult>;
   private _deleteWhere;
   prepareTypeMapper(): Promise<void>;
   /**
@@ -356,9 +372,13 @@ declare class PostgresAdapter extends BaseDbAdapter {
   dropViewByName(viewName: string): Promise<void>;
   renameTable(oldName: string): Promise<void>;
   typeMapper(field: TDbFieldMeta): string;
-  syncIndexes(): Promise<void>;
-  syncForeignKeys(): Promise<void>;
+  protected _syncIndexes(dryRun: boolean): Promise<TIndexChange[]>;
+  syncForeignKeys(): Promise<TForeignKeyChange[]>;
+  /** The FK changes {@link syncForeignKeys} would make — no DDL. */
+  planForeignKeys(): Promise<TForeignKeyChange[]>;
+  private _syncForeignKeys;
   dropForeignKeys(fkFieldKeys: string[]): Promise<void>;
+  private _dropFkConstraint;
   /** Queries information_schema for existing FK constraints. */
   private _getExistingFkConstraints;
   getSearchIndexes(): TSearchIndexInfo[];

package/dist/index.mjs

@@ -1,6 +1,6 @@
-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 { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_ISOLATION_LEVELS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, bucketTimeZoneUnavailable, createChangeRecorder, defaultFulltextIndex, describeFulltext, fkKey, 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, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, 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 { SEARCH_SOURCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, 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, unquoteSqlStringLiteral, vectorDistanceSource, writeLimitWhere } from "@atscript/db-sql-tools";
 import { BUCKET_MAX_INSTANT, BUCKET_MIN_INSTANT } from "@uniqu/core";
 //#region src/insert-ignore.ts
 /**
@@ -151,6 +151,7 @@ const pgDialect = {
 		return quoteTableName(name);
 	},
 	unlimitedLimit: "ALL",
+	stringLiteral: sqlStringLiteral,
 	toValue: toPgValue,
 	toParam(value) {
 		if (value === void 0) return null;
@@ -309,8 +310,8 @@ function buildInsert$1(table, data) {
 function buildInsertMany$1(table, rows, columns) {
 	return buildInsertMany(pgDialect, table, rows, columns);
 }
-function buildSelect$1(table, where, controls) {
-	return buildSelect(pgDialect, table, where, controls);
+function buildSelect$1(table, where, controls, lock) {
+	return buildSelect(pgDialect, table, where, controls, lock);
 }
 function buildUpdate$1(table, data, where, limit, ops, versionColumn, expectedVersion) {
 	return buildUpdate(pgDialect, table, data, where, limit, ops, versionColumn, expectedVersion);
@@ -612,6 +613,8 @@ function truncateBytes(s, bytes) {
 	while (byteLength(out) > bytes) out = out.slice(0, -1);
 	return out;
 }
+/** Name prefix of the pgvector HNSW indexes (managed outside the model's `indexes`). */
+const PG_VECTOR_INDEX_PREFIX = "atscript__vec_";
 /**
 * The name PostgreSQL generates for an unnamed constraint (`makeObjectName`):
 * `<table>_<columns joined by _>_<label>`, with the table and column parts
@@ -707,11 +710,12 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	_txConnection() {
 		return this._getTransactionState();
 	}
-	async _beginTransaction() {
+	async _beginTransaction(opts) {
 		const conn = await this.driver.getConnection();
 		try {
-			await conn.exec("BEGIN");
-			this._log("BEGIN");
+			const sql = opts?.isolation ? `BEGIN ISOLATION LEVEL ${opts.isolation.toUpperCase()}` : "BEGIN";
+			await conn.exec(sql);
+			this._log(sql);
 			return conn;
 		} catch (err) {
 			conn.release();
@@ -818,6 +822,18 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 	supportsNullsPlacement() {
 		return true;
 	}
+	/**
+	* Locking reads: `SELECT … FOR UPDATE` / `FOR SHARE` [`NOWAIT` /
+	* `SKIP LOCKED`]. Under REPEATABLE READ / SERIALIZABLE, locking a row that
+	* changed since the snapshot fails with `SERIALIZATION_FAILURE`. @since 0.1.162
+	*/
+	supportsReadLocks() {
+		return true;
+	}
+	/** Every level, via `BEGIN ISOLATION LEVEL …`. @since 0.1.162 */
+	isolationLevels() {
+		return ALL_ISOLATION_LEVELS;
+	}
 	/** Computed view columns and first-row joins. */
 	viewCapabilities() {
 		return ALL_VIEW_CAPABILITIES;
@@ -1085,7 +1101,7 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 			if (clauses.length === 0) continue;
 			const sql = `SELECT ${selectCols} FROM ${quoteTableName(this.resolveTableName())} WHERE ${clauses.join(" OR ")} ORDER BY ${order} FOR UPDATE`;
 			this._log(sql, params);
-			const found = await this._wrapConstraintError(() => this._exec().all(sql, params));
+			const found = await this._exec().all(sql, params).catch((error) => this._mapConstraintError(error));
 			for (const doc of found) keySets.forEach((fields, k) => {
 				const tuple = uniqueKeyTuple(doc, fields);
 				if (tuple !== void 0) lockedTuples[k].add(tuple);
@@ -1127,15 +1143,15 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 			...query.controls,
 			$limit: 1
 		};
-		const { sql, params } = buildSelect$1(this.resolveTableName(), where, controls);
+		const { sql, params } = buildSelect$1(this.resolveTableName(), where, controls, query.lock);
 		this._log(sql, params);
-		return this._exec().get(sql, params);
+		return this._exec().get(sql, params).catch((error) => this._mapConstraintError(error));
 	}
 	async findMany(query) {
 		const where = buildWhere(query.filter);
-		const { sql, params } = buildSelect$1(this.resolveTableName(), where, query.controls);
+		const { sql, params } = buildSelect$1(this.resolveTableName(), where, query.controls, query.lock);
 		this._log(sql, params);
-		return this._exec().all(sql, params);
+		return this._exec().all(sql, params).catch((error) => this._mapConstraintError(error));
 	}
 	/**
 	* `$skip` / `$limit` per partition in one statement: a `ROW_NUMBER()`
@@ -1240,8 +1256,21 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 			modifiedCount: result.affectedRows
 		};
 	}
+	/**
+	* Bounded writes (since 0.1.162): PostgreSQL has no `UPDATE/DELETE … LIMIT`,
+	* so the statement is re-keyed on the primary key through an ordered,
+	* limited subquery — the `deleteOne` / `updateOne` pattern with `n` rows.
+	*/
+	supportsWriteLimit() {
+		return true;
+	}
+	/** `where` narrowed to a bounded write's rows, or `where` itself when unbounded. */
+	_boundedWhere(where, bound) {
+		if (!bound) return where;
+		return writeLimitWhere(pgDialect, quoteTableName(this.resolveTableName()), this._pk().cols.map((c) => qi(c)), where, bound);
+	}
 	async updateMany(filter, data, ops, opts) {
-		const where = buildWhere(filter);
+		const where = this._boundedWhere(buildWhere(filter), opts?.limit);
 		const versionColumn = this._versionColumnFor(opts);
 		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, void 0, ops, versionColumn);
 		this._log(sql, params);
@@ -1252,8 +1281,8 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		};
 	}
 	async replaceOne(filter, data, expectedVersion) {
-		const full = fillReplacePayload(data, this._replaceColumns(), this._table.versionColumnPhysical);
-		return this.updateOne(filter, full, void 0, expectedVersion);
+		const full = fillReplacePayload(data, this._replaceColumns(), this._table.versionColumnPhysical, this._table.onUpdateIncPhysical);
+		return this.updateOne(filter, full, this._onUpdateIncOps(), expectedVersion);
 	}
 	/** The columns a full replace assigns (`replaceColumnsFor`), built once per table. */
 	_replaceColumns() {
@@ -1266,7 +1295,7 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		return memo.cols;
 	}
 	async replaceMany(filter, data) {
-		return this.updateMany(filter, data);
+		return this.updateMany(filter, data, this._onUpdateIncOps());
 	}
 	async deleteOne(filter) {
 		const where = buildWhere(filter);
@@ -1279,8 +1308,8 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		this._log(sql, params);
 		return { deletedCount: (await this._wrapConstraintError(() => this._exec().run(sql, params))).affectedRows };
 	}
-	async deleteMany(filter) {
-		return this._deleteWhere(buildWhere(filter));
+	async deleteMany(filter, opts) {
+		return this._deleteWhere(this._boundedWhere(buildWhere(filter), opts?.limit));
 	}
 	async _deleteWhere(where) {
 		const { sql, params } = buildDelete$1(this.resolveTableName(), where);
@@ -1772,13 +1801,23 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 		if (field.isGeoPoint) return this._supportsGeo ? "geography(Point,4326)" : pgTypeFromField(field);
 		return pgTypeFromField(field);
 	}
-	async syncIndexes() {
+	async _syncIndexes(dryRun) {
 		const tableName = this._table.tableName;
 		const schema = this._schema;
 		await this.prepareTypeMapper();
-		await this.syncIndexesWithDiff({
+		const dropIndex = async (name) => {
+			const sql = `DROP INDEX IF EXISTS ${schema ? `${qi(schema)}.` : ""}${qi(name)}`;
+			this._log(sql);
+			await this._exec().exec(sql);
+		};
+		/** Every index name on the table (read by `listExisting`) — the vector pass checks it. */
+		let liveNames = /* @__PURE__ */ new Set();
+		const changes = await this.syncIndexesWithDiff({
+			dryRun,
+			isUnmanaged: (name) => name.startsWith(PG_VECTOR_INDEX_PREFIX),
+			skipIndex: (index) => index.type === "geo" && !this._supportsGeo ? `[postgres] geo index "${index.name}" declared but PostGIS is not available — skipped` : void 0,
 			listExisting: async () => {
-				return (await this._exec().all(`SELECT i.relname AS name,
+				const rows = await this._exec().all(`SELECT i.relname AS name,
                   (SELECT array_agg(a.attname::text ORDER BY k.ord)
                    FROM unnest(x.indkey) WITH ORDINALITY AS k(attnum, ord)
                    JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum
@@ -1787,7 +1826,9 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
            JOIN pg_class t ON t.oid = x.indrelid
            JOIN pg_class i ON i.oid = x.indexrelid
            JOIN pg_namespace n ON n.oid = t.relnamespace
-           WHERE t.relname = $1 AND n.nspname = COALESCE($2, current_schema())`, [tableName, schema])).map((r) => ({
+           WHERE t.relname = $1 AND n.nspname = COALESCE($2, current_schema())`, [tableName, schema]);
+				liveNames = new Set(rows.map((r) => r.name));
+				return rows.map((r) => ({
 					name: r.name,
 					columns: r.columns ?? void 0
 				}));
@@ -1803,10 +1844,6 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 					return;
 				}
 				if (index.type === "geo") {
-					if (!this._supportsGeo) {
-						this.logger.warn(`[postgres] geo index "${index.name}" declared but PostGIS is not available — skipped`);
-						return;
-					}
 					const sql = `CREATE INDEX IF NOT EXISTS ${qi(index.key)} ON ${quoteTableName(this.resolveTableName())} USING gist (${qi(index.fields[0].name)})`;
 					this._log(sql);
 					await this._exec().exec(sql);
@@ -1818,54 +1855,57 @@ var PostgresAdapter = class PostgresAdapter extends BaseDbAdapter {
 				this._log(sql);
 				await this._exec().exec(sql);
 			},
-			dropIndex: async (name) => {
-				const sql = `DROP INDEX IF EXISTS ${schema ? `${qi(schema)}.` : ""}${qi(name)}`;
-				this._log(sql);
-				await this._exec().exec(sql);
-			}
+			dropIndex
 		});
+		const desiredVector = new Set(this._supportsVector ? [...this._vectorFields.values()].map((v) => `${PG_VECTOR_INDEX_PREFIX}${v.indexName}`) : []);
+		const vector = createChangeRecorder(dryRun);
+		for (const name of liveNames) if (name.startsWith(PG_VECTOR_INDEX_PREFIX) && !desiredVector.has(name)) await vector.apply({
+			name,
+			action: "drop"
+		}, name, () => dropIndex(name));
 		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);
+			const indexName = `${PG_VECTOR_INDEX_PREFIX}${vec.indexName}`;
+			if (liveNames.has(indexName)) continue;
+			await vector.apply({
+				name: indexName,
+				action: "add"
+			}, indexName, async () => {
+				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);
+			});
 		}
+		return [...changes, ...vector.changes];
 	}
 	async syncForeignKeys() {
-		const existingByName = await this._getExistingFkConstraints();
-		const desiredFkKeys = /* @__PURE__ */ new Set();
-		for (const fk of this._table.foreignKeys.values()) desiredFkKeys.add([...fkColumns(fk).fields].toSorted().join(","));
-		for (const [constraintName, columns] of existingByName) {
-			const key = [...columns].toSorted().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.toSorted().join(",")));
-		for (const fk of this._table.foreignKeys.values()) {
-			const key = [...fkColumns(fk).fields].toSorted().join(",");
-			if (!existingKeys.has(key)) {
+		return this._syncForeignKeys(false);
+	}
+	/** The FK changes {@link syncForeignKeys} would make — no DDL. */
+	async planForeignKeys() {
+		return this._syncForeignKeys(true);
+	}
+	_syncForeignKeys(dryRun) {
+		return this.syncForeignKeysWithDiff({
+			dryRun,
+			listExisting: () => this._getExistingFkConstraints(),
+			dropConstraint: (name) => this._dropFkConstraint(name),
+			addConstraint: async (fk) => {
 				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} ADD ${foreignKeySql(qi, fk)}`;
 				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.toSorted().join(",");
-			if (keySet.has(key)) {
-				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP CONSTRAINT ${qi(constraintName)}`;
-				this._log(ddl);
-				await this._exec().exec(ddl);
-			}
-		}
+		for (const [constraintName, cols] of await this._getExistingFkConstraints()) if (keySet.has(fkKey(cols))) await this._dropFkConstraint(constraintName);
+	}
+	async _dropFkConstraint(name) {
+		const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP CONSTRAINT ${qi(name)}`;
+		this._log(ddl);
+		await this._exec().exec(ddl);
 	}
 	/** Queries information_schema for existing FK constraints. */
 	async _getExistingFkConstraints() {
@@ -2303,10 +2343,8 @@ function normalizePgDefault(value, isIdentity) {
 	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;
+	const castMatch = cleaned.match(/^('.*')::[\w\s]+$/);
+	return unquoteSqlStringLiteral(castMatch ? castMatch[1] : cleaned) ?? cleaned;
 }
 /**
 * Converts a normalized similarity threshold (0-1) to a pgvector max distance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-postgres",
-  "version": "0.1.160",
+  "version": "0.1.162",
   "description": "PostgreSQL adapter for @atscript/db with pg (node-postgres) driver support.",
   "keywords": [
     "atscript",
@@ -43,20 +43,20 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.108",
-    "@atscript/typescript": "^0.1.108",
+    "@atscript/core": "^0.1.109",
+    "@atscript/typescript": "^0.1.109",
     "@types/pg": "^8.11.0",
     "@uniqu/core": "^0.1.15",
     "pg": "^8.13.0",
-    "unplugin-atscript": "^0.1.108"
+    "unplugin-atscript": "^0.1.109"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.108",
-    "@atscript/typescript": "^0.1.108",
+    "@atscript/core": "^0.1.109",
+    "@atscript/typescript": "^0.1.109",
     "@uniqu/core": "^0.1.15",
     "pg": ">=8.0.0",
-    "@atscript/db": "^0.1.160",
-    "@atscript/db-sql-tools": "^0.1.160"
+    "@atscript/db": "^0.1.162",
+    "@atscript/db-sql-tools": "^0.1.162"
   },
   "peerDependenciesMeta": {
     "pg": {