Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

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

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

Last synced: about 2 months 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)

- [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(user: Updateable) {

  return await db

    .updateTable('users')

    .set(user)

    .where({ id: user.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`)



#### --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, --runtime-enums-style 



The PostgreSQL `--runtime-enums` option generates runtime enums instead of string unions.



The option `--runtime-enums-style` specifies which naming convention to use for runtime enum keys. (values: [`pascal-case`, `screaming-snake-case`], default: `pascal-case`)



**Examples:**



`--runtime-enums=false`



```ts

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

```



`--runtime-enums`



```ts

export enum Status {

  CONFIRMED = 'CONFIRMED',

  UNCONFIRMED = 'UNCONFIRMED',

}

```



`--runtime-enums --runtime-enums-style=pascal-case`



```ts

export enum Status {

  Confirmed = 'CONFIRMED',

  Unconfirmed = 'UNCONFIRMED',

}

```



#### --schema [value] 



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



Multiple schemas can be specified:



```sh

kysely-codegen --schema=public --schema=hidden

```



#### --singular 



Singularize generated table names, e.g. `BlogPost` instead of `BlogPosts`. We use the [pluralize](https://www.npmjs.com/package/pluralize) package for singularization.



#### --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`)



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