ClickHouse
Let agents run SQL against ClickHouse Cloud or your own ClickHouse server over HTTPS.
Connect it with: User name and password. ClickHouse's own documentation: https://clickhouse.com/docs/interfaces/http.
What agents can do
Connect ClickHouse so the agents working your tasks can reach it. With it connected, they can:
- Run analytical SQL over event and log tables to answer questions in a task.
- Inspect databases, tables and column types with SHOW and DESCRIBE before changing a schema.
- Check that ingestion is current by reading the newest rows.
- Run the query an agent wrote for a report and attach the result.
Before you start
- A ClickHouse Cloud service, or a self-managed ClickHouse server with its HTTPS interface open to the internet.
- A database user for agents, granted SELECT on what they should read. In ClickHouse Cloud, create one under SQL console with CREATE USER and GRANT rather than handing out the default user.
- If the service has an IP access list, an entry that allows Jaah's address.
- A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.
Connect with ClickHouse
Jaah connects to ClickHouse with a user name and password, not with a sign-in button.
Connect with an API key
Find each value first:
- HTTPS endpoint: ClickHouse Cloud: open the service and select Connect > HTTPS, then copy the host and port as https://HOST:8443. A self-managed server: its HTTPS address, port 8443 by default.
- User: The database user agents sign in as; ClickHouse Cloud's first user is named default.
- Password: The user's password. ClickHouse Cloud shows the default user's password once when the service is created; reset it under the service's Settings > Reset password if you no longer have it.
Then add it to Jaah:
- In Jaah, open Secrets, select New, and pick the ClickHouse card.
- Name the secret and choose who can use it.
- Fill in HTTPS endpoint, User, Password.
- Select Save. Jaah tests the secret straight away (see Test the connection).
Jaah encrypts what you type and never shows it again — not to you, and not to an admin.
Use your own OAuth app
Not used: Jaah connects to ClickHouse with a user name and password, not through an OAuth app.
Test the connection
Select Test on the secret. Jaah calls ClickHouse's API once (GET <HTTPS endpoint>/?query=SELECT%201%20FORMAT%20JSON) with the stored values, and shows whether ClickHouse accepted it, or which value ClickHouse refused and the status it answered. Jaah also tests automatically when you save or reconnect.
The last result and its time stay on the secret's page, so you can see whether it still works without testing again.
Who can use it
Every secret has an owner, and the owner decides who can use it:
- Personal — only your own tasks can use it. This is the default.
- Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
- Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.
More on owners and access: How secrets work.
Use it in an agent session
An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:
org/<name>for an organization secret,projects/<project>/<name>for one attached to a project,me/<name>for your personal one.
A key connection hands the agent its fields: base_url, username, password.
Tell the agent in your task description which secret to use, for example “use the ClickHouse secret org/clickhouse”.
Manage, rotate or disconnect
Everything is on the secret's page under Secrets:
- Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at ClickHouse once the test passes. Steps: Replace or delete a secret.
- Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at ClickHouse's side too, change the password at ClickHouse or remove the user.
Limitations
- Jaah tests with
SELECT 1. It proves the address, user and password, not that the user may read a given table. - Only HTTPS endpoints are accepted. A server reachable only over the native protocol (port 9440) or a private network cannot be connected.
- Queries run with the user's settings and quotas. Set readonly = 1 on the user's profile to keep agents read-only.
- Agents can do only what the connected ClickHouse account allows.
Troubleshooting
Test says ClickHouse rejected the password (401 or 403)
Check the user and password. In ClickHouse Cloud reset the password under the service's Settings, then select Replace on the secret.
Test says ClickHouse cannot be reached
Use the HTTPS host with port 8443 from Connect > HTTPS. A stopped (idle) ClickHouse Cloud service wakes on the first request, so test again after a minute. Check the service's IP access list.
A query fails with ACCESS_DENIED
Grant the user SELECT on the database or table: GRANT SELECT ON db.* TO agent_user.
Still stuck? Select Test and read the result: it names the value ClickHouse refused and the status it answered.
FAQ
Does it work with self-managed ClickHouse?
Yes, when its HTTPS interface is reachable from the internet at a public address.
Can agents write data?
Only if the user may. Give agents a user with SELECT grants only, or readonly = 1 on its settings profile.
Can Jaah or an admin see the key or token?
No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.
Can I connect more than one ClickHouse account?
Yes. Add one secret per account, each with its own name, and tell the agent which one to use.