Docs Menu
Docs Home
/
MongoDB Cluster-to-Cluster Sync
/
Reference
/
mongosync API Endpoints

commit

On this page

  • Description
  • Requirements
  • Request
  • Request Body Parameters
  • Response
  • Example
  • Confirm that the Synchronization is Ready
  • Send the Commit Request
  • Behavior
  • State
  • Data Verification
  • Collection Characteristic Changes
  • Endpoint Protection

Description

Finalizes the sync between the source cluster and the destination cluster and stops continuous sync between clusters.

For more information, see Finalize Cutover Process.

Requirements

Before using the commit endpoint:

  • Stop your application to prevent any further writes to the source cluster. During commit, you may still read from the source cluster.

    Warning

    If you write to the source cluster during commit, you might experience data loss.

  • Use the progress endpoint to confirm the following values:

    • lagTimeSeconds for mongosync, the source cluster for the verifier, and the destination cluster for the verifier are all near 0 (Recommended, but not required)

      Note

      lagTimeSeconds

      lagTimeSeconds indicates the time between the last applied event and time of the current latest event. When you send a commit request, mongosync enters the COMMITTING state for the amount of seconds reported by lagTimeSeconds, and then transitions to the COMMITTED state.

      When lagTimeSeconds is 0, the source and destination clusters are in a consistent state.

      For more information on the lagTimeSeconds fields, see progress.

    • state: "RUNNING"

    • canCommit: true

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 Commit Synchronization From Multiple mongosync Instances.

Request

POST /api/v1/commit

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 commits the synchronization operation to the destination cluster.

Confirm that the Synchronization is Ready

Before sending a request to the commit endpoint, use the progress endpoint to confirm that the synchronization is ready to be committed.

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
}

The progress endpoint returned "canCommit":true, which means that the commit request can run successfully.

Send the Commit Request

The following command sends a request to the commit endpoint:

Request

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

Response

{"success":true}

Behavior

State

If the commit request is successful, mongosync enters the COMMITTED state. Once mongosync enters the COMMITTED state, continuous sync between the clusters stops.

Data Verification

Before transferring your application load from the source cluster to the destination, check your data to ensure that the sync was successful.

Note

If mongosync stops during commit, before the /progress endpoint reports canWrite: true, you must restart the entire migration to ensure that it's verified.

For more information, see Verify Data Transfer.

Collection Characteristic Changes

commit restores collection characteristics that mongosync temporarily alters during synchronization.

The following table illustrates the impact of commit on collection characteristics that mongosync alters during the synchronization process.

Collection Characteristic
Impact of commit

Unique Indexes

commit resets unique indexes that mongosync replicated as non-unique on the destination cluster.

TTL Indexes

commit resets expireAfterSeconds which mongosync set to the value of MAX_INT on the destination cluster.

Hidden Indexes

commit resets hidden indexes that mongosync replicated as non-hidden on the destination cluster.

Write Blocking

If you enable dual write-blocking, mongosync blocks writes:

  • On the destination cluster during sync.

  • On the source cluster when commit is received.

mongosync enables destination-only write-blocking by default.

To learn more, see Write Blocking.

Capped Collections

commit resets the required maximum size of capped collections which mongosync set to the maximum allowable size on the destination cluster.

Endpoint Protection

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

Back

resume

Next

reverse