Creating XDCR Replications

To create an XDCR replication, use the POST /controller/createReplication HTTP method and URI.

HTTP method and URI

POST /controller/createReplication

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 specifying Auto as the value of compressionType 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.