awkweb/kysely-migrate

Kysely migrations and codegen CLI

kysely-migrate

Kysely migrations and codegen CLI

Installation

bun add -D kysely-migrate

Usage

Create a kysely-migrate.config.ts file and fill it out.

import { Kysely, MysqlDialect } from 'kysely'
import { defineConfig } from 'kysely-migrate'
import { createPool } from 'mysql2'

export default defineConfig({
  db: new Kysely({
    dialect: new MysqlDialect({ pool: createPool('mysql://') }),
  }),
  migrationFolder: 'src/db/migrations',
  codegen: { dialect: 'mysql', out: 'src/db/types.ts' },
})

Add a "migrate" script to your package.json file.

{
  "scripts": {
    "migrate": "bun -b kysely-migrate"
  }
}

Run commands to manage migrations and generate types.

bun migrate <command> [options]

Commands

Run kysely-migrate --help or kysely-migrate <command> --help to see the list of available commands, options, and examples.

codegen  generate types from database metadata
create   create new migration
down     migrate one step down
init     create configuration file
list     list migrations
to       migrate to selected migration
up       migrate one step up

API

defineConfig

Creates Config object.

import { defineConfig } from 'kysely-migrate'

Name	Type	Description
config	Config | (() => Config | Promise<Config>)	Configuration object or a function that returns a configuration object.
returns	Config	Configuration object.

loadEnv

Loads environment variables from .env or .env.* files.

import { loadEnv } from 'kysely-migrate'

Name	Type	Description
config.mode	string | undefined	.env file type (e.g. `.env.${mode}`)
config.envDir	string | undefined	Directory to load .env file from
returns	Record<string, string>	Parsed environment variables.

Config

Config object.

import { type Config } from 'kysely-migrate'

{
  /** Kysely instance used to manipulate migrations and introspect database */
  db: Kysely<any>
  /** Path to migrations directory */
  migrationFolder: string

  /** `kysely-migrate codegen` options */
  codegen?:
    | {
        /** Custom definition mappings for database types to TypeScript types */
        definitions?: Definitions | undefined
        /** Dialect definitions to inherit */
        dialect?: 'mysql' | 'postgres' | 'sqlite' | undefined
        /** Output file path */
        out: string
      }
    | undefined
  
  /** Used for internal `FileMigrationProvider` instance. Defaults to `node:fs/promises`. */
  fs?: FileMigrationProviderFS | undefined
  /** Used for internal `FileMigrationProvider` instance. Defaults to `node:path`. */
  path?: FileMigrationProviderPath | undefined
  /** Defaults to internal `migrator` created with `db` and `migrationFolder`. */
  migrator?: Migrator | undefined
}

Dialect Definitions

Dialect definition files map database types to TypeScript types. They are used by the codegen command to generate types from database metadata. The following dialect definitions are available:

import {
  mysqlDefinitions,
  postgresDefinitions,
  sqliteDefinitions,
} from 'kysely-migrate'

Frequently Asked Questions

Unknown file extension ".ts"

If you aren't using Bun, you either need to use the .js extension for your migration files or process the TypeScript files yourself. For example, you can use tsx.

{
  "scripts": {
    "migrate": "tsx node_modules/kysely-migrate/dist/esm/cli.js"
  }
}

Contributing

Contributions to kysely-migrate are greatly appreciated! If you're interested in contributing, please create a new GitHub Discussion with some info on what you would like to work on before submitting a pull request.

kysely-migrate's Issues

Cannot generate config

Describe the bug

When trying to run a kysely-migrate init I get error message "Config not found". This is a bit weird considering that the command should generate a config file.

It seems to me that the error might lie in findConfig.ts as this function throws such error.

Link to Minimal Reproducible Example

No response

Steps To Reproduce

1. Run kysely-migrate init

Package Version

0.0.16

TypeScript Version

5.1.3

Anything else?

No response

Validations

• Checked there isn't already an issue that exists for the bug you encountered.
• Added a minimal reproduction.

codegen replaces underscores by spaces

Describe the bug

Hello, thank you for this utility, it makes dealing with kysely migrations much more convenient.
I tried the codegen function, and while it worked quite good, the generated names get underscore replaced by spaces, which is incorrect.

To give you an example user_session generates a type named User Session which is obviously not valid typescript.

Link to Minimal Reproducible Example

I don't think is needed, sorry

Steps To Reproduce

Just use any underscore in any table name then try to run a codegen command

Package Version

kysely-migrate 0.0.16

TypeScript Version

5.3.3

Anything else?

No response

Validations

• Checked there isn't already an issue that exists for the bug you encountered.
• Added a minimal reproduction.