https://github.com/kysely-org/kysely-ctl
Command-line tool for Kysely
https://github.com/kysely-org/kysely-ctl
automation cli ctl knex kysely migrations mssql mysql postgres seeds sql sqlite
Last synced: about 2 months ago
JSON representation
Command-line tool for Kysely
- Host: GitHub
- URL: https://github.com/kysely-org/kysely-ctl
- Owner: kysely-org
- License: mit
- Created: 2024-04-25T22:43:22.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-19T22:23:28.000Z (about 1 year ago)
- Last Synced: 2025-05-07T15:51:46.508Z (about 1 year ago)
- Topics: automation, cli, ctl, knex, kysely, migrations, mssql, mysql, postgres, seeds, sql, sqlite
- Language: TypeScript
- Homepage:
- Size: 684 KB
- Stars: 175
- Watchers: 1
- Forks: 10
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-opensource-israel - kysely-ctl - Command-line tool for Kysely.    (Projects by main language / typescript)
- awesome - kysely-org/kysely-ctl - Command-line tool for Kysely, Knex-compatible, works in Node.js, Deno, Bun, etc. (<a name="TypeScript"></a>TypeScript)
README
[](https://github.com/kysely-org/kysely-ctl/releases/latest)
[](https://github.com/kysely-org/kysely-ctl)
[](https://github.com/kysely-org/kysely-ctl/blob/master/LICENSE)
[](https://github.com/kysely-org/kysely-ctl/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)
[](https://github.com/kysely-org/kysely-ctl/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc)
[](https://www.npmjs.com/package/kysely-ctl)
###### Join the discussion ⠀⠀⠀⠀⠀⠀⠀
[](https://discord.gg/xyBJ3GwvAm)
[](https://bsky.app/profile/kysely.dev)
`kysely-ctl` is the official command-line tool for [Kysely](https://kysely.dev).
We strive to make it [TypeScript](https://www.typescriptlang.org/)-first, cross-platform
([macOS](https://www.apple.com/macos), [Linux](https://www.linux.org/), and [Windows](https://www.microsoft.com/en-us/windows)),
cross-runtime ([Node.js](https://nodejs.org/), [Bun](https://bun.sh/), and [Deno](https://deno.com/)),
and cross-module system ([ESM](https://nodejs.org/api/esm.html#modules-ecmascript-modules)
and [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules)) compatible.
We also aim to have feature parity with [Knex.js](https://knexjs.org)'s CLI.
## Install
### Prerequisites:
`kysely-ctl` requires `kysely` >= 0.18.1 to be installed in your project/s.
### System-wide installation:
When installed globally, kysely-ctl will be available as kysely in your terminal,
anywhere.
#### Node.js:
```bash
npm i -g kysely-ctl
```
or:
```bash
pnpm add -g kysely-ctl
```
#### Bun
```bash
bun add -g kysely-ctl
```
#### Deno
```bash
deno install -g -f npm:kysely-ctl@latest
```
### Project-scoped installation:
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:
#### Node.js:
```bash
npm i -D kysely-ctl
```
or:
```bash
yarn add -D kysely-ctl
```
or:
```bash
pnpm add -D kysely-ctl
```
#### Bun
```bash
bun add -D kysely-ctl
```
#### Deno
```bash
deno 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.
```ts
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. path to where migration files are located. default is a folder named "migrations" next to the config file/folder.
migrator, // optional. a `Kysely` migrator instance factory of shape `(db: Kysely) => Migrator | Promise`. 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) => Seeder | Promise`. default is `kysely-ctl`'s `Seeder`.
seedFolder, // optional. path to where seed files are located. default is a folder named "seeds" next to the config file/folder.
}
});
```
#### Reuse Kysely instance defined elsewhere
You can pass a `Kysely` instance, instead of `dialect`, `dialectConfig` & `plugins`:
```ts
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,
// ...
});
```
#### Custom migration/seed file prefixes
To use Knex's timestamp prefixes:
```ts
import { defineConfig, getKnexTimestampPrefix } from "kysely-ctl";
export default defineConfig({
// ...
migrations: {
// ...
getMigrationPrefix: getKnexTimestampPrefix,
// ...
},
// ...
});
```
#### Extending configuration
See [c12 docs](https://github.com/unjs/c12#extending-configuration) and the following [example](https://github.com/kysely-org/kysely-ctl/blob/main/examples/node-esm-multi-config/.config/kysely.test.config.ts).
#### Environment-specific configuration
See [c12 docs](https://github.com/unjs/c12#environment-specific-configuration) and the following [example](https://github.com/kysely-org/kysely-ctl/blob/main/examples/node-esm-environments/.config/kysely.config.ts).
### Commands
For more information run `kysely -h` in your terminal.
#### Migrate
The migrate module mirrors Knex.js CLI's module of the
same name.
```bash
knex migrate:
```
Can now be called as either:
```bash
kysely migrate:
```
or
```bash
kysely migrate
```
> [!NOTE]
> `rollback` without `--all` flag is not supported, as [Kysely](https://kysely.dev)
doesn't keep track of "migration batches".
#### Seed
The seed module mirrors Knex.js CLI's module of the same
name.
```bash
knex seed:
```
Can now be called as either:
```bash
kysely seed:
```
or
```bash
kysely seed
```
> [!NOTE]
> We also provide `kysely seed list`, which is not part of [Knex.js](https://knexjs.org)
CLI.
#### SQL
The sql module allows you to run SQL queries directly from the command line using the kysely instance.
Single-query:
```bash
kysely sql "select 1"
```
or interactive mode:
```bash
kysely sql -f json
✔ sqlite ❯
select 1;
{
"rows": [
{
"1": 1
}
]
}
❯ sqlite ❯
exit
```
## Acknowledgements
[acro5piano](https://github.com/acro5piano) who built [kysely-migration-cli](https://github.com/acro5piano/kysely-migration-cli)
and inspired this project.
[UnJS](https://unjs.io)'s amazing tools that help power this project.
[Knex.js](https://knexjs.org) team for paving the way.