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

# ClickHouse accounts

> Add and connect to ClickHouse databases.

ClickHouse accounts let you manage access to a ClickHouse database. Users connect through Web Access or the CLI, and every statement they run is recorded in the [session](/docs/documentation/platform/pam/sessions/overview).

Sessions reach ClickHouse over its HTTP interface, on port 8123 or 8443, rather than the native protocol on 9000. Every request passes through the [gateway](/docs/documentation/platform/gateways/overview) in your own network, and the credential never reaches the client.

## Prerequisites

* A ClickHouse user for Infisical to connect as.
* The HTTP interface enabled on the target. `http_port` (8123) is on by default in a stock ClickHouse configuration. `https_port` (8443) needs a certificate configured, and is what ClickHouse Cloud exposes.
* A [gateway](/docs/documentation/platform/gateways/overview) that can reach that port. A gateway that predates ClickHouse support refuses the session with a version error.

## Creating an account

<Steps>
  <Step title="Start adding an account">
    Go to **Privileged Access Management → Accounts** and select **Add Account**.
  </Step>

  <Step title="Select a folder and template">
    Choose which [folder](/docs/documentation/platform/pam/folders/overview) to add the account to, then select a ClickHouse [template](/docs/documentation/platform/pam/templates/overview).
  </Step>

  <Step title="Enter connection details">
    | Field                   | Description                                                                   |
    | ----------------------- | ----------------------------------------------------------------------------- |
    | **Name**                | A descriptive name (e.g., `analytics-prod`)                                   |
    | **Host**                | ClickHouse host                                                               |
    | **Port**                | The HTTP interface port. 8123 for plain HTTP, 8443 for HTTPS                  |
    | **Database**            | The database sessions open. Web Access lists the tables inside it             |
    | **SSL Enabled**         | Use HTTPS for the connection. Required for port 8443 and for ClickHouse Cloud |
    | **Reject Unauthorized** | Reject connections with invalid certificates (only if SSL enabled)            |
    | **SSL Certificate**     | Custom CA certificate (only if SSL enabled)                                   |
  </Step>

  <Step title="Enter credentials">
    | Field        | Description                                                                  |
    | ------------ | ---------------------------------------------------------------------------- |
    | **Username** | The ClickHouse user sessions connect as. Use `default` for the built-in user |
    | **Password** | The user's password. Leave blank for a user created with `no_password`       |
  </Step>

  <Step title="Save">
    Select **Create**. Infisical signs in to ClickHouse through the gateway and runs one statement to confirm the credential works before saving the account.
  </Step>
</Steps>

## Permissions

What a session can do comes from the ClickHouse grants on the account's user, so grant that user only what the people using the account need. Web Access reads the database, table and column lists from `system.databases`, `system.tables` and `system.columns`, which every user can read for the objects they already have access to.

```sql theme={"dark"}
CREATE USER pam_service IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT ON analytics.* TO pam_service;
```

Every session opens on the account's **Database**, whatever a client asks for. That is a starting point, not a limit: a session can still read any database the user has a grant on, and Web Access lists them all. Scope the grants, not the **Database** field.

Sessions connect with the user's default roles. The gateway drops the `role` URL parameter, which would otherwise activate a role with no statement to record, so use `SET ROLE` instead and it's recorded like any other statement.

Command blocking matches the text of each statement, so a statement that builds SQL at runtime can run something a pattern would otherwise reject. Use ClickHouse grants for restrictions that have to hold.

## Connecting

<Tabs>
  <Tab title="Web Access">
    Web Access provides a browser-based interface with two tools:

    * **Data Explorer** — browse tables, view data, filter and sort, export to CSV/JSON
    * **SQL Editor** — write and run SQL queries

    To connect:

    1. Go to **Privileged Access Management → Accounts**
    2. Find the account and select the rocket icon (or select **Launch Session** from the menu)
    3. Select **Connect in Browser**

    ClickHouse has no schema layer inside a database, so the Data Explorer sidebar lists databases where it lists schemas for other account types.
  </Tab>

  <Tab title="CLI">
    The CLI starts a local proxy that speaks ClickHouse's HTTP interface on `127.0.0.1`. Connect with TLS off and no certificate to trust, since the hop to the gateway is already an encrypted tunnel. The username and password a client sends are ignored, because the gateway authenticates for you.

    ```bash theme={"dark"}
    infisical pam access analytics/clickhouse-prod
    ```

    The command prints the port and a ready-made connection string. JDBC clients such as DBeaver and DataGrip, `clickhouse-connect`, `@clickhouse/client`, and `curl` all speak this interface. `clickhouse-client` and Python's `clickhouse-driver` speak only the native protocol, so they can't use this port.

    ```bash theme={"dark"}
    curl 'http://127.0.0.1:<port>/?query=SELECT+1'
    ```

    **Flags:**

    * `--port <port>` — use a specific local port (otherwise one is assigned automatically)
    * `--reason <reason>` — provide an access reason (if required by template)
  </Tab>
</Tabs>

The Data Explorer shows the first 1,000 rows a statement produces and tells you when there are more, and caps a statement at 30 seconds. Neither limit applies to the CLI, so use it with your own client for a long query or a full result set.

<Note>
  ClickHouse applies row changes as asynchronous mutations rather than as statements that take effect when they return, so the Data Explorer grid is read-only for every table. Run `ALTER TABLE ... UPDATE` or `DELETE FROM` from the SQL Editor instead. The column marked as a key in the grid is the table's sorting key, which ClickHouse calls the primary key: it's an index, not a unique constraint.
</Note>

## Recording

Every statement a session runs is recorded, along with the outcome of each one, and appears under **Session Logs** on the session. Web Access and the CLI both reach ClickHouse through the gateway, so recording works the same for either. Recordings are encrypted with a per-session key and written to the storage backend the [template](/docs/documentation/platform/pam/templates/overview) selects, the same as any other account type.

The template's **Command Blocking** policy applies to ClickHouse as well: a statement matching one of its patterns is rejected before it reaches ClickHouse, and the rejection is recorded. **Session Log Masking** patterns are applied to the recording before it's written.

Applying that policy means reading the statement first, so on an account that blocks commands a request body over one megabyte is refused, and one compressed with anything other than `gzip` or `deflate` is rejected outright. Send large inserts in smaller batches, or use an account without the policy, where the body streams through and only its first megabyte is recorded.

## Next steps

<CardGroup cols={2}>
  <Card title="Sessions" icon="display" href="/docs/documentation/platform/pam/sessions/overview">
    View and manage sessions.
  </Card>

  <Card title="Access requests" icon="user-check" href="/docs/documentation/platform/pam/access-requests/overview">
    Require approval before a session starts.
  </Card>
</CardGroup>