Configuration Overview
chkit is configured through clickhouse.config.ts (TypeScript) or clickhouse.config.py (Python, in beta). Shared configuration options use the same keys and defaults in both languages.
Core Fields
Section titled “Core Fields”schema: glob path to schema filesentry: optional project entry module in place ofschemaglobs (TypeScript only)outDir: root folder for generated artifactsmigrationsDir: SQL migration file foldermetaDir: state folder (snapshot.json)plugins: plugin registrationsclickhouse: live connection optionscheck: CI gate behaviorsafety: destructive migration safety behavior
Migration state (the journal of applied migrations) is not stored in metaDir. It lives in the _chkit_migrations table in your configured clickhouse.database, so status, migrate, and check require a ClickHouse connection.
Example
Section titled “Example”import { defineConfig } from '@chkit/core'
export default defineConfig({ schema: './src/db/schema/**/*.ts', outDir: './chkit', migrationsDir: './chkit/migrations', metaDir: './chkit/meta', clickhouse: { url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123', username: process.env.CLICKHOUSE_USER ?? 'default', password: process.env.CLICKHOUSE_PASSWORD ?? '', database: process.env.CLICKHOUSE_DB ?? 'default', },})import os
from chkit import define_config
config = define_config( { "schema": "./src/db/schema/**/*.py", "outDir": "./chkit", "migrationsDir": "./chkit/migrations", "metaDir": "./chkit/meta", "clickhouse": { "url": os.environ.get("CLICKHOUSE_URL", "http://localhost:8123"), "username": os.environ.get("CLICKHOUSE_USER", "default"), "password": os.environ.get("CLICKHOUSE_PASSWORD", ""), "database": os.environ.get("CLICKHOUSE_DB", "default"), }, })Connection URL (clickhouse.url)
Section titled “Connection URL (clickhouse.url)”The URL scheme sets the protocol: https:// connects over TLS, http:// over plain HTTP. A URL without a port uses the scheme’s default port (443 for https, 80 for http), so include the port for ClickHouse’s own ports, as in http://localhost:8123 or https://host:8443.
clickhouse.secure is optional and defaults to the URL scheme. If you set it, it must match the scheme: secure: true with an http:// URL, or secure: false with an https:// URL, fails when the config loads.
MergeTree index granularity (clickhouse.indexGranularity)
Section titled “MergeTree index granularity (clickhouse.indexGranularity)”ClickHouse writes index_granularity into every MergeTree table created without it, using the server’s <merge_tree><index_granularity> setting (8192 unless the server sets another value). The setting cannot change afterwards. chkit gives such a table the same value: CREATE TABLE writes it, and generate, drift and cutovers compare it.
clickhouse.indexGranularity is the value chkit assumes. It defaults to 8192. Set it when your server uses another default:
clickhouse: { url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123', indexGranularity: 4096,},"clickhouse": { "url": os.environ.get("CLICKHOUSE_URL", "http://localhost:8123"), "indexGranularity": 4096,},drift, check, migrate and pull read the server’s default from system.merge_tree_settings and stop when it differs from clickhouse.indexGranularity, with a message that names the value to set. When the server cannot be asked (no access to system.merge_tree_settings), they skip the check. generate runs offline and does not check.
Project entry (entry, TypeScript only)
Section titled “Project entry (entry, TypeScript only)”Instead of schema globs you can point chkit at one entry module:
export default defineConfig({ entry: './src/chkit.ts',})chkit imports the module once and collects the schema definitions it exports, including definitions re-exported from other files. This provides a single explicit list of tables, views, and dictionaries instead of matching files by glob. entry and schema are mutually exclusive.
Cluster mode (ON CLUSTER)
Section titled “Cluster mode (ON CLUSTER)”For self-managed multi-node ClickHouse clusters, set clickhouse.cluster to the cluster name from your server’s remote_servers config:
clickhouse: { url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123', password: process.env.CLICKHOUSE_PASSWORD ?? '', database: 'default', cluster: 'my_cluster',},"clickhouse": { "url": os.environ.get("CLICKHOUSE_URL", "http://localhost:8123"), "password": os.environ.get("CLICKHOUSE_PASSWORD", ""), "database": "default", "cluster": "my_cluster",},When cluster is set, chkit:
- emits every generated DDL statement with an
ON CLUSTER <name>clause, sogeneratebakes it into the migration files andmigratepropagates each change to all nodes via ClickHouse’s distributed DDL queue, - creates its migration journal (
_chkit_migrations) as aReplicatedReplacingMergeTree, keeping applied-migration history consistent across every node — so runningmigrateagainst a load-balanced endpoint never re-applies migrations, and - creates the ingest journal as one
ReplicatedMergeTreeshared by every node, so ingestion runs through a load balancer continue one checkpoint.
chkit does not rewrite your table engines: declare ReplicatedMergeTree (or another Replicated*/Shared* variant) yourself for tables whose data should replicate. Empty-argument engines (e.g. ENGINE = ReplicatedMergeTree) are recommended so the server’s default_replica_path supplies a collision-free Keeper path, which also keeps drop-and-recreate safe.
Cluster mode expects the standard {shard} and {replica} macros on every node (<macros><shard>…</shard><replica>…</replica></macros> in each server’s configuration) — the journal’s replicated engine interpolates both. Standard cluster layouts, including replica-only setups (shard: 1), define them already.
Leave cluster unset for single-node servers, ClickHouse Cloud, or ObsessionDB, where replication is automatic (SharedMergeTree) and ON CLUSTER is unnecessary. The value accepts an identifier (my_cluster) or a macro ({cluster}) when your nodes define one.
User profile config
Section titled “User profile config”The TypeScript CLI reads a user-profile config at ~/.config/chkit/config.ts (honoring XDG_CONFIG_HOME). When that file is missing but ObsessionDB credentials are present (~/.config/chkit/credentials.json, written by chkit obsessiondb login), chkit synthesizes a profile that registers only the ObsessionDB plugin.
Project-scoped commands (generate, migrate, status, drift, check, snapshot, codegen, pull) always require a project config in the working directory. The other commands, chkit query, chkit plugin and chkit obsessiondb, fall back to the profile when no project config is found, so ad-hoc queries run from any directory, including right after chkit obsessiondb login without a local config file at all. chkit obsessiondb and chkit plugin obsessiondb load the ObsessionDB plugin even without credentials, so chkit obsessiondb login itself runs from any directory.
When a project config is found, chkit layers the profile under it for every command. Project values win, and the profile’s plugins are added unless the project registers a plugin with the same name. On a logged-in machine the ObsessionDB plugin is therefore loaded even when clickhouse.config.ts does not register it.
The Python CLI reads its profile from ~/.config/chkit/config.py (honoring XDG_CONFIG_HOME), a module that exports config like clickhouse.config.py and may leave out schema. When that file is missing but ObsessionDB credentials are present, it synthesizes the same ObsessionDB-only profile. The project-config requirement, the fallback to the profile and the layering rules are the same as in the TypeScript CLI, so on a logged-in machine the ObsessionDB plugin is loaded even when clickhouse.config.py does not register it.
Related pages
Section titled “Related pages”- Schema DSL reference — define the database objects loaded by the config
- Schema plugins — register schema imports, row model generation, and beta SQL backfills
- CLI reference — run migrations and inspect a live database
- CI/CD integration — configure validation and deployment by environment