Description
Sets up and manages ClickHouse using the clickhousectl CLI — installs and runs a local ClickHouse server for development, and creates managed ClickHouse Cloud services for production (authentication, service creation, schema migration, application connection). Use when the user wants to build an application with ClickHouse, set up a local ClickHouse dev environment, create tables and start querying, deploy ClickHouse to production or ClickHouse Cloud, or migrate from a local setup to the cloud.
SKILL.md
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.
Related
- When designing schemas, consult the
clickhouse-best-practicesskill for ORDER BY selection, data types, and partitioning. - For Postgres (local development or managed ClickHouse Cloud Postgres), use the
infra-postgresskill.
More skills from the agent-skills repository
View all 8 skillschdb-datastore
accelerate pandas with chDB datastore
Apr 15ClickHouseData AnalysisData EngineeringPerformance +1chdb-sql
run ClickHouse SQL queries in Python
Apr 15ClickHouseData AnalysisData EngineeringPython +1clickhouse-architecture-advisor
advise on ClickHouse architectures
Apr 15ArchitectureClickHouseData EngineeringDatabase +1clickhouse-best-practices
review ClickHouse schemas and queries
Apr 6ClickHouseCode ReviewDatabasePerformance +1clickhouse-js-node-rowbinary
encode and decode ClickHouse RowBinary streams
Jul 1API DevelopmentClickHouseDatabaseJavaScript +1clickhouse-managed-postgres-rca
diagnose performance issues on ClickHouse-managed Postgres
Jun 8ClickHouseDebuggingMonitoringObservability +3
More from ClickHouse
View publisherinfra-postgres
manage PostgreSQL database instances
agent-skills
Jul 28DatabaseDeploymentDockerInfrastructure +1clickhouse-js-node-coding
build Node.js applications with ClickHouse
clickhouse-js
May 6BackendClickHouseDatabaseNode.jsclickhouse-js-node-troubleshooting
troubleshoot ClickHouse Node.js client
clickhouse-js
Apr 14ClickHouseDebuggingNode.jsTypeScriptclickstack-otel-collector
set up OpenTelemetry collector for ClickHouse
clickhouse-docs
Jun 11ClickHouseLogsMetricsObservability +1setup
set up ClickHouse MCP server connections
clickhouse-claude-code-plugin
Apr 19ClickHouseDatabaseLocal DevelopmentMCP