Create a Replication
An XDCR replication allows data to be replicated continuously from a specified bucket on the source cluster to a specified bucket on the target.
An XDCR replication is created on the cluster that is to be the source of the data-replication. Each replication uses a single reference, which has already been created. (See Create a Reference.) To create the replication, you specify:
The local, source bucket from which data is to be replicated.
The remote cluster to which data is to be replicated. This cluster must already be registered on the local cluster as a reference.
The bucket on the remote cluster to which data is to be replicated.
The XDCR protocol to be used.
Whether filtering should be used in replication, and if so, according to what regular expression.
Other Advanced Replication Settings, which can be used to optimize replication-performance.
Note that multiple replications (each using a different source-target bucket combination) can be created using a single reference (which refers to a target cluster, but not to any specific bucket on it).
Examples on This Page
The examples in the subsections below show how to create the same replication; using the UI, the CLI, and the REST API respectively. As their starting-point, the examples assume the scenario that concluded the page Create a Reference, this being:
Two clusters already exist; each containing a single node. These are named after their IP addresses:
Each cluster contains a single bucket, which is the
Each cluster has the Full Administrator username of
Administrator, and password of
10.142.180.101now has a reference that specifies its own
travel-samplebucket as a source, and the
10.142.180.102as a target.
Create an XDCR Replication with the UI
Proceed as follows:
Access Couchbase Web Console. Left-click on the XDCR tab, in the left-hand navigation menu.
This displays the XDCR Replications screen, the lower part of the main panel of which is entitled Outgoing Replications:
The list, which is designed to show the name and IP address or hostname of each existing replication, is currently empty, and so bears the notification
There are currently no replications defined. Use ADD REPLICATION to set one up.
To start creating a replication, left-click on the ADD REPLICATION button:
This brings up the Add Replication dialog:
Enter appropriate information into the fields of the Add Replication dialog. Specify
10.142.180.102as the target cluster, and
travel-sampleas both source and target bucket. At this stage, do not check the
Enable advanced filteringcheckbox, and do not elect to open either Replication Filters or Advanced Replication Settings. Note that the Replication Priority pulldown menu is currently set to the default, High: do not change this. For information on the significance of the alternative settings — Medium and Low — see XDCR Priority.
The completed dialog now appears as follows.
Left-click on the Save button. The XDCR Replications screen is now redisplayed, with the appearance of the Outgoing Replications panel as follows:
This indicates that a replication is now in progress: from
bucket "travel-sample" on cluster "10.142.180.102".
This concludes creation of the replication. Note that by left-clicking on the row for the replication, additional controls can be displayed:
Use of the Pause control is described in Pause a Replication; use of the Delete control in Delete a Replication; and use of the Edit control in Editing Filters.
To see real-time statistics on the current replication, left-click on the XDCR Stats tab, at the left:
For information on how to read the interactive charts now displayed, see Manage Statistics.
Advanced Filtering with the UI
Advanced Filtering can be enabled by left-clicking on the Replication Filters control, in the Add Replication dialog. The UI expands to reveal the following field:
One or more expressions, to be used as filters, can be entered into the Filter Expression field. The expression is matched against documents' ids, field-names, values, and extended attributes, within the source bucket. Each document that provides a successful match is replicated. Documents that do not provide a match are not replicated.
Optionally, a document’s id can be entered into the interactive field adjacent to the Test Filter button. When the button is clicked, a match is attempted on the specified document. If the match is successful, a green match notification is displayed; otherwise, an orange no match is displayed.
An overview of XDCR filtering is provided in XDCR Advanced Filtering. For reference information on expressions used in advanced filtering, see the XDCR Advanced Filtering Reference. The practical steps required for establishing filters are explained in Filter a Replication.
Advanced Replication Settings with the UI
Left-click on the Advanced Replication Settings control, in the Add Replication dialog. The UI expands vertically, to reveal the following:
The values displayed in the fields are defaults, which can be modified interactively, and saved: this may help in achieving optimal replication-performance. For details on the significance of each field, see the XDCR Reference.
Create an XDCR Replication with the CLI
Staring from the scenario defined above, in Examples on This Page, use the CLI
xdcr-replicate command to create an XDCR replication, as follows:
couchbase-cli xdcr-replicate -c 10.142.180.101 \ -u Administrator \ -p password \ --create \ --xdcr-cluster-name 10.142.180.102 \ --xdcr-from-bucket travel-sample \ --xdcr-to-bucket travel-sample \ --xdcr-replication-mode xmem
If successful, this provides the following response:
SUCCESS: XDCR replication created
For more information, see the complete reference for the xdcr-replicate command. Note that this includes descriptions of all flags that support the Advanced Settings, described above.
Create an XDCR Replication with the REST API
Starting from the scenario defined above, in Examples on This Page, using the REST API’s
POST /controller/createReplication HTTP method and URI, create an XDCR reference as follows:
curl -v -X POST -u Administrator:password \ http://10.142.180.101:8091/controller/createReplication \ -d fromBucket=travel-sample \ -d toCluster=10.142.180.102 \ -d toBucket=travel-sample \ -d replicationType=continuous \ -d enableCompression=1
If successful, this provides the following response:
For more information, see Creating XDCR Replications. For information on REST-driven configuration of the Advanced Settings described above, see Managing Advanced XDCR Settings.
Once a replication has been defined and is therefore running, you can opt to pause it, in order to perform system maintenance. See Pause a Replication.