---
title: "Configuration Overview"
description: "clickhouse.config.ts / clickhouse.config.py structure and defaults."
---

import { Tabs, TabItem } from '@astrojs/starlight/components';

`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

- `schema`: glob path to [schema files](/schema/dsl-reference/)
- `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.

## Example

<Tabs syncKey="lang">
  <TabItem label="TypeScript">
    ```ts
    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',
      },
    })
    ```
  </TabItem>
  <TabItem label="Python">
    ```python
    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"),
            },
        }
    )
    ```
  </TabItem>
</Tabs>

## 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`)

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:

<Tabs syncKey="lang">
  <TabItem label="TypeScript">
    ```ts
    clickhouse: {
      url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123',
      indexGranularity: 4096,
    },
    ```
  </TabItem>
  <TabItem label="Python">
    ```python
    "clickhouse": {
        "url": os.environ.get("CLICKHOUSE_URL", "http://localhost:8123"),
        "indexGranularity": 4096,
    },
    ```
  </TabItem>
</Tabs>

`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)

Instead of `schema` globs you can point chkit at one entry module:

```ts
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`)

For self-managed multi-node ClickHouse clusters, set `clickhouse.cluster` to the cluster name from your server's `remote_servers` config:

<Tabs syncKey="lang">
  <TabItem label="TypeScript">
    ```ts
    clickhouse: {
      url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123',
      password: process.env.CLICKHOUSE_PASSWORD ?? '',
      database: 'default',
      cluster: 'my_cluster',
    },
    ```
  </TabItem>
  <TabItem label="Python">
    ```python
    "clickhouse": {
        "url": os.environ.get("CLICKHOUSE_URL", "http://localhost:8123"),
        "password": os.environ.get("CLICKHOUSE_PASSWORD", ""),
        "database": "default",
        "cluster": "my_cluster",
    },
    ```
  </TabItem>
</Tabs>

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](/plugins/ingest/#journal-and-overlapping-runs) 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.

## 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`](/cli/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.

:::caution
A machine without a profile, such as a CI runner, does not load the ObsessionDB plugin unless the project config registers `obsessiondb()`. Its checks (Distributed tables, [submitted backfill jobs](/obsessiondb/backfills/#submitted-jobs-in-chkit-check)), its `Shared` engine rewrite and its service executor then do not run. Register `obsessiondb()` in the project config to get the same behavior everywhere.
:::

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

- [Schema DSL reference](/schema/dsl-reference/) — define the database objects loaded by the config
- [Schema plugins](/plugins/overview/) — register schema imports, row model generation, and beta SQL backfills
- [CLI reference](/cli/overview/) — run migrations and inspect a live database
- [CI/CD integration](/guides/ci-cd/) — configure validation and deployment by environment
