Cluster management¶

If you're on an Enterprise plan with dedicated infrastructure and have access to the private beta, you can manage your ClickHouse® cluster replicas directly from the Plan & Billing page. This allows you to horizontally scale your cluster by adding or removing replicas and controlling how read and write workloads are distributed across them.

Access Cluster Management¶

To manage your cluster replicas:

1. Navigate to Organization settings from the sidebar.
2. Go to the Plan & Billing section.

This opens the cluster management interface where you can view your current replicas and their configurations.

Understanding replica configuration¶

Each replica in your cluster has the following configuration:

Managing a Cluster¶

Add a replica¶

To add a new replica to your cluster:

1. In the cluster management interface, select Add new replica.
2. Configure the Read and Write weights
3. Select the CPU and memory configuration from the dropdown.
4. Review the cost impact shown below the configuration.
5. Select Add replica.

Cost implications¶

Adding replicas increases your monthly credit consumption. The exact cost depends on the CPU and memory configuration you select. Cost estimates are displayed in the interface before you add a replica.

Remove a replica¶

To remove a replica from your cluster:

1. In the cluster management interface, locate the replica you want to remove.
2. Click the × icon next to the replica.
3. Adjust the replica weights to redistribute traffic across remaining replicas.
4. Confirm the removal by selecting Delete replica.

Rebalance traffic across replicas¶

You can control how your workload is distributed across replicas by adjusting their weights:

1. Modify the Read weights to control query traffic distribution.
2. Adjust Write weights to control which replicas handle data ingestion.
3. Select Save changes to apply the new configuration.

How Weight Distribution Works¶

Weights determine the proportional distribution of traffic across replicas using a weighted round-robin approach:

• Read weights: Query traffic is distributed proportionally based on each replica's read weight relative to the total of all read weights. At least one replica must have a non-zero read weight. If a replica has a read weight of 0, it will not receive any query traffic.
• Write weights: Currently, only one replica can have a non-zero write weight (multi-writer support coming in the future). The ingestion traffic will be routed to the replica with non-zero write weight.
• Valid range: Each weight must be between 0 and 65535.
• Required minimums: At least one replica must have a non-zero read weight, and exactly one replica must have a non-zero write weight.

Weight distribution examples¶

Read traffic distribution¶

• Example 1: equal distribution of query traffic across replicas (useful when all replicas have the same size)
  • replica-a [R: 1], replica will receive 50% of query traffic
  • replica-b [R: 1], replica will receive 50% of query traffic
• Example 2: non-equal distribution of query traffic across replicas (useful when replicas have different sizes)
  • replica-a [R: 1], replica will receive 33% of query traffic (1/3)
  • replica-b [R: 2], replica will receive 67% of query traffic (2/3)
• Example 3: non-equal distribution of query traffic across replicas (useful when replicas have different sizes)
  • replica-a [R: 10], replica will receive 17% of query traffic (1/6)
  • replica-b [R: 20], replica will receive 33% of query traffic (2/6)
  • replica-c [R: 30], replica will receive 50% of query traffic (3/6)

Write traffic distribution¶

• Example 1:
  • replica-a [R: 1], replica will receive 100% of ingestion traffic
  • replica-b [R: 0], replica will receive 0% of ingestion traffic
  • replica-c [R: 0], replica will receive 0% of ingestion traffic

Example cluster traffic distribution¶