infra-clickhouse
clickhouse/agent-skills
Set up and manage ClickHouse locally for development or deploy to ClickHouse Cloud for production.
What is infra-clickhouse?
Manages ClickHouse using the clickhousectl CLI in two environments: local development on your machine, and managed ClickHouse Cloud services for production. Use this when building applications with ClickHouse, setting up a dev environment, creating tables, deploying to production, or migrating from local to cloud.
- Install and run a local ClickHouse server for development
- Create and manage ClickHouse Cloud services for production
- Handle authentication and service creation in the cloud
- Perform schema migration and application connection setup
- Output machine-readable JSON for all commands
- Support both local and cloud workflows with clear routing
How to install infra-clickhouse
npx skills add https://github.com/clickhouse/agent-skills --skill infra-clickhouse- clickhousectl CLI installed (install via: curl -fsSL https://clickhouse.com/cli | sh)
- For cloud workflows: ClickHouse Cloud account and authentication credentials
How to use infra-clickhouse
- 1.Verify clickhousectl is installed by running: which clickhousectl
- 2.For local development: follow ref/local.md to install and run ClickHouse on your machine
- 3.For cloud deployment: follow ref/cloud.md to authenticate and create managed services
- 4.Create tables and schemas using clickhousectl commands
- 5.Use --json flag on any command for machine-readable output
- 6.When ready to go to production, migrate from local to cloud using the provided workflows
Use cases
- Build and prototype a ClickHouse application locally without cloud costs
- Set up a local development environment with tables and queries
- Deploy a local ClickHouse setup to managed ClickHouse Cloud for production
- Operate existing cloud services including schema updates and user management
- Migrate from local development to production cloud infrastructure
- Developers building applications with ClickHouse
- DevOps engineers managing ClickHouse infrastructure
- Teams moving from local development to production cloud deployments
- Data engineers setting up analytics or OLAP systems
infra-clickhouse FAQ
No. For local development, you only need clickhousectl installed. Cloud account and credentials are only required if you want to deploy to ClickHouse Cloud for production.
Yes. Start with ref/local.md for local development, and it points to ref/cloud.md when you're ready to migrate to production.
Exit codes follow gh conventions: 0 for success, 1 for error, 2 for cancelled, and 4 for authentication required.
Add the --json flag to any clickhousectl command for JSON-formatted output.
Use the clickhouse-best-practices skill for guidance on ORDER BY selection, data types, and partitioning.
Full instructions (SKILL.md)
Source of truth, from clickhouse/agent-skills.
name: infra-clickhouse 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. license: Apache-2.0 metadata: author: ClickHouse Inc version: "0.3.0"
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.
Related skills
More from clickhouse/agent-skills and the wider catalog.
infra-postgres
Set up and manage Postgres locally or in ClickHouse Cloud using clickhousectl.
chdb-datastore
Drop-in pandas replacement with ClickHouse speed for filtering, grouping, joining, and cross-source data operations.
chdb-sql
Run ClickHouse SQL on local files, URLs, S3, and remote databases without a server.
clickhouse-architecture-advisor
Workload-aware ClickHouse architecture decisioning with provenance-labeled recommendations.
create-pull-request
Create a GitHub pull request following project conventions. Use when the user asks to create a PR, submit changes for review, or open a pull request. Handles commit analysis, branch management, PR template usage, and PR creation using the gh CLI tool.
cline-sdk
Comprehensive SDK for building AI agents with custom tools, plugins, LLM providers, and multi-agent orchestration.