--- title: "Configure the ClickHouse data source | Grafana Plugins documentation" description: "Configure the ClickHouse data source for Grafana, including connection, TLS, logs, traces, and provisioning" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Configure the ClickHouse data source This page explains how to configure the ClickHouse data source, including connection settings, TLS, logs and traces column mappings, and provisioning. ## Before you begin Before configuring the data source, ensure you have: - **Grafana permissions:** Organization administrator role. - **Plugin:** The ClickHouse data source plugin installed. For Grafana version compatibility, see [Requirements](/docs/plugins/grafana-clickhouse-datasource/latest/#requirements). - **ClickHouse:** A running ClickHouse server and a user with read-only access (or the permissions described below). - **Network access:** The Grafana server can reach the ClickHouse server on the intended port (HTTP: 8123 or 8443 with TLS; Native: 9000 or 9440 with TLS). > Note > > **Grafana Cloud users:** If your ClickHouse server is behind a firewall, you must allowlist the Grafana Cloud outbound IP addresses so that queries can reach your database. For the current list of IPs, refer to [Allow Grafana Cloud outbound traffic](/docs/grafana-cloud/account-management/allow-traffic/). > > The published list covers standard outbound IPs but may not include every address used by your specific Grafana Cloud stack. If connections are still blocked after allowlisting the documented IPs, check your firewall or ClickHouse server logs for the rejected source addresses and [open a support ticket](/profile/org#support) so the Grafana team can confirm the full set of IPs for your stack. ## ClickHouse user and permissions Grafana executes queries exactly as written and does not validate or restrict SQL. Use a **read-only ClickHouse user** for this data source to avoid accidental or destructive operations (such as modifying or deleting tables) while still allowing dashboards and queries to run. If your ClickHouse administrator has already given you a read-only user and connection details, you can skip to [Add the data source](#add-the-data-source). ### Recommended permissions Create a ClickHouse user with: - **readonly** permission enabled - Access limited to the databases and tables you intend to query - Permission to modify the **max\_execution\_time** setting (required by the plugin’s client) > Warning > > Grafana does not prevent execution of non-read queries. If the ClickHouse user has sufficient privileges, statements such as `DROP TABLE` or `ALTER TABLE` will be executed by ClickHouse. ### Configure a read-only user To configure a suitable read-only user: 1. Create a user or profile using [Creating users and roles in ClickHouse](https://clickhouse.com/docs/en/operations/access-rights). 2. Set `readonly = 1` for the user or profile. For details, see [Permissions for queries (readonly)](https://clickhouse.com/docs/en/operations/settings/permissions-for-queries#readonly). 3. Allow modification of the **max\_execution\_time** setting, which is required by the [clickhouse-go](https://github.com/ClickHouse/clickhouse-go/) client so the plugin can enforce query timeouts. #### Required SETTINGS permissions The plugin’s underlying client ([clickhouse-go](https://github.com/ClickHouse/clickhouse-go/)) sets certain ClickHouse `SETTINGS` on each query. If the ClickHouse user does not have permission to modify these settings, queries will fail at runtime even though the **Save & test** check may pass. At a minimum the user must be allowed to change the following settings: Expand table | Setting | Why the plugin needs it | |--------------------------|-----------------------------------------------------------| | **max\_execution\_time** | Enforces the query timeout configured in the data source. | When `readonly = 1` is set, ClickHouse blocks all setting changes by default. To allow the required settings without disabling read-only mode: 1. Create a [settings profile or constraint](https://clickhouse.com/docs/en/operations/settings/constraints-on-settings) for the Grafana user. 2. Set the constraint type for each required setting to **changeable\_in\_readonly**. Example (SQL): SQL ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sql -- Allow the grafana_reader profile to modify max_execution_time while remaining read-only ALTER SETTINGS PROFILE grafana_reader SETTINGS readonly = 1, SETTINGS max_execution_time CHANGEABLE_IN_READONLY; ``` If you see errors such as `DB::Exception: Cannot modify 'max_execution_time': Setting is locked` at query time, the user is missing this permission. Refer to [Troubleshoot ClickHouse data source issues](/docs/plugins/grafana-clickhouse-datasource/latest/troubleshooting/) for more details. > Note > > If you use a **public ClickHouse instance**, do not set `readonly = 2`. Keep `readonly = 1` and use the `changeable_in_readonly` constraint described above. ## ClickHouse protocol support The data source supports two transport protocols: **Native** (default) and **HTTP**. Both support the same query capabilities. The Native protocol uses ClickHouse’s binary TCP interface for better performance. HTTP uses the ClickHouse HTTP interface, which is useful when your network requires HTTP-based connectivity (for example, through a reverse proxy or load balancer). ### Default ports Expand table | Protocol | TLS | Port | |----------|-----|------| | HTTP | No | 8123 | | HTTP | Yes | 8443 | | Native | No | 9000 | | Native | Yes | 9440 | When you enable **Secure connection** in Grafana, you must also set the port to a TLS-enabled port. Grafana does not change the port automatically when TLS is toggled on. ## Add the data source To add the data source: 1. Click **Connections** in the left-side menu. 2. Click **Add new connection**. 3. Type **ClickHouse** in the search bar. 4. Select **ClickHouse**. 5. Click **Add new data source**. ## Configure settings After adding the data source, configure the following settings. ### Server settings Expand table | Setting | Description | |----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Name** | The name used to refer to the data source in panels and queries. | | **Default** | Toggle to make this the default data source for new panels. | | **Server address** | The ClickHouse server host (for example, `localhost`). | | **Protocol** | **Native** or **HTTP**. | | **Port** | Port number; depends on protocol and whether TLS is enabled (see default ports above). | | **Secure connection** | Enable when your ClickHouse server uses TLS. When enabled, update the **Port** to a TLS-enabled port and configure [TLS settings](#tls-settings) below. | | **Username** | ClickHouse user name. Use a [read-only user](#clickhouse-user-and-permissions). | | **Password** | ClickHouse user password. | | **Forward OAuth Identity** | Forward the logged-in Grafana user’s OAuth token to ClickHouse as a JWT instead of authenticating with the configured username and password. ClickHouse Cloud only; requires a [secure (TLS) connection](#tls-settings). See [Forward OAuth Identity](#forward-oauth-identity). | | **Default database** | The database the query builder uses when no database is selected. If left blank, the plugin defaults to `default`. | | **Default table** | The default table used by the query builder. | ### Default database guidance The **Default database** setting controls which database the query builder and ad hoc filters use when no database is explicitly specified. - **Self-hosted ClickHouse:** Set this to the database you query most often so that the query builder pre-selects it. - **ClickHouse Cloud:** Leave this field **blank**. ClickHouse Cloud connections already route to the correct default database for your service. Setting an explicit value can cause `Unknown database` errors if the name does not match the service’s configured database. If you are unsure which database to use, leave the field blank and select a database per query in the query builder. ### HTTP settings The following settings appear only when **Protocol** is set to **HTTP**: Expand table | Setting | Description | |----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **HTTP URL Path** | Additional URL path appended to HTTP requests (for example, `/clickhouse`). Defaults to `/`. | | **Custom HTTP headers** | Static headers sent with every request. Each header has a name, value, and an optional **Secure** toggle that stores the value in encrypted storage. | | **Forward Grafana HTTP headers** | When enabled, forwards Grafana request headers (such as authentication headers) to ClickHouse. Enables multi-connection mode so each unique set of forwarded headers gets its own connection. | ### TLS settings When **Secure connection** is enabled, the following TLS settings become available: Expand table | Setting | Description | |---------------------|--------------------------------------------------------------------------------------------------------------------------------| | **Skip TLS Verify** | Skip server certificate verification. Use only for testing; not recommended for production. | | **TLS Client Auth** | Enable mutual TLS (mTLS) by providing a client certificate and key. | | **With CA Cert** | Provide a custom CA certificate for verifying the ClickHouse server’s TLS certificate (required for self-signed certificates). | | **CA Cert** | PEM-encoded CA certificate. | | **Client Cert** | PEM-encoded client certificate (required when TLS Client Auth is enabled). | | **Client Key** | PEM-encoded client private key (required when TLS Client Auth is enabled). | ### Configuration mode Use **Configuration mode** to choose how the data source is used by the query builder. Expand table | Mode | Description | |-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | **All databases** | Allows queries against any database and table the ClickHouse user can read. Use this mode for general exploration and dashboards that query multiple tables. | | **Single source** | Focuses the data source on one logs or traces table. Choose a **Signal type**, then configure the database, table, and column mappings for that source. | Use **Single source** when the data source is dedicated to one logs or traces table, such as an OpenTelemetry table. This keeps the logs or traces schema settings with the selected source and avoids reconfiguring column mappings in each query. Single source data sources use the [compact query mode](/docs/plugins/grafana-clickhouse-datasource/latest/query-editor/#compact-query-mode) in the query editor. ### Additional settings Expand table | Setting | Description | |---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Dial Timeout** | Timeout in seconds for establishing a connection. Default: `10`. | | **Query Timeout** | Timeout in seconds for read queries. Default: `60`. | | **Connection Max Lifetime** | Maximum lifetime of a pooled connection, in minutes. Default: `5`. | | **Max Idle Connections** | Maximum number of idle connections kept in the pool. Default: `25`. | | **Max Open Connections** | Maximum number of open connections in the pool. Default: `50`. | | **Validate SQL** | When enabled, validates SQL syntax in the query editor. | | **Enable row limit** | The plugin always limits query results to the Grafana row limit setting (default `1000000` rows). When enabled, the plugin also applies the limit on the ClickHouse server, so excess rows are not sent over the network. | | **Row Capacity Hint** | Optional expected row count for pre-allocating result frames. When set, the plugin pre-sizes each response frame to this many rows, which avoids repeated memory allocation on large results. Leave at `0` (the default, disabled) unless queries from this data source reliably return a similar, large number of rows. A value larger than the typical result wastes memory. Values above `1000000` are clamped. | | **Suggest Map keys in filter editor** | When enabled, the filter editor probes `Map(...)` columns for distinct keys to populate key suggestions. On large tables with high-cardinality maps this probe can scan a very large number of rows, so disable it to suppress the probe (you can still type Map keys manually). Default: enabled. | ### Custom ClickHouse settings You can pass arbitrary ClickHouse `SETTINGS` with every query by adding key-value pairs in the **Custom Settings** section. For example, you can set `max_block_size` or `max_threads` to tune query performance. These settings are appended to each query’s `SETTINGS` clause. They do not replace any settings that the plugin sets internally (such as `max_execution_time`). ### Logs configuration The data source includes a dedicated configuration section for log queries. These settings control the default column mappings used by the [logs query builder](/docs/plugins/grafana-clickhouse-datasource/latest/query-editor/#logs-query-builder): Expand table | Setting | Description | |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Default log database** | The default database for log queries. | | **Default log table** | The default table for log queries. | | **Use OTel** | When enabled, pre-fills column mappings for [OpenTelemetry ClickHouse exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/clickhouseexporter) tables. Select the OTel schema version that matches your exporter. | | **Time column** | The high-precision timestamp column for sorting log rows. | | **Filter Time column** | A lower-precision time column for fast partition-based filtering. Used with the `1.2.9` schema only. | | **Log Level column** | The column containing the log severity level. | | **Log Message column** | The column containing the log message body. | | **Columns** | Extra columns projected into new logs queries; each appears in the Fields list, the expanded log row, and the field filters, and can be shown as a displayed field. | | **Context columns** | Comma-separated list of columns included alongside log messages for additional context. | When **Configuration mode** is set to **Single source** and **Signal type** is set to **Logs**, these settings define the focused logs source. In **Single source** mode, the **Columns** field is a picker of the selected table’s columns with an **Add all columns** shortcut; other configuration modes accept a typed list. The columns work with both OTel and non-OTel log tables; when **Use OTel** is enabled, they are added on top of the OTel default columns. ### Traces configuration The data source includes a dedicated configuration section for trace queries. These settings control the default column mappings used by the [traces query builder](/docs/plugins/grafana-clickhouse-datasource/latest/query-editor/#traces-query-builder): Expand table | Setting | Description | |----------------------------|------------------------------------------------------------------------------------------------------------------------------| | **Default trace database** | The default database for trace queries. | | **Default trace table** | The default table for trace queries. | | **Use OTel** | When enabled, pre-fills column mappings for OpenTelemetry tables. Select the OTel schema version that matches your exporter. | | **Duration unit** | The unit for the duration column (`seconds`, `milliseconds`, `microseconds`, or `nanoseconds`). | | **Flatten nested** | Enable if your traces table was created with `flatten_nested=1`. | When **Use OTel** is disabled, you can manually configure columns for Trace ID, Span ID, Parent Span ID, Service Name, Operation Name, Start Time, Duration, Tags, Service Tags, Kind, Status Code, Status Message, State, and Instrumentation Library. When **Configuration mode** is set to **Single source** and **Signal type** is set to **Traces**, these settings define the focused traces source. ### OTel schema versions The plugin ships built-in column maps for the OpenTelemetry ClickHouse exporter’s default schemas. Pick the version that matches the exporter that wrote your data: - **`auto (latest)`** : detects the logs schema version from the table’s columns when building a query: tables with a `TimestampTime` column use the `1.2.9` map, tables without it use the `1.3.0` map. Recommended, and the default. Pin a specific version below to override the detection. - **`1.3.0`** : `opentelemetry-collector-contrib` clickhouseexporter `v0.151.0` and later. The `otel_logs` table partitions and orders directly on `Timestamp`. The `TimestampTime` column was removed in [PR #47720](https://github.com/open-telemetry/opentelemetry-collector-contrib/pull/47720), so the **Filter Time column** is left blank. - **`1.2.9`** : `opentelemetry-collector-contrib` clickhouseexporter `v0.150.x` and earlier. The `otel_logs` table includes a `TimestampTime DateTime` column used for partition-based filtering. The trace tables (`otel_traces`, `otel_traces_trace_id_ts`) and metric tables are unchanged across these versions; only the `otel_logs` schema changed. Detection therefore only applies to logs, and traces always use the selected version’s map. If queries fail with an `Unknown identifier 'TimestampTime'` error after upgrading the exporter, leave the version on `auto (latest)` and rebuild the query, or pin the schema version to `1.3.0`. ### Private data source connect > Note > > Only available for Grafana Cloud users. Private data source connect (PDC) allows you to establish a private, secured connection between a Grafana Cloud instance (or stack) and data sources secured within a private network. Select the drop-down to locate the URL for PDC. For more information, refer to [Private data source connect](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/). Click **Manage private data source connect** to go to your PDC connection page, where you can find your PDC configuration details. ## Forward Grafana HTTP headers When you use the **HTTP** protocol, you can propagate Grafana’s per-request HTTP headers end-to-end to ClickHouse. This attaches context about the originating Grafana user, dashboard, and panel to every query so you can drive query-log attribution, quotas, and row policies from ClickHouse. To enable it, expand **Optional HTTP settings** on the data source and turn on **Forward Grafana HTTP headers to data source**. > Note > > This setting is only available on the HTTP protocol. The native protocol does not carry HTTP headers. When the toggle is on, the following headers are forwarded on each ClickHouse connection: Expand table | Header | Source | |--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `X-Grafana-User` | The logged-in Grafana user’s login. Populated from the plugin’s request context, so you do not need to enable the Grafana `dataproxy.send_user_header` setting for this plugin. | | `X-Dashboard-Uid`, `X-Panel-Id`, `X-Panel-Plugin-Id`, `X-Dashboard-Title`, `X-Panel-Title` | Identifiers set by Grafana when the query originates from a dashboard panel. | | `X-Grafana-Org-Id`, `X-Query-Group-Id`, `X-Grafana-From-Expr`, `X-Datasource-Uid` | Request-context headers set by Grafana core. | ### Use cases - **Query-log attribution**: ClickHouse records the forwarded headers in `system.query_log.http_user_agent` and related fields, so operators can correlate queries back to the Grafana user and dashboard that triggered them. - **Row policies and quotas**: ClickHouse [row policies](https://clickhouse.com/docs/en/operations/access-rights/#row-policies) and [quotas](https://clickhouse.com/docs/en/operations/quotas) can key on the `X-Grafana-User` header, so a single shared ClickHouse account can still enforce per-viewer access rules. ### Connection pool implications With header forwarding enabled, connections are keyed by the forwarded header set, which means each distinct Grafana user opens their own ClickHouse connection. Expect the connection count to scale with concurrent unique users and size `max_connections` on your ClickHouse server accordingly. ### Custom headers To forward headers other than the Grafana-set ones (for example, bearer tokens or tenant identifiers), add them as **Custom HTTP headers** in the same **Optional HTTP settings** panel. Custom headers are sent on every query regardless of the **Forward Grafana HTTP headers** toggle. ## Forward OAuth Identity > Note > > JWT authentication requires server-side support for JSON Web Tokens, which is currently [ClickHouse Cloud only](https://clickhouse.com/docs/en/operations/external-authenticators/jwt). It is not available on self-hosted or open source ClickHouse. When **Forward OAuth Identity** is enabled, the plugin forwards the logged-in Grafana user’s OAuth access token to ClickHouse as a JSON Web Token (JWT). ClickHouse then authenticates each query as the real user rather than as a shared service account, so you can drive per-user access rights, [row policies](https://clickhouse.com/docs/en/operations/access-rights/#row-policies), and query-log attribution from ClickHouse-side identities. For the token to be available, Grafana must be configured to forward the user’s OAuth access token to the data source. For server-side setup, refer to [ClickHouse JWT authentication](https://clickhouse.com/docs/en/operations/external-authenticators/jwt). To enable it, turn on **Forward OAuth Identity** in the **Database credentials** section of the data source configuration. ### Requirements and behavior - **A secure (TLS) connection is required.** Enable **Secure connection** and set the **Port** to a TLS-enabled port. The plugin rejects the connection if JWT authentication is enabled without TLS. It also rejects the connection when **Skip TLS Verify** is enabled, because forwarding a real user’s token over an unverified connection exposes it to interception. - **Credentials are suppressed on query connections.** When enabled, the configured username and password are not sent on per-query connections; the forwarded token is the sole credential. - **Health checks fall back to username and password.** **Save & test** and other health checks run outside a user request, where no user token is available, so they use the configured username and password. Keep valid credentials configured so connection tests can succeed. - **Alerting is blocked by default.** Alert rule evaluation also runs outside a user session, so there is no identity to forward. By default these queries are **rejected** rather than run as a shared account. To keep alerting working, enable **Allow service account fallback** in the **Database credentials** section. > Warning > > Enabling **Allow service account fallback** lets alert rules and other backend queries fall back to the configured username and password. Those queries then authenticate as the shared service account and are **not** subject to the per-user [row policies](https://clickhouse.com/docs/en/operations/access-rights/#row-policies), quotas, or query-log attribution that OAuth pass-through enforces for interactive queries. As a result, an alert may read rows a given dashboard user could not see interactively. Scope the configured service account to the least privilege your alert queries require. The plugin emits a backend warning log each time this fallback is exercised. - **Connections are keyed per user.** Enabling JWT authentication automatically turns on header forwarding, so each Grafana user opens a separate ClickHouse connection. See [Connection pool implications](#connection-pool-implications) for sizing guidance. ## Verify the connection Once you have configured your ClickHouse connection settings, click **Save & test** to verify the connection. When the connection test succeeds, you see **Data source is working**. A successful test confirms that Grafana can reach ClickHouse and that the credentials are valid. If the test fails, refer to [Troubleshoot ClickHouse data source issues](/docs/plugins/grafana-clickhouse-datasource/latest/troubleshooting/) for common configuration errors and solutions. ## Provision the data source You can define the data source in YAML files as part of the Grafana provisioning system. For more information, refer to [Provisioning Grafana data sources](/docs/grafana/latest/administration/provisioning/#data-sources). Example ClickHouse data source configuration with basic authentication: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 1 datasources: - name: ClickHouse type: grafana-clickhouse-datasource jsonData: host: localhost port: 9000 protocol: native username: grafana_reader # configMode: classic # "classic" for all databases, "single-table" for single source # signalType: logs # "logs" or "traces"; used when configMode is "single-table" # defaultDatabase: # defaultTable: # logs: # defaultDatabase: # defaultTable: # otelEnabled: # traces: # defaultDatabase: # defaultTable: # otelEnabled: # secure: # tlsSkipVerify: # tlsAuth: # tlsAuthWithCACert: # dialTimeout: # queryTimeout: # connMaxLifetime: # max lifetime of a pooled connection (default 5) # maxIdleConns: # max idle connections in the pool (default 25) # maxOpenConns: # max open connections in the pool (default 50) # validateSql: # enableRowLimit: # rowCapacityHint: # pre-allocate result frames to this many rows (0 = disabled, max 1000000) # enableMapKeysDiscovery: # probe Map columns for filter-editor key suggestions (default true) # forwardGrafanaHeaders: # oauthPassThru: # forward the user's OAuth token as a JWT (ClickHouse Cloud only); requires secure: true # oauthPassThruAllowFallback: # allow alerts/backend queries to fall back to username and password # path: # HTTP URL path (HTTP protocol only) # httpHeaders: # HTTP protocol only # - name: X-Example-Header # secure: false # value: # customSettings: # - setting: max_block_size # value: "65505" secureJsonData: password: password # tlsCACert: # tlsClientCert: # tlsClientKey: ``` ## Provision with Terraform You can provision the ClickHouse data source using the [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs). Example with basic authentication: hcl ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```hcl resource "grafana_data_source" "clickhouse" { type = "grafana-clickhouse-datasource" name = "ClickHouse" json_data_encoded = jsonencode({ host = "localhost" port = 9000 protocol = "native" username = "grafana_reader" tlsSkipVerify = false # configMode = "classic" # or "single-table" # signalType = "logs" # or "traces"; used when configMode is "single-table" # defaultDatabase = "mydb" # logs = { # defaultDatabase = "otel" # defaultTable = "otel_logs" # otelEnabled = true # } # dialTimeout = "10" # queryTimeout = "60" # validateSql = true # enableRowLimit = true # oauthPassThru = true # forward the user's OAuth token as a JWT (ClickHouse Cloud only); requires secure = true }) secure_json_data_encoded = jsonencode({ password = var.clickhouse_password }) } ``` For more options and authentication methods, refer to the [Grafana Terraform provider documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/data_source). ## Next steps After configuring the data source: - [ClickHouse query editor](/docs/plugins/grafana-clickhouse-datasource/latest/query-editor/): Build queries with the SQL editor or query builder. - [ClickHouse template variables](/docs/plugins/grafana-clickhouse-datasource/latest/template-variables/): Use variables in dashboards and queries. - [ClickHouse data source](/docs/plugins/grafana-clickhouse-datasource/latest/): Overview, supported features, and pre-built dashboards.