clickhousectl-cloud-deploy
Use when a user wants to deploy ClickHouse to the cloud, go to production, use ClickHouse Cloud, host a managed ClickHouse service, or migrate from a local ClickHouse setup to ClickHouse Cloud.
- Installs
- 4.3K
- Last 24h
- —
- Trending rank
- —
- Security
- Fail
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/clickhouse/agent-skills --skill clickhousectl-cloud-deploy- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads clickhousectl-cloud-deploy automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
Deploy to ClickHouse Cloud
This skill walks through deploying to ClickHouse Cloud using clickhousectl. It covers account setup, CLI authentication, service creation, schema migration, and connecting your application. Follow these steps in order.
When to Apply
Use this skill when the user wants to:
- Deploy their ClickHouse application to production
- Host ClickHouse as a managed cloud service
- Migrate from a local ClickHouse setup to ClickHouse Cloud
- Create a ClickHouse Cloud service
- Set up ClickHouse Cloud for the first time
Step 1: Sign up for ClickHouse Cloud
Before using any cloud commands, the user needs a ClickHouse Cloud account.
Ask the user: "Do you already have a ClickHouse Cloud account?"
If they do not have an account, explain:
ClickHouse Cloud is a fully managed service that runs ClickHouse for you — no infrastructure to maintain, automatic scaling, backups, and upgrades included. There's a free trial so you can get started without a credit card.
To create an account, go to: https://clickhouse.cloud
Sign up with your email, Google, or GitHub account. Once you're in the console, let me know and we'll continue with the next step.
Wait for the user to confirm they have signed up or already have an account before proceeding.
Step 2: Authenticate the CLI
First, ensure clickhousectl is installed. Check with:
which clickhousectl
If not found, install it:
curl -fsSL https://clickhouse.com/cli | sh
Authenticate clickhousectl with a ClickHouse Cloud API key.
Create an API key
Guide the user through creating one in the ClickHouse Cloud console:
- Click the gear icon (Settings) in the left sidebar
- Go to API Keys
- Click Create API Key
- Give it a name (e.g., "clickhousectl")
- Select the Admin role for the key. Admin is needed because
cloud service queryauto-provisions a per-service query endpoint API key on first use, which requires permission to create keys. Developer-scoped keys can manage services but may not be able to complete the auto-provisioning step.- Click Generate API Key
- Copy both the Key ID and the Key Secret — the secret is only shown once
Authenticate clickhousectl with the key
Ask the user to open a new terminal tab in the same working directory and run the login command there with their Key ID and Secret — this keeps the secret out of the chat session. Tell them to come back and let you know once it's done.
clickhousectl cloud login --api-key <key> --api-secret <secret>
Both --api-key and --api-secret are required — if the user only has one, tell them both are needed.
To verify authentication works:
clickhousectl cloud org list
This should return the user's organization.
Step 3: Create a cloud service
Create a new ClickHouse Cloud service:
clickhousectl cloud service create --name <service-name>
From the output, add the HTTPS host and port to .env as CLICKHOUSE_HOST and CLICKHOUSE_PORT. Make sure .env is gitignored.
Then poll until the service state is running:
clickhousectl cloud service get <service-id>
Step 4: Migrate schemas
If the user has local table definitions (e.g., from using the clickhousectl-local-dev skill), migrate them to the cloud service.
Use cloud service query to run SQL against the cloud service over HTTP. Just pass the service name (or --id).
Read the local schema files from clickhouse/tables/ and apply each one to the cloud service:
clickhousectl cloud service query --name <service-name> \
--queries-file clickhouse/tables/<table>.sql
Apply them in dependency order — tables referenced by materialized views should be created first.
Also apply materialized views if they exist:
clickhousectl cloud service query --name <service-name> \
--queries-file clickhouse/materialized_views/<view>.sql
To target a specific database, pass --database <name>.
Step 5: Verify the deployment
Connect to the cloud service and confirm tables exist:
clickhousectl cloud service query --name <service-name> --query "SHOW TABLES"
Run a test query to confirm the schema is correct:
clickhousectl cloud service query --name <service-name> --query "DESCRIBE TABLE <table-name>"
Step 6: Create a dedicated user for the application
The default user has full admin rights and should not be used by the application. Create a dedicated user scoped to the schema deployed in Step 4.
Generate a strong random password and append the credentials to .env before creating the user, so the password is persisted even if a subsequent step fails:
PASSWORD=$(openssl rand -base64 32)
echo "CLICKHOUSE_USER=app_user" >> .env
echo "CLICKHOUSE_PASSWORD=$PASSWORD" >> .env
Then create the user and grant the minimum permissions the app needs. Replace <database> with the database the schema lives in (often default):
clickhousectl cloud service query --name <service-name> --query \
"CREATE USER app_user IDENTIFIED BY '$PASSWORD'"
clickhousectl cloud service query --name <service-name> --query \
"GRANT SELECT, INSERT ON <database>.* TO app_user"
Adjust the grants to fit the app:
- Read-only app → drop
INSERT - Needs to create/drop its own tables → also grant
CREATE TABLE, DROP TABLEon the database (but prefer running migrations as the admin user instead) - Multiple databases → repeat the
GRANTper database, or scope per table withON <database>.<table>
Verify the user exists and has the expected grants:
clickhousectl cloud service query --name <service-name> --query "SHOW GRANTS FOR app_user"
ClickHouse cannot reveal the password later, so if .env is lost, the user must reset the password via ALTER USER app_user IDENTIFIED BY '<new>'.
The application can now use the credentials in .env to connect to ClickHouse Cloud.
FAQ
What does the clickhousectl-cloud-deploy skill do?
Use when a user wants to deploy ClickHouse to the cloud, go to production, use ClickHouse Cloud, host a managed ClickHouse service, or migrate from a local ClickHouse setup to ClickHouse Cloud.
How do I install clickhousectl-cloud-deploy?
Run npx skills add https://github.com/clickhouse/agent-skills --skill clickhousectl-cloud-deploy in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/clickhousectl-cloud-deploy/ (personal) or .claude/skills/clickhousectl-cloud-deploy/ (project).
Which AI agents can use clickhousectl-cloud-deploy?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is clickhousectl-cloud-deploy safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk flagged risks; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains clickhousectl-cloud-deploy?
It is published by clickhouse in clickhouse/agent-skills, and it is an official skill from the maker of the technology it covers. It has 4,276 recorded installs.
More from clickhouse/agent-skills
clickhouse-best-practices
clickhouse/agent-skills
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.
clickhouse-architecture-advisor
clickhouse/agent-skills
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.
chdb-sql
clickhouse/agent-skills
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.
chdb-datastore
clickhouse/agent-skills
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.
clickhouse-js-node-troubleshooting
clickhouse/agent-skills
Troubleshoot and resolve common issues with the ClickHouse Node.js client (@clickhouse/client). Use this skill whenever a user reports errors, unexpected behavior, or configuration questions involving the Node.js client specifically — including socket hang-up errors, Keep-Alive problems, stream handling issues, data type mismatches, read-only user restrictions, proxy/TLS setup problems, or long-running query timeouts. Trigger even when the user hasn't precisely named the issue; vague symptoms like "my inserts keep failing" or "connection drops randomly" in a Node.js context are strong signals to use this skill. Do NOT use for browser/Web client issues.
clickhouse-js-node-coding
clickhouse/agent-skills
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.
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.