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:

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:

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.

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.

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.

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.

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
      # defaultDatabase: <string>
      # defaultTable: <string>
      # secure: <bool>
      # tlsSkipVerify: <bool>
      # tlsAuth: <bool>
      # tlsAuthWithCACert: <bool>
      # dialTimeout: <seconds>
      # queryTimeout: <seconds>
      # validateSql: <bool>
      # enableRowLimit: <bool>
      # forwardGrafanaHeaders: <bool>
      # 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
    # defaultDatabase = "mydb"
    # dialTimeout     = "10"
    # queryTimeout    = "60"
    # validateSql     = true
    # enableRowLimit  = 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.