kysely 0.12.2 → 0.15.0

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

@@ -0,0 +1,234 @@
+import { Kysely } from '../kysely.js';
+export declare const MIGRATION_TABLE = "kysely_migration";
+export declare const MIGRATION_LOCK_TABLE = "kysely_migration_lock";
+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.
+ *
+ * ### Example
+ *
+ * This example uses the {@link FileMigrationProvider} that reads migrations
+ * files from a single folder. You can easily implement your own
+ * {@link MigrationProvider} if you want to provide migrations some
+ * other way.
+ *
+ * ```ts
+ * const migrator = new Migrator({
+ *   db,
+ *   // The constructor signature of FileMigrationProvider is a
+ *   // bit weird to keep Kysely independent of node.js or any
+ *   // other environment.
+ *   provider: new FileMigrationProvider(
+ *     fs.readdir,
+ *     path.join,
+ *     // Path to the folder that contains all your migrations.
+ *     'migrations'
+ *   )
+ * })
+ * ```
+ */
+export declare class Migrator {
+    #private;
+    constructor(props: MigratorProps);
+    /**
+     * Runs all migrations that have not yet been run.
+     *
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed. See the examples below.
+     *
+     * 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.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import * as path from 'path'
+     * import * as fs from 'fs/promises'
+     *
+     * const db = new Kysely<Database>({
+     *   dialect: new PostgresDialect({
+     *     host: 'localhost',
+     *     database: 'kysely_test',
+     *   }),
+     * })
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   // The constructor signature of FileMigrationProvider is a
+     *   // bit weird to keep Kysely independent of node.js or any
+     *   // other environment.
+     *   provider: new FileMigrationProvider(
+     *     fs.readdir,
+     *     path.join,
+     *     // Path to the folder that contains all your migrations.
+     *     'migrations'
+     *   )
+     * })
+     *
+     * const { error, results } = await migrator.migrateToLatest()
+     *
+     * results?.forEach((it) => {
+     *   if (it.status === 'Success') {
+     *     console.log(`migration "${it.migrationName}" was executed successfully`)
+     *   } else if (it.status === 'Error') {
+     *     console.error(`failed to execute migration "${it.migrationName}"`)
+     *   }
+     * })
+     *
+     * if (error) {
+     *   console.error('failed to run `migrateToLatest`')
+     *   console.error(error)
+     * }
+     * ```
+     */
+    migrateToLatest(): Promise<MigrationResultSet>;
+    /**
+     * Migrate up/down to a specific migration.
+     *
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await migrator.migrateTo('some_migration')
+     * ```
+     *
+     * If you specify the name of the first migration, this method migrates
+     * down to the first migration, but doesn't run the `down` method of
+     * the first migration. In case you want to migrate all the way down,
+     * you can use a special constant `NO_MIGRATIONS`:
+     *
+     * ```ts
+     * await migrator.migrateTo(NO_MIGRATIONS)
+     * ```
+     */
+    migrateTo(targetMigrationName: string | NoMigrations): Promise<MigrationResultSet>;
+    /**
+     * Migrate one step up.
+     *
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await migrator.migrateUp()
+     * ```
+     */
+    migrateUp(): Promise<MigrationResultSet>;
+    /**
+     * Migrate one step down.
+     *
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await migrator.migrateDown()
+     * ```
+     */
+    migrateDown(): Promise<MigrationResultSet>;
+}
+export interface MigratorProps {
+    readonly db: Kysely<any>;
+    readonly provider: MigrationProvider;
+}
+/**
+ * All migration methods ({@link MigrationModule.migrateTo | migrateTo},
+ * {@link MigrationModule.migrateToLatest | migrateToLatest} etc.) never
+ * throw but return this object instead.
+ */
+export interface MigrationResultSet {
+    /**
+     * This is defined if something went wrong.
+     *
+     * An error may have occurred in one of the migrations in which case the
+     * {@link results} list contains an item with `status === 'Error'` to
+     * indicate which migration failed.
+     *
+     * An error may also have occurred before Kysely was able to figure out
+     * which migrations should be executed, in which case the {@link results}
+     * list is undefined.
+     */
+    readonly error?: unknown;
+    /**
+     * {@link MigrationResult} for each individual migration that was supposed
+     * to be executed by the operation.
+     *
+     * If all went well, each result's `status` is `Success`. If some migration
+     * failed, the failed migration's result's `status` is `Error` and all
+     * results after that one have `status` ´NotExecuted`.
+     *
+     * This property can be undefined if an error occurred before Kysely was
+     * able to figure out which migrations should be executed.
+     *
+     * If this list is empty, there were no migrations to execute.
+     */
+    readonly results?: MigrationResult[];
+}
+export interface MigrationResult {
+    readonly migrationName: string;
+    /**
+     * The direction in which this migration was executed.
+     */
+    readonly direction: 'Up' | 'Down';
+    /**
+     * The execution status.
+     *
+     *  - `Success` means the migration was successfully executed. Note that
+     *    if any of the later migrations in the {@link MigrationResult.results}
+     *    list failed (have status `Error`) AND the dialect supports transactional
+     *    DDL, even the successfull migrations were rolled back.
+     *
+     *  - `Error` means the migration failed. In this case the
+     *    {@link MigrationResult.error} contains the error.
+     *
+     *  - `NotExecuted` means that the migration was supposed to be executed
+     *    but wasn't because an earlier migration failed.
+     */
+    readonly status: 'Success' | 'Error' | 'NotExecuted';
+}
+export interface MigrationProvider {
+    /**
+     * Returns all migrations, old and new.
+     *
+     * For example if you have your migrations in a folder as separate files,
+     * you can use the {@link FileMigrationProvider} that implements this
+     * method to return all migrations in a folder.
+     *
+     * The keys of the returned object are migration names and values are the
+     * migrations. The order of the migrations is determined by the alphabetical
+     * order of the migration names. The items in the object don't need to be
+     * sorted, they are sorted by Kysely.
+     */
+    getMigrations(): Promise<Record<string, Migration>>;
+}
+/**
+ * Type for the {@link NO_MIGRATIONS} constant. Never create one of these.
+ */
+export interface NoMigrations {
+    readonly __noMigrations__: true;
+}

package/dist/esm/migration/migrator.js

@@ -0,0 +1,413 @@
+import { freeze, getLast } from '../util/object-utils.js';
+import { PRIVATE_ADAPTER } from '../util/private-symbols.js';
+export const MIGRATION_TABLE = 'kysely_migration';
+export const MIGRATION_LOCK_TABLE = 'kysely_migration_lock';
+export const MIGRATION_LOCK_ID = 'migration_lock';
+export const NO_MIGRATIONS = freeze({ __noMigrations__: true });
+/**
+ * A class for running migrations.
+ *
+ * ### Example
+ *
+ * This example uses the {@link FileMigrationProvider} that reads migrations
+ * files from a single folder. You can easily implement your own
+ * {@link MigrationProvider} if you want to provide migrations some
+ * other way.
+ *
+ * ```ts
+ * const migrator = new Migrator({
+ *   db,
+ *   // The constructor signature of FileMigrationProvider is a
+ *   // bit weird to keep Kysely independent of node.js or any
+ *   // other environment.
+ *   provider: new FileMigrationProvider(
+ *     fs.readdir,
+ *     path.join,
+ *     // Path to the folder that contains all your migrations.
+ *     'migrations'
+ *   )
+ * })
+ * ```
+ */
+export class Migrator {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    /**
+     * Runs all migrations that have not yet been run.
+     *
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed. See the examples below.
+     *
+     * 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.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import * as path from 'path'
+     * import * as fs from 'fs/promises'
+     *
+     * const db = new Kysely<Database>({
+     *   dialect: new PostgresDialect({
+     *     host: 'localhost',
+     *     database: 'kysely_test',
+     *   }),
+     * })
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   // The constructor signature of FileMigrationProvider is a
+     *   // bit weird to keep Kysely independent of node.js or any
+     *   // other environment.
+     *   provider: new FileMigrationProvider(
+     *     fs.readdir,
+     *     path.join,
+     *     // Path to the folder that contains all your migrations.
+     *     'migrations'
+     *   )
+     * })
+     *
+     * const { error, results } = await migrator.migrateToLatest()
+     *
+     * results?.forEach((it) => {
+     *   if (it.status === 'Success') {
+     *     console.log(`migration "${it.migrationName}" was executed successfully`)
+     *   } else if (it.status === 'Error') {
+     *     console.error(`failed to execute migration "${it.migrationName}"`)
+     *   }
+     * })
+     *
+     * if (error) {
+     *   console.error('failed to run `migrateToLatest`')
+     *   console.error(error)
+     * }
+     * ```
+     */
+    async migrateToLatest() {
+        return this.#migrate(({ migrations }) => migrations.length - 1);
+    }
+    /**
+     * Migrate up/down to a specific migration.
+     *
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await migrator.migrateTo('some_migration')
+     * ```
+     *
+     * If you specify the name of the first migration, this method migrates
+     * down to the first migration, but doesn't run the `down` method of
+     * the first migration. In case you want to migrate all the way down,
+     * you can use a special constant `NO_MIGRATIONS`:
+     *
+     * ```ts
+     * await migrator.migrateTo(NO_MIGRATIONS)
+     * ```
+     */
+    async migrateTo(targetMigrationName) {
+        return this.#migrate(({ migrations }) => {
+            if (targetMigrationName === NO_MIGRATIONS) {
+                return -1;
+            }
+            const index = migrations.findIndex((it) => it.name === targetMigrationName);
+            if (index === -1) {
+                throw new Error(`migration "${targetMigrationName}" doesn't exist`);
+            }
+            return index;
+        });
+    }
+    /**
+     * Migrate one step up.
+     *
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await migrator.migrateUp()
+     * ```
+     */
+    async migrateUp() {
+        return this.#migrate(({ currentIndex, migrations }) => Math.min(currentIndex + 1, migrations.length - 1));
+    }
+    /**
+     * Migrate one step down.
+     *
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await migrator.migrateDown()
+     * ```
+     */
+    async migrateDown() {
+        return this.#migrate(({ currentIndex }) => Math.max(currentIndex - 1, -1));
+    }
+    async #migrate(getTargetMigrationIndex) {
+        try {
+            await this.#ensureMigrationTablesExists();
+            return await this.#runMigrations(getTargetMigrationIndex);
+        }
+        catch (error) {
+            if (error instanceof MigrationResultSetError) {
+                return error.resultSet;
+            }
+            return { error };
+        }
+    }
+    async #ensureMigrationTablesExists() {
+        await this.#ensureMigrationTableExists();
+        await this.#ensureMigrationLockTableExists();
+        await this.#ensureLockRowExists();
+    }
+    async #ensureMigrationTableExists() {
+        if (!(await this.#doesTableExists(MIGRATION_TABLE))) {
+            try {
+                await this.#props.db.schema
+                    .createTable(MIGRATION_TABLE)
+                    .ifNotExists()
+                    .addColumn('name', 'varchar(255)', (col) => col.notNull().primaryKey())
+                    // The migration run time as ISO string. This is not a real date type as we
+                    // can't know which data type is supported by all future dialects.
+                    .addColumn('timestamp', 'varchar(255)', (col) => col.notNull())
+                    .execute();
+            }
+            catch (error) {
+                // At least on PostgreSQL, `if not exists` doesn't guarantee the `create table`
+                // query doesn't throw if the table already exits. That's why we check if
+                // the table exist here and ignore the error if it does.
+                if (!(await this.#doesTableExists(MIGRATION_TABLE))) {
+                    throw error;
+                }
+            }
+        }
+    }
+    async #ensureMigrationLockTableExists() {
+        if (!(await this.#doesTableExists(MIGRATION_LOCK_TABLE))) {
+            try {
+                await this.#props.db.schema
+                    .createTable(MIGRATION_LOCK_TABLE)
+                    .ifNotExists()
+                    .addColumn('id', 'varchar(255)', (col) => col.notNull().primaryKey())
+                    .addColumn('is_locked', 'integer', (col) => col.notNull().defaultTo(0))
+                    .execute();
+            }
+            catch (error) {
+                // At least on PostgreSQL, `if not exists` doesn't guarantee the `create table`
+                // query doesn't throw if the table already exits. That's why we check if
+                // the table exist here and ignore the error if it does.
+                if (!(await this.#doesTableExists(MIGRATION_LOCK_TABLE))) {
+                    throw error;
+                }
+            }
+        }
+    }
+    async #ensureLockRowExists() {
+        if (!(await this.#doesLockRowExists())) {
+            try {
+                await this.#props.db
+                    .insertInto(MIGRATION_LOCK_TABLE)
+                    .values({ id: MIGRATION_LOCK_ID })
+                    .execute();
+            }
+            catch (error) {
+                if (!(await this.#doesLockRowExists())) {
+                    throw error;
+                }
+            }
+        }
+    }
+    async #doesTableExists(tableName) {
+        const metadata = await this.#props.db.introspection.getMetadata({
+            withInternalKyselyTables: true,
+        });
+        return !!metadata.tables.find((it) => it.name === tableName);
+    }
+    async #doesLockRowExists() {
+        const lockRow = await this.#props.db
+            .selectFrom(MIGRATION_LOCK_TABLE)
+            .where('id', '=', MIGRATION_LOCK_ID)
+            .select('id')
+            .executeTakeFirst();
+        return !!lockRow;
+    }
+    async #runMigrations(getTargetMigrationIndex) {
+        const run = async (db) => {
+            try {
+                await this.#props.db[PRIVATE_ADAPTER].acquireMigrationLock(db);
+                const state = await this.#getState(db);
+                if (state.migrations.length === 0) {
+                    return { results: [] };
+                }
+                const targetIndex = getTargetMigrationIndex(state);
+                if (targetIndex === undefined) {
+                    return { results: [] };
+                }
+                if (targetIndex < state.currentIndex) {
+                    return await this.#migrateDown(db, state, targetIndex);
+                }
+                else if (targetIndex > state.currentIndex) {
+                    return await this.#migrateUp(db, state, targetIndex);
+                }
+                return { results: [] };
+            }
+            finally {
+                await this.#props.db[PRIVATE_ADAPTER].releaseMigrationLock(db);
+            }
+        };
+        if (this.#props.db[PRIVATE_ADAPTER].supportsTransactionalDdl) {
+            return this.#props.db.transaction().execute(run);
+        }
+        else {
+            return this.#props.db.connection().execute(run);
+        }
+    }
+    async #getState(db) {
+        const migrations = await this.#resolveMigrations();
+        const executedMigrations = await this.#getExecutedMigrations(db);
+        this.#ensureMigrationsNotCorrupted(migrations, executedMigrations);
+        return freeze({
+            migrations,
+            currentIndex: migrations.findIndex((it) => it.name === getLast(executedMigrations)),
+        });
+    }
+    async #resolveMigrations() {
+        const allMigrations = await this.#props.provider.getMigrations();
+        return Object.keys(allMigrations)
+            .sort()
+            .map((name) => ({
+            ...allMigrations[name],
+            name,
+        }));
+    }
+    async #getExecutedMigrations(db) {
+        const executedMigrations = await db
+            .selectFrom(MIGRATION_TABLE)
+            .select('name')
+            .orderBy('name')
+            .execute();
+        return executedMigrations.map((it) => it.name);
+    }
+    #ensureMigrationsNotCorrupted(migrations, executedMigrations) {
+        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.
+        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,
+                direction: 'Down',
+                status: 'NotExecuted',
+            });
+        }
+        for (let i = 0; i < results.length; ++i) {
+            const migration = state.migrations.find((it) => it.name === results[i].migrationName);
+            try {
+                if (migration.down) {
+                    await migration.down(db);
+                    await db
+                        .deleteFrom(MIGRATION_TABLE)
+                        .where('name', '=', migration.name)
+                        .execute();
+                    results[i] = {
+                        migrationName: migration.name,
+                        direction: 'Down',
+                        status: 'Success',
+                    };
+                }
+            }
+            catch (error) {
+                results[i] = {
+                    migrationName: migration.name,
+                    direction: 'Down',
+                    status: 'Error',
+                };
+                throw new MigrationResultSetError({
+                    error,
+                    results,
+                });
+            }
+        }
+        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,
+                direction: 'Up',
+                status: 'NotExecuted',
+            });
+        }
+        for (let i = 0; i < results.length; ++i) {
+            const migration = state.migrations.find((it) => it.name === results[i].migrationName);
+            try {
+                await migration.up(db);
+                await db
+                    .insertInto(MIGRATION_TABLE)
+                    .values({
+                    name: migration.name,
+                    timestamp: new Date().toISOString(),
+                })
+                    .execute();
+                results[i] = {
+                    migrationName: migration.name,
+                    direction: 'Up',
+                    status: 'Success',
+                };
+            }
+            catch (error) {
+                results[i] = {
+                    migrationName: migration.name,
+                    direction: 'Up',
+                    status: 'Error',
+                };
+                throw new MigrationResultSetError({
+                    error,
+                    results,
+                });
+            }
+        }
+        return { results };
+    }
+}
+class MigrationResultSetError extends Error {
+    #resultSet;
+    constructor(result) {
+        super();
+        this.#resultSet = result;
+    }
+    get resultSet() {
+        return this.#resultSet;
+    }
+}

package/dist/esm/operation-node/check-constraint-node.d.ts

@@ -11,5 +11,5 @@ export interface CheckConstraintNode extends OperationNode {
  */
 export declare const CheckConstraintNode: Readonly<{
     is(node: OperationNode): node is CheckConstraintNode;
-    create(expressionSql: string, constraintName?: string | undefined): CheckConstraintNode;
+    create(expression: RawNode, constraintName?: string | undefined): CheckConstraintNode;
 }>;

package/dist/esm/operation-node/check-constraint-node.js

@@ -1,5 +1,4 @@
 import { freeze } from '../util/object-utils.js';
-import { RawNode } from './raw-node.js';
 import { IdentifierNode } from './identifier-node.js';
 /**
  * @internal
@@ -8,10 +7,10 @@ export const CheckConstraintNode = freeze({
     is(node) {
         return node.kind === 'CheckConstraintNode';
     },
-    create(expressionSql, constraintName) {
+    create(expression, constraintName) {
         return freeze({
             kind: 'CheckConstraintNode',
-            expression: RawNode.createWithSql(expressionSql),
+            expression,
             name: constraintName ? IdentifierNode.create(constraintName) : undefined,
         });
     },