From f90685752bc3d440e94eac1c226b07e795fcda4a Mon Sep 17 00:00:00 2001 From: Tom Meagher Date: Wed, 25 Oct 2023 19:01:29 -0400 Subject: [PATCH] chore: readme --- README.md | 116 +++++++++++++++++++++++++++++++++++-------- src/cli.ts | 3 ++ src/utils/loadEnv.ts | 4 +- 3 files changed, 100 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 5543a57..5f2e230 100644 --- a/README.md +++ b/README.md @@ -6,37 +6,111 @@ ```bash npm i --save-dev kysely-migrate +pnpm add -D kysely-migrate +yarn add -D kysely-migrate +bun add -D kysely-migrate ``` ## Usage +Create a `kysely-migrate.config.ts` file and fill it out: + +```ts +// kysely-migrate.config.ts +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' }, +}) +``` + +Run commands to create and apply migrations, and generate types. + ```bash kysely-migrate [options] ``` -## Docs +## API -Run `kysely-migrate --help` (output below) or `kysely-migrate --help` to see the list of available commands and options. +### Commands -```bash -Usage: - $ kysely-migrate [options] - -Commands: - 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 - -For more info, run any command with the `--help` flag: - $ kysely-migrate create --help - -Options: - -h, --help Display this message - -v, --version Display version number +Run `kysely-migrate --help` (output below) or `kysely-migrate --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 + +### defineConfig + +Creates [`Config`](#config) object. + +| Name | Type | Description | +| ------- | ---------------------------------------- | --------------------------------------------------------------------- | +| `config` | `Config | (() => Config \| Promise)` | Configuration object or a function that returns a configuration object. | +| returns | `Config` | Configuration object. | + +### loadEnv + +Loads environment variables from `.env` or `.env.*` files. + +| 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` | Parsed environment variables. | + +### Config + +`Config` object. + +```ts +{ + /** Kysely instance used to manipulate migrations and introspect database */ + db: Kysely + /** 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 +} +``` + +### 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: + +```ts +import { + mysqlDefinitions, + postgresDefinitions, + sqliteDefinitions, +} from 'kysely-migrate' ``` ## Sponsors diff --git a/src/cli.ts b/src/cli.ts index 6cc3de0..4b8fa27 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -33,6 +33,7 @@ cli .option('-R, --reset', '[boolean] reset all migrations') .option('-r, --root ', '[string] root path to resolve config from') .example((name) => `${name} down`) + .example((name) => `${name} down --reset`) .action(async (options: DownOptions) => await down(options)) cli @@ -55,6 +56,7 @@ cli .option('-n, --name ', '[string] migration name') .option('-r, --root ', '[string] root path to resolve config from') .example((name) => `${name} to`) + .example((name) => `${name} to --name 0001_every_mangos_carry`) .action(async (options: ToOptions) => await to(options)) cli @@ -63,6 +65,7 @@ cli .option('-l, --latest', '[boolean] apply all pending migrations') .option('-r, --root ', '[string] root path to resolve config from') .example((name) => `${name} up`) + .example((name) => `${name} up --latest`) .action(async (options: UpOptions) => await up(options)) cli.help() diff --git a/src/utils/loadEnv.ts b/src/utils/loadEnv.ts index 2cd8e0a..9a6e278 100644 --- a/src/utils/loadEnv.ts +++ b/src/utils/loadEnv.ts @@ -6,8 +6,8 @@ import { expand } from 'dotenv-expand' // https://github.com/vitejs/vite/blob/main/packages/vite/src/node/env.ts#L7 export function loadEnv( config: { - mode?: string - envDir?: string + mode?: string | undefined + envDir?: string | undefined } = {}, ): Record { const mode = config.mode