kysely 0.29.7 → 0.29.9

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.7)](https://socket.dev/npm/package/kysely/overview/0.29.7)
+[![Socket Badge](https://badge.socket.dev/npm/package/kysely/0.29.9)](https://socket.dev/npm/package/kysely/overview/0.29.9)
 [![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-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-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/pglite/pglite-driver.js

@@ -1,8 +1,9 @@
 /// <reference types="./pglite-driver.d.ts" />
+import { AbortedTransactionError } from '../../driver/aborted-transaction-error.js';
 import { parseSavepointCommand } from '../../parser/savepoint-parser.js';
 import { waitOrAbort, } from '../../util/abort.js';
 import { Deferred } from '../../util/deferred.js';
-import { freeze, isFunction } from '../../util/object-utils.js';
+import { freeze, isFunction, isObject } from '../../util/object-utils.js';
 import { createQueryId } from '../../util/query-id.js';
 import { extendStackTrace } from '../../util/stack-trace-utils.js';
 const PRIVATE_BEGIN_TRANSACTION_METHOD = Symbol();
@@ -102,11 +103,22 @@ class PGliteConnection {
     }
     async [PRIVATE_COMMIT_TRANSACTION_METHOD]() {
         this.#commitTransaction?.();
-        await this.#transactionClosedPromise;
-        this.#commitTransaction = undefined;
-        this.#rollbackTransaction = undefined;
-        this.#transaction = undefined;
-        this.#transactionClosedPromise = undefined;
+        try {
+            await this.#transactionClosedPromise;
+        }
+        catch (error) {
+            // https://github.com/electric-sql/pglite/blob/bac163ecc92e968adda68864b74b7e3d65a68e97/packages/pglite/src/errors.ts#L11-L17
+            if (isObject(error) && 'code' in error && error.code === '25P02') {
+                throw new AbortedTransactionError({ cause: error });
+            }
+            throw error;
+        }
+        finally {
+            this.#commitTransaction = undefined;
+            this.#rollbackTransaction = undefined;
+            this.#transaction = undefined;
+            this.#transactionClosedPromise = undefined;
+        }
     }
     async [PRIVATE_ROLLBACK_TRANSACTION_METHOD]() {
         this.#rollbackTransaction?.();

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

@@ -95,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.
@@ -124,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();
@@ -58,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()));
@@ -88,6 +101,7 @@ class PostgresConnection {
     #options;
     #queryId;
     #pid;
+    #discarded;
     constructor(client, options) {
         this.#client = client;
         this.#options = options;
@@ -107,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' ||
@@ -142,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()));
@@ -163,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-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(options?: ErrorOptions);
+}
+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(options) {
+        super('Transaction was rolled back instead of committed', options);
+    }
+}
+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/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

@@ -477,6 +477,54 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
     /**
      * Executes a given compiled query or query builder.
      *
+     * Returns a {@link QueryResult} containing `rows` and any metadata provided
+     * by the dialect, such as `numAffectedRows` or `insertId`.
+     * Unlike a query builder's `execute`, this method doesn't wrap write metadata
+     * in an {@link InsertResult}, {@link UpdateResult} or {@link DeleteResult}.
+     * Without `returning` or `output`, a write normally has an empty `rows` array.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const query = db
+     *   .selectFrom('person')
+     *   .select(['id', 'first_name'])
+     *   .where('id', '=', 123)
+     *   .compile()
+     *
+     * const { rows } = await db.executeQuery(query)
+     * console.log(rows[0]?.first_name)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name"
+     * from "person"
+     * where "id" = $1
+     * ```
+     *
+     * Read metadata from a write query:
+     *
+     * ```ts
+     * const query = db
+     *   .updateTable('person')
+     *   .set({ first_name: 'Jennifer' })
+     *   .where('id', '=', 123)
+     *   .compile()
+     *
+     * const { numAffectedRows } = await db.executeQuery(query)
+     * console.log(numAffectedRows)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "person"
+     * set "first_name" = $1
+     * where "id" = $2
+     * ```
+     *
      * See {@link https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0004-splitting-query-building-and-execution.md#execute-compiled-queries splitting build, compile and execute code recipe} for more information.
      */
     executeQuery<R>(query: CompiledQuery<R> | Compilable<R>, options?: AbortableQueryOptions): Promise<QueryResult<R>>;
@@ -626,6 +674,9 @@ 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.
@@ -655,6 +706,9 @@ 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.
      *
@@ -815,13 +869,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 ControlledTransctionState {
-    isCommitted: boolean;
-    isRolledBack: boolean;
+interface ControlledTransactionState {
+    status: 'active' | 'committed' | 'rolled back' | 'aborted';
 }
 interface ControlledTransactionProps extends KyselyProps {
     readonly connection: ControlledConnection;
-    readonly state: ControlledTransctionState;
+    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';
@@ -538,6 +539,54 @@ export class Kysely extends QueryCreator {
     /**
      * Executes a given compiled query or query builder.
      *
+     * Returns a {@link QueryResult} containing `rows` and any metadata provided
+     * by the dialect, such as `numAffectedRows` or `insertId`.
+     * Unlike a query builder's `execute`, this method doesn't wrap write metadata
+     * in an {@link InsertResult}, {@link UpdateResult} or {@link DeleteResult}.
+     * Without `returning` or `output`, a write normally has an empty `rows` array.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const query = db
+     *   .selectFrom('person')
+     *   .select(['id', 'first_name'])
+     *   .where('id', '=', 123)
+     *   .compile()
+     *
+     * const { rows } = await db.executeQuery(query)
+     * console.log(rows[0]?.first_name)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name"
+     * from "person"
+     * where "id" = $1
+     * ```
+     *
+     * Read metadata from a write query:
+     *
+     * ```ts
+     * const query = db
+     *   .updateTable('person')
+     *   .set({ first_name: 'Jennifer' })
+     *   .where('id', '=', 123)
+     *   .compile()
+     *
+     * const { numAffectedRows } = await db.executeQuery(query)
+     * console.log(numAffectedRows)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "person"
+     * set "first_name" = $1
+     * where "id" = $2
+     * ```
+     *
      * See {@link https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0004-splitting-query-building-and-execution.md#execute-compiled-queries splitting build, compile and execute code recipe} for more information.
      */
     async executeQuery(query, options) {
@@ -680,8 +729,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 {
@@ -689,13 +740,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;
             }
@@ -734,7 +788,7 @@ export class ControlledTransactionBuilder {
         return new ControlledTransaction({
             ...props,
             connection,
-            state: { isCommitted: false, isRolledBack: false },
+            transactionState: { status: 'active' },
             executor: this.#props.executor.withConnectionProvider(new SingleConnectionProvider(connection.connection)),
         });
     }
@@ -745,23 +799,27 @@ export class ControlledTransaction extends Transaction {
     constructor(props) {
         props = {
             ...props,
-            executor: new NotCommittedOrRolledBackAssertingExecutor(props.executor, props.state),
+            executor: new NotCommittedOrRolledBackAssertingExecutor(props.executor, props.transactionState),
         };
-        const { connection, state, ...transactionProps } = props;
+        const { connection, transactionState, ...transactionProps } = props;
         super(transactionProps);
         this.#props = freeze(props);
         const queryId = createQueryId();
         this.#compileQuery = (node) => props.executor.compileQuery(node, queryId);
     }
     get isCommitted() {
-        return this.#props.state.isCommitted;
+        return this.#props.transactionState.status === 'committed';
     }
     get isRolledBack() {
-        return this.#props.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.
@@ -790,8 +848,17 @@ export class ControlledTransaction extends Transaction {
     commit() {
         return new Command(async () => {
             await this.#props.executor.provideConnection(async (connection) => {
-                await this.#props.driver.commitTransaction(connection);
-                this.#props.state.isCommitted = true;
+                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();
             });
         });
@@ -799,6 +866,9 @@ export class ControlledTransaction extends Transaction {
     /**
      * 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.
      *
@@ -829,13 +899,16 @@ export class ControlledTransaction extends Transaction {
      */
     rollback() {
         return new Command(async () => {
+            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.state.isRolledBack = true;
+                    this.#props.transactionState.status = 'rolled back';
                     this.#props.connection.release();
                 }
             });
@@ -1014,11 +1087,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');
     }
 }
@@ -1030,13 +1103,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;
@@ -1051,37 +1124,37 @@ class NotCommittedOrRolledBackAssertingExecutor {
         return this.#executor.compileQuery(node, queryId);
     }
     provideConnection(consumer, options) {
-        assertNotCommittedOrRolledBack(this.#state);
+        assertNotCommittedOrRolledBack(this.#transactionState);
         return this.#executor.provideConnection(async (connection) => {
-            assertNotCommittedOrRolledBack(this.#state);
+            assertNotCommittedOrRolledBack(this.#transactionState);
             return await consumer(connection);
         }, options);
     }
     executeQuery(compiledQuery, options) {
-        assertNotCommittedOrRolledBack(this.#state);
+        assertNotCommittedOrRolledBack(this.#transactionState);
         return this.#executor
             .withConnectionProvider(this)
             .executeQuery(compiledQuery, options);
     }
     stream(compiledQuery, chunkSize, options) {
-        assertNotCommittedOrRolledBack(this.#state);
+        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/dist/migration/file-migration-provider.d.ts

@@ -2,11 +2,21 @@ import type { Migration, MigrationProvider } from './migrator.js';
 /**
  * Reads all migrations from a folder.
  *
+ * Loads `.js`, `.ts`, `.mjs`, `.mts`, `.cjs` and `.cts` files, excluding
+ * TypeScript declaration files. Loading TypeScript requires a runtime or
+ * loader that supports it. Subdirectories are not scanned.
+ *
+ * A module must export an `up` function, either as a named export or as part
+ * of a default export object. The filename without its extension is used as
+ * the migration name. See {@link FileMigrationProviderProps.onFileIgnored}
+ * to report files that aren't loaded.
+ *
  * ### Examples
  *
  * ```ts
  * import { promises as fs } from 'node:fs'
  * import path from 'node:path'
+ * import { FileMigrationProvider } from 'kysely/migration'
  *
  * new FileMigrationProvider({
  *   fs,
@@ -43,9 +53,65 @@ export interface FileMigrationProviderPath {
     join(...path: string[]): string;
 }
 export interface FileMigrationProviderProps {
+    /**
+     * Provides the directory listing. For Node.js, use `promises` from `node:fs`.
+     */
     fs: FileMigrationProviderFS;
+    /**
+     * Overrides how migration modules are imported. Receives the joined file path
+     * and returns the module exports. Defaults to a dynamic `import`.
+     *
+     * ### Examples
+     *
+     * Use a file URL when importing absolute paths in Node.js:
+     *
+     * ```ts
+     * import { promises as fs } from 'node:fs'
+     * import path from 'node:path'
+     * import { pathToFileURL } from 'node:url'
+     * import { FileMigrationProvider } from 'kysely/migration'
+     *
+     * const provider = new FileMigrationProvider({
+     *   fs,
+     *   path,
+     *   migrationFolder: path.resolve('migrations'),
+     *   import: (filePath) => import(pathToFileURL(filePath).href),
+     * })
+     * ```
+     */
     import?(module: string): Promise<any>;
+    /**
+     * The path to the migration directory. Use an absolute path to avoid
+     * depending on the current working directory.
+     */
     migrationFolder: string;
+    /**
+     * Called when a directory entry is ignored.
+     *
+     * `Extension` means the filename doesn't have a supported extension.
+     * `NotMigration` means the imported module has no supported `up` export.
+     * Import errors are thrown instead of being reported through this callback.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { promises as fs } from 'node:fs'
+     * import path from 'node:path'
+     * import { FileMigrationProvider } from 'kysely/migration'
+     *
+     * const provider = new FileMigrationProvider({
+     *   fs,
+     *   path,
+     *   migrationFolder: path.resolve('migrations'),
+     *   onFileIgnored(fileName, reason) {
+     *     console.log(`Ignored ${fileName}: ${reason}`)
+     *   },
+     * })
+     * ```
+     */
     onFileIgnored?(fileName: string, reason: 'Extension' | 'NotMigration'): void;
+    /**
+     * Provides path joining. For Node.js, use `node:path`.
+     */
     path: FileMigrationProviderPath;
 }

package/dist/migration/file-migration-provider.js

@@ -3,11 +3,21 @@ import { isFunction, isObject } from '../util/object-utils.js';
 /**
  * Reads all migrations from a folder.
  *
+ * Loads `.js`, `.ts`, `.mjs`, `.mts`, `.cjs` and `.cts` files, excluding
+ * TypeScript declaration files. Loading TypeScript requires a runtime or
+ * loader that supports it. Subdirectories are not scanned.
+ *
+ * A module must export an `up` function, either as a named export or as part
+ * of a default export object. The filename without its extension is used as
+ * the migration name. See {@link FileMigrationProviderProps.onFileIgnored}
+ * to report files that aren't loaded.
+ *
  * ### Examples
  *
  * ```ts
  * import { promises as fs } from 'node:fs'
  * import path from 'node:path'
+ * import { FileMigrationProvider } from 'kysely/migration'
  *
  * new FileMigrationProvider({
  *   fs,

package/dist/migration/migrator.d.ts

@@ -386,6 +386,16 @@ export interface MigrationInfo {
     /**
      * When was the migration executed.
      *
+     * In most cases, this is the time on the machine running the migrator when
+     * the migration was applied (as reported by `Date.now()`), not the database
+     * server's time.
+     * Execution timestamps are used to determine the order in which migrations
+     * were executed, so they never go backwards. If the machine clock is behind
+     * the latest recorded execution timestamp (e.g. it was stepped back by an NTP
+     * sync, it drifted from the clock of another machine running migrations, or
+     * it was ahead when a previous migration was applied), the migration is
+     * recorded 1 millisecond after the latest recorded execution timestamp instead.
+     *
      * If this is undefined, the migration hasn't been executed yet.
      */
     executedAt?: Date;

package/dist/migration/migrator.js

@@ -1,12 +1,14 @@
 /// <reference types="./migrator.d.ts" />
 import { NoopPlugin } from '../plugin/noop-plugin.js';
 import { WithSchemaPlugin } from '../plugin/with-schema/with-schema-plugin.js';
+import { warnOnce } from '../util/log-once.js';
 import { freeze, getLast, isObject } from '../util/object-utils.js';
 export const DEFAULT_MIGRATION_TABLE = 'kysely_migration';
 export const DEFAULT_MIGRATION_LOCK_TABLE = 'kysely_migration_lock';
 export const DEFAULT_ALLOW_UNORDERED_MIGRATIONS = false;
 export const MIGRATION_LOCK_ID = 'migration_lock';
 export const NO_MIGRATIONS = freeze({ __noMigrations__: true });
+const CLOCK_BEHIND_WARNING_THRESHOLD_MILLISECONDS = 1_000;
 /**
  * A class for running migrations.
  *
@@ -448,7 +450,7 @@ export class Migrator {
     }
     async #getState(db) {
         const migrations = await this.#resolveMigrations();
-        const executedMigrations = await this.#getExecutedMigrations(db);
+        const { executedMigrations, maxExecutedAt } = await this.#getExecutedMigrations(db);
         this.#ensureNoMissingMigrations(migrations, executedMigrations);
         if (!this.#allowUnorderedMigrations) {
             this.#ensureMigrationsInOrder(migrations, executedMigrations);
@@ -458,6 +460,7 @@ export class Migrator {
             migrations,
             executedMigrations,
             lastMigration: getLast(executedMigrations),
+            maxExecutedAt,
             pendingMigrations,
         });
     }
@@ -476,22 +479,44 @@ export class Migrator {
         }));
     }
     async #getExecutedMigrations(db) {
-        const executedMigrations = await db
+        const rows = await db
             .withPlugin(this.#schemaPlugin)
             .selectFrom(this.#migrationTable)
             .select(['name', 'timestamp'])
             .$narrowType()
             .execute();
+        if (rows.length === 0) {
+            return { executedMigrations: [], maxExecutedAt: 0 };
+        }
+        if (rows.length === 1) {
+            const [{ name, timestamp }] = rows;
+            return {
+                executedMigrations: [name],
+                maxExecutedAt: this.#getExecutedAt(name, timestamp),
+            };
+        }
         const nameComparator = this.#props.nameComparator || ((a, b) => a.localeCompare(b));
-        return (executedMigrations
+        let maxExecutedAt = 0;
+        const executedMigrations = rows
             // https://github.com/kysely-org/kysely/issues/843
             .sort((a, b) => {
-            if (a.timestamp === b.timestamp) {
+            const aExecutedAt = this.#getExecutedAt(a.name, a.timestamp);
+            const bExecutedAt = this.#getExecutedAt(b.name, b.timestamp);
+            maxExecutedAt = Math.max(maxExecutedAt, aExecutedAt, bExecutedAt);
+            if (aExecutedAt === bExecutedAt) {
                 return nameComparator(a.name, b.name);
             }
-            return (new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+            return aExecutedAt - bExecutedAt;
         })
-            .map((it) => it.name));
+            .map((it) => it.name);
+        return { executedMigrations, maxExecutedAt };
+    }
+    #getExecutedAt(name, timestamp) {
+        const executedAt = new Date(timestamp).getTime();
+        if (Number.isNaN(executedAt)) {
+            throw new Error(`corrupted migrations: previously executed migration ${name} has an invalid timestamp ${timestamp}`);
+        }
+        return executedAt;
     }
     #ensureNoMissingMigrations(migrations, executedMigrations) {
         // Ensure all executed migrations exist in the `migrations` list.
@@ -563,16 +588,18 @@ export class Migrator {
                 status: 'NotExecuted',
             };
         });
+        let { maxExecutedAt } = state;
         for (let i = 0; i < results.length; i++) {
             const migration = state.pendingMigrations[i];
             try {
                 await migration.up(db);
+                maxExecutedAt = this.#getNextExecutedAt(maxExecutedAt);
                 await db
                     .withPlugin(this.#schemaPlugin)
                     .insertInto(this.#migrationTable)
                     .values({
                     name: migration.name,
-                    timestamp: new Date().toISOString(),
+                    timestamp: new Date(maxExecutedAt).toISOString(),
                 })
                     .execute();
                 results[i] = {
@@ -601,6 +628,17 @@ export class Migrator {
         }
         await qb.execute();
     }
+    // https://github.com/kysely-org/kysely/issues/2244
+    #getNextExecutedAt(maxExecutedAt) {
+        const now = Date.now();
+        if (now > maxExecutedAt) {
+            return now;
+        }
+        if (maxExecutedAt - now >= CLOCK_BEHIND_WARNING_THRESHOLD_MILLISECONDS) {
+            warnOnce('The machine clock is behind the latest migration `executedAt`. Recording migrations 1 millisecond after it instead.');
+        }
+        return maxExecutedAt + 1;
+    }
 }
 class MigrationResultSetError extends Error {
     #resultSet;

package/dist/plugin/with-schema/with-schema-transformer.js

@@ -78,10 +78,7 @@ export class WithSchemaTransformer extends OperationNodeTransformer {
         return {
             ...super.transformSelectModifier({ ...node, of: undefined }, queryId),
             of: node.of?.map((item) => TableNode.is(item) && !item.table.schema
-                ? {
-                    ...item,
-                    table: this.transformIdentifier(item.table.identifier, queryId),
-                }
+                ? this.#transformTableWithoutSchema(item, queryId)
                 : this.transformNode(item, queryId)),
         };
     }
@@ -89,12 +86,18 @@ export class WithSchemaTransformer extends OperationNodeTransformer {
         return SCHEMALESS_FUNCTIONS[node.func]
             ? node[argsKey].map((arg) => !TableNode.is(arg) || arg.table.schema
                 ? this.transformNode(arg, queryId)
-                : {
-                    ...arg,
-                    table: this.transformIdentifier(arg.table.identifier, queryId),
-                })
+                : this.#transformTableWithoutSchema(arg, queryId))
             : this.transformNodeList(node[argsKey], queryId);
     }
+    #transformTableWithoutSchema(node, queryId) {
+        return {
+            ...node,
+            table: {
+                ...node.table,
+                identifier: this.transformIdentifier(node.table.identifier, queryId),
+            },
+        };
+    }
     #collectSchemableIds(node) {
         const schemableIds = new Set();
         if ('name' in node && node.name && SchemableIdentifierNode.is(node.name)) {

package/dist/query-builder/json-path-builder.d.ts

@@ -73,7 +73,7 @@ export declare class JSONPathBuilder<S, O = S> {
      * select "nicknames"->>'$[#-1]' as `last_nickname` from `person`
      * ```
      */
-    at<I extends (any[] extends O ? number | 'last' | `#-${number}` : never), O2 = null | NonNullable<NonNullable<O>[keyof NonNullable<O> & number]>>(index: `${I}` extends `${any}.${any}` | `#--${any}` ? never : I): TraversedJSONPathBuilder<S, O2>;
+    at<I extends (any[] extends O ? number | 'last' | `#-${number}` : never)>(index: `${I}` extends `${any}.${any}` | `#--${any}` ? never : I): TraversedJSONPathBuilder<S, JSONArrayElementType<O>>;
     /**
      * Access a property of a JSON object.
      *
@@ -123,7 +123,7 @@ export declare class JSONPathBuilder<S, O = S> {
      * select "profile"->'addresses'->0->'city' as "city" from "person"
      * ```
      */
-    key<K extends (any[] extends O ? never : O extends object ? keyof NonNullable<O> & string : never), O2 = undefined extends O ? null | NonNullable<NonNullable<O>[K]> : null extends O ? null | NonNullable<NonNullable<O>[K]> : string extends keyof NonNullable<O> ? null | NonNullable<NonNullable<O>[K]> : NonNullable<O>[K]>(key: K): TraversedJSONPathBuilder<S, O2>;
+    key<K extends (any[] extends O ? never : O extends object ? keyof NonNullable<O> & string : never)>(key: K): TraversedJSONPathBuilder<S, JSONObjectValueType<O, K>>;
 }
 export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O> implements AliasableExpression<O> {
     #private;
@@ -292,3 +292,6 @@ export declare class AliasedJSONPathBuilder<O, A extends string> implements Alia
      */
     toOperationNode(): AliasNode;
 }
+type JSONArrayElementType<O> = null | NonNullable<NonNullable<O>[keyof NonNullable<O> & number]>;
+type JSONObjectValueType<O, K extends keyof NonNullable<O>> = undefined extends O ? null | NonNullable<NonNullable<O>[K]> : null extends O ? null | NonNullable<NonNullable<O>[K]> : string extends keyof NonNullable<O> ? null | NonNullable<NonNullable<O>[K]> : NonNullable<O>[K];
+export {};

package/dist/query-compiler/compiled-query.d.ts

@@ -1,13 +1,85 @@
 import { type RootOperationNode } from '../operation-node/root-operation-node.js';
 import { type QueryId } from '../util/query-id.js';
+/**
+ * A SQL query compiled for a specific dialect, together with its parameters
+ * and operation node tree.
+ *
+ * The output type `O` describes a result row. It doesn't validate or convert
+ * values returned by the database driver.
+ *
+ * Query builders create compiled queries with {@link Compilable.compile | compile()},
+ * and {@link RawBuilder}s with `compile(db)`. Compiling doesn't execute the query.
+ *
+ * See {@link Kysely.executeQuery} for execution and {@link CompiledQuery.raw}
+ * for constructing a query from an existing SQL string.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * const compiledQuery = db
+ *   .selectFrom('person')
+ *   .select('first_name')
+ *   .where('id', '=', 123)
+ *   .compile()
+ *
+ * console.log(compiledQuery.sql) // select "first_name" from "person" where "id" = $1
+ * console.log(compiledQuery.parameters) // [123]
+ * ```
+ */
 export interface CompiledQuery<O = unknown> {
+    /**
+     * The operation node tree used to compile the query, after query plugins have run.
+     */
     readonly query: RootOperationNode;
+    /**
+     * Identifies the query when passing data between plugin hooks.
+     */
     readonly queryId: QueryId;
+    /**
+     * The SQL string, with placeholders in the target dialect's syntax.
+     */
     readonly sql: string;
+    /**
+     * The parameter values in the order expected by the placeholders in {@link CompiledQuery.sql | sql}.
+     */
     readonly parameters: ReadonlyArray<unknown>;
 }
 export declare function isCompiledQuery<R>(thing: unknown): thing is CompiledQuery<R>;
 type CompiledQueryFactory = Readonly<{
+    /**
+     * Creates a compiled query from an existing SQL string and parameter values.
+     *
+     * The SQL is used as provided. This method doesn't escape SQL, generate
+     * placeholders, or check that the parameters match the placeholders.
+     * Use the target dialect's placeholder syntax, such as `$1` for PostgreSQL
+     * or `?` for MySQL and SQLite. For SQL built from interpolated values,
+     * prefer the {@link sql} template tag.
+     *
+     * ### Examples
+     *
+     * Execute a parameterized PostgreSQL query:
+     *
+     * ```ts
+     * import { CompiledQuery } from 'kysely'
+     *
+     * const result = await db.executeQuery<{ first_name: string }>(
+     *   CompiledQuery.raw(
+     *     'select "first_name" from "person" where "id" = $1',
+     *     [123],
+     *   ),
+     * )
+     *
+     * const firstName: string | undefined = result.rows[0]?.first_name
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "first_name"
+     * from "person"
+     * where "id" = $1
+     * ```
+     */
     raw(sql: string, parameters?: unknown[]): Readonly<CompiledQuery>;
 }>;
 export declare const CompiledQuery: CompiledQueryFactory;

package/dist/util/log-once.d.ts

@@ -3,3 +3,8 @@
  * Logs a message and ensures it won't be logged again.
  */
 export declare function logOnce(message: string): void;
+/**
+ * Use for system-level warnings.
+ * Logs a warning and ensures it won't be logged again.
+ */
+export declare function warnOnce(message: string): void;

package/dist/util/log-once.js

@@ -11,3 +11,14 @@ export function logOnce(message) {
     LOGGED_MESSAGES.add(message);
     console.log(message);
 }
+/**
+ * Use for system-level warnings.
+ * Logs a warning and ensures it won't be logged again.
+ */
+export function warnOnce(message) {
+    if (LOGGED_MESSAGES.has(message)) {
+        return;
+    }
+    LOGGED_MESSAGES.add(message);
+    console.warn(message);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.29.7",
+  "version": "0.29.9",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",
@@ -62,17 +62,17 @@
   ],
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
-    "@electric-sql/pglite": "0.5.10",
+    "@electric-sql/pglite": "0.5.16",
     "@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.6.5",
+    "@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.3.0",
     "chai-as-promised": "8.0.2",
@@ -83,14 +83,14 @@
     "pathe": "2.0.3",
     "pg": "8.23.1",
     "pg-cursor": "2.22.1",
-    "playwright": "1.64.1",
+    "playwright": "1.65.0",
     "prettier": "3.9.10",
     "prototype-pollution-vulnerable-lodash.merge-dont-upgrade": "npm:lodash.merge@4.6.1",
-    "remeda": "2.51.0",
-    "semver": "7.8.5",
+    "remeda": "2.59.0",
+    "semver": "7.8.6",
     "sinon": "22.1.0",
     "tarn": "3.1.2",
-    "tedious": "20.3.7",
+    "tedious": "20.3.8",
     "tsd": "0.33.0",
     "tsx": "4.23.15",
     "typescript": "7.0.2",