ClickHouse Setup

Basira requires a dedicated database user with read access to system tables that expose query performance, merge operations, and cluster health.

1. Create Monitoring User

Connect to your ClickHouse instance and create a read-only monitoring user:

CREATE USER basira_monitor IDENTIFIED BY 'your-secure-password';

Grant read access to the system tables the agent needs:

GRANT SELECT ON system.* TO basira_monitor;

If you want to restrict access to only the specific tables Basira reads:

GRANT SELECT ON system.processes TO basira_monitor;
GRANT SELECT ON system.query_log TO basira_monitor;
GRANT SELECT ON system.settings TO basira_monitor;
GRANT SELECT ON system.parts TO basira_monitor;
GRANT SELECT ON system.merges TO basira_monitor;
GRANT SELECT ON system.mutations TO basira_monitor;

Also grant access to any user databases you want the agent to monitor:

GRANT SELECT ON my_database.* TO basira_monitor;

Verify

SELECT currentUser();
-- Should return 'basira_monitor'

SELECT count(*) FROM system.processes;
-- Should return without permission errors

2. Enable query_log

ClickHouse logs completed queries to system.query_log by default. Verify it is enabled in your config.xml or users.xml:

<query_log>
    <database>system</database>
    <table>query_log</table>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
</query_log>

Most ClickHouse installations have this enabled out of the box. If system.query_log is empty, check that log_queries is set to 1 for the relevant user profiles.

Verify

Run a query, wait a few seconds, then:

SELECT count(*) FROM system.query_log WHERE event_date = today();

3. Supported Versions

Basira supports ClickHouse 21.8 and later. The agent uses normalized_query_hash (available since 21.8) for query fingerprinting.

4. Network Access

Ensure the Basira agent can reach your ClickHouse instance:

• Native protocol: The agent connects via the ClickHouse native protocol (default port 9000). Make sure this port is accessible from the agent's network
• Cloud providers: Add the agent's security group or VPC to your ClickHouse instance's allowed connections
• SSL/TLS: Use secure=true in the DSN for encrypted connections: clickhouse://basira_monitor:pass@host:9440/default?secure=true

5. DSN Format

The agent connects using the ClickHouse native protocol. DSN format:

clickhouse://basira_monitor:your-secure-password@host:9000/default

For TLS-enabled connections:

clickhouse://basira_monitor:your-secure-password@host:9440/default?secure=true

Next Steps

Once your database is configured, install the Basira agent and point it at your ClickHouse instance. For monitoring multiple databases with a single agent, see Multi-Database Setup.