Clickhouse
Tools to query and explore a ClickHouse database
1.0.1ClickHouse Toolkit
Arcade toolkit for connecting to and querying a ClickHouse database. Enables agents and tools to explore database structure and execute read-only SQL queries.
Capabilities
- Database & table discovery: List all databases, retrieve available tables when table names are unknown, and inspect individual table schemas before querying.
- Schema introspection: Fetch column-level structure for any named table; ClickHouse lacks PostgreSQL-style schemas, so schema discovery returns a default schema name.
- Read-only query execution: Run parameterized
SELECTqueries with full support forJOIN,WHERE,HAVING,ORDER BY,LIMIT, andOFFSETclauses;INSERT,UPDATE, andDELETEare blocked. - Query safety guardrails: Built-in rules enforce column-level selection (no
SELECT *), case-insensitive string matching, string trimming,LIKE-based matching, and index/primary-key-only joins.
Secrets
CLICKHOUSE_DATABASE_CONNECTION_STRING — A connection string used to authenticate and connect to your ClickHouse instance. It encodes the host, port, username, password, and target database in a single URI, typically in the format clickhouse://[user]:[password]@[host]:[port]/[database] (or the HTTPS variant for cloud-hosted instances).
To obtain this:
- ClickHouse Cloud: Log in to the ClickHouse Cloud console, select your service, and navigate to Connect → View connection string. Choose the native protocol or HTTPS endpoint and copy the full URI, substituting your actual password.
- Self-hosted ClickHouse: Construct the URI manually using your server's hostname/IP, port (default
9000for native,8123for HTTP), and the credentials configured in yourusers.xmlor via SQL user management.
Ensure the ClickHouse user has at least SELECT privileges on the target database and tables.
Store this secret in Arcade by following the Arcade secrets guide or add it directly at https://api.arcade.dev/dashboard/auth/secrets.
Available tools(5)
| Tool name | Description | Secrets | |
|---|---|---|---|
Discover all the databases in the ClickHouse database. | 1 | ||
Discover all the schemas in the ClickHouse database.
Note: ClickHouse doesn't have schemas like PostgreSQL, so this returns a default schema name. | 1 | ||
Discover all the tables in the ClickHouse database when the list of tables is not known.
ALWAYS use this tool before any other tool that requires a table name. | 1 | ||
You have a connection to a ClickHouse database.
Execute a SELECT query and return the results against the ClickHouse database.
No other queries (INSERT, UPDATE, DELETE, etc.) are allowed.
ONLY use this tool if you have already loaded the schema of the tables you need to query.
The final query will be constructed as follows:
SELECT {select_query_part} FROM {from_clause} JOIN {join_clause}
WHERE {where_clause} HAVING {having_clause}
ORDER BY {order_by_clause} LIMIT {limit} OFFSET {offset}
When running queries, follow these rules which will help avoid errors:
* Never "select *" from a table. Always select the columns you need.
* Always order your results. Use the most important columns or the primary key if you're unsure.
* Always use case-insensitive queries to match strings in the query.
* Always trim strings in the query.
* Prefer LIKE queries over direct string matches or regex queries.
* Only join on columns that are indexed or the primary key. Do not join on arbitrary columns.
* ClickHouse is case-sensitive, so be careful with table and column names. | 1 | ||
Get the schema/structure of a ClickHouse table in the ClickHouse database
when the schema is not known, and the name of the table is provided.
This tool should ALWAYS be used before executing any query.
All tables in the query must be discovered first,
so that their exact names are known. | 1 |