Kysely Migration CLI

Common errors

• mig: command not found

  cause The `kysely-mig` CLI executable is not in your system's PATH, typically due to a failed global installation or a PATH configuration issue.
  fix Run `npm install -g kysely-mig` again. If the problem persists, check your npm global installation directory (e.g., `npm root -g`) and ensure it's included in your system's PATH environment variable.

• Error: No database connection details found for current environment.

  cause The migrator cannot find the `.env` configuration file for the currently selected environment, or no environment has been set as active.
  fix Ensure you have generated an environment file (`mig env generate <filename>`), filled in the database details, added it to the migrator's context (`mig env add <filename>`), and explicitly set it as the current environment (`mig env set <filename>`). Verify the environment name matches exactly.

• Error: ENOENT: no such file or directory, open '.../.kysely-mig/envs/my-env.env'

  cause The specified environment file could not be found by the `kysely-mig` CLI within its configuration directory, often due to an incorrect path during `mig env add` or the file being moved/deleted after being added.
  fix Verify the environment file exists at the path you provided to `mig env add`, and that the filename matches what's expected. You may need to remove (`mig env rm <filename>`) and re-add the environment if its location or name changed, or if there were file permission issues.

Warnings

• gotcha The package is currently in version 0.9.1. As a pre-1.0 release, it may introduce breaking changes in minor versions without strict adherence to semantic versioning principles, requiring careful review during updates.
  Fix: Always review the changelog before upgrading to new minor versions (e.g., from 0.9.x to 0.10.x) to identify potential breaking changes or API alterations.
• gotcha Configuration files and internal state are managed in the user's home directory (`$USER_HOME`). This can lead to issues in CI/CD pipelines, containerized environments, or multi-user setups where `$USER_HOME` might not be consistently available or writable, or where isolation is required.
  Fix: For CI/CD or container environments, ensure `$USER_HOME` is appropriately set and has write permissions, or consider manually copying configuration files into the expected location within the container/environment using a custom volume or initialization script.
• gotcha Currently, kysely-mig is explicitly designed for PostgreSQL databases. Attempting to use it with other SQL dialects (e.g., MySQL, SQLite) will likely result in errors or unexpected behavior due to PostgreSQL-specific SQL generation and feature reliance.
  Fix: Ensure your project exclusively uses PostgreSQL. If you require other databases, consider alternative migration tools or monitor the kysely-mig roadmap for broader database support.
• gotcha Global installation (`npm install -g kysely-mig`) can lead to versioning conflicts if different projects on the same machine require distinct versions of the CLI tool. This can cause unexpected behavior or broken migrations.
  Fix: Consider installing `kysely-mig` as a `devDependency` in your project (`npm install --save-dev kysely-mig`) and running it via `npx kysely-mig` or through npm scripts (`"migrate": "kysely-mig up"`) to ensure project-specific versioning and avoid global conflicts.

Install

• npm install kysely-mig npm
• yarn add kysely-mig yarn
• pnpm add kysely-mig pnpm

Imports

• Migrator
  wrong:

  const Migrator = require('kysely-mig');

  correct:

  import { Migrator } from 'kysely-mig';

  The primary class for programmatic migration management. Use named import for ESM. CommonJS environments typically require `const { Migrator } = require('kysely-mig');` or an async import.
• MigratorOptions
  wrong:

  import type { MigratorOptions } from 'kysely-mig';

  correct:

  import { MigratorOptions } from 'kysely-mig';

  This is an interface for configuring the Migrator class. While `import type` is generally preferred for types, `import { MigratorOptions } from 'kysely-mig';` also works as it's exported as a value in some contexts. The latter is provided for broader compatibility.
• MigrationFile

  import { MigrationFile } from 'kysely-mig';

  Represents a migration file object, useful for programmatic listing or manipulation of migration states. Primarily a type, but exported as a value for consistency.

Quickstart

Demonstrates the initial setup, environment configuration, migration generation, and execution using the `kysely-mig` CLI.

npm install -g kysely-mig

mig setup

# Generate a database configuration file
mig env generate local-db

# Open 'local-db.env' and fill in your PostgreSQL connection details
# Example: DATABASE_URL="postgres://user:password@host:port/database"

# Add the configuration to kysely-mig's context and set it as default
mig env add ./local-db.env -d

# Verify the current environment is set
mig env get

# Generate a new migration file for 'users' table
mig make users

# Edit the generated migration file (e.g., migrations/timestamp_users.ts)
// Example content for migrations/timestamp_users.ts:
// import { Kysely, sql } from 'kysely';
//
// export async function up(db: Kysely<any>): Promise<void> {
//   await db.schema
//     .createTable('users')
//     .addColumn('id', 'uuid', (col) => col.primaryKey().defaultTo(sql`gen_random_uuid()`))
//     .addColumn('email', 'varchar(255)', (col) => col.unique().notNull())
//     .addColumn('username', 'varchar(255)', (col) => col.unique().notNull())
//     .addColumn('created_at', 'timestamp', (col) => col.defaultTo(sql`now()`).notNull())
//     .execute();
// }
//
// export async function down(db: Kysely<any>): Promise<void> {
//   await db.schema.dropTable('users').execute();
// }

# Run all pending migrations
mig up