kysely 0.12.2 → 0.13.0

package/README.md

@@ -252,32 +252,56 @@ await db.migration.migrateToLatest(pathToMigrationsFolder)
 ```
 
 to run all migrations that have not yet been run. The migrations are executed in alphabetical
-order by their file name.
+order by their name. See the [migration module](https://koskimas.github.io/kysely/classes/MigrationModule.html) 
+documentation for more info.
 
 Kysely doesn't have a CLI for running migrations and probably never will. This is because Kysely's
 migrations are also written in typescript. To run the migrations, you need to first build the
 typescript code into javascript. The CLI would cause confusion over which migrations are being
-run, the typescript ones or the javascript ones. If we added support for both, it would mean the
-CLI would depend on a typescript compiler, which most production environments don't (and shouldn't)
+run, the typescript ones or the javascript ones. If we added support for both, the CLI would 
+need to depend on a typescript compiler, which most production environments don't (and shouldn't)
 have. You will probably want to add a simple migration script to your projects like this:
 
 ```ts
 import path from 'path'
+
+// This example assumes you have a file named `database.ts` that
+// creates and exports a `Kysely` instance `db`. You can just
+// as well create a new `Kysely` instance in the function below
+// or do something completely different to obtain an instance
+// of `Kysely`.
 import { db } from './database'
 
-db.migration
-  .migrateToLatest(path.join(__dirname, 'migrations'))
-  .then(() => db.destroy())
+async function migrateToLatest() {
+  const { error, results } = await db.migration.migrateToLatest(
+    path.join(__dirname, 'migrations')
+  )
+
+  // Destroy the `Kysely` instance to make the script exit faster.
+  await db.destroy()
+
+  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 migrate')
+    console.error(error)
+    process.exit(1)
+  }
+}
+
+migrateToLatest()
 ```
 
 The migration methods use a lock on the database level, and parallel calls are executed serially.
 This means that you can safely call `migrateToLatest` and other migration methods from multiple
 server instances simultaneously and the migrations are guaranteed to only be executed once.
 
-NOTE: Only `db.migration.migrateToLatest` method is implemented at the moment. There is no way
-to run the down migrations, or to go forward to a specific migration. These methods will be
-added soon.
-
 # Why not just contribute to knex
 
 Kysely is very similar to knex, but it also attempts to fix things that I personally find not-so-good

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

@@ -1,6 +1,6 @@
 import { Kysely } from '../../kysely.js';
-import { DialectAdapter } from '../dialect-adapter.js';
-export declare class MysqlAdapter implements DialectAdapter {
+import { DialectAdapterBase } from '../dialect-adapter-base.js';
+export declare class MysqlAdapter extends DialectAdapterBase {
     /**
      * Whether or not this dialect supports transactional DDL.
      *

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

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MysqlAdapter = void 0;
+const dialect_adapter_base_js_1 = require("../dialect-adapter-base.js");
 const LOCK_ID = 'ea586330-2c93-47c8-908d-981d9d270f9d';
 const LOCK_TIMEOUT_SECONDS = 60 * 60;
-class MysqlAdapter {
+class MysqlAdapter extends dialect_adapter_base_js_1.DialectAdapterBase {
     get supportsTransactionalDdl() {
         return false;
     }

package/dist/cjs/dialect/postgres/postgres-adapter.d.ts

@@ -1,6 +1,6 @@
 import { Kysely } from '../../kysely.js';
-import { DialectAdapter } from '../dialect-adapter.js';
-export declare class PostgresAdapter implements DialectAdapter {
+import { DialectAdapterBase } from '../dialect-adapter-base.js';
+export declare class PostgresAdapter extends DialectAdapterBase {
     /**
      * Whether or not this dialect supports transactional DDL.
      *

package/dist/cjs/dialect/postgres/postgres-adapter.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostgresAdapter = void 0;
+const dialect_adapter_base_js_1 = require("../dialect-adapter-base.js");
 // Random id for our transaction lock.
 const LOCK_ID = '3853314791062309107';
-class PostgresAdapter {
+class PostgresAdapter extends dialect_adapter_base_js_1.DialectAdapterBase {
     get supportsTransactionalDdl() {
         return true;
     }

package/dist/cjs/dialect/sqlite/sqlite-adapter.d.ts

@@ -1,5 +1,5 @@
-import { DialectAdapter } from '../dialect-adapter.js';
-export declare class SqliteAdapter implements DialectAdapter {
+import { DialectAdapterBase } from '../dialect-adapter-base.js';
+export declare class SqliteAdapter implements DialectAdapterBase {
     /**
      * Whether or not this dialect supports transactional DDL.
      *

package/dist/cjs/index.d.ts

@@ -140,7 +140,7 @@ export * from './introspection/database-introspector.js';
 export * from './util/compilable.js';
 export * from './util/log.js';
 export { AnyColumn, UnknownRow, AnySelectQueryBuilder, } from './util/type-utils.js';
-export { SelectExpression, SelectExpressionOrList, } from './parser/select-parser.js';
+export { SelectExpression, SelectExpressionOrList, Selection, } from './parser/select-parser.js';
 export { ReferenceExpression, ReferenceExpressionOrList, } from './parser/reference-parser.js';
 export { ValueExpression, ValueExpressionOrList, } from './parser/value-parser.js';
 export { FilterValueExpression, FilterValueExpressionOrList, ExistsExpression, FilterOperator, } from './parser/filter-parser.js';

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

@@ -3,6 +3,73 @@ import { DialectAdapter } from '../dialect/dialect-adapter.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 declare type MigrationsOrFolderPath = Record<string, Migration> | string;
+export interface Migration {
+    up(db: Kysely<any>): Promise<void>;
+    down?(db: Kysely<any>): Promise<void>;
+}
+/**
+ * Type for the NO_MIGRATIONS constant. Never create one of these.
+ */
+export interface NoMigrations {
+    readonly __noMigrations__: true;
+}
+/**
+ * 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 declare class MigrationModule {
     #private;
     constructor(db: Kysely<any>, adapter: DialectAdapter);
@@ -10,26 +77,45 @@ export declare class MigrationModule {
      * Runs all migrations that have not yet been run.
      *
      * The only argument must either be a file path to the folder that contains all migrations
-     * OR an object that contains all migrations (not just the ones that need to be run).
+     * OR an object that contains all migrations (not just the ones that need to be executed).
      * The keys in the object must be the unique migration names.
      *
+     * 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 (passed as the argument) and runs the
      * ones whose names are alphabetically after the last migration that has been run. If the
-     * list of executed migrations doesn't match the list of possible migrations, and error
-     * is thrown.
+     * list of executed migrations doesn't match the beginning of the list of possible migrations
+     * an error is thrown.
      *
      * ### Examples
      *
      * ```ts
-     * await db.migration.migrateToLatest(
+     * const { error, results } = await db.migration.migrateToLatest(
      *   path.join(__dirname, 'migrations')
      * )
+     *
+     * 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)
+     * }
      * ```
      *
      * In the next example, we use a record of migration objects instead of file folder path.
      * The keys in the object are migration names that can be anything you want. The order of
      * the migrations is determined based on the alphabetical order of the keys in the record.
-     * This can be useful if you are using a bundler like webpack or esbuild.
+     * This version of the `migrateToLatest` method can be useful if you are using a bundler
+     * like webpack or esbuild.
      *
      * ```ts
      * await db.migration.migrateToLatest({
@@ -57,10 +143,67 @@ export declare class MigrationModule {
      * })
      * ```
      */
-    migrateToLatest(migrationsFolderPath: string): Promise<void>;
-    migrateToLatest(allMigrations: Record<string, Migration>): Promise<void>;
-}
-export interface Migration {
-    up(db: Kysely<any>): Promise<void>;
-    down?(db: Kysely<any>): Promise<void>;
+    migrateToLatest(migrationsFolderPath: string): Promise<MigrationResultSet>;
+    migrateToLatest(allMigrations: Record<string, Migration>): Promise<MigrationResultSet>;
+    /**
+     * Migrate up/down to a specific migration.
+     *
+     * Otherwise works just like {@link migrateToLatest}. The first argument
+     * behaves the same, the output is the same etc.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.migration.migrateTo(
+     *   path.join(__dirname, 'migrations'),
+     *   '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` migration for
+     * the first migration. In case you want to migrate down ALL migrations
+     * you can use a special constant `NO_MIGRATIONS`:
+     *
+     * ```ts
+     * await db.migration.migrateTo(
+     *   path.join(__dirname, 'migrations'),
+     *   NO_MIGRATIONS,
+     * )
+     * ```
+     */
+    migrateTo(migrationsFolderPath: string, targetMigrationName: string | NoMigrations): Promise<MigrationResultSet>;
+    migrateTo(allMigrations: Record<string, Migration>, targetMigrationName: string | NoMigrations): Promise<MigrationResultSet>;
+    /**
+     * Migrate one step up.
+     *
+     * Otherwise works just like {@link migrateToLatest}. The only argument
+     * behaves the same, the output is the same etc.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.migration.migrateUp(
+     *   path.join(__dirname, 'migrations'),
+     * )
+     * ```
+     */
+    migrateUp(migrationsFolderPath: string): Promise<MigrationResultSet>;
+    migrateUp(allMigrations: Record<string, Migration>): Promise<MigrationResultSet>;
+    /**
+     * Migrate one step down.
+     *
+     * Otherwise works just like {@link migrateToLatest}. The only argument
+     * behaves the same, the output is the same etc.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.migration.migrateDown(
+     *   path.join(__dirname, 'migrations'),
+     * )
+     * ```
+     */
+    migrateDown(migrationsFolderPath: string): Promise<MigrationResultSet>;
+    migrateDown(allMigrations: Record<string, Migration>): Promise<MigrationResultSet>;
 }