Skip to content
chkit Docs

Schema Overview

In chkit, your ClickHouse schema lives in TypeScript files. You declare tables, views, and materialized views as plain values using functions from @chkit/core, group them with schema(), and let chkit handle the rest — diffing them against the database, generating migration SQL, and applying it safely.

A typical schema file looks like this:

import { schema, table } from '@chkit/core'


const events = table({
  database: 'default',
  name: 'events',
  engine: 'MergeTree',
  columns: [
    { name: 'id', type: 'UInt64' },
    { name: 'source', type: 'String' },
    { name: 'ingested_at', type: 'DateTime64(3)', default: 'fn:now64(3)' },
  ],
  primaryKey: ['id'],
  orderBy: ['id'],
  partitionBy: 'toYYYYMM(ingested_at)',
})


export default schema(events)

chkit discovers schema files using the schema glob in your configuration, so you can split definitions across as many files as you like.

Concepts

Section titled “Concepts”
  • Definitions — tables, views, and materialized views are values created with table(), view(), and materializedView(). They describe the desired state of your database.
  • Schema groups — schema(...) collects definitions into a single export, but any exported definition is also discovered automatically.
  • Diff + plan — when you run chkit generate, chkit compares your schema to the live database (or the last applied state) and emits migration SQL.
  • Engines — MergeTree, ReplacingMergeTree, AggregatingMergeTree, and their Shared variants for ObsessionDB are all first-class.

Reference

Section titled “Reference”
Section titled “Related”