kysely-codegen

The generator produces a TypeScript file containing interfaces for your tables (models) and a central DB interface. When using customImports, overrides, or typeMapping, the generated code will include the corresponding imports and type definitions.

import type { InstantRange } from './custom-types';
import type { MyCustomType } from '@my-org/custom-types';
import type { OriginalType as AliasedType } from './types';
import type { Temporal } from '@js-temporal/polyfill';

export interface EventModel {
  createdAt: Temporal.Instant;
  dateRange: ColumnType<InstantRange, InstantRange, never>;
  eventDate: Temporal.PlainDate;
}

export interface UserModel {
  settings: { theme: 'dark' };
}

// ...

export interface DB {
  bacchi: Bacchus;
  events: EventModel;
  users: UserModel;
}

The easiest way to generate types is to set a DATABASE_URL environment variable in an .env file and run the kysely-codegen command.

Supported Connection String Formats:

• PostgreSQL: postgres://username:password@yourdomain.com/database
• MySQL: mysql://username:password@yourdomain.com/database
• SQLite: C:/Program Files/sqlite3/db (path to file)
• MSSQL: Server=mssql;Database=database;User Id=user;Password=password
• LibSQL: libsql://token@host:port/database

Note: If using PlanetScale, include the SSL query string parameter: ssl={"rejectUnauthorized":true}.

To specify a custom output path for the generated .d.ts file, use the --out-file flag.

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

To use kysely-codegen, install it as a development dependency. You must also install kysely along with the driver specific to your database.

# Install the codegen
npm install --save-dev kysely-codegen

# Install Kysely and your driver
# PostgreSQL
npm install kysely pg

# MySQL
npm install kysely mysql2

# SQLite
npm install kysely better-sqlite3

# MSSQL
npm install kysely tedious tarn @tediousjs/connection-string@1.0.0

# LibSQL
npm install @libsql/kysely-libsql

Use --custom-imports to map database types to custom TypeScript types from external packages or local files. You can use the # syntax for named imports with aliasing.

Basic Example:

# Map 'InstantRange' to a local file
kysely-codegen --custom-imports='{"InstantRange":"./custom-types"}'

Named Imports with Aliasing:

# Import 'OriginalType' from './types' and alias it as 'MyType'
kysely-codegen --custom-imports='{"MyType":"./types#OriginalType"}'

After defining custom imports, you can use --overrides to apply specific ColumnType definitions to columns using the table_name.column_name syntax.

kysely-codegen --custom-imports='{"MyType":"./types#OriginalType","DateRange":"@org/utils#CustomDateRange"}'

You can configure the generator using command-line flags or by providing a configuration file via the --config-file flag. When both are used, CLI flags take precedence over configuration file settings.

Note on Deprecations:

• Use --default-schema instead of --schema.
• Use --singularize instead of --singular.

The project provides a docker-compose.yml file to quickly spin up local development environments for various database engines supported by kysely-codegen. You can use these services to host your schema before running the codegen tool.

Available services include:

• kysely_codegen_postgres: PostgreSQL
• kysely_codegen_mysql: MySQL
• kysely_codegen_libsql: LibSQL
• kysely_codegen_adminer: A web-based database management tool (Adminer) accessible on port 8081.

The --type-mapping flag allows you to automatically map all columns of a specific database type to a custom TypeScript type. This is more efficient than overriding individual columns.

Example: To map PostgreSQL timestamptz to a Temporal.Instant type:

# 1. Define the mapping
# 2. Provide the custom import for the target type
kysely-codegen --type-mapping='{"timestamptz":"Temporal.Instant"}' --custom-imports='{"Temporal":"@js-temporal/polyfill"}'

The kysely_codegen_mysql service uses the official mysql:latest image. You can configure the database using the following environment variables:

• MYSQL_DATABASE: The name of the database to create.
• MYSQL_USER: The username for the database.
• MYSQL_PASSWORD: The password for the user.
• MYSQL_ROOT_PASSWORD: The password for the root user.

By default, it maps the internal port 3306 to host port 3306.

services:
  kysely_codegen_mysql:
    image: mysql:latest
    environment:
      - MYSQL_DATABASE=database
      - MYSQL_PASSWORD=password
      - MYSQL_ROOT_PASSWORD=password
      - MYSQL_USER=user
    ports:
      - 3306:3306

The runtimeEnums option controls how database enums are generated in TypeScript. It accepts a boolean or a RuntimeEnumsStyle value.

• If set to true (or a style), the generator creates actual TypeScript enum declarations.
• If set to false (default), enums are generated as union types of literal strings.