How to Configure LangChain ClickHouse Audit Log

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a langchain clickhouse audit log by giving the agent a dedicated database user. Then you record its activity in the server system tables and agent callbacks. Most teams start by sharing one database login across all their AI apps. That broad role lets a single bad prompt read or change way too much data. How a langchain clickhouse audit log works in practice A good audit setup starts with how ClickHouse manages its users and roles. ClickHouse stores users, roles, row rules, setting

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 langchain clickhouse audit log by giving the agent a dedicated database user. Then you record its activity in the server system tables and agent callbacks. Most teams start by sharing one database login across all their AI apps. That broad role lets a single bad prompt read or change way too much data.

How a langchain clickhouse audit log works in practice

A good audit setup starts with how ClickHouse manages its users and roles. ClickHouse stores users, roles, row rules, settings, and quotas as SQL access items. To turn this on, the server needs a storage folder for access files. It also needs at least one admin user who holds the right to manage access. A user can only hand out the permissions that they already hold themselves.

For an AI agent, you should create a dedicated database user with SQL. That user setup defines the login method, allowed host addresses, default roles, and user settings. Giving the LangChain app its own user separates agent queries from human queries. When the database logs a query, you see the agent user name right away. You do not have to guess whether a person or a bot ran the query.

Next, you restrict what tables and columns that agent user can read. ClickHouse lets you grant read access on specific columns of a table. If an agent only needs two columns, you grant read rights on those two alone. The agent can then run queries that ask for only those allowed columns. If the agent tries to select all columns with a star, the database refuses it. It returns no data at all unless the table holds only those granted columns. You can also grant read rights across a group of tables using a name prefix.

How LangChain agents build and run database queries

On the app side, a LangChain agent pairs a chat model with database tools. The agent reads a user question in plain words and picks which tool to call. It turns the question into a SQL query, runs it, and returns the answer. You can also limit which tables the agent sees in its tool settings.

To build the app side of your audit trail, you use LangChain callback handlers. Callbacks catch the start and end of every chain step, model prompt, and tool call. When the agent decides to run a query, the callback writes that event out. Your team can send those events to a log file or a central log store. You should log the input prompt, the chosen tool, and the generated SQL string.

Audit Log Integrity + ClickHouse Access Management: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native logging solves and where the gaps remain

Combining dedicated database users with app callbacks gives you a solid baseline record. ClickHouse records which user ran each query and how much time it took. Meanwhile, LangChain records which prompt caused the model to write that specific SQL statement. Together, these logs help you trace a strange database load back to a chat prompt.

Still, native logs and static user grants still leave big operational gaps open. Static database roles decide who can log in, not what a live query does. Even with column grants, an allowed column might hold emails, phone numbers, or card numbers. If an agent selects that column, raw personal data flows right into the model context. From there, sensitive records also end up saved inside your plain text app logs.

Splitting logs between the app and the database also makes security audits slow. App logs can break when a developer changes code or forgets a callback setting. Database logs show the SQL text, but they miss the human identity behind the chat. Teams need a unified way to check queries in flight and rewrite matched fields in results.

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 does a star query fail for a restricted ClickHouse agent user?

ClickHouse blocks star queries when a user only has grants on specific columns. The query returns nothing unless the table contains only the columns that user can read.

Should multiple LangChain agents share the same ClickHouse login?

No, each agent should have its own ClickHouse user and role. Separate users make it easy to see which app ran a bad query in the logs.

What happens if an agent reads a column with personal data?

Native column grants are all or nothing for each column. If you grant access to a column with emails or card numbers, the model gets raw data unless you mask results in flight.

The query runs. The emails stay hidden.