ClickHouse

The ClickHouse connector works with ClickHouse Cloud and self-hosted ClickHouse over the HTTP interface: port 8443 (HTTPS) on ClickHouse Cloud, 8123 (HTTP) or 8443 on a self-hosted server. It needs no driver on your side.

Tools

Tool	What it returns
Test Connection	Server version, user, default database, timezone, whether the connection uses TLS, the user’s grants, and warnings about write or administrative grants. Errors say whether authentication, the network or TLS failed
List Databases	Databases with their engine, number of tables and total size
List Tables	Tables and views with engine, row count, size on disk, sorting key and partition key
Describe Table	Columns (type, default, codec, compressed size, whether each is in the sorting, primary or partition key), engine, keys, row count and size
Run Query	Rows of one read-only `SELECT`, as objects, with `truncated` when more existed
Query Log	Recent queries from `system.query_log`: duration, rows and bytes read, memory, and the exception for failed ones. Filter by minimum duration, errors only and time window
Execute Statement	Runs one write statement (`INSERT`, `ALTER`, `CREATE`, `DROP`, `TRUNCATE`, `OPTIMIZE`). Needs a `read_write` connection and a confirmation on every call

Query parameters

Values go in ClickHouse’s own parameter syntax, {name:Type}, and the agent passes them in params. They are sent to the server separately from the SQL text, never pasted into it:

SELECT level, count() AS n
FROM events
WHERE service = {service:String} AND ts > {since:DateTime}
GROUP BY level

with params {"service": "checkout", "since": "2026-09-26 00:00:00"}.

Safety

Read-only by default, enforced by ClickHouse. Every read is sent with readonly = 1 (or, for a user whose profile is already read-only, runs under that profile), so the server refuses an INSERT, ALTER or DROP on that request (error 164) whatever the user’s grants. Run Query also refuses before sending anything: comments, a second statement, write keywords, and SETTINGS or FORMAT clauses that would change the limits.
Limits on every call. max_execution_time defaults to 15 s (up to 55 s with timeout_seconds). max_result_rows with result_overflow_mode = break stops the server at 500 rows (up to 5,000 with max_rows); Danube stops reading at the same cap and the response is limited to 1 MB. A cut result has truncated: true. 64-bit integers come back as numbers.
Writes are a separate tool. Execute Statement only runs on a connection stored with mode read_write, and every call returns a confirm_token first that the agent must show you and send back.
No secrets in results. The password travels in a request header, never in the URL, and is removed from every error message. Redirects are not followed.
Every call is audited. The audit log records who called, which tool, a SHA-256 of the SQL (never the text), the row count, the duration and the outcome.

Create a read-only user

Run this as an admin (on ClickHouse Cloud, in the SQL console as default):

CREATE USER danube_readonly IDENTIFIED BY 'choose-a-long-password'
  SETTINGS readonly = 2;
GRANT SELECT ON app.* TO danube_readonly;
-- Lets Query Log read recent queries
GRANT SELECT ON system.query_log TO danube_readonly;

Repeat the GRANT SELECT line for every database agents should see. readonly = 2 makes the user read-only for data and schema while still letting Danube set the per-query time and row limits. With readonly = 1 the user is read-only too, but ClickHouse then refuses every setting, including those limits: Danube still caps rows and times out on its side, and Test Connection warns about it.

Connect

Open ClickHouse in the dashboard’s tool catalog and click Connect, or let the agent call store_credential. Fill in the URL (for ClickHouse Cloud, the HTTPS endpoint from Connect in the Cloud console, ending in :8443), user, password and default database. Mode stays Read only unless you want Execute Statement to work. Paste a CA certificate only for a self-hosted server with a private certificate. How Danube reaches ClickHouse depends on where it runs:

Public endpoint
Private network, SSH bastion
Private network, data-plane agent

ClickHouse Cloud services and self-hosted servers with a public HTTPS endpoint connect directly. Allow Danube’s egress addresses in the service’s IP access list (ClickHouse Cloud: Settings then Security): see Connect your production database safely.

Fill in the SSH bastion fields: the bastion’s public host, user, private key and host key fingerprint. Set the URL to ClickHouse’s private address as the bastion sees it, for example http://clickhouse.internal:8123. Danube verifies the bastion’s host key against the fingerprint you stored and never trusts a new key on first use. Leave the fingerprint empty once and Test Connection prints the key the bastion presented, so you can check it and paste it in.

Run the data-plane agent inside the network and store the password as a reference, for example env://CLICKHOUSE_PASSWORD. The call then runs on the agent, which resolves the reference locally. Nothing inbound is opened, and the password never reaches Danube. ClickHouse needs no extra driver in the agent image.

Run Test Connection after saving. It tells you which of these failed: the credentials (auth_required), the network (connection_error, destination_blocked) or TLS (tls_error).

Example prompts

“Which tables in ClickHouse are biggest, and how are they sorted?”
“How many error events did the checkout service log per hour today?”
“Which queries in the last hour took longer than five seconds, and how many rows did they read?”
“Show me the queries that failed in the last 30 minutes and group them by exception.”
“Describe the events table and tell me which filters will use its sorting key.”

Get Started

Organizations & Governance

Infrastructure Connectors

Account

CLI

MCP Clients

SDKs & Integrations

Tools

Query parameters

Safety

Create a read-only user

Connect

Example prompts

​Tools

​Query parameters

​Safety

​Create a read-only user

​Connect

​Example prompts

Tools

Query parameters

Safety

Create a read-only user

Connect

Example prompts