Skip to main content
Skip to main content
Edit this page

Horizontal scaling

Manual horizontal scaling​

Scale plan feature

Manual horizontal scaling is available in the Scale and Enterprise plans. To upgrade, visit the plans page in the cloud console.

You can use ClickHouse Cloud public APIs to scale your service by updating the scaling settings for the service or adjust the number of replicas from the cloud console.

Scale and Enterprise tiers also support single-replica services. Services once scaled out, can be scaled back in to a minimum of a single replica. Note that single replica services have reduced availability and aren't recommended for production usage.

Note

Services can scale horizontally to a maximum of 20 replicas. If you need additional replicas, please contact our support team.

Horizontal scaling via API​

To horizontally scale a cluster, issue a PATCH request via the API to adjust the number of replicas. The screenshots below show an API call to scale out a 3 replica cluster to 6 replicas, and the corresponding response.

PATCH request to update numReplicas

Response from PATCH request

If you issue a new scaling request or multiple requests in succession, while one is already in progress, the scaling service will ignore the intermediate states and converge on the final replica count.

Horizontal scaling via UI​

To scale a service horizontally from the UI, you can adjust the number of replicas for the service on the Settings page.

Service scaling settings from the ClickHouse Cloud console

Once the service has scaled, the metrics dashboard in the cloud console should show the correct allocation to the service. The screenshot below shows the cluster having scaled to total memory of 96 GiB, which is 6 replicas, each with 16 GiB memory allocation.

Handling spikes in workload​

If you have an upcoming expected spike in your workload, you can use the ClickHouse Cloud API to preemptively scale up your service to handle the spike and scale it down once the demand subsides.

To understand the current CPU cores and memory in use for each of your replicas, you can run the query below:

SELECT *
FROM clusterAllReplicas('default', view(
    SELECT
        hostname() AS server,
        anyIf(value, metric = 'CGroupMaxCPU') AS cpu_cores,
        formatReadableSize(anyIf(value, metric = 'CGroupMemoryTotal')) AS memory
    FROM system.asynchronous_metrics
))
ORDER BY server ASC
SETTINGS skip_unavailable_shards = 1