> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anomalyarmor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse

> Connect AnomalyArmor to ClickHouse databases

<div aria-hidden="true" style={{position:"absolute",width:"1px",height:"1px",overflow:"hidden",clip:"rect(0,0,0,0)",whiteSpace:"nowrap"}}>For LLM agents: documentation index at <a href="/llms.txt" tabIndex={-1}>/llms.txt</a>, full text at <a href="/llms-full.txt" tabIndex={-1}>/llms-full.txt</a>. Append .md to any page URL for plain markdown.</div>
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)  |

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

## Provider-Specific Instructions

<Tabs>
  <Tab title="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**:

    ```sql theme={null}
    -- 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;
    ```
  </Tab>

  <Tab title="Self-Hosted">
    ### Self-Hosted ClickHouse

    **Verify HTTP Interface**:

    Check your `config.xml` has HTTP enabled:

    ```xml theme={null}
    <http_port>8123</http_port>
    <!-- or for HTTPS -->
    <https_port>8443</https_port>
    ```

    **Firewall Configuration**:

    Allow inbound connections from AnomalyArmor:

    ```bash theme={null}
    # 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**:

    ```sql theme={null}
    -- 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):

    ```xml theme={null}
    <!-- In config.xml -->
    <https_port>8443</https_port>
    <openSSL>
        <server>
            <certificateFile>/path/to/server.crt</certificateFile>
            <privateKeyFile>/path/to/server.key</privateKeyFile>
        </server>
    </openSSL>
    ```
  </Tab>

  <Tab title="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.
  </Tab>

  <Tab title="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**:

    ```yaml theme={null}
    services:
      clickhouse:
        image: clickhouse/clickhouse-server:latest
        ports:
          - "8123:8123"
          - "9000:9000"
    ```

    <Note>
      For local development, you may need to expose the ClickHouse port publicly or use a tunneling solution for AnomalyArmor to connect.
    </Note>
  </Tab>
</Tabs>

## Creating a Read-Only User

Full SQL script for setting up AnomalyArmor access:

```sql theme={null}
-- 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:

```sql theme={null}
-- 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:

```sql theme={null}
-- 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

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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

    ```sql theme={null}
    -- View user's allowed hosts
    SELECT name, host_ip, host_names FROM system.users;
    ```
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Permission denied">
    **Causes**:

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

    **Solutions**:

    ```sql theme={null}
    -- Grant required permissions
    GRANT SELECT ON system.* TO anomalyarmor;
    GRANT SELECT ON your_database.* TO anomalyarmor;
    GRANT SHOW ON *.* TO anomalyarmor;
    ```
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Connection Architecture

<img src="https://mintcdn.com/anomalyarmor/mPQTTzz5PYy4fThA/images/diagrams/clickhouse-connection-light.svg?fit=max&auto=format&n=mPQTTzz5PYy4fThA&q=85&s=48e8c0842b197ca92401fc8c91d59c18" alt="ClickHouse Connection Architecture" className="block dark:hidden" width="700" height="450" data-path="images/diagrams/clickhouse-connection-light.svg" />

<img src="https://mintcdn.com/anomalyarmor/pPIiSU0b3Ixsp9az/images/diagrams/clickhouse-connection-dark.svg?fit=max&auto=format&n=pPIiSU0b3Ixsp9az&q=85&s=e0ab72e3cba4359bf6f67e13a415025f" alt="ClickHouse Connection Architecture" className="hidden dark:block" width="700" height="450" data-path="images/diagrams/clickhouse-connection-dark.svg" />

## 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.

## Next Steps

<CardGroup cols={2}>
  <Card title="Run Discovery" icon="magnifying-glass" href="/quickstart/run-first-discovery">
    Scan your ClickHouse database
  </Card>

  <Card title="Set Up Alerts" icon="bell" href="/quickstart/set-up-first-alert">
    Get notified of schema changes
  </Card>
</CardGroup>