Skip to content

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.

  • schema: glob path to schema files
  • entry: optional project entry module in place of schema globs (TypeScript only)
  • outDir: root folder for generated artifacts
  • migrationsDir: SQL migration file folder
  • metaDir: state folder (snapshot.json)
  • plugins: plugin registrations
  • clickhouse: live connection options
  • check: CI gate behavior
  • safety: 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.

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',
},
})

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,
},

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.

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.

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',
},

When cluster is set, chkit:

  • emits every generated DDL statement with an ON CLUSTER <name> clause, so generate bakes it into the migration files and migrate propagates each change to all nodes via ClickHouse’s distributed DDL queue,
  • creates its migration journal (_chkit_migrations) as a ReplicatedReplacingMergeTree, keeping applied-migration history consistent across every node — so running migrate against a load-balanced endpoint never re-applies migrations, and
  • creates the ingest journal as one ReplicatedMergeTree shared 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.

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.