ClickHouse - AnomalyArmor

Connect AnomalyArmor to your ClickHouse database for schema monitoring and freshness tracking. We support both self-hosted ClickHouse and ClickHouse Cloud.

Requirements

ClickHouse version: 21.8 or higher
HTTP interface: Enabled (default on most installations)
User credentials: With read access to system tables
Network access: From AnomalyArmor to your ClickHouse server

Connection Settings

Field	Description	Example
Connection Name	Friendly identifier	`ClickHouse Analytics`
Host	ClickHouse hostname	`xxx.clickhouse.cloud`
Port	HTTP(S) port	`8443` (HTTPS) or `8123` (HTTP)
Database	Database name	`default`
Username	ClickHouse user	`anomalyarmor`
Password	User password	`••••••••`

Port Configuration

Port	Protocol	When to Use
`8443`	HTTPS	ClickHouse Cloud and production
`8123`	HTTP	Development or internal networks
`9440`	Native TLS	Not supported (use HTTP interface)

Always use HTTPS (port 8443) for cloud-hosted or production ClickHouse. HTTP (8123) should only be used for local development.

Provider-Specific Instructions

ClickHouse Cloud
Self-Hosted
Altinity Cloud
Docker/Local

ClickHouse Cloud

Finding Connection Details:

Go to your ClickHouse Cloud console
Select your service
Click Connect → HTTPS
Copy the connection details

Host: abc123.us-east-1.aws.clickhouse.cloud
Port: 8443
Database: default (or your database name)

IP Allowlisting:

Go to Settings → Security
Under IP Access List, add AnomalyArmor IPs
Save changes

Add the AnomalyArmor IP addresses: 34.xxx.xxx.xxx/32 and 34.xxx.xxx.xxx/32Creating a Read-Only User:

-- Create user
CREATE USER anomalyarmor
IDENTIFIED BY 'your-secure-password';

-- Grant read access
GRANT SELECT ON *.* TO anomalyarmor;
GRANT SHOW ON *.* TO anomalyarmor;

-- Access to system tables (required for discovery)
GRANT SELECT ON system.* TO anomalyarmor;

Self-Hosted ClickHouse

Verify HTTP Interface:Check your config.xml has HTTP enabled:

<http_port>8123</http_port>
<!-- or for HTTPS -->
<https_port>8443</https_port>

Firewall Configuration:Allow inbound connections from AnomalyArmor:

# iptables example
iptables -A INPUT -p tcp --dport 8443 -s 34.xxx.xxx.xxx -j ACCEPT
iptables -A INPUT -p tcp --dport 8443 -s 34.xxx.xxx.xxx -j ACCEPT

Creating a Read-Only User:

-- Create user
CREATE USER anomalyarmor
IDENTIFIED BY 'your-secure-password'
HOST IP '34.xxx.xxx.xxx', '34.xxx.xxx.xxx';

-- Grant read access
GRANT SELECT ON *.* TO anomalyarmor;
GRANT SHOW ON *.* TO anomalyarmor;

SSL/TLS Setup (recommended):

<!-- In config.xml -->
<https_port>8443</https_port>
<openSSL>
    <server>
        <certificateFile>/path/to/server.crt</certificateFile>
        <privateKeyFile>/path/to/server.key</privateKeyFile>
    </server>
</openSSL>

Docker / Local Development

Default Connection:

Host: localhost (or container IP)
Port: 8123 (HTTP) or 8443 (HTTPS)
Database: default
Username: default
Password: (empty or as configured)

Docker Compose Example:

services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    ports:
      - "8123:8123"
      - "9000:9000"

For local development, you may need to expose the ClickHouse port publicly or use a tunneling solution for AnomalyArmor to connect.

Creating a Read-Only User

Full SQL script for setting up AnomalyArmor access:

-- Create dedicated user
CREATE USER IF NOT EXISTS anomalyarmor
IDENTIFIED BY 'your-secure-password';

-- Grant read access to all databases
GRANT SELECT ON *.* TO anomalyarmor;

-- Grant ability to see databases and tables
GRANT SHOW ON *.* TO anomalyarmor;

-- Access to system tables (required for discovery)
GRANT SELECT ON system.tables TO anomalyarmor;
GRANT SELECT ON system.columns TO anomalyarmor;
GRANT SELECT ON system.databases TO anomalyarmor;
GRANT SELECT ON system.parts TO anomalyarmor;

-- Optional: Restrict to specific databases
-- GRANT SELECT ON analytics.* TO anomalyarmor;
-- GRANT SELECT ON production.* TO anomalyarmor;

Verify Permissions

Test the user can access metadata:

-- Should work
SELECT database, name, engine FROM system.tables LIMIT 5;

-- Should work
SELECT database, table, name, type FROM system.columns LIMIT 5;

What We Monitor

AnomalyArmor discovers and monitors these ClickHouse objects:

Object Type	Monitored	Notes
Tables	Yes	All table engines
Views	Yes	Standard views
Materialized Views	Yes	Including underlying tables
Dictionaries	No	Coming soon
Functions	No	Not supported

Metadata Captured

For each table:

Database and table name
Column names and data types
Table engine type
Partition information
Last modification time (for freshness)

What We Query

AnomalyArmor runs these types of queries:

-- List databases
SELECT name FROM system.databases
WHERE name NOT IN ('system', 'INFORMATION_SCHEMA', 'information_schema');

-- List tables
SELECT database, name, engine, metadata_modification_time
FROM system.tables
WHERE database NOT IN ('system', 'INFORMATION_SCHEMA');

-- List columns
SELECT database, table, name, type, default_kind, default_expression
FROM system.columns
WHERE database NOT IN ('system', 'INFORMATION_SCHEMA');

-- Check freshness (for tables with timestamp columns)
SELECT MAX(event_time) FROM analytics.events;

Impact: These are lightweight metadata queries. No table scans.

ClickHouse-Specific Considerations

Table Engines

AnomalyArmor works with all ClickHouse table engines:

Engine	Schema Monitoring	Freshness
MergeTree family	Full	Yes
Log family	Full	Limited
Distributed	Full	Via underlying tables
View	Full	N/A
MaterializedView	Full	Yes

ReplicatedMergeTree

For replicated tables, connect to any replica. Schema changes propagate across all replicas, so monitoring one is sufficient.

Distributed Tables

Distributed tables show the schema of the distributed table definition. Underlying shard tables are monitored separately if in the same cluster.

Troubleshooting

Connection refused

Causes:

Wrong port (using native port instead of HTTP)
Firewall blocking connection
HTTP interface disabled

Solutions:

Verify port is 8443 (HTTPS) or 8123 (HTTP)
Check firewall/security group allows AnomalyArmor IPs
Verify HTTP interface is enabled in config.xml
Test: curl https://your-host:8443/ping

Authentication failed

Causes:

Wrong username or password
User doesn’t exist
IP not in user’s allowed hosts

Solutions:

Verify credentials
Check user exists: SELECT * FROM system.users WHERE name = 'anomalyarmor'
Verify IP is allowed: Check user’s HOST restrictions

-- View user's allowed hosts
SELECT name, host_ip, host_names FROM system.users;

SSL certificate error

Causes:

Self-signed certificate not trusted
Certificate hostname mismatch

Solutions:

For ClickHouse Cloud: Should work automatically
For self-hosted: Ensure certificate is valid
Contact support if issues persist with valid certificates

Permission denied

Causes:

User lacks SELECT on system tables
User lacks access to target databases

Solutions:

-- Grant required permissions
GRANT SELECT ON system.* TO anomalyarmor;
GRANT SELECT ON your_database.* TO anomalyarmor;
GRANT SHOW ON *.* TO anomalyarmor;

No tables found

Causes:

User can only see specific databases
All tables in excluded system databases

Solutions:

Grant SHOW privilege: GRANT SHOW ON *.* TO anomalyarmor
Verify tables exist outside system databases
Check AnomalyArmor schema filters

Connection Architecture

Best Practices

Use HTTPS in Production

Always use port 8443 with HTTPS for production:

Encrypted in transit
Required by ClickHouse Cloud
Protects credentials

Connect to One Node

For clustered setups, connect to one node. System tables show cluster-wide metadata.

Schedule Discovery After Mutations

If you have regular schema changes (ALTER TABLE), schedule discovery after those operations complete.

Common Questions

Which ClickHouse versions and deployments does AnomalyArmor support?

ClickHouse 21.8+ self-hosted and ClickHouse Cloud are fully supported. Both use the HTTPS/TCP native protocol on port 8443 (Cloud) or 8123/9000 (self-hosted). Older ClickHouse versions may work for basic monitoring but aren’t officially supported - upgrade if possible.

Does AnomalyArmor support ClickHouse materialized views and dictionaries?

Materialized views are first-class assets (schema drift, freshness, metrics all work). Dictionaries are discovered and cataloged but not actively monitored for freshness; treat them as reference metadata.

Can AnomalyArmor monitor freshness on a ClickHouse `MergeTree` table that uses event-time partitioning?

Yes. Use your event-time column (e.g., event_date, created_at) as the freshness timestamp. AnomalyArmor queries MAX(event_date) which ClickHouse resolves efficiently via partition metadata, even on billion-row tables.

How much load does AnomalyArmor put on my ClickHouse cluster?

Very little. Discovery hits system.tables / system.columns which are metadata tables. Freshness and metrics use MAX / COUNT(*) / uniqExact which ClickHouse optimizes to microseconds on partitioned tables. Expect microseconds-to-low-milliseconds per query.

​Requirements

​Connection Settings

​Port Configuration

​Provider-Specific Instructions

​ClickHouse Cloud

​Self-Hosted ClickHouse

​Altinity Cloud

​Docker / Local Development

​Creating a Read-Only User

​Verify Permissions

​What We Monitor

​Metadata Captured

​What We Query

​ClickHouse-Specific Considerations

​Table Engines

​ReplicatedMergeTree

​Distributed Tables

​Troubleshooting

​Connection Architecture

​Best Practices

​Use HTTPS in Production

​Connect to One Node

​Schedule Discovery After Mutations

​Common Questions

​Which ClickHouse versions and deployments does AnomalyArmor support?

​Does AnomalyArmor support ClickHouse materialized views and dictionaries?

​Can AnomalyArmor monitor freshness on a ClickHouse MergeTree table that uses event-time partitioning?

​How much load does AnomalyArmor put on my ClickHouse cluster?

​Next Steps

Run Discovery

Set Up Alerts

Requirements

Connection Settings

Port Configuration

Provider-Specific Instructions

ClickHouse Cloud

Self-Hosted ClickHouse

Altinity Cloud

Docker / Local Development

Creating a Read-Only User

Verify Permissions

What We Monitor

Metadata Captured

What We Query

ClickHouse-Specific Considerations

Table Engines

ReplicatedMergeTree

Distributed Tables

Troubleshooting

Connection Architecture

Best Practices

Use HTTPS in Production

Connect to One Node

Schedule Discovery After Mutations

Common Questions

Which ClickHouse versions and deployments does AnomalyArmor support?

Does AnomalyArmor support ClickHouse materialized views and dictionaries?

Can AnomalyArmor monitor freshness on a ClickHouse `MergeTree` table that uses event-time partitioning?

How much load does AnomalyArmor put on my ClickHouse cluster?

Next Steps