Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

kysely-ctl

kysely-org239.5kMIT0.15.1TypeScript support: included

Command-line tool for Kysely

cli, ctl, kysely, migration, seeding, codegen

readme

kysely in the terminal

NPM Version Tests License Issues Pull Requests GitHub contributors Downloads

Join the discussion ⠀⠀⠀⠀⠀⠀⠀

Discord Bluesky

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 in your project/s.

System-wide installation:

<summary>When installed globally, kysely-ctl will be available as kysely in your terminal, anywhere.</summary>

Node.js:

npm i -g kysely-ctl

or:

pnpm add -g kysely-ctl

Bun

bun add -g kysely-ctl

Deno

deno install -g -f npm:kysely-ctl@latest

Project-scoped installation:

<summary>Alternatively, you can install kysely-ctl in your project as a dev dependency, which will make it available as kysely in your project's package.json:</summary>

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

deno add -D npm:kysely-ctl

Use

Configuration

<summary>Currently, a kysely.config.ts file is required, in the project root OR .config folder. Run kysely init in your terminal to create one.</summary> 
import { defineConfig } from "kysely-ctl";

export default defineConfig({
  destroyOnExit, // optional. dictates whether the (resolved) `kysely` instance should be destroyed when a command is finished executing. default is `true`.
  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 factory of shape `(db: Kysely<any>) => Migrator | Promise<Migrator>`. 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 factory of shape `(db: Kysely<any>) => Seeder | Promise<Seeder>`. 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({
  destroyOnExit, // optional. dictates whether the `kysely` instance should be destroyed when a command is finished executing. default is `true`.
  // ...
  kysely,
  // ...
});

To use Knex's timestamp prefixes:

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

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

Environment-specific configuration

See c12 docs and the following example

Commands

For more information run kysely -h in your terminal.

Migrate

<summary>The migrate module mirrors Knex.js CLI's module of the same name.</summary> 
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

<summary>The seed module mirrors Knex.js CLI's module of the same name.</summary> 
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.

SQL

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

Single-query:

kysely sql "select 1"

or interactive mode:

kysely sql -f json

✔ sqlite ❯
select 1;
{
  "rows": [
    {
      "1": 1
    }
  ]
}

❯ sqlite ❯
exit

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.