Skip to content
ch-kit Schema

Python Overview (beta)

Use chkit-py to define ClickHouse schemas and run the chkit migration workflow in Python. Python support is in beta; its API and CLI behavior may change between releases.

Install

Section titled “Install”
Terminal window
pip install chkit-py
chkit --help

The package is named chkit-py on PyPI; the import name is chkit.

Quickstart

Section titled “Quickstart”
Terminal window
pip install chkit-py
chkit init                    # scaffold clickhouse.config.py + example schema
chkit generate --name init    # diff schema vs snapshot, write migrations/*.sql
chkit migrate --json          # inspect the pending plan without applying
chkit migrate --apply         # apply pending migrations
chkit status                  # show applied / pending counts
chkit check --strict          # CI gate (pending, drift, checksum)

Use the CLI Reference for shared commands, flags, exit codes, and --json output. chkit --help and chkit <command> --help print the same help as the TypeScript CLI, listing chkit-py’s own commands and flags. chkit-py declares the ObsessionDB plugin flags on its commands, so --help-plugins lists them without loading the config. See the TypeScript-only features below. Config lives in clickhouse.config.py instead of clickhouse.config.ts, and schema files are Python modules instead of TypeScript modules.

Design

Section titled “Design”
  • Type checking. Public APIs have type annotations checked with mypy --strict and pyright strict mode.
  • Pydantic v2 models. Schema objects are frozen. Pydantic validates them at construction and rejects unknown fields.
  • Imperative core. Pure functions over data; minimal classes outside of Pydantic models and the CLI shell.

Interoperability with TypeScript chkit

Section titled “Interoperability with TypeScript chkit”

Both implementations produce the same artifacts, so a project (or a team) can mix them:

  • Snapshots: models serialize with the same camelCase JSON field names as @chkit/core, so chkit/meta/snapshot.json is readable by either implementation.
  • Journal: migrations are recorded in the same ClickHouse _chkit_migrations table with the same schema and checksums.
  • SQL: the planner and renderer emit the same DDL statements for the same schema, including ON CLUSTER stamping when clickhouse.cluster is set.

Differences from the TypeScript version

Section titled “Differences from the TypeScript version”

The schema/migration CLI and backfill engine share the TypeScript workflow. The following features are TypeScript-only:

  • chkit skills proxy and the create-chkit scaffolder: use chkit init instead.
  • deps.ts-style dependency auto-install: install packages explicitly with pip.
  • The project entry module: use schema globs to select Python schema files.

These pages

Section titled “These pages”

Use the Core API to load and validate definitions, plan diffs, manage snapshots, and render SQL from Python. Use the Python tabs in the Schema DSL Reference for schema definitions.

Section titled “Related”