kysely 0.29.6 → 0.29.8

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.29.6)](https://socket.dev/npm/package/kysely/overview/0.29.6)
+[![Socket Badge](https://badge.socket.dev/npm/package/kysely/0.29.8)](https://socket.dev/npm/package/kysely/overview/0.29.8)
 [![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/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/dialect/mysql/mysql-dialect-config.d.ts

@@ -19,6 +19,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 | ((options?: AbortableOperationOptions) => Promise<MysqlPool>);

package/dist/dialect/mysql/mysql-driver.d.ts

@@ -25,6 +25,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/dialect/pglite/pglite-dialect-config.d.ts

@@ -16,6 +16,16 @@ export interface PGliteDialectConfig {
      *
      * If a function is provided, it's called once when the first query is executed.
      *
+     * Once the driver has initialized, {@link Kysely.destroy} calls `pglite.close()`
+     * if the instance is still open, whether it is supplied directly or returned
+     * by a function. If initialization hasn't started, `db.destroy()` does nothing,
+     * even if the supplied instance has been used outside Kysely.
+     *
+     * If Kysely is not the sole consumer of the instance, or its lifecycle is
+     * managed elsewhere, skip `db.destroy()`. Let the application call
+     * `pglite.close()` once all consumers, including Kysely, have finished. No
+     * separate cleanup of the `Kysely` instance is needed.
+     *
      * https://pglite.dev/docs/api#main-constructor
      */
     pglite: PGlite | ((options?: AbortableOperationOptions) => PGlite | Promise<PGlite>);

package/dist/dialect/pglite/pglite-driver.d.ts

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

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

@@ -42,6 +42,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 | ((options?: AbortableOperationOptions) => Promise<PostgresPool>);
@@ -85,7 +95,7 @@ export type PostgresClientConstructor = new (options: any) => PostgresClient;
  * https://node-postgres.com/apis/pool#releasing-clients
  */
 export interface PostgresPoolClient extends Omit<PostgresClient, 'connect' | 'end'> {
-    release(): void;
+    release(destroy?: boolean): void;
 }
 /**
  * This interface is pg driver's `Cursor` class that kysely needs.
@@ -114,7 +124,7 @@ export type PostgresCursorConstructor = new <T>(sql: string, parameters: unknown
  * https://node-postgres.com/apis/result
  */
 export interface PostgresQueryResult<R> {
-    command: 'UPDATE' | 'DELETE' | 'INSERT' | 'SELECT' | 'MERGE';
+    command: 'UPDATE' | 'DELETE' | 'INSERT' | 'SELECT' | 'MERGE' | 'COMMIT' | 'ROLLBACK';
     rowCount: number;
     rows: R[];
 }

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

@@ -5,6 +5,7 @@ import type { QueryCompiler } from '../../query-compiler/query-compiler.js';
 import type { AbortableOperationOptions } from '../../util/abort.js';
 import type { PostgresClientConstructor, 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);
@@ -25,12 +26,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>;
@@ -57,5 +61,6 @@ declare class PostgresConnection implements DatabaseConnection {
     killSession(controlConnectionProvider: ControlConnectionProvider): Promise<void>;
     streamQuery<O>(compiledQuery: CompiledQuery, chunkSize: number): AsyncIterableIterator<QueryResult<O>>;
     [PRIVATE_RELEASE_METHOD](): void;
+    [PRIVATE_MARK_FOR_DISCARD_METHOD](): void;
 }
 export {};

package/dist/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(options) {
         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 {
         await connection.executeQuery(CompiledQuery.raw(sql));
     }
     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()));
@@ -83,6 +101,7 @@ class PostgresConnection {
     #options;
     #queryId;
     #pid;
+    #discarded;
     constructor(client, options) {
         this.#client = client;
         this.#options = options;
@@ -102,16 +121,21 @@ class PostgresConnection {
             this.#pid = processID;
         }
         else {
+            this.#assertNotDiscarded();
             const { rows: [{ pid }], } = await this.#client.query('select pg_backend_pid() as pid', []);
             this.#pid = Number(pid);
         }
     }
     async executeQuery(compiledQuery) {
+        this.#assertNotDiscarded();
         try {
             // this helps ensure we don't cancel the wrong query when aborted.
             this.#queryId = compiledQuery.queryId;
             const result = await this.#client.query(compiledQuery.sql, compiledQuery.parameters);
             const { command, rowCount, rows } = result;
+            if (command === 'ROLLBACK' || command === 'COMMIT') {
+                return { rows: [{ command }] };
+            }
             return {
                 numAffectedRows: command === 'INSERT' ||
                     command === 'UPDATE' ||
@@ -137,6 +161,7 @@ class PostgresConnection {
         if (!this.#options.cursor) {
             throw new Error("`cursor` is not present in your postgres dialect config. It's required to make streaming work in postgres.");
         }
+        this.#assertNotDiscarded();
         // this helps ensure we don't cancel the wrong query when aborted.
         this.#queryId = compiledQuery.queryId;
         const cursor = this.#client.query(new this.#options.cursor(compiledQuery.sql, compiledQuery.parameters.slice()));
@@ -158,7 +183,15 @@ 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');
+        }
     }
     async #executeControlQuery(query, controlConnectionProvider) {
         if (!this.#queryId) {

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

@@ -9,6 +9,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 | ((options?: AbortableOperationOptions) => Promise<SqliteDatabase>);

package/dist/dialect/sqlite/sqlite-driver.d.ts

@@ -23,6 +23,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/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/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/driver/driver.d.ts

@@ -24,6 +24,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/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/driver/runtime-driver.d.ts

@@ -33,6 +33,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/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/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/index.d.ts

@@ -60,6 +60,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 type * from './driver/database-connection.js';
 export type * from './driver/connection-provider.js';
 export * from './driver/default-connection-provider.js';

package/dist/index.js

@@ -53,6 +53,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/default-connection-provider.js';
 export * from './driver/single-connection-provider.js';
 export * from './driver/dummy-driver.js';

package/dist/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
  *
@@ -450,7 +451,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>;
     /**
@@ -616,6 +626,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
@@ -641,6 +658,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
@@ -666,6 +693,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.
@@ -696,6 +727,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
@@ -727,6 +762,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
@@ -782,8 +821,12 @@ export declare class ControlledTransaction<DB, S extends string[] = []> extends
     $omitTables<T extends keyof DB>(): ControlledTransaction<DB extends object ? Omit<DB, T> : DB, S>;
     $pickTables<T extends keyof DB>(): ControlledTransaction<DB extends object ? Pick<DB, T> : DB, 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;

package/dist/kysely.js

@@ -6,6 +6,7 @@ import { QueryCreator } from './query-creator.js';
 import { DefaultQueryExecutor } from './query-executor/default-query-executor.js';
 import { freeze, isObject, isUndefined } from './util/object-utils.js';
 import { RuntimeDriver } from './driver/runtime-driver.js';
+import { isAbortedTransactionError, } from './driver/aborted-transaction-error.js';
 import { SingleConnectionProvider } from './driver/single-connection-provider.js';
 import { validateTransactionSettings, } from './driver/driver.js';
 import { createFunctionModule, } from './query-builder/function-module.js';
@@ -23,7 +24,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
  *
@@ -505,7 +507,16 @@ export class Kysely extends 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();
@@ -670,8 +681,10 @@ export class TransactionBuilder {
         const settings = { isolationLevel, accessMode };
         validateTransactionSettings(settings);
         return this.#props.executor.provideConnection(async (connection) => {
-            const state = { isCommitted: false, isRolledBack: false };
-            const executor = new NotCommittedOrRolledBackAssertingExecutor(this.#props.executor.withConnectionProvider(new SingleConnectionProvider(connection)), state);
+            const transactionState = {
+                status: 'active',
+            };
+            const executor = new NotCommittedOrRolledBackAssertingExecutor(this.#props.executor.withConnectionProvider(new SingleConnectionProvider(connection)), transactionState);
             const transaction = new Transaction({ ...kyselyProps, executor });
             let transactionBegun = false;
             try {
@@ -679,13 +692,16 @@ export class TransactionBuilder {
                 transactionBegun = true;
                 const result = await callback(transaction);
                 await this.#props.driver.commitTransaction(connection);
-                state.isCommitted = true;
+                transactionState.status = 'committed';
                 return result;
             }
             catch (error) {
-                if (transactionBegun) {
+                if (isAbortedTransactionError(error)) {
+                    transactionState.status = 'aborted';
+                }
+                else if (transactionBegun) {
                     await this.#props.driver.rollbackTransaction(connection);
-                    state.isRolledBack = true;
+                    transactionState.status = 'rolled back';
                 }
                 throw error;
             }
@@ -714,10 +730,17 @@ export class ControlledTransactionBuilder {
         const settings = { isolationLevel, accessMode };
         validateTransactionSettings(settings);
         const connection = await 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,
+            transactionState: { status: 'active' },
             executor: this.#props.executor.withConnectionProvider(new SingleConnectionProvider(connection.connection)),
         });
     }
@@ -725,29 +748,34 @@ export class ControlledTransactionBuilder {
 export class ControlledTransaction extends Transaction {
     #props;
     #compileQuery;
-    #state;
     constructor(props) {
-        const state = { isCommitted: false, isRolledBack: false };
         props = {
             ...props,
-            executor: new NotCommittedOrRolledBackAssertingExecutor(props.executor, state),
+            executor: new NotCommittedOrRolledBackAssertingExecutor(props.executor, props.transactionState),
         };
-        const { connection, ...transactionProps } = props;
+        const { connection, transactionState, ...transactionProps } = props;
         super(transactionProps);
         this.#props = freeze(props);
-        this.#state = state;
         const queryId = createQueryId();
         this.#compileQuery = (node) => props.executor.compileQuery(node, queryId);
     }
     get isCommitted() {
-        return this.#state.isCommitted;
+        return this.#props.transactionState.status === 'committed';
     }
     get isRolledBack() {
-        return this.#state.isRolledBack;
+        return (this.#props.transactionState.status === 'rolled back' ||
+            this.#props.transactionState.status === 'aborted');
     }
     /**
      * 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
@@ -770,16 +798,36 @@ export 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) => {
+                try {
+                    await this.#props.driver.commitTransaction(connection);
+                }
+                catch (error) {
+                    if (isAbortedTransactionError(error)) {
+                        this.#props.transactionState.status = 'aborted';
+                        this.#props.connection.release();
+                    }
+                    throw error;
+                }
+                this.#props.transactionState.status = 'committed';
+                this.#props.connection.release();
+            });
         });
     }
     /**
      * 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
@@ -802,16 +850,29 @@ export 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();
+            if (this.#props.transactionState.status === 'aborted') {
+                return;
+            }
+            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.transactionState.status = 'rolled back';
+                    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.
@@ -839,15 +900,20 @@ export 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
@@ -876,15 +942,20 @@ export 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
@@ -918,9 +989,10 @@ export 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 });
         });
     }
@@ -967,11 +1039,11 @@ export class Command {
         return await this.#cb();
     }
 }
-function assertNotCommittedOrRolledBack(state) {
-    if (state.isCommitted) {
+function assertNotCommittedOrRolledBack(transactionState) {
+    if (transactionState.status === 'committed') {
         throw new Error('Transaction is already committed');
     }
-    if (state.isRolledBack) {
+    if (transactionState.status !== 'active') {
         throw new Error('Transaction is already rolled back');
     }
 }
@@ -983,13 +1055,13 @@ function assertNotCommittedOrRolledBack(state) {
  */
 class NotCommittedOrRolledBackAssertingExecutor {
     #executor;
-    #state;
-    constructor(executor, state) {
+    #transactionState;
+    constructor(executor, transactionState) {
         this.#executor =
             executor instanceof NotCommittedOrRolledBackAssertingExecutor
                 ? executor.#executor
                 : executor;
-        this.#state = state;
+        this.#transactionState = transactionState;
     }
     get adapter() {
         return this.#executor.adapter;
@@ -1004,29 +1076,37 @@ class NotCommittedOrRolledBackAssertingExecutor {
         return this.#executor.compileQuery(node, queryId);
     }
     provideConnection(consumer, options) {
-        return this.#executor.provideConnection(consumer, options);
+        assertNotCommittedOrRolledBack(this.#transactionState);
+        return this.#executor.provideConnection(async (connection) => {
+            assertNotCommittedOrRolledBack(this.#transactionState);
+            return await consumer(connection);
+        }, options);
     }
     executeQuery(compiledQuery, options) {
-        assertNotCommittedOrRolledBack(this.#state);
-        return this.#executor.executeQuery(compiledQuery, options);
+        assertNotCommittedOrRolledBack(this.#transactionState);
+        return this.#executor
+            .withConnectionProvider(this)
+            .executeQuery(compiledQuery, options);
     }
     stream(compiledQuery, chunkSize, options) {
-        assertNotCommittedOrRolledBack(this.#state);
-        return this.#executor.stream(compiledQuery, chunkSize, options);
+        assertNotCommittedOrRolledBack(this.#transactionState);
+        return this.#executor
+            .withConnectionProvider(this)
+            .stream(compiledQuery, chunkSize, options);
     }
     withConnectionProvider(connectionProvider) {
-        return new NotCommittedOrRolledBackAssertingExecutor(this.#executor.withConnectionProvider(connectionProvider), this.#state);
+        return new NotCommittedOrRolledBackAssertingExecutor(this.#executor.withConnectionProvider(connectionProvider), this.#transactionState);
     }
     withPlugin(plugin) {
-        return new NotCommittedOrRolledBackAssertingExecutor(this.#executor.withPlugin(plugin), this.#state);
+        return new NotCommittedOrRolledBackAssertingExecutor(this.#executor.withPlugin(plugin), this.#transactionState);
     }
     withPlugins(plugins) {
-        return new NotCommittedOrRolledBackAssertingExecutor(this.#executor.withPlugins(plugins), this.#state);
+        return new NotCommittedOrRolledBackAssertingExecutor(this.#executor.withPlugins(plugins), this.#transactionState);
     }
     withPluginAtFront(plugin) {
-        return new NotCommittedOrRolledBackAssertingExecutor(this.#executor.withPluginAtFront(plugin), this.#state);
+        return new NotCommittedOrRolledBackAssertingExecutor(this.#executor.withPluginAtFront(plugin), this.#transactionState);
     }
     withoutPlugins() {
-        return new NotCommittedOrRolledBackAssertingExecutor(this.#executor.withoutPlugins(), this.#state);
+        return new NotCommittedOrRolledBackAssertingExecutor(this.#executor.withoutPlugins(), this.#transactionState);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.29.6",
+  "version": "0.29.8",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",
@@ -62,67 +62,67 @@
   ],
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
-    "@electric-sql/pglite": "0.5.8",
+    "@electric-sql/pglite": "0.5.13",
     "@types/better-sqlite3": "9.6.0",
     "@types/chai": "5.2.3",
     "@types/chai-as-promised": "8.0.2",
     "@types/mocha": "10.0.10",
-    "@types/node": "26.2.0",
+    "@types/node": "26.6.6",
     "@types/pg": "8.23.1",
     "@types/pg-cursor": "2.7.2",
     "@types/prototype-pollution-vulnerable-lodash.merge-dont-upgrade": "npm:@types/lodash.merge@4.6.1",
     "@types/semver": "7.8.0",
-    "@types/sinon": "22.0.0",
+    "@types/sinon": "22.0.2",
     "better-sqlite3": "13.0.3",
-    "chai": "6.2.2",
+    "chai": "6.3.0",
     "chai-as-promised": "8.0.2",
     "esbuild": "0.28.2",
     "jsr": "0.14.3",
-    "mocha": "12.0.1",
-    "mysql2": "3.24.4",
+    "mocha": "12.0.3",
+    "mysql2": "3.24.6",
     "pathe": "2.0.3",
-    "pg": "8.23.0",
-    "pg-cursor": "2.22.0",
-    "playwright": "1.63.0",
-    "prettier": "3.9.6",
+    "pg": "8.23.1",
+    "pg-cursor": "2.22.1",
+    "playwright": "1.64.1",
+    "prettier": "3.9.10",
     "prototype-pollution-vulnerable-lodash.merge-dont-upgrade": "npm:lodash.merge@4.6.1",
-    "remeda": "2.50.0",
+    "remeda": "2.57.0",
     "semver": "7.8.5",
     "sinon": "22.1.0",
     "tarn": "3.1.2",
-    "tedious": "20.0.0",
+    "tedious": "20.3.8",
     "tsd": "0.33.0",
-    "tsx": "4.23.13",
+    "tsx": "4.23.15",
     "typescript": "7.0.2",
     "typescript-6": "npm:typescript@6.0.3"
   },
   "scripts": {
     "clean": "rm -rf dist & rm -rf test/node/dist & rm -rf test/browser/bundle.js",
-    "bench:ts": "pnpm build && node --experimental-strip-types ./test/ts-benchmarks/index.ts",
-    "test": "pnpm build && pnpm test:node:build && pnpm test:node:run && pnpm test:typings && pnpm test:esmimports && pnpm test:exports",
+    "bench:ts": "pnpm run build && node --experimental-strip-types ./test/ts-benchmarks/index.ts",
+    "test": "pnpm run build && pnpm run test:node:build && pnpm run test:node:run && pnpm run test:typings && pnpm run test:esmimports && pnpm run test:exports",
     "test:node:build": "tsc -p test/node",
-    "test:node": "pnpm build && pnpm test:node:build && pnpm test:node:run",
+    "test:node": "pnpm run build && pnpm run test:node:build && pnpm run test:node:run",
     "test:node:run": "mocha --timeout 15000 test/node/dist/**/*.test.js",
     "test:browser:build": "rm -rf test/browser/bundle.js && esbuild test/browser/main.ts --bundle --outfile=test/browser/bundle.js",
-    "test:browser": "pnpm build && pnpm test:browser:build && node test/browser/test.js",
-    "test:bun": "pnpm build && bun link && cd test/bun && bun install && bun run test",
-    "test:cloudflare-workers": "pnpm build && pnpm -r test --filter kysely-cloudflare-workers-test",
+    "test:browser": "pnpm run build && pnpm run test:browser:build && node test/browser/test.js",
+    "test:bun": "pnpm run build && bun link && cd test/bun && bun install && bun run test",
+    "test:cloudflare-workers": "pnpm run build && pnpm -r --filter kysely-cloudflare-workers-test run test",
     "test:deno": "deno run --allow-env --allow-read --allow-net --no-lock test/deno/test.ts",
     "test:typings": "tsd test/typings",
     "test:esmimports": "node scripts/check-esm-imports.cjs",
     "test:esbuild": "esbuild --bundle --platform=node --external:pg-native dist/index.js --outfile=/dev/null",
     "test:exports": "attw --profile esm-only --pack . && node scripts/check-exports.cjs",
     "test:jsdocs": "deno check --doc-only --no-lock --unstable-sloppy-imports --config=\"deno.check.json\" ./src",
-    "test:outdatedts": "pnpm build && cd test/outdated-ts && pnpm i && pnpm test",
+    "test:outdatedts": "pnpm run build && cd test/outdated-ts && pnpm i && pnpm run test",
     "lint:deno": "deno lint --config=\"deno.lint.json\" ./src",
     "prettier": "prettier --write 'src/**/*.ts' 'test/**/*.ts'",
-    "build": "pnpm clean && tsc && pnpm script:add-deno-type-references && pnpm script:copy-interface-doc",
+    "build": "pnpm run clean && tsc && pnpm run script:add-deno-type-references && pnpm run script:copy-interface-doc",
     "script:copy-interface-doc": "node scripts/copy-interface-documentation.cjs",
     "script:add-deno-type-references": "node scripts/add-deno-type-references.cjs",
     "script:align-versions": "node --experimental-strip-types scripts/align-versions.mts",
     "script:generate-site-examples": "node scripts/generate-site-examples.mts",
     "script:override-tsconfig-target": "node --experimental-strip-types scripts/override-tsconfig-target.mts",
     "script:remove-global-augmentations": "node --experimental-strip-types scripts/remove-global-augmentations.mts",
-    "version": "pnpm script:align-versions && git add ."
+    "version": "pnpm run script:align-versions && git add ."
   }
 }