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


      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


      Type Name Description Schema



      Database name




      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.




      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.



      HTTP Code Description Schema


      Replication successfully updated



      Replication successfully inserted



      • 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",
        "query_params": {
        "continuous": false
      PUT /db1-local/_replication/db1-rep-id1 HTTP/1.1
      Host: localhost:4985
      Content-Type: application/json
      Content-Length: 235
      {"direction": "push",
        "remote": "http://user1:password1@example.com:4984/db1-remote",
        "query_params": {
        "continuous": false


      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.