kysely 0.28.17 → 0.28.18

package/README.md

@@ -1,7 +1,7 @@
 [![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://stand-with-ukraine.pp.ua)
 
 [![NPM Version](https://img.shields.io/npm/v/kysely?style=flat&label=latest)](https://github.com/kysely-org/kysely/releases/latest)
-[![Socket Badge](https://badge.socket.dev/npm/package/kysely/0.28.17)](https://socket.dev/npm/package/kysely/overview/0.28.17)
+[![Socket Badge](https://badge.socket.dev/npm/package/kysely/0.28.18)](https://socket.dev/npm/package/kysely/overview/0.28.18)
 [![Tests](https://github.com/kysely-org/kysely/actions/workflows/test.yml/badge.svg)](https://github.com/kysely-org/kysely)
 [![License](https://img.shields.io/github/license/kysely-org/kysely?style=flat)](https://github.com/kysely-org/kysely/blob/master/LICENSE)
 [![Issues](https://img.shields.io/github/issues-closed/kysely-org/kysely?logo=github)](https://github.com/kysely-org/kysely/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)

package/dist/cjs/dialect/mssql/mssql-adapter.d.ts

@@ -1,5 +1,6 @@
 import type { Kysely } from '../../kysely.js';
 import { DialectAdapterBase } from '../dialect-adapter-base.js';
+import type { MigrationLockOptions } from '../dialect-adapter.js';
 export declare class MssqlAdapter extends DialectAdapterBase {
     /**
      * Whether or not this dialect supports `if not exists` in creation of tables/schemas/views/etc.
@@ -70,7 +71,7 @@ export declare class MssqlAdapter extends DialectAdapterBase {
      * `db` is a single connection (session) that will be used to execute the
      * migrations.
      */
-    acquireMigrationLock(db: Kysely<any>): Promise<void>;
+    acquireMigrationLock(db: Kysely<any>, _opt: MigrationLockOptions): Promise<void>;
     /**
      * Releases the migration lock. See {@link acquireMigrationLock}.
      *
@@ -79,5 +80,5 @@ export declare class MssqlAdapter extends DialectAdapterBase {
      * is a single connection (session) that was used to execute the migrations
      * and the `acquireMigrationLock` call.
      */
-    releaseMigrationLock(): Promise<void>;
+    releaseMigrationLock(db: Kysely<any>, _opt: MigrationLockOptions): Promise<void>;
 }

package/dist/cjs/dialect/mssql/mssql-adapter.js

@@ -4,6 +4,7 @@ exports.MssqlAdapter = void 0;
 const migrator_js_1 = require("../../migration/migrator.js");
 const sql_js_1 = require("../../raw-builder/sql.js");
 const dialect_adapter_base_js_1 = require("../dialect-adapter-base.js");
+const LOCK_PRINCIPAL = 'dbo';
 class MssqlAdapter extends dialect_adapter_base_js_1.DialectAdapterBase {
     get supportsCreateIfNotExists() {
         return false;
@@ -14,15 +15,20 @@ class MssqlAdapter extends dialect_adapter_base_js_1.DialectAdapterBase {
     get supportsOutput() {
         return true;
     }
-    async acquireMigrationLock(db) {
-        // Acquire a transaction-level exclusive lock on the migrations table.
+    async acquireMigrationLock(db, _opt) {
+        // Acquire a session-level exclusive lock on the migrations table. A
+        // session-level lock (as opposed to the default transaction-level lock)
+        // stays held after the migration transaction commits and until we release
+        // it explicitly in `releaseMigrationLock` OR the session ends. This way we
+        // know the lock is either released by us after successful or failed
+        // migrations OR it's released by SQL Server if the connection dies.
         // https://learn.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/sp-getapplock-transact-sql?view=sql-server-ver16
-        await (0, sql_js_1.sql) `exec sp_getapplock @DbPrincipal = ${sql_js_1.sql.lit('dbo')}, @Resource = ${sql_js_1.sql.lit(migrator_js_1.DEFAULT_MIGRATION_TABLE)}, @LockMode = ${sql_js_1.sql.lit('Exclusive')}`.execute(db);
+        await (0, sql_js_1.sql) `exec sp_getapplock @DbPrincipal = ${sql_js_1.sql.lit(LOCK_PRINCIPAL)}, @Resource = ${sql_js_1.sql.lit(migrator_js_1.DEFAULT_MIGRATION_TABLE)}, @LockMode = ${sql_js_1.sql.lit('Exclusive')}, @LockOwner = ${sql_js_1.sql.lit('Session')}`.execute(db);
     }
-    async releaseMigrationLock() {
-        // Nothing to do here. `sp_getapplock` is automatically released at the
-        // end of the transaction and since `supportsTransactionalDdl` true, we know
-        // the `db` instance passed to acquireMigrationLock is actually a transaction.
+    async releaseMigrationLock(db, _opt) {
+        // Release the session-level lock acquired in `acquireMigrationLock`.
+        // https://learn.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/sp-releaseapplock-transact-sql?view=sql-server-ver16
+        await (0, sql_js_1.sql) `exec sp_releaseapplock @DbPrincipal = ${sql_js_1.sql.lit(LOCK_PRINCIPAL)}, @Resource = ${sql_js_1.sql.lit(migrator_js_1.DEFAULT_MIGRATION_TABLE)}, @LockOwner = ${sql_js_1.sql.lit('Session')}`.execute(db);
     }
 }
 exports.MssqlAdapter = MssqlAdapter;

package/dist/cjs/dialect/mysql/mysql-dialect-config.d.ts

@@ -10,6 +10,16 @@ export interface MysqlDialectConfig {
      *
      * If a function is provided, it's called once when the first query is executed.
      *
+     * Once the driver has initialized, {@link Kysely.destroy} calls
+     * `pool.end(callback)`, whether the pool is supplied directly or returned by a
+     * function. If initialization hasn't started, `db.destroy()` does nothing,
+     * even if the supplied pool has been used outside Kysely.
+     *
+     * If Kysely is not the sole consumer of the pool, or the pool's lifecycle is
+     * managed elsewhere, skip `db.destroy()`. Let the application call
+     * `pool.end(callback)` once all consumers, including Kysely, have finished. No
+     * separate cleanup of the `Kysely` instance is needed.
+     *
      * https://github.com/sidorares/node-mysql2#using-connection-pools
      */
     pool: MysqlPool | (() => Promise<MysqlPool>);

package/dist/cjs/dialect/postgres/postgres-adapter.d.ts

@@ -76,5 +76,5 @@ export declare class PostgresAdapter extends DialectAdapterBase {
      * is a single connection (session) that was used to execute the migrations
      * and the `acquireMigrationLock` call.
      */
-    releaseMigrationLock(_db: Kysely<any>, _opt: MigrationLockOptions): Promise<void>;
+    releaseMigrationLock(db: Kysely<any>, _opt: MigrationLockOptions): Promise<void>;
 }

package/dist/cjs/dialect/postgres/postgres-adapter.js

@@ -3,8 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostgresAdapter = void 0;
 const sql_js_1 = require("../../raw-builder/sql.js");
 const dialect_adapter_base_js_1 = require("../dialect-adapter-base.js");
-// Random id for our transaction lock.
 const LOCK_ID = BigInt('3853314791062309107');
+const LOCK_TIMEOUT_MILLISECONDS = 60 * 60 * 1_000;
 class PostgresAdapter extends dialect_adapter_base_js_1.DialectAdapterBase {
     get supportsTransactionalDdl() {
         return true;
@@ -13,13 +13,19 @@ class PostgresAdapter extends dialect_adapter_base_js_1.DialectAdapterBase {
         return true;
     }
     async acquireMigrationLock(db, _opt) {
-        // Acquire a transaction level advisory lock.
-        await (0, sql_js_1.sql) `select pg_advisory_xact_lock(${sql_js_1.sql.lit(LOCK_ID)})`.execute(db);
+        // in 1 RTT, acquire a session-level advisory lock with a timeout.
+        //
+        // if ever this runs inside a transaction, niche edge case we support - the
+        // user is responsible to set a different timeout value or disable (`0` value).
+        await (0, sql_js_1.sql) `
+    with set_timeout as (
+      select set_config('lock_timeout', '${sql_js_1.sql.lit(LOCK_TIMEOUT_MILLISECONDS)}', true) as config_val
+    )
+    select pg_advisory_lock(${sql_js_1.sql.lit(LOCK_ID)})
+    from set_timeout`.execute(db);
     }
-    async releaseMigrationLock(_db, _opt) {
-        // Nothing to do here. `pg_advisory_xact_lock` is automatically released at the
-        // end of the transaction and since `supportsTransactionalDdl` true, we know
-        // the `db` instance passed to acquireMigrationLock is actually a transaction.
+    async releaseMigrationLock(db, _opt) {
+        await (0, sql_js_1.sql) `select pg_advisory_unlock(${sql_js_1.sql.lit(LOCK_ID)})`.execute(db);
     }
 }
 exports.PostgresAdapter = PostgresAdapter;

package/dist/cjs/dialect/postgres/postgres-dialect-config.d.ts

@@ -8,6 +8,16 @@ export interface PostgresDialectConfig {
      *
      * If a function is provided, it's called once when the first query is executed.
      *
+     * Once the driver has initialized, {@link Kysely.destroy} calls `pool.end()`,
+     * whether the pool is supplied directly or returned by a function. If
+     * initialization hasn't started, `db.destroy()` does nothing, even if the
+     * supplied pool has been used outside Kysely.
+     *
+     * If Kysely is not the sole consumer of the pool, or the pool's lifecycle is
+     * managed elsewhere, skip `db.destroy()`. Let the application call `pool.end()`
+     * once all consumers, including Kysely, have finished. No separate cleanup of
+     * the `Kysely` instance is needed.
+     *
      * https://node-postgres.com/apis/pool
      */
     pool: PostgresPool | (() => Promise<PostgresPool>);

package/dist/cjs/dialect/postgres/postgres-driver.js

@@ -21,6 +21,11 @@ class PostgresDriver {
     }
     async acquireConnection() {
         const client = await this.#pool.connect();
+        // `destroy` was called while the connection was being acquired.
+        if (!this.#pool) {
+            client.release();
+            throw new Error('driver has already been destroyed');
+        }
         let connection = this.#connections.get(client);
         if (!connection) {
             connection = new PostgresConnection(client, {

package/dist/cjs/dialect/postgres/postgres-introspector.js

@@ -73,20 +73,26 @@ class PostgresIntrospector {
         };
     }
     #parseTableMetadata(columns) {
-        const tableDictionary = new Map();
-        for (let i = 0, len = columns.length; i < len; i++) {
-            const column = columns[i];
-            const { schema, table } = column;
-            const tableKey = `schema:${schema};table:${table}`;
-            if (!tableDictionary.has(tableKey)) {
-                tableDictionary.set(tableKey, (0, object_utils_js_1.freeze)({
+        const tables = [];
+        const schemas = new Map();
+        for (const column of columns) {
+            let schema = schemas.get(column.schema);
+            if (!schema) {
+                schema = new Map();
+                schemas.set(column.schema, schema);
+            }
+            let table = schema.get(column.table);
+            if (!table) {
+                table = (0, object_utils_js_1.freeze)({
                     columns: [],
                     isView: column.table_type === 'v',
-                    name: table,
-                    schema,
-                }));
+                    name: column.table,
+                    schema: column.schema,
+                });
+                schema.set(column.table, table);
+                tables.push(table);
             }
-            tableDictionary.get(tableKey).columns.push((0, object_utils_js_1.freeze)({
+            table.columns.push((0, object_utils_js_1.freeze)({
                 comment: column.column_description ?? undefined,
                 dataType: column.type,
                 dataTypeSchema: column.type_schema,
@@ -96,7 +102,7 @@ class PostgresIntrospector {
                 name: column.column,
             }));
         }
-        return Array.from(tableDictionary.values());
+        return tables;
     }
 }
 exports.PostgresIntrospector = PostgresIntrospector;

package/dist/cjs/dialect/sqlite/sqlite-dialect-config.d.ts

@@ -8,6 +8,16 @@ export interface SqliteDialectConfig {
      *
      * If a function is provided, it's called once when the first query is executed.
      *
+     * Once the driver has initialized, {@link Kysely.destroy} calls
+     * `database.close()`, whether the database is supplied directly or returned by
+     * a function. If initialization hasn't started, `db.destroy()` does nothing,
+     * even if the supplied database has been used outside Kysely.
+     *
+     * If Kysely is not the sole consumer of the database, or the database's
+     * lifecycle is managed elsewhere, skip `db.destroy()`. Let the application
+     * call `database.close()` once all consumers, including Kysely, have finished.
+     * No separate cleanup of the `Kysely` instance is needed.
+     *
      * https://github.com/JoshuaWise/better-sqlite3/blob/master/docs/api.md#new-databasepath-options
      */
     database: SqliteDatabase | (() => Promise<SqliteDatabase>);

package/dist/cjs/helpers/mssql.d.ts

@@ -202,7 +202,9 @@ export declare function jsonObjectFrom<O>(expr: Expression<O>): RawBuilder<Simpl
  *
  * ```sql
  * select "id", json_query(
- *   '{"first":"'+"first_name"+',"last":"'+"last_name"+',"full":"'+concat("first_name", ' ', "last_name")+'"}'
+ *   '{"'+string_escape(N'first', 'json')+'":"'+string_escape("first_name", 'json')+
+ *   '","'+string_escape(N'last', 'json')+'":"'+string_escape("last_name", 'json')+
+ *   '","'+string_escape(N'full', 'json')+'":"'+string_escape(concat("first_name", ' ', "last_name"), 'json')+'"}'
  * ) as "name"
  * from "person"
  * ```

package/dist/cjs/helpers/mssql.js

@@ -209,11 +209,13 @@ function jsonObjectFrom(expr) {
  *
  * ```sql
  * select "id", json_query(
- *   '{"first":"'+"first_name"+',"last":"'+"last_name"+',"full":"'+concat("first_name", ' ', "last_name")+'"}'
+ *   '{"'+string_escape(N'first', 'json')+'":"'+string_escape("first_name", 'json')+
+ *   '","'+string_escape(N'last', 'json')+'":"'+string_escape("last_name", 'json')+
+ *   '","'+string_escape(N'full', 'json')+'":"'+string_escape(concat("first_name", ' ', "last_name"), 'json')+'"}'
  * ) as "name"
  * from "person"
  * ```
  */
 function jsonBuildObject(obj) {
-    return (0, sql_js_1.sql) `json_query('{${sql_js_1.sql.join(Object.keys(obj).map((k) => (0, sql_js_1.sql) `"${sql_js_1.sql.raw(k)}":"'+${obj[k]}+'"`), (0, sql_js_1.sql) `,`)}}')`;
+    return (0, sql_js_1.sql) `json_query('{${sql_js_1.sql.join(Object.keys(obj).map((k) => (0, sql_js_1.sql) `"'+string_escape(N${sql_js_1.sql.lit(k)}, 'json')+'":"'+string_escape(${obj[k]}, 'json')+'"`), (0, sql_js_1.sql) `,`)}}')`;
 }

package/dist/cjs/kysely.d.ts

@@ -29,7 +29,8 @@ declare global {
  * The main Kysely class.
  *
  * You should create one instance of `Kysely` per database using the {@link Kysely}
- * constructor. Each `Kysely` instance maintains its own connection pool.
+ * constructor. The dialect manages database connections and may use a shared
+ * pool or database instance.
  *
  * ### Examples
  *
@@ -384,7 +385,16 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
     /**
      * Releases all resources and disconnects from the database.
      *
-     * You need to call this when you are done using the `Kysely` instance.
+     * Call this when you are done using the `Kysely` instance and Kysely is
+     * responsible for closing its connections, pool, or database instance.
+     *
+     * If the pool or database instance is shared with other consumers or its
+     * lifecycle is managed elsewhere, skip this call. Let the application close it
+     * once all consumers, including Kysely, have finished. No separate cleanup of
+     * the `Kysely` instance is needed.
+     *
+     * The driver is initialized lazily. If initialization hasn't started, this
+     * method does nothing.
      */
     destroy(): Promise<void>;
     /**
@@ -511,7 +521,16 @@ export declare class Transaction<DB> extends Kysely<DB> {
     /**
      * Releases all resources and disconnects from the database.
      *
-     * You need to call this when you are done using the `Kysely` instance.
+     * Call this when you are done using the `Kysely` instance and Kysely is
+     * responsible for closing its connections, pool, or database instance.
+     *
+     * If the pool or database instance is shared with other consumers or its
+     * lifecycle is managed elsewhere, skip this call. Let the application close it
+     * once all consumers, including Kysely, have finished. No separate cleanup of
+     * the `Kysely` instance is needed.
+     *
+     * The driver is initialized lazily. If initialization hasn't started, this
+     * method does nothing.
      */
     destroy(): Promise<void>;
     /**
@@ -646,6 +665,10 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Commits the transaction.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before committing.
+     *
      * See {@link rollback}.
      *
      * ### Examples
@@ -671,6 +694,13 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Rolls back the transaction.
      *
+     * The connection is released even if the rollback fails, so the transaction
+     * cannot be used afterwards in either case.
+     *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before rolling back.
+     *
      * See {@link commit} and {@link rollbackToSavepoint}.
      *
      * ### Examples
@@ -696,6 +726,10 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Creates a savepoint with a given name.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before creating a savepoint.
+     *
      * See {@link rollbackToSavepoint} and {@link releaseSavepoint}.
      *
      * For a type-safe experience, you should use the returned instance from now on.
@@ -726,6 +760,10 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Rolls back to a savepoint with a given name.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before rolling back to a savepoint.
+     *
      * See {@link savepoint} and {@link releaseSavepoint}.
      *
      * You must use the same instance returned by {@link savepoint}, or
@@ -757,6 +795,10 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Releases a savepoint with a given name.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before releasing a savepoint.
+     *
      * See {@link savepoint} and {@link rollbackToSavepoint}.
      *
      * You must use the same instance returned by {@link savepoint}, or
@@ -834,8 +876,13 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
      */
     withTables<T extends Record<string, Record<string, any>>>(): ControlledTransaction<DrainOuterGeneric<DB & T>, S>;
 }
+interface ControlledTransctionState {
+    isCommitted: boolean;
+    isRolledBack: boolean;
+}
 interface ControlledTransactionProps extends KyselyProps {
     readonly connection: ControlledConnection;
+    readonly state?: ControlledTransctionState;
 }
 export declare class Command<T> {
     #private;

package/dist/cjs/kysely.js

@@ -27,7 +27,8 @@ Symbol.asyncDispose ??= Symbol('Symbol.asyncDispose');
  * The main Kysely class.
  *
  * You should create one instance of `Kysely` per database using the {@link Kysely}
- * constructor. Each `Kysely` instance maintains its own connection pool.
+ * constructor. The dialect manages database connections and may use a shared
+ * pool or database instance.
  *
  * ### Examples
  *
@@ -436,7 +437,16 @@ class Kysely extends query_creator_js_1.QueryCreator {
     /**
      * Releases all resources and disconnects from the database.
      *
-     * You need to call this when you are done using the `Kysely` instance.
+     * Call this when you are done using the `Kysely` instance and Kysely is
+     * responsible for closing its connections, pool, or database instance.
+     *
+     * If the pool or database instance is shared with other consumers or its
+     * lifecycle is managed elsewhere, skip this call. Let the application close it
+     * once all consumers, including Kysely, have finished. No separate cleanup of
+     * the `Kysely` instance is needed.
+     *
+     * The driver is initialized lazily. If initialization hasn't started, this
+     * method does nothing.
      */
     async destroy() {
         await this.#props.driver.destroy();
@@ -613,10 +623,17 @@ class ControlledTransactionBuilder {
         const settings = { isolationLevel, accessMode };
         (0, driver_js_1.validateTransactionSettings)(settings);
         const connection = await (0, provide_controlled_connection_js_1.provideControlledConnection)(this.#props.executor);
-        await this.#props.driver.beginTransaction(connection.connection, settings);
+        try {
+            await this.#props.driver.beginTransaction(connection.connection, settings);
+        }
+        catch (error) {
+            connection.release();
+            throw error;
+        }
         return new ControlledTransaction({
             ...props,
             connection,
+            state: { isCommitted: false, isRolledBack: false },
             executor: this.#props.executor.withConnectionProvider(new single_connection_provider_js_1.SingleConnectionProvider(connection.connection)),
         });
     }
@@ -625,29 +642,35 @@ exports.ControlledTransactionBuilder = ControlledTransactionBuilder;
 class ControlledTransaction extends Transaction {
     #props;
     #compileQuery;
-    #state;
     constructor(props) {
-        const state = { isCommitted: false, isRolledBack: false };
-        props = {
+        const transactionState = props.state ?? {
+            isCommitted: false,
+            isRolledBack: false,
+        };
+        const controlledProps = {
             ...props,
-            executor: new NotCommittedOrRolledBackAssertingExecutor(props.executor, state),
+            state: transactionState,
+            executor: new NotCommittedOrRolledBackAssertingExecutor(props.executor, transactionState),
         };
-        const { connection, ...transactionProps } = props;
+        const { connection, state, ...transactionProps } = controlledProps;
         super(transactionProps);
-        this.#props = (0, object_utils_js_1.freeze)(props);
-        this.#state = state;
+        this.#props = (0, object_utils_js_1.freeze)(controlledProps);
         const queryId = (0, query_id_js_1.createQueryId)();
-        this.#compileQuery = (node) => props.executor.compileQuery(node, queryId);
+        this.#compileQuery = (node) => controlledProps.executor.compileQuery(node, queryId);
     }
     get isCommitted() {
-        return this.#state.isCommitted;
+        return this.#props.state.isCommitted;
     }
     get isRolledBack() {
-        return this.#state.isRolledBack;
+        return this.#props.state.isRolledBack;
     }
     /**
      * Commits the transaction.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before committing.
+     *
      * See {@link rollback}.
      *
      * ### Examples
@@ -670,16 +693,24 @@ class ControlledTransaction extends Transaction {
      * ```
      */
     commit() {
-        assertNotCommittedOrRolledBack(this.#state);
         return new Command(async () => {
-            await this.#props.driver.commitTransaction(this.#props.connection.connection);
-            this.#state.isCommitted = true;
-            this.#props.connection.release();
+            await this.#props.executor.provideConnection(async (connection) => {
+                await this.#props.driver.commitTransaction(connection);
+                this.#props.state.isCommitted = true;
+                this.#props.connection.release();
+            });
         });
     }
     /**
      * Rolls back the transaction.
      *
+     * The connection is released even if the rollback fails, so the transaction
+     * cannot be used afterwards in either case.
+     *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before rolling back.
+     *
      * See {@link commit} and {@link rollbackToSavepoint}.
      *
      * ### Examples
@@ -702,16 +733,26 @@ class ControlledTransaction extends Transaction {
      * ```
      */
     rollback() {
-        assertNotCommittedOrRolledBack(this.#state);
         return new Command(async () => {
-            await this.#props.driver.rollbackTransaction(this.#props.connection.connection);
-            this.#state.isRolledBack = true;
-            this.#props.connection.release();
+            await this.#props.executor.provideConnection(async (connection) => {
+                // A failed rollback can't be meaningfully retried (e.g. dead connection).
+                try {
+                    await this.#props.driver.rollbackTransaction(connection);
+                }
+                finally {
+                    this.#props.state.isRolledBack = true;
+                    this.#props.connection.release();
+                }
+            });
         });
     }
     /**
      * Creates a savepoint with a given name.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before creating a savepoint.
+     *
      * See {@link rollbackToSavepoint} and {@link releaseSavepoint}.
      *
      * For a type-safe experience, you should use the returned instance from now on.
@@ -739,15 +780,20 @@ class ControlledTransaction extends Transaction {
      * ```
      */
     savepoint(savepointName) {
-        assertNotCommittedOrRolledBack(this.#state);
         return new Command(async () => {
-            await this.#props.driver.savepoint?.(this.#props.connection.connection, savepointName, this.#compileQuery);
+            await this.#props.executor.provideConnection(async (connection) => {
+                await this.#props.driver.savepoint?.(connection, savepointName, this.#compileQuery);
+            });
             return new ControlledTransaction({ ...this.#props });
         });
     }
     /**
      * Rolls back to a savepoint with a given name.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before rolling back to a savepoint.
+     *
      * See {@link savepoint} and {@link releaseSavepoint}.
      *
      * You must use the same instance returned by {@link savepoint}, or
@@ -776,15 +822,20 @@ class ControlledTransaction extends Transaction {
      * ```
      */
     rollbackToSavepoint(savepointName) {
-        assertNotCommittedOrRolledBack(this.#state);
         return new Command(async () => {
-            await this.#props.driver.rollbackToSavepoint?.(this.#props.connection.connection, savepointName, this.#compileQuery);
+            await this.#props.executor.provideConnection(async (connection) => {
+                await this.#props.driver.rollbackToSavepoint?.(connection, savepointName, this.#compileQuery);
+            });
             return new ControlledTransaction({ ...this.#props });
         });
     }
     /**
      * Releases a savepoint with a given name.
      *
+     * Waits for ongoing queries to finish. Streams must be exhausted or closed
+     * before awaiting this command. When consuming a stream with `for await`,
+     * exit the loop before releasing a savepoint.
+     *
      * See {@link savepoint} and {@link rollbackToSavepoint}.
      *
      * You must use the same instance returned by {@link savepoint}, or
@@ -818,9 +869,10 @@ class ControlledTransaction extends Transaction {
      * ```
      */
     releaseSavepoint(savepointName) {
-        assertNotCommittedOrRolledBack(this.#state);
         return new Command(async () => {
-            await this.#props.driver.releaseSavepoint?.(this.#props.connection.connection, savepointName, this.#compileQuery);
+            await this.#props.executor.provideConnection(async (connection) => {
+                await this.#props.driver.releaseSavepoint?.(connection, savepointName, this.#compileQuery);
+            });
             return new ControlledTransaction({ ...this.#props });
         });
     }
@@ -899,15 +951,23 @@ class NotCommittedOrRolledBackAssertingExecutor {
         return this.#executor.compileQuery(node, queryId);
     }
     provideConnection(consumer) {
-        return this.#executor.provideConnection(consumer);
+        assertNotCommittedOrRolledBack(this.#state);
+        return this.#executor.provideConnection(async (connection) => {
+            assertNotCommittedOrRolledBack(this.#state);
+            return await consumer(connection);
+        });
     }
     executeQuery(compiledQuery) {
         assertNotCommittedOrRolledBack(this.#state);
-        return this.#executor.executeQuery(compiledQuery);
+        return this.#executor
+            .withConnectionProvider(this)
+            .executeQuery(compiledQuery);
     }
     stream(compiledQuery, chunkSize) {
         assertNotCommittedOrRolledBack(this.#state);
-        return this.#executor.stream(compiledQuery, chunkSize);
+        return this.#executor
+            .withConnectionProvider(this)
+            .stream(compiledQuery, chunkSize);
     }
     withConnectionProvider(connectionProvider) {
         return new NotCommittedOrRolledBackAssertingExecutor(this.#executor.withConnectionProvider(connectionProvider), this.#state);