Understanding ClickHouse's ZooKeeper Dependency

ClickHouse uses ZooKeeper (or the built-in ClickHouse Keeper) to coordinate ReplicatedMergeTree tables. When ZooKeeper is degraded, replicated tables stop accepting writes. Understanding this dependency is critical for production ClickHouse operations.

How ClickHouse Uses ZooKeeper

For every ReplicatedMergeTree table, ClickHouse stores coordination state in ZooKeeper:

• Which data parts each replica has
• The merge order (so all replicas merge in the same order)
• Insert deduplication log
• Replica health state

Every write to a replicated table goes through ZooKeeper. ZooKeeper does not store the actual data — just the coordination metadata.

Monitoring ZooKeeper Health

-- Check ZooKeeper session state
SELECT * FROM system.zookeeper
WHERE path = '/clickhouse'
LIMIT 5;
 
-- Check ZooKeeper connection metrics
SELECT metric, value
FROM system.metrics
WHERE metric LIKE '%Zookeeper%';
 
-- Check for ZooKeeper-related errors in logs
SELECT event_time, level, message
FROM system.text_log
WHERE message LIKE '%ZooKeeper%' AND level = 'Error'
ORDER BY event_time DESC
LIMIT 20;

ClickHouse Keeper: The Modern Alternative

Since ClickHouse v22.4, clickhouse-keeper is a drop-in replacement for ZooKeeper built directly into ClickHouse. It:

• Eliminates the external Java dependency
• Uses the Raft consensus protocol
• Is easier to deploy alongside ClickHouse
• Is recommended for all new deployments

What Fails When ZooKeeper Is Down

| Operation | Affected? | |---|---| | Reads from replicated tables | No | | Writes to replicated tables | Yes — blocked | | Background merges | Yes — paused | | Replication sync | Yes — paused | | Reads from non-replicated tables | No | | Writes to non-replicated tables | No |

Clustersight monitors ZooKeeper session health and alerts you immediately when connectivity degrades, before your writes start failing.

Read more: How to Monitor ClickHouse in Production