clickhouse-best-practices

ClickHouse Agent Skills

The official Agent Skills for ClickHouse. These skills help LLMs and agents to adopt best practices when working with ClickHouse and chdb (in-process ClickHouse for Python).

You can use these skills with open-source ClickHouse and managed ClickHouse Cloud. Try ClickHouse Cloud with $300 in free credits.

Installation

npx

npx skills add clickhouse/agent-skills

The CLI auto-detects installed agents and prompts you to select where to install.

clickhousectl

Use the ClickHouse CLI clickhousectl to install the agent skills:

clickhousectl skills

What is this?

Agent Skills are packaged instructions that extend AI coding agents (Claude Code, Cursor, Copilot, etc.) with domain-specific expertise. This repository provides skills for ClickHouse databases and chdb — covering schema design, query optimization, data ingestion patterns, and in-process analytics with Python.

When an agent loads these skills, it gains knowledge of ClickHouse best practices and chdb APIs, and can apply them while helping you design tables, write queries, analyze data, or troubleshoot performance issues.

Skills follow the open specification at agentskills.io.

Available Skills

ClickHouse Best Practices

28 rules covering schema design, query optimization, and data ingestion—prioritized by impact.

Category	Rules	Impact
Primary Key Selection	4	CRITICAL
Data Type Selection	5	CRITICAL
JOIN Optimization	5	CRITICAL
Insert Batching	1	CRITICAL
Mutation Avoidance	2	CRITICAL
Partitioning Strategy	4	HIGH
Skipping Indices	1	HIGH
Materialized Views	2	HIGH
Async Inserts	2	HIGH
OPTIMIZE Avoidance	1	HIGH
JSON Usage	1	MEDIUM

Location: skills/clickhouse-best-practices/

For humans: Read SKILL.md for an overview, or AGENTS.md for the complete compiled guide.

For agents: The skill activates automatically when you work with ClickHouse—creating tables, writing queries, or designing data pipelines.

ClickHouse Architecture Advisor

5 decision frameworks covering workload-aware architecture decisions for real-time ClickHouse deployments.

Decision Area	Impact
Ingestion Strategy	CRITICAL
Join & Enrichment Patterns	CRITICAL
Late-Arriving Data & Upserts	CRITICAL
Time-Series Partitioning	HIGH
Real-Time Pre-Aggregation	HIGH

Complements clickhouse-best-practices by answering when, why, and how — not just what. All recommendations are explicitly classified as official, derived, or field guidance.

Location: skills/clickhouse-architecture-advisor/

For humans: Read SKILL.md for an overview, or AGENTS.md for the compiled guide.

For agents: The skill activates during architecture design sessions — when choosing ingestion patterns, designing time-series schemas, selecting enrichment strategies, or handling mutable state.

ClickHouse JS Node Troubleshooting

Troubleshooting guide for the ClickHouse Node.js client (@clickhouse/client). Covers common failure modes including socket hang-up / ECONNRESET, Keep-Alive misconfiguration, data type mismatches, read-only user restrictions, proxy / pathname URL confusion, TLS certificate errors, compression issues, logging setup, and query parameter interpolation.

Location: skills/clickhouse-js-node-troubleshooting/

For agents: The skill activates when users report errors, unexpected behavior, or configuration questions involving the ClickHouse Node.js client — including vague symptoms like "my inserts keep failing" or "connection drops randomly" in a Node.js context. Not used for browser/Web client issues.

chdb DataStore

Pandas-compatible API for chdb — drop-in pandas replacement backed by ClickHouse. Write import chdb.datastore as pd and use the same pandas API, 10-100x faster. Supports 16+ data sources (MySQL, PostgreSQL, S3, MongoDB, Iceberg, Delta Lake, etc.) with cross-source joins.

Location: skills/chdb-datastore/

For agents: The skill activates when you analyze data with pandas-style syntax, speed up slow pandas code, query remote databases as DataFrames, or join data across different sources.

chdb SQL