chmonitor only reads ClickHouse system tables — it never issues writes, DDL, or schema changes. Run it under a dedicated read-only user to follow the principle of least privilege and limit the blast radius if credentials are exposed.

This page shows how to create that user on each supported deployment type and how to wire it into the chmonitor env vars.

• Principle of least privilege. chmonitor only needs SELECT on system.* (and optionally on databases you want to explore). Nothing more.
• Credential isolation. A separate chmonitor user means a leaked secret cannot be used to drop tables or modify data.
• Audit trail. All chmonitor queries appear in system.query_log under a distinct user value, making it easy to attribute traffic.

Pick your deployment type.

<Tabs items={["ClickHouse OSS / self-managed", "Altinity Cloud", "ClickHouse Cloud"]}>

Use the SQL console or clickhouse-client as an admin user.

CREATE SETTINGS PROFILE IF NOT EXISTS chmonitor_readonly
SETTINGS readonly = 2,
         max_execution_time = 60,
         allow_ddl = 0,
         allow_introspection_functions = 0;

readonly = 2 blocks all writes and DDL while still letting the client set per-query settings such as max_execution_time — which chmonitor requires. (The stricter readonly = 1 also forbids settings changes, so chmonitor would fail under it; use readonly = 2.) allow_ddl = 0 is redundant under readonly but makes the intent explicit.

CREATE USER IF NOT EXISTS chmonitor
IDENTIFIED BY 'replace-with-a-strong-password'
SETTINGS PROFILE 'chmonitor_readonly';

GRANT SELECT ON system.* TO chmonitor;

If you also want to let chmonitor browse user databases (e.g. via the Explorer page), add grants for those databases:

-- Optional: grant read access to a specific database
GRANT SELECT ON my_database.* TO chmonitor;

Do not grant INSERT, ALTER, DROP, CREATE, or SYSTEM privileges. chmonitor does not need them.

SHOW GRANTS FOR chmonitor;
-- Expected: GRANT SELECT ON system.* TO chmonitor

SELECT * FROM system.users WHERE name = 'chmonitor';

Altinity builds are API-compatible with ClickHouse OSS. The same SQL as the ClickHouse OSS / self-managed tab applies. Run it via the Altinity console SQL editor or through clickhouse-client connecting to your Altinity endpoint.

This covers both Altinity Cloud and Altinity.Cloud Stable.

ClickHouse Cloud uses the same SQL RBAC model. Use the SQL Console in the Cloud UI or connect with an admin credential.

-- 1. Settings profile (same as OSS)
CREATE SETTINGS PROFILE IF NOT EXISTS chmonitor_readonly
SETTINGS readonly = 2,
         max_execution_time = 60,
         allow_ddl = 0;

-- 2. User
CREATE USER IF NOT EXISTS chmonitor
IDENTIFIED BY 'replace-with-a-strong-password'
SETTINGS PROFILE 'chmonitor_readonly';

-- 3. Grant
GRANT SELECT ON system.* TO chmonitor;

Set these environment variables in your deployment (.env, Cloudflare Worker secrets, Kubernetes secret, or Docker env):

For multiple hosts, use comma-separated values — position N in each variable maps to host N:

CLICKHOUSE_HOST=http://ch-1:8123,http://ch-2:8123
CLICKHOUSE_USER=chmonitor,chmonitor
CLICKHOUSE_PASSWORD=secret-1,secret-2
CLICKHOUSE_NAME=Shard 1,Shard 2

See Environment variables for the full variable reference, and Multiple hosts for multi-host setup.

chmonitor issues only SELECT queries against system.* tables and any databases you explicitly grant. It never:

• Inserts, updates, or deletes rows
• Creates or drops tables or databases
• Alters table schemas
• Issues SYSTEM commands (flush, reload, etc.)