What's new in 3.18
AI agents sign in to CHouse MCP with OAuth, and Upgrades checks what a ClickHouse upgrade changes for your workload — and what to change when you upgrade.
3.18 changes how CHouse UI talks to ClickHouse: one server module now sends every statement, and each statement says which CHouse account or background purpose it is for. It is the first step of a larger change to how a statement gets its ClickHouse identity (ADR 0033).
Highlights
See which account ran a statement — Every request to ClickHouse carries a query id of the form chouse:p:<account id>:<random>, or chouse:s:<purpose>:<random> for background work, and, on servers that accept it, a quota key with the same account or purpose. A ClickHouse administrator can read the account straight from system.query_log, and can create a keyed quota to limit each CHouse account separately. A statement cannot change its own query id. → Who a statement runs as
EXECUTE AS is refused, for administrators too — CHouse UI decides which ClickHouse user a statement runs as. The check reads ClickHouse's own parse, so a comment or a wrapper cannot hide the keyword. To make this possible, statements typed by administrators are now parsed by ClickHouse before they run, like everyone else's. → Who a statement runs as
Reads are sent read-only — CHouse UI now asks ClickHouse itself to refuse a write. Every read is sent with readonly = 2, for administrators too, and so is every statement from a person whose roles hold no write permission. Whether a statement is a read comes from ClickHouse's parse of it, so a mistake in CHouse UI's own check cannot turn a read into a write. → Reads are sent read-only
System tables that show other people's work need a permission — Reading system.query_log, system.processes and the other statement logs needs query:history:view:all; reading system.users, system.grants and the other access tables needs clickhouse:users:view. Everyone still sees their own statements on the Logs page. → System tables that show other people's work
A job runs as whoever last changed what it does — A scheduled query or data health check with no owner used to run with no access check. It now fails with a message that says why, shows No owner, and offers Assign to me. Saving a change to a job's SQL, output or channels makes you its owner, so nobody's job runs a statement someone else wrote under their name. → Who a job runs as
Limit each person to a ClickHouse role — A connection can now be a role ceiling: its ClickHouse user holds no grant of its own, each CHouse role is mapped to one ClickHouse role, and every statement is sent with the role of the person it is for. ClickHouse itself then refuses anything outside that role, for administrators too. CHouse UI checks the login before the switch and every five minutes after. Needs ClickHouse 24.4 or newer: on an older server the kind is disabled in the form, with the reason; existing connections are unchanged. → Connection kinds and the role ceiling
Run each person's statements as their own ClickHouse user — A connection can now be personal: a super admin links each CHouse account to a ClickHouse user, and that person's statements run as that user, so the grants, row policies and quotas you already have in ClickHouse decide what they reach. CHouse UI stores no password for those users. It needs a ClickHouse build that checks grants for every statement run this way; CHouse UI tests the server itself and refuses one that fails (of the builds tested, 26.3.63 passes and 26.5.7 does not). → Personal connections
See what your statements run as, from an agent or a terminal — The MCP tool connection_runs_as and chouse connection runs-as report the ClickHouse identity a caller's statements carry on each connection and whether it is usable now. A super admin can manage the links of a personal connection with chouse connection links. Switching a kind, editing a role map and confirming a suspended link need a browser session. → CLI
Upgrading from 3.17
The RBAC database gains a column for each job's owner (scheduled_queries.owner_id, filled from its creator), the kind and health columns of each connection (every existing connection becomes a shared login) and the role map table. They are added automatically at start-up. Check these:
| What changed | What to do |
|---|---|
Query ids in system.query_log and system.processes now look like chouse:p:<account id>:<random> | If a script or alert of yours matches CHouse query ids by their old shape (a bare UUID, or the chouse-ai- prefix), update it. The AI id is now the last part: chouse:p:<account id>:chouse-ai-<request id>-<n> |
A typed KILL QUERY needs live_queries:kill_all | Give that permission to roles that should stop other people's queries from the SQL editor. live_queries:kill still stops your own queries from Live Queries and the editor's Stop button |
| Statements typed by administrators are parsed by ClickHouse first | Nothing to do. An administrator's statement is refused when ClickHouse cannot parse it, or when the connection cannot be reached to parse it |
EXECUTE AS is refused in every typed statement | Nothing to do unless someone relied on it; run such statements with a ClickHouse client instead |
| A scheduled job with no owner fails instead of running | Open the job and choose Assign to me, or save a change to it. The job list marks these jobs No owner, and failed runs say when this is the reason |
| Saving a change to a job's SQL, output or channels makes the saver its owner | Nothing to do. Expect the owner shown on a job to change after someone else edits it; the next run is checked against the new owner's access |
A typed read of the statement logs (system.query_log, system.processes, system.text_log, …) needs query:history:view:all, and of the access tables (system.users, system.grants, …) needs clickhouse:users:view | Give the permission to roles whose saved queries, dashboard panels, scheduled queries or agents read these tables. The built-in admin and super_admin roles are not affected. A panel or job that reads them for someone without the permission now fails with a message naming it |
Reads are sent with readonly = 2 | Nothing to do for most installs. A statement CHouse UI used to send as a read that in fact writes is now refused by ClickHouse (error 164). A connection whose ClickHouse login has readonly = 2 keeps working |
| A CHouse role that is mapped to a ClickHouse role on a connection can be assigned only by a super admin | Nothing to do until you use the role ceiling. After that, an admin who used to assign such a role must ask a super admin |
| Ownership in Live Queries, Logs, lineage and usage is read from the query id | Nothing to do. Statements logged before the upgrade are still attributed from log_comment |
Every request sends an X-ClickHouse-Quota header, on servers that accept it (24.8 and 26.5 do; 23.8 does not and gets none) | Nothing to do. It has an effect only if you create a ClickHouse quota KEYED BY client_key |
The full list of changes is in the changelog.