Skip to content

Schema CLI Overview

Use the chkit CLI to define ClickHouse schemas in TypeScript or Python, generate and review migration SQL, deploy changes, and check for drift.

CommandDescription
chkit initScaffold a new project with config and example schema
chkit generateDiff schema definitions against the last snapshot and produce migration SQL
chkit migrateApply pending migration files to ClickHouse
chkit statusShow migration status (total, applied, pending, checksum mismatches)
chkit driftCompare snapshot against live ClickHouse and report differences
chkit checkRun policy checks for CI gates (pending, checksums, drift, plugins)
chkit snapshotRebuild snapshot.json from schema definitions, for example after a merge conflict
chkit queryRun an ad-hoc SQL query against the configured target
chkit pullIntrospect live ClickHouse and generate a schema file
chkit codegenGenerate typed row models from schema definitions
chkit pluginList or run plugin commands

Generate migrations from local files without a database connection. The starter schema still requires an explicitly chosen CLICKHOUSE_DB namespace. Preserve supplied target metadata during generation so cluster and engine settings remain consistent. Configure a ClickHouse connection to apply migrations or inspect a live database.

Two groups of commands. No connection: generate (diff schema vs snapshot), codegen (types from schema), and editing schema files. Connects to ClickHouse: migrate (apply SQL), pull (introspect), status (read journal), check and drift (compare live DB to code).
Needs a connectionOffline
migrate (apply SQL), pull (introspect), status (read journal), check / drift (compare live DB to code)generate (diff schema vs. snapshot), snapshot rebuild (rewrite the snapshot from schema), codegen (types from schema), editing schema files
Terminal window
chkit init # scaffold config + example schema
# Set CLICKHOUSE_DB to the intended namespace before generation.
chkit generate --name init # produce migration SQL + snapshot
# Supply the remaining connection values before connected commands.
chkit migrate --json # inspect the pending plan without applying
chkit migrate --apply # apply reviewed migrations to ClickHouse
chkit status # verify migration state
chkit check # CI gate: pending, checksums, drift, plugins

These flags are available on every command that loads a config file:

FlagTypeDefaultDescription
-c, --config <path>stringclickhouse.config.ts / clickhouse.config.pyPath to the chkit config file
--jsonbooleanfalseEmit machine-readable JSON output
-t, --table <selector>stringn/aNarrow some commands to matching tables (exact name or trailing wildcard prefix, e.g. events_*). Effect varies per command: see note below
-h, --helpbooleann/aShow built-in help without evaluating project config
--help-pluginsbooleann/aInclude configured plugin flags; evaluates config/plugin registration but skips lifecycle hooks
-v, -V, --versionbooleann/aPrint CLI version

Both CLIs accept the same short forms: the ones in these tables, generate -n, pull -o/-d/-f and init -y. A short flag takes its value as -t events, -t=events or -tevents. Short flags cannot be bundled: -fo out.ts is an unknown flag. -v/-V work only before a command. Any other short flag, such as -x, is rejected as an unknown flag, the same as an unknown long flag. Before the config is loaded, chkit does not know which flags its plugins add, so a plugin flag value that starts with -c or -t (--tag -critical) reads as --config or --table; write it with = (--tag=-critical).

The effect of --table depends on the command:

  • generate, migrate, and drift use it to narrow the schema/migration operations they plan or evaluate.
  • check applies it only to its drift and plugin checks; the pending-migration and checksum checks still run across all tables, so chkit check --table app.users can still fail on an unrelated pending migration.
  • status, codegen, and pull accept the flag but ignore it, so chkit status --table app.users still reports unscoped totals.
  • snapshot rebuild rejects it: a rebuild always rewrites the whole snapshot.

Check the command reference before relying on table filtering.

These environment variables affect every command:

VariableDescription
CHKIT_DEBUGSet to 1 or true to emit structured debug logging to stderr. Covers config loading, command dispatch, plugin lifecycle hooks, ClickHouse queries with timing, journal operations, and per-command details.
CHKIT_JOURNAL_TABLEOverride the name of the migration journal table (default _chkit_migrations). See chkit migrate.

Read debug logs from stderr and --json output from stdout:

Terminal window
CHKIT_DEBUG=1 chkit migrate --apply