kern-orm 0.7.0 → 0.9.0

package/dist/{database-B7Kf5Q9X.mjs → database-t66EaIGE.mjs}

@@ -4222,6 +4222,131 @@ function bindSchema(schema, database, options = {}) {
 	const db = defineEntries(methods, schema.$tables, (key) => bindQuery(startQuery(schema.$tables[key], contexts[key]), db));
 	return db;
 }
+// src/execution/driver-error.ts
+/** Marks an instance of `QueryError` of any copy of kern-orm, which `instanceof QueryError` of another copy recognizes. */
+const queryErrorBrand = /* @__PURE__ */ Symbol.for("kern-orm.QueryError");
+/** Marks an instance of `ConnectionError` of any copy of kern-orm. */
+const connectionErrorBrand = /* @__PURE__ */ Symbol.for("kern-orm.ConnectionError");
+/**
+* Tells whether `value` is an instance of `errorClass`: by the brand of any copy of kern-orm for `errorClass` itself, and by the prototype chain for its subclasses.
+*
+* An application can load several copies of kern-orm, such as one of a driver, and an error of one copy is then an instance of the class of another.
+*/
+function isInstance(errorClass, root, brand, value) {
+	if (errorClass !== root) return Function.prototype[Symbol.hasInstance].call(errorClass, value);
+	return typeof value === "object" && value !== null && value[brand] === true;
+}
+/** Sets the brand of `error`, which is not enumerable, so that it does not show among the fields of the error. */
+function setBrand(error, brand) {
+	Object.defineProperty(error, brand, { value: true });
+}
+/**
+* Error of a statement that PostgreSQL rejected, such as for a violated constraint; the connection of the statement stays usable.
+*
+* A driver whose client gives the severity of an error only in the language of the server, such as node-postgres, tells such an error by its SQLSTATE when the server translates its messages.
+* An error that ends the session with a code that a statement also gets, such as `40001` of a conflict with recovery on a replica, then rejects with `QueryError`, and the next statement on the connection with `ConnectionError`.
+*/
+var QueryError = class QueryError extends Error {
+	name = "QueryError";
+	/** SQLSTATE of the error, such as `23505` for a violated unique constraint. */
+	code;
+	/** Name of the constraint that the statement violated, if any. */
+	constraint;
+	constructor(message, fields) {
+		super(message, "cause" in fields ? { cause: fields.cause } : void 0);
+		this.code = fields.code;
+		this.constraint = fields.constraint;
+		setBrand(this, queryErrorBrand);
+	}
+	/** Tells whether `value` is an instance of the class, including one of `QueryError` of another copy of kern-orm. */
+	static [Symbol.hasInstance](value) {
+		return isInstance(this, QueryError, queryErrorBrand, value);
+	}
+};
+/**
+* Error of a statement or connection that failed for another reason than PostgreSQL rejecting a statement, such as a lost connection, a timeout of the client, or a closed driver.
+*
+* The statement may have run or not, and its connection may be lost or in an unknown state of its transaction.
+*/
+var ConnectionError = class ConnectionError extends Error {
+	name = "ConnectionError";
+	constructor(message, options) {
+		super(message, options);
+		setBrand(this, connectionErrorBrand);
+	}
+	/** Tells whether `value` is an instance of the class, including one of `ConnectionError` of another copy of kern-orm. */
+	static [Symbol.hasInstance](value) {
+		return isInstance(this, ConnectionError, connectionErrorBrand, value);
+	}
+};
+/** SQLSTATE of five digits or uppercase letters; clients also give codes of their own, such as `ECONNRESET` or `CONNECTION_CLOSED`. */
+const sqlState = /^[0-9A-Z]{5}$/;
+/** SQLSTATE of an error that ends the session: of the classes of connection exceptions, authorization, operator intervention, and internal errors, and the timeouts of an idle transaction and of a transaction. */
+const sessionEndingCode = /^(?:08|28|57P|XX|25P03$|25P04$)/;
+/** Tells whether an error of the server of `severity` and SQLSTATE `code` ends its session. */
+function isSessionEnding(severity, code) {
+	if (severity === "ERROR") return false;
+	if (severity === "FATAL" || severity === "PANIC") return true;
+	return sessionEndingCode.test(code);
+}
+/**
+* Classifies an error of a client as `QueryError` or `ConnectionError`, by the fields of the PostgreSQL error it carries, for a driver to reject with.
+*
+* An error that kern-orm has already classified returns as it is.
+* An error without a severity or a SQLSTATE, such as of a client that lost its connection, is a `ConnectionError`, and so is one of severity `FATAL` or `PANIC`, which ends the session.
+* An error of severity `ERROR` is a `QueryError`.
+* With a translated severity, the SQLSTATE tells an error that ends the session, so a few errors of other codes that end it give `QueryError`.
+*/
+function toDriverError(error, fields) {
+	if (error instanceof QueryError || error instanceof ConnectionError) return error;
+	const message = error instanceof Error ? error.message : String(error);
+	const { severity, code, constraint } = fields ?? {};
+	if (typeof severity !== "string" || typeof code !== "string" || !sqlState.test(code)) return new ConnectionError(message, { cause: error });
+	if (isSessionEnding(severity, code)) return new ConnectionError(message, { cause: error });
+	return new QueryError(message, {
+		code,
+		constraint: typeof constraint === "string" ? constraint : void 0,
+		cause: error
+	});
+}
+// src/execution/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-orm: onReleaseError failed", handlerFailure.error);
+		console.error("kern-orm: releasing a connection failed", error);
+	} catch {}
+}
 // src/execution/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`.
@@ -4260,14 +4385,78 @@ function settleUnlessAborted(start, signal, abort, discard) {
 /**
 * 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 is ignored.
+* 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) {
+function acquireUnlessAborted(driver, signal, onReleaseError) {
 	if (signal.aborted) return Promise.reject(signal.reason);
-	return settleUnlessAborted(() => driver.acquire(), signal, () => true, (connection) => {
-		Promise.resolve().then(() => connection.release()).catch(() => {});
-	});
-}
+	return settleUnlessAborted(() => driver.acquire(), signal, () => true, (connection) => void releaseConnection(connection, onReleaseError));
+}
+// src/execution/transaction/connection-loss.ts
+/** Marks an instance of `TransactionConnectionError` of any copy of kern-orm. */
+const transactionConnectionErrorBrand = /* @__PURE__ */ Symbol.for("kern-orm.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-orm. */
+	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/execution/transaction/settings.ts
 /** Settings of a level of `transaction` with `options`, or `undefined` when it has none. */
 function getLevelSettings(options) {
@@ -4310,19 +4499,38 @@ function createSettingStatement(settings) {
 	return createStatement(text, parameters);
 }
 // src/execution/transaction/level.ts
-/** Statement that starts the transaction of a level without a parent: a transaction of `transaction`, a test transaction, or the first test fixture. */
+/** Options of a level started without options, shared so that such a start allocates none. */
+const noLevelOptions = {};
 const beginStatement = /* @__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 without a parent, 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;
+}
+/**
 * Creates the state of a `starting` level on `connection`, nested in `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` without a parent watches its connection for a `ConnectionError`.
+* `isolation` is the isolation level that a level without a parent begins with.
 */
-function createLevel(connection, parent, transaction) {
+function createLevel(connection, parent, transaction, isolation) {
+	const watch = transaction && !parent ? new ConnectionWatch(connection) : void 0;
 	return {
-		connection,
+		connection: watch ?? connection,
+		watch,
 		parent,
 		depth: parent ? parent.depth + 1 : 0,
 		inTransaction: transaction || (parent?.inTransaction ?? false),
@@ -4331,19 +4539,32 @@ function createLevel(connection, parent, transaction) {
 		rollbackOnly: void 0,
 		cleanup: void 0,
 		endedBy: void 0,
-		restore: void 0
+		restore: void 0,
+		isolation: parent ? parent.isolation : isolation
 	};
 }
 /**
-* Reserves a nested level of `parent`, sends its `SAVEPOINT`, and applies its `settings`, rejecting when one of them fails.
+* 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) {
+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) {
@@ -4361,6 +4582,30 @@ async function startNestedLevel(parent, transaction, signal, settings) {
 	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.
@@ -4388,8 +4633,7 @@ async function runLevel(storage, level, callback, commits, signal) {
 	const cleanup = await endLevel(level, commits && !rejection);
 	return {
 		result,
-		rejection: combineRejections(rejection, cleanup),
-		failure: cleanup.failure
+		rejection: combineRejections(rejection, cleanup)
 	};
 }
 /**
@@ -4400,6 +4644,11 @@ async function runLevel(storage, level, callback, commits, signal) {
 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;
@@ -4407,28 +4656,33 @@ function endLevel(level, commit, endedBy) {
 async function cleanUpLevel(level, commit, nested) {
 	const nestedCleanup = await nested;
 	const { parent } = level;
-	const cleanup = parent ? await endSavepoint(level, commit && !level.rollbackOnly) : await endTransaction(level.connection, commit);
+	const cleanup = parent ? await endSavepoint(level, commit && !level.rollbackOnly) : await endTransaction(level, commit);
 	level.state = "closed";
 	if (parent) {
 		if (parent.child === level) parent.child = void 0;
 		parent.rollbackOnly ??= cleanup.rejection;
 	}
-	return {
-		rejection: combineRejections(nestedCleanup?.rejection, cleanup),
-		failure: cleanup.failure
-	};
+	return { rejection: combineRejections(nestedCleanup?.rejection, cleanup) };
 }
-/** Ends a transaction with `COMMIT` or `ROLLBACK`. */
-async function endTransaction(connection, commit) {
+/**
+* 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 {
-		const { command } = await connection.execute(commit ? commitStatement : rollbackStatement);
-		if (commit && command !== "COMMIT") return { rejection: { error: /* @__PURE__ */ new Error("Transaction was rolled back: a statement in it failed") } };
-		return {};
+		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: { error },
-			failure: { error }
-		};
+		return { rejection: suppress(error, lost, "Transaction rollback failed") };
 	}
 }
 /**
@@ -4451,7 +4705,7 @@ async function endSavepoint(level, commit) {
 function getSavepointName(level) {
 	return `kern_${level.depth}`;
 }
-/** Closes a nested level whose `SAVEPOINT` failed, freeing its parent for other statements. */
+/** Closes a nested level whose `SAVEPOINT` 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;
@@ -4472,20 +4726,7 @@ function createClosedError(level, rejection) {
 }
 /** 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) {
-	const ended = await cleanup;
-	return {
-		rejection: combineRejections({ error }, ended),
-		failure: ended.failure
-	};
-}
-/** Returns the connection of a transaction to the driver, keeping a failed release as a rejection that suppresses `rejection`. */
-async function releaseConnection(connection, failure, rejection) {
-	try {
-		await connection.release(failure);
-		return rejection;
-	} catch (error) {
-		return suppress(error, rejection, "Releasing the transaction connection failed");
-	}
+	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) {
@@ -4503,6 +4744,7 @@ function suppress(error, earlier, message) {
 /** 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. */
@@ -4522,16 +4764,17 @@ var TestFixtureStack = class {
 	* 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) {
+	constructor(driver, storage, onReleaseError) {
 		this.#driver = driver;
 		this.#storage = storage;
+		this.#onReleaseError = onReleaseError;
 	}
 	/**
-	* Starts opening a test fixture, see `startTestFixture` of the coordinator, or, given `refusal`, returns a fixture that rejects with it.
+	* 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) {
+	start(seed, refusal, options) {
 		let level;
 		let closeRequested = false;
 		const closing = Promise.withResolvers();
@@ -4570,7 +4813,7 @@ var TestFixtureStack = class {
 		const open = async () => {
 			if (closeRequested) return;
 			const parent = this.#fixtures.at(-1);
-			const started = parent ? await this.#startInFixture(parent) : await this.#beginFixture();
+			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) {
@@ -4614,13 +4857,14 @@ var TestFixtureStack = class {
 	* 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(signal) {
+	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, signal);
+			return fixture && this.#startInFixture(fixture, options);
 		});
 		return signal ? settleUnlessAborted(start, signal, () => waiting) : start();
 	}
@@ -4674,8 +4918,9 @@ var TestFixtureStack = class {
 	}
 	/** Rolls back a fixture and releases the connection of the first one, returning the error to reject with. */
 	async #endFixture(fixture) {
-		const cleanup = await endLevel(fixture, false);
-		return fixture.parent ? cleanup.rejection : releaseConnection(fixture.connection, cleanup.failure, cleanup.rejection);
+		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) {
@@ -4683,23 +4928,25 @@ var TestFixtureStack = class {
 		this.#transitions = result.catch(() => {});
 		return result;
 	}
-	/** Starts the first test fixture: a transaction on a reserved connection. */
-	async #beginFixture() {
+	/** 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(beginStatement);
+			await connection.execute(getBeginStatement(isolation));
 		} catch (error) {
-			throw (await releaseConnection(connection, { error }, { error })).error;
+			await releaseConnection(connection, this.#onReleaseError);
+			throw error;
 		}
-		return createLevel(connection, void 0, false);
+		return createLevel(connection, void 0, false, isolation);
 	}
 	/**
-	* Starts a nested level of a test fixture, preempting its active one.
+	* 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, signal) {
+	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);
@@ -4707,7 +4954,7 @@ var TestFixtureStack = class {
 		const unavailable = createUnavailableError(fixture, "start a level of the test fixture");
 		if (unavailable) throw suppressAbortReason(unavailable, signal);
 		signal?.throwIfAborted();
-		return startNestedLevel(fixture, false, signal);
+		return startNestedLevel(fixture, false, options);
 	}
 };
 // src/execution/transaction/coordinator.ts
@@ -4718,15 +4965,18 @@ var TestFixtureStack = class {
 */
 var TransactionCoordinator = class {
 	driver;
-	test;
 	#storage = new AsyncLocalStorage();
 	#fixtures;
+	#onReleaseError;
 	/** Closing of the database, set by the first `close`; from then on, operations outside a transaction reject. */
 	#closed;
-	constructor(driver, test = false) {
+	/** 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.#fixtures = new TestFixtureStack(driver, this.#storage);
+		this.#onReleaseError = onReleaseError;
+		this.#fixtures = new TestFixtureStack(driver, this.#storage, onReleaseError);
 	}
 	execute(statement) {
 		const target = this.#route("execute a query");
@@ -4749,15 +4999,19 @@ var TransactionCoordinator = class {
 	/**
 	* 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.
+	* 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.
 	* 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 settings = getLevelSettings(options);
+		const levelOptions = options && {
+			settings: getLevelSettings(options),
+			isolation: options.isolation
+		};
 		const parent = this.#storage.getStore();
-		if (parent) return this.#runNested(parent, callback, true, void 0, settings);
+		if (parent) return 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, void 0, settings);
+		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.
@@ -4789,13 +5043,14 @@ var TransactionCoordinator = class {
 	* 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, { signal } = {}) {
+	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, signal);
+		if (parent) return this.#runNested(parent, callback, false, options);
 		if (this.#closed) return Promise.reject(createDatabaseClosedError("start a test transaction"));
-		return this.#fixtures.startTestLevel(signal).then((level) => level ? this.#runStarted(level, callback, false, signal) : this.#runRoot(callback, false, signal));
+		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.
@@ -4803,8 +5058,8 @@ var TransactionCoordinator = class {
 	* Test transactions started outside any transaction run in the innermost fixture.
 	* A fixture whose `seed` rejects rolls back and closes.
 	*/
-	createTestFixture(seed) {
-		return this.startTestFixture(seed).fixture;
+	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.
@@ -4812,8 +5067,8 @@ var TransactionCoordinator = class {
 	* 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) {
-		return this.#fixtures.start(seed, this.#getFixtureRefusal());
+	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() {
@@ -4848,34 +5103,48 @@ var TransactionCoordinator = class {
 		}
 		if (rejection) throw rejection.error;
 	}
-	async #runRoot(callback, commits, signal, settings) {
-		const connection = await (signal ? acquireUnlessAborted(this.driver, signal) : this.driver.acquire());
-		if (signal?.aborted) throw (await releaseConnection(connection, void 0, { error: signal.reason })).error;
-		const level = createLevel(connection, void 0, commits);
+	/**
+	* 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, { signal, settings, isolation } = noLevelOptions) {
+		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, isolation);
+		const { watch } = level;
 		let outcome;
 		try {
-			await connection.execute(beginStatement);
+			await level.connection.execute(getBeginStatement(isolation));
 		} catch (error) {
 			level.state = "closed";
-			outcome = {
-				rejection: { error: suppressAbortReason(error, signal) },
-				failure: { error }
-			};
+			outcome = { rejection: { error: suppressAbortReason(error, signal) } };
 		}
 		if (!outcome && settings) try {
 			await applySettings(level, settings);
 		} catch (error) {
 			outcome = await getEndedOutcome(endLevel(level, false), error);
 		}
-		outcome ??= await runLevel(this.#storage, level, callback, commits, signal);
-		const rejection = await releaseConnection(connection, outcome.failure, outcome.rejection);
-		if (rejection) throw rejection.error;
+		if (!outcome) {
+			if (watch) watch.phase = "transaction";
+			outcome = await runLevel(this.#storage, level, callback, commits, signal);
+		}
+		await releaseConnection(connection, this.#onReleaseError);
+		if (outcome.rejection) throw watch?.failure ? new TransactionConnectionError(watch.failure.phase, { cause: outcome.rejection.error }) : outcome.rejection.error;
 		return outcome.result;
 	}
-	async #runNested(parent, callback, commits, signal, settings) {
+	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, signal, settings), callback, commits, signal);
+		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) {
@@ -4894,8 +5163,8 @@ function createDatabaseClosedError(operation) {
 }
 // src/execution/database.ts
 /** Creates a database over a driver; its transactions are shared by every schema bound to it. */
-function createDatabase({ driver, test }) {
-	const coordinator = new TransactionCoordinator(driver, test);
+function createDatabase({ driver, ...options }) {
+	const coordinator = new TransactionCoordinator(driver, options);
 	let tablelessDb;
 	const getTablelessDb = () => tablelessDb ??= bindSchema(defineSchema(), database);
 	const database = {
@@ -4920,4 +5189,4 @@ function createDatabase({ driver, test }) {
 function createLockStatement(key) {
 	return createStatement("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [key]);
 }
-export { not as A, countType as C, literal as D, toAggregateType as E, combineNodes as M, and as O, countProjection as S, createCountCall as T, createTableFactory as _, defineSchema as a, RequiredRelationError as b, requireDerived as c, desc as d, orderBy as f, createStatement as g, one as h, sql as i, or as j, isColumnValues as k, addTerms as l, many as m, identifier as n, SelectQuery as o, matchColumn as p, param as r, from as s, createDatabase as t, asc as u, defineTable as v, createAggregateCall as w, ResultDecodeError as x, NotFoundError as y };
+export { toAggregateType as A, NotFoundError as C, countType as D, countProjection as E, or as F, combineNodes as I, and as M, isColumnValues as N, createAggregateCall as O, not as P, defineTable as S, ResultDecodeError as T, matchColumn as _, toDriverError as a, createStatement as b, sql as c, from as d, requireDerived as f, orderBy as g, desc as h, QueryError as i, literal as j, createCountCall as k, defineSchema as l, asc as m, TransactionConnectionError as n, identifier as o, addTerms as p, ConnectionError as r, param as s, createDatabase as t, SelectQuery as u, many as v, RequiredRelationError as w, createTableFactory as x, one as y };