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.

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, and
  • 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.

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. chkit query is the exception: when no project config is found, it falls back to the profile, so ad-hoc queries run from any directory, including right after chkit obsessiondb login without a local config file at all.

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 has no profile config: it reads only the project config.