How to Configure Claude Code ClickHouse Permissions

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up claude code clickhouse permissions by creating a restricted database user for your agent. Then you pass those read-only login details to the agent through its tool setup. Many teams start by handing an AI agent their own admin database login. That shortcut lets a mistyped query drop tables or read private customer records. How claude code clickhouse permissions work in practice Claude Code reaches external databases in two main ways. First, it uses Model Context Protocol servers to

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 claude code clickhouse permissions by creating a restricted database user for your agent. Then you pass those read-only login details to the agent through its tool setup. Many teams start by handing an AI agent their own admin database login. That shortcut lets a mistyped query drop tables or read private customer records.

How claude code clickhouse permissions work in practice

Claude Code reaches external databases in two main ways. First, it uses Model Context Protocol servers to connect to external tools and data sources. Vendor docs recommends putting a read-only database user in the connection string. This step prevents the queries that Claude runs from changing any stored data. Second, the agent can run shell commands through its built-in Bash tool. In manual mode, the Bash tool asks for human approval before running database commands. Only a small built-in list of safe local read commands skips this prompt.

On the database side, ClickHouse manages users, roles, row policies, settings profiles, and quotas with SQL. To turn on SQL-driven access control, an admin sets up an access storage directory. You also need at least one database user with access management rights turned on. An admin with user creation rights can then create a dedicated login for the agent. During user creation, you can set the login method, allowed client hosts, and default roles. A database user can only grant rights that they already hold themselves.

Scoping table and column grants for AI agents

Once the agent has its own database user, you can limit what it reads. ClickHouse lets you grant read access on specific columns instead of whole tables. If you grant select rights on two columns, the agent can query only those two columns. Queries that ask for other columns will fail right away. A full wildcard query across all columns is also refused and returns no data. It only works if the table holds just the granted columns. Recent ClickHouse versions also let you grant select rights across table prefixes with a trailing asterisk.

What native database roles solve and what they miss

Native database roles and column grants solve the first part of agent security. They decide who can log in and which tables or columns stay off limits. If the agent tries to alter a table using a read-only login, ClickHouse blocks it.

Claude Code Security + ClickHouse Access Management: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Still, static database roles leave an operational gap during live coding sessions. First, the client machine still holds a static database password in a local file. Any script or shell command on that laptop can read and reuse that secret. Second, column grants are all-or-nothing rules. When the agent needs to inspect a table with customer emails or phone numbers, you face a hard choice. Either you block the column and break the task, or you grant select rights. Once you grant select rights, raw emails, phone numbers, and card numbers flow into the model context. Native roles check who logs in, not what individual queries return in flight.

Add runtime guardrails and masking beside ClickHouse

Database grants and network rules control who can reach ClickHouse. Even so, an allowed client or agent can send an alter mutation that deletes rows or read raw personal data. In practice, hoop.dev sits inline in the native TCP protocol beside the server as a sidecar for your ClickHouse. For every production query an agent or human sends, hoop.dev decides whether to pass, mask, block, or escalate it for review.

With hoop.dev ClickHouse support, guardrails refuse banned queries before they run or hold risky calls for approval, and data masking rewrites matched string columns in results in memory. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.

Frequently asked questions

How does Claude Code connect to a ClickHouse database?

It connects through a Model Context Protocol server or by running database CLI commands in its Bash tool. Both paths use the database login details stored on the developer machine.

Why does wildcard select fail when using ClickHouse column grants?

ClickHouse blocks wildcard select queries when a user only has rights on specific columns. The user must name the allowed columns in the query unless the table has no other columns.

Can ClickHouse database roles mask sensitive fields for AI agents?

Standard column grants only allow or block access to an entire column. To rewrite emails, phone numbers, or national IDs in query results, you need inline data masking in the query path.

The query runs. The emails stay hidden.