Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/acro5piano/kysely-migration-cli
A thin library to create a migration script using Kysely
https://github.com/acro5piano/kysely-migration-cli
database kysely migration typescript
Last synced: 8 days ago
JSON representation
A thin library to create a migration script using Kysely
- Host: GitHub
- URL: https://github.com/acro5piano/kysely-migration-cli
- Owner: acro5piano
- License: mit
- Created: 2022-04-11T02:41:02.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-10T14:50:41.000Z (2 months ago)
- Last Synced: 2024-10-12T06:43:26.022Z (29 days ago)
- Topics: database, kysely, migration, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/kysely-migration-cli
- Size: 65.4 KB
- Stars: 66
- Watchers: 4
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-kysely - kysely-migration-cli - Thin migration cli library for [Kysely](https://kysely.dev).    (CLIs)
README
# kysely-migration-cli
A lightweight migration CLI **library** for [Kysely](https://github.com/koskimas/kysely)
# Installation
Install using the dependency manager of your choice
```typescript
// NPM
npm install --save kysely-migration-cli
// PNPM
pnpm add kysely-migration-cli
// YARN
yarn add kysely-migration-cli
```
# Usage
`kysely-migration-cli` is a **library** designed to assist you in creating your own migration script. It does not aim to provide an executable command.
Create a migration script as shown below:
```typescript
// scripts/migrate.ts
import * as path from 'path'
import { promises as fs } from 'fs'
import pg from 'pg'
import { Kysely, Migrator, PostgresDialect, FileMigrationProvider } from 'kysely'
import { run } from 'kysely-migration-cli'
// For ESM environment
const migrationFolder = new URL('../migrations', import.meta.url).pathname
// For CJS environment
// const migrationFolder = path.join(__dirname, '../migrations')
const db = new Kysely({
dialect: new PostgresDialect({
pool: new pg.Pool({
connectionString: process.env.DATABASE_URL,
}),
}),
})
const migrator = new Migrator({
db,
provider: new FileMigrationProvider({
fs,
path,
migrationFolder,
}),
})
run(db, migrator, migrationFolder)
```
Note: The above script assumes your migration folder is located at the same directory of chdir and named `./migrations`
Then run:
```bash
# Choose your preferred tool. Here are some examples:
#
# $ node -r esbuild-register scripts/migrate.ts -h
# $ node -r ts-node/register scripts/migrate.ts -h
# $ node -r babel-node/register scripts/migrate.ts -h
# $ ts-node-transpile-only scripts/migrate.ts -h
# $ npm run tsc && node scripts/migrate.js -h
# $ bun run scripts/migrate.ts -h
$ node -r esbuild-register scripts/migrate.ts -h
```
Output:
```
Usage: kysely-migration-cli [options] [command]
Options:
-h, --help display help for command
Commands:
up Run a pending migration if any
down Revert the latest migration with a down file
redo Down and Up
latest Run all pending migrations
down-to Migrates down to the specified migration name. Specify
"NO_MIGRATIONS" to migrate all the way down.
create Create a new migration with the given description, and
the current time as the version
help [command] display help for command
```
# Migration creation
The `create` command generates a migration boilorplate with the current timestamp. For example, running `node -r ts-node/register scripts/migrate.ts create initial` creates a file named `migrations/20220222T044655-initial.ts` with the following code:
```ts
import { type Kysely } from 'kysely'
export async function up(db: Kysely): Promise {
}
export async function down(db: Kysely): Promise {
}
```
If you want to modify the default template, you can pass an option `--template=yourtemplate.txt` pointing to a file containing the custom template
If you want to change the path where migration files are stored, please modify the CLI code as follows:
```typescript
// scripts/migrate.ts
// ...
run(db, migrator, 'dir/to/migration/files')
```
# Experimental: CLI without a script file
Important Notes:
- This is an experimental feature, and the behavior may change in the future.
- Currently, it only works with Postgres.
You can run `kysely-migration-cli` without a script file.
```
env DATABASE_URL=postgres://postgres:[email protected]:5432/postgres \
npm run kysely-migration-cli
```
If you place an `.env` file containing `DATABASE_URL=postgres://...`, the CLI will automatically load it before execution. To enable this, you need to install the dotenv module (`npm install dotenv`) .
To transpile TypeScript, `kysely-migration-cli` attempts to register a transpiler using Node's hook api. It currently supports the following transpilers:
- `esbuild-register`
- `ts-node/register/transpile-only`
- `@swc-node/register`
> Of course, they are not required for platforms which supports TypeScript natively, such as `Deno` and `Bun`.
If you require additional registration supports, please submit a pull request.
# Related Packages
Kysely has now the official CLI called `kysely-ctl`. It's actively maintianed and covers broader features, while `kysely-migration-cli` has less dependencies.
https://github.com/kysely-org/kysely-ctl
# License
Copyright © 2022 [Kay Gosho](https://github.com/acro5piano) (@acro5piano).
This project is licensed under the MIT License - see the LICENSE file for details.