Pull Plugin

This document covers practical usage of the optional pull plugin.

What it does

• Connects to a live ClickHouse instance and introspects table metadata (columns, engines, indexes, projections, partitioning, TTL, settings).
• Introspects views and materialized views (including TO clause parsing).
• Generates a deterministic TypeScript schema file using @chkit/core builders.
• Supports filtering by database and dry-run previews.

How it fits your workflow

The plugin is designed for bootstrapping a chkit project from an existing ClickHouse deployment.

• chkit pull (alias for chkit plugin pull schema):
  • Connects to ClickHouse, introspects all schema objects, and writes a TypeScript schema file.
  • Generated file works directly with chkit generate and chkit check.
• Dry-run mode previews the output without writing to disk.

Plugin setup

In clickhouse.config.ts, register pull(...) from @chkit/plugin-pull.

import { defineConfig } from '@chkit/core'
import { pull } from '@chkit/plugin-pull'

export default defineConfig({
  schema: './src/db/schema/**/*.ts',
  plugins: [
    pull({
      outFile: './src/db/schema/pulled.ts',
      databases: ['analytics'],
      overwrite: false,
    }),
  ],
})

Options

• outFile (default: ./src/db/schema/pulled.ts) — Output file path for the generated schema.
• databases (default: [], meaning all) — Filter to specific databases.
• overwrite (default: false) — Allow overwriting an existing output file.
• introspect (default: built-in) — Custom introspection function (advanced).

Invalid option values fail fast at startup via plugin config validation.

Commands

• chkit plugin pull schema (also available as chkit pull)
  • Introspects live ClickHouse and writes a chkit schema file.

Useful flags:

• --out-file <path> — Override output file path.
• --database <name> — Filter to databases (comma-separated or repeated).
• --dryrun — Preview output without writing.
• --force / --overwrite — Overwrite existing output file.

Exit codes: 0 (success), 1 (runtime error), 2 (config error).

Generated output format

The plugin produces a TypeScript module that imports builders from @chkit/core and exports a default schema.

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

// Pulled from live ClickHouse metadata via chkit plugin pull schema

const app_events = table({
  database: "app",
  name: "events",
  engine: "MergeTree()",
  columns: [
    { name: "id", type: "UInt64" },
    { name: "received_at", type: "DateTime64(3)", default: "fn:now64(3)" },
  ],
  primaryKey: ["id"],
  orderBy: ["id"],
  partitionBy: "toYYYYMM(received_at)",
})

const app_events_view = view({
  database: "app",
  name: "events_view",
  as: "SELECT id FROM app.events",
})

const app_events_mv = materializedView({
  database: "app",
  name: "events_mv",
  to: { database: "app", name: "events_rollup" },
  as: "SELECT id, count() AS c FROM app.events GROUP BY id",
})

export default schema(app_events, app_events_view, app_events_mv)

Tables may also include uniqueKey, ttl, settings, indexes, and projections when present in the source metadata.

Current limits

• Materialized views without a TO clause are skipped.
• Requires a live ClickHouse connection.