Skip to content

DOC-13858 Server File-Based Rebalance for Data Service #4105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rao-shwe wants to merge 9 commits into
base: release/8.1
Choose a base branch
from
Open

DOC-13858 Server File-Based Rebalance for Data Service #4105

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
dfd4845
basic-draft-of-all-sections-fbr-for-kv
rao-shwe Apr 15, 2026
3a8583c
fixed-formatting-issues
rao-shwe May 7, 2026
486fe1d
Spilt up Shwetha's monolithic doc and did lots of cleanup. Not ready …
ggray-cb May 19, 2026
0cb76b8
Apply suggestions from code review
ggray-cb May 19, 2026
c3e92c0
Fixing issue spotted by CoPilot.
ggray-cb May 19, 2026
8d7468a
Adding attribute for to Totoro release to What's New
ggray-cb Jun 24, 2026
7f3e8eb
Missed a few
ggray-cb Jun 24, 2026
dac8b86
Removing more 8.1 references.
ggray-cb Jun 24, 2026
285cc4c
Updates to What's New based on Hyun Ju's feedback.
ggray-cb Jul 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions modules/ROOT/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -358,6 +358,7 @@ include::cli:partial$cbcli/nav.adoc[]
**** xref:rest-api:rest-cluster-removenode.adoc[Removing Nodes from Clusters]

*** xref:rest-api:rest-rebalance-overview.adoc[Rebalance]
**** xref:rest-api:file-based-data-rebalance.adoc[]
Comment thread
ggray-cb marked this conversation as resolved.
**** xref:rest-api:rest-retrieve-cluster-rebalance-reason-codes.adoc[Getting Rebalance Reason Codes]
**** xref:rest-api:rest-cluster-rebalance.adoc[Rebalancing the Cluster]
**** xref:rest-api:rest-get-rebalance-progress.adoc[Getting Rebalance Progress]
Expand Down
7 changes: 4 additions & 3 deletions modules/introduction/pages/whats-new.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,17 @@
= What's New in Version 8.1
= What's New in Version {totoro}
:description: Couchbase is the modern database for enterprise applications.
:page-aliases: security:security-watsnew
:totoro: codename Totoro release
:page-toclevels: 2

[abstract]
{description} +
Couchbase Server 8.1 combines the strengths of relational databases with the flexibility, performance, and scale of Couchbase.
Couchbase Server {totoro} combines the strengths of relational databases with the flexibility, performance, and scale of Couchbase.

For information about platform support changes, deprecation notifications, and fixed and known issues, see the xref:release-notes:relnotes.adoc[Release Notes].

[#new-features-81]
== New Features and Enhancements in 8.1.0
== New Features and Enhancements in {totoro}

This release introduces the following new features.

Expand Down
46 changes: 36 additions & 10 deletions modules/introduction/partials/new-features-81.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[#section-new-feature-810-platform-support]
=== Platform Support

Couchbase Server 8.1 adds support for the following operating systems:
Couchbase Server {totoro} adds support for the following operating systems:

* TBD

Expand All @@ -13,24 +13,50 @@ TBD

=== Data Service Changes

Couchbase Server 8.1 introduces several new features for the Data Service.
Couchbase Server {totoro} introduces several new features for the Data Service.

TBD
==== File-Based Rebalance (FBR)

Couchbase Server {totoro} introduces File-Based Rebalance (FBR) for the Data Service.
FBR accelerates cluster rebalance by copying vBucket storage files directly between nodes rather than streaming data through the DCP (Database Change Protocol) replication pipeline.
This eliminates the serialization and pipeline overhead of DCP backfill for large, disk-resident datasets.

The following changes apply to the Data Service rebalance behavior in {totoro}:

* *File-Based Rebalance*: FBR transfers vBucket data files directly from the source node to the destination node during the backfill phase of a vBucket move, bypassing the full DCP backfill mechanism used in prior releases.

* *Enabled by default*: FBR is enabled by default for Couchbase Server Enterprise Edition, both for self-managed deployments and Couchbase Capella.
No configuration is required to activate it.

* *Automatic rebalance type selection*: Couchbase Server automatically determines if it can use FBR to move a vBucket.
If it cannot, it automatically falls back to copying the vBucket using DCP.

* *New bucket-level rebalance type setting*: A new per-bucket setting, `dataServiceRebalanceType`, allows operators to control rebalance behavior at the bucket level, overriding the cluster-level FBR setting.

* *Separate vBucket move concurrency for FBR*: A new setting, `dataServiceFileBasedRebalanceMovesPerNode`, controls the maximum number of concurrent file-based vBucket moves per node.
This is independent of the existing `rebalanceMovesPerNode` setting, which applies to DCP rebalance.

@hyunjuV hyunjuV Jul 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is also a new File-Based Rebalance throttle rate setting (snapshot_download_throttle_bytes) which sets the max rate at which file-based rebalance snapshots will be transferred between nodes. Very high transfer rates means that rebalance will proceed very quickly but may have a negative impact on KV operation latencies during rebalance. A value of 0 means that snapshot transfer is unthrottled.

Additional details:

  1. snapshot_download_throttle_bytes is an option in GET, POST /pools/default/settings/memcached/global

  2. In the UI (under Advanced Rebalance Settings for the Data Service), the setting of 150 MiB/s translates to snapshot_download_throttle_bytes=157286400. By default, the value is 0 (unthrottled).

  3. The rate of FBR snapshots transfer can be seen with a rate function applied to the metric kv_ep_snapshot_read_bytes.

* *Data transfer rate throttle*: The new `snapshot_download_throttle_bytes` setting lets you limit FBR's data transfer rate between nodes.
Setting this value to too high (or setting it to 0, which makes those transfers unlimited) can increase the latency of KV operations.

NOTE: FBR is an Couchbase Server Enterprise Edition feature.
Couchbase Server Community Edition continues to use DCP-based rebalance for all vBucket moves.

See xref:learn:clusters-and-availability/rebalance.adoc#file-based-rebalance[File-Based Rebalance] for more information.

=== Non-Data Services

Couchbase Server 8.1 release has key non-Data Services enhancements.
Couchbase Server {totoro} release has key non-Data Services enhancements.


=== Couchbase Cluster

Couchbase Server 8.1 release has added cluster enhancements and diagnostic capabilities.
Couchbase Server {totoro} release has added cluster enhancements and diagnostic capabilities.

[#unstable-metric]
==== New Metric to Detect Unstable Nodes

Couchbase Server 8.1.0 introduces a new metric, `cm_node_unreachable_total`, to help you monitor for unstable nodes in your cluster.
Couchbase Server {totoro} introduces a new metric, `cm_node_unreachable_total`, to help you monitor for unstable nodes in your cluster.
An unstable node periodically becomes unavailable but recovers before the auto failover timeout expires.
This metric counts the number of times a node has been unable to reach another node in the cluster.
By monitoring it, you can identify nodes that are having issues before they become unavailable for long enough to be automatically failed over.
Expand All @@ -39,25 +65,25 @@ See xref:learn:clusters-and-availability/unstable-nodes.adoc[] for more informat

=== XDCR

Couchbase Server 8.1 release has key cross datacenter replication (XDCR) enhancements and diagnostic capabilities.
Couchbase Server {totoro} release has key cross datacenter replication (XDCR) enhancements and diagnostic capabilities.

TBD.

=== Security and Authentication

Couchbase Server 8.1 release has key security and authentication enhancements.
Couchbase Server {totoro} release has key security and authentication enhancements.

TBD.

=== Query Service

Couchbase Server 8.1 release adds these Query Service features.
Couchbase Server {totoro} release adds these Query Service features.


TBD.

=== Search Service

Couchbase Server 8.1 introduces several new features for the xref:search:search.adoc[Search Service].
Couchbase Server {totoro} introduces several new features for the xref:search:search.adoc[Search Service].

TBD.
Loading