How Grafana reaches ClickHouse through the ClickHouse data source plugin
If your ClickHouse cluster already holds logs, traces or high-cardinality metrics and your team wants them in self-hosted Grafana, the supported route is the Grafana ClickHouse data source plugin. It covers metrics, logs, traces, alerting and recording rules, annotations, template variables and ad hoc filters, and the Grafana docs list ClickHouse 22.7 or later as the version it needs. Confirm your server version against that minimum before any other planning, because an older cluster changes the upgrade work ahead of the Grafana build.
The plugin gives you two ways to write queries. The SQL editor suits engineers who already know which tables, columns and time filters they need, while the visual query builder helps analysts pick a table, fields and aggregations without writing SQL. Both run against the same ClickHouse server over the network, so Grafana sends queries to your cluster and the data stays in your infrastructure. Decide early which group will own each dashboard, because that choice determines how much of the query logic lives in saved SQL and how much in builder settings that are harder to review.
ClickHouse itself is open source under the Apache License 2.0 (SPDX: Apache-2.0), and you can run the server in your own cloud account or data center. ClickHouse Inc. sells ClickHouse Cloud as a managed alternative, but the integration described here assumes a server you operate. Plan the connection path, the database user that Grafana uses, and the network route from Grafana to ClickHouse before you start, and record which ClickHouse version each environment runs so that the plugin version and the server version are tested together.
What you need before connecting Grafana to ClickHouse
Connecting Grafana to ClickHouse depends on four things being settled first: the ClickHouse version and release line, the Grafana database that holds its configuration, the network paths between the two, and the account Grafana uses to query. Each card below is a decision or check to close before the data source is configured.
ClickHouse 22.7 or later
The Grafana ClickHouse data source documents support for ClickHouse 22.7 or later. Treat that as the floor, not the target. Confirm the exact version your cluster runs, then check the plugin's current compatibility notes in the plugin docs before you pin either side, because plugin and server versions move independently.
Pick a supported ClickHouse line
The ClickHouse security policy lists 26.9, 26.8, 26.7 and 26.3 as versions that receive security updates. Any other version is unsupported. Decide which line you will run before building dashboards, since moving between lines later means a server upgrade and a dashboard regression pass. Record the choice so the team knows which line to patch against.
Production Grafana database
Grafana stores its configuration in SQLite by default, but the installation docs state SQLite does not scale for production. Plan MySQL 8.0 or later, or PostgreSQL 12 or later, before adding the ClickHouse data source. This matters more if you plan two or more active Grafana servers for high availability, which requires a shared database.
Network paths to ClickHouse
Grafana's server, not the user's browser, opens the connection to ClickHouse, so the path must run from each Grafana node to the ClickHouse HTTP and native interfaces your configuration uses. Confirm the ports with your ClickHouse setup, open them only between those hosts, and check any proxy or load balancer in between for query timeouts that are shorter than your dashboard queries.
Read-only ClickHouse account
Create a dedicated ClickHouse user for Grafana that holds only the SELECT grants on the databases and tables that dashboards read. Restrict its settings profile so a single panel cannot run unbounded queries. Use the access control documentation to define roles and grants, and avoid reusing an administrative or ingestion account, since a shared credential makes query auditing and revocation harder.
Authentication method for the account
Decide how Grafana authenticates before configuring the data source. ClickHouse supports LDAP, Kerberos, SSL X.509 certificates, an HTTP authenticator and JWT authentication as external authenticators. Choose the method your directory and security team can operate, and confirm with them how credentials will be stored, rotated and removed when someone leaves.
Configure the ClickHouse data source in order
This sequence takes a self-hosted Grafana instance from a plugin install to a working ClickHouse data source with a read-only account, verified queries and alert rules. Each step ends with a check you can record before moving on.
Install the ClickHouse plugin on Grafana
The Grafana platform team installs the ClickHouse data source plugin on the Grafana server, virtual machine image, container image or Helm values used for your deployment, then restarts Grafana so the plugin loads. Record the plugin version and the Grafana version together, and check both against the plugin documentation's compatibility notes before you go further. The step is done when the plugin appears in the Grafana plugin catalog as installed and Grafana starts without plugin load errors in its logs. Plugin installation should go through the same change process you use for other Grafana configuration so the install can be reproduced on every node.
Confirm ClickHouse server version prerequisites
Before you create any accounts, confirm that the ClickHouse server you will query runs version 22.7 or later, which is the minimum the Grafana ClickHouse data source documentation lists. Check the server version with your ClickHouse administrator and compare it against the supported lines in the ClickHouse security policy, since unsupported versions receive no security updates. The step is done when you have a written version record for each cluster or endpoint the dashboards will hit. If the server is older, plan the upgrade as its own change with a pre-production test rather than upgrading inside this integration.
Create a dedicated read-only ClickHouse user
A ClickHouse administrator creates a separate user for Grafana that holds only SELECT rights on the databases and tables that dashboards need, and no write, DDL or user-management privileges. Scope the grants to named schemas and, where your access model allows, to specific tables, and set resource limits so one dashboard cannot starve ingestion. Use the access control documentation to define the grants, and decide whether the account authenticates with a password or with an external authenticator such as LDAP or JWT, which ClickHouse supports. The step is done when a session opened with that user can run a SELECT on the intended tables and is refused an INSERT or CREATE statement.
Enter server, port and TLS settings
In Grafana, the platform team creates the ClickHouse data source and enters the server host name, the native or HTTP port your ClickHouse deployment exposes, the database name and the read-only user credentials. Enable TLS and supply the certificate authority your security team manages, so the connection is encrypted and the server identity is verified rather than skipped. Store the password through Grafana's secrets handling or your provisioning pipeline instead of pasting it into a shared dashboard. The step is done when every field is saved and the configuration matches the ports and certificates your ClickHouse administrator confirmed.
Run the connection test
Select Save and test on the data source page and read the result. A passing test confirms that Grafana reaches the server, authenticates the read-only user and can run a basic query against the selected database. If the test fails, check network routes, firewall rules, the TLS trust chain and the user's grants in that order, since each one produces a different error message. The step is done when the test reports success and a repeat run after a Grafana restart still passes. Record the result with the Grafana and plugin versions in your change log.
Build the first query in the SQL editor and visual builder
Open a new panel on a test dashboard and write a first query in the SQL editor against a table that holds log or event data, selecting a timestamp column and a count with a time bucket and filtering on the dashboard time range. Then rebuild the same query in the visual query builder to confirm that both views produce matching results for the same time range. Check that the output returns rows across the expected time buckets and that the counts agree with a direct query run from the ClickHouse client. The step is done when the panel renders a time series that matches the independent count for a chosen window.
Enable alerting and recording rules
Create an alert rule in Grafana Alerting that uses the ClickHouse query as its condition, set an evaluation interval and a threshold that is safe for a test environment, and route it to a test contact point. Then create a recording rule for a query you will reuse across dashboards, if your Grafana edition and the ClickHouse data source documentation support it for that query type. Confirm that the rule evaluates without error in the rule state view and that the recorded series appears when you query it back. The step is done when the alert shows a normal or firing state with no evaluation error and the recording rule writes a series you can read in Grafana.
Provision the data source as code
Once the manual setup works, the platform team writes the data source, dashboard and alert definitions into the provisioning files or as-code tooling your Grafana deployment uses, so every environment loads the same configuration at startup. Keep the password out of the file by referencing a secret that your pipeline injects. Rebuild a non-production Grafana from the files alone and run the same connection test and query check to confirm the result matches the manual setup. The step is done when a clean Grafana instance loads the data source from code and passes the same checks without manual edits.
Choosing the SQL editor or visual query builder for each signal
The visual query builder suits operators who need quick, bounded views of metrics and simple log counts, such as request rates, error counts by service, or p95 latency over a chosen time range. It keeps time filters, template variables and ad hoc filters in the panel's own controls, which makes dashboards easier for teammates to read and edit. Raw SQL in the code editor becomes necessary once a panel needs ClickHouse-specific functions, joins across tables, nested trace spans, JSON-extracted log fields or aggregations the builder does not expose. Confirm in the ClickHouse data source documentation which query types the builder covers in your plugin version before you standardize on it for each signal.
Table layout and ordering keys decide how much data each dashboard query reads, so they matter as much as the query text. A query that filters on the columns a table is sorted by can skip most of the data, while a filter on an unsorted column scans far more rows on every refresh. For logs and traces, check that the time column and the most common service or severity filters are part of the sorting key. For high-cardinality metrics, check whether panels group by labels that were never planned for indexing. Ask the team that owns the schema to document the sorting key next to each dashboard's main filters, and treat any panel that scans a full table as a design defect to fix before go-live.
Prove every query shape against representative data in a pre-production environment before the dashboards reach operators. Use a copy of production-like volume, the same ClickHouse version and the same template variable values that users pick most often, then time each panel under concurrent refreshes. Include ad hoc filter combinations, because they change the generated SQL and can defeat an index the static query used. Record the query, the rows read and the result for each panel, and revisit the design when the ClickHouse version or table schema changes. Where the team cannot reproduce production volume, state that gap in the sign-off so the performance assumptions are not mistaken for measured results.
How Grafana fields map to ClickHouse tables and columns
This table pairs each Grafana concept used in dashboards, logs, traces and alerts with the ClickHouse columns and query shapes it typically needs. Read it as a checklist for your own schema, since the column names shown are a convention your team confirms rather than a fixed requirement. The main takeaway is that Grafana's panels and filters only work well when the timestamp, label and span fields are designed into the tables before dashboards are built.
| Grafana concept | ClickHouse columns or shape | Where it is used | Decision to confirm |
|---|---|---|---|
| Time series panels | A DateTime or DateTime64 timestamp column plus a numeric value column and one or more dimension columns | Time range macros in the SQL editor and query builder filter on the timestamp column | Which column is the time axis and whether it is partitioned by day or hour |
| Log panels | A timestamp, a message string column and a severity column such as level or severity_text | Log panels read the message and level fields to render rows and color by severity | Whether severity is stored as text, enum or number, and how it is normalized |
| Service and host labels | Low-cardinality String or LowCardinality(String) columns for service, host and environment | Ad hoc filters and template variables list distinct values from these columns | Column names and which labels are indexed through sorting key or skip indexes |
| Trace panels | Span fields such as trace ID, span ID, parent span ID, service name, operation name, start time and duration | Trace views rebuild the span tree from the trace ID and parent span ID columns | Whether spans live in a separate table from logs and how trace IDs are typed |
| Annotations | An event table with a timestamp, title, text and tags or source column | Annotation queries overlay deployment or incident events on time series panels | Which source system writes annotations and whether they share the logs table |
| Template variables | A query returning DISTINCT values from one dimension column, often restricted by the selected time range | Dropdowns on dashboards that feed WHERE clauses through variable macros | Whether variable queries scan large ranges and need a narrower window or a lookup table |
| Alert and recording rules | An aggregating query with a bounded time window returning numeric results per series | Alert rules evaluate the query on a schedule and recording rules store results | Which aggregates and time windows are stable enough to alert on and who owns the rule |
Securing the Grafana to ClickHouse connection
The Grafana to ClickHouse connection carries operational data that often includes sensitive event and log content, so access has to be controlled on both sides. The cards below cover the ClickHouse account and transport, where credentials live, the external authenticators your team must confirm, and the Grafana settings and roles that govern who can query.
Dedicated read-only ClickHouse user
Create a separate ClickHouse account for Grafana with grants limited to the databases and tables its dashboards read. Do not reuse an administrative or ingestion account. Review the grants against the access model in the ClickHouse access control documentation, and confirm that the account cannot create, alter or drop objects. Record who owns the account and how its grants are reviewed.
TLS on the query path
Encrypt the connection between the Grafana server and ClickHouse, so queries, results and credentials do not cross the network in clear text. Confirm with your ClickHouse deployment which HTTP and native endpoints are exposed, which certificate authority issues them, and whether Grafana trusts that authority on the host where it runs. Test the connection with certificate verification enabled rather than disabled.
Credentials outside dashboards
Keep the ClickHouse password out of dashboard JSON, where anyone with export rights could read it. Store it through Grafana provisioning or a secrets mechanism your platform team already operates, and reference it from the data source definition. Restrict who can read or edit the provisioning files, and rotate the credential on a schedule your security team sets.
External authenticators to confirm
ClickHouse supports LDAP, Kerberos, SSL X.509 certificates, an HTTP authenticator and JWT as external authenticators. Each one changes how the Grafana service account is identified and rotated, so choose one only after checking it against your directory and identity provider. Confirm which option your team uses, who operates the directory integration, and how a disabled directory account is handled.
Grafana security hardening settings
Apply the hardening guidance for the Grafana server itself: secure and SameSite cookies, a Content Security Policy, Trusted Types, hiding the version from unauthenticated users, requiring authentication for the metrics endpoint, and domain verification against DNS rebinding. These settings protect the sessions that issue ClickHouse queries, so review them as part of the same change that adds the data source.
Role-based access inside Grafana
The ClickHouse credential is shared by everyone who can run a query through the data source, so Grafana roles decide who can see the results. Map viewers, editors and administrators to the teams that need them, and limit who can edit the data source or its query editor. Check whether your edition provides the team sync and SSO features you need, and confirm the folder permissions that protect sensitive dashboards.
Testing dashboards, alerts and backups before go-live
Before go-live, test the three things that fail quietly in a Grafana and ClickHouse setup: query results, dashboard behavior under load, and whether data can actually be restored. Start with query result parity. For a sample of panels, run the same SQL in the ClickHouse client and in the Grafana ClickHouse data source against the same time range, then compare row counts, aggregates and timestamp handling. Pay particular attention to time zone conversion, macro expansion for time filters, and ad hoc filters, because a dashboard can look correct while silently applying a different window than the analyst expects. Keep the expected results in version control so the same comparison can be repeated after every upgrade.
Next, test dashboard load under concurrent users. Pick the dashboards that a realistic peak of viewers will open at once, including dashboards with template variables and high-cardinality log or trace queries, and measure query duration and ClickHouse resource use while they run. Then test alert rule evaluation and notification routing: confirm that each rule evaluates on its intended interval, that a deliberately triggered condition reaches the right contact point, and that recovery notifications arrive. If you run more than one Grafana server, confirm that alerting is configured so that notifications are not duplicated, as the Grafana high availability guidance describes.
Finally, run a ClickHouse backup restore test on a spare cluster. Replication keeps replicas in step, but it also copies a bad DROP or an erroneous delete to every replica, so it does not protect against human error or corruption. Take a backup with BACKUP and restore it to a spare cluster, then check row counts and a sample of queries against known values. The ClickHouse backup documentation warns that a backup never test-restored will probably not restore properly when needed, so schedule restore tests regularly rather than once. For upgrades, pilot each Grafana and ClickHouse change in a pre-production environment with representative data, read the changelog for backward-incompatible changes, and confirm which ClickHouse release line your version belongs to in the ClickHouse production guidance before you schedule the change.
Common failures when Grafana cannot query ClickHouse
This table lists the failures teams most often hit when a Grafana panel or alert cannot read from ClickHouse, with the likely cause and the first fix to try for each. Work down the rows in order, since plugin and version problems block everything else. Confirm version-specific behavior in the ClickHouse and Grafana release notes before changing a production instance.
| Symptom | Likely cause | First fix to try |
|---|---|---|
| Data source type missing after install | The ClickHouse plugin was installed but Grafana was not restarted, or the plugin was not allowed to load | Restart the Grafana service, then check the plugin list and the server log for plugin load errors |
| Panels fail on a ClickHouse data source | ClickHouse server is older than 22.7, which the plugin requires for its supported features | Check the server version with a SQL query, then upgrade to a supported release line before debugging queries |
| Connection refused | Wrong host or port, the native or HTTP port is not reachable from the Grafana host, or a firewall or security group blocks it | Test connectivity from the Grafana host with a simple client, then correct the address and port in the data source settings |
| TLS or certificate errors | Certificate chain not trusted by Grafana, hostname mismatch, or a secure port configured without TLS enabled | Install the CA certificate on the Grafana host, match the certificate name to the configured host, and align the secure setting with the server port |
| Permission denied on tables or databases | The Grafana database user lacks SELECT on the target tables, or the user is restricted to a different database | Grant read-only SELECT on the required databases to a dedicated Grafana user, then rerun the failing query in the SQL editor |
| Dashboards load slowly or time out | Unbounded time ranges, queries that do not filter on the table's time column, or no use of the table's ordering key | Apply the dashboard time range in every query, filter on the leading ordering key columns, and limit result rows for table panels |
| Alerts fire on stale or missing data | Alert query window ends before the latest ingested rows, or ingestion lag is larger than the evaluation window | Align the alert window with the ingestion delay, add a no-data rule, and compare the alert result with the same query in Explore |
| Ad hoc filters or variables return no values | Variable query runs against a different database or table than the panels, or it returns high-cardinality values that are truncated | Point the variable query at the same table as the panels, narrow it with the time range, and confirm the filter column name matches the schema |
Questions teams ask before connecting Grafana to ClickHouse
What drives the cost and effort of a Grafana and ClickHouse integration?
The main drivers are the number of data sources, the shape of the ClickHouse schemas, and how many dashboards and alert rules need to run against them. Cost comes from people: scoping, building queries and dashboards, configuring the ClickHouse data source plugin, setting up access, and testing against representative data. Schemas that are well suited to analytical queries cost less to chart than ones that need reshaping first. Ask any quote to itemize discovery, schema and query work, dashboard build, alerting, access setup, testing and handover, and to state which items are one-time and which recur. Your own platform costs, including the ClickHouse cluster, Keeper nodes and backup storage, are separate from the services fee.
How long does it take to scope and build this integration?
Duration depends on how many sources feed Grafana, how clean the schemas are, and how many dashboards and alert rules are in scope. A single cluster with a short list of dashboards is far simpler than several clusters feeding logs, traces and metrics into shared views. Scoping usually comes first because it fixes which tables, users and dashboards are included. No fixed timeline is given here; the written scope from a quote will set the schedule, and the team should ask for milestones tied to a pre-production check before any production cutover.
What must our team provide before the work starts?
The team needs to provide four things. First, ClickHouse access: a read-only account or a dedicated role with the grants the dashboards require, plus network reach from the Grafana host. Second, schema documentation for the tables that will be queried, including time columns, partition keys and retention. Third, a set of sample queries or dashboard requirements that reflect real questions. Fourth, a pre-production environment with representative data and query load, so changes are tested before they reach production. Check the access model with your security team early, because role design determines what Grafana users can see.
Can our in-house team build this without outside help?
Yes, if the team already runs ClickHouse and Grafana and has time to learn the ClickHouse data source plugin. The skills needed are SQL against analytical tables, Grafana provisioning, role design in ClickHouse, and operating a replicated cluster. The Grafana ClickHouse data source supports metrics, logs, traces, alerting and recording rules, template variables and ad hoc filters, with a SQL editor and a visual query builder, so the build is largely configuration and query work. Outside help is most useful for schema review, access design and a tested handover. Whichever route you choose, confirm the ClickHouse version you run meets the plugin prerequisite of ClickHouse 22.7 or later.
What recurs after go-live in this stack?
Several items recur. Grafana publishes major releases once a year in April or May, minor releases every other month and patch releases at least monthly, so the plugin and server need a regular upgrade cycle. ClickHouse stable releases ship roughly monthly, and LTS releases ship twice a year and are supported for a year. Only the versions listed in the ClickHouse security policy receive security updates, so plan an upgrade path before a line falls out of support. Backups need scheduled runs and regular restore tests on a spare cluster, because the ClickHouse documentation warns that a backup never test-restored will probably not restore when needed. Replication alone does not protect against human error or corruption.
How do Grafana Cloud or ClickHouse Cloud options change the work?
A managed option changes who runs the infrastructure, not the design questions. ClickHouse Cloud is a managed service sold by ClickHouse Inc., and Grafana Cloud offers a free tier, a Pro tier with a 19 US dollar monthly platform fee plus usage, and an Enterprise tier with a 25,000 US dollar yearly minimum commitment, according to Grafana's pricing page. Access, schema, query design and dashboard work stay largely the same. Plan for different network paths, data residency terms and where credentials are stored. Also confirm which plugin features and identity options each tier supports before you commit, because Grafana's authentication options differ between open source and Enterprise editions.
What goes wrong most often with ClickHouse dashboards in Grafana?
The most common problems are overly broad queries that scan too much data, missing time filters, and dashboards that assume a schema the team later changed. Alert rules built on expensive queries can add steady load to the cluster. Access problems also appear when the Grafana account has more or fewer grants than intended. Test queries against representative data in a pre-production environment, use the time-column and partition design to limit scans, and confirm ad hoc filters behave as expected on large tables. Read the ClickHouse changelog before upgrades, since minor backward-incompatible changes can occur.
How DeployOpen scopes and delivers a Grafana and ClickHouse integration
DeployOpen plans, builds, documents and supports the Grafana and ClickHouse data source inside infrastructure you control, from the Grafana instance to the ClickHouse cluster behind it. Engagements are fixed-scope, so the datasets, dashboards, alert rules and access model are agreed in writing before any work begins.
How we scope
- Inventory the ClickHouse tables, retention and query patterns behind each planned dashboard before choosing a query approach.
- Confirm ClickHouse and Grafana versions against the plugin's prerequisites, including ClickHouse 22.7 or later for the data source.
- Agree in writing which metrics, logs, traces, alert rules and ad hoc filters are in scope, and which are excluded.
How we build
- Create read-only ClickHouse users scoped to the agreed databases and tables, with access reviewed before the data source is connected.
- Configure the ClickHouse data source in Grafana, choosing between the visual query builder and the SQL editor per dashboard.
- Test dashboards, template variables and alerting on a pre-production cluster loaded with representative data before any production use.
How we hand over
- Provide data source definitions and dashboards as provisioning files so the setup can be rebuilt and reviewed from source control.
- Document query conventions, alert rule ownership, the backup and restore procedure and the upgrade steps for both products.
- Walk your operators through the runbook, including how to run a restore test on a spare cluster before relying on backups.
How we support
- Ongoing support, version upgrades and continuous testing are available as retainers after handover.
- Plan Grafana and ClickHouse upgrades against the published release and support timelines, with changelog review before each change.
- Confirm with us which parts of compliance evidence, such as alerting and capacity records, your auditors will need from the stack.
