Join us Sept 17 at .local NYC! Use code WEB50 to save 50% on tickets. Learn more >
MongoDB Event
Docs Menu
Docs Home
/
MongoDB Mongosync
/
Reference
/
mongosync API Endpoints

reverse

Description

Reverses the direction of a committed sync operation.

For example:

  • You have a COMMITTED sync operation.

  • cluster0 is the source and cluster1 is the destination.

  • After the sync operation is COMMITTED, new writes occur only on the destination cluster. The source cluster will not accept new writes.

In this scenario, you can use the reverse endpoint to sync writes from cluster1 to cluster0, including any writes that occurred on cluster1 after mongosync reached canWrite=true. To check the canWrite status during sync, use the /progress endpoint.

For more information and a tutorial on using the reverse endpoint, see Reverse Sync Direction.

Requirements

To use the reverse endpoint:

  • mongosync must be configured when the initial sync begins. The call to the /start API endpoint must set:

    • reversible to true

    • enableUserWriteBlocking to "sourceAndDestination".

Note

Dual write-blocking is a prerequisite for running reverse.

You cannot update these options after the sync starts.

  • mongosync must be in the COMMITTED state.

  • The destination cluster oplog must not roll over between mongosync reaching canWrite=true and receiving the /reverse request.

Warning

Unique indexes on the source cluster must not use the legacy format.

To validate that collection indexes on the source cluster use the proper formatting, see Validate Unique Indexes.

  • The source and destination clusters must have the same number of shards. You cannot reverse sync when the clusters have different topologies or major versions.

  • The user specified in the mongosync connection string must have the required permissions on the source and destination clusters. The permissions vary depending on your environment and if you want to modify write-blocking settings or use reverse sync.

Note

When you configure multiple mongosync instances to sync between sharded clusters, you must send identical API endpoint commands to each mongosync instance.

For more information, see Reverse Multiple Mongosyncs.

Validate Unique Indexes

In order to reverse direction, mongosync requires that all unique indexes on the source cluster (except for _id) do not have legacy unique index keys.

Before you Begin

You can ensure that non-_id unique indexes use the correct formatting on the source cluster with the $collStats aggregation stage. To run this aggregation pipeline on your collection, copy and paste the example code, replacing <collection> with the collection name and <field_name> with the name of the indexed field. You must run this on all nodes, for all collections that have unique indexes. Note that only the non-_id unique indexes need to have formatVersion 13 or 14.

 db.<collection>.aggregate( [
   { $collStats: { storageStats: { } } },
   { $project: { "storageStats.indexDetails.<field_name>.metadata.formatVersion": 1 } }
 ] )
[
  {
    storageStats: {
      indexDetails: { <field_name>: { metadata: { formatVersion: 14 } } }
    }
  }
]

Unique indexes with formatVersion 13 or 14 are guaranteed to not have legacy keys.

If you have unique indexes of a different formatVersion, you can also use the db.collection.validate() method with full = false to confirm if there are legacy index keys. You must run this on all nodes for all collections with unique indexes. validate() returns a warning if legacy format index keys are detected.

Steps

To update the format version of the indexes for compatibility with mongosync, you must resync all nodes in the original source cluster. To resync all nodes:

1
Resync all secondaries, one by one.

For a tutorial on resyncing nodes, see Resync a Member of a Replica Set.

2
Step down the primary node and step up one of the secondary nodes.
3
Resync the old primary node from the new primary node.

Request

POST /api/v1/reverse

Request Body Parameters

This endpoint does not use HTTP request body parameters. However, you must specify the --data option with an empty object { }.

Response

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.

Example

The following example reverses the direction of a committed sync operation.

Request

curl localhost:27182/api/v1/reverse -XPOST --data '{ }'

Response

{"success":true}

Behavior

The reverse endpoint starts the REVERSING state. mongosync swaps the source and destination clusters and resumes applying change events.

If the reverse sync is successful, mongosync enters the RUNNING state. The synchronization continues in the reverse direction from the original sync job. You do not need to restart the entire sync process to copy the original data.

To view the mapping direction for the synchronization of the source and destination clusters, use the progress endpoint and check the directionMapping object.

Embedded Verifier

The embedded verifier is enabled by default for replica set migrations.

Endpoint Protection

mongosync does not protect the reverse endpoint. However, by default the API binds to localhost only and does not accept calls from other sources. Additionally, the reverse call does not expose connection credentials or user data.

Limitations

The reverse endpoint does not support:

Back

commit

Next

mongosync States

On this page