ClickHouse schema and migration CLI for TypeScript projects.
Define your ClickHouse schema in TypeScript, generate migrations automatically, detect drift, and run CI checks -- all from a single CLI.
- Schema-as-code -- Define tables, views, and materialized views in TypeScript using a declarative DSL
- Automatic migration generation -- Diff your schema changes and generate timestamped SQL migrations with rename detection
- Safe migrations -- Destructive operations are flagged with risk levels and require explicit confirmation
- Drift detection -- Compare your local schema against a live ClickHouse instance to catch out-of-band changes
- CI gate -- Run
chkit checkto fail builds on pending migrations, checksum mismatches, or schema drift - TypeScript codegen -- Generate row types and optional Zod schemas from your schema definitions (
@chkit/plugin-codegen) - Schema pulling -- Introspect an existing ClickHouse database into local schema files (
@chkit/plugin-pull) - Data backfill -- Time-windowed, checkpointed backfill operations with retry logic (
@chkit/plugin-backfill) - JSON output -- Every command supports
--jsonfor scripting and automation
bun add -d chkit @chkit/core@chkit/core provides the table() / schema DSL your *.schema.ts files import, so it is required alongside the CLI.
# Scaffold a new project
bunx chkit init
# Generate a migration from schema changes
bunx chkit generate --name add-users-table
# Preview and apply pending migrations
bunx chkit migrate --apply
# Check migration status
bunx chkit status
# Detect schema drift
bunx chkit drift
# CI gate (fails on pending migrations or drift)
bunx chkit checkAll commands support --json for machine-readable output and --config <path> to specify a custom config file.
- Node 20+ or Bun — chkit loads your TypeScript config and schema files on both runtimes.
- ClickHouse 24.x or newer — chkit targets recent ClickHouse (self-hosted, ClickHouse Cloud, or ObsessionDB). Some schema features are version-gated; see ClickHouse compatibility.
| Plugin | Description |
|---|---|
@chkit/plugin-codegen |
Generate TypeScript row types and Zod schemas |
@chkit/plugin-pull |
Pull schemas from a live ClickHouse instance |
@chkit/plugin-backfill |
Time-windowed data backfill with checkpoints |
@chkit/plugin-obsessiondb |
Auto-rewrite Shared engines for ObsessionDB compatibility |
Install the chkit agent skill so AI coding assistants understand chkit:
npx skills add obsessiondb/chkitSee the chkit documentation.
chkit is pre-1.0. While the version is 0.x, the public API is still
stabilizing and any release may contain breaking changes — this is the
standard SemVer 0.x contract. Pin an exact
version (or a tight range) if you need reproducible installs.
latesttracks the current beta line. Until 1.0 ships, installingchkitwith no tag (bun add -d chkit) gives you the latest0.1.0-beta.xbuild. This is intentional for the pre-1.0 period.- All publishable packages release in lockstep.
chkit,create-chkit, and every@chkit/*package share a single version, so a given chkit version always lines up with matching plugin and core versions — there is no cross-package version skew. - Public vs. internal surface. The supported public API is the
chkitCLI,@chkit/core, and the@chkit/plugin-*packages.@chkit/clickhouseand@chkit/codegenare internal and not meant to be installed directly. - At 1.0 chkit will commit to real SemVer (breaking changes only in major bumps) and a deprecation policy. Until then, treat minor/patch bumps as potentially breaking.
Built and maintained by the team behind ObsessionDB — fully-managed ClickHouse with a first-party chkit integration (@chkit/plugin-obsessiondb).