Documentation Plugins ClickHouse data source Configure the ClickHouse data source

Configure the ClickHouse data source

This document explains how to configure the ClickHouse data source.

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.

If you use a public ClickHouse instance, do not set readonly = 2. Instead:

• Keep readonly = 1
• Set the constraint type for max_execution_time to changeable_in_readonly

ClickHouse protocol support

The data source supports two transport protocols: Native (default) and HTTP. Both use ClickHouse’s optimized native data formats and support the same query capabilities.

Default ports

When you enable Secure connection (TLS) in Grafana, use a port that supports TLS. Grafana does not change the port automatically when TLS is enabled.

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:

Verify the connection

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
      defaultDatabase: database
      tlsSkipVerify: false
      # secure: <bool>
      # tlsAuth: <bool>
      # tlsAuthWithCACert: <bool>
      # dialTimeout: <seconds>
      # queryTimeout: <seconds>
      # defaultTable: <string>
      # httpHeaders:
      #   - name: X-Example-Header
      #     secure: false
      #     value: <string>
    secureJsonData:
      username: username
      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 = {
    defaultDatabase = "default"
    port             = 9000
    host             = "localhost"
    protocol         = "native"
    tlsSkipVerify    = false
  }

  secure_json_data = {
    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.