infra-clickhouse

Gets ClickHouse, a fast database for analytics, running either on your own computer for development or as a managed ClickHouse Cloud service for production, all through one command-line tool.

WHEN TO USE

SCOPE

USE FOR

Run ClickHouse locally to build or prototype an app, with no cloud account needed.
Create a paid, managed ClickHouse Cloud service when the app is ready for production.
Manage schemas, users and queries on a ClickHouse Cloud service you already have.
Start locally now and follow the same tool's path to production later.

NOT FOR

Running Postgres; the sibling infra-postgres skill covers that.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (4)

ClickHouse with clickhousectl

clickhousectl manages ClickHouse in two environments:

Local — ClickHouse installed and running on the user's machine, for development.
Cloud — managed ClickHouse Cloud services, for production: fully managed, automatic scaling, backups, and upgrades.

This file routes to the right reference. The step-by-step workflows live in ref/local.md and ref/cloud.md — read the one that matches the user's situation before running commands.

Which reference to use

The user wants to...	Read
Build an app with ClickHouse, develop or prototype locally, no cloud account needed	ref/local.md
Go to production, host a managed ClickHouse, or use ClickHouse Cloud explicitly	ref/cloud.md
Operate an existing cloud service (schemas, users, queries against it)	ref/cloud.md
Develop locally now, ship to production later	Start with ref/local.md; it points to ref/cloud.md when it's time to go to prod

If it's genuinely ambiguous (e.g. "set up ClickHouse for my app"), default to local for development tasks and ask before creating anything in the cloud — cloud services cost money.

Prerequisites (both workflows)

Check that clickhousectl is installed:

which clickhousectl

If not found, install it:

curl -fsSL https://clickhouse.com/cli | sh

This installs to ~/.local/bin/clickhousectl (with a chctl alias). If the command is still not found, suggest export PATH="$HOME/.local/bin:$PATH" or a new terminal.

All commands accept --json for machine-readable output. Exit codes follow gh conventions: 0 success, 1 error, 2 cancelled, 4 auth required.

When designing schemas, consult the clickhouse-best-practices skill for ORDER BY selection, data types, and partitioning.
For Postgres (local development or managed ClickHouse Cloud Postgres), use the infra-postgres skill.

This skill ships inside the ClickHouse Agent Skills plugin.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add clickhouse/agent-skills --skill "infra-clickhouse" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

View on GitHub

Same repository

chdb-datastore
Use when the user has tabular data (pandas DataFrame, parquet, csv, Arrow, json) and wants to filter, group, aggregate, join, or speed up slow pandas. Provides chDB DataStore — same pandas API, ClickHouse engine underneath. Also handles reading from S3, MySQL, PostgreSQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake as DataFrames and joining across sources. TRIGGER when: user mentions DataFrame, parquet, csv, "fast pandas", "speed up pandas", or cross-source DataFrame joins; user imports chdb.datastore or from datastore import DataStore. SKIP this skill for raw SQL syntax (use chdb-sql instead), ClickHouse server administration, or non-Python DataStore API work.Read full description
chdb-sql
Use when the user wants to run SQL — especially analytical SQL — on local files (parquet/csv/json), URLs, S3 paths, or remote databases (Postgres, MySQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake) without setting up a server. Provides chDB — embedded ClickHouse SQL in Python with 1000+ functions, Session for stateful multi-step pipelines, parametrized queries, and cross-source joins via s3(), mysql(), postgresql(), iceberg(), deltaLake(), remoteSecure() table functions. TRIGGER when: user wants SQL on parquet/csv/files or across remote analytical sources; uses ClickHouse SQL features (window functions, windowFunnel, geoToH3, JSON path ops, Session, parametrized queries); imports chdb or calls chdb.query(). SKIP this skill for pandas-style DataFrame method-chaining (use chdb-datastore instead) or ClickHouse server administration.Read full description
clickhouse-architecture-advisor
MUST USE when designing ClickHouse architectures, selecting between ingestion or modeling patterns, or translating best practices into workload-specific system designs. Complements clickhouse-best-practices with decision frameworks and explicit provenance labels.Read full description
clickhouse-best-practices
MUST USE when reviewing ClickHouse schemas, queries, or configurations. Contains 31 rules that MUST be checked before providing recommendations. Always read relevant rule files and cite specific rules in responses.Read full description
clickhouse-js-node-coding
Write idiomatic application code with the ClickHouse Node.js client (@clickhouse/client). Use this skill whenever a user is *building* against the Node.js client — configuring the client, pinging, inserting rows in JSON or raw formats, selecting and parsing results, binding query parameters, managing sessions and temporary tables, working with data types or customizing JSON parsing. Do NOT use for browser/Web client code.Read full description
clickhouse-js-node-rowbinary
Generate TypeScript/JavaScript code that reads/decodes AND writes/encodes ClickHouse RowBinary streams for the ClickHouse HTTP server. Use this skill whenever a user wants to parse or produce RowBinary, RowBinaryWithNames, or RowBinaryWithNamesAndTypes. Node.js only, doesn't cover browsers.Read full description

ClickHouse with clickhousectl

Which reference to use

Prerequisites (both workflows)

Related

Local tool required

infra-clickhouse

ClickHouse with clickhousectl

Which reference to use

Prerequisites (both workflows)

Related

Local tool required

More skills

MCP keyword matches