> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usekestrel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse

> Connect ClickHouse Cloud for service lifecycle (start/stop/scale), IP access list, backups, ClickPipes ingestion, usage costs, error-spike detection, and AI investigation in workflows

The ClickHouse integration connects Kestrel to your ClickHouse Cloud organization through the ClickHouse Cloud API, enabling control-plane events (service state, scaling, backups, ClickPipes, query errors, and spend) to trigger workflows and giving AI agents read-only access to your services' state.

ClickHouse Cloud has no control-plane webhooks (its notifications are email/console-only, and ClickStack alert webhooks are observability alerts, not service/backup/ClickPipe events), so Kestrel polls the ClickHouse Cloud API on a per-tenant cadence to detect service state changes, scaling and version changes, backup completions/failures, ClickPipe failures, failed-query spikes, and spend thresholds.

## Prerequisites

* **Organization Admin** role in Kestrel
* A ClickHouse Cloud organization with at least one service
* A ClickHouse Cloud **API key** (key ID + secret) with the **Admin** role, created in the ClickHouse Cloud console

## Setup

**1. Create an API key**

In the ClickHouse Cloud console (`console.clickhouse.cloud`), click your **organization** name in the bottom-left to open the organization menu, choose **API keys**, then click **New API key**. Give it a name (e.g. `kestrel`) and select the **Admin** role (Developer keys are read-only and cannot start/stop/scale services). Copy the generated **Key ID** and **Key secret** (shown only once).

The key ID and secret are sent as HTTP Basic auth to the ClickHouse Cloud API at `api.clickhouse.cloud` to read and manage services, backups, and ClickPipes.

**2. Connect in Kestrel**

1. Navigate to **Integrations → ClickHouse** in your Kestrel dashboard.
2. Paste your **Key ID** and **Key secret**.
3. Optionally enter your **Organization ID** — a ClickHouse Cloud API key belongs to exactly one organization, so Kestrel auto-detects it when left blank.
4. Choose a **Poll Interval** (how often Kestrel checks the ClickHouse Cloud API for service/backup/ClickPipe/error/spend events).
5. Click **Connect ClickHouse** — your ClickHouse Cloud organization appears as connected.

> [!WARNING]
>
> The API key grants access to your ClickHouse Cloud services and their control plane. Treat it as a secret — Kestrel stores it encrypted.

> [!NOTE]
>
> All ClickHouse triggers are detected by polling, so there may be up to one poll interval of delay before a workflow fires. The minimum poll interval is 60 seconds.

## How It's Used

### In Workflows

**Trigger blocks (all poll-based):**

* **Service State Changed** — fires when a service changes state (running, idle, stopped, awaking, ...)
* **Service Idle** — fires when a service scales to idle/stopped (cost signal)
* **Service Scaled** — fires when a service's replica count or memory limits change
* **Backup Completed** / **Backup Failed** — fires when a service backup reaches a terminal state
* **Query Error Spike** — fires when failed queries/inserts (Prometheus counters) increase past a configurable threshold within a poll window
* **ClickPipe Failed** — fires when a managed ingestion pipeline enters a failed state
* **Version Changed** — fires when a service's ClickHouse version changes after an upgrade
* **Usage/Spend Threshold** — fires when month-to-date spend (ClickHouse Credits) crosses a percent of a configured monthly budget
* **Too Many Parts** — fires when a partition's max part count exceeds a threshold (the classic "too many parts" incident)
* **High Query Concurrency** — fires when concurrent running queries exceed a threshold

Filter triggers by service ID and event type; the error-spike threshold, monthly budget, and usage percent are configurable per trigger.

**Action blocks:**

* **List Services** / **Get Service** — inventory (state, scaling, version, endpoints, IP access list)
* **Create Service** — provision a service, e.g. a self-serve staging analytics DB (gate behind an Approval node)
* **Start Service** / **Stop Service** — the cost levers: resume before working hours, stop non-prod services overnight
* **Update Autoscaling** — per-replica memory limits, replica count, idle scaling, idle timeout
* **Update IP Access List** — add/remove CIDR entries (security)
* **List Backups** / **Get Backup** / **Update Backup Configuration** — backup visibility and schedule
* **Restore Backup** — restore by provisioning a new service from a backup (the API has no in-place restore; gate behind an Approval node)
* **Delete Service** — tear down a stopped service (gate behind an Approval node)
* **List API Keys** — key hygiene (metadata only; secrets are never returned)
* **Get Service Metrics** — fetch failed-query Prometheus counters during RCA
* **Get Usage Costs** — org spend report in ClickHouse Credits
* **Get / Set / Clear Autoscaling Schedule** — native scheduled autoscaling (business-hours scale-down; the race-free cost lever)
* **Get / Set / Clear Upgrade Window** — control when ClickHouse version upgrades occur (maintenance governance)
* **Get / Update / Reset ClickHouse Setting** — tune server/query settings, e.g. `max_concurrent_queries` (Beta API; some settings trigger a rollout restart)
* **Get / Upsert / Delete Query Endpoint** — manage the query API endpoint (roles, allowed origins)
* **List Members** / **Remove Member** — org access review and offboarding (gate remove behind Approval)
* **List Roles** — org role inventory for access review
* **List Activity** — org audit/activity log over a recent window (security RCA)
* **List ClickPipes** / **Get ClickPipe** / **Start ClickPipe** / **Stop ClickPipe** / **Resync ClickPipe** / **Scale ClickPipe** — manage managed ingestion (Kafka, S3, CDC)
* **Investigate ClickHouse** — run an AI investigation of services, backups, ClickPipes, metrics, and costs

ClickHouse service, ClickPipe, and backup selects accept template variables like `{{signal.service_id}}`, `{{signal.clickpipe_id}}`, and `{{signal.backup_id}}` from the trigger.

Example (cost — the flagship ClickHouse flow): On a weeknight schedule, stop non-production ClickHouse services and post a summary to Slack; on a morning schedule, start them again.

Example (incident): When a query-error spike or ClickPipe failure is detected, run an AI investigation, page on-call via PagerDuty, and open a Jira issue with the findings.

Example (provisioning): A "staging ClickHouse service" developer request gates behind an Approval, then creates the service and posts the endpoint host to Slack.

## Disconnecting

1. Navigate to **Integrations → ClickHouse**
2. Click **Disconnect**
3. Confirm the disconnection

This stops all ClickHouse workflow triggers. You can reconnect at any time.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.