# chkit

> ClickHouse schema management and migration toolkit for TypeScript.

chkit defines ClickHouse schemas in TypeScript, diffs them into migration SQL, applies migrations, and verifies the live database stays in sync. Each link below points to the raw Markdown of that page.

## Docs

- [For AI Agents](https://chkit.obsessiondb.com/ai-agents.md): How an AI coding agent should set up and operate chkit on a user's behalf.
- [Getting Started](https://chkit.obsessiondb.com/getting-started.md): Get chkit running in your project — start from a curated example or add it to an existing repo.
- [The era of OLAP deserves the tooling relational has had for years](https://chkit.obsessiondb.com/blog/olap-deserves-better-tooling.md): Why we built ch-kit: schema-as-code, migrations, and guardrails for ClickHouse, after running it at near-petabyte scale.
- [chkit check](https://chkit.obsessiondb.com/cli/check.md): Run policy checks for CI gates covering pending migrations, checksums, drift, and plugins.
- [chkit codegen](https://chkit.obsessiondb.com/cli/codegen.md): Generate TypeScript types, ingestion functions, and runtime migration modules from schema definitions.
- [chkit drift](https://chkit.obsessiondb.com/cli/drift.md): Compare the snapshot against live ClickHouse and report schema differences.
- [chkit generate](https://chkit.obsessiondb.com/cli/generate.md): Diff schema definitions against the last snapshot and produce migration SQL.
- [chkit init](https://chkit.obsessiondb.com/cli/init.md): Scaffold a chkit project — config, example schema, dependencies, and an optional database connection.
- [chkit migrate](https://chkit.obsessiondb.com/cli/migrate.md): Apply pending migration files to ClickHouse.
- [CLI Overview](https://chkit.obsessiondb.com/cli/overview.md): Command surface of the chkit CLI.
- [chkit plugin](https://chkit.obsessiondb.com/cli/plugin.md): List installed plugins or run plugin commands.
- [chkit pull](https://chkit.obsessiondb.com/cli/pull.md): Introspect live ClickHouse and generate a TypeScript schema file.
- [chkit query](https://chkit.obsessiondb.com/cli/query.md): Run a SQL query against the configured ClickHouse target.
- [chkit status](https://chkit.obsessiondb.com/cli/status.md): Show migration status including total, applied, pending, and checksum mismatches.
- [Configuration Overview](https://chkit.obsessiondb.com/configuration/overview.md): clickhouse.config.ts structure and defaults.
- [Add to an existing project](https://chkit.obsessiondb.com/getting-started/add-to-existing-project.md): Install chkit into an existing TypeScript project and run the first migration flow.
- [Start with an example](https://chkit.obsessiondb.com/getting-started/with-an-example.md): Scaffold a working chkit project from a curated example with create-chkit.
- [CI/CD Integration](https://chkit.obsessiondb.com/guides/ci-cd.md): Run chkit schema validation, migration deployment, and type checking in continuous integration pipelines.
- [ClickHouse compatibility](https://chkit.obsessiondb.com/guides/clickhouse-compatibility.md): Which ClickHouse versions and engines chkit supports, and which features are version-gated.
- [The migration workflow](https://chkit.obsessiondb.com/guides/migration-workflow.md): How chkit's ahead-of-time migration model works: what snapshot.json holds, which files to commit, and how a team deploys when only some developers can reach production.
- [Troubleshooting](https://chkit.obsessiondb.com/guides/troubleshooting.md): Common chkit errors mapped to their causes and fixes — missing dependencies, connection and auth failures, rejected migrations, blocked destructive operations, and drift.
- [Backfill Jobs](https://chkit.obsessiondb.com/obsessiondb/backfills.md): Run backfills as managed ObsessionDB jobs — submit a plan, track it in the console, and let the backend execute the chunks server-side.
- [Engine Rewriting](https://chkit.obsessiondb.com/obsessiondb/engine-rewriting.md): How chkit strips Shared engine prefixes when the target isn't ObsessionDB so one set of schema files works against both.
- [Getting Started with ObsessionDB](https://chkit.obsessiondb.com/obsessiondb/getting-started.md): Connect chkit to ObsessionDB from the CLI — claim a free dev instance, sign up with a one-time email code, or log in to an existing account.
- [ObsessionDB Overview](https://chkit.obsessiondb.com/obsessiondb/overview.md): First-class integration with ObsessionDB — engine rewriting, service selection, and remote execution from one schema.
- [Services](https://chkit.obsessiondb.com/obsessiondb/services.md): List, select, alias, and override ObsessionDB services per command — and how queries route through the ObsessionDB API.
- [Backfill Plugin](https://chkit.obsessiondb.com/plugins/backfill.md): Plan, execute, and monitor time-windowed backfill operations with async query submission, concurrent execution, and checkpointed progress.
- [Codegen Plugin](https://chkit.obsessiondb.com/plugins/codegen.md): Generate TypeScript row types, optional Zod schemas, ingestion functions, and runtime migration modules from chkit schema definitions.
- [Plugins Overview](https://chkit.obsessiondb.com/plugins/overview.md): How chkit plugins work and which official plugins are available.
- [Pull Plugin](https://chkit.obsessiondb.com/plugins/pull.md): Introspect live ClickHouse tables, views, and materialized views and generate chkit schema files.
- [Schema DSL Reference](https://chkit.obsessiondb.com/schema/dsl-reference.md): Complete reference for chkit schema definition functions, column types, and table options.
- [Schema Overview](https://chkit.obsessiondb.com/schema/overview.md): How chkit thinks about ClickHouse schema and where to learn each piece of the DSL.
- [Refreshable Materialized Views](https://chkit.obsessiondb.com/schema/refreshable-views.md): Schedule ClickHouse materialized views to refresh on a cron-like cadence, with APPEND mode, DEPENDS ON chains, and the three hard rules chkit enforces.
- [Tutorial: your first schema](https://chkit.obsessiondb.com/tutorials/first-schema.md): Build a chkit project from an empty folder — migrate the starter table to a live database, insert and query rows, then evolve the schema.