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:

1npm i -D kysely-ctl

or:

1yarn add -D kysely-ctl

or:

1pnpm add -D kysely-ctl

Bun

1bun add -D kysely-ctl

Deno

1deno add -D npm:kysely-ctl

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.

1import { defineConfig } from "kysely-ctl";
2
3export default defineConfig({
4  destroyOnExit, // optional. dictates whether the (resolved) `kysely` instance should be destroyed when a command is finished executing. default is `true`.
5  dialect, // a `Kysely` dialect instance OR the name of an underlying driver library (e.g. `'pg'`).
6  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.
7  migrations: { // optional.
8    allowJS, // optional. controls whether `.js`, `.cjs` or `.mjs` migrations are allowed. default is `false`.
9    getMigrationPrefix, // optional. a function that returns a migration prefix. affects `migrate make` command. default is `() => ${Date.now()}_`.
10    migrationFolder, // optional. name of migrations folder. default is `'migrations'`.
11    migrator, // optional. a `Kysely` migrator instance factory of shape `(db: Kysely<any>) => Migrator | Promise<Migrator>`. default is `Kysely`'s `Migrator`.
12    provider, // optional. a `Kysely` migration provider instance. default is `kysely-ctl`'s `TSFileMigrationProvider`.
13  },
14  plugins, // optional. `Kysely` plugins list. default is `[]`.
15  seeds: { // optional.
16    allowJS, // optional. controls whether `.js`, `.cjs` or `.mjs` seeds are allowed. default is `false`.
17    getSeedPrefix, // optional. a function that returns a seed prefix. affects `seed make` command. default is `() => ${Date.now()}_`.
18    provider, // optional. a seed provider instance. default is `kysely-ctl`'s `FileSeedProvider`.
19    seeder, // optional. a seeder instance factory of shape `(db: Kysely<any>) => Seeder | Promise<Seeder>`. default is `kysely-ctl`'s `Seeder`.
20    seedFolder, // optional. name of seeds folder. default is `'seeds'`.
21  }
22});

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

1import { defineConfig } from "kysely-ctl";
2import { kysely } from 'path/to/kysely/instance';
3
4export default defineConfig({
5  destroyOnExit, // optional. dictates whether the `kysely` instance should be destroyed when a command is finished executing. default is `true`.
6  // ...
7  kysely,
8  // ...
9});

To use Knex's timestamp prefixes:

1import { defineConfig, getKnexTimestampPrefix } from "kysely-ctl";
2
3export default defineConfig({
4  // ...
5  migrations: {
6    // ...
7    getMigrationPrefix: getKnexTimestampPrefix,
8    // ...
9  },
10  // ...
11});

Commands

For more information run kysely -h in your terminal.

Migrate

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

1knex migrate:<command>

Can now be called as either:

1kysely migrate:<command>

or

1kysely 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.

1knex seed:<command>

Can now be called as either:

1kysely seed:<command>

or

1kysely seed <command>

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

SQL

The sql module allows you to run SQL queries directly from the command line using the kysely instance.

Single-query:

1kysely sql "select 1"

or interactive mode:

1kysely sql -f json
2
3✔ sqlite ❯
4select 1;
5{                                                                                     
6  "rows": [
7    {
8      "1": 1
9    }
10  ]
11}
12
13❯ sqlite ❯
14exit

Environment-specific configuration

See c12 docs and the following example

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.