ClickHouse® cluster fault tolerance

Last update: September 29 2026Open in Markdown

The following factors affect ClickHouse® cluster fault tolerance:

• presence of data replication;
• node allocation type.

Data replication

Replication is supported only for replicated tables. Read more about replicated tables in the ClickHouse® documentation Replicated* table engines.

To ensure data replication and make creating replicated tables available, the cluster must consist of:

• at least one shard with two or more nodes;
• and the ClickHouse® Keeper node group.

You can specify the number of nodes in a shard when creating a cluster. You can also add or delete nodes in a shard of an existing cluster. The maximum number of nodes in a shard is ten.

If you specify more than one node in a shard when creating a cluster, ClickHouse® Keeper will be added automatically.

To add nodes to an existing cluster consisting of one shard with one node, you must first add ClickHouse® Keeper. When adding ClickHouse® Keeper, existing MergeTree tables are automatically converted to replicated ones (for example, to ReplicatedMergeTree). When new nodes are added to such a cluster, they are automatically synchronized with existing replicas in the shard.

Node allocation type

The node allocation type in a cluster depends on:

• the number of nodes in shards;
• the type of pool in which the cluster is located;
• the number of segments in the pool;
• the configuration line.

You can view the list of pools and segments in the Selectel Infrastructure table of the Locations: countries, regions, availability zones, pools, and data center addresses.

Four node allocation types are available:

• Single-Segment;
• Multi-Segment;
• Single-AZ;
• Multi-AZ.

Single-Segment

Nodes are placed in one segment of a single-AZ pool. Applicable:

• for clusters consisting of one shard with one node;
• shards with multiple nodes if the cluster is located in a pool that consists of one segment;
• shards with multiple nodes in configurations of the HighFreq line.

note

For example, you have created a cluster in the ru-2 pool with ClickHouse® Keeper and a shard with two nodes. For both groups of nodes, you used configurations from the HighFreq line. All nodes will be placed in the same pool segment, for example, ru-2c.

Multi-Segment

Nodes are placed in different segments of a single-AZ pool. Applicable to clusters that consist of shards with multiple nodes if the cluster is located in a pool with multiple segments.

Segments are located in different racks of the same data center. Nodes of each shard are distributed across segments sequentially.

note

For example, you have created a cluster in the ru-1 pool with one shard containing four nodes. The first three nodes will be placed sequentially in pool segments ru-1a, ru-1b, and ru-1c. The fourth node will be placed in segment ru-1a. If you add a fifth node, it will be placed in pool segment ru-1b.

Single-AZ

Nodes are placed in a single segment of a multi-zone pool. Applicable to:

• for clusters that consist of one shard with one node if the cluster is located in the ru-6, uz-1 pools;
• clusters that consist of shards with multiple nodes if the shard has a HighFreq configuration and is located in the uz-1 pool.

note

For example, you created a cluster in the uz-1 pool with one shard that contains four nodes. You used a HighFreq configuration for the shard. All nodes will be placed in a single pool segment, for example, uz-1b.

Multi-AZ

Nodes are placed in different segments of a multi-zone pool. Applicable to:

• for clusters that consist of shards with multiple nodes if the cluster is located in the ru-6 pool;
• clusters that consist of shards with multiple nodes if shards do not use HighFreq configurations and the cluster is located in the uz-1 pool.

Each pool segment is located in a separate data center. The nodes of each shard are distributed across segments sequentially.

note

For example, you created a cluster in the ru-6 pool with one shard that contains four nodes. The first three nodes will be placed sequentially in the ru-6a, ru-6b, and ru-6c pool segments. The fourth node will be placed in the ru-6a segment. If you add a fifth node, it will be placed in the ru-6b pool segment.

Add a node

A shard can contain up to ten nodes. While a node is being added, the other shard nodes will continue to work for read and write operations.

1. If the cluster consists only of one shard with one node, add ClickHouse® Keeper.
2. In the Control panel, in the top menu, click Products and select Cloud Databases.
3. Go to the tab Active.
4. Go to the cluster page → the tab Settings.
5. In the shard's menu, select Change number of nodes.
6. Go to the tab Add.
7. Specify the new number of nodes in the shard. If there are no available IP addresses in the subnet to which the cluster is connected, you cannot add a node. Each new node occupies a new IP address in the subnet.
8. Click Save.

Delete a node

carefully

Deleting a node will delete all data stored on that node.

While deleting, the other shard nodes will continue to work for read and write operations. The public IP address associated with the node will be deleted.

1. In the Control panel, in the top menu, click Products and select Cloud Databases.
2. Go to the tab Active.
3. Go to the cluster page → the tab Settings.
4. In the shard's menu, select Change number of nodes.
5. Go to the tab Delete.
6. Select the node you want to delete. At least one node must remain in the shard. You cannot delete all nodes from a shard.
7. Click Save.

ClickHouse® is a registered trademark of ClickHouse, Inc. https://clickhouse.com.