mcpField
C
clickhouse

clickhouse

github.com/dobroslavradosavljevicData & databases337 installsUpdated 1d ago
Repository

About clickhouse

A skill for ClickHouse analytics work in TypeScript and Node.js. It guides client usage, SQL, schema and ingestion choices, operations, and focused verification using official client documentation.

Key features

  1. 01Official TypeScript client guidance
  2. 02SQL and schema design
  3. 03Batch and async ingestion patterns
  4. 04Cloud and self-hosted operations
  5. 05Focused query and insert checks

Use cases

  1. 01Build a Node.js ClickHouse analytics app
  2. 02Design MergeTree tables and sort keys
  3. 03Ingest JSONEachRow data in batches
  4. 04Check queries, streams, and migrations

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/dobroslavradosavljevic/skills --skill clickhouse

After installing, type/clickhousein Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
client-ts.md
ingest-query-patterns.md
source-map.md
sql-engines-modeling.md
testing-migrations.md
types-cloud-ops.md
usage-guide.md

Details

From the project README

ClickHouse (TypeScript)

Use this skill for ClickHouse OLAP work driven from TypeScript/Node: official JS clients, SQL the app runs, table design, ingest, Cloud vs self-hosted, and ops the app can query.

Workflow

  1. Inspect the local surface:
    • Packages: @clickhouse/client (Node) and/or @clickhouse/client-web (browser/Workers). Snapshot 1.23.1 (1.24.0 is merged but unreleased). Node >=20. Client supports server 24.8+; current server lines are 26.9 stable and 26.8 / 26.3 LTS.
    • Connection: url (HTTPS Cloud :8443 vs local HTTP :8123), auth (password vs Cloud JWT access_token), database, TLS.
    • Schema: engine (MergeTree family), ORDER BY, PARTITION BY, MVs/projections.
    • Ingest path: insert() batches vs async_insert, streams, empty-array no-op.
  2. For day-to-day how-to, follow usage-guide.md first.
  3. Refresh docs when versions drift. Start from source-map.md.
  4. Route deeper detail:
  5. Prefer official @clickhouse/client over unscoped/clickhouse community packages. Never interpolate user input into SQL — use {name: Type} + query_params.
  6. Verify with focused query/insert smokes, part-count awareness for ingest, and consume/close every ResultSet.

Core Judgment

  • ClickHouse is columnar OLAP, not OLTP. Optimize for batched analytics, not high-QPS point lookups.
  • JS clients speak HTTP(S) only (not native TCP 9000).
  • Default to MergeTree + strong ORDER BY; partitions are for data management (TTL/DROP), not a substitute for the sort key.
  • Prefer batched insert({ format: 'JSONEachRow' }); tiny sync inserts → TOO_MANY_PARTS. Use async_insert=1 + wait_for_async_insert=1 when clients cannot batch.
  • Specialized engines (Replacing/Summing/Aggregating/Collapsing) need correctness SQL (FINAL or merge-aware aggregation) — merges are eventual.
  • Prefer insert-only / RMT / MVs over chatty ALTER UPDATE/DELETE mutations; lightweight DELETE FROM for row deletes; lightweight UPDATE … SET (beta, patch parts) only for small (<~10%) batched fixes.
  • Server 26.9+: the new analyzer is mandatory (enable_analyzer is obsolete) and default compression moved to ZSTD — retest old queries and pinned settings when upgrading.
  • Type traps: UInt64 → string in JSON; Decimal as string; Date as 'YYYY-MM-DD'; always set format: 'JSONEachRow' for object rows (insert default is JSONCompactEachRow).
  • Always consume or close() ResultSets — dangling streams cause ECONNRESET.
  • One shared client per process; close() / await using on shutdown. Sessions → max_open_connections: 1.
  • Cloud: HTTPS :8443, managed replication, no app-level Distributed(...) — use remoteSecure when needed.
  • Prefer bun / bunx in command examples.

Verification

Prefer repository-owned commands. For meaningful ClickHouse work, cover the relevant subset:

  • bun pm ls @clickhouse/client and Node ≥20.
  • Smoke: ping({ select: true }), DDL via command, insert + query with JSONEachRow.
  • Ingest: batch size / async_insert settings; watch for error 252 too many parts.
  • Streaming: full consume or close(); backpressure on insert streams.
  • Cloud: TLS URL, credentials/JWT, keep-alive idle TTL < server timeout (~2500 ms client default).
  • Schema: ORDER BY matches filter patterns; RMT/MV correctness under FINAL or merge aggs.
  • Tests: @testcontainers/clickhouse + getClientOptions() when integration tests exist.

Report which checks ran, which did not, and version/Cloud assumptions that remain.

Comments

Markdown supported