For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10 (unreleased)

Grow a Multi-Region RDBMS cluster

Add a region to a running Multi-Region RDBMS cluster through the cluster management API, and plan the partition count.

Learn how to grow a Multi-Region RDBMS cluster from two regions to three or more.

You can add a zone to a running cluster without changing the brokers that already run. Each broker ID combines a zone name and an index, such as london_0. A new zone brings new IDs and leaves the existing ones as they are.

Three stages of the same cluster. First, two zones, london and paris, hold two replicas each, for a replication factor of four. The zurich slot exists but is not in the zone list. Losing either zone leaves two of four replicas, so processing stops. Second, the operator deploys the zurich brokers, adds the zone with POST /actuator/cluster/zones/zurich, one replica and priority 800, and waits for COMPLETED. Third, three zones in a 2-2-1 layout at replication factor five, where losing a database zone leaves three of five replicas and processing continues. The engine renumbers no broker and restarts no running region.Grow a Multi-Region RDBMS cluster by adding a zone1. Bootstrap on two zoneslondon2 replicasparis2 replicaszurich slotprovisioned, not declaredreplicationFactor 4 (2-2)Losing a zone leaves2 of 4 replicas:no majority,processing stops2. Add the zone onlinea. Deploy the zurich brokersb. Add the zone to the clusterc. Wait for COMPLETEDPOST /actuator/cluster/ zones/zurich{ "numberOfReplicas": 1, "priority": 800, "brokers": [ "zurich_0", "zurich_1" ]}3. Three zoneslondon2 replicasparis2 replicaszurich1 replica, addedreplicationFactor 5 (2-2-1)Losing a database zoneleaves 3 of 5 replicas:quorum kept,processing continuesThe engine renumbers no broker and restarts no running region.Adding a zone leaves the partition count unchanged.

Declare only the zones you deploy​

Every zone in the zone list must have its brokers running when the cluster bootstraps. Don't declare a zone to reserve it for later growth. Add it through the management API after its brokers run.

A zone in the zone list receives partition replicas even if its brokers don't run. A declared zone without brokers leaves every partition one zone short. For example, if you declare a 2-2-1 layout but deploy only the first two zones, each partition runs four of five replicas. Losing either database zone then stops processing.

Add a zone to the running cluster​

  1. Start the brokers of the new zone.
  2. Add the zone with the Add or re-add a zone request. The request body needs numberOfReplicas, priority, and either numberOfBrokers or brokers.
  3. Wait for the change to report COMPLETED. Follow it with the Monitoring API.

The engine places the zone's replicas and raises the replication factor in one change. No broker is renumbered, and the regions already running aren't restarted.

Zones runningLayoutReplication factorAfter losing one zone
Two2-24Two of four replicas: processing stops
Three2-2-15Three of five replicas at worst: processing continues

Plan the partition count​

Adding a zone doesn't change the partition count. To raise it, use partition scaling, before or after you add the zone but not during the same change. The reference implementation sizes the partition count on the provisioned region slots, so it already fits the largest topology it can grow into.