kysely 0.28.17 → 0.28.19

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

@@ -2,6 +2,7 @@
 import { DEFAULT_MIGRATION_TABLE } from '../../migration/migrator.js';
 import { sql } from '../../raw-builder/sql.js';
 import { DialectAdapterBase } from '../dialect-adapter-base.js';
+const LOCK_PRINCIPAL = 'dbo';
 export class MssqlAdapter extends DialectAdapterBase {
     get supportsCreateIfNotExists() {
         return false;
@@ -12,14 +13,19 @@ export class MssqlAdapter extends 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 sql `exec sp_getapplock @DbPrincipal = ${sql.lit('dbo')}, @Resource = ${sql.lit(DEFAULT_MIGRATION_TABLE)}, @LockMode = ${sql.lit('Exclusive')}`.execute(db);
+        await sql `exec sp_getapplock @DbPrincipal = ${sql.lit(LOCK_PRINCIPAL)}, @Resource = ${sql.lit(DEFAULT_MIGRATION_TABLE)}, @LockMode = ${sql.lit('Exclusive')}, @LockOwner = ${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 sql `exec sp_releaseapplock @DbPrincipal = ${sql.lit(LOCK_PRINCIPAL)}, @Resource = ${sql.lit(DEFAULT_MIGRATION_TABLE)}, @LockOwner = ${sql.lit('Session')}`.execute(db);
     }
 }

package/dist/esm/dialect/mssql/mssql-driver.d.ts

@@ -25,6 +25,9 @@ export declare class MssqlDriver implements Driver {
     beginTransaction(connection: MssqlConnection, settings: TransactionSettings): Promise<void>;
     /**
      * Commits a transaction.
+     *
+     * Throws {@link AbortedTransactionError} if the database confirms that
+     * the transaction was rolled back instead of committed.
      */
     commitTransaction(connection: MssqlConnection): Promise<void>;
     /**

package/dist/esm/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/esm/dialect/mysql/mysql-driver.d.ts

@@ -24,6 +24,9 @@ export declare class MysqlDriver implements Driver {
     beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
     /**
      * Commits a transaction.
+     *
+     * Throws {@link AbortedTransactionError} if the database confirms that
+     * the transaction was rolled back instead of committed.
      */
     commitTransaction(connection: DatabaseConnection): Promise<void>;
     /**

package/dist/esm/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/esm/dialect/postgres/postgres-adapter.js

@@ -1,8 +1,8 @@
 /// <reference types="./postgres-adapter.d.ts" />
 import { sql } from '../../raw-builder/sql.js';
 import { DialectAdapterBase } from '../dialect-adapter-base.js';
-// Random id for our transaction lock.
 const LOCK_ID = BigInt('3853314791062309107');
+const LOCK_TIMEOUT_MILLISECONDS = 60 * 60 * 1_000;
 export class PostgresAdapter extends DialectAdapterBase {
     get supportsTransactionalDdl() {
         return true;
@@ -11,12 +11,18 @@ export class PostgresAdapter extends DialectAdapterBase {
         return true;
     }
     async acquireMigrationLock(db, _opt) {
-        // Acquire a transaction level advisory lock.
-        await sql `select pg_advisory_xact_lock(${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 sql `
+    with set_timeout as (
+      select set_config('lock_timeout', '${sql.lit(LOCK_TIMEOUT_MILLISECONDS)}', true) as config_val
+    )
+    select pg_advisory_lock(${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 sql `select pg_advisory_unlock(${sql.lit(LOCK_ID)})`.execute(db);
     }
 }

package/dist/esm/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>);
@@ -51,7 +61,7 @@ export interface PostgresPool {
 export interface PostgresPoolClient {
     query<R>(sql: string, parameters: ReadonlyArray<unknown>): Promise<PostgresQueryResult<R>>;
     query<R>(cursor: PostgresCursor<R>): PostgresCursor<R>;
-    release(): void;
+    release(destroy?: boolean): void;
 }
 export interface PostgresCursor<T> {
     read(rowsCount: number): Promise<T[]>;
@@ -59,7 +69,7 @@ export interface PostgresCursor<T> {
 }
 export type PostgresCursorConstructor = new <T>(sql: string, parameters: unknown[]) => PostgresCursor<T>;
 export interface PostgresQueryResult<R> {
-    command: 'UPDATE' | 'DELETE' | 'INSERT' | 'SELECT' | 'MERGE';
+    command: 'UPDATE' | 'DELETE' | 'INSERT' | 'SELECT' | 'MERGE' | 'COMMIT' | 'ROLLBACK';
     rowCount: number;
     rows: R[];
 }

package/dist/esm/dialect/postgres/postgres-driver.d.ts

@@ -4,6 +4,7 @@ import { CompiledQuery } from '../../query-compiler/compiled-query.js';
 import type { QueryCompiler } from '../../query-compiler/query-compiler.js';
 import type { PostgresCursorConstructor, PostgresDialectConfig, PostgresPoolClient } from './postgres-dialect-config.js';
 declare const PRIVATE_RELEASE_METHOD: unique symbol;
+declare const PRIVATE_MARK_FOR_DISCARD_METHOD: unique symbol;
 export declare class PostgresDriver implements Driver {
     #private;
     constructor(config: PostgresDialectConfig);
@@ -24,12 +25,15 @@ export declare class PostgresDriver implements Driver {
     beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
     /**
      * Commits a transaction.
+     *
+     * Throws {@link AbortedTransactionError} if the database confirms that
+     * the transaction was rolled back instead of committed.
      */
     commitTransaction(connection: DatabaseConnection): Promise<void>;
     /**
      * Rolls back a transaction.
      */
-    rollbackTransaction(connection: DatabaseConnection): Promise<void>;
+    rollbackTransaction(connection: PostgresConnection): Promise<void>;
     savepoint(connection: DatabaseConnection, savepointName: string, compileQuery: QueryCompiler['compileQuery']): Promise<void>;
     rollbackToSavepoint(connection: DatabaseConnection, savepointName: string, compileQuery: QueryCompiler['compileQuery']): Promise<void>;
     releaseSavepoint(connection: DatabaseConnection, savepointName: string, compileQuery: QueryCompiler['compileQuery']): Promise<void>;
@@ -51,5 +55,6 @@ declare class PostgresConnection implements DatabaseConnection {
     executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>>;
     streamQuery<O>(compiledQuery: CompiledQuery, chunkSize: number): AsyncIterableIterator<QueryResult<O>>;
     [PRIVATE_RELEASE_METHOD](): void;
+    [PRIVATE_MARK_FOR_DISCARD_METHOD](): void;
 }
 export {};

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

@@ -1,10 +1,12 @@
 /// <reference types="./postgres-driver.d.ts" />
+import { AbortedTransactionError } from '../../driver/aborted-transaction-error.js';
 import { parseSavepointCommand } from '../../parser/savepoint-parser.js';
 import { CompiledQuery } from '../../query-compiler/compiled-query.js';
 import { isFunction, freeze } from '../../util/object-utils.js';
 import { createQueryId } from '../../util/query-id.js';
 import { extendStackTrace } from '../../util/stack-trace-utils.js';
 const PRIVATE_RELEASE_METHOD = Symbol();
+const PRIVATE_MARK_FOR_DISCARD_METHOD = Symbol();
 export class PostgresDriver {
     #config;
     #connections = new WeakMap();
@@ -19,6 +21,11 @@ export 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, {
@@ -53,10 +60,21 @@ export class PostgresDriver {
         }
     }
     async commitTransaction(connection) {
-        await connection.executeQuery(CompiledQuery.raw('commit'));
+        const { rows } = await connection.executeQuery(CompiledQuery.raw('commit'));
+        // PostgreSQL completes COMMIT with a ROLLBACK tag if an earlier
+        // statement error left the transaction aborted.
+        if (rows[0]?.command === 'ROLLBACK') {
+            throw new AbortedTransactionError();
+        }
     }
     async rollbackTransaction(connection) {
-        await connection.executeQuery(CompiledQuery.raw('rollback'));
+        try {
+            await connection.executeQuery(CompiledQuery.raw('rollback'));
+        }
+        catch (err) {
+            connection[PRIVATE_MARK_FOR_DISCARD_METHOD]();
+            throw err;
+        }
     }
     async savepoint(connection, savepointName, compileQuery) {
         await connection.executeQuery(compileQuery(parseSavepointCommand('savepoint', savepointName), createQueryId()));
@@ -81,13 +99,18 @@ export class PostgresDriver {
 class PostgresConnection {
     #client;
     #options;
+    #discarded;
     constructor(client, options) {
         this.#client = client;
         this.#options = options;
     }
     async executeQuery(compiledQuery) {
+        this.#assertNotDiscarded();
         try {
             const { command, rowCount, rows } = await this.#client.query(compiledQuery.sql, [...compiledQuery.parameters]);
+            if (command === 'ROLLBACK' || command === 'COMMIT') {
+                return { rows: [{ command }] };
+            }
             return {
                 numAffectedRows: command === 'INSERT' ||
                     command === 'UPDATE' ||
@@ -109,6 +132,7 @@ class PostgresConnection {
         if (!Number.isInteger(chunkSize) || chunkSize <= 0) {
             throw new Error('chunkSize must be a positive integer');
         }
+        this.#assertNotDiscarded();
         const cursor = this.#client.query(new this.#options.cursor(compiledQuery.sql, compiledQuery.parameters.slice()));
         try {
             while (true) {
@@ -126,6 +150,14 @@ class PostgresConnection {
         }
     }
     [PRIVATE_RELEASE_METHOD]() {
-        this.#client.release();
+        this.#client.release(Boolean(this.#discarded));
+    }
+    [PRIVATE_MARK_FOR_DISCARD_METHOD]() {
+        this.#discarded = true;
+    }
+    #assertNotDiscarded() {
+        if (this.#discarded) {
+            throw new Error('Postgres connection has been discarded');
+        }
     }
 }

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

@@ -71,20 +71,26 @@ export 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, 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 = 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(freeze({
+            table.columns.push(freeze({
                 comment: column.column_description ?? undefined,
                 dataType: column.type,
                 dataTypeSchema: column.type_schema,
@@ -94,6 +100,6 @@ export class PostgresIntrospector {
                 name: column.column,
             }));
         }
-        return Array.from(tableDictionary.values());
+        return tables;
     }
 }

package/dist/esm/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/esm/dialect/sqlite/sqlite-driver.d.ts

@@ -22,6 +22,9 @@ export declare class SqliteDriver implements Driver {
     beginTransaction(connection: DatabaseConnection): Promise<void>;
     /**
      * Commits a transaction.
+     *
+     * Throws {@link AbortedTransactionError} if the database confirms that
+     * the transaction was rolled back instead of committed.
      */
     commitTransaction(connection: DatabaseConnection): Promise<void>;
     /**

package/dist/esm/driver/aborted-transaction-error.d.ts

@@ -0,0 +1,11 @@
+declare const ABORTED_TRANSACTION_ERROR: unique symbol;
+/**
+ * Thrown when the database rolls back a transaction instead of committing it.
+ */
+export declare class AbortedTransactionError extends Error {
+    name: string;
+    readonly [ABORTED_TRANSACTION_ERROR] = true;
+    constructor();
+}
+export declare function isAbortedTransactionError(error: unknown): error is AbortedTransactionError;
+export {};

package/dist/esm/driver/aborted-transaction-error.js

@@ -0,0 +1,16 @@
+/// <reference types="./aborted-transaction-error.d.ts" />
+import { isObject } from '../util/object-utils.js';
+const ABORTED_TRANSACTION_ERROR = Symbol.for('kysely.AbortedTransactionError');
+/**
+ * Thrown when the database rolls back a transaction instead of committing it.
+ */
+export class AbortedTransactionError extends Error {
+    name = 'AbortedTransactionError';
+    [ABORTED_TRANSACTION_ERROR] = true;
+    constructor() {
+        super('Transaction was rolled back instead of committed');
+    }
+}
+export function isAbortedTransactionError(error) {
+    return isObject(error) && ABORTED_TRANSACTION_ERROR in error;
+}

package/dist/esm/driver/driver.d.ts

@@ -23,6 +23,9 @@ export interface Driver {
     beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
     /**
      * Commits a transaction.
+     *
+     * Throws {@link AbortedTransactionError} if the database confirms that
+     * the transaction was rolled back instead of committed.
      */
     commitTransaction(connection: DatabaseConnection): Promise<void>;
     /**

package/dist/esm/driver/dummy-driver.d.ts

@@ -55,6 +55,9 @@ export declare class DummyDriver implements Driver {
     beginTransaction(): Promise<void>;
     /**
      * Commits a transaction.
+     *
+     * Throws {@link AbortedTransactionError} if the database confirms that
+     * the transaction was rolled back instead of committed.
      */
     commitTransaction(): Promise<void>;
     /**

package/dist/esm/driver/runtime-driver.d.ts

@@ -31,6 +31,9 @@ export declare class RuntimeDriver implements Driver {
     beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
     /**
      * Commits a transaction.
+     *
+     * Throws {@link AbortedTransactionError} if the database confirms that
+     * the transaction was rolled back instead of committed.
      */
     commitTransaction(connection: DatabaseConnection): Promise<void>;
     /**

package/dist/esm/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/esm/helpers/mssql.js

@@ -205,11 +205,13 @@ export 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"
  * ```
  */
 export function jsonBuildObject(obj) {
-    return sql `json_query('{${sql.join(Object.keys(obj).map((k) => sql `"${sql.raw(k)}":"'+${obj[k]}+'"`), sql `,`)}}')`;
+    return sql `json_query('{${sql.join(Object.keys(obj).map((k) => sql `"'+string_escape(N${sql.lit(k)}, 'json')+'":"'+string_escape(${obj[k]}, 'json')+'"`), sql `,`)}}')`;
 }

package/dist/esm/index.d.ts

@@ -57,6 +57,7 @@ export * from './dynamic/dynamic.js';
 export * from './dynamic/dynamic-reference-builder.js';
 export * from './dynamic/dynamic-table-builder.js';
 export * from './driver/driver.js';
+export * from './driver/aborted-transaction-error.js';
 export * from './driver/database-connection.js';
 export * from './driver/connection-provider.js';
 export * from './driver/default-connection-provider.js';

package/dist/esm/index.js

@@ -58,6 +58,7 @@ export * from './dynamic/dynamic.js';
 export * from './dynamic/dynamic-reference-builder.js';
 export * from './dynamic/dynamic-table-builder.js';
 export * from './driver/driver.js';
+export * from './driver/aborted-transaction-error.js';
 export * from './driver/database-connection.js';
 export * from './driver/connection-provider.js';
 export * from './driver/default-connection-provider.js';

package/dist/esm/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,13 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Commits the transaction.
      *
+     * If the database rolls back instead of committing, marks the transaction
+     * as rolled back, releases the connection and throws {@link AbortedTransactionError}.
+     *
+     * 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 +697,16 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     /**
      * Rolls back the transaction.
      *
+     * If a commit already reported that the database rolled back the transaction,
+     * succeeds without sending another rollback command.
+     *
+     * 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 +732,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 +766,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 +801,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 +882,12 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
      */
     withTables<T extends Record<string, Record<string, any>>>(): ControlledTransaction<DrainOuterGeneric<DB & T>, S>;
 }
+interface ControlledTransactionState {
+    status: 'active' | 'committed' | 'rolled back' | 'aborted';
+}
 interface ControlledTransactionProps extends KyselyProps {
     readonly connection: ControlledConnection;
+    readonly transactionState?: ControlledTransactionState;
 }
 export declare class Command<T> {
     #private;