# Documentation gap: PMM\_CLICKHOUSE\_IS\_CLUSTER / PMM\_CLICKHOUSE\_CLUSTER\_NAME for HA + external ClickHouse

**URL:** <https://forums.percona.com/t/documentation-gap-pmm-clickhouse-is-cluster-pmm-clickhouse-cluster-name-for-ha-external-clickhouse/40591>\
**Category:** PMM 3.x\
**Tags:** pmm\
**Created:** [April 9, 2026, 1:13am UTC](https://forums.percona.com/t/documentation-gap-pmm-clickhouse-is-cluster-pmm-clickhouse-cluster-name-for-ha-external-clickhouse/40591 "2026-04-09T01:13:56Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![ddkozyreva](https://sea1.discourse-cdn.com/flex019/user_avatar/forums.percona.com/ddkozyreva/32/20219_2.png) [@ddkozyreva](https://forums.percona.com/u/ddkozyreva)\
**Post date:** [April 9, 2026, 1:13am UTC](https://forums.percona.com/t/documentation-gap-pmm-clickhouse-is-cluster-pmm-clickhouse-cluster-name-for-ha-external-clickhouse/40591/1 "2026-04-09T01:13:56Z")

</div>

Hi team!

I’d like to flag a documentation gap that cost us several hours of debugging in a PMM 3.6.0 HA setup with an external 3-node ClickHouse cluster (one shard, three replicas, ZooKeeper present, macros configured).

Symptom: PostgreSQL QAN data appeared on only one ClickHouse node — the one matching PMM\_CLICKHOUSE\_ADDR of the currently-active pmm-managed instance. After a PMM HA leader change, fresh data started landing on a different CH node, while Grafana (pinned to a fixed CH datasource) silently showed “No data”.

Root cause: qan-api2 only creates pmm.metrics as ReplicatedMergeTree when both PMM\_CLICKHOUSE\_IS\_CLUSTER=true and PMM\_CLICKHOUSE\_CLUSTER\_NAME= are set. Without them, the migration produces a plain MergeTree, which is local to whichever CH node ran the migration first — even if the underlying CH cluster is fully cluster-aware. References: qan-api2/main.go (kingpin flags), qan-api2/db.go (NewDB / IsClickhouseClusterReady), qan-api2/migrations/migrations.go (GetEngine(isCluster)).

Where the docs fall short:

The Use external ClickHouse with PMM page does not mention either variable — a user setting up an external CH cluster from this page has no way to know cluster mode exists.

The Install PMM HA Cluster page mentions PMM\_CLICKHOUSE\_IS\_CLUSTER: “1” once in a YAML snippet under “Pre-configured HA variables” with the comment # Enable ClickHouse clustering, never explains what “clustering” means here, and never mentions PMM\_CLICKHOUSE\_CLUSTER\_NAME at all (despite it being equally required).

The two pages aren’t cross-linked, so a user combining HA PMM with an external CH cluster is unlikely to discover the second variable.

Suggested improvement:

List both variables together on the external-ClickHouse reference page with a short note that they control whether qan-api2 migrations create ReplicatedMergeTree vs plain MergeTree.  
State that this is a one-shot decision: changing the flags after tables already exist requires dropping the pmm database and re-running migrations (golang-migrate doesn’t retro-convert engines).  
Cross-link the external-ClickHouse and HA-cluster pages.  
Optional: have qan-api2 log a WARN at startup if it sees a multi-replica cluster in system.clusters but IS\_CLUSTER is not set — would catch the misconfiguration without any docs change.

Thanks!