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.
