kysely-ctl

When creating a new migration file, you must export an up function to apply the changes and optionally export a down function to revert them.

Both functions receive a db instance of type Kysely<any>. Using any for the database type is recommended to ensure migrations remain 'frozen in time' and are not broken by subsequent changes to your main database interface. Alternatively, you can use a specific 'snapshot' version of your database interface.

• up(db): Mandatory. Contains the logic to apply the migration.
• down(db): Optional. Contains the logic to undo the changes made by up. You can safely delete this function if you do not need rollback capabilities.

/**
 * @param {import('kysely').Kysely<any>} db
 * @returns {Promise<void>}
 */
export async function up(db) {
	// up migration code goes here...
}

/**
 * @param {import('kysely').Kysely<any>} db
 * @returns {Promise<void>}
 */
export async function down(db) {
	// down migration code goes here...
}

A kysely.config.ts file is required in your project root or a .config folder. You can create one by running kysely init.

Use defineConfig to specify how the CLI interacts with your database, migrations, and seeds. You can either provide a dialect and dialectConfig or pass an existing Kysely instance directly.

Key Configuration Options:

• destroyOnExit (boolean): Whether the Kysely instance should be destroyed when a command finishes. Defaults to true.
• dialect: A Kysely dialect instance or the name of a driver library (e.g., 'pg').
• dialectConfig: Options passed to the driver library if dialect is a string.
• kysely: An existing Kysely instance to reuse.
• migrations: Configuration for migrations (folder, provider, migrator, etc.).
• seeds: Configuration for seeds (folder, provider, seeder, etc.).
• plugins: A list of Kysely plugins.

import { defineConfig } from "kysely-ctl";

export default defineConfig({
  destroyOnExit, // optional. default is `true`.
  dialect, // a `Kysely` dialect instance OR the name of an underlying driver library (e.g. `'pg'`).
  dialectConfig, // optional.
  migrations: {
    allowJS, // optional. default is `false`.
    getMigrationPrefix, // optional. default is `() => ${Date.now()}_`.
    migrationFolder, // optional. default is "migrations" next to config.
    migrator, // optional.
    provider, // optional. default is `kysely-ctl`'s `TSFileMigrationProvider`.
  },
  plugins, // optional. default is `[]`.
  seeds: {
    allowJS, // optional. default is `false`.
    getSeedPrefix, // optional. default is `() => ${Date.now()}_`.
    provider, // optional. default is `kysely-ctl`'s `FileSeedProvider`.
    seeder, // optional.
    seedFolder, // optional. default is "seeds" next to config.
  }
});

The tsdown.config.mts file defines the build configuration for the project using tsdown. It specifies entry points, output formats, and automated checks for module compatibility.

Key configuration areas include:

• Entry points: Defines the source files to be bundled (./src/index.mts and ./src/bin.mts).
• Formats: Set to ['esm'] to ensure the output is ECMAScript Modules.
• Exports: Configures the bin export for the kysely command, while excluding the bin key from the public package exports.
• Automated Checks: Enables attw (Are The Types Wrong?) with an esm-only profile and publint to ensure package quality and compatibility.
• Asset Management: Copies template files from ./src/templates to the dist directory.

import { defineConfig } from 'tsdown'

export default defineConfig({
	attw: {
		enabled: true,
		level: 'error',
		profile: 'esm-only',
	},
	clean: true,
	copy: {
		from: ['./src/templates'],
		to: 'dist',
	},
	dts: true,
	entry: ['./src/index.mts', './src/bin.mts'],
	exports: {
		bin: {
			kysely: './src/bin.mts',
		},
		enabled: 'local-only',
		exclude: ['bin'],
	},
	format: ['esm'],
	publint: {
		enabled: true,
	},
	shims: true,
	tsconfig: './tsconfig.prod.json',
})

Migrations can be configured in two ways: Migratorless (folder-based) or Migratorful (custom logic).

Migratorless Migrations

Used when you want kysely-ctl to manage migrations from a specific folder.

• migrationFolder: The directory containing migration files.
• allowJS: Whether to allow .js migration files in addition to .ts.
• provider: A custom MigrationProvider to handle how migrations are stored/retrieved.

Migratorful Migrations

Used when you want to provide your own Migrator instance.

• migrator: A factory function that receives the Kysely instance and returns a Migrator.
• getMigrationPrefix: A function to determine the migration file prefix.

Note: If you provide a migrator, you cannot provide migrationFolder or provider directly in the same config block.

// Migratorless example
const migrationsConfig = {
  migrationFolder: './src/migrations',
  allowJS: true
};

// Migratorful example
const migrationsConfig = {
  migrator: (db) => new Migrator({ /* ... */ })
};

The KyselyCTLConfig object is the primary way to configure kysely-ctl. It supports three main modes of operation: defining a dialect and its configuration, providing a custom Kysely instance, or using a resolvable dialect string.

Configuration Modes

1. Dialect Mode: Specify a dialect (e.g., 'pg', 'mysql2', 'better-sqlite3') and its corresponding dialectConfig. This is the recommended way for most users.
2. Kysely Instance Mode: Provide an existing kysely instance directly. In this mode, dialect and dialectConfig must not be provided.
3. Resolvable Dialect Mode: Use supported dialect strings that map to specific configuration shapes.

Supported Dialects and Config Types

Global Options

• destroyOnExit: Boolean indicating if the connection should be destroyed on exit.
• plugins: An array of KyselyPlugin instances (can be provided as a factory function).
• migrations: Configuration for migrations (see Migrations Configuration).
• seeds: Configuration for seeds (see Seeds Configuration).

// Example: Using a dialect
const config: KyselyCTLConfig = {
  dialect: 'pg',
  dialectConfig: {
    connectionString: 'postgres://user:pass@localhost:5432/db'
  }
};

// Example: Using an existing Kysely instance
const configWithInstance: KyselyCTLConfig = {
  kysely: myExistingKyselyInstance
};