Replication & Sharding

🔄 Replication

🧒 ELI5: The Backup Notebook

Imagine you're taking notes in class. Replication means your friend copies everything you write into their notebook too. If you lose your notebook, your friend still has all the notes. That's replication — keeping identical copies of data on multiple servers for safety.

How It Works

ClickHouse uses ClickHouse Keeper (or ZooKeeper) to coordinate replicas:

-- ReplicatedMergeTree = MergeTree + Replication
CREATE TABLE events_replicated (
    event_date Date,
    event_time DateTime,
    user_id UInt64,
    event_type String
) ENGINE = ReplicatedMergeTree(
    '/clickhouse/tables/{shard}/events',
    '{replica}'
)
PARTITION BY toYYYYMM(event_date)
ORDER BY (event_date, user_id);

⚠️ Replication ≠ Backup

Replication protects against server failure. But if you accidentally run DROP TABLE, it drops on ALL replicas! You still need proper backups.

🔀 Sharding

🧒 ELI5: The Pizza Slices

You have a pizza so big one person can't eat it. So you shard (slice) it — give 1/4 to each of 4 friends. Each friend eats their slice in parallel. Done 4x faster! Sharding splits your data across multiple servers so each one handles a fraction of the work.

-- Distributed table (queries all shards)
CREATE TABLE events_distributed
ENGINE = Distributed(
    'my_cluster',     -- cluster name
    'default',         -- database
    'events_local',    -- local table name
    rand()             -- sharding key
);

🏗️ Cluster Architectures

Setup	Servers	Use Case
Single Server	1	Development, small datasets (<1TB)
2 Replicas	2	High availability, no sharding needed
3 Shards × 2 Replicas	6	Medium datasets (1-50TB)
10+ Shards × 3 Replicas	30+	Petabyte-scale (Uber, Cloudflare)

Setup

Servers

Use Case

Single Server

Development, small datasets (<1TB)

2 Replicas

High availability, no sharding needed

3 Shards × 2 Replicas

Medium datasets (1-50TB)

10+ Shards × 3 Replicas

30+

Petabyte-scale (Uber, Cloudflare)

💡 ClickHouse Cloud

Don't want to manage clusters? ClickHouse Cloud handles replication, sharding, scaling, and backups automatically. It's the easiest way to run ClickHouse in production.

October 2026 practice

Checked against the ClickHouse documentation in October 2026. The JSON type has been production-ready since version 25.3. ClickHouse Cloud rewrites a MergeTree create onto the matching SharedMergeTree engine.

Self-hosted replication uses ReplicatedMergeTree and ClickHouse Keeper. Keeper replaces ZooKeeper. There is no seamless live cutover: stop ZooKeeper, convert the snapshot with clickhouse-keeper-converter, and start Keeper. Do not reuse a server_id for a different host. Back up Keeper logs and snapshots before you change disks. Sharding is a Distributed table over shards. ClickHouse Cloud hides this behind SharedMergeTree. A metadata change on SharedMergeTree is not guaranteed to be visible on every replica at the same instant. The same session on the same node already sees it.

-- Self-hosted: ReplicatedMergeTree plus a ClickHouse Keeper ensemble.
-- ClickHouse Cloud: write ENGINE = MergeTree. The service stores SharedMergeTree.