chkit Docs | Blog

chkit is now available in Python

Tue, 11 Aug 2026 00:00:00 GMT

We closed our last post with a promise: if you do not use TypeScript but Python, a port was coming. It shipped.

pip install chkit-py
chkit --help

That is the entire ClickHouse® schema-as-code toolkit, ported to Python at parity with the TypeScript original: the DSL, the diff engine, the migration planner, the drift detection, the CI gates, and the plugins. It is not a wrapper around a Node binary. A wrapper would still put a Node runtime in your Airflow images and give Python nothing importable. It is a full port, with Pydantic models, a library API, and a CLI that is just chkit on your PATH.

This post covers why we built it, how the two implementations stay in sync, and what is different on the Python side.

The people closest to ClickHouse write Python

Look at who actually sits next to a ClickHouse cluster all day. Data engineers orchestrating pipelines in Airflow and Dagster. Analytics engineers living in notebooks. ML teams whose entire world is pandas, Polars, and PyArrow. The queries feeding your dashboards were probably prototyped in a Jupyter cell.

For that whole population, a schema tool that only exists on npm is a tax. Adopting chkit meant adopting a Node toolchain (package.json, a runtime, a lockfile) in repositories that had none, maintained by people who did not choose JavaScript and should not have to. Most teams do the rational thing instead: they keep hand-writing DDL, which is exactly the failure mode chkit exists to eliminate.

Agents default to Python

Coding agents are the other reason. Ask an agent to script something against a database and it almost always writes Python, because that is the ecosystem it draws from.

If your schema toolkit does not exist in Python, agents route around it: they hand-write the CREATE TABLE, and you are back to unreviewed DDL, the exact problem chkit exists to solve. If you want agents to keep schema changes inside the migration workflow, the tool has to exist in the language they actually use.

The docs follow the same idea. Every page of chkit.obsessiondb.com is available as raw Markdown (append .md to any URL), there is an llms.txt index at the root, and every reference page now shows TypeScript and Python side by side with synced tabs: pick your language once, and the whole site follows. An agent (or a human) landing anywhere in the docs gets working code in the language it is actually going to run.

The same schema, in Python

Here is the table from our last post, in Python:

from chkit import schema, table

events = table(
    database="analytics",
    name="events",
    columns=[
        {"name": "id", "type": "UInt64"},
        {"name": "org_id", "type": "String"},
        {"name": "source", "type": "LowCardinality(String)"},
        {"name": "payload", "type": "String", "nullable": True},
        {"name": "received_at", "type": "DateTime64(3)", "default": "fn:now64(3)"},
    ],
    engine="MergeTree()",
    primary_key=["id"],
    order_by=["org_id", "received_at", "id"],
    partition_by="toYYYYMM(received_at)",
    ttl="received_at + INTERVAL 90 DAY",
    settings={"index_granularity": 8192},
    indexes=[
        {"name": "idx_source", "expression": "source", "type": "set", "maxRows": 0, "granularity": 1},
    ],
)

definitions = schema(events)

Definitions are Pydantic models: frozen, validated at construction, unknown fields rejected. A typo in a column option fails loudly at import time instead of silently shipping a table with no codec. The DSL accepts both snake_case and the TypeScript camelCase names (primary_key or primaryKey), so examples port between languages with their keys unchanged.

The CLI is the same CLI. Same commands, same flags, same exit codes, same --json envelopes:

chkit generate --name add_events_table
chkit migrate            # shows the plan
chkit migrate --apply    # applies, journals, verifies checksums
chkit drift
chkit check --strict     # your CI gate

Everything from the last post carries over. The guardrails: risk-tagged plans, the structural-vs-alterable distinction, tracked renames, destructive-operation blocking with exit code 3, checksum-verified migration history. The schema surface: dictionaries, refreshable materialized views, projections, ON CLUSTER mode. The ecosystem: pull for adopting an existing database (a built-in command in Python, no plugin to install), the codegen plugin (which emits Pydantic models, one shape covering what TypeScript needed interfaces and Zod for), the backfill engine, and the ObsessionDB integration.

Two implementations, one source of truth

A second implementation is only useful if the two never disagree. chkit-py and chkit share their artifacts:

The snapshot (chkit/meta/snapshot.json) serializes with identical JSON shapes. A snapshot written by the TypeScript CLI is read by the Python CLI, and vice versa.
The journal is the same _chkit_migrations table in ClickHouse, same schema, same SHA-256 checksums.
The SQL: both planners render the same DDL for the same definitions, statement for statement, down to how ClickHouse normalizes projection index parentheses.

Which means a TypeScript service and a Python pipeline can manage the same database without stepping on each other. Your app team stays in TS, your data team stays in Python, and there is still exactly one source of truth with one migration history.

Keeping that guarantee was most of the porting work, down to matching JavaScript’s number formatting so a plan written by one implementation runs unchanged under the other. It is verified by 1,100+ tests (most ported case-for-case from the TypeScript suites) that run in the same CI on every commit, plus an e2e suite per implementation against live ClickHouse. The deliberate differences between the two are documented in DRIFT.md.

A few things intentionally did not cross over: the create chkit scaffolder (chkit init covers it), dependency auto-install (Python convention is an explicit pip install), the chkit skills proxy, and two codegen extras (ingest helpers and an embedded migration runner) that are deferred until Python users ask for them.

Start from where you already are

Same story as the TypeScript side, minus the toolchain:

pip install chkit-py
chkit init                    # writes clickhouse.config.py + a starter schema
chkit generate --name init
chkit migrate --apply

Already running ClickHouse? chkit pull introspects the live database and writes a deterministic Python schema file with everything in it: tables, views, materialized views, dictionaries, codecs, projections. Then chkit drift confirms the result matches before you change anything.

Config is a plain Python module (clickhouse.config.py), reading credentials from environment variables, with the same options and defaults as the TypeScript config, including function-style configs for CI. The three first-party plugins ship inside the package; there is nothing else to install.

One toolkit, whatever the language

Last time we argued that ClickHouse deserves the migration tooling relational databases have had for years. That argument no longer depends on your language: if you run ClickHouse from Python, chkit now works the same way it does from TypeScript.

Install: https://pypi.org/project/chkit-py/
Docs: https://chkit.obsessiondb.com/python/overview/
Repo: https://github.com/obsessiondb/chkit (MIT, the Python port lives in chkit_python/)

Same disclosure as last time: we run ObsessionDB, a managed ClickHouse offering, and chkit-py, like chkit, runs against ObsessionDB, ClickHouse Cloud, Altinity, or any self-hosted ClickHouse. No lock-in; the tooling is for the ecosystem.

It is beta, like its TypeScript sibling: the CLI surface and the DSL are stable, but we may make small breaking changes before 1.0. If something is missing, or the Python ergonomics could be better, issues and PRs are welcome. Improvements land in both languages.

Stay tuned!

ClickHouse® is a registered trademark of ClickHouse, Inc.

The era of OLAP deserves the tooling relational has had for years

Thu, 25 Jun 2026 00:00:00 GMT

If you build on Postgres or MySQL, you have not hand written a migration in years. You change a TypeScript schema, a tool diffs it, generates the SQL, applies it, and fails your CI if production has drifted. Drizzle, Prisma, and Flyway made that the default. It is boring, and boring is exactly what you want from the thing that changes your database.

Now switch to ClickHouse®. Suddenly you are back in 2010: hand written DDL, diffs done by eye, a migrations/ folder that may or may not match what is actually running, and a sinking feeling every time someone runs an ALTER in production. OLAP is becoming the default for analytics, but the tooling around it never caught up to what the relational world treats as table stakes.

We felt this acutely. In our previous venture, Numia, we ran ClickHouse at near-petabyte scale for real-time blockchain analytics. We hit two walls. The first was scaling the database like serious infrastructure. The second was the complete absence of tooling to manage the schema as code. We built ObsessionDB, managed ClickHouse with decoupled storage and compute, to solve the first. ch-kit is how we are solving the second, and it is open source.

This post is about the second wall, and what schema-as-code for ClickHouse actually looks like once you have it.

The problem with hand written DDL

A ClickHouse schema is not just a list of columns. A single MergeTree table carries an engine, a sorting key, a partitioning expression, TTL rules, skip indexes, projections, codecs, and table settings. Materialized views point at target tables. Some of those properties can be altered in place. Some cannot, and changing them means a drop and recreate, which on a large table is not a thing you discover by accident.

When all of that lives in raw SQL files, three failures show up over and over:

Drift. Someone runs a manual ALTER to fix an incident at 3am. The fix never makes it back into a migration file. Now your repository and your production database disagree, and nothing tells you.
Unsafe changes. A migration drops a column. The reviewer did not notice. It runs in CI on a Friday. The data is gone.
No source of truth. The schema is whatever the sum of every migration file happens to produce. To know the current shape of a table, you read the database, not your code.

Relational tooling solved all three. ch-kit solves them for ClickHouse.

Define your schemas in TypeScript

In ch-kit, tables, views, and materialized views are TypeScript values. Here is a real table definition, with the features you actually use in production:

import { schema, table } from '@chkit/core'

const events = table({
  database: 'analytics',
  name: 'events',
  columns: [
    { name: 'id', type: 'UInt64' },
    { name: 'org_id', type: 'String' },
    { name: 'source', type: 'LowCardinality(String)' },
    { name: 'payload', type: 'String', nullable: true },
    { name: 'received_at', type: 'DateTime64(3)', default: 'fn:now64(3)' },
  ],
  engine: 'MergeTree()',
  primaryKey: ['id'],
  orderBy: ['org_id', 'received_at', 'id'],
  partitionBy: 'toYYYYMM(received_at)',
  ttl: 'received_at + INTERVAL 90 DAY',
  settings: { index_granularity: 8192 },
  indexes: [
    { name: 'idx_source', expression: 'source', type: 'set', maxRows: 0, granularity: 1 },
  ],
})

export default schema(events)

This is the desired state of your database, expressed as code, type checked, reviewable in a pull request, and split across as many files as you want. Materialized views and refreshable views are first class, including the to target table and refresh schedules. Compression codecs are typed too, so a column codec chain like [{ kind: 'DoubleDelta' }, { kind: 'ZSTD', level: 3 }] is validated rather than stringly typed.

You do not write SQL to define this. You write SQL for your queries, because ch-kit is not an ORM and has no opinion about how you read your data. It only owns the schema, the migrations, and the guardrails.

Migrations are diffs, not artifacts you maintain

As we’ve mentioned already multiple times, with ch-kit you just change the TypeScript, and the rest is handled for you. Migrations are part of it.

chkit generate --name add_events_table

With generate, ch-kit loads your TS definitions, compares them against the previous snapshot, computes an ordered plan, and writes a migration SQL file plus an updated snapshot. If nothing changed, no file is created. Every operation in the plan is tagged with a risk level:

Risk	Meaning	Examples
`safe`	No data loss	`CREATE TABLE`, `ADD COLUMN`
`caution`	Review recommended	settings changes
`danger`	Destructive	`DROP TABLE`, `DROP COLUMN`

Here is a detail that matters and that most ad hoc setups get wrong. ch-kit knows which schema properties are structural and which are alterable. Changing columns, indexes, projections, settings, or TTL is an ALTER in place. Changing the engine, primaryKey, orderBy, partitionBy, or uniqueKey is structural, which means a drop and recreate. ch-kit makes that distinction explicit in the plan instead of letting you find out in production that your “small” change rewrites the whole table.

Renames are tracked, not guessed. Mark a column or table with renamedFrom (or pass --rename-table / --rename-column) and ch-kit emits a real rename instead of a destructive drop and add:

columns: [
  { name: 'user_email', type: 'String', renamedFrom: 'email' },
]

Applying changes without losing data

Once you have your migrations defined with generate, you can preview the impact by running chkit migrate. This will dry run and show you the plan. If you like what you see, just add --apply at the end for the actual run:

chkit migrate            # shows the plan
chkit migrate --apply    # applies pending migrations

Three guardrails run on every apply:

Destructive operations are blocked. Any migration containing a risk=danger operation, a DROP TABLE or DROP COLUMN, requires explicit approval. In an interactive terminal you get a prompt. In CI, the command exits with code 3 and refuses to run unless you pass --allow-destructive or set safety.allowDestructive in config. The error payload tells you exactly which migration and which operation, with an impact description and a recommendation. Your data does not disappear because a reviewer was tired.
Checksums are verified. Every applied migration is recorded in a _chkit_migrations journal table in ClickHouse along with a SHA-256 hash of the file content. If a migration file is edited after it was applied, the next run aborts before touching anything. Migration history is immutable, and ch-kit enforces it.
It is built for CI. The CLI detects non-interactive environments (CI=true, no TTY) and never blocks on a prompt. Every command supports --json with a stable output envelope, so you can parse results with jq and build approval gates.

Don’t let your project drift!

ch-kit also implements a drift command that introspects the live database and compares it, object by object and column by column, against your snapshot:

chkit drift --json

It reports missing objects, extra objects, changed columns, and mismatches on settings, TTL, indexes, ORDER BY, PARTITION BY, primary keys, and projections. It is detailed enough that the 3am manual ALTER shows up the next morning as a concrete, named difference instead of a vague feeling that something is off.

In CI you turn that signal into a gate with chkit check:

chkit check --strict --json

check evaluates three policies, all on by default: fail on pending migrations, fail on checksum mismatch, fail on drift. The --strict flag forces them on regardless of config, so a permissive local setting never leaks into your pipeline. A full pull request gate is a few lines:

- name: Check schema consistency
  run: npx chkit check --strict --json

- name: Verify generated types
  run: npx chkit codegen --check --json

That codegen --check step is the other half. ch-kit generates TypeScript row types (and optional Zod schemas) from the same definitions, so your application types and your database schema cannot quietly diverge either.

Works with any ClickHouse

ch-kit is not a lock-in play. We run ObsessionDB, a managed ClickHouse offering that competes with ClickHouse Cloud, Altinity, and the rest. But we love ClickHouse, and we believe the tooling around it should be available to everyone using the technology, because that is what strengthens the ecosystem. So ch-kit runs against ObsessionDB, ClickHouse Cloud, Altinity, or any other managed or self-hosted ClickHouse.

The only managed-specific touch is that Shared* engine prefixes (SharedMergeTree, SharedReplacingMergeTree, and so on) are normalized away during comparison, so managed engines do not show up as false drift. If you run ObsessionDB, the first-party plugin keeps your schema on the right Shared* engines automatically, from the exact same TypeScript you use locally. If you do not, those engine variants are stripped for your target. Same schema, different backends.

It is MIT licensed, written in TypeScript, runs on Node 20+ or Bun, and needs ClickHouse 24.x or newer. It is beta: the CLI surface and the schema DSL are stable and run our own production workloads today, and we may still make small breaking changes before 1.0.

Start from where you already are

Most teams adopting ch-kit are not starting from an empty database. They already have ClickHouse in production, with tables that matter and data they cannot lose. Either way, the first step is the same: get a project scaffolded.

If you are starting from scratch, npm create chkit@latest gives you a working project from a curated example:

npm create chkit@latest

If you are adding ch-kit to an existing TypeScript project, chkit init writes the project config (clickhouse.config.ts, with the ClickHouse connection block reading from environment variables) and a starter schema file. It is idempotent, so running it on an existing project leaves your files untouched.

my-app/

# before: your existing TypeScript project
# ├── package.json
# ├── tsconfig.json
# └── src/
#     └── index.ts

$ chkit init
Created clickhouse.config.ts
Created src/db/schema/example.ts

# after: chkit added exactly two files, nothing else touched
# my-app/
# ├── clickhouse.config.ts          ← config: ClickHouse connection + plugins
# ├── package.json
# ├── tsconfig.json
# └── src/
#     ├── index.ts
#     └── db/
#         └── schema/
#             └── example.ts        ← starter schema: an `events` table

If you are starting fresh, edit the generated example schema to match the tables you want, then move on to generate.

If you already run ClickHouse, the next command is chkit pull. It introspects your live database and writes a deterministic TypeScript schema file from what is actually there:

# 1) install the pull plugin
npm install -D @chkit/plugin-pull

# 2) register it in clickhouse.config.ts:
#      import { pull } from '@chkit/plugin-pull'
#      plugins: [pull({ outFile: './src/db/schema/pulled.ts' })]

# 3) introspect your live database into TypeScript
chkit pull --out-file ./src/db/schema/pulled.ts

This is the step that turns an existing production database into version-controlled code. You do not transcribe table definitions by hand and hope you got the ORDER BY and the codecs right. ch-kit reads them. The output is deterministic, so it produces clean, reviewable diffs instead of churn, and you can scope it to specific databases with --database or preview it with --dryrun before writing anything.

Once you have pulled, prove the result immediately:

chkit drift

If your code matches production, drift reports nothing. That zero-drift result is the moment your database stops being the source of truth and your repository takes over. From here, every future change starts in TypeScript:

chkit generate --name init
chkit migrate --apply
chkit drift

Want more? Check the rest of the features!

The relational world stopped hand writing migrations a long time ago. OLAP should not be the exception. If you run ClickHouse and you are still managing schema by hand, we built ch-kit so you do not have to.

Repo: https://github.com/obsessiondb/chkit
Docs: https://chkit.obsessiondb.com/getting-started/
Install: https://www.npmjs.com/package/chkit

If you do not use TypeScript but Python, do not worry: we will publish a Python port in the coming weeks. And since ch-kit is open source, if you feel something is missing, you are more than welcome to open an issue or a PR.

Stay tuned!

ClickHouse® is a registered trademark of ClickHouse, Inc.