kysely 0.29.4 → 0.30.0-beta.1

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

@@ -5,23 +5,25 @@ import type { AbortableOperationOptions } from '../../util/abort.js';
  */
 export interface MysqlDialectConfig {
     /**
-     * A `mysql2` `Client` constructor, to be used for connecting to the database
-     * outside of the `pool` to avoid waiting for an idle connection.
+     * A `createConnection` function (from either `mysql2` or `mysql2/promise`),
+     * to be used for connecting to the database outside of the `pool` to avoid
+     * waiting for an idle connection.
      *
      * This is useful for cancelling queries on the database side.
      */
     controlConnection?: {
-        (connectionUri: string): MysqlConnection;
-        (config: object): MysqlConnection;
+        (connectionUri: string): MysqlConnection | Promise<MysqlPromiseConnection>;
+        (config: object): MysqlConnection | Promise<MysqlPromiseConnection>;
     };
     /**
-     * A mysql2 Pool instance or a function that returns one.
+     * A mysql2 Pool instance (from either `mysql2` or `mysql2/promise`) or a
+     * function that returns one.
      *
      * If a function is provided, it's called once when the first query is executed.
      *
      * https://github.com/sidorares/node-mysql2#using-connection-pools
      */
-    pool: MysqlPool | ((options?: AbortableOperationOptions) => Promise<MysqlPool>);
+    pool: MysqlPool | MysqlPromisePool | ((options?: AbortableOperationOptions) => Promise<MysqlPool | MysqlPromisePool>);
     /**
      * Called once for each created connection.
      */
@@ -43,6 +45,17 @@ export interface MysqlPool {
     getConnection(callback: (error: unknown, connection: MysqlPoolConnection) => void): void;
     end(callback: (error: unknown) => void): void;
 }
+/**
+ * This interface is the subset of `mysql2/promise`'s `Pool` class that
+ * kysely needs.
+ *
+ * It's a thin promise wrapper around the callback pool, which it exposes
+ * as its `pool` property. The dialect unwraps it and uses the callback
+ * pool directly.
+ */
+export interface MysqlPromisePool {
+    pool: MysqlPool;
+}
 export interface MysqlConnection {
     config: object;
     connect(callback?: (error: unknown) => void): void;
@@ -52,6 +65,18 @@ export interface MysqlConnection {
     };
     threadId: number;
 }
+/**
+ * This interface is the subset of `mysql2/promise`'s `Connection` class that
+ * kysely needs.
+ *
+ * It's a thin promise wrapper around the callback connection. It's already
+ * connected when the `createConnection` promise resolves, so the dialect
+ * uses its promise-based API directly.
+ */
+export interface MysqlPromiseConnection {
+    destroy(): void;
+    query(sql: string, values?: unknown[]): Promise<unknown>;
+}
 export type MysqlConectionConstructor = new (opts?: object) => MysqlConnection;
 export interface MysqlPoolConnection extends MysqlConnection {
     release(): void;

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

@@ -11,7 +11,7 @@ import type { MysqlDialectConfig } from './mysql-dialect-config.js';
  * The constructor takes an instance of {@link MysqlDialectConfig}.
  *
  * ```ts
- * import { createPool } from 'mysql2'
+ * import { createPool } from 'mysql2/promise' // or just 'mysql2' — both work
  *
  * new MysqlDialect({
  *   pool: createPool({
@@ -25,7 +25,7 @@ import type { MysqlDialectConfig } from './mysql-dialect-config.js';
  * can be a function:
  *
  * ```ts
- * import { createPool } from 'mysql2'
+ * import { createPool } from 'mysql2/promise' // or just 'mysql2' — both work
  *
  * new MysqlDialect({
  *   pool: async () => createPool({

package/dist/dialect/mysql/mysql-dialect.js

@@ -9,7 +9,7 @@ import { MysqlAdapter } from './mysql-adapter.js';
  * The constructor takes an instance of {@link MysqlDialectConfig}.
  *
  * ```ts
- * import { createPool } from 'mysql2'
+ * import { createPool } from 'mysql2/promise' // or just 'mysql2' — both work
  *
  * new MysqlDialect({
  *   pool: createPool({
@@ -23,7 +23,7 @@ import { MysqlAdapter } from './mysql-adapter.js';
  * can be a function:
  *
  * ```ts
- * import { createPool } from 'mysql2'
+ * import { createPool } from 'mysql2/promise' // or just 'mysql2' — both work
  *
  * new MysqlDialect({
  *   pool: async () => createPool({

package/dist/dialect/mysql/mysql-driver.js

@@ -13,9 +13,12 @@ export class MysqlDriver {
         this.#config = freeze({ ...config });
     }
     async init(options) {
-        this.#pool = isFunction(this.#config.pool)
+        const pool = isFunction(this.#config.pool)
             ? await this.#config.pool(options)
             : this.#config.pool;
+        // A `mysql2/promise` pool's `getConnection` ignores the callback we pass
+        // it, hanging any query forever. Unwrap the callback pool it decorates.
+        this.#pool = isPromisePool(pool) ? pool.pool : pool;
     }
     async acquireConnection(options) {
         const rawConnection = await this.#acquireConnection();
@@ -93,6 +96,12 @@ export class MysqlDriver {
         });
     }
 }
+function isPromisePool(pool) {
+    return ('pool' in pool && isObject(pool.pool) && isFunction(pool.pool.getConnection));
+}
+function isPromiseConnection(connection) {
+    return isFunction(connection.then);
+}
 function isOkPacket(obj) {
     return isObject(obj) && 'insertId' in obj && 'affectedRows' in obj;
 }
@@ -224,7 +233,24 @@ class MysqlConnection {
         const { 
         // omitting these as they cause a warning and perhaps a future error when passed.
         clientFlags: _, maxPacketSize: __, ...cfg } = config;
-        const controlConnection = this.#controlConnection(cfg);
+        const controlConnectionOrPromise = this.#controlConnection(cfg);
+        // `mysql2/promise`'s `createConnection` returns a promise of a connection
+        // that's already connected, with a promise-based API. Use it directly.
+        if (isPromiseConnection(controlConnectionOrPromise)) {
+            const controlConnection = await controlConnectionOrPromise;
+            try {
+                // by the time we get the connection, another query might have been executed.
+                // we need to ensure we're not canceling the wrong query.
+                if (queryIdToCancel.queryId === this.#queryId?.queryId) {
+                    await controlConnection.query(query, []);
+                }
+            }
+            finally {
+                controlConnection.destroy();
+            }
+            return;
+        }
+        const controlConnection = controlConnectionOrPromise;
         try {
             await new Promise((resolve, reject) => {
                 controlConnection.connect((connectError) => {

package/dist/helpers/sqlite.d.ts

@@ -1,7 +1,14 @@
 import type { Expression } from '../expression/expression.js';
 import type { SelectQueryBuilderExpression } from '../query-builder/select-query-builder-expression.js';
 import type { RawBuilder } from '../raw-builder/raw-builder.js';
-import type { ShallowDehydrateObject, ShallowDehydrateValue, Simplify } from '../util/type-utils.js';
+import type { KyselyTypeError } from '../util/type-error.js';
+import type { IsNever, ShallowDehydrateObject, ShallowDehydrateValue, Simplify } from '../util/type-utils.js';
+/**
+ * Used to check for `BLOB` column existence in result records.
+ */
+export type ExtractBlobs<O> = {
+    [K in keyof O]: O[K] extends Expression<infer V> ? Extract<V, Uint8Array> : Extract<O[K], Uint8Array>;
+}[keyof O];
 /**
  * A SQLite helper for aggregating a subquery into a JSON array.
  *
@@ -63,7 +70,7 @@ import type { ShallowDehydrateObject, ShallowDehydrateValue, Simplify } from '..
  * from "person"
  * ```
  */
-export declare function jsonArrayFrom<O>(expr: SelectQueryBuilderExpression<O>): RawBuilder<Simplify<ShallowDehydrateObject<O>>[]>;
+export declare function jsonArrayFrom<O>(expr: IsNever<ExtractBlobs<O>> extends true ? SelectQueryBuilderExpression<O> : KyselyTypeError<'SQLite does not support passing `BLOB` values to `json_object`. Cast to `TEXT`.'>): RawBuilder<Simplify<ShallowDehydrateObject<O>>[]>;
 /**
  * A SQLite helper for turning a subquery into a JSON object.
  *
@@ -127,7 +134,7 @@ export declare function jsonArrayFrom<O>(expr: SelectQueryBuilderExpression<O>):
  * from "person";
  * ```
  */
-export declare function jsonObjectFrom<O>(expr: SelectQueryBuilderExpression<O>): RawBuilder<Simplify<ShallowDehydrateObject<O>> | null>;
+export declare function jsonObjectFrom<O>(expr: IsNever<ExtractBlobs<O>> extends true ? SelectQueryBuilderExpression<O> : KyselyTypeError<'SQLite does not support passing `BLOB` values to `json_object`. Cast to `TEXT`.'>): RawBuilder<Simplify<ShallowDehydrateObject<O>> | null>;
 /**
  * The SQLite `json_object` function.
  *
@@ -184,6 +191,6 @@ export declare function jsonObjectFrom<O>(expr: SelectQueryBuilderExpression<O>)
  * from "person"
  * ```
  */
-export declare function jsonBuildObject<O extends Record<string, Expression<unknown>>>(obj: O): RawBuilder<Simplify<{
+export declare function jsonBuildObject<O extends Record<string, Expression<unknown>>>(obj: IsNever<ExtractBlobs<O>> extends true ? O : KyselyTypeError<'SQLite does not support passing `BLOB` values to `json_object`. Cast to `TEXT`.'>): RawBuilder<Simplify<{
     [K in keyof O]: O[K] extends Expression<infer V> ? ShallowDehydrateValue<V> : never;
 }>>;

package/dist/helpers/sqlite.js

@@ -188,7 +188,10 @@ export function jsonObjectFrom(expr) {
  * ```
  */
 export function jsonBuildObject(obj) {
-    return sql `json_object(${sql.join(Object.keys(obj).flatMap((k) => [sql.lit(k), obj[k]]))})`;
+    return sql `json_object(${sql.join(Object.keys(obj).flatMap((k) => [
+        sql.lit(k),
+        obj[k],
+    ]))})`;
 }
 function getSqliteJsonObjectArgs(node, table) {
     try {

package/dist/migration/file-migration-provider.d.ts

@@ -1,11 +1,12 @@
-import type { Migration, MigrationProvider } from './migrator.js';
+import type { Migration } from './migration.js';
+import type { MigrationProvider } from './migrator.js';
 /**
  * Reads all migrations from a folder.
  *
  * ### Examples
  *
  * ```ts
- * import { promises as fs } from 'node:fs'
+ * import fs from 'node:fs/promises'
  * import path from 'node:path'
  *
  * new FileMigrationProvider({

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

@@ -6,7 +6,7 @@ import { isFunction, isObject } from '../util/object-utils.js';
  * ### Examples
  *
  * ```ts
- * import { promises as fs } from 'node:fs'
+ * import fs from 'node:fs/promises'
  * import path from 'node:path'
  *
  * new FileMigrationProvider({

package/dist/migration/index.d.ts

@@ -1,2 +1,3 @@
 export * from './file-migration-provider.js';
+export * from './migration.js';
 export * from './migrator.js';

package/dist/migration/index.js

@@ -1,3 +1,4 @@
 /// <reference types="./index.d.ts" />
 export * from './file-migration-provider.js';
+export * from './migration.js';
 export * from './migrator.js';

package/dist/migration/migration.d.ts

@@ -0,0 +1,70 @@
+import type { Kysely } from '../kysely.js';
+/**
+ * The shape of a migration's module.
+ */
+export interface Migration {
+    /**
+     * Configuration object for this migration module.
+     *
+     * See {@link MigrationConfig}.
+     */
+    config?: MigrationConfig;
+    /**
+     * The `down` method that reverts the changes made by it's sibling {@link Migration.up}
+     * method.
+     */
+    down?(db: Kysely<any>): Promise<void>;
+    /**
+     * The `up` method that changes the database schema.
+     *
+     * See {@link Migration.down}.
+     */
+    up(db: Kysely<any>): Promise<void>;
+}
+/**
+ * Configuration for a single migration.
+ */
+export interface MigrationConfig {
+    /**
+     * Controls whether this migration runs inside its own transaction, when
+     * {@link MigrateOptions.transactionMode} is `'per-migration'` — the only
+     * mode that honors this property. Defaults to `true` in that mode: the
+     * migration runs in its own transaction unless this is set to `false`.
+     *
+     * In any other transaction mode, leaving this property out is the only
+     * valid state — providing a value, either one, results in an error: in
+     * `'per-run'` mode a single shared transaction cannot partially exclude a
+     * migration, and in `'none'` mode there are no transactions to configure.
+     * This is the one place an explicit `true` differs from the default —
+     * `true` asserts a requirement that non-`'per-migration'` modes refuse,
+     * while leaving the property out never errors.
+     *
+     * Setting `false` makes the migration run without a transaction. This is
+     * required for statements that cannot run inside a transaction, such as
+     * PostgreSQL's `CREATE INDEX CONCURRENTLY`. Note that without a
+     * transaction, a failure can leave the migration partially applied, and the
+     * migration table record is written separately after the migration
+     * completes. Prefer a single statement per non-transactional migration, and
+     * write it so it can be safely retried — for example, drop a
+     * possibly-leftover invalid index before creating it.
+     */
+    readonly transaction?: boolean;
+}
+/**
+ * Helps define a single migration by taking over types duties and enforcing the contract.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * import { defineMigration } from 'kysely/migration'
+ *
+ * export default defineMigration({
+ *   async up(db) {
+ *     // ...
+ *   },
+ *
+ *   config: { transaction: false },
+ * })
+ * ```
+ */
+export declare function defineMigration(migration: Migration): Migration;

package/dist/migration/migration.js

@@ -0,0 +1,21 @@
+/// <reference types="./migration.d.ts" />
+/**
+ * Helps define a single migration by taking over types duties and enforcing the contract.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * import { defineMigration } from 'kysely/migration'
+ *
+ * export default defineMigration({
+ *   async up(db) {
+ *     // ...
+ *   },
+ *
+ *   config: { transaction: false },
+ * })
+ * ```
+ */
+export function defineMigration(migration) {
+    return migration;
+}

package/dist/migration/migrator.d.ts

@@ -1,19 +1,10 @@
 import type { Kysely } from '../kysely.js';
+import type { Migration } from './migration.js';
 export declare const DEFAULT_MIGRATION_TABLE = "kysely_migration";
 export declare const DEFAULT_MIGRATION_LOCK_TABLE = "kysely_migration_lock";
 export declare const DEFAULT_ALLOW_UNORDERED_MIGRATIONS = false;
 export declare const MIGRATION_LOCK_ID = "migration_lock";
 export declare const NO_MIGRATIONS: NoMigrations;
-export interface Migration {
-    up(db: Kysely<any>): Promise<void>;
-    /**
-     * An optional down method.
-     *
-     * If you don't provide a down method, the migration is skipped when
-     * migrating down.
-     */
-    down?(db: Kysely<any>): Promise<void>;
-}
 /**
  * A class for running migrations.
  *
@@ -25,7 +16,7 @@ export interface Migration {
  * other way.
  *
  * ```ts
- * import { promises as fs } from 'node:fs'
+ * import fs from 'node:fs/promises'
  * import path from 'node:path'
  * import * as Sqlite from 'better-sqlite3'
  * import { Kysely, SqliteDialect } from 'kysely'
@@ -73,7 +64,7 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import * as Sqlite from 'better-sqlite3'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
@@ -115,7 +106,7 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *
@@ -138,7 +129,7 @@ export declare class Migrator {
      * you can use a special constant `NO_MIGRATIONS`:
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator, NO_MIGRATIONS } from 'kysely/migration'
      *
@@ -154,8 +145,33 @@ export declare class Migrator {
      *
      * await migrator.migrateTo(NO_MIGRATIONS)
      * ```
+     *
+     * By default, this method migrates up or down depending on which side of the
+     * current migration state the target migration is on. Pass
+     * {@link MigrateToOptions.direction} to enforce a direction — if reaching the
+     * target would require migrating the other way, nothing is executed and
+     * {@link MigrationResultSet.error} holds an error:
+     *
+     * ```ts
+     * import fs from 'node:fs/promises'
+     * import path from 'node:path'
+     * import { FileMigrationProvider, Migrator } from 'kysely/migration'
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   provider: new FileMigrationProvider({
+     *     fs,
+     *     // Path to the folder that contains all your migrations.
+     *     migrationFolder: 'some/path/to/migrations',
+     *     path,
+     *   })
+     * })
+     *
+     * // Errors if `some_migration` is already executed.
+     * await migrator.migrateTo('some_migration', { direction: 'Up' })
+     * ```
      */
-    migrateTo(targetMigrationName: string | NoMigrations, options?: MigrateOptions): Promise<MigrationResultSet>;
+    migrateTo(targetMigrationName: string | NoMigrations, options?: MigrateToOptions): Promise<MigrationResultSet>;
     /**
      * Migrate one step up.
      *
@@ -167,7 +183,7 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *
@@ -196,7 +212,7 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *
@@ -221,9 +237,65 @@ export interface MigrateOptions {
      *
      * Default is `false`.
      *
-     * This is useful when some migrations include queries that would fail otherwise.
+     * @deprecated Use {@link transactionMode} instead — `disableTransactions: true`
+     * is equivalent to `transactionMode: 'none'`. Setting both to contradicting
+     * values results in an error.
      */
     readonly disableTransactions?: boolean;
+    /**
+     * Controls how migrations are wrapped in transactions, when the dialect
+     * supports transactional DDL ({@link DialectAdapter.supportsTransactionalDdl}).
+     *
+     * - `'per-run'` — the entire migration run is wrapped in a single transaction.
+     *   Either every migration in the run is applied, or none are. Any migration
+     *   with a per-migration `transaction` configuration ({@link MigrationConfig.transaction})
+     *   results in an error, since a single shared transaction cannot partially
+     *   exclude a migration. Requires transactional DDL — results in an error on
+     *   dialects without it (e.g. MySQL).
+     *
+     * - `'per-migration'` — each migration runs in its own transaction, together
+     *   with the insertion/deletion of its migration table record. A failure rolls
+     *   back only the failing migration; previously completed migrations stay
+     *   applied. Individual migrations can opt out of their transaction with
+     *   `config: { transaction: false }` — required for statements that cannot
+     *   run inside a transaction, such as PostgreSQL's `CREATE INDEX CONCURRENTLY`
+     *   or `ALTER TYPE ... ADD VALUE` (pre-12). Requires transactional DDL —
+     *   results in an error on dialects without it.
+     *
+     * - `'none'` — migrations run without any transactions. Any migration with a
+     *   per-migration `transaction` configuration results in an error.
+     *
+     * When not provided, the current default is `'per-run'` on dialects that
+     * support transactional DDL and `'none'` on dialects that don't. This
+     * default might change to `'per-migration'` in a future version of Kysely —
+     * running multiple migrations without an explicit `transactionMode` logs a
+     * message about this. Provide an explicit `transactionMode` to make the
+     * migrator's behavior independent of the default.
+     *
+     * Note that transactions spanning multiple migrations (`'per-run'`) can make
+     * otherwise-valid migration sequences fail. For example, a new PostgreSQL enum
+     * value cannot be used in the same transaction that added it, so a migration
+     * that runs `ALTER TYPE ... ADD VALUE` followed by a migration that uses the
+     * new value works when the two run in separate transactions, but fails when
+     * both are pending in a single `'per-run'` mode run.
+     */
+    readonly transactionMode?: MigratorTransactionMode;
+}
+export type MigratorTransactionMode = 'per-run' | 'per-migration' | 'none';
+export interface MigrateToOptions extends MigrateOptions {
+    /**
+     * Enforces a migration direction.
+     *
+     * When provided and reaching the target migration would require migrating
+     * the other way, nothing is executed and {@link MigrationResultSet.error}
+     * holds an error. For example, `direction: 'Up'` errors when the target
+     * migration is already executed.
+     *
+     * By default, {@link Migrator.migrateTo | migrateTo} migrates up or down
+     * depending on which side of the current migration state the target
+     * migration is on.
+     */
+    readonly direction?: MigrationDirection;
 }
 export interface MigratorProps extends MigrateOptions {
     readonly db: Kysely<any>;
@@ -327,7 +399,7 @@ export interface MigrationResultSet {
      */
     readonly results?: MigrationResult[];
 }
-type MigrationDirection = 'Up' | 'Down';
+export type MigrationDirection = 'Up' | 'Down';
 export interface MigrationResult {
     readonly migrationName: string;
     /**
@@ -390,4 +462,3 @@ export interface MigrationInfo {
      */
     executedAt?: Date;
 }
-export {};

package/dist/migration/migrator.js

@@ -1,7 +1,8 @@
 /// <reference types="./migrator.d.ts" />
 import { NoopPlugin } from '../plugin/noop-plugin.js';
 import { WithSchemaPlugin } from '../plugin/with-schema/with-schema-plugin.js';
-import { freeze, getLast, isObject } from '../util/object-utils.js';
+import { logOnce } from '../util/log-once.js';
+import { freeze, 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;
@@ -18,7 +19,7 @@ export const NO_MIGRATIONS = freeze({ __noMigrations__: true });
  * other way.
  *
  * ```ts
- * import { promises as fs } from 'node:fs'
+ * import fs from 'node:fs/promises'
  * import path from 'node:path'
  * import * as Sqlite from 'better-sqlite3'
  * import { Kysely, SqliteDialect } from 'kysely'
@@ -87,7 +88,7 @@ export class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import * as Sqlite from 'better-sqlite3'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
@@ -131,7 +132,7 @@ export class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *
@@ -154,7 +155,7 @@ export class Migrator {
      * you can use a special constant `NO_MIGRATIONS`:
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator, NO_MIGRATIONS } from 'kysely/migration'
      *
@@ -170,11 +171,39 @@ export class Migrator {
      *
      * await migrator.migrateTo(NO_MIGRATIONS)
      * ```
+     *
+     * By default, this method migrates up or down depending on which side of the
+     * current migration state the target migration is on. Pass
+     * {@link MigrateToOptions.direction} to enforce a direction — if reaching the
+     * target would require migrating the other way, nothing is executed and
+     * {@link MigrationResultSet.error} holds an error:
+     *
+     * ```ts
+     * import fs from 'node:fs/promises'
+     * import path from 'node:path'
+     * import { FileMigrationProvider, Migrator } from 'kysely/migration'
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   provider: new FileMigrationProvider({
+     *     fs,
+     *     // Path to the folder that contains all your migrations.
+     *     migrationFolder: 'some/path/to/migrations',
+     *     path,
+     *   })
+     * })
+     *
+     * // Errors if `some_migration` is already executed.
+     * await migrator.migrateTo('some_migration', { direction: 'Up' })
+     * ```
      */
     async migrateTo(targetMigrationName, options) {
         return this.#migrate(({ migrations, executedMigrations, pendingMigrations, }) => {
             if (isObject(targetMigrationName) &&
                 targetMigrationName.__noMigrations__ === true) {
+                if (options?.direction === 'Up') {
+                    throw new Error(`can't migrate up to NO_MIGRATIONS`);
+                }
                 return { direction: 'Down', step: Infinity };
             }
             if (!migrations.find((m) => m.name === targetMigrationName)) {
@@ -183,12 +212,18 @@ export class Migrator {
             const executedIndex = executedMigrations.indexOf(targetMigrationName);
             const pendingIndex = pendingMigrations.findIndex((m) => m.name === targetMigrationName);
             if (executedIndex !== -1) {
+                if (options?.direction === 'Up') {
+                    throw new Error(`migration "${targetMigrationName}" is already executed; can't migrate up to it`);
+                }
                 return {
                     direction: 'Down',
                     step: executedMigrations.length - executedIndex - 1,
                 };
             }
             if (pendingIndex !== -1) {
+                if (options?.direction === 'Down') {
+                    throw new Error(`migration "${targetMigrationName}" isn't executed; can't migrate down to it`);
+                }
                 return { direction: 'Up', step: pendingIndex + 1 };
             }
             throw new Error(`migration "${targetMigrationName}" isn't executed or pending`);
@@ -205,7 +240,7 @@ export class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *
@@ -236,7 +271,7 @@ export class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *
@@ -403,6 +438,7 @@ export class Migrator {
             lockRowId: MIGRATION_LOCK_ID,
             lockTableSchema: this.#props.migrationTableSchema,
         });
+        const transactionMode = this.#resolveTransactionMode(options, adapter);
         const run = async (db) => {
             const state = await this.#getState(db);
             if (state.migrations.length === 0) {
@@ -412,13 +448,34 @@ export class Migrator {
             if (step <= 0) {
                 return { results: [] };
             }
-            if (direction === 'Down') {
-                return await this.#migrateDown(db, state, step);
+            const migrationsToRun = this.#getMigrationsToRun(state, direction, step);
+            const [orchestrator, runner] = direction === 'Down'
+                ? [
+                    this.#rollbackMigrations.bind(this),
+                    this.#rollbackMigration.bind(this),
+                ]
+                : [this.#applyMigrations.bind(this), this.#applyMigration.bind(this)];
+            if (transactionMode.value === 'per-migration') {
+                return await orchestrator(migrationsToRun, async (migration) => {
+                    if (migration.config?.transaction === false) {
+                        return await runner(db, migration);
+                    }
+                    await db.transaction().execute((trx) => runner(trx, migration));
+                });
+            }
+            const migrationWithTransactionConfig = migrationsToRun.find((migration) => migration.config?.transaction != null);
+            if (migrationWithTransactionConfig) {
+                const modeDescription = transactionMode.explicit
+                    ? `\`transactionMode\` is '${transactionMode.value}'`
+                    : `\`transactionMode\` was not provided and defaults to '${transactionMode.value}'`;
+                throw new Error(`Migration "${migrationWithTransactionConfig.name}" has a \`transaction\` configuration but ${modeDescription}. Per-migration transaction configuration is only supported when \`transactionMode\` is 'per-migration'. Set \`transactionMode: 'per-migration'\` on the migrator or the migrate call to enable it.`);
             }
-            else if (direction === 'Up') {
-                return await this.#migrateUp(db, state, step);
+            if (!transactionMode.explicit &&
+                adapter.supportsTransactionalDdl &&
+                migrationsToRun.length > 1) {
+                logOnce("kysely:migrator: multiple migrations were run in a single transaction ('per-run'). This default might change in a future version of Kysely. Pass an explicit `transactionMode` to the migrator to pin the behavior and silence this message: 'per-run' to keep the current behavior, or 'per-migration' to run each migration in its own transaction.");
             }
-            return { results: [] };
+            return await orchestrator(migrationsToRun, (migration) => runner(db, migration));
         };
         const runWithLock = async (db, cb) => {
             try {
@@ -429,51 +486,92 @@ export class Migrator {
                 await adapter.releaseMigrationLock(db, lockOptions);
             }
         };
-        const disableTransactions = options?.disableTransactions ?? this.#props.disableTransactions;
         if (this.#props.db.isTransaction) {
             if (!adapter.supportsTransactionalDdl) {
                 throw new Error('Transactional DDL is not supported in this dialect. Passing a transaction to this migrator would result in failure or unexpected behavior.');
             }
-            if (disableTransactions) {
-                throw new Error('`disableTransactions` is true but the migrator was given a transaction. Passing a transaction to this migrator would result in failure or unexpected behavior.');
+            if (transactionMode.value !== 'per-run') {
+                throw new Error(`The transaction mode is '${transactionMode.value}' but the migrator was given a transaction. Passing a transaction to this migrator is only supported when \`transactionMode\` is 'per-run'.`);
             }
             return runWithLock(this.#props.db, run);
         }
-        if (adapter.supportsTransactionalDdl && !disableTransactions) {
+        if (transactionMode.value === 'per-run') {
             return this.#props.db
                 .connection()
-                .execute((db) => runWithLock(db, (db) => db.transaction().execute((trx) => run(trx))));
+                .execute((db) => runWithLock(db, (db) => db.transaction().execute(run)));
         }
         return this.#props.db.connection().execute((db) => runWithLock(db, run));
     }
+    #resolveTransactionMode(options, adapter) {
+        const resolveLevel = (options, source) => {
+            if (!options) {
+                return;
+            }
+            const { disableTransactions, transactionMode } = options;
+            if (disableTransactions != null &&
+                transactionMode &&
+                (transactionMode === 'none') !== disableTransactions) {
+                throw new Error(`\`transactionMode\` is '${transactionMode}' but \`disableTransactions\` is ${disableTransactions} in the ${source}. These options contradict each other. Prefer \`transactionMode\` — \`disableTransactions\` is deprecated.`);
+            }
+            if (transactionMode) {
+                if (transactionMode !== 'none' && !adapter.supportsTransactionalDdl) {
+                    throw new Error(`\`transactionMode\` is '${transactionMode}' but transactional DDL is not supported in this dialect. Migrations would fail or behave unexpectedly.`);
+                }
+                return { explicit: true, value: transactionMode };
+            }
+            if (disableTransactions == null) {
+                return;
+            }
+            if (disableTransactions === true) {
+                return { explicit: true, value: 'none' };
+            }
+            return {
+                explicit: false,
+                value: adapter.supportsTransactionalDdl ? 'per-run' : 'none',
+            };
+        };
+        return (resolveLevel(options, 'migrate call options') ||
+            resolveLevel(this.#props, 'migrator properties') || {
+            explicit: false,
+            value: adapter.supportsTransactionalDdl ? 'per-run' : 'none',
+        });
+    }
+    #getMigrationsToRun(state, direction, step) {
+        if (direction === 'Down') {
+            return state.executedMigrations
+                .toReversed()
+                .slice(0, step)
+                .map((name) => {
+                return state.migrations.find((it) => it.name === name);
+            });
+        }
+        return state.pendingMigrations.slice(0, step);
+    }
     async #getState(db) {
-        const migrations = await this.#resolveMigrations();
-        const executedMigrations = await this.#getExecutedMigrations(db);
+        const [migrations, executedMigrations] = await Promise.all([
+            this.#resolveMigrations(),
+            this.#getExecutedMigrations(db),
+        ]);
         this.#ensureNoMissingMigrations(migrations, executedMigrations);
         if (!this.#allowUnorderedMigrations) {
             this.#ensureMigrationsInOrder(migrations, executedMigrations);
         }
         const pendingMigrations = this.#getPendingMigrations(migrations, executedMigrations);
         return freeze({
-            migrations,
             executedMigrations,
-            lastMigration: getLast(executedMigrations),
+            lastMigration: executedMigrations.at(-1),
+            migrations,
             pendingMigrations,
         });
     }
     #getPendingMigrations(migrations, executedMigrations) {
-        return migrations.filter((migration) => {
-            return !executedMigrations.includes(migration.name);
-        });
+        return migrations.filter((migration) => !executedMigrations.includes(migration.name));
     }
     async #resolveMigrations() {
         const allMigrations = await this.#props.provider.getMigrations();
         return Object.keys(allMigrations)
             .sort()
-            .map((name) => ({
-            ...allMigrations[name],
-            name,
-        }));
+            .map((name) => ({ ...allMigrations[name], name }));
     }
     async #getExecutedMigrations(db) {
         const executedMigrations = await db
@@ -509,92 +607,63 @@ export class Migrator {
             }
         }
     }
-    async #migrateDown(db, state, step) {
-        const migrationsToRollback = state.executedMigrations
-            .toReversed()
-            .slice(0, step)
-            .map((name) => {
-            return state.migrations.find((it) => it.name === name);
-        });
-        const results = migrationsToRollback.map((migration) => {
-            return {
-                migrationName: migration.name,
-                direction: 'Down',
-                status: 'NotExecuted',
-            };
-        });
+    async #rollbackMigrations(migrationsToRollback, rollbacker) {
+        const results = migrationsToRollback.map((migration) => ({
+            direction: 'Down',
+            migrationName: migration.name,
+            status: 'NotExecuted',
+        }));
         for (let i = 0; i < results.length; ++i) {
             const migration = migrationsToRollback[i];
+            if (!migration.down) {
+                continue;
+            }
             try {
-                if (migration.down) {
-                    await migration.down(db);
-                    await db
-                        .withPlugin(this.#schemaPlugin)
-                        .deleteFrom(this.#migrationTable)
-                        .where('name', '=', migration.name)
-                        .execute();
-                    results[i] = {
-                        migrationName: migration.name,
-                        direction: 'Down',
-                        status: 'Success',
-                    };
-                }
+                await rollbacker(migration);
+                results[i].status = 'Success';
             }
             catch (error) {
-                results[i] = {
-                    migrationName: migration.name,
-                    direction: 'Down',
-                    status: 'Error',
-                };
-                throw new MigrationResultSetError({
-                    error,
-                    results,
-                });
+                results[i].status = 'Error';
+                throw new MigrationResultSetError({ error, results });
             }
         }
         return { results };
     }
-    async #migrateUp(db, state, step) {
-        const migrationsToRun = state.pendingMigrations.slice(0, step);
-        const results = migrationsToRun.map((migration) => {
-            return {
-                migrationName: migration.name,
-                direction: 'Up',
-                status: 'NotExecuted',
-            };
-        });
+    async #applyMigrations(migrationsToRun, applier) {
+        const results = migrationsToRun.map((migration) => ({
+            direction: 'Up',
+            migrationName: migration.name,
+            status: 'NotExecuted',
+        }));
         for (let i = 0; i < results.length; i++) {
-            const migration = state.pendingMigrations[i];
+            const migration = migrationsToRun[i];
             try {
-                await migration.up(db);
-                await db
-                    .withPlugin(this.#schemaPlugin)
-                    .insertInto(this.#migrationTable)
-                    .values({
-                    name: migration.name,
-                    timestamp: new Date().toISOString(),
-                })
-                    .execute();
-                results[i] = {
-                    migrationName: migration.name,
-                    direction: 'Up',
-                    status: 'Success',
-                };
+                await applier(migration);
+                results[i].status = 'Success';
             }
             catch (error) {
-                results[i] = {
-                    migrationName: migration.name,
-                    direction: 'Up',
-                    status: 'Error',
-                };
-                throw new MigrationResultSetError({
-                    error,
-                    results,
-                });
+                results[i].status = 'Error';
+                throw new MigrationResultSetError({ error, results });
             }
         }
         return { results };
     }
+    async #applyMigration(db, migration) {
+        await migration.up(db);
+        await db
+            .withPlugin(this.#schemaPlugin)
+            .insertInto(this.#migrationTable)
+            .values({ name: migration.name, timestamp: new Date().toISOString() })
+            .execute();
+    }
+    async #rollbackMigration(db, migration) {
+        await migration.down(db);
+        await db
+            .withPlugin(this.#schemaPlugin)
+            .deleteFrom(this.#migrationTable)
+            .where('name', '=', migration.name)
+            .execute();
+    }
     async #createIfNotExists(qb) {
         if (this.#props.db.getExecutor().adapter.supportsCreateIfNotExists) {
             qb = qb.ifNotExists();

package/dist/util/object-utils.d.ts

@@ -14,7 +14,6 @@ export declare function isFunction(obj: unknown): obj is Function;
 export declare function isObject(obj: unknown): obj is ShallowRecord<string, unknown>;
 export declare function isArrayBufferOrView(obj: unknown): obj is ArrayBuffer | ArrayBufferView;
 export declare function isPlainObject(obj: unknown): obj is Record<string, unknown>;
-export declare function getLast<T>(arr: ArrayLike<T>): T | undefined;
 export declare function freeze<T>(obj: T): Readonly<T>;
 export declare function asArray<T>(arg: T | ReadonlyArray<T>): ReadonlyArray<T>;
 export declare function asReadonlyArray<T>(arg: T | ReadonlyArray<T>): ReadonlyArray<T>;

package/dist/util/object-utils.js

@@ -56,9 +56,6 @@ export function isPlainObject(obj) {
     }
     return Object.getPrototypeOf(obj) === proto;
 }
-export function getLast(arr) {
-    return arr[arr.length - 1];
-}
 export function freeze(obj) {
     return Object.freeze(obj);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.29.4",
+  "version": "0.30.0-beta.1",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",