@atscript/db-sqlite 0.1.126 → 0.1.128

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
-import { AtscriptDbView, BaseDbAdapter, DbError, DbSpace } from "@atscript/db";
-import { buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildSelect, buildUpdate, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, geoWindowFromControls, parseRegexString, refActionToSql, renameGeoDistance, toSqlValue } from "@atscript/db-sql-tools";
+import { BaseDbAdapter, DbError, DbSpace } from "@atscript/db";
+import { buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildSelect, buildUpdate, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, geoWindowFromControls, parseRegexString, refActionToSql, renameGeoDistance, replaceColumnsFor, toSqlValue } from "@atscript/db-sql-tools";
+import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/better-sqlite3-driver.ts
 /**
 * {@link TSqliteDriver} implementation backed by `better-sqlite3`.
@@ -349,6 +350,212 @@ function buildPrefixedWhere(alias, filter) {
 	}, filter);
 }
 //#endregion
+//#region src/tx-gate.ts
+const DEFAULT_WARN_MS = 5e3;
+/** Async context that holds a gate exclusively via {@link SqliteTxGate.runExclusive}. */
+const exclusiveHolds = new AsyncLocalStorage();
+/**
+* One waiter for the gate, created once per `_stmt` / `acquire` call and kept
+* across wake-ups: the timeout and warn timers are armed ONCE with an absolute
+* deadline, so `transactionWaitTimeoutMs` bounds the waiter's TOTAL wait
+* however many transactions run ahead of it, and a re-queued waiter allocates
+* nothing new. `next()` resolves on the next release (or rejects once the
+* deadline passed); `dispose()` clears the timers.
+*/
+var GateWaiter = class {
+	_gate;
+	_resolve;
+	_reject;
+	_timeoutTimer;
+	_warnTimer;
+	_expired;
+	_startedAt = Date.now();
+	constructor(_gate, opts) {
+		this._gate = _gate;
+		const timeoutMs = opts?.transactionWaitTimeoutMs;
+		const warnMs = opts?.transactionWaitWarnMs ?? DEFAULT_WARN_MS;
+		const heldSince = this._gate.heldSince;
+		if (timeoutMs !== void 0 && timeoutMs >= 0) {
+			this._timeoutTimer = setTimeout(() => {
+				const waited = Date.now() - this._startedAt;
+				const heldFor = heldSince ? Date.now() - heldSince : 0;
+				this._expired = new DbError("TX_WAIT_TIMEOUT", [{
+					path: "",
+					message: `SQLite transaction gate: waited ${waited}ms for the connection (a transaction has been open for ${heldFor}ms) — transactionWaitTimeoutMs exceeded`
+				}]);
+				this._gate._dequeue(this);
+				const reject = this._reject;
+				this._resolve = void 0;
+				this._reject = void 0;
+				reject?.(this._expired);
+			}, timeoutMs);
+			this._timeoutTimer.unref?.();
+		}
+		if (warnMs > 0 && opts?.logger) {
+			const logger = opts.logger;
+			this._warnTimer = setTimeout(() => {
+				const waited = Date.now() - this._startedAt;
+				const since = heldSince ? new Date(heldSince).toISOString() : "unknown";
+				logger.warn(`[atscript-db-sqlite] a statement has been waiting ${waited}ms for an open transaction (held since ${since}); never await external I/O inside withTransaction on SQLite`);
+			}, warnMs);
+			this._warnTimer.unref?.();
+		}
+	}
+	/** Resolves on the NEXT release; rejects with `TX_WAIT_TIMEOUT` once the deadline passed. */
+	next() {
+		if (this._expired) return Promise.reject(this._expired);
+		return new Promise((resolve, reject) => {
+			this._resolve = resolve;
+			this._reject = reject;
+			this._gate._enqueue(this);
+		});
+	}
+	/** Called by the gate on release: wakes the pending `next()` (a no-op when none is pending). */
+	wake() {
+		const resolve = this._resolve;
+		this._resolve = void 0;
+		this._reject = void 0;
+		resolve?.();
+	}
+	dispose() {
+		if (this._timeoutTimer !== void 0) clearTimeout(this._timeoutTimer);
+		if (this._warnTimer !== void 0) clearTimeout(this._warnTimer);
+	}
+};
+/**
+* Logical FIFO mutex around the single synchronous SQLite connection.
+*
+* SQLite has one connection per driver, so two async contexts cannot each
+* own a transaction: a second `BEGIN` fails with "cannot start a transaction
+* within a transaction", and — worse — any statement from another context
+* that runs while a transaction is open executes INSIDE that transaction
+* (rolled back with it, reads its uncommitted rows). The gate serialises:
+*
+* - {@link acquire} / {@link release} — taken by `BEGIN`, released by
+*   `COMMIT` / `ROLLBACK`;
+* - {@link runWhenFree} — plain (non-transactional) statements check
+*   {@link held} synchronously right before executing and wait otherwise;
+* - {@link runExclusive} — hold the connection without a transaction (schema sync).
+*
+* Fairness: one FIFO waiter list for acquirers and statement waiters alike;
+* a release wakes every current waiter in registration order, each re-checks
+* synchronously and re-queues (ahead of any new arrival) if someone ahead took
+* the gate. A waiter is one object with timers armed once, whatever the
+* number of wake-ups. The fast path (nothing held) allocates nothing.
+*/
+var SqliteTxGate = class {
+	/** True while a transaction (or an exclusive hold) owns the connection. */
+	held = false;
+	/** `Date.now()` when the current holder took the gate (0 when free). */
+	heldSince = 0;
+	_waiters = [];
+	/** True when the current async context holds this gate via {@link runExclusive}. */
+	get heldByCurrentContext() {
+		return exclusiveHolds.getStore() === this;
+	}
+	/**
+	* Waits until the gate is free, then takes it synchronously (no `await`
+	* between the check and `held = true`). Pair with {@link release}.
+	*/
+	async acquire(opts) {
+		if (this.held) {
+			const waiter = new GateWaiter(this, opts);
+			try {
+				do
+					await waiter.next();
+				while (this.held);
+			} finally {
+				waiter.dispose();
+			}
+		}
+		this.held = true;
+		this.heldSince = Date.now();
+	}
+	/** Frees the gate and wakes every waiter (in registration order). */
+	release() {
+		this.held = false;
+		this.heldSince = 0;
+		const waiters = this._waiters;
+		this._waiters = [];
+		for (const w of waiters) w.wake();
+	}
+	/**
+	* Runs one synchronous statement once no transaction holds the connection
+	* (immediately when the gate is free). The `held` check and `fn` run in
+	* the same synchronous segment, so they cannot interleave with a `BEGIN`
+	* from another context.
+	*/
+	async runWhenFree(fn, opts) {
+		if (this.held) {
+			const waiter = new GateWaiter(this, opts);
+			try {
+				do
+					await waiter.next();
+				while (this.held);
+			} finally {
+				waiter.dispose();
+			}
+		}
+		return fn();
+	}
+	/**
+	* Holds the gate for the duration of `fn` WITHOUT opening a transaction
+	* (nested transactions inside `fn` still `BEGIN`/`COMMIT` on the held
+	* connection without re-acquiring). Re-entrant for the same async context.
+	*/
+	async runExclusive(fn, opts) {
+		if (this.heldByCurrentContext) return fn();
+		await this.acquire(opts);
+		try {
+			return await exclusiveHolds.run(this, fn);
+		} finally {
+			this.release();
+		}
+	}
+	/** @internal */
+	_enqueue(waiter) {
+		this._waiters.push(waiter);
+	}
+	/** @internal */
+	_dequeue(waiter) {
+		const idx = this._waiters.indexOf(waiter);
+		if (idx !== -1) this._waiters.splice(idx, 1);
+	}
+};
+/**
+* Transaction state returned by `SqliteAdapter._beginTransaction`: releases
+* the gate the transaction holds exactly once (a transaction opened inside an
+* exclusive hold owns nothing to release). Ownership across adapters is
+* decided by the core (`_transactionOwner()` = the driver), not here.
+*/
+var SqliteTxState = class {
+	_gate;
+	_holdsGate;
+	constructor(_gate, _holdsGate) {
+		this._gate = _gate;
+		this._holdsGate = _holdsGate;
+	}
+	release() {
+		if (!this._holdsGate) return;
+		this._holdsGate = false;
+		this._gate.release();
+	}
+};
+const gates = /* @__PURE__ */ new WeakMap();
+/**
+* Returns the gate for a driver instance (one gate per driver — every adapter
+* of a space shares its driver, so they share the gate; two driver wrappers
+* around one `Database` would get two gates: construct one driver per database).
+*/
+function getSqliteTxGate(driver) {
+	let gate = gates.get(driver);
+	if (!gate) {
+		gate = new SqliteTxGate();
+		gates.set(driver, gate);
+	}
+	return gate;
+}
+//#endregion
 //#region src/sqlite-adapter.ts
 /**
 * SQLite adapter for {@link AtscriptDbTable}.
@@ -380,9 +587,14 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 	_vectorThresholds = /* @__PURE__ */ new Map();
 	/** Partition filter fields per vector index (from @db.search.filter). Field paths. */
 	_vectorPartitionFields = /* @__PURE__ */ new Map();
-	constructor(driver) {
+	/** Per-driver transaction gate (shared by every adapter over this driver). */
+	_gate;
+	_txOptions;
+	constructor(driver, options) {
 		super();
 		this.driver = driver;
+		this._gate = getSqliteTxGate(driver);
+		this._txOptions = { ...options };
 		this.driver.exec("PRAGMA foreign_keys = ON");
 	}
 	onFieldScanned(field, _type, metadata) {
@@ -444,17 +656,74 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		if (!this._supportsVector && this._vectorFields.size > 0) this._log("[atscript-db-sqlite] sqlite-vec extension not available — vector fields will be stored as JSON TEXT (no similarity search).");
 		return this._supportsVector;
 	}
+	_waitOpts() {
+		return {
+			...this._txOptions,
+			logger: this.logger
+		};
+	}
+	/** Every adapter over this driver shares one transaction — and one gate (since 0.1.128). */
+	_transactionOwner() {
+		return this.driver;
+	}
+	/** Inside our own transaction, or holding the connection exclusively. */
+	_ownsConnection() {
+		return this._getTransactionState() !== void 0 || this._gate.heldByCurrentContext;
+	}
+	/**
+	* Runs one synchronous driver statement. Inside our own transaction (or an
+	* exclusive hold) it runs immediately; otherwise it waits until no
+	* transaction is open on the connection. The `held` check and the statement
+	* run in the same synchronous segment, so they cannot interleave with a
+	* `BEGIN` from another context.
+	*/
+	async _stmt(fn) {
+		if (!this._gate.held || this._ownsConnection()) return fn();
+		return this._gate.runWhenFree(fn, this._waitOpts());
+	}
+	/**
+	* Holds the connection for the duration of `fn` WITHOUT opening a
+	* transaction: no other context's statement or transaction can interleave.
+	* Meant for the schema entry points that `await` mid-body or toggle
+	* connection-level PRAGMAs (`ensureTable`, `recreateTable`, `dropColumns`,
+	* `dropTablesByName`, `syncIndexes`) — their DDL must not land inside a
+	* request's transaction (PRAGMA changes are no-ops inside one). Inside our
+	* own transaction `fn` runs directly; re-entrant for the same async
+	* context; nested `withTransaction` calls inside `fn` still BEGIN/COMMIT
+	* on the held connection.
+	*/
+	async _withExclusiveConnection(fn) {
+		if (this._getTransactionState() !== void 0) return fn();
+		return this._gate.runExclusive(fn, this._waitOpts());
+	}
 	async _beginTransaction() {
-		this._log("BEGIN");
-		this.driver.exec("BEGIN");
+		const holdsGate = !this._gate.heldByCurrentContext;
+		if (holdsGate) await this._gate.acquire(this._waitOpts());
+		const state = new SqliteTxState(this._gate, holdsGate);
+		try {
+			this._log("BEGIN IMMEDIATE");
+			this.driver.exec("BEGIN IMMEDIATE");
+		} catch (error) {
+			state.release();
+			throw error;
+		}
+		return state;
 	}
-	async _commitTransaction() {
-		this._log("COMMIT");
-		this.driver.exec("COMMIT");
+	async _commitTransaction(state) {
+		try {
+			this._log("COMMIT");
+			this.driver.exec("COMMIT");
+		} finally {
+			state.release();
+		}
 	}
-	async _rollbackTransaction() {
-		this._log("ROLLBACK");
-		this.driver.exec("ROLLBACK");
+	async _rollbackTransaction(state) {
+		try {
+			this._log("ROLLBACK");
+			this.driver.exec("ROLLBACK");
+		} finally {
+			state.release();
+		}
 	}
 	/** SQLite does not use schemas — override to always exclude schema. */
 	resolveTableName() {
@@ -496,7 +765,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 	async insertOne(data) {
 		const { sql, params } = buildInsert$1(this.resolveTableName(), data);
 		this._log(sql, params);
-		const result = this._wrapConstraintError(() => this.driver.run(sql, params));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
 		return { insertedId: this._resolveInsertedId(data, result.lastInsertRowid) };
 	}
 	async insertMany(data) {
@@ -505,7 +774,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 			for (const row of data) {
 				const { sql, params } = buildInsert$1(this.resolveTableName(), row);
 				this._log(sql, params);
-				const result = this._wrapConstraintError(() => this.driver.run(sql, params));
+				const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
 				ids.push(this._resolveInsertedId(row, result.lastInsertRowid));
 			}
 			return {
@@ -522,19 +791,19 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		};
 		const { sql, params } = buildSelect$1(this.resolveTableName(), where, controls);
 		this._log(sql, params);
-		return this.driver.get(sql, params);
+		return this._stmt(() => this.driver.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.driver.all(sql, params);
+		return this._stmt(() => this.driver.all(sql, params));
 	}
 	async count(query) {
 		const where = buildWhere(query.filter);
 		const sql = `SELECT COUNT(*) as cnt FROM "${esc(this.resolveTableName())}" WHERE ${where.sql}`;
 		this._log(sql, where.params);
-		return this.driver.get(sql, where.params)?.cnt ?? 0;
+		return (await this._stmt(() => this.driver.get(sql, where.params)))?.cnt ?? 0;
 	}
 	async aggregate(query) {
 		const where = buildWhere(query.filter);
@@ -542,11 +811,11 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		if (query.controls.$count) {
 			const { sql, params } = buildAggregateCount$1(tableName, where, query.controls);
 			this._log(sql, params);
-			return [{ count: this.driver.get(sql, params)?.count ?? 0 }];
+			return [{ count: (await this._stmt(() => this.driver.get(sql, params)))?.count ?? 0 }];
 		}
 		const { sql, params } = buildAggregateSelect$1(tableName, where, query.controls);
 		this._log(sql, params);
-		return this.driver.all(sql, params);
+		return this._stmt(() => this.driver.all(sql, params));
 	}
 	async updateOne(filter, data, ops, expectedVersion) {
 		const where = buildWhere(filter);
@@ -557,7 +826,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 			params: where.params
 		}, ops, versionColumn, expectedVersion);
 		this._log(sql, params);
-		const result = this._wrapConstraintError(() => this.driver.run(sql, params));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -568,7 +837,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		const versionColumn = this._table.versionColumn;
 		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, ops, versionColumn);
 		this._log(sql, params);
-		const result = this._wrapConstraintError(() => this.driver.run(sql, params));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -578,12 +847,12 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		const where = buildWhere(filter);
 		const tableName = this.resolveTableName();
 		const versionColumn = this._table.versionColumn;
-		const { sql, params } = buildUpdate$1(tableName, data, {
+		const { sql, params } = buildUpdate$1(tableName, fillReplacePayload(data, replaceColumnsFor(this._table.fieldDescriptors, this.nativeDefaultFns()), versionColumn), {
 			sql: `rowid = (SELECT rowid FROM "${esc(tableName)}" WHERE ${where.sql} LIMIT 1)`,
 			params: where.params
 		}, void 0, versionColumn, expectedVersion);
 		this._log(sql, params);
-		const result = this._wrapConstraintError(() => this.driver.run(sql, params));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -594,7 +863,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		const versionColumn = this._table.versionColumn;
 		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, void 0, versionColumn);
 		this._log(sql, params);
-		const result = this._wrapConstraintError(() => this.driver.run(sql, params));
+		const result = await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)));
 		return {
 			matchedCount: result.changes,
 			modifiedCount: result.changes
@@ -605,20 +874,26 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		const tableName = this.resolveTableName();
 		const sql = `DELETE FROM "${esc(tableName)}" WHERE rowid = (SELECT rowid FROM "${esc(tableName)}" WHERE ${where.sql} LIMIT 1)`;
 		this._log(sql, where.params);
-		return { deletedCount: this._wrapConstraintError(() => this.driver.run(sql, where.params)).changes };
+		return { deletedCount: (await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, where.params)))).changes };
 	}
 	async deleteMany(filter) {
 		const where = buildWhere(filter);
 		const { sql, params } = buildDelete$1(this.resolveTableName(), where);
 		this._log(sql, params);
-		return { deletedCount: this._wrapConstraintError(() => this.driver.run(sql, params)).changes };
+		return { deletedCount: (await this._stmt(() => this._wrapConstraintError(() => this.driver.run(sql, params)))).changes };
 	}
-	async ensureTable() {
-		if (this._table instanceof AtscriptDbView) return this.ensureView();
-		const sql = buildCreateTable(this.resolveTableName(), this._table.fieldDescriptors, this._table.foreignKeys, { typeMapper: (field) => this.typeMapper(field) });
-		this._log(sql);
-		this.driver.exec(sql);
-		this._seedIncrementStart();
+	/**
+	* SQLite accepts forward FK references, so a foreign-key cycle is created
+	* inline in any order — `opts.deferForeignKeysTo` is accepted and ignored.
+	*/
+	async ensureTable(_opts) {
+		return this._withExclusiveConnection(async () => {
+			if (this._table.isView) return this.ensureView();
+			const sql = buildCreateTable(this.resolveTableName(), this._table.fieldDescriptors, this._table.foreignKeys, { typeMapper: (field) => this.typeMapper(field) });
+			this._log(sql);
+			this.driver.exec(sql);
+			this._seedIncrementStart();
+		});
 	}
 	_incrementSeeded = false;
 	/**
@@ -638,129 +913,213 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		}
 	}
 	async ensureView() {
-		const view = this._table;
-		const sql = buildCreateView$1(this.resolveTableName(), view.viewPlan, view.getViewColumnMappings(), (ref) => view.resolveFieldRef(ref));
-		this._log(sql);
-		this.driver.exec(sql);
+		return this._stmt(() => {
+			const view = this._table;
+			const sql = buildCreateView$1(this.resolveTableName(), view.viewPlan, view.getViewColumnMappings(), (ref) => view.resolveFieldRef(ref));
+			this._log(sql);
+			this.driver.exec(sql);
+		});
 	}
 	async getExistingColumns() {
 		return this.getExistingColumnsForTable(this.resolveTableName());
 	}
 	async syncColumns(diff) {
-		const tableName = this.resolveTableName();
-		const added = [];
-		const renamed = [];
-		for (const { field, oldName } of diff.renamed ?? []) {
-			const ddl = `ALTER TABLE "${esc(tableName)}" RENAME COLUMN "${esc(oldName)}" TO "${esc(field.physicalName)}"`;
-			this._log(ddl);
-			this.driver.exec(ddl);
-			renamed.push(field.physicalName);
-		}
-		for (const field of diff.added) {
-			const sqlType = this.typeMapper(field);
-			let ddl = `ALTER TABLE "${esc(tableName)}" ADD COLUMN "${esc(field.physicalName)}" ${sqlType}`;
-			if (!field.optional && !field.isPrimaryKey) ddl += " NOT NULL";
-			if (field.defaultValue?.kind === "value") ddl += ` DEFAULT ${defaultValueToSqlLiteral(field.designType, field.defaultValue.value)}`;
-			else if (!field.optional && !field.isPrimaryKey) ddl += ` DEFAULT ${defaultValueForType(field.designType)}`;
-			if (field.collate) ddl += ` COLLATE ${field.collate.toUpperCase()}`;
-			this._log(ddl);
-			this.driver.exec(ddl);
-			added.push(field.physicalName);
-		}
-		return {
-			added,
-			renamed
-		};
+		return this._stmt(() => {
+			const tableName = this.resolveTableName();
+			const added = [];
+			const renamed = [];
+			for (const { field, oldName } of diff.renamed ?? []) {
+				const ddl = `ALTER TABLE "${esc(tableName)}" RENAME COLUMN "${esc(oldName)}" TO "${esc(field.physicalName)}"`;
+				this._log(ddl);
+				this.driver.exec(ddl);
+				renamed.push(field.physicalName);
+			}
+			for (const field of diff.added) {
+				const sqlType = this.typeMapper(field);
+				let ddl = `ALTER TABLE "${esc(tableName)}" ADD COLUMN "${esc(field.physicalName)}" ${sqlType}`;
+				if (!field.optional && !field.isPrimaryKey) ddl += " NOT NULL";
+				if (field.defaultValue?.kind === "value") ddl += ` DEFAULT ${defaultValueToSqlLiteral(field.designType, field.defaultValue.value)}`;
+				else if (!field.optional && !field.isPrimaryKey) ddl += ` DEFAULT ${defaultValueForType(field.designType)}`;
+				if (field.collate) ddl += ` COLLATE ${field.collate.toUpperCase()}`;
+				this._log(ddl);
+				this.driver.exec(ddl);
+				added.push(field.physicalName);
+			}
+			return {
+				added,
+				renamed
+			};
+		});
 	}
 	async recreateTable() {
-		const tableName = this.resolveTableName();
-		const tempName = `${tableName}__tmp_${Date.now()}`;
-		this._dropAllFtsTables(tableName);
-		this._dropAllVecTables(tableName);
-		this.driver.exec("PRAGMA foreign_keys = OFF");
-		this.driver.exec("PRAGMA legacy_alter_table = ON");
-		try {
-			const createSql = buildCreateTable(tempName, this._table.fieldDescriptors, this._table.foreignKeys, { typeMapper: (field) => this.typeMapper(field) });
-			this._log(createSql);
-			this.driver.exec(createSql);
-			const oldCols = (await this.getExistingColumns()).map((c) => c.name);
-			const newCols = this._table.fieldDescriptors.filter((f) => !f.ignored).map((f) => f.physicalName);
-			const oldColSet = new Set(oldCols);
-			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) => `"${esc(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(field.designType, field.defaultValue.value) : defaultValueForType(field.designType);
-						return `COALESCE("${esc(c)}", ${fallback}) AS "${esc(c)}"`;
-					}
-					return `"${esc(c)}"`;
-				}).join(", ");
-				const copySql = `INSERT INTO "${esc(tempName)}" (${colNames}) SELECT ${selectExprs} FROM "${esc(tableName)}"`;
-				this._log(copySql);
-				this.driver.exec(copySql);
+		return this._withExclusiveConnection(async () => {
+			const tableName = this.resolveTableName();
+			const tempName = `${tableName}__tmp_${Date.now()}`;
+			this._dropAllFtsTables(tableName);
+			this._dropAllVecTables(tableName);
+			this.driver.exec("PRAGMA foreign_keys = OFF");
+			this.driver.exec("PRAGMA legacy_alter_table = ON");
+			try {
+				const createSql = buildCreateTable(tempName, this._table.fieldDescriptors, this._table.foreignKeys, { typeMapper: (field) => this.typeMapper(field) });
+				this._log(createSql);
+				this.driver.exec(createSql);
+				const oldCols = (await this.getExistingColumns()).map((c) => c.name);
+				const newCols = this._table.fieldDescriptors.filter((f) => !f.ignored).map((f) => f.physicalName);
+				const oldColSet = new Set(oldCols);
+				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) => `"${esc(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(field.designType, field.defaultValue.value) : defaultValueForType(field.designType);
+							return `COALESCE("${esc(c)}", ${fallback}) AS "${esc(c)}"`;
+						}
+						return `"${esc(c)}"`;
+					}).join(", ");
+					const copySql = `INSERT INTO "${esc(tempName)}" (${colNames}) SELECT ${selectExprs} FROM "${esc(tableName)}"`;
+					this._log(copySql);
+					this.driver.exec(copySql);
+				}
+				const oldName = `${tableName}__old_${Date.now()}`;
+				this.driver.exec(`ALTER TABLE "${esc(tableName)}" RENAME TO "${esc(oldName)}"`);
+				this.driver.exec(`ALTER TABLE "${esc(tempName)}" RENAME TO "${esc(tableName)}"`);
+				this.driver.exec(`DROP TABLE IF EXISTS "${esc(oldName)}"`);
+			} finally {
+				this.driver.exec("PRAGMA legacy_alter_table = OFF");
+				this.driver.exec("PRAGMA foreign_keys = ON");
 			}
-			const oldName = `${tableName}__old_${Date.now()}`;
-			this.driver.exec(`ALTER TABLE "${esc(tableName)}" RENAME TO "${esc(oldName)}"`);
-			this.driver.exec(`ALTER TABLE "${esc(tempName)}" RENAME TO "${esc(tableName)}"`);
-			this.driver.exec(`DROP TABLE IF EXISTS "${esc(oldName)}"`);
-		} finally {
-			this.driver.exec("PRAGMA legacy_alter_table = OFF");
-			this.driver.exec("PRAGMA foreign_keys = ON");
-		}
+		});
 	}
 	async dropTable() {
-		const tableName = this.resolveTableName();
-		this._dropAllFtsTables(tableName);
-		this._dropAllVecTables(tableName);
-		const ddl = `DROP TABLE IF EXISTS "${esc(tableName)}"`;
-		this._log(ddl);
-		this.driver.exec(ddl);
+		return this._stmt(() => {
+			const tableName = this.resolveTableName();
+			this._dropAllFtsTables(tableName);
+			this._dropAllVecTables(tableName);
+			const ddl = `DROP TABLE IF EXISTS "${esc(tableName)}"`;
+			this._log(ddl);
+			this.driver.exec(ddl);
+		});
 	}
 	async dropColumns(columns) {
-		await this.withTransaction(async () => {
-			const tableName = this.resolveTableName();
-			for (const col of columns) {
-				const ddl = `ALTER TABLE "${esc(tableName)}" DROP COLUMN "${esc(col)}"`;
-				this._log(ddl);
-				this.driver.exec(ddl);
-			}
+		return this._withExclusiveConnection(async () => {
+			await this.withTransaction(async () => {
+				const tableName = this.resolveTableName();
+				for (const col of columns) {
+					const ddl = `ALTER TABLE "${esc(tableName)}" DROP COLUMN "${esc(col)}"`;
+					this._log(ddl);
+					this.driver.exec(ddl);
+				}
+			});
 		});
 	}
 	async dropIndexesForColumns(columns) {
-		const tableName = this.resolveTableName();
-		const dropped = new Set(columns);
-		const indexes = this.driver.all(`PRAGMA index_list("${esc(tableName)}")`).filter((i) => i.name.startsWith("atscript__"));
-		for (const index of indexes) if (this.driver.all(`PRAGMA index_info("${esc(index.name)}")`).some((c) => c.name !== null && dropped.has(c.name))) {
-			const sql = `DROP INDEX IF EXISTS "${esc(index.name)}"`;
-			this._log(sql);
-			this.driver.exec(sql);
-		}
-		for (const name of this._listShadowTables(tableName, "fts")) if (this.driver.all(`PRAGMA table_info("${esc(name)}")`).some((c) => dropped.has(c.name))) this._dropFtsTable(name);
-		for (const name of this._listShadowTables(tableName, "vec")) {
-			const triggerSql = this.driver.all(`SELECT sql FROM sqlite_master WHERE type='trigger' AND name = ?`, [`${name}__ai`])[0]?.sql ?? "";
-			if (columns.some((c) => triggerSql.includes(`"${esc(c)}"`))) this._dropVecTable(name);
-		}
+		return this._stmt(() => {
+			const tableName = this.resolveTableName();
+			const dropped = new Set(columns);
+			const indexes = this.driver.all(`PRAGMA index_list("${esc(tableName)}")`).filter((i) => i.name.startsWith("atscript__"));
+			for (const index of indexes) if (this.driver.all(`PRAGMA index_info("${esc(index.name)}")`).some((c) => c.name !== null && dropped.has(c.name))) {
+				const sql = `DROP INDEX IF EXISTS "${esc(index.name)}"`;
+				this._log(sql);
+				this.driver.exec(sql);
+			}
+			for (const name of this._listShadowTables(tableName, "fts")) if (this.driver.all(`PRAGMA table_info("${esc(name)}")`).some((c) => dropped.has(c.name))) this._dropFtsTable(name);
+			for (const name of this._listShadowTables(tableName, "vec")) {
+				const triggerSql = this.driver.all(`SELECT sql FROM sqlite_master WHERE type='trigger' AND name = ?`, [`${name}__ai`])[0]?.sql ?? "";
+				if (columns.some((c) => triggerSql.includes(`"${esc(c)}"`))) this._dropVecTable(name);
+			}
+		});
 	}
 	async dropTableByName(tableName) {
-		this._dropAllFtsTables(tableName);
-		this._dropAllVecTables(tableName);
-		const ddl = `DROP TABLE IF EXISTS "${esc(tableName)}"`;
-		this._log(ddl);
-		this.driver.exec(ddl);
+		return this._stmt(() => {
+			this._dropAllFtsTables(tableName);
+			this._dropAllVecTables(tableName);
+			const ddl = `DROP TABLE IF EXISTS "${esc(tableName)}"`;
+			this._log(ddl);
+			this.driver.exec(ddl);
+		});
 	}
 	async dropViewByName(viewName) {
-		const ddl = `DROP VIEW IF EXISTS "${esc(viewName)}"`;
-		this._log(ddl);
-		this.driver.exec(ddl);
+		return this._stmt(() => {
+			const ddl = `DROP VIEW IF EXISTS "${esc(viewName)}"`;
+			this._log(ddl);
+			this.driver.exec(ddl);
+		});
+	}
+	/**
+	* Drops a group of mutually referencing tables with FK enforcement off for
+	* the duration (`PRAGMA foreign_keys` is a no-op inside a transaction, so
+	* the exclusive connection hold — not a `BEGIN` — keeps another context's
+	* transaction from overlapping it). Safe because schema sync only passes
+	* groups whose referrers are all inside the group.
+	*/
+	async dropTablesByName(tableNames) {
+		return this._withExclusiveConnection(async () => {
+			this.driver.exec("PRAGMA foreign_keys = OFF");
+			try {
+				for (const name of tableNames) await this.dropTableByName(name);
+			} finally {
+				this.driver.exec("PRAGMA foreign_keys = ON");
+			}
+		});
+	}
+	async hasRows(tableName) {
+		return this._stmt(() => {
+			const sql = `SELECT 1 AS one FROM "${esc(tableName ?? this.resolveTableName())}" LIMIT 1`;
+			this._log(sql);
+			return this.driver.get(sql) != null;
+		});
+	}
+	/**
+	* Live foreign keys referencing `tableName`: `PRAGMA foreign_key_list` is
+	* outbound-only, so the tables in `sqlite_master` are scanned (a loop
+	* rather than the `pragma_foreign_key_list` table-valued function, which
+	* not every bundled SQLite exposes). Only tables whose CREATE text contains
+	* `REFERENCES` can declare a foreign key — the prefilter is a superset, a
+	* false positive just costs one PRAGMA.
+	*/
+	async getReferencingForeignKeys(tableName) {
+		return this._stmt(() => {
+			const out = [];
+			const tables = this.driver.all(`SELECT name FROM sqlite_master
+         WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND sql LIKE '%REFERENCES%'`);
+			for (const { name } of tables) {
+				const rows = this.driver.all(`PRAGMA foreign_key_list("${esc(name)}")`);
+				const byId = /* @__PURE__ */ new Map();
+				for (const row of rows) {
+					if (row.table !== tableName) continue;
+					let fk = byId.get(row.id);
+					if (!fk) {
+						fk = {
+							table: name,
+							fields: [],
+							targetFields: []
+						};
+						byId.set(row.id, fk);
+					}
+					fk.fields.push(row.from);
+					fk.targetFields.push(row.to);
+				}
+				out.push(...byId.values());
+			}
+			return out;
+		});
+	}
+	async getObjectKind(name) {
+		return this._stmt(() => {
+			const row = this.driver.get(`SELECT type FROM sqlite_master WHERE name = ? AND type IN ('table', 'view')`, [name]);
+			if (!row) return;
+			return row.type === "view" ? "view" : "table";
+		});
 	}
 	async renameTable(oldName) {
-		const newName = this.resolveTableName();
-		const ddl = `ALTER TABLE "${esc(oldName)}" RENAME TO "${esc(newName)}"`;
-		this._log(ddl);
-		this.driver.exec(ddl);
+		return this._stmt(() => {
+			const newName = this.resolveTableName();
+			const ddl = `ALTER TABLE "${esc(oldName)}" RENAME TO "${esc(newName)}"`;
+			this._log(ddl);
+			this.driver.exec(ddl);
+		});
 	}
 	typeMapper(field) {
 		if (field.encrypted) return "TEXT";
@@ -769,37 +1128,41 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		return sqliteTypeFromDesignType(field.designType);
 	}
 	async getExistingColumnsForTable(tableName) {
-		return this.driver.all(`PRAGMA table_info("${esc(tableName)}")`).map((r) => ({
-			name: r.name,
-			type: r.type,
-			notnull: r.notnull === 1,
-			pk: r.pk > 0,
-			dflt_value: normalizeSqliteDefault(r.dflt_value)
-		}));
+		return this._stmt(() => {
+			return this.driver.all(`PRAGMA table_info("${esc(tableName)}")`).map((r) => ({
+				name: r.name,
+				type: r.type,
+				notnull: r.notnull === 1,
+				pk: r.pk > 0,
+				dflt_value: normalizeSqliteDefault(r.dflt_value)
+			}));
+		});
 	}
 	async syncIndexes() {
-		const tableName = this.resolveTableName();
-		await this.syncIndexesWithDiff({
-			listExisting: async () => this.driver.all(`PRAGMA index_list("${esc(tableName)}")`).filter((i) => !i.name.startsWith("sqlite_")).map((i) => ({
-				name: i.name,
-				columns: this.driver.all(`PRAGMA index_info("${esc(i.name)}")`).map((c) => c.name).filter((n) => n !== null)
-			})),
-			createIndex: async (index) => {
-				const unique = index.type === "unique" ? "UNIQUE " : "";
-				const cols = index.fields.map((f) => `"${esc(f.name)}" ${f.sort === "desc" ? "DESC" : "ASC"}`).join(", ");
-				const sql = `CREATE ${unique}INDEX IF NOT EXISTS "${esc(index.key)}" ON "${esc(tableName)}" (${cols})`;
-				this._log(sql);
-				this.driver.exec(sql);
-			},
-			dropIndex: async (name) => {
-				const sql = `DROP INDEX IF EXISTS "${esc(name)}"`;
-				this._log(sql);
-				this.driver.exec(sql);
-			},
-			shouldSkipType: (type) => type === "fulltext" || type === "geo"
+		return this._withExclusiveConnection(async () => {
+			const tableName = this.resolveTableName();
+			await this.syncIndexesWithDiff({
+				listExisting: async () => this.driver.all(`PRAGMA index_list("${esc(tableName)}")`).filter((i) => !i.name.startsWith("sqlite_")).map((i) => ({
+					name: i.name,
+					columns: this.driver.all(`PRAGMA index_info("${esc(i.name)}")`).map((c) => c.name).filter((n) => n !== null)
+				})),
+				createIndex: async (index) => {
+					const unique = index.type === "unique" ? "UNIQUE " : "";
+					const cols = index.fields.map((f) => `"${esc(f.name)}" ${f.sort === "desc" ? "DESC" : "ASC"}`).join(", ");
+					const sql = `CREATE ${unique}INDEX IF NOT EXISTS "${esc(index.key)}" ON "${esc(tableName)}" (${cols})`;
+					this._log(sql);
+					this.driver.exec(sql);
+				},
+				dropIndex: async (name) => {
+					const sql = `DROP INDEX IF EXISTS "${esc(name)}"`;
+					this._log(sql);
+					this.driver.exec(sql);
+				},
+				shouldSkipType: (type) => type === "fulltext" || type === "geo"
+			});
+			this._syncFtsIndexes(tableName);
+			this._syncVecIndexes(tableName);
 		});
-		this._syncFtsIndexes(tableName);
-		this._syncVecIndexes(tableName);
 	}
 	getSearchIndexes() {
 		const indexes = [];
@@ -838,7 +1201,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 			params.push(controls.$skip);
 		}
 		this._log(sql, params);
-		return this.driver.all(sql, params);
+		return this._stmt(() => this.driver.all(sql, params));
 	}
 	async searchWithCount(text, query, indexName) {
 		if (!text.trim()) return {
@@ -851,7 +1214,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		this._log(countSql, base.params);
 		return {
 			data,
-			count: this.driver.get(countSql, base.params)?.cnt ?? 0
+			count: (await this._stmt(() => this.driver.get(countSql, base.params)))?.cnt ?? 0
 		};
 	}
 	/** Builds FTS table name from index name: `<table>__fts__<indexName>`. */
@@ -956,18 +1319,20 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 	async vectorSearch(vector, query, indexName) {
 		if (!this._detectVectorSupport()) throw new Error("Vector search requires the sqlite-vec extension. Construct BetterSqlite3Driver with { vector: true }.");
 		const base = this._buildVectorSearchBase(vector, query, indexName);
-		return this._runVectorSearch(base);
+		return this._stmt(() => this._runVectorSearch(base));
 	}
 	async vectorSearchWithCount(vector, query, indexName) {
 		if (!this._detectVectorSupport()) throw new Error("Vector search requires the sqlite-vec extension. Construct BetterSqlite3Driver with { vector: true }.");
 		const base = this._buildVectorSearchBase(vector, query, indexName);
-		const data = this._runVectorSearch(base);
 		const countSql = `SELECT COUNT(*) AS cnt ${base.fromWhere}`;
-		this._log(countSql, base.params);
-		return {
-			data,
-			count: this.driver.get(countSql, base.params)?.cnt ?? 0
-		};
+		return this._stmt(() => {
+			const data = this._runVectorSearch(base);
+			this._log(countSql, base.params);
+			return {
+				data,
+				count: this.driver.get(countSql, base.params)?.cnt ?? 0
+			};
+		});
 	}
 	_runVectorSearch(base) {
 		let sql = `SELECT * ${base.fromWhere} ORDER BY _distance ASC LIMIT ?`;
@@ -1098,7 +1463,7 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 	async geoSearch(point, query, indexName) {
 		const { sql, params } = this._buildGeoSearchSelect(this._prepareGeoSearch(point, query, indexName));
 		this._log(sql, params);
-		return this.driver.all(sql, params).map((row) => renameGeoDistance(row));
+		return (await this._stmt(() => this.driver.all(sql, params))).map((row) => renameGeoDistance(row));
 	}
 	async geoSearchWithCount(point, query, indexName) {
 		const ctx = this._prepareGeoSearch(point, query, indexName);
@@ -1106,8 +1471,10 @@ var SqliteAdapter = class SqliteAdapter extends BaseDbAdapter {
 		const countFrag = buildGeoSearchCount(sqliteDialect, ctx.tableName, ctx.where, ctx.dist, ctx.window);
 		this._log(sql, params);
 		this._log(countFrag.sql, countFrag.params);
-		const rows = this.driver.all(sql, params);
-		const countRow = this.driver.get(countFrag.sql, countFrag.params);
+		const { rows, countRow } = await this._stmt(() => ({
+			rows: this.driver.all(sql, params),
+			countRow: this.driver.get(countFrag.sql, countFrag.params)
+		}));
 		return {
 			data: rows.map((row) => renameGeoDistance(row)),
 			count: countRow?.cnt ?? 0
@@ -1240,8 +1607,13 @@ function normalizeSqliteDefault(value) {
 //#endregion
 //#region src/index.ts
 function createAdapter(connection, options) {
-	const driver = new BetterSqlite3Driver(connection, options);
-	return new DbSpace(() => new SqliteAdapter(driver));
+	const { transactionWaitTimeoutMs, transactionWaitWarnMs, ...driverOptions } = options ?? {};
+	const driver = new BetterSqlite3Driver(connection, driverOptions);
+	const adapterOptions = {
+		transactionWaitTimeoutMs,
+		transactionWaitWarnMs
+	};
+	return new DbSpace(() => new SqliteAdapter(driver, adapterOptions));
 }
 //#endregion
-export { BetterSqlite3Driver, SqliteAdapter, buildWhere, createAdapter };
+export { BetterSqlite3Driver, SqliteAdapter, SqliteTxGate, SqliteTxState, buildWhere, createAdapter, getSqliteTxGate };