{"id":16420,"library":"kysely-mig","title":"Kysely Migration CLI","description":"Kysely-Mig is a TypeScript-first command-line interface (CLI) tool designed to manage database migrations and seeding for PostgreSQL databases, built on top of the Kysely query builder. The current stable version is 0.9.1, indicating it's still in active development, likely with frequent updates as features are added or refined. Key differentiators include atomic operations, automatic rollback on errors, transaction support, migration locking, multi-environment configuration, and selective/partial migration execution. It provides both a robust CLI for schema evolution and a programmatic API for integrating migration logic directly into applications, simplifying database management for Kysely users.","status":"active","version":"0.9.1","language":"javascript","source_language":"en","source_url":"https://github.com/drekuru/kysely-mig","tags":["javascript","migration","database","tables","pg","postgres","sql","seeds","schemas","typescript"],"install":[{"cmd":"npm install kysely-mig","lang":"bash","label":"npm"},{"cmd":"yarn add kysely-mig","lang":"bash","label":"yarn"},{"cmd":"pnpm add kysely-mig","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Migrator = require('kysely-mig');","symbol":"Migrator","correct":"import { Migrator } from 'kysely-mig';"},{"note":"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.","wrong":"import type { MigratorOptions } from 'kysely-mig';","symbol":"MigratorOptions","correct":"import { MigratorOptions } from 'kysely-mig';"},{"note":"Represents a migration file object, useful for programmatic listing or manipulation of migration states. Primarily a type, but exported as a value for consistency.","wrong":null,"symbol":"MigrationFile","correct":"import { MigrationFile } from 'kysely-mig';"}],"quickstart":{"code":"npm install -g kysely-mig\n\nmig setup\n\n# Generate a database configuration file\nmig env generate local-db\n\n# Open 'local-db.env' and fill in your PostgreSQL connection details\n# Example: DATABASE_URL=\"postgres://user:password@host:port/database\"\n\n# Add the configuration to kysely-mig's context and set it as default\nmig env add ./local-db.env -d\n\n# Verify the current environment is set\nmig env get\n\n# Generate a new migration file for 'users' table\nmig make users\n\n# Edit the generated migration file (e.g., migrations/timestamp_users.ts)\n// Example content for migrations/timestamp_users.ts:\n// import { Kysely, sql } from 'kysely';\n//\n// export async function up(db: Kysely<any>): Promise<void> {\n//   await db.schema\n//     .createTable('users')\n//     .addColumn('id', 'uuid', (col) => col.primaryKey().defaultTo(sql`gen_random_uuid()`))\n//     .addColumn('email', 'varchar(255)', (col) => col.unique().notNull())\n//     .addColumn('username', 'varchar(255)', (col) => col.unique().notNull())\n//     .addColumn('created_at', 'timestamp', (col) => col.defaultTo(sql`now()`).notNull())\n//     .execute();\n// }\n//\n// export async function down(db: Kysely<any>): Promise<void> {\n//   await db.schema.dropTable('users').execute();\n// }\n\n# Run all pending migrations\nmig up","lang":"typescript","description":"Demonstrates the initial setup, environment configuration, migration generation, and execution using the `kysely-mig` CLI."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"mig: command not found"},{"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.","cause":"The migrator cannot find the `.env` configuration file for the currently selected environment, or no environment has been set as active.","error":"Error: No database connection details found for current environment."},{"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.","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.","error":"Error: ENOENT: no such file or directory, open '.../.kysely-mig/envs/my-env.env'"}],"ecosystem":"npm"}