XDCR is an essential tool for database High-Availability, Disaster-Recovery, and Geo Locality. Collections support in Couchbase Server 7.0 includes major XDCR architectural improvements. They now enable XDCR to micro-service specific data replication or tenant specific data replication for multi-tenant applications. This blog will introduce a new collections replication management feature, and describe an under-the-hood XDCR replication architectural improvement. These improvements enable a whole new dimension of replication use cases. We are confident that XDCR will position Couchbase Server 7.0 to be ready to support many more micro-service or multi-tenant application use cases that will become more prevalent in the near future.

If you’re unfamiliar with Couchbase Collections, please feel free to read another well-written blog on collections before continuing.
If you would like a refresher on XDCR basic architecture, please read this blog.
We will touch on the subject of Advanced filtering, which is explained in another blog.
We will briefly mention a 6.5 feature called Replication Priority. This blog contains more information.

XDCR Collections Mapping

Couchbase Server 7.0 Buckets now contain individual namespaces called Scopes and Collections. When observing collections from a single cluster, it is relatively straightforward. However, since XDCR replication leads to multi-dimensional scaling, managing Scopes and Collections becomes more complex.

A single unique XDCR’s replication can exist between a source and a target bucket. This requirement isn’t changing. Instead, we are introducing a new concept of “mapping” to support managing collections within a bucket-to-bucket replication. More specifically, we are introducing two types of mappings: “implicit mapping” and “explicit mapping”.

At its core, a mapping is a link between two namespaces of the same level, and it exists in the context of a bucket-to-bucket replication. A mapping can be between scopes, or between collections. Each bucket-to-bucket replication will use either implicit or explicit mapping to perform replication between source and target collections. Replications use implicit mapping unless otherwise explicitly (pun intended) specified.

Implicit Mapping

Implicit mapping is the concept that a linkage should be established if the same named namespace exists in both the source and target buckets. This means that if both the source and target bucket contain identically named scope and collections, then they are implicitly mapped. For example, a source bucket contains a namespace Scope1.Collection1. Implicit Mapping states replication will take place if the target bucket also contains Scope1.Collection1.

Figure 1: Replication between two buckets given Implicit Mapping

Figure 1 shows a bucket-to-bucket replication using implicit mapping. Note that (not shown in the figure) source default collections and target default collections are mapped together. Also, any unmapped namespaces will not have any data replicated. If the unmapped namespaces are created, XDCR will catch up missing data using a backfill replication. A later section will explain this.

Explicit Mapping

For users who require more granular control, they may use Explicit Mapping. Explicit mapping requires users to explicitly define namespace relationships. Mapping a scope to another scope means all collections within them are implicitly mapped. Moreover, mapping a collection to another collection will not affect any other namespaces.

Explicit mapping is accomplished via the use of mapping rules via CLI. The XDCR Console UI will provide an abstraction so that the rules do not have to be entered manually. The Couchbase Server documentation will include a detailed explanation of the mapping rules and how to use them. In essence, the rules describe how explicit mapping should work. They programmatically tells XDCR how to match the namespaces by name.


Figure 2: Replication between two buckets using Explicit Mapping, specifying two rules: a scope-to-scope mapping rule and a collection-to-collection mapping rule

Explicit Mapping Rules brings a new level of flexibility in mapping collections. Users can also change the rules on the fly. Using the new rules, XDCR will intelligently ensure that all the data are replicated. (The next section will cover this). These two features should powerfully address many different use cases.

Figure 3: XDCR UI provides an easy-to-use experience for setting up explicit mapping and hides the need to manually enter mapping rules

Collections Migration

Upon upgrading to Couchbase Server 7.0, all the data will reside in the bucket’s default collection. XDCR provides the online solution (without application downtime) to migrate data to individual collections on a target bucket via the “migration mode”. Migration mode is a specialized version of the explicit mapping. It utilizes the XDCR Advanced Filtering engine from Couchbase Server 6.5 to perform stream-based filtering as documents are being streamed from the source bucket. Depending on the migration rules specified, the document will then be replicated to the specified target collection.

Figure 4: Migration Mode using different migration rules to route documents to their respective locations

Couchbase Server documentation will have more details on migration mode.


Main Pipeline

When a replication is created, it is translated into a “Replication Specification” and stored internally. XDCR then reads the specs (and its settings), and creates a pipeline that requests data from the source bucket. The pipeline faithfully replicates each document to the target bucket (barring any advanced filtering in place). The above process remains the same in Couchbase Server 7.0. This means that if a source bucket contains multiple source collections, XDCR will request them all. This is a “Main Pipeline”. The main pipeline replicates a source document to the target using the implicit or explicit routing. If the target cluster does not contain the mapped namespace, XDCR will drop the document “on the floor”. It then continues to replicate the next mutation.

Figure 5: Replicating all documents from source bucket with a missing target collection

During replication, XDCR will continuously watch for new or removed target collections. When it detects a new target collection, it will check to see if the new mapping can be established. If it can, then the main pipeline will now successfully replicate the data to the target namespace. A replication stream is in the form of sequence. If XDCR previously dropped a document, sequence stream cannot “rewind” to an earlier point for the missed document. XDCR needs to replicate any missed mutations. Otherwise, there will be missing data.

One side note: This above inability to rewind (without collections) is exactly why there is an option called “Save and Restart Replication” when editing the Advanced Filtering Expression in Couchbase Server 6.5. When “Save and Restart Replication” is used, the pipeline starts over and streams from sequence 0 to ensure that all documents are replicated. Obviously, this solution wouldn’t work for collections.

Backfill Pipeline

In Couchbase Server 7.0, XDCR now introduces a new internal concept called “Backfill Pipeline”. The Backfill Pipeline’s purpose is to stream data that the main pipeline has dropped earlier. This ensures that all the data from a namespace is replicated. When a new target collection is detected, and once XDCR detects the new collection, XDCR will automatically create a backfill pipeline and stream the missing data. In the meantime, the main pipeline will remain responsible for streaming any ongoing mutations to the new target collection.

The backfill pipelines will always be started in low priority mode to minimize the performance impact on the main pipelines. Once the backfill pipeline has finished streaming missing data (based on a definite end sequence number), then the backfill pipeline is automatically torn down. The whole process happens silently behind the scenes without the need to alert the users, as the backfill pipeline’s construction and teardown are completely automated. However, this architecture may cause users to notice that some documents created later in time on the source buckets arrive prior to the earlier mutations.

Figure 6: Backfill Pipeline streaming data for CollectionB only for previously missed sequence numbers

Figure 6 shows the combination in action. A new collectionB was created on the target bucket. XDCR on Cluster A detected the new collection when its main pipeline was streaming out mutations at sequence number 200. It then created a backfill pipeline, which is responsible for collectionB mutations from sequence number 0 to 200. All ongoing collectionB mutations (201+) will go through the main pipeline.

In summary, the main pipeline enables XDCR to continue to replicate the latest mutations continuously; the backfill pipeline allows a lower priority replication stream to replicate any previously missed data.

Tying it Together

XDCR Collections Replication ultimately builds on the concepts presented above. Moreover, given that XDCR intelligently monitors both source and target collections management changes, it can replicate either dynamically (via implicit mapping) or programmatically (via explicit mapping). XDCR Collections allows users to dynamically change modes between implicit and explicit mapping, as well as the ability to modify explicit mapping rules on the fly without the need to restart replication from sequence 0.

Collections in Couchbase Server 7.0 will open up many more use cases. With XDCR’s Collection support, and the flexibility of management that it provides, Couchbase Server will be able to address even more customer needs than any previous releases.

Posted by Neil Huang, Senior Software Engineer, Couchbase

Neil Huang is a Senior Software Engineer at Couchbase, and is a developer for cross datacenter replication (XDCR). Neil has more than 10 years of experience working in enterprise software. Prior to Couchbase, he was a member of the data stack software team for Enterprise Data Storage, HPE-3PAR, as well as a data storage startup building a next-generation distributed data platform. Neil received both his bachelor’s degree in electrical engineering/computer engineering and master’s degree in computer network engineering from UCLA.

Leave a reply