clickhouse-cloud-service-setup

Fetch ClickHouse Cloud service details from API (organization ID, service endpoints, configuration). Use when setting up new ClickHouse Cloud services, discovering endpoints, or validating service metadata for gapless-crypto-clickhouse project.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates the discovery and configuration of ClickHouse Cloud services via REST API. It streamlines the technical workflow of fetching organization IDs, resolving service endpoints (HTTPS/Native), and validating metadata like memory tiers and IP access. By integrating with Doppler for secret management, it ensures a secure and error-free setup for database infrastructure, specifically optimized for the gapless-crypto-clickhouse project environment.

Use Cases

  • 1. Automated Service Provisioning: Rapidly fetch and store connection details for new ClickHouse Cloud instances to accelerate development environment setup.
  • 2. Infrastructure Secret Management: Automatically sync ClickHouse hostnames, ports, and organization IDs into Doppler to maintain a single source of truth for credentials.
  • 3. Connectivity Troubleshooting: Verify service states and endpoint availability (Port 8443/9440) when connection issues arise in the data pipeline.
  • 4. Configuration Auditing: Validate service settings such as idle scaling timeouts and regional placement to ensure compliance with project infrastructure standards.
nameclickhouse-cloud-service-setup
descriptionFetch ClickHouse Cloud service details from API (organization ID, service endpoints, configuration). Use when setting up new ClickHouse Cloud services, discovering endpoints, or validating service metadata for gapless-crypto-clickhouse project.

ClickHouse Cloud Service Setup

Automate service metadata discovery via ClickHouse Cloud API for gapless-crypto-clickhouse project.

Purpose

Fetch and store ClickHouse Cloud service details using the ClickHouse Cloud REST API. This skill guides the workflow of:

  1. Authenticating with ClickHouse Cloud API
  2. Resolving Organization ID
  3. Fetching service metadata
  4. Extracting connection endpoints
  5. Storing configuration in Doppler

When to Use

Use this skill when:

  • Initial service provisioning: Setting up a new ClickHouse Cloud service
  • Service discovery: Finding endpoints and configuration for existing service
  • Endpoint resolution: Determining HTTPS (port 8443) or Native (port 9440) endpoints
  • Configuration validation: Verifying idle scaling, memory tier, IP access settings

Triggers: User mentions "ClickHouse Cloud service", "fetch service details", "organization ID", "service endpoints"

Prerequisites

Required Credentials (stored in Doppler aws-credentials/prd project):

  • CLICKHOUSE_CLOUD_KEY_ID: API Key ID (format: xnIdJM3n42LDImsZ9zzg)
  • CLICKHOUSE_CLOUD_KEY_SECRET: API Key Secret (secured in Doppler)

Service Context:

  • Service ID: a3163f31-21f4-4e22-844e-ef3fbc26ace2 (gapless-crypto-clickhouse service)
  • Organization: "TE's Organization"

Workflow

Step 1: Authenticate with ClickHouse Cloud API

# Retrieve API credentials from Doppler
KEY_ID=$(doppler secrets get CLICKHOUSE_CLOUD_KEY_ID --project aws-credentials --config prd --plain)
KEY_SECRET=$(doppler secrets get CLICKHOUSE_CLOUD_KEY_SECRET --project aws-credentials --config prd --plain)

API Authentication: HTTP Basic Auth with KEY_ID:KEY_SECRET

Step 2: Resolve Organization ID

# Fetch organizations
curl -s -u "$KEY_ID:$KEY_SECRET" https://api.clickhouse.cloud/v1/organizations | jq -r '.[0].id'

Expected Output: UUID format (e.g., 2404d339-6921-4f1c-bf80-b07d5e23b91a)

Store in Doppler:

doppler secrets set CLICKHOUSE_CLOUD_ORG_ID "<org_id>" --project aws-credentials --config prd

Step 3: Fetch Service Details

# Get service metadata
SERVICE_ID="a3163f31-21f4-4e22-844e-ef3fbc26ace2"  # gapless-crypto-clickhouse service
ORG_ID=$(doppler secrets get CLICKHOUSE_CLOUD_ORG_ID --project aws-credentials --config prd --plain)

curl -s -u "$KEY_ID:$KEY_SECRET" \
  "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/services/$SERVICE_ID" | jq '.'

Response Schema: See references/api-endpoints.md

Step 4: Extract Connection Endpoints

From API response, extract:

HTTPS Endpoint (recommended for clickhouse-connect):

  • Host: ebmf8f35lu.us-west-2.aws.clickhouse.cloud
  • Port: 8443

Native Protocol Endpoint (for clickhouse-client):

  • Host: ebmf8f35lu.us-west-2.aws.clickhouse.cloud
  • Port: 9440

Store in Doppler:

doppler secrets set CLICKHOUSE_HOST "ebmf8f35lu.us-west-2.aws.clickhouse.cloud" --project aws-credentials --config prd
doppler secrets set CLICKHOUSE_PORT "8443" --project aws-credentials --config prd
doppler secrets set CLICKHOUSE_USER "default" --project aws-credentials --config prd

Step 5: Extract Service Configuration

Configuration Details:

  • Idle Scaling: Enabled (15 minutes timeout)
  • Memory Tier: 8-24 GB (development tier)
  • Region: us-west-2 (AWS)
  • ClickHouse Version: 25.8.1.8702
  • IP Access: 0.0.0.0/0 (open to world, consider restricting for production)

State Validation: Ensure service state is running

Success Criteria

  • ✅ Organization ID retrieved and stored in Doppler
  • ✅ Service details fetched successfully
  • ✅ Connection endpoints extracted (HTTPS 8443 confirmed)
  • ✅ Configuration parameters validated (idle scaling enabled, region us-west-2)
  • ✅ Service state confirmed as running

Troubleshooting

Issue: "Could not authenticate with ClickHouse Cloud API"

  • Check: Verify CLICKHOUSE_CLOUD_KEY_ID and CLICKHOUSE_CLOUD_KEY_SECRET in Doppler
  • Verify: API keys not expired (check https://clickhouse.cloud/ → Settings → API Keys)

Issue: "Service not found"

  • Check: Verify service ID matches gapless-crypto-clickhouse service
  • Expected: a3163f31-21f4-4e22-844e-ef3fbc26ace2

Issue: "Service state is not running"

References

Next Steps

After service setup, proceed to:

  1. clickhouse-cloud-credentials - Store all credentials in Doppler + 1Password
  2. clickhouse-cloud-connection - Test connection to ClickHouse Cloud