Skip to content

README.md

Latest commit

 

History

History
76 lines (51 loc) · 2.61 KB

README.md

File metadata and controls

76 lines (51 loc) · 2.61 KB

chkit

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.

Features

  • 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 check to 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 --json for scripting and automation

Install

bun add -d chkit

Usage

# 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 check

All commands support --json for machine-readable output and --config <path> to specify a custom config file.

Plugins

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

AI Agent Skill

Install the chkit agent skill so AI coding assistants understand chkit:

npx skills add obsessiondb/chkit

Documentation

See the chkit documentation.

License

MIT

Sponsored by ObsessionDB