Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/RobinBlomberg/kysely-codegen

Generate Kysely type definitions from your database.
https://github.com/RobinBlomberg/kysely-codegen

Last synced: 27 days ago
JSON representation

Generate Kysely type definitions from your database.

Awesome Lists containing this project

README 

        
# ![kysely-codegen](./assets/kysely-codegen-logo.svg) 



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



## Table of contents 



- [Installation](#installation)

- [Generating type definitions](#generating-type-definitions)

- [Using the type definitions](#using-the-type-definitions)

- [CLI arguments](#cli-arguments)

- [Configuration file](#configuration-file)

- [Issue funding](#issue-funding)



## Installation



```sh

npm install --save-dev kysely-codegen

```



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



```sh

# 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



# LibSQL

npm 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:



```sh

# PostgreSQL

DATABASE_URL=postgres://username:[email protected]/database



# MySQL

DATABASE_URL=mysql://username:[email protected]/database



# SQLite

DATABASE_URL=C:/Program Files/sqlite3/db



# MSSQL

DATABASE_URL=Server=mssql;Database=database;User Id=user;Password=password



# LibSQL

DATABASE_URL=libsql://token@host:port/database

```



> If your URL contains a password with special characters, those characters may need to be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding#Reserved_characters).

>

> 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:



```sh

kysely-codegen

```



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



```ts

import { ColumnType } from 'kysely';



export type Generated = T extends ColumnType

  ? ColumnType

  : ColumnType;



export type Timestamp = ColumnType;



export interface Company {

  id: Generated;

  name: string;

}



export interface User {

  company_id: number | null;

  created_at: Generated;

  email: string;

  id: Generated;

  is_active: boolean;

  name: string;

  updated_at: Timestamp;

}



export interface DB {

  company: Company;

  user: User;

}

```



To specify a different output file:



```sh

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

```



## Using the type definitions



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



```ts

import { Kysely, PostgresDialect } from 'kysely';

import { DB } from 'kysely-codegen';

import { Pool } from 'pg';



const db = new Kysely({

  dialect: new PostgresDialect({

    pool: new Pool({

      connectionString: process.env.DATABASE_URL,

    }),

  }),

});



const rows = await db.selectFrom('users').selectAll().execute();

//    ^ { 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.



```ts

import { Insertable, Updateable } from 'kysely';

import { DB } from 'kysely-codegen';

import { db } from './db';



async function insertUser(user: Insertable) {

  return await db

    .insertInto('users')

    .values(user)

    .returningAll()

    .executeTakeFirstOrThrow();

  // ^ Selectable

}



async function updateUser(id: number, user: Updateable) {

  return await db

    .updateTable('users')

    .set(user)

    .where('id', '=', id)

    .returning(['email', 'id'])

    .executeTakeFirstOrThrow();

  // ^ { email: string; id: number; }

}

```



Read the [Kysely documentation](https://kysely.dev/docs/getting-started) for more information.



## CLI arguments



#### --camel-case 



Use the Kysely CamelCasePlugin for generated table column names.



**Example:**



```ts

export interface User {

  companyId: number | null;

  createdAt: Generated;

  email: string;

  id: Generated;

  isActive: boolean;

  name: string;

  updatedAt: Timestamp;

}

```



#### --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:



```sh

kysely-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](https://github.com/micromatch/micromatch) under the hood, which provides advanced glob support. For instance, if you only want to include your public tables:



```sh

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

```



You can also include only certain tables within a schema:



```sh

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

```



Or exclude an entire class of tables:



```sh

kysely-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:**



```sh

kysely-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`



```ts

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

```



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



```ts

export enum Status {

  CONFIRMED = 'CONFIRMED',

  UNCONFIRMED = 'UNCONFIRMED',

}

```



`--runtime-enums=pascal-case`



```ts

export enum Status {

  Confirmed = 'CONFIRMED',

  Unconfirmed = 'UNCONFIRMED',

}

```



#### --singularize 



Singularize generated type aliases, e.g. as `BlogPost` instead of `BlogPosts`. The codegen uses the [pluralize](https://www.npmjs.com/package/pluralize) package for singularization.



You can specify custom singularization rules in the [configuration file](#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](https://github.com/cosmiconfig/cosmiconfig) for all available configuration file formats.



The default configuration:



```json

{

  "camelCase": false,

  "dateParser": "timestamp",

  "defaultSchemas": [], // ["public"] for PostgreSQL.

  "dialect": null,

  "domains": true,

  "envFile": null,

  "excludePattern": null,

  "includePattern": null,

  "logLevel": "warn",

  "numericParser": "string",

  "outFile": "./node_modules/kysely-codegen/dist/db.d.ts",

  "overrides": {},

  "partitions": false,

  "print": false,

  "runtimeEnums": false,

  "singularize": false,

  "typeOnlyImports": true,

  "url": "env(DATABASE_URL)",

  "verify": false

}

```



The configuration object adds support for more advanced options:



```json

{

  "camelCase": true,

  "overrides": {

    "columns": {

      "users.settings": "{ theme: 'dark' }"

    }

  },

  "singularize": {

    "/^(.*?)s?$/": "$1_model",

    "/(bacch)(?:us|i)$/i": "$1us"

  }

}

```



The generated output:



```ts

export interface UserModel {

  settings: { theme: 'dark' };

}



// ...



export interface DB {

  bacchi: Bacchus;

  users: UserModel;

}

```



## Issue funding



We use [Polar.sh](https://polar.sh/RobinBlomberg) to upvote and promote specific features that you would like to see implemented. Check the backlog and help out: