ClickHouse Security: Implementing Auditing and Log Capture


The objective of this run-book is to guide you through the process of implementing auditing and log capture in ClickHouse. By capturing detailed logs of query executions, user activities, and system events, you can enable forensic investigations, ensure compliance reporting, and monitor potential security threats effectively.

Configure Logging Settings

  1. Open the ClickHouse server configuration file (usually located at /etc/clickhouse-server/config.xml) in a text editor.
  2. Locate the <log> section in the configuration file.
  3. Set the desired log level, such as trace, debug, information, or warning, based on the level of detail you want to capture.
  4. Specify the log path and filename using the <path> and <base> tags. For example:
  1. Save the configuration file and restart the ClickHouse server for the changes to take effect.

Enable Query Log

  1. Open the ClickHouse client configuration file (usually located at ~/.clickhouse-client/config.xml) or create it if it doesn’t exist.
  2. Add the following XML snippet to enable query logging:
  1. Save the configuration file.

Create the Query Log Table

  1. Connect to ClickHouse using the client tool (e.g., clickhouse-client).
  2. Create the query log table by executing the following SQL statement:
CREATE TABLE IF NOT EXISTS default.query_log
event_date Date DEFAULT toDate(now()),
event_time DateTime DEFAULT toDateTime(now()),
user_name String,
query String,
query_id UUID DEFAULT generateUUIDv4()
) ENGINE = MergeTree(event_date, (event_date, event_time), 8192)

Adjust the table name and storage parameters according to your preferences.

  1. Ensure that the user executing the query has sufficient privileges to create tables in the target database.

Audit User Activities and System Events

  1. Determine the events and activities you want to capture in the audit logs. This may include logins, logouts, table creations, alterations, access grants, and other critical actions.
  2. Implement custom audit triggers or hooks in ClickHouse to capture these events. Use the appropriate mechanisms based on your requirements, such as UDFs (User-Defined Functions), system tables, or custom scripts triggered by events.
  3. Within these triggers or hooks, insert relevant information into an audit log table similar to the query log table created in Step 3. Ensure you capture relevant details such as event date, event time, user name, and specific details of the event or activity.

Monitor and Analyze Audit Logs

  1. Regularly monitor the audit logs to identify potential security threats, compliance issues, or unusual activities.
  2. Utilize ClickHouse’s powerful SQL capabilities to perform analysis on the audit logs. For example, you can query the logs to identify suspicious patterns, track user activity, or generate compliance reports.
  3. Implement appropriate visualization tools or reporting mechanisms to make the analysis of audit logs more accessible and actionable.


By following this run-book, you can implement auditing and log capture in ClickHouse effectively. Capturing detailed logs of query executions, user activities, and system events enables you to perform forensic investigations, maintain compliance, and monitor potential security threats. Regularly monitoring and analyzing audit logs in ClickHouse empowers you to ensure the integrity and security of your data analytics environment.

To know more about ClickHouse security, do visit the following articles:

ChistaDATA: Your Trusted ClickHouse Consultative Support and Managed Services Provider. Unlock the Power of Real-Time Analytics with ChistaDATA Cloud( – the World’s Most Advanced ClickHouse DBaaS Infrastructure. Contact us at or (844)395-5717 for tailored solutions and optimal performance.

About Shiv Iyer 226 Articles
Open Source Database Systems Engineer with a deep understanding of Optimizer Internals, Performance Engineering, Scalability and Data SRE. Shiv currently is the Founder, Investor, Board Member and CEO of multiple Database Systems Infrastructure Operations companies in the Transaction Processing Computing and ColumnStores ecosystem. He is also a frequent speaker in open source software conferences globally.