Documentation Plugins ClickHouse data source Configure

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.
• 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).

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.

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)

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.
2. Set readonly = 1 for the user or profile. For details, see Permissions for queries (readonly).
3. Allow modification of the max_execution_time setting, which is required by the clickhouse-go client so the plugin can enforce query timeouts.

Required SETTINGS permissions

The plugin’s underlying client (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:

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 for the Grafana user.
2. Set the constraint type for each required setting to changeable_in_readonly.

Example (SQL):

SQL Copy

-- 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 for more details.

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

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

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:

TLS settings

When Secure connection is enabled, the following TLS settings become available:

Configuration mode

Use Configuration mode to choose how the data source is used by the query builder.

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 in the query editor.

Additional settings

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:

When Configuration mode is set to Single source and Signal type is set to Logs, these settings define the focused logs source.

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:

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, 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

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.

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.

When the toggle is on, the following headers are forwarded on each ClickHouse connection:

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 and 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

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, 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.

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, 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 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 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.

Example ClickHouse data source configuration with basic authentication:

YAML Copy

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: <string>
      # defaultTable: <string>
      # logs:
      #   defaultDatabase: <string>
      #   defaultTable: <string>
      #   otelEnabled: <bool>
      # traces:
      #   defaultDatabase: <string>
      #   defaultTable: <string>
      #   otelEnabled: <bool>
      # secure: <bool>
      # tlsSkipVerify: <bool>
      # tlsAuth: <bool>
      # tlsAuthWithCACert: <bool>
      # dialTimeout: <seconds>
      # queryTimeout: <seconds>
      # connMaxLifetime: <minutes>   # max lifetime of a pooled connection (default 5)
      # maxIdleConns: <int>          # max idle connections in the pool (default 25)
      # maxOpenConns: <int>          # max open connections in the pool (default 50)
      # validateSql: <bool>
      # enableRowLimit: <bool>
      # rowCapacityHint: <int>  # pre-allocate result frames to this many rows (0 = disabled)
      # enableMapKeysDiscovery: <bool>  # probe Map columns for filter-editor key suggestions (default true)
      # forwardGrafanaHeaders: <bool>
      # oauthPassThru: <bool>  # forward the user's OAuth token as a JWT (ClickHouse Cloud only); requires secure: true
      # oauthPassThruAllowFallback: <bool>  # allow alerts/backend queries to fall back to username and password
      # path: <string>  # HTTP URL path (HTTP protocol only)
      # httpHeaders:     # HTTP protocol only
      #   - name: X-Example-Header
      #     secure: false
      #     value: <string>
      # customSettings:
      #   - setting: max_block_size
      #     value: "65505"
    secureJsonData:
      password: password
      # tlsCACert: <string>
      # tlsClientCert: <string>
      # tlsClientKey: <string>

Provision with Terraform

You can provision the ClickHouse data source using the Grafana Terraform provider. Example with basic authentication:

hcl Copy

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.

Next steps

After configuring the data source:

• ClickHouse query editor: Build queries with the SQL editor or query builder.
• ClickHouse template variables: Use variables in dashboards and queries.
• ClickHouse data source: Overview, supported features, and pre-built dashboards.