Docs Menu
Docs Home
/
MongoDB Cluster-to-Cluster Sync
/
Reference

Finalize Cutover Process

On this page

  • Steps
  • Behavior
  • Learn More

You can finalize a migration and transfer your application workload from the source to the destination cluster using the mongosync cutover process.

mongosync should remain active until it reaches the COMMITTED state. This allows mongosync to sync any additional writes that occur during the migration.

Note

Before you switch your application workload to the destination cluster, you should always verify a successful sync. For more information, see Verify Data Transfer.

Steps

1

Verify the status of the mongosync process.

Call the progress endpoint to determine the status of mongosync before starting the cutover process. Ensure that the mongosync process status indicates the following values:

  • canCommit is true.

  • lagTimeSeconds is small (near 0).

    If lagTimeSeconds isn't close to 0 when the cutover starts, cutover might take a long time.

  • When using the Embedded Verifier check both the verification.source and the verification.destination return documents. The lagTimeSeconds fields in both documents should be near 0 and the phase fields should show "stream hashing".

    If /commit is called and the values are not near 0 or if the verifier is not in the stream hashing phase, the cutover process might take a long a time.

The following example returns the status of the synchronization process.

Request

curl localhost:27182/api/v1/progress -XGET

Response

{
   "progress":
      {
         "state":"RUNNING",
         "canCommit":true,
         "canWrite":false,
         "info":"change event application",
         "lagTimeSeconds":0,
         "collectionCopy":
            {
               "estimatedTotalBytes":694,
               "estimatedCopiedBytes":694
            },
         "directionMapping":
            {
               "Source":"cluster0: localhost:27017",
               "Destination":"cluster1: localhost:27018"
            },
         "verification":
            {
               "source":
                  {
                     "estimatedDocumentCount": 42,
                     "hashedDocumentCount": 42,
                     "lagTimeSeconds": 2,
                     "totalCollectionCount": 42,
                     "scannedCollectionCount": 10,
                     "phase": "stream hashing"
                  },
               "destination": {
                     "estimatedDocumentCount": 42,
                     "hashedDocumentCount": 42,
                     "lagTimeSeconds": 2,
                     "totalCollectionCount": 42,
                     "scannedCollectionCount": 10,
                     "phase": "stream hashing"
               }
            }
      },
   "success": true
}
2

Stop any write operations to the synced collections on the source.

  • If you started mongosync with enableUserWriteBlocking set to true, mongosync blocks all write operations on the entire source cluster during the commit (step 4) for you.

  • If you didn't start mongosync with enableUserWriteBlocking, ensure that writes are disabled. For example, run the setUserWriteBlockMode command on the source cluster:

    db.adminCommand( {
       setUserWriteBlockMode: 1,
       global: true
    } )

  • If mongosync uses filtered sync, it's not necessary to disable writes to the entire source cluster. But you must ensure that write operations are stopped for the collections included by the filter.

3

Send a commit request to mongosync.

If you started multiple mongosync instances for your migration, you must issue a commit request for each mongosync instance.

Request

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

Response

{"success":true}

Note

After you submit a commit request, call the progress endpoint to ensure that the mongosync state is COMMITTING or COMMITTED.

4

Wait until you can perform writes on the destination cluster.

Call the progress endpoint to determine if canWrite is true. If canWrite is false, wait until progress shows canWrite is true.

curl -sS localhost:27182/api/v1/progress -XGET | jq ".progress.canWrite"
true
5

Verify data transfer.

Verify the successful sync of data from the source to the destination cluster.

For more information, see Verify Data Transfer.

6

Enable application writes on the destination cluster.

To enable writes, update setUserWriteBlockMode:

db.adminCommand(
   {
      setUserWriteBlockMode: 1,
      global: false
   }
)

Then, transfer your application workload to the destination cluster.

7

Call the progress endpoint to determine the status of the mongosync process.

When the mongosync progress response indicates that the mongosync state is COMMITTED, the cutover process is complete.

curl -sS localhost:27182/api/v1/progress -XGET | jq ".progress.state"
"COMMITTED"

Behavior

canWrite and COMMITTED

mongosync permits writes on the destination cluster at an earlier stage than the COMMITTED state.

In the initial sync, mongosync replicates unique indexes on the source cluster as non-unique indexes on the destination cluster. During commit, the relevant non-unique indexes on the destination cluster are set to prepareUnique. When this is done, the /progress endpoint begins to return canWrite: true. Collections with prepareUnique indexes reject new documents that violate the unique index constraint. mongosync then converts the prepareUnique indexes into unique indexes. When this is done, mongosync changes its state to COMMITTED.

Note

The conversion of prepareUnique indexes to unique indexes can be resource intensive when syncing large collections. This can result in a long time between the /progress endpoint returning canWrite: true and mongosync reaching the COMMITTED state.

Learn More

Back

oplog Sizing

Next

Limitations