Add to an existing project

Install chkit alongside your existing application code, drop a minimal config and starter schema into the current directory, and produce your first migration. Use this path when you already have a TypeScript project that talks to ClickHouse.

Prerequisites

Node.js 20+ or Bun 1.3.5+
A ClickHouse endpoint (CLICKHOUSE_URL, optionally CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, CLICKHOUSE_DB)

1. Install chkit

Add chkit and @chkit/core as dev dependencies:

$ bun add -d chkit @chkit/core

$ npm install -D chkit @chkit/core

$ pnpm add -D chkit @chkit/core

$ yarn add -D chkit @chkit/core

2. Initialize the config

chkit init writes clickhouse.config.ts (config with sensible defaults) and src/db/schema/example.ts (a starter MergeTree table). It’s idempotent — running it on an existing project leaves both files untouched.

$ bunx chkit init

$ npx chkit init

$ pnpm dlx chkit init

$ yarn dlx chkit init

Edit src/db/schema/example.ts to match the table you actually want before moving on.

3. Generate the initial migration

chkit generate diffs your schema definitions against the previous snapshot and writes migration SQL into chkit/migrations/. Pass --name to label the migration file.

$ bunx chkit generate --name init

$ npx chkit generate --name init

$ pnpm dlx chkit generate --name init

$ yarn dlx chkit generate --name init

4. Apply the migration

chkit migrate --apply runs unapplied migrations against the ClickHouse endpoint from your environment. Make sure CLICKHOUSE_URL (and any auth env vars) are set before running this.

$ bunx chkit migrate --apply

$ npx chkit migrate --apply

$ pnpm dlx chkit migrate --apply

$ yarn dlx chkit migrate --apply

5. Verify

chkit status shows which migrations have been applied. chkit check confirms the live schema matches your TypeScript definitions.

$ bunx chkit status

$ npx chkit status

$ pnpm dlx chkit status

$ yarn dlx chkit status

$ bunx chkit check

$ npx chkit check

$ pnpm dlx chkit check

$ yarn dlx chkit check

AI agent skill

chkit ships an agent skill so AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, and others) understand chkit commands, schema DSL, and workflows.

On the first interactive run, chkit detects your agent and prompts to install the skill. To install it manually at any time:

$ bunx skills add obsessiondb/chkit

$ npx skills add obsessiondb/chkit

$ pnpm dlx skills add obsessiondb/chkit

$ yarn dlx skills add obsessiondb/chkit

The skill is installed into your project’s agent directory (e.g. .claude/skills/chkit/, .cursor/skills/chkit/).

Where to next

CLI reference — every command and flag
Configuration — wire up clickhouse.config.ts
Schema DSL — define tables, views, and materialized views
Start with an example — the other path