kysely-ctl

kysely-ctl is the official command-line tool for Kysely. We strive to make it TypeScript-first, cross-platform (macOS, Linux, and Windows), cross-runtime (Node.js, Bun, and Deno), and cross-module system (ESM and CommonJS) compatible. We also aim to have feature parity with Knex.js's CLI.

[!NOTE] This is a work in progress. Please report any issues you encounter or suggest any ideas you have in the issues section or in kysely's discord server.

Install

Prerequisites:

kysely-ctl requires kysely >= 0.18.1 to be installed.

Node.js:

npm i -D kysely-ctl

or:

yarn add -D kysely-ctl

or:

pnpm add -D kysely-ctl

Bun

bun add -D kysely-ctl

Deno

Add kysely-ctl to your package.json:

{
  ...
  "scripts": {
    ...
    "kysely": "kysely", // allows running commands with `deno task kysely ...`
    ...
  },
  ...
  "devDependencies": {
    ...
    "kysely-ctl": "^0.8.5"
    ...
  },
  ...
}

Running the following:

deno cache <some_file>

will install kysely-ctl in a node_modules folder.

[!WARNING] It's complicated.

We use c12 for configuration file loading, which uses jiti to load .ts files. jiti doesn't support deno yet. If your config file has Deno-native URL imports, specifiers (e.g. npm:, jsr:), import map resolution, it won't work. This means you can't use kysely-ctl with SQLite on Deno, as it requires a Deno-native SQLite library - Deno doesn't support better-sqlite3 yet.

Use

Configuration

Currently, a kysely.config.ts file is required, in the project root OR .config folder. Run kysely init in your terminal to create one.

import { defineConfig } from "kysely-ctl";

export default defineConfig({
  dialect, // a `Kysely` dialect instance OR the name of an underlying driver library (e.g. `'pg'`).
  dialectConfig, // optional. when `dialect` is the name of an underlying driver library, `dialectConfig` is the options passed to the Kysely dialect that matches that library.
  migrations: { // optional.
    allowJS, // optional. controls whether `.js`, `.cjs` or `.mjs` migrations are allowed. default is `false`.
    getMigrationPrefix, // optional. a function that returns a migration prefix. affects `migrate make` command. default is `() => ${Date.now()}_`.
    migrationFolder, // optional. name of migrations folder. default is `'migrations'`.
    migrator, // optional. a `Kysely` migrator instance. default is `Kysely`'s `Migrator`.
    provider, // optional. a `Kysely` migration provider instance. default is `kysely-ctl`'s `TSFileMigrationProvider`.
  },
  plugins, // optional. `Kysely` plugins list. default is `[]`.
  seeds: { // optional.
    allowJS, // optional. controls whether `.js`, `.cjs` or `.mjs` seeds are allowed. default is `false`.
    getSeedPrefix, // optional. a function that returns a seed prefix. affects `seed make` command. default is `() => ${Date.now()}_`.
    provider, // optional. a seed provider instance. default is `kysely-ctl`'s `FileSeedProvider`.
    seeder, // optional. a seeder instance. default is `kysely-ctl`'s `Seeder`.
    seedFolder, // optional. name of seeds folder. default is `'seeds'`.
  }
});

Alternatively, you can pass a Kysely instance, instead of dialect, dialectConfig & plugins:

import { defineConfig } from "kysely-ctl";
import { kysely } from 'path/to/kysely/instance';

export default defineConfig({
  // ...
  kysely,
  // ...
});

To use Knex's timestamp prefixes:

import { defineConfig, getKnexTimestampPrefix } from "kysely-ctl";

export default defineConfig({
  // ...
  migrations: {
    // ...
    getMigrationPrefix: getKnexTimestampPrefix,
    // ...
  },
  // ...
});

Commands

For more information run kysely -h in your terminal.

Migrate

The migrate module mirrors Knex.js CLI's module of the same name.

knex migrate:<command>

Can now be called as either:

kysely migrate:<command>

or

kysely migrate <command>

[!NOTE] rollback without --all flag is not supported, as Kysely doesn't keep track of "migration batches".

Seed

The seed module mirrors Knex.js CLI's module of the same name.

knex seed:<command>

Can now be called as either:

kysely seed:<command>

or

kysely seed <command>

[!NOTE] We also provide kysely seed list, which is not part of Knex.js CLI.

Acknowledgements

acro5piano who built kysely-migration-cli and inspired this project.

UnJS's amazing tools that help power this project.

Knex.js team for paving the way.