How Couchbase vBucket Rebalancing Distributes Data (2026)

Couchbase’s vBucket rebalancing is less about moving data and more about moving pointers to data.

Let’s watch it in action. Imagine a Couchbase cluster with three nodes: node1, node2, and node3. We have a bucket named my_bucket with 1024 vBuckets. Initially, these vBuckets are distributed evenly.

# On node1, check vBucket distribution for my_bucket
/opt/couchbase/bin/couchbase-cli bucket-vbucket-check --cluster localhost:8091 --username Administrator --password password --bucket my_bucket

The output might look something like this, showing which vBuckets are currently active on which nodes:

Bucket: my_bucket
Total vBuckets: 1024
Active vBuckets:
  node1: 0-340
  node2: 341-682
  node3: 683-1023

Now, we add a fourth node, node4. Couchbase will automatically detect this new node and initiate a rebalance.

# Add node4 to the cluster (this is typically done via the UI or API,
# but for demonstration, let's assume it's already added and rebalance is triggered)
# The trigger itself is usually a UI button click or an API call.

During rebalancing, Couchbase doesn’t copy the entire dataset. Instead, it updates the master-replica map for each vBucket. The goal is to shift the active vBucket ownership from the nodes that will be giving them up to the new node or other nodes that have capacity.

Here’s what happens under the hood:

1. Master/Replica Map Update: Couchbase maintains a mapping of which node is the master for each vBucket and which nodes hold its replicas. When a rebalance starts, this map is updated. For vBuckets that need to move their master from, say, node1 to node4, the map is changed.
2. Data Handoff (if necessary): If a vBucket’s master is moving to a node that doesn’t yet have a replica of that vBucket, the source node (e.g., node1) will stream the vBucket’s data to the destination node (e.g., node4). This is the actual data transfer, but it’s targeted per vBucket, not a full dump. If node4 already holds a replica, it might simply switch its role from replica to master.
3. Client Redirection: Crucially, Couchbase clients (SDKs) maintain a connection to the cluster and periodically fetch the latest vBucket map. When the map changes due to rebalancing, clients update their internal routing tables. They will then start sending requests for specific keys to the new master node responsible for that key’s vBucket.
4. DCP Streams: The actual data movement between nodes happens via the Couchbase Data Piped Channel (DCP) protocol. This is an efficient streaming protocol designed for replication and rebalancing.

Let’s simulate the state after rebalancing. We’ll run the same check command on node1 after the process has completed:

# After rebalance completes, check distribution again
/opt/couchbase/bin/couchbase-cli bucket-vbucket-check --cluster localhost:8091 --username Administrator --password password --bucket my_bucket

The output will show a new distribution, ideally more even:

Bucket: my_bucket
Total vBuckets: 1024
Active vBuckets:
  node1: 0-255
  node2: 256-511
  node3: 512-767
  node4: 768-1023

Notice that the range of vBuckets assigned to each node has changed. This means the master for those vBuckets is now on a different node. If node4 was added, it received ownership of some vBuckets, and other nodes gave them up. The data was streamed from the old masters to the new masters (or existing replicas that became masters) as needed.

The fundamental problem this solves is maintaining high availability and performance as your cluster scales. When you add nodes, you increase capacity. Rebalancing ensures that the workload (which keys map to which vBuckets) is distributed across all available nodes, preventing hotspots and improving throughput. Conversely, when you remove nodes, the vBuckets they owned are redistributed to the remaining nodes, again spreading the load.

The most surprising part of this process is how little data actually moves if replicas are already in place. If you have a replication factor of 2, and you add a node, the vBuckets on the node being removed might already have their replicas on the nodes that will receive them. In this scenario, rebalancing is almost entirely about updating the vBucket map and redirecting client traffic, with minimal actual data copying. The system is designed to be efficient, and leveraging existing replicas is a key part of that.

The next logical step after understanding rebalancing is how Couchbase handles node failures and automatic failover.