Bi-directional XDCR with Mobile Clusters

Sync Gateway versions prior to 4.0 tracked document revisions using revision trees with Multi-Version Concurrency Control (MVCC).

This approach created a tree structure for each document where branches represented conflicting updates and nodes contained revision IDs. While effective for mobile replication protocols, revision trees maintained cluster-specific metadata that prevented meaningful bi-directional replication with XDCR. Each cluster maintained its own revision tree, making it impossible to preserve revision history when documents replicated between clusters.

Version vectors provide a proven mechanism for tracking causality in distributed systems.

A version vector consists of hybrid logical clocks maintained by each component capable of updating documents in the distributed environment. Each instance of Couchbase Lite represents its own component in the version vector, while Sync Gateway and XDCR interact with the component associated with the cluster-specific Couchbase Server bucket. Each component increments its own count when making changes, creating a vector that captures the complete update history across all participating actors.

This architectural change enables:

The version vector metadata travels with documents during replication, ensuring that revision history remains intact regardless of which cluster processes the document.

Document mutations flow through an orchestrated pipeline that preserves mobile metadata while preventing replication loops.

When a document changes in either cluster, Sync Gateway assigns version vector updates that include the identifier and incremented count. XDCR recognizes these version vectors and replicates the document while preserving the metadata. The receiving cluster’s Sync Gateway processes the incoming document through its import mechanism, recognizing that the version vector indicates an external update that does not require additional versioning.

XDCR automatically filters cluster-specific metadata to prevent corruption of local state.

System documents with the _sync: prefix remain local to each cluster — these include sequence trackers, user definitions, and role assignments. Document-level sync metadata in extended attributes gets selectively replicated, with cluster-local information like sequence numbers filtered while global metadata like version vectors passes through. This filtering happens transparently without requiring manual configuration.

Enable cross-cluster versioning on all participating buckets to support version vectors.

Apply the enableCrossClusterVersioning=true configuration to buckets on both source and target clusters before establishing replication.

Sync Gateway 4.0 requires no additional configuration for bi-directional XDCR support.

Sync Gateway 4.0 enforces shared bucket access by default, enabling coexistence with direct SDK writes and XDCR replication. Sync Gateway Enterprise Edition enables document import processing by default, automatically handling replicated documents from XDCR.

The configuration involves two clusters with bi-directional replication between them.

Both clusters run Sync Gateway in active mode, processing reads and writes from mobile clients. Load balancers distribute traffic based on geographic proximity or availability. This topology provides the foundation for zero-downtime disaster recovery and global data distribution. Testing and validation have focused primarily on two-cluster deployments.

Clients maintain independent checkpoints for each cluster they connect to.

When a client connects to a cluster for the first time, it begins replication from sequence zero, checking which documents are missing and need downloading. The client stores this checkpoint locally, associated with the cluster’s identifier. Subsequent connections to the same cluster resume from the stored checkpoint, downloading only changes since the last sync. This mechanism prevents redundant data transfer when clients switch between clusters.

Different Couchbase Lite versions exhibit varying levels of support for bi-directional XDCR deployments.

Couchbase Lite 4.0 provides full support, including the ability to switch between clusters while maintaining consistency. Earlier versions (3.x and 2.x) can synchronize with Sync Gateway 4.0 but cannot switch between clusters without potential consistency issues.