How to Configure LlamaIndex ClickHouse Guardrails

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up llamaindex clickhouse guardrails by naming allowed tables and assigning restricted database roles. Then you limit the agent account to read-only queries on safe columns. Many teams first link their agent to a database with a broad admin account. That shortcut lets the query engine pull every table schema into the model prompt. It also lets generated SQL touch tables that the app should not read. How to set up native llamaindex clickhouse guardrails LlamaIndex connects to databases

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 llamaindex clickhouse guardrails by naming allowed tables and assigning restricted database roles. Then you limit the agent account to read-only queries on safe columns. Many teams first link their agent to a database with a broad admin account. That shortcut lets the query engine pull every table schema into the model prompt. It also lets generated SQL touch tables that the app should not read.

How to set up native llamaindex clickhouse guardrails

LlamaIndex connects to databases through a light wrapper around SQLAlchemy. Its natural language query engine turns user questions into SQL queries over your tables. You can pass a specific list of tables when you set up this engine. Without that list, the query engine pulls all schema context from the database. Pulling every table wastes prompt tokens and exposes internal table names to the model.

Official LlamaIndex docs warn that running arbitrary generated SQL is a security risk. They advise teams to use restricted roles, read-only databases, and sandboxing. In ClickHouse, you build these controls with SQL-driven access management. An admin first turns on the server storage directory for access entities. At least one account needs user and collection management permissions enabled. Note that a ClickHouse user can only grant privileges that they already hold.

With SQL access control active, you create a dedicated account for your agent. The user creation statement sets the login method, default roles, and allowed client hosts. It can also attach user settings and quotas to cap resource use. Next, you grant read privileges on specific columns rather than whole tables. When a user only has column grants, ClickHouse blocks select-star queries on that table. Those broad queries return no data unless the table holds only the granted columns. Starting in version 24.10, a trailing asterisk also lets you grant permissions by table prefix.

What native database roles solve and what they miss

Combining LlamaIndex table lists with ClickHouse column grants builds a solid baseline. The agent only sees the schema for the tables you name in code. If the model invents a query for another table, ClickHouse rejects the statement. Column grants also stop the agent from pulling restricted fields via select-star queries. Host restrictions and quotas help keep rogue scripts from overloading the server.

Yet static database roles only check who logs in and which columns they request. They do not inspect what happens inside the allowed columns during a live query. An agent often needs access to customer tables to answer support or billing questions. Those allowed columns may still hold emails, phone numbers, card numbers, or national IDs. Once ClickHouse runs the query, raw values flow back into the LlamaIndex prompt context. Native database roles also cannot require a human to approve an unusual query in flight. They treat every query from the shared agent account the exact same way.

ClickHouse Access Management + AI Guardrails: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

How to tighten agent query controls

Before you put a text-to-SQL app into production, audit every table the agent can reach. List the exact columns the query engine needs to answer common user questions. Remove any broad table grants and replace them with explicit column grants. Check that your agent account cannot run data mutations or schema changes.

Next, think about what happens when allowed columns hold sensitive text or numbers. Static grants are all-or-nothing, so a permitted column always returns its raw text. When results include emails or card numbers, data masking rewrites matched fields in results. You also want query logs that tie each SQL statement back to the caller. Clear logs and field masking keep sensitive values out of model prompts and chat histories.

Check ClickHouse queries and results before execution

Access control in ClickHouse is essential setup. Setup alone does not check single queries for risk or rewrite sensitive strings in returned rows. By design, hoop.dev sits beside the server as a sidecar for your ClickHouse and parses every statement before execution.

First, hoop.dev guardrails block disallowed deletes, drops, and alter mutations. Then hoop.dev data masking rewrites sensitive string columns in responses and logs each decision per resource. Read the docs and source on GitHub.

Frequently asked questions

Why does LlamaIndex pull all tables from ClickHouse by default?

The natural language SQL query engine needs schema context to write valid queries. If you do not pass a table list, it reads every visible table schema. Passing an explicit table list limits what the engine loads into the prompt.

What happens when a ClickHouse user with column grants runs select star?

ClickHouse refuses a select-star query if the user only holds partial column grants. The database returns no data at all unless every column in that table is granted. The agent must name the allowed columns directly in its generated SQL statement.

Are read-only ClickHouse roles enough for a text-to-SQL agent?

Read-only roles stop the agent from changing or deleting data in your cluster. Still, they still return raw text from any column the role can read. Teams add runtime masking when allowed columns hold emails, phone numbers, or card numbers.

The query runs. The emails stay hidden.