# chkit

> ClickHouse schemas, migrations, and API sync in code. Schema workflows in TypeScript and Python; API sync in TypeScript.

chkit defines ClickHouse schemas, generates and applies reviewable migration SQL, detects drift, and syncs API data into schema-managed tables through TypeScript readers with retries and journaled checkpoints. Plugins add schema pulling, type generation, and SQL backfills. 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.
- [API Sync](https://chkit.obsessiondb.com/api-sync.md): Read application APIs into ClickHouse with TypeScript streams and durable checkpoints.
- [Getting Started](https://chkit.obsessiondb.com/getting-started.md): Set up chkit from an example or add it to an existing project.
- [Apps & integrations](https://chkit.obsessiondb.com/integrations.md): Browse the chkit app registry for ClickHouse integrations, synced records, setup guides, and editable API sync templates.
- [API sync authoring skill](https://chkit.obsessiondb.com/api-sync/agent-skill.md): Install a concise agent skill for implementing new chkit API sync sources.
- [Attio template](https://chkit.obsessiondb.com/api-sync/attio.md): Find the Attio integration guide for installation, synced resources, and ClickHouse queries.
- [Destinations and transformations](https://chkit.obsessiondb.com/api-sync/destinations.md): Store raw data for flexible ClickHouse transformations or map records into a known schema before loading.
- [Incremental syncs](https://chkit.obsessiondb.com/api-sync/incremental-syncs.md): Start with a full sync, then use time windows or durable provider state to fetch changes.
- [Loading and batching](https://chkit.obsessiondb.com/api-sync/loading.md): Use the default loader, then tune batch sizes and concurrency when the workload needs it.
- [Scheduling and recovery](https://chkit.obsessiondb.com/api-sync/operations.md): Select streams, configure retries and limits, backfill source data, and inspect ingestion progress.
- [API sync quickstart](https://chkit.obsessiondb.com/api-sync/quickstart.md): Read a public API into a raw ClickHouse table and query it through a SQL view.
- [Readers and pagination](https://chkit.obsessiondb.com/api-sync/readers.md): Fetch bounded pages, then add child collections and provider-specific behavior as needed.
- [Publish a registry](https://chkit.obsessiondb.com/api-sync/registry-authoring.md): Build and host versioned chkit templates containing editable schemas and ingestion source.
- [Provider templates](https://chkit.obsessiondb.com/api-sync/templates.md): Copy provider schemas and ingestion readers into a TypeScript project with one command.
- [Test a source](https://chkit.obsessiondb.com/api-sync/testing.md): Verify source selection, checkpoint safety, and replay using in-memory ingestion adapters.
- [chkit is now available in Python](https://chkit.obsessiondb.com/blog/chkit-python.md): chkit-py brings the full ClickHouse schema-as-code toolkit to Python, at parity with the TypeScript original. What it covers, how the two implementations stay in sync, and what is different in Python.
- [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 add](https://chkit.obsessiondb.com/cli/add.md): Copy a provider template, register its exports, and install its dependencies.
- [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 typed row models (TypeScript types or Pydantic models), plus TypeScript-only 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 ingest](https://chkit.obsessiondb.com/cli/ingest.md): Run, list, or inspect the ingestion streams your project exports.
- [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 schema file.
- [chkit query](https://chkit.obsessiondb.com/cli/query.md): Run a SQL query against the configured ClickHouse target.
- [chkit registry](https://chkit.obsessiondb.com/cli/registry.md): Browse registry apps, inspect sync resources and integration guides, and build versioned provider templates.
- [chkit snapshot](https://chkit.obsessiondb.com/cli/snapshot.md): Rebuild snapshot.json from your schema definitions, for example after two branches conflict on it.
- [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 / clickhouse.config.py 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 the hello example with create-chkit and apply its first migration.
- [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.
- [Integrating ClickHouse with Attio](https://chkit.obsessiondb.com/integrations/attio.md): Sync Attio CRM records, custom objects, lists, notes, tasks, and workspace members into ClickHouse with editable readers and SQL views.
- [Integrating ClickHouse with Circleback](https://chkit.obsessiondb.com/integrations/circleback.md): Install the editable Circleback raw ingestion example.
- [Integrating ClickHouse with GitHub](https://chkit.obsessiondb.com/integrations/github.md): Install the editable GitHub raw ingestion example.
- [Integrating ClickHouse with Google Calendar](https://chkit.obsessiondb.com/integrations/google-calendar.md): Install canonical Google Calendar ingestion with resumable pages and sync-token checkpoints.
- [Integrating ClickHouse with Google Meet](https://chkit.obsessiondb.com/integrations/google-meet.md): Install resumable Google Meet ingestion with retained parent work and paged transcript entries.
- [Integrating ClickHouse with Lemlist](https://chkit.obsessiondb.com/integrations/lemlist.md): Install the editable Lemlist raw ingestion example.
- [Integrating ClickHouse with Linear](https://chkit.obsessiondb.com/integrations/linear.md): Install the editable Linear raw ingestion example.
- [Integrating ClickHouse with Slack](https://chkit.obsessiondb.com/integrations/slack.md): Sync Slack conversations, users, message history, and thread replies into raw ClickHouse tables with editable API readers.
- [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 one set of schema files with Shared engines works against both ObsessionDB and regular ClickHouse.
- [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.
- [Ingest Plugin](https://chkit.obsessiondb.com/plugins/ingest.md): Load application API data into ClickHouse with TypeScript readers and journaled checkpoints.
- [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, materialized views, and dictionaries and generate chkit schema files.
- [Python Core API](https://chkit.obsessiondb.com/python/core-api.md): The chkit.core pipeline as library functions — loading, validation, diffing, planning, snapshots, and SQL rendering.
- [Python Overview](https://chkit.obsessiondb.com/python/overview.md): Define ClickHouse schemas and run migrations in Python with chkit-py.
- [Schema DSL Reference](https://chkit.obsessiondb.com/schema/dsl-reference.md): Complete reference for chkit schema definition functions, column types, and table options — in TypeScript and Python.
- [Kafka tables](https://chkit.obsessiondb.com/schema/kafka.md): Define Kafka queues and materialized-view ingestion pipelines in schema code.
- [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.