ClickHouse

Connect AnomalyArmor to ClickHouse databases

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

ClickHouse Cloud

Finding Connection Details:

1. Go to your ClickHouse Cloud console
2. Select your service
3. Click Connect → HTTPS
4. Copy the connection details

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

IP Allowlisting:

1. Go to Settings → Security
2. Under IP Access List, add AnomalyArmor IPs
3. Save changes

Add the AnomalyArmor IP addresses: 34.xxx.xxx.xxx/32 and 34.xxx.xxx.xxx/32

Creating 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

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>

Altinity Cloud

Altinity Cloud

Altinity Cloud is a managed ClickHouse service:

Connection Details:

1. Go to your Altinity Cloud cluster
2. Find connection details in the cluster overview
3. Use the HTTPS endpoint

IP Allowlisting:

Add AnomalyArmor IPs to your cluster’s allowed networks in the Altinity console.

User Setup:

Same as self-hosted ClickHouse. Create a read-only user through the Altinity console or SQL.

Docker/Local

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:

1. Verify port is 8443 (HTTPS) or 8123 (HTTP)
2. Check firewall/security group allows AnomalyArmor IPs
3. Verify HTTP interface is enabled in config.xml
4. 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:

1. Verify credentials
2. Check user exists: SELECT * FROM system.users WHERE name = 'anomalyarmor'
3. 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:

1. For ClickHouse Cloud: Should work automatically
2. For self-hosted: Ensure certificate is valid
3. 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:

1. Grant SHOW privilege: GRANT SHOW ON *.* TO anomalyarmor
2. Verify tables exist outside system databases
3. 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.

Next Steps

Run Discovery

Scan your ClickHouse database

Set Up Alerts

Get notified of schema changes