A newer version of this documentation is available.

View Latest

XDCR Management Overview

      +
      Cross Datacenter Replication (XDCR) provides an easy way to replicate data from one cluster to another.

      What is XDCR?

      Cross Data Center Replication (XDCR) replicates data between clusters: this provides protection against data-center failure, and also provides high-performance data-access for globally distributed, mission-critical applications.

      Note that Couchbase has modified the license restrictions to its Couchbase Server Community Edition package, for version 7.0 and higher: in consequence, XDCR is promoted to a commercial-only feature of Enterprise Edition. See Couchbase Modifies License of Free Community Edition Package, for more information on the license restrictions; and see XDCR and Community Edition, below, for information on how the new restrictions affect the experience of Community-Edition administrators.

      XDCR replicates data from a specific bucket on the source cluster to a specific bucket on the target cluster. Any bucket (Couchbase or Ephemeral) on any cluster can be specified as a source or a target for one or more XDCR definitions. Scopes and collections, within source and target buckets, can also be specified. Data from the source is pushed to the target bucket by means of an XDCR agent, running on the source cluster, using the Database Change Protocol.

      Note that XDCR can only be established between clusters whose numbers of vBuckets are equal: all supported platforms have 1024 vBuckets except MacOS, which has 64. For more information, see vBuckets.

      A complete architectural description of XDCR is provided in Cross Data Center Replication (XDCR). You may wish to familiarize yourself with the information provided there, before performing the routines provided in this section.

      For information on scopes and collections, see Scopes and Collections.

      What XDCR Tasks Can Be Performed?

      Management of XDCR includes the following:

      • Preparation: Make sure that you have appropriate permissions for managing XDCR. Check platform sizes, configurations, and ports. Details are provided in Prepare for XDCR.

      • Reference management: Remote clusters must be registered as targets for XDCR. This requires appropriate administration credentials for the remote cluster, and the existence on that cluster of one or more buckets that can be specified as recipients of replicated data. Information on establishing references is provided in Create a Reference; and information on deleting them in Delete a Reference.

      • Replication management: Once a reference has been registered on the local cluster, it can be specified as the target for a replication. This requires that an existing source and an existing target bucket also be specified. Optionally, filters can be established, so that only documents with matching ids, fields, values, or extended attributes are replicated. Additionally, advanced settings can be configured, to ensure optimal performance. Information on establishing replications is provided in Create a Replication; and information on deleting them in Delete a Replication.

        Note that replications can be configured to occur between specific scopes and collections; as described in Replicate Using Scopes and Collections.

      • Pausing and Resuming replications: Once started, a replication is continuous; mutations on the source being constantly transmitted to the target. Occasionally, for purposes of system maintenance, it may be desirable manually to pause a replication, and then resume it. Information is provided in Pause a Replication; and Resume a Replication.

      • Recovering Data: In the event of data-loss, the cbrecovery tool can be used to restore data. The tool accesses remotely replicated buckets, previously created with XDCR, and copies appropriate subsets of their data back onto the original source-cluster. Information is provided in Recover Data with XDCR.

      How to Use This Section

      This section is divided into multiple subsections, each of which presents step-by-step examples of how to perform a particular XDCR management task. In most subsections, three examples are provided, showing how to perform the same task with Couchbase Web Console, CLI, and REST API respectively. The subsections are arranged in a sequence, to make it easy to start from the first example, Prepare for XDCR, and proceed to the last.

      XDCR and Community Edition

      Couchbase has modified the license restrictions to its Couchbase Server Community Edition package, for version 7.0 and higher: in consequence, XDCR is promoted to a commercial-only feature of Enterprise Edition.

      Consequently, prior to any attempt to add a remote cluster, the XDCR screen displays the following message:

      xdcr screen ce

      The provided link takes the reader to detailed information on the new license restrictions, at Couchbase Modifies License of Free Community Edition Package.

      Attempts to establish replications cause the following console message to be displayed:

      xdcr console message ce

      Community-Edition adminstrators who wish to upgrade to version 7.0 or later, and wish to use XDCR, are recommended to consult Couchbase Modifies License of Free Community Edition Package, for guidance.