kysely 0.28.17 → 0.28.19

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.19)](https://socket.dev/npm/package/kysely/overview/0.28.19)
 [![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/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/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/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/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>);
@@ -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/cjs/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/cjs/dialect/postgres/postgres-driver.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostgresDriver = void 0;
+const aborted_transaction_error_js_1 = require("../../driver/aborted-transaction-error.js");
 const savepoint_parser_js_1 = require("../../parser/savepoint-parser.js");
 const compiled_query_js_1 = require("../../query-compiler/compiled-query.js");
 const object_utils_js_1 = require("../../util/object-utils.js");
 const query_id_js_1 = require("../../util/query-id.js");
 const stack_trace_utils_js_1 = require("../../util/stack-trace-utils.js");
 const PRIVATE_RELEASE_METHOD = Symbol();
+const PRIVATE_MARK_FOR_DISCARD_METHOD = Symbol();
 class PostgresDriver {
     #config;
     #connections = new WeakMap();
@@ -21,6 +23,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, {
@@ -55,10 +62,21 @@ class PostgresDriver {
         }
     }
     async commitTransaction(connection) {
-        await connection.executeQuery(compiled_query_js_1.CompiledQuery.raw('commit'));
+        const { rows } = await connection.executeQuery(compiled_query_js_1.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 aborted_transaction_error_js_1.AbortedTransactionError();
+        }
     }
     async rollbackTransaction(connection) {
-        await connection.executeQuery(compiled_query_js_1.CompiledQuery.raw('rollback'));
+        try {
+            await connection.executeQuery(compiled_query_js_1.CompiledQuery.raw('rollback'));
+        }
+        catch (err) {
+            connection[PRIVATE_MARK_FOR_DISCARD_METHOD]();
+            throw err;
+        }
     }
     async savepoint(connection, savepointName, compileQuery) {
         await connection.executeQuery(compileQuery((0, savepoint_parser_js_1.parseSavepointCommand)('savepoint', savepointName), (0, query_id_js_1.createQueryId)()));
@@ -84,13 +102,18 @@ exports.PostgresDriver = 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' ||
@@ -112,6 +135,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) {
@@ -129,6 +153,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/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/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/cjs/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/cjs/driver/aborted-transaction-error.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbortedTransactionError = void 0;
+exports.isAbortedTransactionError = isAbortedTransactionError;
+const object_utils_js_1 = require("../util/object-utils.js");
+const ABORTED_TRANSACTION_ERROR = Symbol.for('kysely.AbortedTransactionError');
+/**
+ * Thrown when the database rolls back a transaction instead of committing it.
+ */
+class AbortedTransactionError extends Error {
+    name = 'AbortedTransactionError';
+    [ABORTED_TRANSACTION_ERROR] = true;
+    constructor() {
+        super('Transaction was rolled back instead of committed');
+    }
+}
+exports.AbortedTransactionError = AbortedTransactionError;
+function isAbortedTransactionError(error) {
+    return (0, object_utils_js_1.isObject)(error) && ABORTED_TRANSACTION_ERROR in error;
+}

package/dist/cjs/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/cjs/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/cjs/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/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/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/cjs/index.js

@@ -75,6 +75,7 @@ __exportStar(require("./dynamic/dynamic.js"), exports);
 __exportStar(require("./dynamic/dynamic-reference-builder.js"), exports);
 __exportStar(require("./dynamic/dynamic-table-builder.js"), exports);
 __exportStar(require("./driver/driver.js"), exports);
+__exportStar(require("./driver/aborted-transaction-error.js"), exports);
 __exportStar(require("./driver/database-connection.js"), exports);
 __exportStar(require("./driver/connection-provider.js"), exports);
 __exportStar(require("./driver/default-connection-provider.js"), exports);

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,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;