A newer version of this documentation is available.

Inter-Sync Gateway Replication Configuration

March 23, 2025

+ 12

Using Sync Gateway’s Admin REST API to configure and manage inter-Sync Gateway replications

Pre-3.0 Legacy Configuration Equivalents

This content describes configuration for Sync Gateway 3.0 and higher — for legacy configuration, see: Legacy Pre-3.0 Configuration

Introduction

In 3.0 we use the Admin REST API to provision persistent configuration changes. This content introduces the Add or Update a Replication endpoint for convenience — see Replication for a full description of the endpoints available.

Using CA Certificates

Required CA certificates must be added to the system certificate pool.

On Linux, this is done using one of the following methods:

Adding the location of the certificate to SSL_CERT_FILE environment variable,
Placing the certificate in a location pointed to by the SSL_CERT_DIR environment variable.
Using one of the system-dependent locations listed in this file.

For Windows-based systems, add CA certificate files to the system root certificate store.

Add or Update a Replication

PUT {db}/_config/_replication

The replication endpoint is used to manage both _ad hoc and persistent replication operations.

Using a PUT request you can update (or insert, if it doesn’t exist) a set of replication details.

To cancel a replication You can cancel continuous replications by adding the cancel field to the JSON request object and setting the value to true.

Note that the structure of the request must be identical to the original for the cancellation request to be honoured.

For example, if you requested continuous replication, the cancellation request must also contain the continuous field.

Sync Gateway Roles Required (CBS 7.0.2 Developer Preview):

Sync Gateway Replicator

Parameters

Type Name Description Schema

Type	Name	Description	Schema
Path	db required	Database name	string
Path	replicationID required	If supplied, the <i>replicationID</i> parameter must be a valid replication id. If it is not supplied for a <i>new</i> replication*, then a random UUID is generated.	string
Body	ReplicationBody optional	This replication request message body is a JSON document that comprises all the properties required to upsert a replication. If the `replicationID` matches an existing `replication_id` then the values of any properties provided in the body are used to update the existing replication’s property values.	Replication_model

Path

db
required

Database name

string

Path

replicationID
required

If supplied, the <i>replicationID</i> parameter must be a valid replication id.

If it is not supplied for a <i>new</i> replication*, then a random UUID is generated.

string

Body

ReplicationBody
optional

This replication request message body is a JSON document that comprises all the properties required to upsert a replication.

If the replicationID matches an existing replication_id then the values of any properties provided in the body are used to update the existing replication’s property values.

Replication_model

Responses

HTTP Code	Description	Schema
200	Replication successfully updated	ReplicationResponse
201	Replication successfully inserted	ReplicationResponse

HTTP Code

Description

Schema

200

Replication successfully updated

ReplicationResponse

201

Replication successfully inserted

ReplicationResponse

Example

Curl
HTTP

bash
Copy
curl --location --request PUT 'http://localhost:4985/db1-local/_replication/db1-rep-id1 '\
--header 'Content-Type: application/json' \
--data-raw '{
  "direction": "push",
  "purge_on_removal": false,
  "remote": "http://user1:password1@example.com:4984/db1-remote",
  "filter":"sync_gateway/bychannel",
  "query_params": {
    "channels":["channel.user1"]
  },
  "continuous": false
  }'

http
Copy
PUT /db1-local/_replication/db1-rep-id1 HTTP/1.1
Host: localhost:4985
Content-Type: application/json
Content-Length: 235

{"direction": "push",
  "purge_on_removal":false,
  "remote": "http://user1:password1@example.com:4984/db1-remote",
  "filter":"sync_gateway/bychannel",
  "query_params": {
    "channels":["channel.user1"]
  },
  "continuous": false
}

Schema

This section shows Sync Gateway’s replication configuration settings in schema format for convenience in constructing JSON models for use in the Admin REST API.

The configuration settings described here are provisioned through the Replication endpoints.

 {
  adhoc: false,
  batch_size: 0,
  cancel: false,
  conflict_resolution_type: "string",
  continuous: false,
  custom_conflict_resolver: "string",
  direction: "string",
  enable_delta_sync: false,
  filter: "string",
  max_backoff_time: 0,
  password: "string",
  purge_on_removal: false,
  query_params: [
    "string"
  ],
  remote: "string",
  replication_id: "string",
  initial_state: "string",
  username: "string"
}

`adhoc`

boolean

" About

Use the Admin REST API's adhoc parameter to specify that a replication is ad hoc rather than persistent.

Behavior

Ad hoc replications behave the same as normal replications, but they are automatically removed when their status changes to stopped. This will usually be on completion, but may also be as a result of user action.

Constraints

This parameter is NOT available to configured replications; only those initialized using the Admin REST API."

`batch_size`

integer

(Default: 200)

About

Use the optional batch_size property to specify the number of changes to be included in a single batch during replication.

`cancel`

boolean

About

Use this parameter on,y when you want to want to cancel an existing active replication.

Constraints

This parameter is NOT available in configured replications; only those initialized using the Admin REST API.
NOTE that the body of the request must be the same as the replication's replication definition for the cancellation request to be honoured. For example, if you requested continuous replication, the cancellation request must also contain the continuous field.

`conflict_resolution_type`

string

(Default: default)

About

The conflict_resolution_type property defines the conflict resolution policy that Sync Gateway applies when resolving conflicting revisions.

The default behavior is that automatic conflict resolution policy is applied.

Valid options

default
localWins
remoteWins
custom

Behavior

default - Selecting default applies the following conflict resolution policy
- Deletes always win (the delete with longest revision history wins if both revisions are deletes)
- The revision with the longest revision history wins (so, the one with most changes and consequently the highest revision Id).
localWins - Selecting localWins will result in local revisions always being the winner in any conflict.
remoteWins - Selecting remoteWins will result in remote revisions always being the winner in any conflict.

custom - Selecting custom specifies that you want to handle conflict resolution with your own application logic. You must provide this logic as a Javascript function by specifying it in using the custom-conflict-resolver parameter.

Example

"conflict_resolution_type":"remoteWins"

Constraints

Replications created prior to version 2.8 will default to default.

`continuous`

boolean

About

The continuous property specifies whether this replication will run in continuous mode.

Behavior

continuous=true-- In continuous mode, changes are immediately synced in accordance with the replication definition.
continuous=false-- Detected changes are synced in accordance with the replication definition. The replication ceases once all revisions are processed.

Constraints

Optional for stops and removes

`custom_conflict_resolver`

string

(Default: none)

About

The optional custom_conflict_resolver property specifies the Javascript function that will be used to resolve conflicts, if the custom conflict resolution type is specified in the conflict_resolution_type.

Options

The property is mandatory when conflict_resolution_type=custom and will be ignored in all other cases.

Using

Provide the required logic in a Javascript function, as a string within backticks (see also the description for the sync function`.

The function takes one parameter struct representing the conflict and comprising

the document id
the local document
the remote document

The function returns a document struct representing the winning revision.

Example

"custom_conflict_resolver":`
  function(conflict) {
    console.log("full remoteDoc doc: "+JSON.stringify(conflict.RemoteDocument));
  return conflict.RemoteDocument;
}`

Constraints

Using complex custom_conflict_resolver functions can noticeably degrade performance. Use a built-in resolver whenever possible.

`direction`

string

About

The mandatory direction property specifies whether the replication is push, pull or pushAndPull relative to this node.

The property value is referenced by the remote property.

Behavior

pull - changes are pulled from the remote database
push - changes are pushed to the remote database
pushAndPull - changes are both pushed-to and pulled-from the remote database

Constraints

Replications created prior to version 2.8 derive their direction from the source/target url of the replication.

`enable_delta_sync`

boolean

About

The optional enable_delta_sync parameter turns on delta sync for a replication. It works in conjunction with the database level setting delta_sync.enabled.

Options

"enable_delta_sync": true, the replication can use delta sync (depending on delta_sync.enabled setting)
"enable_delta_sync": false, the replication cannot use delta sync

Behavior

The optional enable_delta_sync parameter works in conjunction with the database level delta_sync.enabled setting, to determine whether this replication uses delta sync.

If "delta_sync.enabled": true for both databases involved in the replication, then this parameter enables or disables its use for this specific replication.
In all other cases it has no effect and the replication runs without delta-sync.

Constraints

Applies ONLY to Enterprise Edition deployments.
Depends upon the setting of the database level parameter delta_sync.enabled
Replications created prior to version 2.8 must run with "enable_delta_sync": false
Push replications will not use Delta Sync when pushing to a pre-2.8 target

`filter`

string

About

Use the optional filterproperty to defines the function to be used to filter documents.

Options

A common value used when replicating from Sync Gateway is sync_gateway/bychannel. This option limits the pull replication to a specific set of channels. You can specify the required channels using query_params.

Behavior

Works in conjunction with query_params to control the documents processed by the replication.

Example

"filter":"sync_gateway/bychannel"

Constraints

OPTIONAL for stops and removes (even if defined during creation)

`max_backoff_time`

integer

(Default: 5)

The max_backoff_timeproperty specifies the time-period (in minutes) during which Sync Gateway will attempt to reconnect lost or unreachable remote targets.

On disconnection, Sync Gateway will do an exponential backoff up to the specified value, after which it will attempt to reconnect indefinitely every max_backoff_time minutes.

If a zero value is specified, then Sync Gateway will do an exponential backoff up to an interval of five minutes before stopping the replication.

NOTE - this value defaults to five minutes for replications created prior to version 2.8.

`password`

string

(Default: mandatory)

About

Use password to provide the login password value for the accredited user running this replication.

Behavior

These details are used to authenticate credentials and approve access to data.

Once provided and recorded, the password data is redacted and will not be displayed in either the configuration file or Admin REST API. A string of **** will be displayed in its place.

`purge_on_removal`

boolean

About

The optional purge_on_removal property specifies, per replication, whether the removal of a channel triggers a purge.

Options

true or false
Default = false - Document removals are ignored by receiving end

Behavior

If purge_on_removal=false, then the removal of channels is ignored (not purged) by the receiving end.

Constraints

Applies only to PULL replications, including the PULL portion of a PUSHANDPULL replication.
Replications created prior to version 2.8 must be run with purge_on_removal=false.

`query_params`

array

About

The query_params property defines a set of key/value pairs used in the query string of the replication.

Behavior

This property works in conjunction with filters and channels to provide routing.

Using

You can use query_params' channels function to pull from a specific set of channels. To do so, you would also need to set the filter to sync_gateway/bychannels.

Example

  "filter":"sync_gateway/bychannel",
  "query_params": {
    "channels":["channel.user1"]
  },

Constraints

OPTIONAL for stops and removes (even if defined during creation)

`remote`

string

About

The remote property represents the endpoint of a database for the remote Sync Gateway. That is, it identifies the remote Sync Gateway database that is the subject of this replication's push, pull or pushAndPull action.

Typically the endpoint will include URI, Port and Database name elements.

You can also include user credentials in the URL, in the form <username>:<password>. The credentials relate to an existing Sync Gateway user on the remote server.

Example "remote": "http://user:password@example.com:4985/db1-remote"

Format

a string containing a valid URL for a (remote) Sync Gateway database.
an object whose url property contains the Sync Gateway database URL.

Behavior

Dependent upon setting of direction.

If direction is :

pull, 'remote' defines the remote cluster from which data is pulled
push, 'remote' defines the remote cluster to which data is pushed
pushAndPull, 'remote' defines the push configuration.

Example

"remote": "http://www.example.com:4984/sample-database",

`replication_id`

string

About

The replication_id property specifies either:

For NEW replications, the ID to be assigned to the the replication. If no replication_id is specified, Sync Gateway will assign a random UUID to new replications.
For existing replications, this is the ID of the required replication.
If cancel=true, this is the id of the active replication task to be cancelled.

Constraints

If this is specified in the body of a POST or PUT request then it must be the same value as specified in the request URL.

`initial_state`

string

(Default: Running)

About

The optional initial_state property is used to specify that the replication must be launched in 'Stopped' mode

Behavior

All replications are configured to start on Sync Gateway launch. So, if omitted, the state defaults to 'Running'.

*Constraints

Replications created prior to version 2.8 will all default to a state of 'Running'.

`username`

string

(Default: Mandatory)

About

Use username to provide the name of the accredited user running this replication.

Behavior

These details are used to authenticate credentials and approve access to data

Once provided and recorded, the username data is redacted and will not be displayed in either the configuration file or Admin REST API. A string of **** will be displayed in its place.

API Topics

Reference

Community

Mobile Forum | Blog | Blog (Mobile) | Tutorials

Inter-Sync Gateway Replication Configuration

Introduction

Add or Update a Replication

Parameters

Responses

Example

Schema

Related Content