> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# `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](https://www.mongodb.com/docs/mongosync/current/reference/api/progress.md#std-label-c2c-api-progress) endpoint.

To complete a reverse sync, call the [/commit](https://www.mongodb.com/docs/mongosync/current/reference/api/commit.md#std-label-c2c-api-commit) endpoint to complete the reverse sync process.

**Warning:**

Do not use the original source cluster until you commit the reverse sync. If you call the `reverse` endpoint without [/commit](https://www.mongodb.com/docs/mongosync/current/reference/api/commit.md#std-label-c2c-api-commit), the original source cluster remains in an unusable, intermediate state.

For more information and a tutorial on using the `reverse` endpoint, see [Reverse Sync Direction.](https://www.mongodb.com/docs/mongosync/current/reverse-sync.md#std-label-c2c-reverse-process)

## Requirements

To use the `reverse` endpoint:

- `mongosync` must be configured when the initial sync begins. The call to the [/start](https://www.mongodb.com/docs/mongosync/current/reference/api/start.md#std-label-c2c-api-start) API endpoint must set the `reversible` option to `true`.

You cannot update this option 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](https://www.mongodb.com/docs/manual/core/index-unique.md#std-label-index-type-unique) 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.](https://www.mongodb.com/docs/mongosync/current/reference/api/reverse.md#std-label-c2c-validate-unique-index)

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

- The source and destination clusters must run the same MongoDB major version.

* 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 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.](https://www.mongodb.com/docs/mongosync/current/topologies/multiple-mongosyncs.md#std-label-c2c-sharded-reverse)

### Validate Unique Indexes

In order to reverse direction, `mongosync` requires that all [unique](https://www.mongodb.com/docs/manual/core/index-unique.md#std-label-index-type-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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats.md#mongodb-pipeline-pipe.-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`.

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

**Output:**

```javascript
[
  {
    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()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.validate.md#mongodb-method-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](https://www.mongodb.com/docs/manual/tutorial/resync-replica-set-member.md#std-label-resync-replica-member) 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.](https://www.mongodb.com/docs/manual/tutorial/resync-replica-set-member.md#std-label-resync-replica-member)

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

```http
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

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

```

### Response

```json
{"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.

After you call the `reverse` endpoint, commit the sync to finalize the reverse data migration. Committing a reverse sync works the same way as committing the initial sync.

1. Confirm that the reverse sync is ready to commit.

   Call the [/progress](https://www.mongodb.com/docs/mongosync/current/reference/api/progress.md#std-label-c2c-api-progress) endpoint and confirm the following values:

   - `lag.overallLagSeconds` is close to `0`.

   - The state is `RUNNING`.

   - `canCommit` is `true`.

2. Call the `/commit` endpoint.

   Send a request to the [/commit](https://www.mongodb.com/docs/mongosync/current/reference/api/commit.md#std-label-c2c-api-commit) endpoint. After the request succeeds, `mongosync` enters the `COMMITTED` state. For the full procedure, see [Finalize Cutover Process.](https://www.mongodb.com/docs/mongosync/current/reference/cutover-process.md#std-label-c2c-cutover-process)

To view the mapping direction for the synchronization of the source and destination clusters, use the [progress](https://www.mongodb.com/docs/mongosync/current/reference/api/progress.md#std-label-c2c-api-progress) endpoint and check the `directionMapping` object.

**Note:**

`mongosync` does not retain hot documents specified with the [`--hotDocIDs`](https://www.mongodb.com/docs/mongosync/current/reference/mongosync-binary.md#std-option-mongosync.--hotDocIDs) option or [`hotDocIDs`](https://www.mongodb.com/docs/mongosync/current/reference/configuration.md#mongodb-setting-hotDocIDs) setting on a `reverse` sync. If replication lag occurs due to hot documents during a `reverse` sync, restart the `mongosync` process and specify the hot document identifiers for the reverse direction. Specified hot document identifiers take effect only after you stop and restart `mongosync`. Do not restart the migration from scratch.

### 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:

- [filtered sync.](https://www.mongodb.com/docs/mongosync/current/reference/collection-level-filtering.md#std-label-c2c-filtered-sync)

- migrations from [pre-6.0 source clusters.](https://www.mongodb.com/docs/mongosync/current/release-notes/1.10.md#std-label-c2c-older-version-support)