clickhouse-stackql-demo

Talk and demo assets for the ClickHouse Melbourne Meetup, 26 Aug 2026.

synopsis

StackQL is an open source project that exposes cloud and SaaS providers as data sources accessed via SQL, supporting query, audit, and provisioning operations using standard SELECT, INSERT, UPDATE, and DELETE semantics. The StackQL ClickHouse provider covers the ClickHouse Cloud API, including organisations, services, API keys, members and roles, backups, ClickPipes, and usage and cost data.

This session demonstrates practical operations against ClickHouse Cloud using the provider: inventorying services across organisations, auditing keys and membership, reporting on usage and cost, and performing service lifecycle operations. ClickHouse Cloud data can also be joined with any of the other providers in the StackQL registry (AWS, GitHub, Okta, and others) in a single query, useful for cross-platform audit and reporting.

This session will also demonstrate exposing these capabilities to AI agents via the StackQL MCP (Model Context Protocol) server. Connected to Claude or any MCP-capable client, an agent can discover the ClickHouse provider schema, generate and validate queries, and perform inspection, audit, and gated provisioning operations against ClickHouse Cloud environments from natural language prompts.

The talk is demo-driven: a walkthrough of the ClickHouse provider from the StackQL shell, followed by a live agent session performing an audit and a provisioning task via MCP. All tools and code shown are open source. Relevant to platform engineers, SREs, and anyone operating ClickHouse Cloud environments.

speaker bio

Jeff Aven is the co-creator of StackQL, an open source project for querying and provisioning cloud and SaaS resources using SQL, and co-founder of StackQL Studios. He has over 35 years in the technology industry, is a published author on data and analytics, and an authorised trainer for Databricks, Google, and Confluent. Based in Melbourne, Australia.

demo 1: clickhouse provider

Demonstrates basic usage of StackQL and the clickhouse provider with:

• stackql shell
• stackql exec with different formats and options
• stackql srv with a postgres client (psql and @stackql/pgwire-lite)
• pystackql and Marketplace GitHub actions

demo 2: stackql-deploy

Demonstrates stackql-deploy to provision and maintain a realtime-analytics multi-provider stack including a ClickHouse Cloud service.

# source auth and stack variables from the (gitignored) .env file
# (set -a exports everything sourced, so child processes see the auth vars)
set -a; source .env; set +a

# set deploy time variables
export AWS_REGION=ap-southeast-2
export OFFICE_CIDR=203.0.113.0/24

# show every query that would run, resolve nothing
stackql-deploy build realtime-analytics dev --dry-run \
  -e AWS_REGION=$AWS_REGION -e OFFICE_CIDR=$OFFICE_CIDR

# deploy dev: 1 replica, 8-16 GB, idles to zero
# (idempotent: re-running asserts state, only changes what drifted)
stackql-deploy build realtime-analytics dev \
  -e AWS_REGION=$AWS_REGION -e OFFICE_CIDR=$OFFICE_CIDR

# deploy prd from the same manifest: 3 replicas, 16-32 GB, always on, 7-day backups
stackql-deploy build realtime-analytics prd \
  -e AWS_REGION=$AWS_REGION -e OFFICE_CIDR=$OFFICE_CIDR

# test (exists + statecheck only, no mutations)
stackql-deploy test realtime-analytics dev \
  -e AWS_REGION=$AWS_REGION -e OFFICE_CIDR=$OFFICE_CIDR

# tear down in reverse dependency order
stackql-deploy teardown realtime-analytics dev \
  -e AWS_REGION=$AWS_REGION -e OFFICE_CIDR=$OFFICE_CIDR

stackql-deploy also sources .env from the working directory by default (--env-file), so the stack variables in it (CLICKHOUSE_ORG_ID, CONFLUENT_ENVIRONMENT_ID, POSTGRES_MASTER_*) reach the manifest templater without -e; the source puts the auth variables in the shell environment for the stackql server process. See realtime-analytics/README.md for the environment switches (dev vs prd) and stack details.

demo 3: agentic use cases with ClickHouse and stackql mcp

• claude-desktop-prompts.md - prompts for an interactive agent session over the StackQL MCP server, including the gated write (safe mode elicitation)
• python-agent - FinOps analyst agent: Anthropic SDK + stackql-mcp-server (read_only)
• node-agent - SRE assurance agent: Anthropic SDK + @stackql/mcp-server (read_only)

Both agents run from the repo root. They need ANTHROPIC_API_KEY and the CLICKHOUSE_* credentials from .env in the process environment; the MCP server package downloads the stackql binary on first run.

# source auth variables from the (gitignored) .env file
set -a; source .env; set +a

# python agent (FinOps analyst)
# (Debian/Ubuntu/WSL: apt install python3-venv first, or the venv is created without pip)
python3 -m venv demo/agentic-use-cases/python-agent/.venv
source demo/agentic-use-cases/python-agent/.venv/bin/activate
# on Windows (git bash): source demo/agentic-use-cases/python-agent/.venv/Scripts/activate
python -m pip install -r demo/agentic-use-cases/python-agent/requirements.txt
python demo/agentic-use-cases/python-agent/agent.py
deactivate

# node agent (SRE assurance)
npm --prefix demo/agentic-use-cases/node-agent install
node demo/agentic-use-cases/node-agent/agent.mjs

FAQs

• "How is this different from the ClickHouse Terraform provider?" Same API, different model. Terraform holds desired state in HCL and actual state in a file; StackQL holds desired state in SQL and reads actual state from the API every run. No state file, no import, and the same SQL works for ad-hoc queries, CI and agents.
• "Can it query my ClickHouse data, not just the control plane?" Not this provider. The server HTTP interface (SQL against a service, system.* tables) is a separate auth surface; it is the planned clickhouse_server provider. Today: use this for the control plane and the Query API endpoint it provisions for data.
• "Is the agent writing to production?" Only through a server mode you chose. read_only by default; safe routes every write through an elicitation to a human; everything is logged as JSONL with the SQL and the decision.
• "What about secrets?" Credentials live in the server process environment; the model never sees them. RETURNING secrets in a stack are marked protected and not logged.
• "Rate limits?" 10 per 10 seconds per key. Use separate keys per consumer; the agent paces wide scans.

Links:

• stackql
• provider docs
• stackql-deploy