Docs Menu
Docs Home
/
MongoDB Mongosync
/
Reference
Docs Home
/
MongoDB Mongosync
/
Reference
Docs Home
/
MongoDB Mongosync
/
Reference

Finalize Cutover Process

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 mongosync.

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.

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"
            }
      },
   "success": true
}
2

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

  • Wait for all transactions on the source cluster to either commit or abort.

  • If you start 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 you disable writes. 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. However, you must ensure that you stop write operations for the collections that the filter includes.

3

Send a commit request to mongosync.

If you start 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.

Once you complete this step, mongosync blocks writes on the source cluster.

If your source cluster contains Persistant Query Settings (PQS), you must manually migrate PQS to your destination cluster.

If you previously set enableUserWriteBlocking to true, mongosync blocks writes on the source cluster once you complete this step.

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

If you manually blocked writes on the destination cluster by using setUserWriteBlockMode, 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.

If you started mongosync with write-blocking by using the enableUserWriteBlocking option on the /start endpoint, you do not need to complete this step.

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

Migrate Persistent Query Settings

On this page