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" | "Snappy"]
  -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.

A compressionType value of None specifies that data compression is not used during replication. A value of Snappy specifies that the open-source Snappy library is used to provide data compression during replication: however, this is only supported for target clusters running Couchbase Server 5.5 and later. If Snappy is specified for a pre-5.5 cluster, an error is returned, and replication does not proceed. The default value, Auto, specifies that either None or Snappy is applied, depending on the version of the target cluster. If the target cluster is running version 5.5 or later, Auto is resolved to Snappy, and replication proceeds in compressed form. If the target cluster is running a pre-5.5 version, Auto is resolved to None, and replication proceeds in uncompressed form.

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. Note that data compression is enabled, by specifying the value 1 (specifying 0 disables compression).

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 \
-d compressionType="Snappy"

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.