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

# ClickHouse

> Connect ClickHouse to give ewake access to your distributed traces for latency analysis and root cause investigation.

<Info>
  **What you'll get:** ewake can query the traces you store in ClickHouse with SQL, discover your schema automatically, and correlate latency or errors with alerts and deployments, without requiring manual query construction.
</Info>

***

## Prerequisites

* A ClickHouse deployment (ClickHouse Cloud or self-hosted) holding your trace data
* The **HTTP interface** reachable from ewake (port `8443` for HTTPS, `8123` for plain HTTP)
* Access to run `CREATE USER` and `GRANT` — an admin user, or the SQL console on ClickHouse Cloud

<Note>
  ewake never assumes a fixed schema. It reads `system.tables` and `system.columns` to discover your trace tables and their column types on every investigation, then writes SQL against what it actually finds, so a homegrown schema works without any naming convention.
</Note>

***

## Configuration

<Steps>
  <Step title="Create a dedicated read-only user">
    Create a user for ewake in SQL and grant it `SELECT` on your trace tables plus `system.tables` and `system.columns` — and nothing else.

    ```sql theme={null}
    -- A dedicated user for ewake, read-only.
    CREATE USER ewake IDENTIFIED WITH sha256_password BY '<strong-password>'
      SETTINGS readonly = 1,
               max_execution_time   = 30           MAX 30           CHANGEABLE_IN_READONLY,
               max_result_rows      = 1000         MAX 1000         CHANGEABLE_IN_READONLY,
               max_bytes_to_read    = 10000000000  MAX 10000000000  CHANGEABLE_IN_READONLY,
               max_memory_usage     = 2000000000   MAX 2000000000   CHANGEABLE_IN_READONLY,
               result_overflow_mode = 'break'                       CHANGEABLE_IN_READONLY;

    -- SELECT on your trace tables, and on the two system tables ewake reads to discover your schema.
    GRANT SELECT ON <database>.<your_trace_table> TO ewake;
    GRANT SELECT ON system.tables  TO ewake;
    GRANT SELECT ON system.columns TO ewake;
    ```

    <Note>
      **Why the grants, not just `readonly`.** The `SELECT` grants are the real boundary: they let ewake read your schema and traces while blocking the table functions (`url`, `remote`, `file`, `mysql`, `postgresql`) and `system.query_log` that a broad user could use to reach out of the database. `readonly = 2` does **not** restrict those, so ewake relies on the grants instead. Grant each trace table by name rather than a whole database.
    </Note>

    <Note>
      **Why `readonly = 1` with `CHANGEABLE_IN_READONLY`.** ewake sends bounded caps on every query as URL settings. `readonly = 1` rejects *any* setting change, so those five are re-allowed as bounded, session-settable values via `CHANGEABLE_IN_READONLY` — every other setting stays forbidden. Keep each `MAX` at or above the value ewake sends: a `MAX` below it makes ClickHouse reject the query outright.
    </Note>

    This SQL setup works on both self-hosted ClickHouse and ClickHouse Cloud, which has no server config files.
  </Step>

  <Step title="Get your HTTP endpoint">
    **ClickHouse Cloud:** find the HTTPS endpoint in your service under **Connect** — it looks like `https://<id>.<region>.clickhouse.cloud:8443`.

    **Self-hosted:** use the base URL of the HTTP interface (e.g. `https://clickhouse.yourcompany.com:8443`, or `http://…:8123` without TLS).
  </Step>

  <Step title="Open the ClickHouse integration in ewake">
    In your ewake dashboard, go to **Integrations** → **ClickHouse** → click **Connect with API key**.
  </Step>

  <Step title="Enter your credentials">
    | Field                   | Value                                               |
    | ----------------------- | --------------------------------------------------- |
    | **ClickHouse HTTP URL** | The HTTP endpoint from Step 2                       |
    | **Database**            | The database holding your trace data (e.g. `otel`)  |
    | **Username**            | The read-only user created in Step 1 (e.g. `ewake`) |
    | **Password**            | The password for that user — stored encrypted       |

    <Note>
      If your ClickHouse sits behind an authenticating proxy (e.g. Cloudflare Access), add its service-token headers under **Custom headers** — ewake sends them with every request.
    </Note>
  </Step>

  <Step title="Test and save">
    Click **Test connection** to verify the connection, then click **Save**. The test checks that the credentials are accepted and that the user can list its granted tables.

    <Check>
      ClickHouse is connected. Ewake can now query your traces during investigations.
    </Check>
  </Step>
</Steps>

***

## Behind Cloudflare Access or a proxy

If your ClickHouse endpoint sits behind an authenticating proxy, add the credentials it expects under **Custom headers** in the same dialog.

For a Cloudflare Access service token that means two headers:

| Header                    | Value                             |
| ------------------------- | --------------------------------- |
| `CF-Access-Client-Id`     | The service token's client ID     |
| `CF-Access-Client-Secret` | The service token's client secret |

Ewake sends these with every request. Values are stored encrypted, and are not shown again after saving, leaving the fields empty when you edit the connection keeps the headers you already saved.

<Note>
  Without this, a connection test against a proxied endpoint fails with an authentication or redirect error even though the URL and API key are both correct. It's the most common cause of a test failing on a working instance.
</Note>

***

<Note>
  ewake queries ClickHouse in **read-only** mode over the HTTP interface. It never writes rows or modifies your ClickHouse configuration, and it caps every query's runtime, row count and bytes read.
</Note>