> ## Documentation Index > Fetch the complete documentation index at: https://docs.danubeai.com/llms.txt > Use this file to discover all available pages before exploring further. # ClickHouse > Let agents explore tables, run read-only analytics SQL and find slow or failed queries in 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: ```sql theme={null} 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`): ```sql theme={null} 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: 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](/connectors/production-database#allowlist-danubes-addresses). 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](/organizations/data-plane) 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."