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

# ClickHouse

> Query your own ClickHouse instance directly from Evidence without syncing data.

The ClickHouse direct connector lets Evidence run queries live against your own ClickHouse instance — ClickHouse Cloud, self-hosted, or any other deployment exposing the HTTP(S) interface.

<Note>
  This is the **direct** connector — it points Evidence at a ClickHouse instance **you own**. It's distinct from Evidence's built-in managed warehouse (which also runs on ClickHouse under the hood).
</Note>

## Connecting

You only need three things: the **host**, a **username**, and a **password** (or a JWT access token for ClickHouse Cloud).

<Steps>
  <Step title="Find your connection details">
    **ClickHouse Cloud:** open your service in the Cloud console and click **Connect**. Copy the **host** (e.g. `abc123.us-east-1.aws.clickhouse.cloud`) and the **password** for the `default` user. Use port `8443` (HTTPS).

    **Self-hosted:** use the host and port configured for your instance. The HTTP interface defaults to port `8123`, or `8443` when TLS is enabled.
  </Step>

  <Step title="Configure the connector in Evidence">
    Go to **Connectors** in the sidebar, choose **ClickHouse** in the **Warehouse** card, and fill in the form. Leave **Use TLS** on for Cloud; turn it off only for a plain-HTTP self-hosted instance.
  </Step>

  <Step title="(Optional) Restrict the schema browser">
    Add database names to **Databases** to limit which ones appear in the schema browser. Leave empty to show just the connection's default database.
  </Step>

  <Step title="Test and save">
    Click **Test Connection**. Once it passes, click **Save**.
  </Step>
</Steps>

### Create a dedicated read-only user

The setup above will work with the `default` user, but for production you should give Evidence its own credentials with `SELECT`-only access. In the SQL console (or via `clickhouse-client`):

```sql theme={null}
CREATE USER evidence IDENTIFIED WITH sha256_password BY '<strong-password>';

CREATE ROLE evidence_reader;
GRANT SELECT ON <database>.* TO evidence_reader;
GRANT evidence_reader TO evidence;
ALTER USER evidence DEFAULT ROLE evidence_reader;
```

For ClickHouse Cloud, run this from the **SQL console** in the Cloud UI.

## Configuration reference

<Tabs>
  <Tab title="Studio">
    #### Credentials

    <ResponseField name="Host" type="string" required>
      ClickHouse HTTP(S) interface hostname, e.g. abc123.us-east-1.aws.clickhouse.cloud.
    </ResponseField>

    <ResponseField name="Port" type="number">
      HTTP(S) interface port — 8443 for TLS (the ClickHouse Cloud default), 8123 for plain HTTP. Default: `8443`.
    </ResponseField>

    <ResponseField name="Use TLS" type="boolean">
      Connect over HTTPS. Leave on for ClickHouse Cloud; turn off for a plain-HTTP self-hosted instance. Default: `true`.
    </ResponseField>

    <ResponseField name="Username" type="string">
      ClickHouse user to connect as. Default: `"default"`.
    </ResponseField>

    <ResponseField name="Password" type="string">
      Password for the ClickHouse user.
    </ResponseField>

    <ResponseField name="Access token (JWT)" type="string">
      JWT access token. Supported by ClickHouse Cloud only; mutually exclusive with password.
    </ResponseField>

    <ResponseField name="Database" type="string">
      Default database for unqualified table references. Default: `"default"`.
    </ResponseField>

    #### Visibility

    <ResponseField name="Databases" type="string[]">
      Allowlist of databases exposed to the editor and schema browser. Defaults to the connection database when empty. Default: `[]`.
    </ResponseField>
  </Tab>

  <Tab title="CLI (connection.yaml)">
    ```yaml theme={null}
    type: clickhouse
    host: abc123.us-east-1.aws.clickhouse.cloud
    # port: 8443
    # secure: true
    # username: default
    # database: default
    # databases: [analytics, reporting]
    ```

    #### Credentials

    *Provide exactly one of `password`, `access_token`.*

    <ResponseField name="host" type="string" required>
      ClickHouse HTTP(S) interface hostname, e.g. abc123.us-east-1.aws.clickhouse.cloud.
    </ResponseField>

    <ResponseField name="port" type="number">
      HTTP(S) interface port — 8443 for TLS (the ClickHouse Cloud default), 8123 for plain HTTP. Default: `8443`.
    </ResponseField>

    <ResponseField name="secure" type="boolean">
      Connect over HTTPS. Leave on for ClickHouse Cloud; turn off for a plain-HTTP self-hosted instance. Default: `true`.
    </ResponseField>

    <ResponseField name="username" type="string">
      ClickHouse user to connect as. Default: `"default"`.
    </ResponseField>

    <ResponseField name="password" type="string">
      Password for the ClickHouse user.
    </ResponseField>

    <ResponseField name="access_token" type="string">
      JWT access token. Supported by ClickHouse Cloud only; mutually exclusive with password.
    </ResponseField>

    <ResponseField name="database" type="string">
      Default database for unqualified table references. Default: `"default"`.
    </ResponseField>

    #### Visibility

    <ResponseField name="databases" type="string[]">
      Allowlist of databases exposed to the editor and schema browser. Defaults to the connection database when empty. Default: `[]`.
    </ResponseField>
  </Tab>
</Tabs>

## Row-Level Security

Any [row policies](https://clickhouse.com/docs/sql-reference/statements/create/row-policy) defined in your ClickHouse instance apply to queries issued by Evidence. Policies evaluate against the connection-level user — the credentials configured for the warehouse — rather than the individual Evidence viewer.

<Note>
  **Per-viewer row-level security is planned for an upcoming release.** Evidence will propagate each viewer's identity to ClickHouse, allowing row policies to filter results on a per-user basis. To discuss your requirements or request early access, contact [support@evidence.dev](mailto:support@evidence.dev).
</Note>

## Security Considerations

Evidence executes queries against your ClickHouse instance. Take pragmatic steps to protect it against misuse, whether accidental or malicious.

1. Use a dedicated user with `SELECT`-only grants (see [above](#create-a-dedicated-read-only-user)). Avoid reusing the `default` account in production.
2. Scope `GRANT SELECT` to the specific databases (or tables) Evidence should see — not `*.*`.
3. Cap query cost via a [settings profile](https://clickhouse.com/docs/operations/settings/settings-profiles) on the user — `max_execution_time`, `max_memory_usage`, `max_rows_to_read` are a good baseline. Avoid `readonly = 1`; it blocks the per-query setting Evidence uses for number formatting. Use `readonly = 2` if you want a read-only enforcement at the profile level (it still allows the client to override session settings).
4. For ClickHouse Cloud, restrict the service's [IP access list](https://clickhouse.com/docs/cloud/security/setting-ip-filters) to Evidence's [egress IPs](/core-concepts/data-sources#ip-whitelisting) plus your team's networks.
5. Monitor the [query log](https://clickhouse.com/docs/operations/system-tables/query_log) and alert on non-`SELECT` statements issued by the Evidence user (there shouldn't be any).