Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

XDCR — Server Compatibility

      +

      How Sync Gateway works with Couchbase Server’s Cross Data Center Replication (XDCR).
      Sync Gateway provides multiple approaches for replicating mobile data across clusters, with capabilities evolving significantly in version 4.0 to support bi-directional XDCR for active-active deployments.

      Related topics: Buckets | Collections | Eventing | Transactions | XDCR | Backup and restore

      Other Topics: Compatibility Matrix

      Introduction

      Couchbase Server provides the backing data store for Sync Gateway.

      See: Compatibility Matrix for version compatibility information.

      Both Couchbase Mobile and Couchbase Server Cross Data Center Replication (XDCR) provide for efficient and secure replication of data, using different replication technologies optimized for specific use cases.

      Sync Gateway provides different replication approaches depending on your version and use case requirements:

      • Sync Gateway 4.0+: Bi-directional XDCR with version vectors enables active-active mobile clusters

      • Sync Gateway < 4.0: Inter-Sync Gateway Replication for active-active, unidirectional XDCR for specific scenarios

      Here we provide details on how XDCR feature relates to the Couchbase Mobile ecosystem.

      Cross Data Center Replication (XDCR)

      Couchbase Server’s Cross Data Center Replication (XDCR) replicates necessary Sync Gateway metadata along with associated documents, making it suitable for various mobile cluster replication scenarios.

      Bi-directional XDCR

      Sync Gateway 4.0 introduces support for bi-directional XDCR between active mobile clusters through an architectural change from revision trees to version vectors.

      This enables active-active deployments where multiple clusters can process writes simultaneously while maintaining data consistency across geographically distributed datacenters. Both clusters process reads and writes from mobile clients simultaneously.

      Sync Gateway 4.0 uses automatic conflict resolution with a Last-Write-Wins method and hybrid logical clocks by default. Clients can switch seamlessly between clusters without data loss. This provides zero-downtime disaster recovery with immediate fail-over capabilities.

      For detailed technical implementation and configuration requirements, see: Bi-directional XDCR Active-Active with Mobile Clusters.
      xdcr active active replication
      Figure 1. Bi-directional Active-Active XDCR

      Unidirectional XDCR

      Unidirectional XDCR remains valuable for scenarios where you need to replicate the entire dataset from a source bucket to a target bucket without requiring bi-directional synchronization.

      In these deployments, you should deploy Sync Gateway only at one end of the XDCR-replicated bucket (source or target) — see: Example 1.

      Example 1. Unidirectional XDCR Replication

      In this example XDCR deployment:

      • XDCR runs unidirectionally, pushing data from the primary datacenter to the secondary datacenter

      • Data gets pulled by Sync Gateway for downstream clients at the target location

      • Sync Gateway deploys at both ends but operates in read-only mode at the target end to prevent write conflicts

      xdcr data replication to read only
      Figure 2. Unidirectional XDCR Replication

      Disaster Recovery Scenarios

      XDCR serves important roles in mobile cluster disaster recovery, supporting both traditional backup scenarios and modern zero-downtime active-active deployments.

      Traditional Disaster Recovery

      In traditional disaster recovery scenarios, XDCR supports data migration and backup operations where Sync Gateway operates at only one end of the unidirectional XDCR replication.

      Zero Downtime Active-Active Disaster Recovery

      This model provides zero-downtime disaster recovery using bi-directional XDCR between two active mobile clusters. This requires running Sync Gateway 4.0+ on both sides of the active-active XDCR setup. Both clusters remain operational, with seamless fail-over through load balancer switching. You must configure both clusters with import_docs=true.

      Set Up

      To set up zero-downtime disaster recovery:

      1. Configure bi-directional XDCR between the Primary and disaster recovery clusters.
        Enable automatic filtering of cluster specific metadata.

      2. Deploy Sync Gateway in active mode on both clusters.

      3. Configure users, roles, and databases independently on both clusters.
        XDCR replicates documents and attachments, but you must configure users, roles, and databases separately on each cluster.

      4. Configure your load balancer to route traffic primarily to the Primary cluster.

      5. Verify replication health between the two active clusters.

      xdcr active active replication
      Figure 3. DR Cluster Setup (Active-Active)
      Activation

      To activate disaster recovery:

      1. Update load balancer configuration to redirect traffic to the disaster recovery cluster.
        This process requires no Sync Gateway service interruption.

      2. Verify disaster recovery cluster is handling traffic properly.

      3. Maintain bi-directional replication for recovery preparedness.
        The original primary becomes the new DR cluster automatically and requires no manual XDCR reconfiguration.

      Clusters in Same Region

      This model caters for situations where the Active and Disaster Recovery clusters are in the same region or datacenter — see: Figure 4. It includes an optional optimization step, which confirms that there is no downtime during the activation stage.

      Set Up

      To set up and maintain a disaster recovery cluster:

      1. [Optional step — for optimization] Start Sync Gateway with offline: true in the Disaster Recovery cluster to asynchronously create indexes. Creating all indexes beforehand reduces switching costs.
        If you skip this test, you’ll incur latency when Sync Gateway switches to the Disaster Recovery cluster and Sync Gateway rebuilds its indexes.

      2. Connect Sync Gateway to your Primary cluster.

      3. Start the unidirectional XDCR from the Primary cluster to the Disaster Recovery cluster.

      sgw xdcr dr same regn setup
      Figure 4. DR Cluster Setup (Clusters in Same Regions)
      Activation

      When you’re ready to switch to Disaster Recovery operations:

      1. Stop the replication (XDCR) from the Primary cluster to Disaster Recovery cluster.

      2. After you stop XDCR: Switch the Load Balancer to point to the Sync Gateway on the Disaster Recovery cluster. This approach keeps the deployment of Sync Gateway at only 1 end of the XDCR replication.

      3. Promote the Disaster Recovery cluster to Primary and the old Primary to Disaster Recovery.

      4. Flush all replicated buckets in the Primary cluster as a precaution against any spurious writes that enter the Primary cluster and XDCR fails to replicate when you stop it.

      5. Reverse the XDCR to replicate from the newly promoted Primary to the old Primary to set up a new Backup.

      sgw xdcr dr same regn in recovery
      Figure 5. DR Cluster In-recovery (Clusters in Same Regions)

      Clusters in Different Regions

      This model caters for situations where the Active and Disaster Recovery clusters are in different regions or data centers. Although the model has a separate Sync Gateway cluster attached to the Disaster Recovery cluster, this approach keeps the deployment of Sync Gateway at only 1 end of the XDCR replication. The optional optimization step confirms that there is no downtime during the activation stage.

      Set Up

      To set up and maintain a disaster recovery cluster - see: Figure 6:

      1. [Optional step — for optimization] Start Sync Gateway with offline: true in the Disaster Recovery cluster to asynchronously create indexes. If you skip this test, you’ll incur latency when you switch Sync Gateway to the Disaster Recovery cluster and Sync Gateway rebuilds its indexes.

      2. [Critical step] Turn off all the Sync Gateways in the Disaster Recovery cluster.

      3. Start the unidirectional XDCR from the Primary cluster to the Disaster Recovery cluster.

      sgw xdcr dr diff regn setup
      Figure 6. DR Cluster Setup (Clusters in Different Regions)
      Activation

      When you’re ready to switch to Disaster Recovery operations — see: Figure 7:

      1. Stop Sync Gateway on the Primary cluster

      2. Stop the replication (XDCR) from the Primary cluster to the Disaster Recovery cluster.

      3. Verify that any and all Load Balancer updates to direct all traffic to the new Sync Gateway clusters.

      4. Turn on the Sync Gateway cluster in the Disaster Recovery cluster.

      5. Assign the Disaster Recovery cluster to be the new Primary cluster, and make the old Primary cluster the new Disaster Recovery cluster.

      6. Flush all replicated buckets in the Primary cluster as a precaution against any spurious writes coming into the Primary cluster that XDCR did not replicate when you stopped it.

      7. Reverse the original XDCR to replicate from the newly promoted Primary to the old Primary, to set up a new Backup.

      sgw xdcr dr diff regn in recovery
      Figure 7. DR In-Recovery (clusters in different regions)

      Inter Sync Gateway Replication

      For Sync Gateway versions prior to 4.0, Inter-Sync Gateway Replication was the primary solution for active-active mobile cluster deployments.

      Sync Gateway 4.0 introduces native bi-directional XDCR support for active-active mobile clusters, providing a simpler and more efficient alternative to Inter-Sync Gateway Replication. See Bi-directional XDCR.

      Inter-Sync Gateway replication was specifically designed to keep mobile clusters in different data centers in sync, with the ideal use-case being edge clusters containing active Sync Gateway nodes replicated between geographically separate cloud-based Sync Gateway deployments.

      See: Inter Sync Gateway Sync - Overview for complete implementation details.

      Inter-Sync Gateway replication provides bi-directional read/write replications that verify:

      • Sync Gateway observes cluster-specific security by invoking the appropriate Sync Function

      • Sync Gateway maintains the integrity of security history with historical access rules held in metadata

      • All clusters use a consistent Revision Id, allowing clients to identify a revision regardless of cluster location

      • Cluster-specific _sync documents remain local and are not replicated to other mobile clusters

      icr active mobile sync
      Figure 8. Inter-Sync Gateway Active-to-Active Replication
      To upgrade to Sync Gateway 4.0 and enable bi-directional XDCR for active-active mobile clusters, see: Upgrading Sync Gateway.

      Related Content

      Learn more …​
      Reference material …​
      Community

      Mobile Forum | Blog | Blog (Mobile) | Tutorials

      Sync Function Blogs