kysely-codegen generates Kysely type definitions from your database. That's it.

Table of contents

• Installation
• Generating type definitions
• Using the type definitions
• CLI arguments
• Configuration file
• Issue funding

Installation

1npm install --save-dev kysely-codegen

You will also need to install Kysely with your driver of choice:

1# PostgreSQL
2npm install kysely pg
3
4# MySQL
5npm install kysely mysql2
6
7# SQLite
8npm install kysely better-sqlite3
9
10# MSSQL
11npm install kysely tedious tarn @tediousjs/connection-string
12
13# LibSQL
14npm install @libsql/kysely-libsql

Generating type definitions

The most convenient way to get started is to create an .env file with your database connection string:

1# PostgreSQL
2DATABASE_URL=postgres://username:password@yourdomain.com/database
3
4# MySQL
5DATABASE_URL=mysql://username:password@yourdomain.com/database
6
7# SQLite
8DATABASE_URL=C:/Program Files/sqlite3/db
9
10# MSSQL
11DATABASE_URL=Server=mssql;Database=database;User Id=user;Password=password
12
13# LibSQL
14DATABASE_URL=libsql://token@host:port/database

If your URL contains a password with special characters, those characters may need to be percent-encoded.

If you are using PlanetScale, make sure your URL contains this SSL query string parameter: ssl={"rejectUnauthorized":true}

Then run the following command, or add it to the scripts section in your package.json file:

1kysely-codegen

This command will generate a .d.ts file from your database, for example:

1import { ColumnType } from 'kysely';
2
3export type Generated<T> = T extends ColumnType<infer S, infer I, infer U>
4  ? ColumnType<S, I | undefined, U>
5  : ColumnType<T, T | undefined, T>;
6
7export type Timestamp = ColumnType<Date, Date | string, Date | string>;
8
9export interface Company {
10  id: Generated<number>;
11  name: string;
12}
13
14export interface User {
15  company_id: number | null;
16  created_at: Generated<Timestamp>;
17  email: string;
18  id: Generated<number>;
19  is_active: boolean;
20  name: string;
21  updated_at: Timestamp;
22}
23
24export interface DB {
25  company: Company;
26  user: User;
27}

To specify a different output file:

1kysely-codegen --out-file ./src/db/db.d.ts

Using the type definitions

Import DB into new Kysely<DB>, and you're done!

1import { Kysely, PostgresDialect } from 'kysely';
2import { DB } from 'kysely-codegen';
3import { Pool } from 'pg';
4
5const db = new Kysely<DB>({
6  dialect: new PostgresDialect({
7    pool: new Pool({
8      connectionString: process.env.DATABASE_URL,
9    }),
10  }),
11});
12
13const rows = await db.selectFrom('users').selectAll().execute();
14//    ^ { created_at: Date; email: string; id: number; ... }[]

If you need to use the generated types in e.g. function parameters and type definitions, you may need to use the Kysely Insertable, Selectable, Updateable types. Note that you don't need to explicitly annotate query return values, as it's recommended to let Kysely infer the types for you.

1import { Insertable, Updateable } from 'kysely';
2import { DB } from 'kysely-codegen';
3import { db } from './db';
4
5async function insertUser(user: Insertable<User>) {
6  return await db
7    .insertInto('users')
8    .values(user)
9    .returningAll()
10    .executeTakeFirstOrThrow();
11  // ^ Selectable<User>
12}
13
14async function updateUser(id: number, user: Updateable<User>) {
15  return await db
16    .updateTable('users')
17    .set(user)
18    .where('id', '=', id)
19    .returning(['email', 'id'])
20    .executeTakeFirstOrThrow();
21  // ^ { email: string; id: number; }
22}

Read the Kysely documentation for more information.

CLI arguments

--camel-case

Use the Kysely CamelCasePlugin for generated table column names.

Example:

1export interface User {
2  companyId: number | null;
3  createdAt: Generated<Timestamp>;
4  email: string;
5  id: Generated<number>;
6  isActive: boolean;
7  name: string;
8  updatedAt: Timestamp;
9}

--date-parser

Specify which parser to use for PostgreSQL date values. (values: string/timestamp, default: timestamp)

--default-schema [value]

Set the default schema(s) for the database connection.

Multiple schemas can be specified:

1kysely-codegen --default-schema=public --default-schema=hidden

--dialect [value]

Set the SQL dialect. (values: postgres/mysql/sqlite/mssql/libsql/bun-sqlite/kysely-bun-sqlite/worker-bun-sqlite)

--env-file [value]

Specify the path to an environment file to use.

--help, -h

Print all command line options.

--include-pattern [value], --exclude-pattern [value]

You can choose which tables should be included during code generation by providing a glob pattern to the --include-pattern and --exclude-pattern flags. We use micromatch under the hood, which provides advanced glob support. For instance, if you only want to include your public tables:

1kysely-codegen --include-pattern="public.*"

You can also include only certain tables within a schema:

1kysely-codegen --include-pattern="public.+(user|post)"

Or exclude an entire class of tables:

1kysely-codegen --exclude-pattern="documents.*"

--log-level [value]

Set the terminal log level. (values: debug/info/warn/error/silent, default: warn)

--no-domains

Skip generating types for PostgreSQL domains. (default: false)

--numeric-parser

Specify which parser to use for PostgreSQL numeric values. (values: string/number/number-or-string, default: string)

--overrides

Specify type overrides for specific table columns in JSON format.

Example:

1kysely-codegen --overrides='{"columns":{"table_name.column_name":"{foo:\"bar\"}"}}'

--out-file [value]

Set the file build path. (default: ./node_modules/kysely-codegen/dist/db.d.ts)

--partitions

Include partitions of PostgreSQL tables in the generated code.

--print

Print the generated output to the terminal instead of a file.

--runtime-enums

The PostgreSQL --runtime-enums option generates runtime enums instead of string unions. You can optionally specify which naming convention to use for runtime enum keys. (values: [pascal-case, screaming-snake-case], default: screaming-snake-case)

Examples:

--runtime-enums=false

1export type Status = 'CONFIRMED' | 'UNCONFIRMED';

--runtime-enums or --runtime-enums=screaming-snake-case

1export enum Status {
2  CONFIRMED = 'CONFIRMED',
3  UNCONFIRMED = 'UNCONFIRMED',
4}

--runtime-enums=pascal-case

1export enum Status {
2  Confirmed = 'CONFIRMED',
3  Unconfirmed = 'UNCONFIRMED',
4}

--singularize

Singularize generated type aliases, e.g. as BlogPost instead of BlogPosts. The codegen uses the pluralize package for singularization.

You can specify custom singularization rules in the configuration file.

--type-only-imports

Generate code using the TypeScript 3.8+ import type syntax. (default: true)

--url [value]

Set the database connection string URL. This may point to an environment variable. (default: env(DATABASE_URL))

--verify

Verify that the generated types are up-to-date. (default: false)

Configuration file

All codegen options can also be configured in a .kysely-codegenrc.json (or .js, .ts, .yaml etc.) file or the kysely-codegen property in package.json. See Cosmiconfig for all available configuration file formats.

The default configuration:

1{
2  "camelCase": false,
3  "dateParser": "timestamp",
4  "defaultSchemas": [], // ["public"] for PostgreSQL.
5  "dialect": null,
6  "domains": true,
7  "envFile": null,
8  "excludePattern": null,
9  "includePattern": null,
10  "logLevel": "warn",
11  "numericParser": "string",
12  "outFile": "./node_modules/kysely-codegen/dist/db.d.ts",
13  "overrides": {},
14  "partitions": false,
15  "print": false,
16  "runtimeEnums": false,
17  "singularize": false,
18  "typeOnlyImports": true,
19  "url": "env(DATABASE_URL)",
20  "verify": false
21}

The configuration object adds support for more advanced options:

1{
2  "camelCase": true,
3  "overrides": {
4    "columns": {
5      "users.settings": "{ theme: 'dark' }"
6    }
7  },
8  "singularize": {
9    "/^(.*?)s?$/": "$1_model",
10    "/(bacch)(?:us|i)$/i": "$1us"
11  }
12}

The generated output:

1export interface UserModel {
2  settings: { theme: 'dark' };
3}
4
5// ...
6
7export interface DB {
8  bacchi: Bacchus;
9  users: UserModel;
10}

Issue funding

We use Polar.sh to upvote and promote specific features that you would like to see implemented. Check the backlog and help out: