// What runs on ZooKeeper / clickhouse

Does ClickHouse use ZooKeeper?

ZooKeeper or ClickHouse Keeper

For replicated tables, ClickHouse needs a coordination service: ZooKeeper 3.4.5 or newer, or ClickHouse Keeper, which the documentation recommends. Keeper is written in C++, uses Raft through the NuRaft library, and speaks the ZooKeeper client protocol, so ClickHouse and other ZooKeeper clients talk to it unchanged. A ClickHouse server that uses neither replication nor the other coordinated features below runs without either.

ClickHouse supportEverything else that runs on ZooKeeper

Trusted globally by enterprises

Henry ScheinEnbridgeGojekMicrosoft

What ClickHouse uses ZooKeeper for

  • ReplicatedMergeTree metadata: the replication log, part names from sequential block numbers, and the assignment of merges and mutations to replicas.
  • Insert deduplication for replicated tables, from block hash sums kept in the coordination service. Each inserted block adds roughly ten entries.
  • The distributed DDL (ON CLUSTER) queue, and coordination of ON CLUSTER backups.
  • The Replicated database engine, which keeps all of its metadata there.
  • State for the KeeperMap and S3Queue table engines, and optionally user-defined functions and access control.

Which ZooKeeper version ships with ClickHouse

ClickHouse does not bundle a ZooKeeper jar or any Java code. It talks to the coordination service through its own C++ implementation of the ZooKeeper protocol, so scanners find no ZooKeeper component in ClickHouse itself; the version that matters is the one the ensemble runs. ClickHouse Keeper ships in the clickhouse-server package and can also run standalone. The replication documentation supports ZooKeeper 3.4.5 or newer.

CVE counts are ZooKeeper's own advisories matched against the upstream version. The Apache ZooKeeper project does not assess end-of-life lines against new advisories, so "not assessed" means unknown, not safe.

Which coordination service is ClickHouse using?

-- Returns rows when a ZooKeeper-compatible service is configured
SELECT * FROM system.zookeeper_connection;

-- Replicas that have lost their coordination session
SELECT database, table, zookeeper_path FROM system.replicas WHERE is_readonly;

-- ZooKeeper replies "Zookeeper version: 3.x";
-- Keeper replies "ClickHouse Keeper version: ..."
-- echo srvr | nc zk1.internal 2181 | head -1

Can ClickHouse run without ZooKeeper?

Yes, with ClickHouse Keeper. It is protocol-compatible with ZooKeeper, but its snapshot, log and interserver formats are not, so a mixed ZooKeeper and Keeper ensemble is impossible. The documentation says a seamless migration is not possible: stop ingestion and background tasks such as merges, stop ZooKeeper, convert its logs and snapshots with clickhouse-keeper-converter (which needs ZooKeeper 3.4 or later), then start Keeper. Without any coordination service configured, ClickHouse cannot create replicated tables, and existing ones are read-only.

ClickHouse's SECURITY.md currently lists 26.9, 26.8, 26.7 and 26.3 as supported with security updates, and every 25.x release and older as unsupported. ClickHouse Keeper was declared feature complete in 21.12 (December 2021) and has run in ClickHouse Cloud since its private preview in May 2022.

Your options

Move to ClickHouse Keeper

The usual target. Plan a maintenance window: ingestion and merges stop, ZooKeeper data is converted with clickhouse-keeper-converter, and Keeper starts in its place, since the two cannot share an ensemble.

Keep ZooKeeper, patched

Where the same ensemble also serves Kafka, Solr or Hadoop, replacing it for ClickHouse alone does not retire it. OSSeva patches the shared ensemble, including the 3.4 to 3.7 lines, until it is retired.

Most teams buy this at the product level: keep the ClickHouse estate supported, including the ZooKeeper under it. See ClickHouse support.

Frequently asked questions

Can ClickHouse run without ZooKeeper?

Yes, with ClickHouse Keeper, which ClickHouse recommends. Keeper implements the ZooKeeper client protocol on top of Raft.

Can I mix ZooKeeper and ClickHouse Keeper nodes?

No. Keeper's interserver protocol and storage formats differ from ZooKeeper's, so an ensemble is one or the other. Data moves across with clickhouse-keeper-converter.

Which ZooKeeper versions does ClickHouse support?

The replication documentation says ZooKeeper 3.4.5 or newer, with ClickHouse Keeper recommended. ClickHouse uses its own C++ client, so there is no ZooKeeper library inside ClickHouse to patch.

What happens to ClickHouse if ZooKeeper is unavailable?

Replicated tables on a server that starts without it switch to read-only mode, and inserts into replicated tables fail with an exception while it is unreachable. SELECT queries do not use ZooKeeper, so reads continue.

Does ClickHouse Keeper support the same authentication as ZooKeeper?

Keeper supports ACLs with the same permissions and the world, auth and digest schemes. External authentication integrations are not supported, so an ensemble that relies on other schemes needs an access plan before the move.

Keep ClickHouse and the ZooKeeper under it supported.

Send us your versions; we reply with coverage, exposure and a plan within five working days.

Book a Discovery CallThe ZooKeeper dependency map →