How to Configure LlamaIndex ClickHouse Connect

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up a llamaindex clickhouse connect workflow, link your query engine to a database wrapper. Then, bind that wrapper to a restricted ClickHouse user role with scoped read rights. Teams often start by passing a shared admin account to the agent framework. That broad role lets the language model read every table in the cluster. If the model writes a bad query, it can pull sensitive records or overload your server. How a llamaindex clickhouse connect setup works LlamaIndex uses a light wrap

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.

To set up a llamaindex clickhouse connect workflow, link your query engine to a database wrapper. Then, bind that wrapper to a restricted ClickHouse user role with scoped read rights. Teams often start by passing a shared admin account to the agent framework. That broad role lets the language model read every table in the cluster. If the model writes a bad query, it can pull sensitive records or overload your server.

How a llamaindex clickhouse connect setup works

LlamaIndex uses a light wrapper around SQLAlchemy to talk to your database. A natural language table query engine turns user questions into raw SQL statements. You should always pass an explicit list of target tables to this query engine. If you leave that list blank, the engine pulls all schema context from the database. Pulling every table wastes prompt tokens and exposes hidden schemas to the model.

On the database side, ClickHouse manages users, roles, row policies, and quotas as access entities. You first enable SQL-driven access control by setting a storage path on the server. At least one admin account needs user management rights turned on to start. That admin can then create a dedicated user for the AI app. Keep in mind that a ClickHouse user can only grant privileges they hold themselves.

When you create the agent user, you define how it logs in. You can also restrict which network hosts the agent may connect from. Next, you attach default roles and settings profiles to keep resource use in check.

Scoping tables and columns for text to SQL

The official LlamaIndex guides warn that running arbitrary SQL carries a real security risk. The docs urge teams to use restricted roles, read-only databases, and sandboxing. In ClickHouse, you can enforce this by granting select rights on specific columns only. When you grant access to two columns, the agent can query only those two fields.

If the model tries to read a third column, ClickHouse blocks the query right away. A wildcard select query also fails and returns no data at all. A wildcard query works only when the table holds just the granted columns. If your analytics tables share a common naming pattern, you can use prefix grants. Since version 24.10, a trailing asterisk grants select rights across tables that match a name prefix.

ClickHouse Access Management + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Where native database roles fall short

Native roles and column grants decide who can log in and which fields exist. They do not inspect what individual queries do while they run in flight. An agent with valid read rights on a customer table can still dump every row. If a allowed column holds emails, phone numbers, or card numbers, those values return intact.

Static credentials also create a tracking problem for security teams. Every prompt from every human user runs under the same shared service account. Your database logs show the app role, not the person who asked the question. Also, a single bad prompt can trigger a massive join across billions of rows. Database roles alone cannot pause a risky query for human review before it runs.

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 runs beside the server as a sidecar for your ClickHouse and checks native TCP queries with no change to your drivers.

With hoop.dev ClickHouse support, guardrails refuse banned queries before they run, and data masking rewrites matched string columns in results. The audit trail logs which entity types were masked and how many without storing raw values. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.

Frequently asked questions

Why does a wildcard query fail for my restricted ClickHouse user?

ClickHouse blocks wildcard select queries when a user has column-level grants on only part of a table. The query engine must name the exact allowed columns, or the table must contain only those granted columns.

What happens if I do not list target tables in the LlamaIndex query engine?

If you omit the table list, the query engine pulls all schema context from the database. This slows down prompt processing and lets the model see tables it does not need.

How can I limit where the LlamaIndex app logs in from?

When you run the user creation statement in ClickHouse, you can set allowed client hosts. This rule blocks the agent credential if someone tries to use it from an unknown network.

The query runs. The emails stay hidden.