clickhouse-grafana: Altinity's ClickHouse datasource for Grafana

A datasource maintained by the ClickHouse vendor community

The Altinity ClickHouse datasource plugin provides support for ClickHouse as a backend database in Grafana, and the title says it supports Grafana 4.6 and later.

The history is stated in one line and it explains the shape of the project. It was initially developed by Vertamedia and has been maintained by Altinity since 2020. That handover is the reason the plugin still carries the older Vertamedia identifiers in the installation instructions, such as the vertamedia-clickhouse-datasource package name, while the repository and the released versions are Altinity's.

The project is a two-language codebase. The primary language recorded for the repository is TypeScript, and there is a src directory holding the frontend that Grafana loads. There is also a pkg directory with a Go module, whose module path is github.com/altinity/clickhouse-grafana and whose main external dependency is the Grafana plugin SDK for Go at version 0.296.5, alongside brotli, regexp2, klauspost/compress, testify, and x/sync. The Go side is the backend the plugin runs in the Grafana server process, and the dependency on the official SDK is what keeps it compatible with the Grafana plugin model rather than being a fork of it.

The feature list is long and reads like a list of Grafana datasource capabilities. Access to ClickHouse over HTTP or HTTPS, a query setup interface, a raw SQL editor, query formatting, macros support, additional functions, templates, a table view, a SingleStat view, ad-hoc filters, annotations, alerts support, histogram support, logs support, flamegraph support, and traces support.

That last group is the interesting one. A datasource that supports logs, traces, and flame graphs is not just a chart source, it is a way of moving from a metric to the query that produced it, and ClickHouse being the backing store for that data is the use case the plugin was built for.

The licence is MIT, and the repository is not archived, with the last push on 2026-10-19 and recent releases v3.5.0 in August 2026, v3.4.12 in July 2026, and v3.4.11 in April 2026.

Three version boundaries that decide your setup

The quick start section is organised around plugin versions rather than around features, and the reason is that each version boundary corresponds to a different Grafana or ClickHouse behaviour change. Reading these four notes in order saves a lot of debugging.

The first is for plugin version 3.4.9 and later. Because the plugin added output_format_json_quote_64bit_integers=1 to any browser request, if the user you use for the connection has readonly=1 you have to change it to readonly=2, for example in the readonly.xml file under the ClickHouse server users directory.

The second is for plugin versions before 3.4.9, and it is about ClickHouse 25.8 and later. The new ClickHouse version changed the default behaviour for output_format_json_quote_64bit_integers to 0, which does not allow the generated JSON to be read in JavaScript, with a link to the upstream issue for the details. The fix is to add the setting back to 1 in a separate configuration file in the ClickHouse users directory.

The third is for plugin versions before 3.0.0 on Grafana 10 and later. Those older versions were written in Angular, so Grafana prints a warning that the data source plugin uses a deprecated legacy platform based on AngularJS and will stop working in future releases of Grafana. The README says not to worry, because the plugin will still work until Grafana 11 is released, and that after that release you have to upgrade to the 3.x version.

The fourth is for plugin versions before 2.2.0 on Grafana 7 and later. When the 2.0.x and 2.1.x Vertamedia versions were released, the Grafana team did not provide a working signing method for community plugins, so the README tells you to allow the unsigned plugin by name in the plugins section of the Grafana configuration.

[plugins]
allow_loading_unsigned_plugins=vertamedia-clickhouse-datasource

Or by setting the equivalent environment variable.

GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=vertamedia-clickhouse-datasource

So the plugin version you want dictates whether you need a ClickHouse profile change, a Grafana configuration change, or both.

The ClickHouse profile change, spelled out

The readonly setting deserves its own explanation, because it is the change most people hit and the one that is least obvious.

The plugin adds output_format_json_quote_64bit_integers=1 to any request it makes from the browser. In other words, the client asks ClickHouse to quote 64 bit integers as strings in the JSON output, because JavaScript cannot represent every 64 bit integer exactly as a number. A large counter in ClickHouse would otherwise be rounded silently in the browser, which is the classic way a dashboard shows a plausible but wrong number.

That setting is not something a readonly user can set, because it is a profile level setting, so the user with readonly=1 cannot apply it. readonly=2 allows the profile to be modified for the query, which is what makes the plugin's request work.

<clickhouse><profiles><default>
  <readonly>2</readonly>
</default></profiles></clickhouse>

For older plugin versions on newer ClickHouse, the change runs the other way. ClickHouse 25.8 changed the default of the quoting setting to 0, so the plugin has to turn it back on, in a separate file in the users directory.

<clickhouse><profiles><default>
  <output_format_json_quote_64bit_integers>1</output_format_json_quote_64bit_integers>
</default></profiles></clickhouse>

There is a security consequence worth taking seriously. readonly=1 is the setting you want for a user that must never modify data, and readonly=2 is a weaker guarantee, since it permits the request to change profile settings for the query. The trade is explicit in the README rather than hidden, but it means the account you point the plugin at should be a dedicated read-only reporting account rather than a superuser, and it means the file is a server configuration change rather than something you can fix in the Grafana UI.

CHProxy for concurrency limits, queueing and caching

The optional component in this setup is CHProxy, and the README is clear about what it is for, which is protecting ClickHouse from Grafana rather than adding features to Grafana.

Putting CHProxy in front of ClickHouse brings four things. It makes HTTPS access to ClickHouse easy to set up, to provide secure access, and it lets you authorise users by password. It lets you limit concurrency and execution time for requests coming from Grafana, to prevent ClickHouse being overloaded by Grafana. It protects against request bursts for dashboards with numerous graphs, because CHProxy allows queueing requests and executing them sequentially, with the max_queue_size and max_queue_time parameters being the ones to read about. And it adds response caching for the most frequent queries, which protects ClickHouse from excessive refreshes and is the optimal option for popular dashboards.

That last point has a wrinkle the README calls out with a hint, and it is a good one. If you need to cache requests like last 24 hours, where the timestamp changes constantly, then the cache key changes on every refresh and the cache does nothing. The suggestion is to use the Round option in the Raw Editor, so the time range is rounded to a stable boundary and the same query is issued repeatedly.

That is the kind of detail that separates a component you can deploy from one that actually helps. Caching a query whose time range moves every thirty seconds caches nothing, and a proxy that queues requests will happily serialise a dashboard into something that takes minutes to render.

The other point in the connection section is worth noting as well. ClickHouse treats HTTP Basic Authentication credentials as a database user and will try to run queries using that name, which means the username in the datasource configuration is a ClickHouse user and not a label. That is why the readonly discussion above is about a real account, and why a proxy in the middle can change the picture: CHProxy can authorise users by password, so the credentials Grafana holds do not have to be the credentials ClickHouse sees.

The query builder, the macros, and the raw SQL editor

The query setup interface is a builder rather than a query box, and its structure is worth knowing.

The first row, FROM, has two options, database and table, and the table values depend on the selected database. The next rows hold the selectors for time filtering, and the plugin offers DateTime, DateTime64, and TimeStamp, which is a UInt32 in ClickHouse. The timestamp column is required for the time based macros and functions, since all the analytics are based on those values, and the plugin will try to detect a Date or Date32 column automatically. A button called Go to Query is simply a toggle into the raw SQL editor.

The raw editor allows custom SQL, gives information about functions and macros, and formats queries the way ClickHouse does. The query is executed by pressing Run Query or simply by leaving focus from the SQL editor textarea, which is a small quality of life detail that makes the editor feel responsive. Under the editor there are options for rounding, for the time column step, and for Add metadata to the SQL query, which is what lets you know which dashboard and which user produced the workload on your ClickHouse server. Pressing Show Generated SQL shows the raw query with all the macros and functions already replaced, which is exactly what will be sent to ClickHouse.

That generated SQL view is the feature to reach for when a dashboard disagrees with what you expected. The macros expand to time filters and to the selected table, and seeing the expansion removes the guesswork about what the plugin is actually asking the server.

The macros themselves are listed in the README, starting with $table, and the plugin also supports templates, so a dashboard variable can drive the query.

The build, the test rig, and the signing step

The build is a webpack frontend plus a Go backend, and the scripts in the package manifest show the whole pipeline.

The frontend build is webpack with a production environment flag, the dev script runs the same build in watch mode, and the backend is built in a container, with the build:backend script running a backend builder service through docker compose. The full build runs the frontend and the backend in sequence, and the type check is a separate tsc pass with no emit, so type errors fail without producing output. Linting is eslint with a cache.

Testing is layered. Jest is the unit test runner, with a coverage script and a CI variant that passes with no tests and caps the worker count. Cypress is used for the end to end tests, run through the Grafana e2e runner, and there is a separate script that updates the screenshots when the rendering changes. The server script starts Grafana itself with docker compose, which is what makes the end to end run possible without a manually provisioned instance.

There is also an instrumented build path, with a separate webpack configuration and an nyc instrument step, which is how the coverage numbers are collected from the frontend code.

And there is a signing script, which sources a release environment file and runs the official Grafana plugin signing tool, because Grafana requires signed plugins in recent versions and the signing credentials live outside the repository in a file whose example is checked in.

The docker compose file is a test rig rather than a deployment. It defines a ClickHouse service with the HTTP port, the native port, and a Postgres and a MySQL port exposed, and it mounts a set of configuration files into the container: an init schema, a low memory profile, a macros file, a dictionary configuration, a listen ports file, and a set of certificates for server and client TLS. A second service, clickhouse-ontime, runs the same image with a different init schema, which is the dataset the end to end tests query.

Editorial conclusion

clickhouse-grafana fits a team that stores its analytics in ClickHouse and wants those tables in Grafana dashboards with time series, logs, traces and flame graphs from one datasource, and who can adjust a ClickHouse user profile. It does not fit an installation that cannot change server configuration, because the 64 bit integer quoting behaviour needs a profile setting, and it does not fit a Grafana older than the version your plugin line supports. Verify first which plugin version you are on against the three boundaries in the README, that the ClickHouse user you connect with has readonly set to 2 rather than 1, and that you put a proxy in front of ClickHouse if a dashboard refreshes faster than the cluster can answer.

Frequently asked questions

Official sources

1. Altinity/clickhouse-grafana on GitHub
2. Issues
3. License: MIT
4. README
5. Releases