# Setup: ClickHouse

ClickHouse is only used in **watch mode**. Epimetheus creates the metrics table automatically if it does not exist.

## Running ClickHouse

- **Linux (systemd):** `sudo systemctl start clickhouse-server`
- **Docker:** Use the official [ClickHouse image](https://hub.docker.com/r/clickhouse/clickhouse-server) and expose the HTTP interface (default port 8123).
- **Kubernetes:** Deploy ClickHouse and expose a Service; use the HTTP URL (e.g. `http://clickhouse.monitoring.svc.cluster.local:8123`) as `-clickhouse`.

Default HTTP port is **8123**. Epimetheus uses the HTTP interface, not the native protocol.

## Table Creation

You do not need to create the table manually. On first ingest, Epimetheus runs:

```sql
CREATE TABLE IF NOT EXISTS epimetheus_metrics (
    metric String,
    labels Map(String, String),
    value Float64,
    timestamp DateTime64(3)
) ENGINE = MergeTree()
ORDER BY (metric, timestamp)
```

To use a different table name, set `-clickhouse-table`.

## Verification

After running watch mode with `-clickhouse` set, verify ingestion:

```bash
./scripts/verify-clickhouse.sh
```

With custom URL or table:

```bash
./scripts/verify-clickhouse.sh http://localhost:8123 epimetheus_metrics
```

The script checks connectivity (`/ping`), row count, distinct metrics, sample rows, and rows per metric. If the table is empty or missing, it prints a reminder command to run Epimetheus in watch mode with `-clickhouse`. See [ClickHouse backend](../backends/clickhouse.md) for usage.