Creating XDCR Replications
- reference
To create an XDCR replication, use the POST /controller/createReplication
HTTP method and URI.
Description
Data replication occurs from a source cluster to a destination cluster. Once a replication is created, data replication between clusters automatically begins.
Curl Syntax
curl -v -X POST -u [admin]:[password] http://[localhost]:[port]/controller/createReplication -d fromBucket=[bucket-name] -d toCluster=[cluster-name] -d toBucket=[bucket-name] -d replicationType="continuous" -d type=["capi" | "xmem"] -d compressionType=["None" | "Auto" ] -d desiredLatency=[Integer] -d filterExpression=[Expression] -d filterDeletion=[true | false] -d filterExpiration=[true | false] -d filterBypassExpiry=[true | false] -d filterSkipRestream=[true | false] -d priority=["Low" | "Medium" | "High"] -d optimisticReplicationThreshold=[Integer] -d failureRestartInterval=[Integer] -d docBatchSizeKb=[Integer] -d workerBatchSize=[Integer] -d checkpointInterval=[Integer] -d sourceNozzlePerNode=[Integer] -d targetNozzlePerNode=[Integer] -d statsInterval=[Integer] -d logLevel=[String] -d networkUsageLimit=[Integer] -d network_type=["default" | "external"]
The type
values, capi
and xmem
, are respectively represented by Version 1 and Version 2, in the web console.
The default value is xmem
.
If the default is to be used, this parameter does not need to be specified.
The replicationType
value is always continuous
.
This value must be specified.
The value of compressionType
value can be either Auto
or None
:
-
If
Auto
is specified, data compression is provided during replication, provided that the target cluster is running Couchbase Server 5.5 or later. If the target cluster is not running Couchbase Server 5.5 or later, data compression is not provided during replication. (Note that the consequences of specifyingAuto
as the value ofcompressionType
are thereby determined irrespective of whether the data resides in the source bucket in compressed or uncompressed form.) -
If
None
is specified, data compression is not provided during replication if the target cluster is not running Couchbase Server 5.5 or later. If the target cluster is running Couchbase Server 5.5 or later:-
If the data resides in the source bucket in uncompressed form, data compression is not provided.
-
If the data resides in the source bucket in compressed form, data compression is provided.
-
The optional filterExpression
is matched against the ids, field-names, values, and extended attributes of documents in the source bucket.
Each document that produces a successful match is replicated; other documents are not replicated.
For supported expressions, see XDCR Advanced Filtering Reference.
The filterDeletion
and filterExpiration
flags indicate whether mutations corresponding respectively to the deletion and expiration of documents on the source cluster should be either filtered out of the replication to the target cluster, or allowed to remain in.
For each flag, a value of true
means that the mutation is filtered out, ensuring that it is not replicated to the target cluster; while a value of false
(the default) means that the mutation is not filtered out, ensuring that it is replicated to the target cluster.
The default value for both flags is false
.
The filterBypassExpiry
flag indicates whether a document’s TTL should be replicated with the document or not.
A value of true
means that the TTL is removed from the document.
The default value is false
.
The filterSkipRestream
flag indicates whether the replication should be either restarted or allowed to continue without restarting, following modification of the value of filterExpression
.
A value of true
means that the replication should be allowed to continue without restarting.
A value of false
(the default) means that the replication should be restarted.
For more information, see Filter-Expression Editing.
The priority
flag controls resource-allocation to the replication.
The value can be High
, Medium
, or Low
.
The default value is High
.
For information, see XDCR Priority.
The optional network_type
flag determines whether internal or alternate IP addresses are used when communicating with the target cluster.
A value of default
enforces the use of internal IP addresses.
A value of external
enforces the use of alternate IP addresses, whenever possible.
For information, see Alternate Addresses.
For information on all other flags, see Managing Advanced XDCR Settings.
Responses
If successful, the command returns 200 OK
, and an object containing an id
for the new replication: this can be used, when appropriate, to delete the replication.
Failure to authenticate returns 401 Unauthorized
.
A URI featuring an incorrect hostname or port returns a failure to connect
message.
Referencing an unknown source bucket returns 400 Bad Request
, and an object referencing the unknown bucket-name.
For example:
{ "errors": { "fromBucket": "Error validating source bucket 'source'. err=BucketValidationInfo Operation failed after max retries. Last error: Bucket doesn't exist" } }
Referencing an unknown cluster returns 400 Bad Request
, and an object referencing the unknown cluster-name:
{ "errors": { "toCluster": "cannot find remote cluster\n err = unknown remote cluster : refName - 10.143.191.102" } }
Referencing an unknown target bucket returns 400 Bad Request
, and an object referencing the unknown bucket-name:
{ "errors": { "toBucket": "Error validating target bucket 'remote'. err=BucketValidationInfo Operation failed after max retries. Last error: Bucket doesn't exist" } }
Example
The following example creates a replication between the source
and remote
buckets.
The remote
bucket is located on a cluster named 10.142.171.101
.
curl -v -X POST -u Administrator:password \ http://127.0.0.1:8091/controller/createReplication \ -d fromBucket=source \ -d toCluster=10.142.171.101 \ -d toBucket=remote \ -d replicationType=continuous
If the call is successful, data replication immediately begins, and a response similar to the following is returned.
{ "id": "9eee38236f3bf28406920213d93981a3/beer-sample/remote_beer" }
The id
returned in the document can be used to delete the replication, when appropriate.
See Also
The REST procedures for establishing and retrieving advanced settings are described in Managing Advanced XDCR Settings. See Create a Replication for additional examples of creating a replication, including by means of Couchbase Web Console and the CLI. For a conceptual overview of XDCR, see the XDCR Overview. Information on how alternate addresses may be used is provided in Alternate Addresses.