How to Configure Gemini CLI ClickHouse Connect

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a gemini cli clickhouse connect workflow by creating a strict database user. Then you let the agent run queries through a local client. Teams often speed through this step by sharing an admin account with the tool. Broad roles let an automated terminal tool read private tables or drop production data. How a gemini cli clickhouse connect workflow works A terminal AI agent works by running shell commands or helper tools on your machine. When you ask a question about data, the agent w

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 a gemini cli clickhouse connect workflow by creating a strict database user. Then you let the agent run queries through a local client. Teams often speed through this step by sharing an admin account with the tool. Broad roles let an automated terminal tool read private tables or drop production data.

How a gemini cli clickhouse connect workflow works

A terminal AI agent works by running shell commands or helper tools on your machine. When you ask a question about data, the agent writes a query. It sends that query through the Python client driver to the database server. The driver uses local credentials stored on your workstation to log in. Because the agent acts on its own, database rules are your main safety net.

ClickHouse manages users, roles, row rules, settings, and quotas as SQL access items. To turn on SQL access control, an admin sets a storage folder path on the server. At least one admin account needs user management rights turned on first. After that, you can create a dedicated user account just for the terminal agent. A user can only grant rights that they already hold themselves.

When you create the user, you pick the login method and allowed host machines. You also attach default roles and specific user settings to that account. For an AI tool, admins usually grant read rights on specific tables or columns. If you grant read rights on two columns, the agent can only query those two. A query asking for all columns with a star will fail and return nothing. That star query only works if the table holds just the allowed columns. Since version 24.10, a trailing star lets you grant rights across matching table names.

What native database roles solve and what they miss

Native database users and column grants solve the first part of access control. They define which account can log in from a specific host. They also limit which tables and columns that account can read. If the agent tries to read a forbidden column, the database stops the query. This keeps the agent out of tables it has no business touching.

Still, static database grants leave a wide operational gap during live sessions. Database roles check who logs in, not what individual statements do in flight. First, the local driver still needs a password or key stored on disk. Any local script or terminal process can read that stored secret. Second, allowed columns often hold live emails, phone numbers, card numbers, or national IDs. Once a column is granted, the database returns those raw values to 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.

Third, static grants cannot ask a human for approval before a risky command runs. If a developer gives the agent write rights for a task, those rights stay active. The agent can alter rows or run heavy queries until an admin revokes the role. Teams also lack a clear log tying each prompt to the exact SQL statement.

Securing agent queries in flight

Running an AI tool against a fast analytics database takes more than static roles. You should start by locking down the database account to specific hosts and columns. Never give the agent an admin user or broad write permissions across a schema. Keep quotas tight so a bad query from the agent cannot starve production workloads.

Next, look at how data moves between the database and the terminal tool. When query results contain emails or card numbers, masking rewrites matched fields in results. This keeps sensitive strings out of model prompts while letting the query finish. Pair this with command review so risky statements wait for a quick human check.

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

Why did a select star query from the agent fail?

If a user only has grants on specific columns, a star query is refused. The database returns no data unless the table holds only the granted columns. Have the agent list the exact allowed column names in its query instead.

Can I restrict which hosts the agent account logs in from?

Yes, the user creation statement lets you set the exact hosts for that user. The database will reject login attempts coming from any other network address. This stops stolen local keys from working on outside machines.

How do I grant the agent read access to a group of tables?

Since version 24.10, you can use a trailing star in your grant statement. This grants read rights across all tables that share the same name prefix. It saves time when the agent needs access to daily or sharded tables.

The query runs. The emails stay hidden.