A newer version of this documentation is available.

View Latest

Inter-Sync Gateway Replication Configuration

      +

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

      Related topics: Overview | Bootstrap | Database | Database Security | Access Control | Import | Inter-Sync Gateway Replication

      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}/_replication

      Create or update a replication in the database.

      If an existing replication is being updated, that replication must be stopped first.

      Required Sync Gateway RBAC roles:

      • Sync Gateway Replicator

      Parameters

      Path Parameters

      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String

      Body Parameter

      Name Description Schema

      Body
      optional

      If the replication_id matches an existing replication then the existing configuration will be updated. Only the specified fields in the request will be used to update the existing configuration. Unspecified fields will remain untouched.

      UserConfigurableReplicationProperties

      Responses

      HTTP Code Description Schema

      200

      Updated existing configuration successfully

      201

      Created new replication successfully

      400

      There was a problem with your request

      HTTP_Error

      404

      Resource could not be found

      HTTP_Error

      Example

      • Curl

      • HTTP

      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
        }'
      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: 200,
         collections_enabled: false,
         collections_local: [scope1.collection1,scope1.collection3,scope1.collection6],
         collections_remote: [scope1.collectionA,,scope1.collectionF],
         conflict_resolution_type: "default",
         continuous: false,
         custom_conflict_resolver: "none",
         direction: "string",
         enable_delta_sync: false,
         filter: "string",
         initial_state: "running",
         max_backoff_time: 5,
         purge_on_removal: false,
         query_params: [],
         remote: "string",
         remote_password: "string",
         remote_username: "string",
         replication_id: "string",
         run_as: "string"
      }
      

      adhoc

      Type

      boolean

      Description

      Set to true to run the replication as an adhoc replication instead of a persistent one.

      This means that the replication will only last the period of the replication until the status is changed to stopped and then it will be removed automatically. It will also be removed if Sync Gateway restarts or if removed due to user action.

      batch_size

      Type

      integer

      Description

      The amount of changes to be sent in one batch of replications. Changing this is an enterprise-edition only feature.

      collections_enabled

      Type

      boolean

      Description

      If true, the replicator will run with collections, and will replicate all collections, unless otherwise limited by keyspace_map.

      If false, the replicator will only replicate the default collection.

      collections_local

      Type

      array

      Description

      Limits the set of collections replicated to those listed in this array.

      The replication will use all collections defined on the database if this list is empty.

      collections_remote

      Type

      array

      Description

      Remaps the local collection name to the one specified in this array when replicating with the remote.

      If only a subset of collections need remapping, elements in this array can be specified as null to preserve the local collection name.

      The same index is used for both collections_remote and collections_local, and both arrays must be the same length.

      conflict_resolution_type

      Type

      string

      Description

      This defines what conflict resolution policy Sync Gateway should use to apply when resolving conflicting revisions.

      Changing this is an enterprise-edition only feature.

      Behaviour

      • default - In priority order, this will cause
        • Deletes to always win (the delete with the longest revision history wins if both revisions are deletes)
        • The revision with the longest revision history to win. This means the the revision with the most changes and therefore the highest revision ID will win.
      • localWins - This will result in local revisions always being the winner in any conflict.
      • remoteWins - This will result in remote revisions always being the winner in any conflict.
      • custom - This will result in conflicts going through your own custom conflict resolver. You must provide this logic as a Javascript function in the custom_conflict_resolver parameter. This is an enterprise-edition only feature.

      Note: replications created prior to Sync Gateway 2.8 will default to default.

      continuous

      Type

      boolean

      Description

      If true, changes will be immediately synced when they happen. This is known as a continuous replication.

      If false, all changes will be synced until they have been processed. The replication will then cease and not process any future changes (unless started again by the user). This is known as a one-shot replication.

      custom_conflict_resolver

      Type

      string

      Description

      This specifies the Javascript function to use to resolve conflicts between conflicting revisions.

      This must be used when conflict_resolution_type=custom. This property will be ignored when conflict_resolution_type is not custom.

      The Javascript function to provide this property should be in backticks (like the sync function). The function takes 1 parameter which is a struct that represents the conflict. This struct has 2 properties:

      • LocalDocument - The local document. This contains the document ID under the _id key.
      • RemoteDocument - The remote document The function should return the new documents body. This can be the winning revision (for example, return conflict.LocalDocument), a new body, or nil to resolve as a delete.

      Example:

      "custom_conflict_resolver":\`
      	function(conflict) {
      		console.log("Doc ID: "+conflict.LocalDocument._id);
      		console.log("Full remote doc: "+JSON.stringify(conflict.RemoteDocument));
      		return conflict.RemoteDocument;
      	}
      \`
      

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

      This is an enterprise-edition only feature.

      direction

      Type

      string

      Description

      This specifies which direction the replication will be replicating with the remote replicator.

      The directions are:

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

      Replications created prior to Sync Gateway 2.8 derive their direction from the source/target URL of the replication.

      enable_delta_sync

      Type

      boolean

      Description

      This will turn on delta- sync for the replication. This works in conjunction with the database level setting delta_sync.enabled

      If set to true, delta-sync will be used as long as both databases involved in the replication have delta-sync enabled. If a database does not have delta-sync enabled, then the replication will run without delta-sync.

      Replications created prior to Sync Gateway 2.8 must have delta-sync disabled.

      Enabling this is an enterprise-edition only feature.

      filter

      Type

      string

      Description

      This defines whether to filter documents by their channels or not.

      If set to sync_gateway/bychannel then a pull replication will be limited to a specific set of channels specified by the query_params.channels property.

      This only can be used with pull replications.

      initial_state

      Type

      string

      Description

      This is what state to start the replication in when creating a new replication.

      This allows you to control if the replication starts in a stopped start or running state.

      Replications prior to Sync Gateway 2.8 will run in the default state running.

      max_backoff_time

      Type

      integer

      Description

      Specifies the maximum time-period (in minutes) that Sync Gateway will attempt to reconnect to a lost or unreachable remote.

      When a disconnection happens, Sync Gateway will do an exponential backoff up to this specified value. When this value is met, it will attempt to reconnect indefinitely every max_backoff_time minutes.

      If this is set to 0, Sync Gateway will do the normal exponential backoff after the disconnect happens but then attempting 10 minutes and stop the replication.

      Note: this defaults to 5 minutes for replications created prior to Sync Gateway 2.8.

      purge_on_removal

      Type

      boolean

      Description

      Specifies whether to purge a document if the remote user loses access to all of the channels on the document when attempting to pull it from the remote.

      If false, documents will not be replicated and not be purged when the user loses access.

      query_params

      Type

      array

      Description

      This is a set of key/value pairs used in the query string of the replication.

      If filters=sync_gateway/bychannel then this can be used to set the channels to filter by in a pull replication. To do this, set the channels key to a string array of the channels to filter by. For example:

      "filter":"sync_gateway/bychannel",
      "query_params": {
        "channels":["chanUser1"]
      },
      

      remote

      Type

      string

      Description

      This is the endpoint of the database for the remote Sync Gateway that is the subject of this replication's push, pull, or pushAndPull action.

      Typically this would include the URI, port, and database name. For example, http://localhost:4985/db.

      How this remote is used depends on the direction of the replication:

      • pull - this replicator pulls changes from the remote
      • push - this replicator pushes changes to this remote
      • pushAndPull - this replicator pushes changes to this remote, while also pulling receiving changes

      remote_password

      Type

      string

      Description

      The password to use to authenticate with the remote.

      This password will be redacted in the replication config.

      This can only be used for a pull replication.

      remote_username

      Type

      string

      Description

      The username to use to authenticate with the remote.

      This can only be used for a pull replication.

      replication_id

      Type

      string

      Description

      This is the ID of the replication.

      When creating a new replication using a POST request, this will be set to a random UUID if not explicitly set.

      When the replication ID is specified in the URL, this must be set to the same replication ID if specifying it at all.

      run_as

      Type

      string

      Description

      This is used if you want to specify a user to run the replication as. This means that the replication will only be able to replicate what the user access to what the user has access to.