ClickHouse schemas.
Managed in code.

01 / Define

Keep the schema in code.

Define ClickHouse tables, views, materialized views, and dictionaries. Import definitions from an existing database.

Explore the schema DSL ↗

02 / Migrate

Review every change.

Generate SQL from schema changes. Commit migrations alongside the definitions, preview pending changes, and apply them explicitly.

Follow the migration workflow ↗

03 / Verify

Detect schema drift.

Check pending migrations, migration checksums, and differences between the declared schema and the live database. Run the same checks in CI.

Add schema checks to CI ↗

Schema management in practice

From a definition to a reviewed migration

A schema change starts in code and produces SQL to review. This walkthrough uses TypeScript; the Python port (alpha) provides the schema and migration workflow in Python.

Install chkit and @chkit/core, then run chkit init to create the project configuration. The first schema tutorial covers installation, the ClickHouse connection, and each step below.

1. Define

Declare the table

Export a table from the configured schema files. Columns, engine, and ordering describe the intended ClickHouse schema.

src/db/schema/events.ts

import { table } from '@chkit/core'

export const events = table({
  database: 'default',
  name: 'events',
  columns: [
    { name: 'id', type: 'UInt64' },
    { name: 'event_type', type: 'String' },
    { name: 'created_at', type: 'DateTime' },
  ],
  engine: 'MergeTree()',
  primaryKey: ['created_at', 'id'],
  orderBy: ['created_at', 'id'],
})

The schema reference covers engines, keys, indexes, views, and dictionaries.

2. Review & migrate

Generate SQL and review the plan

Generate a migration from the definitions, inspect its SQL in chkit/migrations/, and preview the pending migrations before applying.

Terminal

bunx chkit generate --name create-events
bunx chkit migrate --json

# Apply after reviewing the generated SQL and plan.
bunx chkit migrate --apply

Commit the definitions, migration SQL, and metadata together. chkit records applied migrations in ClickHouse. See the migration workflow for review, destructive changes, and deployment.

3. Evolve

Add a column through another migration

Replace the table definition to add user_id with a default for existing rows.

src/db/schema/events.ts

import { table } from '@chkit/core'

export const events = table({
  database: 'default',
  name: 'events',
  columns: [
    { name: 'id', type: 'UInt64' },
    { name: 'event_type', type: 'String' },
    { name: 'created_at', type: 'DateTime' },
    { name: 'user_id', type: 'UInt64', default: 0 },
  ],
  engine: 'MergeTree()',
  primaryKey: ['created_at', 'id'],
  orderBy: ['created_at', 'id'],
})

bunx chkit generate --name add-user-id
bunx chkit migrate --json
bunx chkit migrate --apply

chkit compares the updated definition with the last snapshot and generates an ADD COLUMN migration. Review the SQL before applying it.

4. Verify

Check migration state and drift

Check whether migrations are pending, checksums have changed, or the live schema differs from the declared schema.

Terminal / CI

bunx chkit status
bunx chkit drift
bunx chkit check

Use chkit check as the CI gate. Its exit code reports whether the schema and migration state satisfy the checks.

Schema tools

Fit the existing project.

Import a live schema, generate application types, or backfill stored data after a schema change. Add the plugins the project needs.

• Import an existing databasePull live schema into local definitions.
• Keep application types alignedGenerate TypeScript row types and Zod schemas.
• Backfill stored data (beta)Run SQL data migrations with checkpoints.
• Work with a coding agentInstall the schema management skill.

Compatible with

• 

  ObsessionDB

• 

  ClickHouse Cloud

• 

  Altinity

• 

  Self-hosted ClickHouse

• 

  …and any other ClickHouse

Manage your ClickHouse schema.

Create your first migration →Use Python (alpha) →

Also in development: chkit Sync (beta)

We’re also building chkit Sync to sync business app data into ClickHouse. It has its own setup, integration, and operations guides in the Sync documentation →.