ClickHouse Cloud

ClickHouse Cloud

This connector manages a ClickHouse Cloud organization through the Cloud control-plane API (https://api.clickhouse.cloud/v1): organizations, services (start, stop, scaling, IP access, metrics), backups, ClickPipes, usage costs and credits, audit activities, notifications, members, invitations, roles and API keys. It does not run SQL: for queries install the ClickHouse connector, which talks to a service's HTTPS interface.

Setup (3 minutes)

1. In the ClickHouse Cloud console open Organization, API keys and click New API key.
2. Give it a name, the role it needs (a read-only or developer role for the reads; admin or a custom role with service manage permissions for start, stop, scaling and updates), an expiry, and optionally an IP allow list.
3. Copy the Key ID into CLICKHOUSE_CLOUD_KEY_ID and the Key secret into CLICKHOUSE_CLOUD_KEY_SECRET. The secret is shown only once. The API takes them as HTTP Basic auth (key id as user, secret as password).
4. Run clickhouse_cloud_list_organizations to check the key.

Workflow

• Start here: clickhouse_cloud_list_organizations gives the organization_id every other tool needs; clickhouse_cloud_whoami shows the key and its roles; clickhouse_cloud_get_organization the details.
• Services: clickhouse_cloud_list_services (filter by tags), clickhouse_cloud_get_service, clickhouse_cloud_get_service_settings, clickhouse_cloud_get_service_metrics (Prometheus text).
• Operate a service: clickhouse_cloud_change_service_state (start, stop, awake), clickhouse_cloud_update_service (name, release channel, IP access list, tags), clickhouse_cloud_update_replica_scaling (memory per replica, replicas, idle scaling). Confirm a stop with the user: queries fail until the service is started again.
• Backups: clickhouse_cloud_list_backups, clickhouse_cloud_get_backup, clickhouse_cloud_get_backup_configuration.
• Ingestion: clickhouse_cloud_list_clickpipes, clickhouse_cloud_get_clickpipe, clickhouse_cloud_change_clickpipe_state (start, stop, resync; a resync copies the source again, so confirm it first).
• Cost and health: clickhouse_cloud_get_usage_cost (per day and entity), clickhouse_cloud_get_credit_balances, clickhouse_cloud_list_notifications, clickhouse_cloud_list_quotas.
• People and access: clickhouse_cloud_list_members, clickhouse_cloud_list_invitations, clickhouse_cloud_list_roles, clickhouse_cloud_create_invitation, clickhouse_cloud_list_api_keys, and clickhouse_cloud_list_activities for the audit log.

Reading the answers: every answer is {status, requestId, result}; the data is in result. Ids are UUIDs. Times are ISO 8601 in UTC. Costs are in ClickHouse Credits (CHC): grandTotalCHC for the period and totalCHC per record. Memory is in GB, backup size in bytes, durations in seconds. Service state moves through starting or stopping before running or stopped; idle means scaled to zero and wakes on the next query.

Paging: clickhouse_cloud_list_organizations, clickhouse_cloud_list_api_keys and clickhouse_cloud_list_notifications return nextCursor when more items exist: pass it as cursor, stop when it is missing. The other lists return everything at once.

Limits and errors: the usage cost report covers at most 31 days per call. The API is rate limited per key; on 429 wait a few seconds before retrying. 401 means a wrong key id or secret (or an expired key), 403 a key without the permission the call needs (the role decides: billing, ClickPipes and service management are separate permissions) or a caller IP outside the key's allow list, 404 a wrong organization or service id, 429 the rate limit.