kern-db 0.0.0-stage → 0.2.0

package/dist/database-BkWPkXG5.mjs

@@ -0,0 +1,1470 @@
+import { i as decodeBoolean } from "./bytea-DNZ_ftio.mjs";
+import { S as createStatement, _ as sql, f as compileFragment, n as startSqlQuery, p as compileScript, x as quoteIdentifier } from "./query-FKBN7BMY.mjs";
+import { i as setBrand, n as QueryError, r as isInstance, t as ConnectionError } from "./driver-error-26zcdHeU.mjs";
+import { n as formatArray } from "./array-BLt8ZNR5.mjs";
+import { AsyncLocalStorage } from "node:async_hooks";
+// src/transaction/release.ts
+/**
+* Returns a connection to the driver and passes a failed release to `onReleaseError`, or to `console.error` without one.
+*
+* The result or error of the transaction is decided before its release, so a failed release must not change it: a committed transaction that rejected would be retried.
+* Reporting the failure cannot change it either.
+* The error of a handler that throws or rejects goes to `console.error` with the failure of the release, and a `console.error` that throws is ignored.
+*/
+async function releaseConnection(connection, onReleaseError) {
+	try {
+		await connection.release();
+	} catch (error) {
+		reportReleaseError(error, onReleaseError);
+	}
+}
+/** Passes a failed release to `onReleaseError`, or to `console.error` without one, without throwing. */
+function reportReleaseError(error, onReleaseError) {
+	if (!onReleaseError) {
+		logReleaseError(error);
+		return;
+	}
+	try {
+		Promise.resolve(onReleaseError(error)).catch((handlerError) => logReleaseError(error, { error: handlerError }));
+	} catch (handlerError) {
+		logReleaseError(error, { error: handlerError });
+	}
+}
+/**
+* Writes a failed release to `console.error`, preceded by the error of `onReleaseError` when the handler failed.
+*
+* A console that throws, such as one redirected to a failing logger, leaves nowhere to report to, so its error is ignored.
+*/
+function logReleaseError(error, handlerFailure) {
+	try {
+		if (handlerFailure) console.error("kern-db: onReleaseError failed", handlerFailure.error);
+		console.error("kern-db: releasing a connection failed", error);
+	} catch {}
+}
+// src/transaction/abort.ts
+/**
+* Runs `start` and settles as its promise, or rejects with the reason of `signal` when it aborts first and `abort`, called on the abort, returns `true`.
+*
+* It listens from before `start`, which may abort the signal before it returns, and stops once the promise of `start` settles, such as for the signal that `node:test` aborts after every test.
+* A later rejection of that promise stays handled, and a value it resolves with after the rejection goes to `discard`, which handles its own failures.
+*/
+function settleUnlessAborted(start, signal, abort, discard) {
+	const settled = Promise.withResolvers();
+	let abandoned = false;
+	const onAbort = () => {
+		if (abort()) {
+			abandoned = true;
+			settled.reject(signal.reason);
+		}
+	};
+	signal.addEventListener("abort", onAbort, { once: true });
+	let running;
+	try {
+		running = start();
+	} catch (error) {
+		signal.removeEventListener("abort", onAbort);
+		settled.reject(error);
+		return settled.promise;
+	}
+	running.then((value) => {
+		signal.removeEventListener("abort", onAbort);
+		if (abandoned) discard?.(value);
+		else settled.resolve(value);
+	}, (error) => {
+		signal.removeEventListener("abort", onAbort);
+		settled.reject(error);
+	});
+	return settled.promise;
+}
+/**
+* Acquires a connection for a test transaction, rejecting with the reason of `signal` when it aborts first.
+*
+* A connection acquired after the abort returns to the pool as best-effort cleanup: the test transaction has already rejected, so nothing awaits the release, and its failure goes to `onReleaseError`.
+*/
+function acquireUnlessAborted(driver, signal, onReleaseError) {
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return settleUnlessAborted(() => driver.acquire(), signal, () => true, (connection) => void releaseConnection(connection, onReleaseError));
+}
+// src/transaction/advisory-lock.ts
+/** Pause of `pollLock` in milliseconds after its first attempt, which doubles after each attempt up to `maxPollDelay`. */
+const firstPollDelay = 50;
+/** Longest pause of `pollLock` in milliseconds. */
+const maxPollDelay = 1e3;
+/** Creates the statement that takes the transaction-level advisory lock of `key`, waiting while another transaction or session holds it. */
+function createLockStatement(key) {
+	return createStatement("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [key]);
+}
+/** Creates the statement that takes the transaction-level advisory lock of `key` unless another transaction or session holds it, see `isTaken`. */
+function createTryLockStatement(key) {
+	return createStatement("SELECT pg_try_advisory_xact_lock(hashtextextended($1, 0))", [key]);
+}
+/** Tells whether the statement that tried to take a lock took it. */
+function isTaken(result) {
+	return decodeBoolean(result.rows[0][0]);
+}
+/**
+* Calls `tryLock` until it takes the lock, with `wait` pausing between the attempts, and rejects with the reason of `signal` once it aborts.
+*
+* An attempt that runs when `signal` aborts is awaited, and if it takes the lock, the call resolves, since the session holds the lock until it ends.
+* `wait` is `pause`, which a test replaces to observe the pauses without a clock.
+*/
+async function pollLock(tryLock, signal, wait = pause) {
+	signal?.throwIfAborted();
+	let delay = firstPollDelay;
+	while (!await tryLock()) {
+		signal?.throwIfAborted();
+		await wait(delay, signal);
+		delay = Math.min(delay * 2, maxPollDelay);
+	}
+}
+/** Waits `delay` milliseconds, or rejects with the reason of `signal` once it aborts, clearing the timer so that it keeps no process alive. */
+function pause(delay, signal) {
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal.reason);
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, delay);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Advisory locks that a session takes with `tryLock` until it ends.
+*
+* PostgreSQL holds a lock of a session until `pg_advisory_unlock` releases it as many times as the session took it, so the session takes each key once, and one `pg_advisory_unlock` of each key releases it.
+*/
+var SessionLocks = class {
+	/** Attempt of each key that the session holds or is taking; an attempt that does not take its lock leaves it. */
+	#attempts = /* @__PURE__ */ new Map();
+	/** Whether a statement of an attempt failed: PostgreSQL keeps a lock of a session that it took after the statement fails, so whether the connection holds it is unknown. */
+	#failed = false;
+	/** Takes the lock of `key` on `connection` unless another session or transaction holds it, and tells whether it took it; a key that the session holds or is taking returns that attempt without a statement. */
+	take(connection, key) {
+		const current = this.#attempts.get(key);
+		if (current) return current;
+		const attempt = connection.execute(createStatement("SELECT pg_try_advisory_lock(hashtextextended($1, 0))", [key])).then((result) => {
+			const taken = isTaken(result);
+			if (!taken) this.#attempts.delete(key);
+			return taken;
+		}, (error) => {
+			this.#failed = true;
+			this.#attempts.delete(key);
+			throw error;
+		});
+		this.#attempts.set(key, attempt);
+		return attempt;
+	}
+	/**
+	* Waits for the attempts in progress and returns the keys of the locks that the session holds, or `undefined` when a statement of an attempt failed, so that it is unknown which locks the connection holds.
+	*
+	* An attempt that the callback of the session did not await is sent before the session ends, so waiting for it does not wait for the session.
+	*/
+	async settle() {
+		await Promise.allSettled(this.#attempts.values());
+		return this.#failed ? void 0 : [...this.#attempts.keys()];
+	}
+};
+/**
+* Creates the statement that releases the locks of a session of `keys`, once each, see `SessionLocks`.
+*
+* It takes the keys as one array and releases them in rows, since PostgreSQL limits the columns of a result to 1664.
+*/
+function createUnlockStatement(keys) {
+	return createStatement("SELECT pg_advisory_unlock(hashtextextended(key, 0)) FROM unnest($1::text[]) AS key", [formatArray(keys, (key) => key)]);
+}
+// src/transaction/connection-loss.ts
+/** Marks an instance of `TransactionConnectionError` of any copy of kern-db. */
+const transactionConnectionErrorBrand = /* @__PURE__ */ Symbol.for("kern-db.TransactionConnectionError");
+/** Message of a transaction whose connection failed in each phase. */
+const phaseMessages = {
+	begin: "Transaction did not start: its connection failed",
+	transaction: "Transaction was rolled back: its connection failed",
+	commit: "Transaction may have been committed: its connection failed during COMMIT"
+};
+/**
+* Error of a transaction whose connection failed, which tells whether the transaction may have been committed.
+*
+* Its `cause` is the error that the transaction would reject with otherwise, such as the error of the callback, or a `SuppressedError` of a failed rollback that keeps it.
+*/
+var TransactionConnectionError = class TransactionConnectionError extends ConnectionError {
+	name = "TransactionConnectionError";
+	/**
+	* Phase of the transaction in which its connection failed:
+	*
+	* - `begin`: before the callback, such as getting the connection or `BEGIN`, so the transaction applied nothing;
+	* - `transaction`: in the callback or its rollback, so the transaction was rolled back;
+	* - `commit`: during `COMMIT`, so whether the transaction was committed is unknown.
+	*/
+	phase;
+	constructor(phase, options) {
+		super(phaseMessages[phase], options);
+		this.phase = phase;
+		setBrand(this, transactionConnectionErrorBrand);
+	}
+	/** Tells whether `value` is an instance of the class, including one of `TransactionConnectionError` of another copy of kern-db. */
+	static [Symbol.hasInstance](value) {
+		return isInstance(this, TransactionConnectionError, transactionConnectionErrorBrand, value);
+	}
+};
+/**
+* Reserved connection of a transaction of `transaction` that records the first `ConnectionError` of its statements and scripts, including those of its nested levels.
+*
+* A failure before `COMMIT` is sent makes the transaction roll back rather than commit, since the statement may not have run.
+* A transaction that rejects after a failure rejects with `TransactionConnectionError` of its phase, while one whose `COMMIT` succeeded resolves.
+*/
+var ConnectionWatch = class {
+	/** Phase of the transaction, which its root advances to `transaction` before the callback and to `commit` before `COMMIT`. */
+	phase = "begin";
+	/** First `ConnectionError`; a later statement that succeeds changes nothing. */
+	failure;
+	#connection;
+	#observe = (error) => {
+		if (!this.failure && error instanceof ConnectionError) this.failure = {
+			error,
+			phase: this.phase
+		};
+		throw error;
+	};
+	constructor(connection) {
+		this.#connection = connection;
+	}
+	execute(statement) {
+		return this.#connection.execute(statement).catch(this.#observe);
+	}
+	executeScript(text) {
+		return this.#connection.executeScript(text).catch(this.#observe);
+	}
+	release() {
+		return this.#connection.release();
+	}
+};
+// src/transaction/settings.ts
+/** Settings of a level of `transaction` or of `session` with `options`, or `undefined` when it has none. */
+function getLevelSettings(options) {
+	return options?.searchPath ? [{
+		name: "search_path",
+		value: options.searchPath.map(quoteIdentifier).join(", ")
+	}] : void 0;
+}
+/**
+* Applies `settings` to a level whose `BEGIN` or `SAVEPOINT` completed, or to a session, unless its cleanup has started.
+*
+* A savepoint first reads the values they replace, which it restores before its `RELEASE`: PostgreSQL keeps a setting of a released savepoint until the transaction ends, while `ROLLBACK TO` restores it itself.
+* A session reads them too, and sets its settings for the whole session of PostgreSQL, since it has no transaction that would end them; the coordinator restores them before it releases the connection.
+*/
+async function applySettings(level, settings) {
+	if (level.cleanup) return;
+	const local = !level.session;
+	if (level.session || level.savepoint) {
+		let text = "SELECT";
+		const names = [];
+		for (const { name } of settings) {
+			names.push(name);
+			text += `${names.length > 1 ? "," : ""} current_setting($${names.length})`;
+		}
+		const values = (await level.connection.execute(createStatement(text, names))).rows[0];
+		level.restore = createSettingStatement(settings.map(({ name }, index) => ({
+			name,
+			value: values[index]
+		})), local);
+		if (level.cleanup) return;
+	}
+	await level.connection.execute(createSettingStatement(settings, local));
+}
+/** Creates the statement that sets `settings`: when `local`, until the transaction ends or rolls back to an earlier savepoint, as `SET LOCAL` does, and otherwise for the session of PostgreSQL, as `SET` does. */
+function createSettingStatement(settings, local) {
+	let text = "SELECT";
+	const parameters = [];
+	for (const { name, value } of settings) {
+		parameters.push(name, value);
+		text += `${parameters.length > 2 ? "," : ""} set_config($${parameters.length - 1}, $${parameters.length}, ${local})`;
+	}
+	return createStatement(text, parameters);
+}
+// src/transaction/level.ts
+/** Options of a level started without options, shared so that such a start allocates none. */
+const noLevelOptions = {};
+const beginStatement$1 = /* @__PURE__ */ createStatement("BEGIN");
+const isolatedBeginStatements = {
+	"read committed": /* @__PURE__ */ createStatement("BEGIN ISOLATION LEVEL READ COMMITTED"),
+	"repeatable read": /* @__PURE__ */ createStatement("BEGIN ISOLATION LEVEL REPEATABLE READ"),
+	serializable: /* @__PURE__ */ createStatement("BEGIN ISOLATION LEVEL SERIALIZABLE")
+};
+const readIsolationStatement = /* @__PURE__ */ createStatement("SELECT current_setting('transaction_isolation')");
+const commitStatement = /* @__PURE__ */ createStatement("COMMIT");
+const rollbackStatement = /* @__PURE__ */ createStatement("ROLLBACK");
+/**
+* Statement that starts the transaction of a level that is not a savepoint, a transaction of `transaction`, a test transaction, or the first test fixture, at `isolation` if given.
+*
+* PostgreSQL takes the isolation level only before the first query of a transaction, so `BEGIN` sets it.
+*/
+function getBeginStatement(isolation) {
+	return isolation ? isolatedBeginStatements[isolation] : beginStatement$1;
+}
+/**
+* Creates the state of a `starting` level on `connection`: a savepoint of `parent`, or a transaction, in the session `parent` if given.
+*
+* It sends no SQL and does not reserve the level as the `child` of `parent`; the caller does both.
+* `transaction` tells whether the level is a transaction of `transaction` rather than a level of the test helpers.
+* A transaction of `transaction` that is not a savepoint watches its connection for a `ConnectionError`.
+* `isolation` is the isolation level that a level that is not a savepoint begins with.
+*/
+function createLevel(connection, parent, transaction, isolation) {
+	const enclosing = parent && !parent.session ? parent : void 0;
+	const watch = transaction && !enclosing ? new ConnectionWatch(connection) : void 0;
+	return {
+		connection: watch ?? connection,
+		watch,
+		parent,
+		depth: enclosing ? enclosing.depth + 1 : 0,
+		session: false,
+		savepoint: enclosing !== void 0,
+		inTransaction: transaction || (enclosing?.inTransaction ?? false),
+		state: "starting",
+		child: void 0,
+		rollbackOnly: void 0,
+		cleanup: void 0,
+		endedBy: void 0,
+		restore: void 0,
+		isolation: enclosing ? enclosing.isolation : isolation,
+		locks: void 0
+	};
+}
+/**
+* Starts a nested level of `parent` with the settings of `options`, at the isolation level of its transaction, rejecting when it cannot start.
+*
+* `transaction` tells whether the level is a transaction of `transaction` rather than a level of the test helpers.
+* A level whose `isolation` differs from that of its transaction rejects without `SAVEPOINT`, since PostgreSQL sets the isolation level only for a whole transaction.
+* A level whose settings fail rolls back to its savepoint first.
+* Aborted by `signal` while it checks `isolation`, it rejects with the reason without `SAVEPOINT`.
+* The failure suppresses the reason of `signal` when the signal aborted before it.
+*/
+async function startNestedLevel(parent, transaction, { signal, settings, isolation } = noLevelOptions) {
+	const level = createLevel(parent.connection, parent, transaction);
+	parent.child = level;
+	if (isolation) {
+		level.state = "reserved";
+		await checkIsolation(level, isolation, signal);
+		if (level.cleanup) return level;
+		if (signal?.aborted) {
+			closeStarting(level);
+			throw signal.reason;
+		}
+		level.state = "starting";
+	}
+	try {
+		await level.connection.execute(createStatement(`SAVEPOINT ${getSavepointName(level)}`));
+	} catch (error) {
+		if (!level.cleanup) {
+			closeStarting(level);
+			throw suppressAbortReason(error, signal);
+		}
+		throw suppressAbortReason(combineRejections({ error }, await level.cleanup).error, signal);
+	}
+	if (settings) try {
+		await applySettings(level, settings);
+	} catch (error) {
+		throw suppressAbortReason(combineRejections({ error }, await endLevel(level, false)).error, signal);
+	}
+	return level;
+}
+/**
+* Checks that the transaction of a `reserved` nested `level` runs at `isolation`, and rejects otherwise, closing the level.
+*
+* A failure suppresses the reason of `signal` when the signal aborted before it.
+* A level that its enclosing level ended during the check returns with its cleanup started.
+*/
+async function checkIsolation(level, isolation, signal) {
+	let actual = level.isolation;
+	if (!actual) {
+		try {
+			actual = (await level.connection.execute(readIsolationStatement)).rows[0][0];
+		} catch (error) {
+			if (!level.cleanup) closeStarting(level);
+			throw suppressAbortReason(error, signal);
+		}
+		level.parent.isolation = actual;
+		level.isolation = actual;
+		if (level.cleanup) return;
+	}
+	if (actual !== isolation) {
+		closeStarting(level);
+		throw suppressAbortReason(/* @__PURE__ */ new Error(`Cannot start a nested transaction at isolation level ${isolation}: its transaction runs at ${actual}, and PostgreSQL sets the isolation level of a whole transaction`), signal);
+	}
+}
+/**
+* Runs `callback` in the context of a started `level` in `storage`, then ends the level.
+*
+* A level that `commits` commits only when the callback resolves with no nested level running and no nested level that failed to end.
+* When `signal` aborts, the level ends at once without waiting for the callback, and its outcome is a rejection with the reason of the signal.
+*/
+async function runLevel(storage, level, callback, commits, signal) {
+	if (level.cleanup) return getEndedOutcome(level.cleanup, createClosedError(level, void 0));
+	let result;
+	let rejection;
+	if (signal?.aborted) endLevel(level, false, "abort");
+	else {
+		level.state = "open";
+		try {
+			result = await (signal ? settleUnlessAborted(() => storage.run(level, callback), signal, () => {
+				endLevel(level, false, "abort");
+				return true;
+			}) : storage.run(level, callback));
+		} catch (error) {
+			rejection = { error };
+		}
+	}
+	if (level.cleanup) return getEndedOutcome(level.cleanup, level.endedBy === "abort" ? signal?.reason : createClosedError(level, rejection));
+	if (!rejection && level.child) rejection = { error: /* @__PURE__ */ new Error(level.session ? "Session ended with an error: a transaction of it was still running when its callback finished" : "Transaction was rolled back: a nested transaction was still running when its callback finished") };
+	if (!rejection && level.rollbackOnly) rejection = { error: new Error("Transaction was rolled back: a nested transaction failed to end", { cause: level.rollbackOnly.error }) };
+	const cleanup = await endLevel(level, commits && !rejection);
+	return {
+		result,
+		rejection: combineRejections(rejection, cleanup)
+	};
+}
+/**
+* Ends `level` once, whoever ends it: later calls return the cleanup already started.
+*
+* Statements of the level and of all levels nested in it fail from the start of the cleanup, and the nested levels end before it.
+*/
+function endLevel(level, commit, endedBy) {
+	if (level.cleanup) return level.cleanup;
+	level.endedBy = endedBy;
+	if (level.state === "reserved") {
+		closeStarting(level);
+		level.cleanup = Promise.resolve({});
+		return level.cleanup;
+	}
+	level.state = "closing";
+	level.cleanup = cleanUpLevel(level, commit, level.child && endLevel(level.child, false, "enclosing level"));
+	return level.cleanup;
+}
+async function cleanUpLevel(level, commit, nested) {
+	const nestedCleanup = await nested;
+	const { parent } = level;
+	let cleanup;
+	if (level.session) cleanup = {};
+	else if (level.savepoint) {
+		cleanup = await endSavepoint(level, commit && !level.rollbackOnly);
+		parent.rollbackOnly ??= cleanup.rejection;
+	} else cleanup = await endTransaction(level, commit);
+	level.state = "closed";
+	if (parent?.child === level) parent.child = void 0;
+	return { rejection: combineRejections(nestedCleanup?.rejection, cleanup) };
+}
+/**
+* Ends a transaction with `COMMIT` or `ROLLBACK`.
+*
+* A transaction whose watch recorded a `ConnectionError` rolls back instead of `COMMIT` and rejects with that error, as if its callback had rejected with it.
+*/
+async function endTransaction(level, commit) {
+	const { connection, watch } = level;
+	const lost = commit && watch?.failure ? { error: watch.failure.error } : void 0;
+	try {
+		if (commit && !lost) {
+			if (watch) watch.phase = "commit";
+			const { command } = await connection.execute(commitStatement);
+			if (command !== "COMMIT") return { rejection: { error: /* @__PURE__ */ new Error("Transaction was rolled back: a statement in it failed") } };
+			return {};
+		}
+		await connection.execute(rollbackStatement);
+		return lost ? { rejection: lost } : {};
+	} catch (error) {
+		return { rejection: suppress(error, lost, "Transaction rollback failed") };
+	}
+}
+/**
+* Ends the savepoint of a nested level, releasing it on commit and rolling back to it otherwise.
+*
+* Before a release, it restores the settings that the level changed; a rollback restores them itself.
+*/
+async function endSavepoint(level, commit) {
+	const name = getSavepointName(level);
+	try {
+		if (!commit) await level.connection.execute(createStatement(`ROLLBACK TO SAVEPOINT ${name}`));
+		else if (level.restore) await level.connection.execute(level.restore);
+		await level.connection.execute(createStatement(`RELEASE SAVEPOINT ${name}`));
+		return {};
+	} catch (error) {
+		return { rejection: { error } };
+	}
+}
+/** Name of the savepoint of a nested level; a level has at most one nested level, so the depth makes it unique. */
+function getSavepointName(level) {
+	return `kern_${level.depth}`;
+}
+/** Closes a level whose `SAVEPOINT` or `BEGIN` was not sent or failed, freeing its parent for other statements. */
+function closeStarting(level) {
+	level.state = "closed";
+	if (level.parent?.child === level) level.parent.child = void 0;
+}
+/**
+* Creates the error of `operation` on a level that rejects statements and nested levels, or returns `undefined` when it accepts them.
+*
+* A level that can only roll back keeps the failure of its nested level as the cause.
+*/
+function createUnavailableError(level, operation) {
+	if (level.session) return createSessionUnavailableError(level, operation);
+	if (level.state !== "open") return /* @__PURE__ */ new Error(`Cannot ${operation}: its transaction is already finished`);
+	if (level.child) return /* @__PURE__ */ new Error(`Cannot ${operation}: a nested transaction is running; await it first`);
+	if (level.rollbackOnly) return new Error(`Cannot ${operation}: a nested transaction failed to end, so the transaction can only roll back`, { cause: level.rollbackOnly.error });
+}
+/** Creates the error of `operation` on a session that rejects statements and transactions, or returns `undefined` when it accepts them. */
+function createSessionUnavailableError(level, operation) {
+	if (level.state !== "open") return /* @__PURE__ */ new Error(`Cannot ${operation}: its session is already finished`);
+	if (level.child) return /* @__PURE__ */ new Error(`Cannot ${operation}: a transaction of the session is running; await it first`);
+	const failure = level.watch?.failure;
+	if (failure) return new Error(`Cannot ${operation}: the connection of the session failed, so the session accepts no more statements`, { cause: failure.error });
+}
+/** Error of a level that another level ended, keeping the rejection of its callback as the cause. */
+function createClosedError(level, rejection) {
+	return new Error(level.endedBy === "preemption" ? "Transaction was rolled back: its test fixture started another level before it finished" : level.parent?.session ? "Transaction was rolled back: its session ended first" : "Transaction was rolled back: its enclosing transaction ended first", rejection && { cause: rejection.error });
+}
+/** Outcome of a level that something other than its callback ended: a rejection with `error`, which a failed cleanup suppresses. */
+async function getEndedOutcome(cleanup, error) {
+	return { rejection: combineRejections({ error }, await cleanup) };
+}
+/** Error of a failure to start a test transaction, which suppresses the reason of `signal` when the signal aborted before the failure. */
+function suppressAbortReason(error, signal) {
+	return signal?.aborted ? suppress(error, { error: signal.reason }, "Starting the test transaction failed").error : error;
+}
+/** Rejection with the error of a cleanup, which suppresses the `earlier` rejection if there is one. */
+function combineRejections(earlier, cleanup) {
+	return cleanup.rejection ? suppress(cleanup.rejection.error, earlier, "Transaction rollback failed") : earlier;
+}
+/** Rejection with `error`, which suppresses the `earlier` rejection if there is one. */
+function suppress(error, earlier, message) {
+	return { error: earlier ? new SuppressedError(error, earlier.error, message) : error };
+}
+// src/transaction/fixture-stack.ts
+/** Open test fixtures of a transaction coordinator and the queue of the changes of their stack. */
+var TestFixtureStack = class {
+	#driver;
+	#onReleaseError;
+	/** Async context of the levels of the coordinator, which tells whether a call runs inside a level. */
+	#storage;
+	/** Open test fixtures, the innermost last. */
+	#fixtures = [];
+	/** Changes of the fixture stack, run one after another so that each one sees the stack the previous one left. */
+	#transitions = Promise.resolve();
+	/**
+	* The `close` functions of the test fixtures that are still opening, from the call that starts the opening until the fixture enters the stack or the opening ends otherwise.
+	*
+	* An opening holds the queue of the fixture stack while its seed runs, so a closing of the stack queued behind it would wait for a seed that may never settle.
+	* Closing the stack therefore calls these first: each one tells its opening to stop waiting for the seed.
+	*/
+	#openings = /* @__PURE__ */ new Set();
+	/**
+	* Outermost fixture in the stack whose closing is queued but has not finished.
+	*
+	* Openings that start after that closing is requested nest outside of the fixture once it closes, so a repeated closing of it, or a closing of a fixture nested in it, must not close them.
+	*/
+	#closing;
+	constructor(driver, storage, onReleaseError) {
+		this.#driver = driver;
+		this.#storage = storage;
+		this.#onReleaseError = onReleaseError;
+	}
+	/**
+	* Starts opening a test fixture with `options`, see `startTestFixture` of the coordinator, or, given `refusal`, returns a fixture that rejects with it.
+	*
+	* The `close` of a refused fixture resolves once the earlier changes of the stack end.
+	*/
+	start(seed, refusal, options) {
+		let level;
+		let closeRequested = false;
+		const closing = Promise.withResolvers();
+		let closedRejection;
+		const close = () => {
+			if (this.#storage.getStore()) return Promise.reject(/* @__PURE__ */ new Error("Cannot close a test fixture inside a transaction"));
+			closeRequested = true;
+			closing.resolve();
+			if (level && this.#fixtures.includes(level)) {
+				const opened = level;
+				if (this.#closing && this.#closing.depth <= opened.depth) return this.#enqueue(() => this.#closeFixture(opened));
+				this.#closing = opened;
+				return this.#closeAfterOpenings(() => this.#enqueue(async () => {
+					try {
+						await this.#closeFixture(opened);
+					} finally {
+						if (this.#closing === opened) this.#closing = void 0;
+					}
+				}));
+			}
+			return this.#enqueue(() => {
+				const rejection = closedRejection;
+				closedRejection = void 0;
+				if (rejection) throw rejection.error;
+			});
+		};
+		if (refusal) return {
+			fixture: Promise.reject(refusal),
+			close
+		};
+		/**
+		* Runs stages 2 and 3 of the fixture and puts it in the stack, returning `undefined` when closing was requested and the fixture rolled back cleanly.
+		*
+		* It rejects with a failure to start the fixture, with the rejection of `seed`, or with a failure to roll back, which suppresses the rejection of `seed`.
+		*/
+		const open = async () => {
+			if (closeRequested) return;
+			const parent = this.#fixtures.at(-1);
+			const started = parent ? await this.#startInFixture(parent, options) : await this.#beginFixture(options?.isolation);
+			started.state = "open";
+			const outcome = closeRequested ? void 0 : await Promise.race([this.#seedFixture(started, seed), closing.promise]);
+			if (outcome && !outcome.rejection && !closeRequested) {
+				this.#fixtures.push(started);
+				level = started;
+				this.#openings.delete(close);
+				const { result } = outcome;
+				return {
+					get data() {
+						if (started.state !== "open") throw new Error("Test fixture is closed");
+						return result;
+					},
+					close,
+					[Symbol.asyncDispose]: close
+				};
+			}
+			const rejection = combineRejections(outcome?.rejection, { rejection: await this.#endFixture(started) });
+			if (rejection) throw rejection.error;
+		};
+		this.#openings.add(close);
+		return {
+			fixture: this.#enqueue(async () => {
+				let opened;
+				try {
+					opened = await open();
+				} catch (error) {
+					if (!closeRequested) throw error;
+					closedRejection = { error };
+				} finally {
+					this.#openings.delete(close);
+				}
+				if (!opened) throw new Error("Test fixture was closed before it opened");
+				return opened;
+			}),
+			close
+		};
+	}
+	/**
+	* Starts the level of a test transaction in the innermost test fixture as a change of the fixture stack, resolving to `undefined` when no fixture is open.
+	*
+	* Aborted while it waits for its turn, it rejects at once and its change starts nothing, so that a test that has already ended never preempts the active level of the fixture.
+	* From its turn on, it settles with its change.
+	*/
+	startTestLevel(options) {
+		const signal = options?.signal;
+		let waiting = true;
+		const start = () => this.#enqueue(() => {
+			if (signal?.aborted) return;
+			waiting = false;
+			const fixture = this.#fixtures.at(-1);
+			return fixture && this.#startInFixture(fixture, options);
+		});
+		return signal ? settleUnlessAborted(start, signal, () => waiting) : start();
+	}
+	/**
+	* Closes every fixture, including those still opening, rejecting with the failures of all of them.
+	*
+	* Unlike closing a fixture, it closes every opening, including one started after a closing of the stack was requested, since nothing may stay open.
+	*/
+	close() {
+		return this.#closeAfterOpenings(() => this.#enqueue(() => {
+			const root = this.#fixtures[0];
+			return root && this.#closeFixture(root);
+		}));
+	}
+	/**
+	* Closes the fixtures still opening and runs `closeStack`, rejecting with the failures of all of them.
+	*
+	* A seed that never settles holds the queue of the fixture stack, so closing is requested for every opening before `closeStack` queues its change, and the rollback does not wait for the seeds.
+	*/
+	async #closeAfterOpenings(closeStack) {
+		const closings = [];
+		for (const closeOpening of this.#openings) closings.push(closeOpening());
+		closings.push(closeStack());
+		let rejection;
+		for (const closing of await Promise.allSettled(closings)) if (closing.status === "rejected") rejection = suppress(closing.reason, rejection, "Closing a test fixture failed");
+		if (rejection) throw rejection.error;
+	}
+	/**
+	* Runs `seed` in a savepoint of a fixture that is released when it resolves, returning its result or rejection.
+	*
+	* The savepoint has its own context, so late code of `seed` cannot reach the fixture after it ends.
+	*/
+	async #seedFixture(fixture, seed) {
+		try {
+			return await runLevel(this.#storage, await startNestedLevel(fixture, false), seed, true);
+		} catch (error) {
+			return { rejection: { error } };
+		}
+	}
+	/** Closes an opened fixture as a change of the fixture stack. */
+	async #closeFixture(fixture) {
+		const index = this.#fixtures.indexOf(fixture);
+		if (index < 0) return;
+		let rejection;
+		try {
+			rejection = await this.#endFixture(fixture);
+		} finally {
+			this.#fixtures.length = index;
+		}
+		if (rejection) throw rejection.error;
+	}
+	/** Rolls back a fixture and releases the connection of the first one, returning the error to reject with. */
+	async #endFixture(fixture) {
+		const { rejection } = await endLevel(fixture, false);
+		if (!fixture.parent) await releaseConnection(fixture.connection, this.#onReleaseError);
+		return rejection;
+	}
+	/** Runs a change of the fixture stack after the earlier ones. */
+	#enqueue(transition) {
+		const result = this.#transitions.then(transition);
+		this.#transitions = result.catch(() => {});
+		return result;
+	}
+	/** Starts the first test fixture: a transaction at `isolation` on a reserved connection. */
+	async #beginFixture(isolation) {
+		const connection = await this.#driver.acquire();
+		try {
+			await connection.execute(getBeginStatement(isolation));
+		} catch (error) {
+			await releaseConnection(connection, this.#onReleaseError);
+			throw error;
+		}
+		return createLevel(connection, void 0, false, isolation);
+	}
+	/**
+	* Starts a nested level of a test fixture with `options`, preempting its active one.
+	*
+	* A fixture runs one nested level at a time, so a new one ends the previous one, such as a test that timed out.
+	* A level whose `signal` aborts while it preempts rejects with its reason instead of starting, and a failure to start after the abort suppresses the reason.
+	*/
+	async #startInFixture(fixture, options) {
+		const signal = options?.signal;
+		if (fixture.child) {
+			const cleanup = await endLevel(fixture.child, false, "preemption");
+			if (cleanup.rejection) throw suppressAbortReason(new Error("Cannot start a level of the test fixture: ending its active level failed", { cause: cleanup.rejection.error }), signal);
+		}
+		const unavailable = createUnavailableError(fixture, "start a level of the test fixture");
+		if (unavailable) throw suppressAbortReason(unavailable, signal);
+		signal?.throwIfAborted();
+		return startNestedLevel(fixture, false, options);
+	}
+};
+// src/error-condition-codes.ts
+/**
+* Condition names of the SQLSTATE codes of PostgreSQL errors, by code: the codes of type `E` with a condition name, which PL/pgSQL takes in `EXCEPTION WHEN`, under the headings of their classes.
+*
+* A code that ends in `000` is the condition of its class.
+* A few names have two codes, such as `null_value_not_allowed`.
+*/
+const conditionsByCode = {
+	"03000": "sql_statement_not_yet_complete",
+	"08000": "connection_exception",
+	"08003": "connection_does_not_exist",
+	"08006": "connection_failure",
+	"08001": "sqlclient_unable_to_establish_sqlconnection",
+	"08004": "sqlserver_rejected_establishment_of_sqlconnection",
+	"08007": "transaction_resolution_unknown",
+	"08P01": "protocol_violation",
+	"09000": "triggered_action_exception",
+	"0A000": "feature_not_supported",
+	"0B000": "invalid_transaction_initiation",
+	"0F000": "locator_exception",
+	"0F001": "invalid_locator_specification",
+	"0L000": "invalid_grantor",
+	"0LP01": "invalid_grant_operation",
+	"0P000": "invalid_role_specification",
+	"0Z000": "diagnostics_exception",
+	"0Z002": "stacked_diagnostics_accessed_without_active_handler",
+	"10608": "invalid_argument_for_xquery",
+	"20000": "case_not_found",
+	"21000": "cardinality_violation",
+	"22000": "data_exception",
+	"2202E": "array_subscript_error",
+	"22021": "character_not_in_repertoire",
+	"22008": "datetime_field_overflow",
+	"22012": "division_by_zero",
+	"22005": "error_in_assignment",
+	"2200B": "escape_character_conflict",
+	"22022": "indicator_overflow",
+	"22015": "interval_field_overflow",
+	"2201E": "invalid_argument_for_logarithm",
+	"22014": "invalid_argument_for_ntile_function",
+	"22016": "invalid_argument_for_nth_value_function",
+	"2201F": "invalid_argument_for_power_function",
+	"2201G": "invalid_argument_for_width_bucket_function",
+	"22018": "invalid_character_value_for_cast",
+	"22007": "invalid_datetime_format",
+	"22019": "invalid_escape_character",
+	"2200D": "invalid_escape_octet",
+	"22025": "invalid_escape_sequence",
+	"22P06": "nonstandard_use_of_escape_character",
+	"22010": "invalid_indicator_parameter_value",
+	"22023": "invalid_parameter_value",
+	"22013": "invalid_preceding_or_following_size",
+	"2201B": "invalid_regular_expression",
+	"2201W": "invalid_row_count_in_limit_clause",
+	"2201X": "invalid_row_count_in_result_offset_clause",
+	"2202H": "invalid_tablesample_argument",
+	"2202G": "invalid_tablesample_repeat",
+	"22009": "invalid_time_zone_displacement_value",
+	"2200C": "invalid_use_of_escape_character",
+	"2200G": "most_specific_type_mismatch",
+	"22004": "null_value_not_allowed",
+	"22002": "null_value_no_indicator_parameter",
+	"22003": "numeric_value_out_of_range",
+	"2200H": "sequence_generator_limit_exceeded",
+	"22026": "string_data_length_mismatch",
+	"22001": "string_data_right_truncation",
+	"22011": "substring_error",
+	"22027": "trim_error",
+	"22024": "unterminated_c_string",
+	"2200F": "zero_length_character_string",
+	"22P01": "floating_point_exception",
+	"22P02": "invalid_text_representation",
+	"22P03": "invalid_binary_representation",
+	"22P04": "bad_copy_file_format",
+	"22P05": "untranslatable_character",
+	"2200L": "not_an_xml_document",
+	"2200M": "invalid_xml_document",
+	"2200N": "invalid_xml_content",
+	"2200S": "invalid_xml_comment",
+	"2200T": "invalid_xml_processing_instruction",
+	"22030": "duplicate_json_object_key_value",
+	"22031": "invalid_argument_for_sql_json_datetime_function",
+	"22032": "invalid_json_text",
+	"22033": "invalid_sql_json_subscript",
+	"22034": "more_than_one_sql_json_item",
+	"22035": "no_sql_json_item",
+	"22036": "non_numeric_sql_json_item",
+	"22037": "non_unique_keys_in_a_json_object",
+	"22038": "singleton_sql_json_item_required",
+	"22039": "sql_json_array_not_found",
+	"2203A": "sql_json_member_not_found",
+	"2203B": "sql_json_number_not_found",
+	"2203C": "sql_json_object_not_found",
+	"2203D": "too_many_json_array_elements",
+	"2203E": "too_many_json_object_members",
+	"2203F": "sql_json_scalar_required",
+	"2203G": "sql_json_item_cannot_be_cast_to_target_type",
+	"23000": "integrity_constraint_violation",
+	"23001": "restrict_violation",
+	"23502": "not_null_violation",
+	"23503": "foreign_key_violation",
+	"23505": "unique_violation",
+	"23514": "check_violation",
+	"23P01": "exclusion_violation",
+	"24000": "invalid_cursor_state",
+	"25000": "invalid_transaction_state",
+	"25001": "active_sql_transaction",
+	"25002": "branch_transaction_already_active",
+	"25008": "held_cursor_requires_same_isolation_level",
+	"25003": "inappropriate_access_mode_for_branch_transaction",
+	"25004": "inappropriate_isolation_level_for_branch_transaction",
+	"25005": "no_active_sql_transaction_for_branch_transaction",
+	"25006": "read_only_sql_transaction",
+	"25007": "schema_and_data_statement_mixing_not_supported",
+	"25P01": "no_active_sql_transaction",
+	"25P02": "in_failed_sql_transaction",
+	"25P03": "idle_in_transaction_session_timeout",
+	"25P04": "transaction_timeout",
+	"26000": "invalid_sql_statement_name",
+	"27000": "triggered_data_change_violation",
+	"28000": "invalid_authorization_specification",
+	"28P01": "invalid_password",
+	"2B000": "dependent_privilege_descriptors_still_exist",
+	"2BP01": "dependent_objects_still_exist",
+	"2D000": "invalid_transaction_termination",
+	"2F000": "sql_routine_exception",
+	"2F005": "function_executed_no_return_statement",
+	"2F002": "modifying_sql_data_not_permitted",
+	"2F003": "prohibited_sql_statement_attempted",
+	"2F004": "reading_sql_data_not_permitted",
+	"34000": "invalid_cursor_name",
+	"38000": "external_routine_exception",
+	"38001": "containing_sql_not_permitted",
+	"38002": "modifying_sql_data_not_permitted",
+	"38003": "prohibited_sql_statement_attempted",
+	"38004": "reading_sql_data_not_permitted",
+	"39000": "external_routine_invocation_exception",
+	"39001": "invalid_sqlstate_returned",
+	"39004": "null_value_not_allowed",
+	"39P01": "trigger_protocol_violated",
+	"39P02": "srf_protocol_violated",
+	"39P03": "event_trigger_protocol_violated",
+	"3B000": "savepoint_exception",
+	"3B001": "invalid_savepoint_specification",
+	"3D000": "invalid_catalog_name",
+	"3F000": "invalid_schema_name",
+	"40000": "transaction_rollback",
+	"40002": "transaction_integrity_constraint_violation",
+	"40001": "serialization_failure",
+	"40003": "statement_completion_unknown",
+	"40P01": "deadlock_detected",
+	"42000": "syntax_error_or_access_rule_violation",
+	"42601": "syntax_error",
+	"42501": "insufficient_privilege",
+	"42846": "cannot_coerce",
+	"42803": "grouping_error",
+	"42P20": "windowing_error",
+	"42P19": "invalid_recursion",
+	"42830": "invalid_foreign_key",
+	"42602": "invalid_name",
+	"42622": "name_too_long",
+	"42939": "reserved_name",
+	"42804": "datatype_mismatch",
+	"42P18": "indeterminate_datatype",
+	"42P21": "collation_mismatch",
+	"42P22": "indeterminate_collation",
+	"42809": "wrong_object_type",
+	"428C9": "generated_always",
+	"42703": "undefined_column",
+	"42883": "undefined_function",
+	"42P01": "undefined_table",
+	"42P02": "undefined_parameter",
+	"42704": "undefined_object",
+	"42701": "duplicate_column",
+	"42P03": "duplicate_cursor",
+	"42P04": "duplicate_database",
+	"42723": "duplicate_function",
+	"42P05": "duplicate_prepared_statement",
+	"42P06": "duplicate_schema",
+	"42P07": "duplicate_table",
+	"42712": "duplicate_alias",
+	"42710": "duplicate_object",
+	"42702": "ambiguous_column",
+	"42725": "ambiguous_function",
+	"42P08": "ambiguous_parameter",
+	"42P09": "ambiguous_alias",
+	"42P10": "invalid_column_reference",
+	"42611": "invalid_column_definition",
+	"42P11": "invalid_cursor_definition",
+	"42P12": "invalid_database_definition",
+	"42P13": "invalid_function_definition",
+	"42P14": "invalid_prepared_statement_definition",
+	"42P15": "invalid_schema_definition",
+	"42P16": "invalid_table_definition",
+	"42P17": "invalid_object_definition",
+	"44000": "with_check_option_violation",
+	"53000": "insufficient_resources",
+	"53100": "disk_full",
+	"53200": "out_of_memory",
+	"53300": "too_many_connections",
+	"53400": "configuration_limit_exceeded",
+	"54000": "program_limit_exceeded",
+	"54001": "statement_too_complex",
+	"54011": "too_many_columns",
+	"54023": "too_many_arguments",
+	"55000": "object_not_in_prerequisite_state",
+	"55006": "object_in_use",
+	"55P02": "cant_change_runtime_param",
+	"55P03": "lock_not_available",
+	"55P04": "unsafe_new_enum_value_usage",
+	"57000": "operator_intervention",
+	"57014": "query_canceled",
+	"57P01": "admin_shutdown",
+	"57P02": "crash_shutdown",
+	"57P03": "cannot_connect_now",
+	"57P04": "database_dropped",
+	"57P05": "idle_session_timeout",
+	"58000": "system_error",
+	"58030": "io_error",
+	"58P01": "undefined_file",
+	"58P02": "duplicate_file",
+	"58P03": "file_name_too_long",
+	F0000: "config_file_error",
+	F0001: "lock_file_exists",
+	HV000: "fdw_error",
+	HV005: "fdw_column_name_not_found",
+	HV002: "fdw_dynamic_parameter_value_needed",
+	HV010: "fdw_function_sequence_error",
+	HV021: "fdw_inconsistent_descriptor_information",
+	HV024: "fdw_invalid_attribute_value",
+	HV007: "fdw_invalid_column_name",
+	HV008: "fdw_invalid_column_number",
+	HV004: "fdw_invalid_data_type",
+	HV006: "fdw_invalid_data_type_descriptors",
+	HV091: "fdw_invalid_descriptor_field_identifier",
+	HV00B: "fdw_invalid_handle",
+	HV00C: "fdw_invalid_option_index",
+	HV00D: "fdw_invalid_option_name",
+	HV090: "fdw_invalid_string_length_or_buffer_length",
+	HV00A: "fdw_invalid_string_format",
+	HV009: "fdw_invalid_use_of_null_pointer",
+	HV014: "fdw_too_many_handles",
+	HV001: "fdw_out_of_memory",
+	HV00P: "fdw_no_schemas",
+	HV00J: "fdw_option_name_not_found",
+	HV00K: "fdw_reply_handle",
+	HV00Q: "fdw_schema_not_found",
+	HV00R: "fdw_table_not_found",
+	HV00L: "fdw_unable_to_create_execution",
+	HV00M: "fdw_unable_to_create_reply",
+	HV00N: "fdw_unable_to_establish_connection",
+	P0000: "plpgsql_error",
+	P0001: "raise_exception",
+	P0002: "no_data_found",
+	P0003: "too_many_rows",
+	P0004: "assert_failure",
+	XX000: "internal_error",
+	XX001: "data_corrupted",
+	XX002: "index_corrupted"
+};
+// src/error-condition.ts
+/**
+* Tells whether `error` is a `QueryError` of `condition`, including a `QueryError` of another copy of kern-db.
+*
+* The condition of a class, such as `integrity_constraint_violation`, matches every error of its class, as in PL/pgSQL.
+*/
+function isQueryError(error, condition) {
+	if (!(error instanceof QueryError)) return false;
+	const conditions = conditionsByCode;
+	return conditions[error.code] === condition || conditions[`${error.code.slice(0, 2)}000`] === condition;
+}
+// src/transaction/session.ts
+const beginStatement = /* @__PURE__ */ createStatement("BEGIN");
+/**
+* Creates the state of a `starting` session on `connection`.
+*
+* It watches its connection for a `ConnectionError`, after which it accepts no statements: the connection may be lost, and a statement that a client ran on a new connection would run without the settings of the session.
+*/
+function createSessionLevel(connection) {
+	const watch = new ConnectionWatch(connection);
+	return {
+		connection: watch,
+		watch,
+		parent: void 0,
+		depth: 0,
+		session: true,
+		savepoint: false,
+		inTransaction: false,
+		state: "starting",
+		child: void 0,
+		rollbackOnly: void 0,
+		cleanup: void 0,
+		endedBy: void 0,
+		restore: void 0,
+		isolation: void 0,
+		locks: void 0
+	};
+}
+/**
+* Releases the advisory locks that an ended session took, restores the settings that it changed, and returns its connection to the driver.
+*
+* A connection whose locks fail to release or whose settings fail to restore is left in a transaction, so that the driver closes it rather than returning it to the pool with them, and so is one whose statement of `tryLock` failed, which may hold a lock that the session does not know of.
+* The failure does not change the result or the error of the session, which is decided before.
+* A failed release of the locks or restore of the settings goes to `onReleaseError`, or to `console.error` without one, unless it is a `ConnectionError`, which a lost connection gives, with nothing to restore.
+*/
+async function releaseSession(level, onReleaseError) {
+	if (!await restoreSession(level, onReleaseError)) await leaveInTransaction(level.connection);
+	await releaseConnection(level.connection, onReleaseError);
+}
+/**
+* Releases the advisory locks of an ended session and then restores its settings, and tells whether its connection can return to the pool.
+*
+* It sends them also after a `ConnectionError`: a client that refused a statement without sending it keeps the connection, which the driver then returns to the pool.
+*/
+async function restoreSession(level, onReleaseError) {
+	const { connection, locks, restore } = level;
+	if (locks) {
+		const keys = await locks.settle();
+		if (!keys) return false;
+		if (keys.length > 0 && !await executeRestoring(connection, createUnlockStatement(keys), "Releasing the advisory locks of a session failed", onReleaseError)) return false;
+	}
+	return !restore || await executeRestoring(connection, restore, "Restoring the settings of a session failed", onReleaseError);
+}
+/** Executes a statement that restores the state of the connection of an ended session, and tells whether it completed, reporting a failure other than a `ConnectionError` with `message`. */
+async function executeRestoring(connection, statement, message, onReleaseError) {
+	try {
+		await connection.execute(statement);
+		return true;
+	} catch (error) {
+		if (!(error instanceof ConnectionError)) reportReleaseError(new Error(message, { cause: error }), onReleaseError);
+		return false;
+	}
+}
+/**
+* Leaves `connection` in a transaction or failed, so that the driver closes it on release, which the driver contract requires for a connection that is not idle or that failed with a `ConnectionError`.
+*
+* It sends `BEGIN` again while PostgreSQL rejects it and may leave the connection idle, such as when a cancel request hits the statement, since such a connection would return to the pool.
+* A client that refuses `BEGIN` without sending it, with a `ConnectionError`, keeps an idle connection that the driver returns to the pool: kern-db cannot tell that from a lost connection, on which sending `BEGIN` again would never end.
+*/
+async function leaveInTransaction(connection) {
+	for (;;) try {
+		await connection.execute(beginStatement);
+		return;
+	} catch (error) {
+		if (!(error instanceof QueryError) || isQueryError(error, "in_failed_sql_transaction")) return;
+	}
+}
+// src/transaction/coordinator.ts
+/**
+* Routes statements and scripts to the ambient transaction or session of the current async context or to the pool.
+*
+* This is the only place that decides which connection executes a statement.
+*/
+var TransactionCoordinator = class {
+	driver;
+	#storage = new AsyncLocalStorage();
+	#fixtures;
+	#onReleaseError;
+	/** Closing of the database, set by the first `close`; from then on, operations outside a transaction reject. */
+	#closed;
+	/** Rejects statements and transactions outside a test transaction or the seed of a test fixture instead of running them on the pool. */
+	test;
+	constructor(driver, { test = false, onReleaseError } = {}) {
+		this.driver = driver;
+		this.test = test;
+		this.#onReleaseError = onReleaseError;
+		this.#fixtures = new TestFixtureStack(driver, this.#storage, onReleaseError);
+	}
+	execute(statement) {
+		const target = this.#route("execute a query");
+		return target instanceof Error ? Promise.reject(target) : target.execute(statement);
+	}
+	/** Executes a script of statements without parameters where `execute` executes a statement. */
+	executeScript(text) {
+		const target = this.#route("execute a script");
+		return target instanceof Error ? Promise.reject(target) : target.executeScript(text);
+	}
+	/** Returns the connection of the ambient transaction or session, or the driver of the pool, that runs `operation`, or the error that rejects it. */
+	#route(operation) {
+		const level = this.#storage.getStore();
+		if (!level) {
+			if (this.#closed) return createDatabaseClosedError(operation);
+			return this.test ? new Error(describeOutsideTest(operation)) : this.driver;
+		}
+		return createUnavailableError(level, operation) ?? level.connection;
+	}
+	/**
+	* Runs `callback` in a transaction that commits when it resolves and rolls back when it rejects, with the settings of `options`.
+	*
+	* Inside a transaction, it runs `callback` in a savepoint nested in it, which restores the settings it changed when it ends, and rejects without the savepoint when the isolation level of `options` differs from that of the transaction.
+	* Inside a session, it starts the transaction on the connection of the session.
+	* A failed cleanup after an error rejects with a `SuppressedError` that keeps the original error in its `suppressed` chain.
+	* A transaction that it starts rolls back instead of `COMMIT` after a `ConnectionError` on its connection, and when it rejects after such an error, also of `COMMIT`, it rejects with `TransactionConnectionError` of the phase of the failure, whose `cause` is the error it would reject with otherwise.
+	*/
+	transaction(callback, options) {
+		const levelOptions = options && {
+			settings: getLevelSettings(options),
+			isolation: options.isolation
+		};
+		const parent = this.#storage.getStore();
+		if (parent) return parent.session ? this.#runInSession(parent, callback, levelOptions) : this.#runNested(parent, callback, true, levelOptions);
+		if (this.#closed) return Promise.reject(createDatabaseClosedError("start a transaction"));
+		return this.test ? Promise.reject(new Error(describeOutsideTest("start a transaction"))) : this.#runRoot(callback, true, levelOptions);
+	}
+	/**
+	* Runs `callback` in the current transaction, or in a new transaction outside of one.
+	*
+	* Joining starts no savepoint, so a rejection of `callback` does not undo its changes.
+	* It rejects without calling `callback` when the current level accepts no statements, as a nested transaction would.
+	*/
+	async ensureTransaction(callback) {
+		const level = this.#storage.getStore();
+		if (!level?.inTransaction) return this.transaction(callback);
+		const unavailable = createUnavailableError(level, "join the transaction");
+		if (unavailable) throw unavailable;
+		return callback();
+	}
+	/**
+	* Tells whether the current async context runs in a transaction of `transaction`.
+	*
+	* A test transaction and the seed of a test fixture are not transactions, unless they run inside one, so that code under test behaves as in production.
+	*/
+	isInTransaction() {
+		return this.#storage.getStore()?.inTransaction ?? false;
+	}
+	/**
+	* Tells whether a statement of the current async context runs in a transaction block of PostgreSQL: in a transaction, a test transaction, or the seed of a test fixture, but not in a session outside its transactions.
+	*
+	* Unlike `isInTransaction`, it counts the levels of the test helpers, since PostgreSQL rejects a statement such as `CREATE INDEX CONCURRENTLY` in any transaction block.
+	*/
+	isInTransactionBlock() {
+		const level = this.#storage.getStore();
+		return level !== void 0 && !level.session;
+	}
+	/**
+	* Runs `callback` in a session: on one reserved connection outside a transaction, with the settings of `options` until it ends.
+	*
+	* Statements of the callback run on the connection, each in a transaction of its own, and `transaction` starts a transaction on it.
+	* It rejects without calling `callback` inside a transaction, a test transaction, or another session, and on a coordinator created for tests, whose statements all run in test transactions.
+	* A rejection of `callback` undoes nothing.
+	* After a `ConnectionError` on its connection, the session accepts no more statements.
+	*/
+	session(callback, options) {
+		const parent = this.#storage.getStore();
+		if (parent) return Promise.reject(/* @__PURE__ */ new Error(parent.session ? "Cannot start a session inside a session" : "Cannot start a session inside a transaction, also a test transaction: the statements of a session run outside a transaction"));
+		if (this.#closed) return Promise.reject(createDatabaseClosedError("start a session"));
+		if (this.test) return Promise.reject(/* @__PURE__ */ new Error("Cannot start a session: the database was created with test: true, so its statements run in test transactions, and the statements of a session run outside a transaction"));
+		return this.#runSession(callback, getLevelSettings(options));
+	}
+	/**
+	* Takes the advisory lock of `key` until the transaction of `transaction` ends, waiting while another transaction or session holds it.
+	*
+	* It rejects without a statement outside such a transaction, where the lock would end with its statement, and in a session outside its transactions, where the waiting statement keeps a snapshot that `CREATE INDEX CONCURRENTLY` in the session that holds the lock waits for.
+	*/
+	async lock(key) {
+		const level = this.#storage.getStore();
+		if (!level?.inTransaction) throw new Error(level?.session ? "Cannot wait for an advisory lock in a session outside a transaction: the waiting statement would keep a snapshot that CREATE INDEX CONCURRENTLY in the session holding the lock waits for; take it with tryLock, which does not wait" : "Cannot take an advisory lock outside a transaction, where it would end with its statement; a test transaction alone does not count");
+		await this.execute(createLockStatement(key));
+	}
+	/**
+	* Takes the advisory lock of `key` unless another transaction or session holds it, and tells whether it took it: until the transaction of `transaction` ends, or in a session outside its transactions, until the session ends.
+	*
+	* It rejects without a statement outside both, where the lock would end with its statement.
+	* A session takes a key that it holds without a statement, and releases its locks when it ends.
+	*/
+	async tryLock(key) {
+		const level = this.#storage.getStore();
+		if (level?.inTransaction) return isTaken(await this.execute(createTryLockStatement(key)));
+		if (!level?.session) throw new Error("Cannot take an advisory lock outside a transaction or a session, where it would end with its statement; a test transaction alone does not count");
+		const unavailable = createUnavailableError(level, "take an advisory lock");
+		if (unavailable) throw unavailable;
+		return (level.locks ??= new SessionLocks()).take(level.connection, key);
+	}
+	/**
+	* Takes the advisory lock of `key` in a session outside its transactions until the session ends, calling `tryLock` again after a pause until it takes the lock.
+	*
+	* It rejects without a statement outside a session, and in a transaction, also of a session or of the test helpers, which would keep a snapshot between the attempts; in a transaction of `transaction`, `lock` waits for the lock instead.
+	* Once `signal` of `options` aborts, it makes no more attempts and rejects with its reason, unless the attempt that is running takes the lock.
+	*/
+	async pollLock(key, options) {
+		const level = this.#storage.getStore();
+		if (!level?.session) throw new Error(!level ? "Cannot poll for an advisory lock outside a session, where it would end with its statement" : level.inTransaction ? "Cannot poll for an advisory lock in a transaction, which would keep a snapshot between the attempts; take it with lock, which waits for it" : "Cannot poll for an advisory lock in a test transaction, which would keep a snapshot between the attempts; take it with lock inside transaction or ensureTransaction");
+		await pollLock(() => this.tryLock(key), options?.signal);
+	}
+	/**
+	* Runs `callback` in a transaction that always rolls back, on a coordinator created for tests.
+	*
+	* Inside a transaction, it runs `callback` in a savepoint nested in it that always rolls back.
+	* When `signal` aborts, the level stops accepting statements at once and ends without waiting for `callback`.
+	* Once the level ends, the transaction rejects with the reason of the signal.
+	* A failure to start or end the level after the abort suppresses the reason in a `SuppressedError`.
+	* Aborted while it waits for its turn in the fixture stack or for a connection, it rejects at once; after the abort, it never calls `callback`.
+	*/
+	testTransaction(callback, options) {
+		const signal = options?.signal;
+		if (!this.test) return Promise.reject(/* @__PURE__ */ new Error("testTransaction requires a database created with test: true"));
+		if (signal?.aborted) return Promise.reject(signal.reason);
+		const parent = this.#storage.getStore();
+		if (parent) return this.#runNested(parent, callback, false, options);
+		if (this.#closed) return Promise.reject(createDatabaseClosedError("start a test transaction"));
+		return this.#fixtures.startTestLevel(options).then((level) => level ? this.#runStarted(level, callback, false, signal) : this.#runRoot(callback, false, options));
+	}
+	/**
+	* Opens a test fixture: a transaction on a reserved connection, or a savepoint in the innermost open fixture, and runs `seed` in it.
+	*
+	* Test transactions started outside any transaction run in the innermost fixture.
+	* A fixture whose `seed` rejects rolls back and closes.
+	*/
+	createTestFixture(seed, options) {
+		return this.startTestFixture(seed, options).fixture;
+	}
+	/**
+	* Starts opening a test fixture, see `createTestFixture`, and returns it with a `close` that can be called before it opens.
+	*
+	* Closing before the fixture opens rejects the opening without waiting for `seed` and rolls the fixture back, so a fixture or test transaction started after `close` never nests in it, even when its `seed` never settles.
+	* Closing an open fixture also closes the fixtures opening in it.
+	*/
+	startTestFixture(seed, options) {
+		return this.#fixtures.start(seed, this.#getFixtureRefusal(), options);
+	}
+	/** Returns the error that rejects a test fixture created now, or `undefined` when it can open. */
+	#getFixtureRefusal() {
+		if (!this.test) return /* @__PURE__ */ new Error("createTestFixture requires a database created with test: true");
+		if (this.#storage.getStore()) return /* @__PURE__ */ new Error("Cannot create a test fixture inside a transaction");
+		if (this.#closed) return createDatabaseClosedError("create a test fixture");
+	}
+	/**
+	* Closes the test fixtures, including those still opening, and then the driver, which waits for the running transactions and sessions to end.
+	*
+	* A driver waits for every reserved connection, so closing it under an open fixture would wait forever.
+	* A failed closing of the driver suppresses the failures of closing the fixtures.
+	* From the first call, statements, transactions, sessions, and fixtures started outside a transaction and a session reject, while the levels already running can still end; a repeated call returns the same closing.
+	*/
+	close() {
+		const level = this.#storage.getStore();
+		if (level) return Promise.reject(/* @__PURE__ */ new Error(`Cannot close the database inside a ${level.session ? "session" : "transaction"}`));
+		this.#closed ??= this.#close();
+		return this.#closed;
+	}
+	/** Closes the test fixtures and then the driver, see `close`. */
+	async #close() {
+		let rejection;
+		try {
+			await this.#fixtures.close();
+		} catch (error) {
+			rejection = { error };
+		}
+		try {
+			await this.driver.close();
+		} catch (error) {
+			rejection = suppress(error, rejection, "Closing the driver failed");
+		}
+		if (rejection) throw rejection.error;
+	}
+	/**
+	* Runs `callback` in a level without a parent on a connection of its own: a transaction of `transaction` when it `commits`, and a test transaction otherwise.
+	*
+	* A transaction of `transaction` whose connection fails rejects with `TransactionConnectionError`.
+	*/
+	async #runRoot(callback, commits, options = noLevelOptions) {
+		const { signal } = options;
+		let connection;
+		try {
+			connection = await (signal ? acquireUnlessAborted(this.driver, signal, this.#onReleaseError) : this.driver.acquire());
+		} catch (error) {
+			throw commits && error instanceof ConnectionError ? new TransactionConnectionError("begin", { cause: error }) : error;
+		}
+		if (signal?.aborted) {
+			await releaseConnection(connection, this.#onReleaseError);
+			throw signal.reason;
+		}
+		const level = createLevel(connection, void 0, commits, options.isolation);
+		const outcome = await this.#runTransaction(level, callback, commits, options);
+		await releaseConnection(connection, this.#onReleaseError);
+		return settleTransaction(level, outcome);
+	}
+	/**
+	* Runs `callback` in a transaction of `transaction` on the connection of `session`, which rejects its own statements until the transaction ends.
+	*
+	* A transaction whose connection fails rejects with `TransactionConnectionError`, as one on a connection of its own does.
+	*/
+	async #runInSession(session, callback, options = noLevelOptions) {
+		const unavailable = createUnavailableError(session, "start a transaction");
+		if (unavailable) throw unavailable;
+		const level = createLevel(session.connection, session, true, options.isolation);
+		session.child = level;
+		return settleTransaction(level, await this.#runTransaction(level, callback, true, options));
+	}
+	/**
+	* Begins the transaction of `level`, a level that is not a savepoint, applies the settings of `options`, runs `callback` in it, and ends it.
+	*
+	* A level whose `BEGIN` fails closes, and one whose settings fail rolls back.
+	*/
+	async #runTransaction(level, callback, commits, { signal, settings, isolation }) {
+		try {
+			await level.connection.execute(getBeginStatement(isolation));
+		} catch (error) {
+			if (level.cleanup) return getEndedOutcome(level.cleanup, error);
+			closeStarting(level);
+			return { rejection: { error: suppressAbortReason(error, signal) } };
+		}
+		if (settings) try {
+			await applySettings(level, settings);
+		} catch (error) {
+			return getEndedOutcome(endLevel(level, false), error);
+		}
+		if (level.watch) level.watch.phase = "transaction";
+		return runLevel(this.#storage, level, callback, commits, signal);
+	}
+	/**
+	* Runs `callback` in a session with `settings` on a connection of its own, and restores the settings before the connection returns to the driver.
+	*
+	* A session whose settings fail to apply rejects without calling `callback`.
+	*/
+	async #runSession(callback, settings) {
+		const level = createSessionLevel(await this.driver.acquire());
+		let outcome;
+		if (settings) try {
+			await applySettings(level, settings);
+		} catch (error) {
+			level.state = "closed";
+			outcome = { rejection: { error } };
+		}
+		outcome ??= await runLevel(this.#storage, level, callback, false);
+		await releaseSession(level, this.#onReleaseError);
+		if (outcome.rejection) throw outcome.rejection.error;
+		return outcome.result;
+	}
+	async #runNested(parent, callback, commits, options) {
+		const unavailable = createUnavailableError(parent, "start a nested transaction");
+		if (unavailable) throw unavailable;
+		return this.#runStarted(await startNestedLevel(parent, commits, options), callback, commits, options?.signal);
+	}
+	/** Runs `callback` in a started level, returning its result or throwing its rejection. */
+	async #runStarted(level, callback, commits, signal) {
+		const { result, rejection } = await runLevel(this.#storage, level, callback, commits, signal);
+		if (rejection) throw rejection.error;
+		return result;
+	}
+};
+/**
+* Returns the result of the `outcome` of a transaction of `level`, a level that is not a savepoint, or throws its rejection.
+*
+* A failure of the connection decides whether the transaction may have been committed, whatever error the rejection has, so the transaction then rejects with `TransactionConnectionError` of its phase.
+*/
+function settleTransaction(level, outcome) {
+	const { rejection } = outcome;
+	if (rejection) {
+		const failure = level.watch?.failure;
+		throw failure ? new TransactionConnectionError(failure.phase, { cause: rejection.error }) : rejection.error;
+	}
+	return outcome.result;
+}
+/** Error message of an operation outside a test transaction on a coordinator created for tests. */
+function describeOutsideTest(operation) {
+	return `Cannot ${operation} outside a test transaction: the database was created with test: true, so wrap the test in testTransaction`;
+}
+/** Error of `operation` started outside a transaction after closing the database was requested. */
+function createDatabaseClosedError(operation) {
+	return /* @__PURE__ */ new Error(`Cannot ${operation}: the database is closed`);
+}
+// src/database.ts
+/** Marks a database of `createDatabase` of any copy of kern-db, which `isDatabase` of another copy recognizes. */
+const databaseBrand = /* @__PURE__ */ Symbol.for("kern-db.Database");
+/**
+* Checks whether `value` is a database of `createDatabase`, also of another copy of kern-db, such as to reject a client of PostgreSQL or a `Db` of kern-orm passed instead of a database.
+*
+* It checks the brand that `createDatabase` sets, so it rejects a spread copy of a database.
+*/
+function isDatabase(value) {
+	return typeof value === "object" && value !== null && value[databaseBrand] === true;
+}
+const coordinators = /* @__PURE__ */ new WeakMap();
+/**
+* Returns the transaction coordinator of a database of `createDatabase`, such as for the test helpers.
+*
+* It throws for another object, such as a copy of a database or a database of another copy of this module, which has no coordinator here.
+*/
+function getCoordinator(database) {
+	const coordinator = coordinators.get(database);
+	if (coordinator === void 0) throw new TypeError("The database was not created by createDatabase of this copy of the package");
+	return coordinator;
+}
+/** Creates a database over a driver. */
+function createDatabase({ driver, ...options }) {
+	const coordinator = new TransactionCoordinator(driver, options);
+	const database = {
+		async script(script, ...values) {
+			return coordinator.executeScript(typeof script === "string" ? script : compileScript(sql(script, ...values)));
+		},
+		query(strings, ...values) {
+			const fragment = sql(strings, ...values);
+			return startSqlQuery(() => compileFragment(fragment), database);
+		},
+		execute: (statement) => coordinator.execute(statement),
+		transaction: (callback, options) => coordinator.transaction(callback, options),
+		ensureTransaction: (callback) => coordinator.ensureTransaction(callback),
+		isInTransaction: () => coordinator.isInTransaction(),
+		isInTransactionBlock: () => coordinator.isInTransactionBlock(),
+		session: (callback, options) => coordinator.session(callback, options),
+		lock: (key) => coordinator.lock(key),
+		tryLock: (key) => coordinator.tryLock(key),
+		pollLock: (key, options) => coordinator.pollLock(key, options),
+		close: () => coordinator.close(),
+		[Symbol.asyncDispose]: () => coordinator.close()
+	};
+	Object.defineProperty(database, databaseBrand, { value: true });
+	coordinators.set(database, coordinator);
+	return database;
+}
+export { TransactionConnectionError as a, isQueryError as i, getCoordinator as n, isDatabase as r, createDatabase as t };