kysely 0.27.1 → 0.27.2

package/dist/cjs/migration/migrator.d.ts

@@ -1,6 +1,7 @@
 import { Kysely } from '../kysely.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 {
@@ -58,7 +59,7 @@ export declare class Migrator {
      * This method goes through all possible migrations provided by the provider and runs the
      * ones whose names come alphabetically after the last migration that has been run. If the
      * list of executed migrations doesn't match the beginning of the list of possible migrations
-     * an error is thrown.
+     * an error is returned.
      *
      * ### Examples
      *
@@ -197,6 +198,20 @@ export interface MigratorProps {
      * This only works on postgres.
      */
     readonly migrationTableSchema?: string;
+    /**
+     * Enforces whether or not migrations must be run in alpha-numeric order.
+     *
+     * When false, migrations must be run in their exact alpha-numeric order.
+     * This is checked against the migrations already run in the database
+     * (`migrationTableName'). This ensures your migrations are always run in
+     * the same order and is the safest option.
+     *
+     * When true, migrations are still run in alpha-numeric order, but
+     * the order is not checked against already-run migrations in the database.
+     * Kysely will simply run all migrations that haven't run yet, in alpha-numeric
+     * order.
+     */
+    readonly allowUnorderedMigrations?: boolean;
 }
 /**
  * All migration methods ({@link Migrator.migrateTo | migrateTo},
@@ -231,12 +246,13 @@ export interface MigrationResultSet {
      */
     readonly results?: MigrationResult[];
 }
+type MigrationDirection = 'Up' | 'Down';
 export interface MigrationResult {
     readonly migrationName: string;
     /**
      * The direction in which this migration was executed.
      */
-    readonly direction: 'Up' | 'Down';
+    readonly direction: MigrationDirection;
     /**
      * The execution status.
      *
@@ -293,3 +309,4 @@ export interface MigrationInfo {
      */
     executedAt?: Date;
 }
+export {};

package/dist/cjs/migration/migrator.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Migrator = exports.NO_MIGRATIONS = exports.MIGRATION_LOCK_ID = exports.DEFAULT_MIGRATION_LOCK_TABLE = exports.DEFAULT_MIGRATION_TABLE = void 0;
+exports.Migrator = exports.NO_MIGRATIONS = exports.MIGRATION_LOCK_ID = exports.DEFAULT_ALLOW_UNORDERED_MIGRATIONS = exports.DEFAULT_MIGRATION_LOCK_TABLE = exports.DEFAULT_MIGRATION_TABLE = void 0;
 const noop_plugin_js_1 = require("../plugin/noop-plugin.js");
 const with_schema_plugin_js_1 = require("../plugin/with-schema/with-schema-plugin.js");
 const object_utils_js_1 = require("../util/object-utils.js");
 exports.DEFAULT_MIGRATION_TABLE = 'kysely_migration';
 exports.DEFAULT_MIGRATION_LOCK_TABLE = 'kysely_migration_lock';
+exports.DEFAULT_ALLOW_UNORDERED_MIGRATIONS = false;
 exports.MIGRATION_LOCK_ID = 'migration_lock';
 exports.NO_MIGRATIONS = (0, object_utils_js_1.freeze)({ __noMigrations__: true });
 /**
@@ -72,7 +73,7 @@ class Migrator {
      * This method goes through all possible migrations provided by the provider and runs the
      * ones whose names come alphabetically after the last migration that has been run. If the
      * list of executed migrations doesn't match the beginning of the list of possible migrations
-     * an error is thrown.
+     * an error is returned.
      *
      * ### Examples
      *
@@ -109,7 +110,7 @@ class Migrator {
      * ```
      */
     async migrateToLatest() {
-        return this.#migrate(({ migrations }) => migrations.length - 1);
+        return this.#migrate(() => ({ direction: 'Up', step: Infinity }));
     }
     /**
      * Migrate up/down to a specific migration.
@@ -135,15 +136,27 @@ class Migrator {
      * ```
      */
     async migrateTo(targetMigrationName) {
-        return this.#migrate(({ migrations }) => {
+        return this.#migrate(({ migrations, executedMigrations, pendingMigrations, }) => {
             if (targetMigrationName === exports.NO_MIGRATIONS) {
-                return -1;
+                return { direction: 'Down', step: Infinity };
             }
-            const index = migrations.findIndex((it) => it.name === targetMigrationName);
-            if (index === -1) {
+            if (!migrations.find((m) => m.name === targetMigrationName)) {
                 throw new Error(`migration "${targetMigrationName}" doesn't exist`);
             }
-            return index;
+            const executedIndex = executedMigrations.indexOf(targetMigrationName);
+            const pendingIndex = pendingMigrations.findIndex((m) => m.name === targetMigrationName);
+            if (executedIndex !== -1) {
+                return {
+                    direction: 'Down',
+                    step: executedMigrations.length - executedIndex - 1,
+                };
+            }
+            else if (pendingIndex !== -1) {
+                return { direction: 'Up', step: pendingIndex + 1 };
+            }
+            else {
+                throw new Error(`migration "${targetMigrationName}" isn't executed or pending`);
+            }
         });
     }
     /**
@@ -161,7 +174,7 @@ class Migrator {
      * ```
      */
     async migrateUp() {
-        return this.#migrate(({ currentIndex, migrations }) => Math.min(currentIndex + 1, migrations.length - 1));
+        return this.#migrate(() => ({ direction: 'Up', step: 1 }));
     }
     /**
      * Migrate one step down.
@@ -178,12 +191,12 @@ class Migrator {
      * ```
      */
     async migrateDown() {
-        return this.#migrate(({ currentIndex }) => Math.max(currentIndex - 1, -1));
+        return this.#migrate(() => ({ direction: 'Down', step: 1 }));
     }
-    async #migrate(getTargetMigrationIndex) {
+    async #migrate(getMigrationDirectionAndStep) {
         try {
             await this.#ensureMigrationTablesExists();
-            return await this.#runMigrations(getTargetMigrationIndex);
+            return await this.#runMigrations(getMigrationDirectionAndStep);
         }
         catch (error) {
             if (error instanceof MigrationResultSetError) {
@@ -201,6 +214,9 @@ class Migrator {
     get #migrationLockTable() {
         return this.#props.migrationLockTableName ?? exports.DEFAULT_MIGRATION_LOCK_TABLE;
     }
+    get #allowUnorderedMigrations() {
+        return (this.#props.allowUnorderedMigrations ?? exports.DEFAULT_ALLOW_UNORDERED_MIGRATIONS);
+    }
     get #schemaPlugin() {
         if (this.#migrationTableSchema) {
             return new with_schema_plugin_js_1.WithSchemaPlugin(this.#migrationTableSchema);
@@ -311,7 +327,7 @@ class Migrator {
             .executeTakeFirst();
         return !!lockRow;
     }
-    async #runMigrations(getTargetMigrationIndex) {
+    async #runMigrations(getMigrationDirectionAndStep) {
         const adapter = this.#props.db.getExecutor().adapter;
         const lockOptions = (0, object_utils_js_1.freeze)({
             lockTable: this.#props.migrationLockTableName ?? exports.DEFAULT_MIGRATION_LOCK_TABLE,
@@ -325,15 +341,15 @@ class Migrator {
                 if (state.migrations.length === 0) {
                     return { results: [] };
                 }
-                const targetIndex = getTargetMigrationIndex(state);
-                if (targetIndex === undefined) {
+                const { direction, step } = getMigrationDirectionAndStep(state);
+                if (step <= 0) {
                     return { results: [] };
                 }
-                if (targetIndex < state.currentIndex) {
-                    return await this.#migrateDown(db, state, targetIndex);
+                if (direction === 'Down') {
+                    return await this.#migrateDown(db, state, step);
                 }
-                else if (targetIndex > state.currentIndex) {
-                    return await this.#migrateUp(db, state, targetIndex);
+                else if (direction === 'Up') {
+                    return await this.#migrateUp(db, state, step);
                 }
                 return { results: [] };
             }
@@ -351,10 +367,21 @@ class Migrator {
     async #getState(db) {
         const migrations = await this.#resolveMigrations();
         const executedMigrations = await this.#getExecutedMigrations(db);
-        this.#ensureMigrationsNotCorrupted(migrations, executedMigrations);
+        this.#ensureNoMissingMigrations(migrations, executedMigrations);
+        if (!this.#allowUnorderedMigrations) {
+            this.#ensureMigrationsInOrder(migrations, executedMigrations);
+        }
+        const pendingMigrations = this.#getPendingMigrations(migrations, executedMigrations);
         return (0, object_utils_js_1.freeze)({
             migrations,
-            currentIndex: migrations.findIndex((it) => it.name === (0, object_utils_js_1.getLast)(executedMigrations)),
+            executedMigrations,
+            lastMigration: (0, object_utils_js_1.getLast)(executedMigrations),
+            pendingMigrations,
+        });
+    }
+    #getPendingMigrations(migrations, executedMigrations) {
+        return migrations.filter((migration) => {
+            return !executedMigrations.includes(migration.name);
         });
     }
     async #resolveMigrations() {
@@ -371,36 +398,43 @@ class Migrator {
             .withPlugin(this.#schemaPlugin)
             .selectFrom(this.#migrationTable)
             .select('name')
-            .orderBy('name')
+            .orderBy(['timestamp', 'name'])
             .execute();
         return executedMigrations.map((it) => it.name);
     }
-    #ensureMigrationsNotCorrupted(migrations, executedMigrations) {
+    #ensureNoMissingMigrations(migrations, executedMigrations) {
+        // Ensure all executed migrations exist in the `migrations` list.
         for (const executed of executedMigrations) {
             if (!migrations.some((it) => it.name === executed)) {
                 throw new Error(`corrupted migrations: previously executed migration ${executed} is missing`);
             }
         }
-        // Now we know all executed migrations exist in the `migrations` list.
-        // Next we need to make sure that the executed migratiosns are the first
-        // ones in the migration list.
+    }
+    #ensureMigrationsInOrder(migrations, executedMigrations) {
+        // Ensure the executed migrations are the first ones in the migration list.
         for (let i = 0; i < executedMigrations.length; ++i) {
             if (migrations[i].name !== executedMigrations[i]) {
                 throw new Error(`corrupted migrations: expected previously executed migration ${executedMigrations[i]} to be at index ${i} but ${migrations[i].name} was found in its place. New migrations must always have a name that comes alphabetically after the last executed migration.`);
             }
         }
     }
-    async #migrateDown(db, state, targetIndex) {
-        const results = [];
-        for (let i = state.currentIndex; i > targetIndex; --i) {
-            results.push({
-                migrationName: state.migrations[i].name,
+    async #migrateDown(db, state, step) {
+        const migrationsToRollback = state.executedMigrations
+            .slice()
+            .reverse()
+            .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',
-            });
-        }
+            };
+        });
         for (let i = 0; i < results.length; ++i) {
-            const migration = state.migrations.find((it) => it.name === results[i].migrationName);
+            const migration = migrationsToRollback[i];
             try {
                 if (migration.down) {
                     await migration.down(db);
@@ -430,17 +464,17 @@ class Migrator {
         }
         return { results };
     }
-    async #migrateUp(db, state, targetIndex) {
-        const results = [];
-        for (let i = state.currentIndex + 1; i <= targetIndex; ++i) {
-            results.push({
-                migrationName: state.migrations[i].name,
+    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',
-            });
-        }
-        for (let i = 0; i < results.length; ++i) {
-            const migration = state.migrations.find((it) => it.name === results[i].migrationName);
+            };
+        });
+        for (let i = 0; i < results.length; i++) {
+            const migration = state.pendingMigrations[i];
             try {
                 await migration.up(db);
                 await db

package/dist/cjs/query-builder/insert-query-builder.d.ts

@@ -1,7 +1,7 @@
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { SelectExpression, SelectCallback } from '../parser/select-parser.js';
-import { InsertObjectOrList, InsertObjectOrListFactory } from '../parser/insert-values-parser.js';
+import { InsertExpression } from '../parser/insert-values-parser.js';
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { NarrowPartial, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
@@ -184,8 +184,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * }))
      * ```
      */
-    values(insert: InsertObjectOrList<DB, TB>): InsertQueryBuilder<DB, TB, O>;
-    values(insert: InsertObjectOrListFactory<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    values(insert: InsertExpression<DB, TB>): InsertQueryBuilder<DB, TB, O>;
     /**
      * Sets the columns to insert.
      *

package/dist/cjs/query-builder/insert-query-builder.js

@@ -20,6 +20,166 @@ class InsertQueryBuilder {
     constructor(props) {
         this.#props = (0, object_utils_js_1.freeze)(props);
     }
+    /**
+     * Sets the values to insert for an {@link Kysely.insertInto | insert} query.
+     *
+     * This method takes an object whose keys are column names and values are
+     * values to insert. In addition to the column's type, the values can be
+     * raw {@link sql} snippets or select queries.
+     *
+     * You must provide all fields you haven't explicitly marked as nullable
+     * or optional using {@link Generated} or {@link ColumnType}.
+     *
+     * The return value of an `insert` query is an instance of {@link InsertResult}. The
+     * {@link InsertResult.insertId | insertId} field holds the auto incremented primary
+     * key if the database returned one.
+     *
+     * On PostgreSQL and some other dialects, you need to call `returning` to get
+     * something out of the query.
+     *
+     * Also see the {@link expression} method for inserting the result of a select
+     * query or any other expression.
+     *
+     * ### Examples
+     *
+     * <!-- siteExample("insert", "Single row", 10) -->
+     *
+     * Insert a single row:
+     *
+     * ```ts
+     * const result = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     age: 40
+     *   })
+     *   .executeTakeFirst()
+     *
+     * // `insertId` is only available on dialects that
+     * // automatically return the id of the inserted row
+     * // such as MySQL and SQLite. On PostgreSQL, for example,
+     * // you need to add a `returning` clause to the query to
+     * // get anything out. See the "returning data" example.
+     * console.log(result.insertId)
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * insert into `person` (`first_name`, `last_name`, `age`) values (?, ?, ?)
+     * ```
+     *
+     * <!-- siteExample("insert", "Multiple rows", 20) -->
+     *
+     * On dialects that support it (for example PostgreSQL) you can insert multiple
+     * rows by providing an array. Note that the return value is once again very
+     * dialect-specific. Some databases may only return the id of the *last* inserted
+     * row and some return nothing at all unless you call `returning`.
+     *
+     * ```ts
+     * await db
+     *   .insertInto('person')
+     *   .values([{
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     age: 40,
+     *   }, {
+     *     first_name: 'Arnold',
+     *     last_name: 'Schwarzenegger',
+     *     age: 70,
+     *   }])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "age") values (($1, $2, $3), ($4, $5, $6))
+     * ```
+     *
+     * <!-- siteExample("insert", "Returning data", 30) -->
+     *
+     * On supported dialects like PostgreSQL you need to chain `returning` to the query to get
+     * the inserted row's columns (or any other expression) as the return value. `returning`
+     * works just like `select`. Refer to `select` method's examples and documentation for
+     * more info.
+     *
+     * ```ts
+     * const result = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     age: 40,
+     *   })
+     *   .returning(['id', 'first_name as name'])
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "age") values ($1, $2, $3) returning "id", "first_name" as "name"
+     * ```
+     *
+     * <!-- siteExample("insert", "Complex values", 40) -->
+     *
+     * In addition to primitives, the values can also be arbitrary expressions.
+     * You can build the expressions by using a callback and calling the methods
+     * on the expression builder passed to it:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const ani = "Ani"
+     * const ston = "ston"
+     *
+     * const result = await db
+     *   .insertInto('person')
+     *   .values(({ ref, selectFrom, fn }) => ({
+     *     first_name: 'Jennifer',
+     *     last_name: sql`concat(${ani}, ${ston})`,
+     *     middle_name: ref('first_name'),
+     *     age: selectFrom('person')
+     *       .select(fn.avg<number>('age')
+     *       .as('avg_age')),
+     *   }))
+     *   .executeTakeFirst()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" (
+     *   "first_name",
+     *   "last_name",
+     *   "middle_name",
+     *   "age"
+     * )
+     * values (
+     *   $1,
+     *   concat($2, $3),
+     *   "first_name",
+     *   (select avg("age") as "avg_age" from "person")
+     * )
+     * ```
+     *
+     * You can also use the callback version of subqueries or raw expressions:
+     *
+     * ```ts
+     * db.with('jennifer', (db) => db
+     *   .selectFrom('person')
+     *   .where('first_name', '=', 'Jennifer')
+     *   .select(['id', 'first_name', 'gender'])
+     *   .limit(1)
+     * ).insertInto('pet').values((eb) => ({
+     *   owner_id: eb.selectFrom('jennifer').select('id'),
+     *   name: eb.selectFrom('jennifer').select('first_name'),
+     *   species: 'cat',
+     * }))
+     * ```
+     */
     values(insert) {
         const [columns, values] = (0, insert_values_parser_js_1.parseInsertExpression)(insert);
         return new InsertQueryBuilder({

package/dist/cjs/query-builder/update-query-builder.d.ts

@@ -8,7 +8,7 @@ import { ReferenceExpression } from '../parser/reference-parser.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { DrainOuterGeneric, NarrowPartial, Nullable, ShallowRecord, SimplifyResult, SimplifySingleResult, SqlBool } from '../util/type-utils.js';
 import { UpdateQueryNode } from '../operation-node/update-query-node.js';
-import { UpdateObject, UpdateObjectFactory, ExtractUpdateTypeFromReferenceExpression } from '../parser/update-set-parser.js';
+import { UpdateObjectExpression, ExtractUpdateTypeFromReferenceExpression } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
@@ -695,8 +695,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * where "id" = $5
      * ```
      */
-    set(update: UpdateObject<DB, TB, UT>): UpdateQueryBuilder<DB, UT, TB, O>;
-    set(update: UpdateObjectFactory<DB, TB, UT>): UpdateQueryBuilder<DB, UT, TB, O>;
+    set(update: UpdateObjectExpression<DB, TB, UT>): UpdateQueryBuilder<DB, UT, TB, O>;
     set<RE extends ReferenceExpression<DB, UT>>(key: RE, value: ValueExpression<DB, TB, ExtractUpdateTypeFromReferenceExpression<DB, UT, RE>>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
      * Allows you to return data from modified rows.

package/dist/esm/migration/migrator.d.ts

@@ -1,6 +1,7 @@
 import { Kysely } from '../kysely.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 {
@@ -58,7 +59,7 @@ export declare class Migrator {
      * This method goes through all possible migrations provided by the provider and runs the
      * ones whose names come alphabetically after the last migration that has been run. If the
      * list of executed migrations doesn't match the beginning of the list of possible migrations
-     * an error is thrown.
+     * an error is returned.
      *
      * ### Examples
      *
@@ -197,6 +198,20 @@ export interface MigratorProps {
      * This only works on postgres.
      */
     readonly migrationTableSchema?: string;
+    /**
+     * Enforces whether or not migrations must be run in alpha-numeric order.
+     *
+     * When false, migrations must be run in their exact alpha-numeric order.
+     * This is checked against the migrations already run in the database
+     * (`migrationTableName'). This ensures your migrations are always run in
+     * the same order and is the safest option.
+     *
+     * When true, migrations are still run in alpha-numeric order, but
+     * the order is not checked against already-run migrations in the database.
+     * Kysely will simply run all migrations that haven't run yet, in alpha-numeric
+     * order.
+     */
+    readonly allowUnorderedMigrations?: boolean;
 }
 /**
  * All migration methods ({@link Migrator.migrateTo | migrateTo},
@@ -231,12 +246,13 @@ export interface MigrationResultSet {
      */
     readonly results?: MigrationResult[];
 }
+type MigrationDirection = 'Up' | 'Down';
 export interface MigrationResult {
     readonly migrationName: string;
     /**
      * The direction in which this migration was executed.
      */
-    readonly direction: 'Up' | 'Down';
+    readonly direction: MigrationDirection;
     /**
      * The execution status.
      *
@@ -293,3 +309,4 @@ export interface MigrationInfo {
      */
     executedAt?: Date;
 }
+export {};

package/dist/esm/migration/migrator.js

@@ -4,6 +4,7 @@ import { WithSchemaPlugin } from '../plugin/with-schema/with-schema-plugin.js';
 import { freeze, getLast } 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 });
 /**
@@ -70,7 +71,7 @@ export class Migrator {
      * This method goes through all possible migrations provided by the provider and runs the
      * ones whose names come alphabetically after the last migration that has been run. If the
      * list of executed migrations doesn't match the beginning of the list of possible migrations
-     * an error is thrown.
+     * an error is returned.
      *
      * ### Examples
      *
@@ -107,7 +108,7 @@ export class Migrator {
      * ```
      */
     async migrateToLatest() {
-        return this.#migrate(({ migrations }) => migrations.length - 1);
+        return this.#migrate(() => ({ direction: 'Up', step: Infinity }));
     }
     /**
      * Migrate up/down to a specific migration.
@@ -133,15 +134,27 @@ export class Migrator {
      * ```
      */
     async migrateTo(targetMigrationName) {
-        return this.#migrate(({ migrations }) => {
+        return this.#migrate(({ migrations, executedMigrations, pendingMigrations, }) => {
             if (targetMigrationName === NO_MIGRATIONS) {
-                return -1;
+                return { direction: 'Down', step: Infinity };
             }
-            const index = migrations.findIndex((it) => it.name === targetMigrationName);
-            if (index === -1) {
+            if (!migrations.find((m) => m.name === targetMigrationName)) {
                 throw new Error(`migration "${targetMigrationName}" doesn't exist`);
             }
-            return index;
+            const executedIndex = executedMigrations.indexOf(targetMigrationName);
+            const pendingIndex = pendingMigrations.findIndex((m) => m.name === targetMigrationName);
+            if (executedIndex !== -1) {
+                return {
+                    direction: 'Down',
+                    step: executedMigrations.length - executedIndex - 1,
+                };
+            }
+            else if (pendingIndex !== -1) {
+                return { direction: 'Up', step: pendingIndex + 1 };
+            }
+            else {
+                throw new Error(`migration "${targetMigrationName}" isn't executed or pending`);
+            }
         });
     }
     /**
@@ -159,7 +172,7 @@ export class Migrator {
      * ```
      */
     async migrateUp() {
-        return this.#migrate(({ currentIndex, migrations }) => Math.min(currentIndex + 1, migrations.length - 1));
+        return this.#migrate(() => ({ direction: 'Up', step: 1 }));
     }
     /**
      * Migrate one step down.
@@ -176,12 +189,12 @@ export class Migrator {
      * ```
      */
     async migrateDown() {
-        return this.#migrate(({ currentIndex }) => Math.max(currentIndex - 1, -1));
+        return this.#migrate(() => ({ direction: 'Down', step: 1 }));
     }
-    async #migrate(getTargetMigrationIndex) {
+    async #migrate(getMigrationDirectionAndStep) {
         try {
             await this.#ensureMigrationTablesExists();
-            return await this.#runMigrations(getTargetMigrationIndex);
+            return await this.#runMigrations(getMigrationDirectionAndStep);
         }
         catch (error) {
             if (error instanceof MigrationResultSetError) {
@@ -199,6 +212,9 @@ export class Migrator {
     get #migrationLockTable() {
         return this.#props.migrationLockTableName ?? DEFAULT_MIGRATION_LOCK_TABLE;
     }
+    get #allowUnorderedMigrations() {
+        return (this.#props.allowUnorderedMigrations ?? DEFAULT_ALLOW_UNORDERED_MIGRATIONS);
+    }
     get #schemaPlugin() {
         if (this.#migrationTableSchema) {
             return new WithSchemaPlugin(this.#migrationTableSchema);
@@ -309,7 +325,7 @@ export class Migrator {
             .executeTakeFirst();
         return !!lockRow;
     }
-    async #runMigrations(getTargetMigrationIndex) {
+    async #runMigrations(getMigrationDirectionAndStep) {
         const adapter = this.#props.db.getExecutor().adapter;
         const lockOptions = freeze({
             lockTable: this.#props.migrationLockTableName ?? DEFAULT_MIGRATION_LOCK_TABLE,
@@ -323,15 +339,15 @@ export class Migrator {
                 if (state.migrations.length === 0) {
                     return { results: [] };
                 }
-                const targetIndex = getTargetMigrationIndex(state);
-                if (targetIndex === undefined) {
+                const { direction, step } = getMigrationDirectionAndStep(state);
+                if (step <= 0) {
                     return { results: [] };
                 }
-                if (targetIndex < state.currentIndex) {
-                    return await this.#migrateDown(db, state, targetIndex);
+                if (direction === 'Down') {
+                    return await this.#migrateDown(db, state, step);
                 }
-                else if (targetIndex > state.currentIndex) {
-                    return await this.#migrateUp(db, state, targetIndex);
+                else if (direction === 'Up') {
+                    return await this.#migrateUp(db, state, step);
                 }
                 return { results: [] };
             }
@@ -349,10 +365,21 @@ export class Migrator {
     async #getState(db) {
         const migrations = await this.#resolveMigrations();
         const executedMigrations = await this.#getExecutedMigrations(db);
-        this.#ensureMigrationsNotCorrupted(migrations, executedMigrations);
+        this.#ensureNoMissingMigrations(migrations, executedMigrations);
+        if (!this.#allowUnorderedMigrations) {
+            this.#ensureMigrationsInOrder(migrations, executedMigrations);
+        }
+        const pendingMigrations = this.#getPendingMigrations(migrations, executedMigrations);
         return freeze({
             migrations,
-            currentIndex: migrations.findIndex((it) => it.name === getLast(executedMigrations)),
+            executedMigrations,
+            lastMigration: getLast(executedMigrations),
+            pendingMigrations,
+        });
+    }
+    #getPendingMigrations(migrations, executedMigrations) {
+        return migrations.filter((migration) => {
+            return !executedMigrations.includes(migration.name);
         });
     }
     async #resolveMigrations() {
@@ -369,36 +396,43 @@ export class Migrator {
             .withPlugin(this.#schemaPlugin)
             .selectFrom(this.#migrationTable)
             .select('name')
-            .orderBy('name')
+            .orderBy(['timestamp', 'name'])
             .execute();
         return executedMigrations.map((it) => it.name);
     }
-    #ensureMigrationsNotCorrupted(migrations, executedMigrations) {
+    #ensureNoMissingMigrations(migrations, executedMigrations) {
+        // Ensure all executed migrations exist in the `migrations` list.
         for (const executed of executedMigrations) {
             if (!migrations.some((it) => it.name === executed)) {
                 throw new Error(`corrupted migrations: previously executed migration ${executed} is missing`);
             }
         }
-        // Now we know all executed migrations exist in the `migrations` list.
-        // Next we need to make sure that the executed migratiosns are the first
-        // ones in the migration list.
+    }
+    #ensureMigrationsInOrder(migrations, executedMigrations) {
+        // Ensure the executed migrations are the first ones in the migration list.
         for (let i = 0; i < executedMigrations.length; ++i) {
             if (migrations[i].name !== executedMigrations[i]) {
                 throw new Error(`corrupted migrations: expected previously executed migration ${executedMigrations[i]} to be at index ${i} but ${migrations[i].name} was found in its place. New migrations must always have a name that comes alphabetically after the last executed migration.`);
             }
         }
     }
-    async #migrateDown(db, state, targetIndex) {
-        const results = [];
-        for (let i = state.currentIndex; i > targetIndex; --i) {
-            results.push({
-                migrationName: state.migrations[i].name,
+    async #migrateDown(db, state, step) {
+        const migrationsToRollback = state.executedMigrations
+            .slice()
+            .reverse()
+            .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',
-            });
-        }
+            };
+        });
         for (let i = 0; i < results.length; ++i) {
-            const migration = state.migrations.find((it) => it.name === results[i].migrationName);
+            const migration = migrationsToRollback[i];
             try {
                 if (migration.down) {
                     await migration.down(db);
@@ -428,17 +462,17 @@ export class Migrator {
         }
         return { results };
     }
-    async #migrateUp(db, state, targetIndex) {
-        const results = [];
-        for (let i = state.currentIndex + 1; i <= targetIndex; ++i) {
-            results.push({
-                migrationName: state.migrations[i].name,
+    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',
-            });
-        }
-        for (let i = 0; i < results.length; ++i) {
-            const migration = state.migrations.find((it) => it.name === results[i].migrationName);
+            };
+        });
+        for (let i = 0; i < results.length; i++) {
+            const migration = state.pendingMigrations[i];
             try {
                 await migration.up(db);
                 await db

package/dist/esm/query-builder/insert-query-builder.d.ts

@@ -1,7 +1,7 @@
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { SelectExpression, SelectCallback } from '../parser/select-parser.js';
-import { InsertObjectOrList, InsertObjectOrListFactory } from '../parser/insert-values-parser.js';
+import { InsertExpression } from '../parser/insert-values-parser.js';
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { NarrowPartial, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
@@ -184,8 +184,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * }))
      * ```
      */
-    values(insert: InsertObjectOrList<DB, TB>): InsertQueryBuilder<DB, TB, O>;
-    values(insert: InsertObjectOrListFactory<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    values(insert: InsertExpression<DB, TB>): InsertQueryBuilder<DB, TB, O>;
     /**
      * Sets the columns to insert.
      *

package/dist/esm/query-builder/insert-query-builder.js

@@ -18,6 +18,166 @@ export class InsertQueryBuilder {
     constructor(props) {
         this.#props = freeze(props);
     }
+    /**
+     * Sets the values to insert for an {@link Kysely.insertInto | insert} query.
+     *
+     * This method takes an object whose keys are column names and values are
+     * values to insert. In addition to the column's type, the values can be
+     * raw {@link sql} snippets or select queries.
+     *
+     * You must provide all fields you haven't explicitly marked as nullable
+     * or optional using {@link Generated} or {@link ColumnType}.
+     *
+     * The return value of an `insert` query is an instance of {@link InsertResult}. The
+     * {@link InsertResult.insertId | insertId} field holds the auto incremented primary
+     * key if the database returned one.
+     *
+     * On PostgreSQL and some other dialects, you need to call `returning` to get
+     * something out of the query.
+     *
+     * Also see the {@link expression} method for inserting the result of a select
+     * query or any other expression.
+     *
+     * ### Examples
+     *
+     * <!-- siteExample("insert", "Single row", 10) -->
+     *
+     * Insert a single row:
+     *
+     * ```ts
+     * const result = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     age: 40
+     *   })
+     *   .executeTakeFirst()
+     *
+     * // `insertId` is only available on dialects that
+     * // automatically return the id of the inserted row
+     * // such as MySQL and SQLite. On PostgreSQL, for example,
+     * // you need to add a `returning` clause to the query to
+     * // get anything out. See the "returning data" example.
+     * console.log(result.insertId)
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * insert into `person` (`first_name`, `last_name`, `age`) values (?, ?, ?)
+     * ```
+     *
+     * <!-- siteExample("insert", "Multiple rows", 20) -->
+     *
+     * On dialects that support it (for example PostgreSQL) you can insert multiple
+     * rows by providing an array. Note that the return value is once again very
+     * dialect-specific. Some databases may only return the id of the *last* inserted
+     * row and some return nothing at all unless you call `returning`.
+     *
+     * ```ts
+     * await db
+     *   .insertInto('person')
+     *   .values([{
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     age: 40,
+     *   }, {
+     *     first_name: 'Arnold',
+     *     last_name: 'Schwarzenegger',
+     *     age: 70,
+     *   }])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "age") values (($1, $2, $3), ($4, $5, $6))
+     * ```
+     *
+     * <!-- siteExample("insert", "Returning data", 30) -->
+     *
+     * On supported dialects like PostgreSQL you need to chain `returning` to the query to get
+     * the inserted row's columns (or any other expression) as the return value. `returning`
+     * works just like `select`. Refer to `select` method's examples and documentation for
+     * more info.
+     *
+     * ```ts
+     * const result = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     age: 40,
+     *   })
+     *   .returning(['id', 'first_name as name'])
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "age") values ($1, $2, $3) returning "id", "first_name" as "name"
+     * ```
+     *
+     * <!-- siteExample("insert", "Complex values", 40) -->
+     *
+     * In addition to primitives, the values can also be arbitrary expressions.
+     * You can build the expressions by using a callback and calling the methods
+     * on the expression builder passed to it:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const ani = "Ani"
+     * const ston = "ston"
+     *
+     * const result = await db
+     *   .insertInto('person')
+     *   .values(({ ref, selectFrom, fn }) => ({
+     *     first_name: 'Jennifer',
+     *     last_name: sql`concat(${ani}, ${ston})`,
+     *     middle_name: ref('first_name'),
+     *     age: selectFrom('person')
+     *       .select(fn.avg<number>('age')
+     *       .as('avg_age')),
+     *   }))
+     *   .executeTakeFirst()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" (
+     *   "first_name",
+     *   "last_name",
+     *   "middle_name",
+     *   "age"
+     * )
+     * values (
+     *   $1,
+     *   concat($2, $3),
+     *   "first_name",
+     *   (select avg("age") as "avg_age" from "person")
+     * )
+     * ```
+     *
+     * You can also use the callback version of subqueries or raw expressions:
+     *
+     * ```ts
+     * db.with('jennifer', (db) => db
+     *   .selectFrom('person')
+     *   .where('first_name', '=', 'Jennifer')
+     *   .select(['id', 'first_name', 'gender'])
+     *   .limit(1)
+     * ).insertInto('pet').values((eb) => ({
+     *   owner_id: eb.selectFrom('jennifer').select('id'),
+     *   name: eb.selectFrom('jennifer').select('first_name'),
+     *   species: 'cat',
+     * }))
+     * ```
+     */
     values(insert) {
         const [columns, values] = parseInsertExpression(insert);
         return new InsertQueryBuilder({

package/dist/esm/query-builder/update-query-builder.d.ts

@@ -8,7 +8,7 @@ import { ReferenceExpression } from '../parser/reference-parser.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { DrainOuterGeneric, NarrowPartial, Nullable, ShallowRecord, SimplifyResult, SimplifySingleResult, SqlBool } from '../util/type-utils.js';
 import { UpdateQueryNode } from '../operation-node/update-query-node.js';
-import { UpdateObject, UpdateObjectFactory, ExtractUpdateTypeFromReferenceExpression } from '../parser/update-set-parser.js';
+import { UpdateObjectExpression, ExtractUpdateTypeFromReferenceExpression } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
@@ -695,8 +695,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * where "id" = $5
      * ```
      */
-    set(update: UpdateObject<DB, TB, UT>): UpdateQueryBuilder<DB, UT, TB, O>;
-    set(update: UpdateObjectFactory<DB, TB, UT>): UpdateQueryBuilder<DB, UT, TB, O>;
+    set(update: UpdateObjectExpression<DB, TB, UT>): UpdateQueryBuilder<DB, UT, TB, O>;
     set<RE extends ReferenceExpression<DB, UT>>(key: RE, value: ValueExpression<DB, TB, ExtractUpdateTypeFromReferenceExpression<DB, UT, RE>>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
      * Allows you to return data from modified rows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.27.1",
+  "version": "0.27.2",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",