From clickhouse-best-practices
Guides deployment of ClickHouse to ClickHouse Cloud using clickhousectl: account signup, CLI authentication (OAuth/API key), service creation, schema migration, app connection. For production or local-to-cloud migration.
npx claudepluginhub clickhouse/agent-skills --plugin clickhouse-best-practicesThis skill uses the workspace's default tool permissions.
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.
Conducts multi-round deep research on GitHub repos via API and web searches, generating markdown reports with executive summaries, timelines, metrics, and Mermaid diagrams.
Dynamically discovers and combines enabled skills into cohesive, unexpected delightful experiences like interactive HTML or themed artifacts. Activates on 'surprise me', inspiration, or boredom cues.
Generates images from structured JSON prompts via Python script execution. Supports reference images and aspect ratios for characters, scenes, products, visuals.
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.
Use this skill when the user wants to:
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.
First, ensure clickhousectl is installed. Check with:
which clickhousectl
If not found, install it:
curl -fsSL https://clickhouse.com/cli | sh
Now authenticate. There are two options — choose based on the situation:
Important: OAuth login is read-only. Browser login (Option A) grants read-only access — you can list organizations, services, and query existing services, but you cannot create, modify, or delete services. Any destructive or mutating cloud operation (service creation, deletion, scaling, etc.) requires API key authentication (Option B). If this workflow involves creating or changing cloud resources, you must use Option B.
Use this when a human is available to open a browser and you only need to inspect existing cloud resources (list orgs, list services, query data). It uses OAuth device flow — no API keys needed.
Instruct the user to run:
clickhousectl cloud login
This prints a URL and a code. The user opens the URL in their browser, confirms the code, and logs in with their ClickHouse Cloud account. The CLI automatically receives credentials once the browser flow completes.
This is sufficient for steps that only read data (e.g., cloud org list, cloud service get, cloud service client). For any step that creates or modifies resources, switch to API key auth.
Use this option when creating, modifying, or deleting cloud resources (e.g., cloud service create, cloud service delete). Also use this for headless/CI environments where no browser is available. Both --api-key and --api-secret are required — if the user provides one without the other, tell them both are needed.
clickhousectl cloud login --api-key <key> --api-secret <secret>
If the user doesn't have API keys yet, guide them to create 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., "cli") and select the Admin role
- Click Generate API Key
- Copy both the Key ID and the Key Secret — the secret is only shown once
To verify authentication works:
clickhousectl cloud org list
This should return the user's organization.
Requires API key auth. Service creation is a mutating operation. If you authenticated with browser login (Option A) in Step 2, you must re-authenticate with API key auth (Option B) before proceeding.
Create a new ClickHouse Cloud service:
clickhousectl cloud service create --name <service-name>
The output includes the service ID and default user password — note it for subsequent commands.
Wait for the service to be ready. After creation, the service takes a moment to provision. Check its status:
clickhousectl cloud service get <service-id>
You can grep the "state" field to see if it is "running".
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 client to run queries against the cloud service — it looks up the endpoint, port, and TLS settings automatically. You just need the service name (or --id) and the password from step 3.
Read the local schema files from clickhouse/tables/ and apply each one to the cloud service:
clickhousectl cloud service client --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 client --name <service-name> \
--queries-file clickhouse/materialized_views/<view>.sql
The --user flag defaults to default. If the user has a different database user, pass --user <username>.
Connect to the cloud service and confirm tables exist:
clickhousectl cloud service client --name <service-name> --query "SHOW TABLES"
Run a test query to confirm the schema is correct:
clickhousectl cloud service client --name <service-name> --query "DESCRIBE TABLE <table-name>"
Retrieve the service endpoint for the user's application config:
clickhousectl cloud service get <service-id>
Provide the user with the connection details:
get output8443 for HTTPS / 9440 for native TLSdefaultExample connection strings (adapt to the user's language/framework):
Python (clickhouse-connect):
import clickhouse_connect
client = clickhouse_connect.get_client(
host='<cloud-host>',
port=8443,
username='default',
password='<password>',
secure=True
)
Node.js (@clickhouse/client):
import { createClient } from '@clickhouse/client'
const client = createClient({
url: 'https://<cloud-host>:8443',
username: 'default',
password: '<password>',
})
Go (clickhouse-go):
conn, err := clickhouse.Open(&clickhouse.Options{
Addr: []string{"<cloud-host>:9440"},
Auth: clickhouse.Auth{
Username: "default",
Password: "<password>",
},
TLS: &tls.Config{},
})
Suggest the user store the password in an environment variable or secrets manager rather than hardcoding it.
Suggest the user should not use the default user in production. A user should be created just for their app.