Docs Menu

Docs HomeMongoDB Cluster-to-Cluster Sync

start

On this page

  • Description
  • Requirements
  • State
  • User Write Blocking
  • Request
  • Request Body Parameters
  • Response
  • Example 1 - Start a Standard Sync Job
  • Request
  • Response
  • Example 2 - Start a Reversible Sync Job
  • Request
  • Response
  • Behavior

Starts the synchronization between a source and destination cluster.

To use the start endpoint, mongosync must be in the IDLE state.

To set enableUserWriteBlocking, the mongosync user must have a role that includes the setUserWriteBlockMode and bypassWriteBlockingMode ActionTypes.

Note

When using enableUserWriteBlocking, writes are only blocked for users that do not have the bypassWriteBlockingMode ActionType. Users who have this ActionType are able to perform writes.

To set a custom role for the mongosync user:

  1. To create a custom role, use the createRole command:

    db.adminCommand( {
    createRole: "reverseSync",
    privileges: [ {
    resource: { db: "", collection: "" },
    actions: [ "setUserWriteBlockMode", "bypassWriteBlockingMode" ]
    } ],
    roles: []
    } )
  2. To grant the custom role to the mongosync user, use the grantRolesToUser command:

    db.adminCommand( {
    grantRolesToUser: "mongosync-user",
    roles: [ { role: "reverseSync", db: "admin" } ]
    } )

Ensure that you use this configured mongosync user in the connection strings for the cluster0 or cluster1 settings when you start mongosync.

POST /api/v1/start
Parameter
Type
Necessity
Description
source
string
Required
Name of the source cluster.
destination
string
Required
Name of the destination cluster.
reversible
boolean
Optional

If set to true, enables the synchronization operation to be reversed. For more information, see the reverse endpoint.

Default value is false.

enableUserWriteBlocking
boolean
Optional

If set to true, blocks writes on the destination cluster while the synchronization is in progress. After the synchronization is committed to the destination cluster, the original source cluster blocks writes and the destination cluster accepts writes.

Default value is false.

Field
Type
Description
success
boolean
When the request is successful, this value is true.
error
string
If an error occurred, indicates the name of the error. This field is omitted from the response when success is true.
errorDescription
string
Detailed description of the error that occurred. This field is omitted from the response when success is true.

The following example starts a synchronization job where cluster0 is the source and cluster1 is the destination.

curl localhost:27182/api/v1/start -XPOST \
--data '
{
"source": "cluster0",
"destination": "cluster1"
} '
{"success":true}

The following example starts a synchronization job where cluster0 is the source and cluster1 is the destination. The reversible and enableUserWriteBlocking fields allow the sync to be reversed.

curl localhost:27182/api/v1/start -XPOST \
--data '
{
"source": "cluster0",
"destination": "cluster1",
"reversible": true,
"enableUserWriteBlocking": true
} '
{"success":true}

If the start request is successful, mongosync enters the RUNNING state.

←  mongosync API Endpointsprogress →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.