How to Configure OpenHands ClickHouse Connect
You set up openhands clickhouse connect by giving the agent a dedicated database user. Then you pass those login details into the agent workspace so the driver can run queries. Teams often start by handing the agent a broad admin account to move fast. That shortcut creates a major risk if the agent runs a bad command or reads private columns. A better plan uses strict database roles and column rules from day one. How openhands clickhouse connect works with native roles OpenHands runs tasks in
Your coding agents run with your access.
Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.
You set up openhands clickhouse connect by giving the agent a dedicated database user. Then you pass those login details into the agent workspace so the driver can run queries. Teams often start by handing the agent a broad admin account to move fast. That shortcut creates a major risk if the agent runs a bad command or reads private columns. A better plan uses strict database roles and column rules from day one.
How openhands clickhouse connect works with native roles
OpenHands runs tasks inside a workspace where it writes and runs Python scripts. When it needs analytical data, it loads the ClickHouse driver to talk to your server. The server checks who the agent is before it runs any query. ClickHouse manages users, roles, row policies, settings profiles, and quotas as access entities with SQL. To turn on SQL access control, the server needs a storage path set up. It also needs at least one user with access management turned on.
Once you turn that on, an admin can create a dedicated user for the agent. Creating a user requires the create user privilege on the server. Remember that a user can only grant the privileges that they have themselves. When you create the agent account, you set its login method and default roles. You can also limit which hosts the user may log in from. Finally, you can attach per-user settings to keep resource use in check.
Locking down tables and columns for agent queries
After you set up the user, you must decide what data the agent can read. Giving an agent read rights on a whole database exposes too much data. Instead, you can grant select rights on specific columns in a table. If you only grant two columns, the agent can query only those two columns. If it tries to read a third column, the server blocks the query.
Even a wildcard query fails and returns no data unless all table columns are allowed. Since version 24.10, a trailing asterisk lets you grant rights by table name prefix. This helps when your agent reads many tables that share a common naming pattern. You can group these column and prefix grants into a single role for the agent.
ClickHouse Access Management + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What native setup solves and what it leaves open
Native database roles and host limits solve the first part of the security puzzle. They control which account logs in and which tables or columns that account can touch. If the agent tries to drop a table or read a blocked column, ClickHouse stops it. This keeps the agent inside a clear boundary on the server side.
Still, static roles do not inspect what happens inside allowed queries in flight. First, the agent workspace still holds a raw database password or key on disk. Second, an allowed column might hold emails, phone numbers, card numbers, or national IDs. Once you grant select on that column, the database sends those raw values back. Dynamic data masking rewrites matched fields in results before the agent reads them. Also, native grants cannot pause a risky query to ask a human for approval first.
Check ClickHouse queries and result columns on the wire
ClickHouse users and row policies decide who connects. They do not check each statement on the wire or redact sensitive string columns in query results. With hoop.dev, you run an open-source proxy, a sidecar for your ClickHouse. It reads ClickHouse's native TCP protocol before queries run while ClickHouse stays in charge of login and grants.
Multi-statement queries and table mutations are split and checked by hoop.dev guardrails. Banned actions are refused with a native ClickHouse error. On returned rows, hoop.dev data masking rewrites String and FixedString columns that match your rules. The audit trail logs each query, table, and verdict. See the MIT-licensed source on GitHub.
Frequently asked questions
Why did my wildcard query fail in an openhands clickhouse connect session?
ClickHouse blocks wildcard select queries when a user only has grants on specific columns. The query returns no data unless the user has rights on every column in that table. Have the agent list the exact allowed column names in its query instead.
How do I let the agent read new daily tables without manual grants?
Since version 24.10, you can use a trailing asterisk to grant select by name prefix. If your daily tables start with the same word, one prefix grant covers them all. Attach that grant to the agent role so new matching tables work right away.
Can a ClickHouse role hide phone numbers or emails inside an allowed column?
No, native column grants are all or nothing for the columns you allow. If a user has select rights on a text column, the server returns the full text. To rewrite emails or phone numbers in results, you need data masking in the query path.
Related guides
In this post