ClickHouse
ClickHouse Cloud: manage services, scaling, backups and access — and run SQL over the native HTTP interface.
About
ClickHouse ships in the w6w first-party pack. It declares 15 actions, 2 health checks, and the host runs its code in a sandbox that never sees the credential.
- App id
io.w6w.clickhouse- Version
- 0.1.1
- Author
- w6w
- Licence
- MIT
- Categories
- Databases · Data Warehousing & ETL
Overview
ClickHouse is unusual among databases in this category for one reason: it speaks HTTP natively, so a workflow can not only manage a ClickHouse Cloud service but actually run SQL against it and get rows back. Query actions are read-only by default — enforced by ClickHouse itself, not just by this app — and insert rows safely without ever concatenating values into a statement, warning when a workflow is inserting in a pattern that will eventually get writes throttled.
Service management covers the full lifecycle: provision, start, stop, scale and delete a ClickHouse Cloud service, control which IP addresses may connect, and list backups and usage costs. Schema actions list tables together with their part counts and describe a table’s columns and sorting key — the detail that determines whether a filter reads a fraction of a table or scans the whole thing.
Idle-aware replica scaling, backup visibility and cost tracking make this as much an operations tool as a query interface, and an activity log records every service created, scaled, stopped or deleted — useful for a workflow that provisions ClickHouse capacity on demand, keeps a warehouse’s schema and access list under version control, or audits who changed what in the control plane.
Build with ClickHouse
Three routes to the same 15 actions. The Workflow tab is generated from ClickHouse's own manifest and carries its real ids, so it is copy-pasteable; the Code and CLI examples are the same call for any action on any app, so every app-specific value in them is a blank you fill in.
List organization activity
activity-list The control plane's audit trail — services created, scaled, stopped, deleted. Actions taken with an API key are attributed to the KEY, so one key per automation is what makes this readable later.
List backups
backup-list A service's backups. They are DELETED WITH THE SERVICE, and restoring one provisions a NEW service rather than rewinding this one — so a restore is a migration with a cutover.
Set a service's IP access list
ip-access-list-set Replace the addresses that may connect. It REPLACES rather than merges, and an address off the list fails to connect rather than to authenticate — which from a workflow looks like an outage.
List organizations
organization-list The organisation this API key belongs to — almost always exactly one, because a key is created inside one. Its UUID is what every other control-plane path needs.
Insert rows
query-insert Insert rows into a table. The data goes in the request BODY rather than in the SQL, so nothing is concatenated into a statement. ClickHouse wants BATCHES — many tiny inserts create parts faster than merges remove them.
Run a query
query-run Run SQL and return rows. READ-ONLY by default, enforced by ClickHouse's own `readonly` setting rather than by parsing the statement. Returns what the query cost as well as what it produced.
Create a service
service-create Provision a ClickHouse Cloud service. The generated password is returned ONCE in this response and is never retrievable again. The IP access list must be given — an empty one accepts no connections, and `0.0.0.0/0` is a database open to the internet.
Delete a service
service-delete Destroy a service and its data. It must be STOPPED first, and its BACKUPS are deleted with it — so 'we have backups' is not a recovery plan for this.
Get a service
service-get One service's state, endpoints, scaling and IP access list. An address not on that list fails to CONNECT rather than to authenticate, which from a workflow looks like the service being down.
List services
service-list The organisation's services. `running` is the only state that answers SQL — and `idle` wakes on the next query while `stopped` does NOT, which is the distinction a failed query cannot make.
Scale a service
service-scale Change replica sizing and idle scaling — where the bill is decided. Turning idle scaling OFF makes the minimum size billable around the clock, which is the most common avoidable cost here, so only that direction is gated.
Start or stop a service
service-state Start or stop a service. A STOPPED service does not wake on a query — unlike an idle one — so stopping something a workflow queries is an outage, not a saving. Idle scaling is the saving.
Describe a table
table-describe A table's columns with per-column sizes, plus its SORTING KEY — which decides whether a filter reads a fraction of the table or all of it, and which no column list shows.
List tables
table-list Tables with their engines, row counts, disk size and PART COUNT — the number that predicts a service refusing writes with TOO_MANY_PARTS, and which nothing else surfaces.
Get usage and cost
usage-cost What the organisation has spent, split into compute, storage and data transfer. The only place this platform reports money — and compute is where a service with idle scaling off shows up.
A workflow step names the app and the action, and the editor fills in the
connection when you pick one. This is the Step shape from the
workflow spec, carrying ClickHouse's real ids.
{
"manifestVersion": "2",
"name": "clickhouse-example",
"steps": [
{
"id": "backup-list",
"uses": {
"app": "io.w6w.clickhouse",
"action": "backup-list",
"connection": "conn_YOUR_CONNECTION_ID"
},
"with": {
"serviceId": "<serviceId>"
}
}
]
}Here are some of the things you can do
-
List backups
readbackup-list -
List organization activity
searchactivity-list -
Set a service's IP access list
performip-access-list-set -
List organizations
readorganization-list -
Insert rows
performquery-insert
+10 more actions available
Every app-specific value here is a blank you have to fill in. An
app action is reached through the connection that authenticates it, so the
address is a connection id, not the app id — and connections belong to your account,
so a public page cannot know yours. Create one for ClickHouse, then fill in
the three blanks: conn_YOUR_CONNECTION_ID, the action key, and the
parameters that action declares. The call itself is real — the shape is transcribed
from the studio's own snippet builder, which prints the same kind of blanks — but
nothing in it is specific to ClickHouse. The Workflow tab is where this app's
real ids are.
npm install @w6w/sdkyarn add @w6w/sdkpnpm add @w6w/sdkdeno add npm:@w6w/sdkimport { W6wClient, isActionRun } from "@w6w/sdk";
// Reads W6W_BASE_URL and W6W_TOKEN from the environment when omitted.
const client = new W6wClient();
const envelope = await client.run({
urn: "conn_YOUR_CONNECTION_ID",
action: "backup-list",
payload: {
serviceId: "<value>",
},
});
if (isActionRun(envelope)) console.log(envelope.value);npm install -g @w6w/cliw6w run conn_YOUR_CONNECTION_ID --action backup-list --payload '{"serviceId":"<value>"}'Give an AI agent ClickHouse — without giving it ClickHouse's credentials. One MCP endpoint exposes every app, function and workflow the caller is entitled to, as tools it can discover and run. Access is granted per team while we onboard.
One tool call{
"name": "w6w_invoke",
"arguments": {
"ref": "app:io.w6w.clickhouse#backup-list",
"input": {
"serviceId": "<serviceId>"
}
}
}
Every tool names its target with a single ref. The
app: form above doesn't name a connection at all — the
host resolves which of the caller's ClickHouse connections to sign
with, and refuses rather than guesses when the answer is ambiguous.
What the agent gets
Credentials it can't read
The token is attached host-side, at the moment of the call. It is never a tool argument, never in the model's context, and never in a transcript — so a prompt injection has nothing to exfiltrate.
A tool surface scoped to the caller
Tools are derived per end user from what that person has actually connected and is entitled to — not one shared bot identity carrying the union of everyone's access.
A durable workflow in one call
Multi-step work runs on the workflow engine and returns a run handle the agent can poll — retries, branching and state survive the conversation that started them.
Health-aware discovery
ClickHouse's declared health checks are on the surface too, so an agent can tell "the vendor is down" from "your credential expired" before it burns a retry on either.
The MCP surface is part of the hosted platform. ClickHouse itself is MIT, and the runtime that executes it is source-available (FSL).
Health checks
ClickHouse declares its own checks, so its health is a property of the app rather than something the host guesses at.
ClickHouse Cloud status
Reads status.clickhouse.com, separating the CONTROL PLANE from the services: an API outage stops provisioning and not queries, and a service outage is the other way round. Never claims a full outage, because incidents are regional and this is app-scoped.
Rate-limit headroom
Not checkable, and the question is the wrong one. ClickHouse is constrained by MEMORY, concurrency and PART COUNT rather than by request rate — `query-run` returns what each query actually cost, and `table-list` reports the part counts that predict a service refusing writes.