`commit`

Description

Finalizes the sync between the source cluster and the destination cluster.

For more information, see Finalize Cutover Process.

Requirements

Before using the commit endpoint:

Warning
To reliably stop writes before you commit the migration, you must:
- Use "majority" write concern for all application writes to the synced collections on the source cluster throughout the migration.
- Shut down all writers to the synced collections cleanly.
Otherwise, writes can be applied after the cutover starts.
- If a write is applied while the cutover is in progress, mongosync detects the write. The migration fails permanently, and you must redo it.
- If writes are applied after the cutover completes, mongosync does not detect them. These writes are lost, and the migration silently corrupts your data.
During commit, you may still read from the source cluster.
Use the progress endpoint to confirm the following values:
- lag.overallLagSeconds is near 0 (Recommended)
  
  Note
  lag.overallLagSeconds
  lag.overallLagSeconds indicates the time between the last applied event and the time of the current latest event. When you send a commit request, mongosync enters the COMMITTING state for the amount of seconds reported by lag.overallLagSeconds, and then transitions to the COMMITTED state.
  When lag.overallLagSeconds is 0, the source and destination clusters are in a consistent state.
  For more information on the lag fields, see progress.
- verification.source.lagTimeSeconds and verification.destination.lagTimeSeconds are near 0 (Recommended)
- state: "RUNNING"
- canCommit: true
  
  Changed in version 1.21:
  canCommit is false when mongosync or the embedded verifier reports more than 30 seconds of lag. Calling /commit when canCommit is false returns an error.

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",         "ceaStage":"steady state",         "lag": {            "overallLagSeconds": 0,            "crudLagSeconds": 0,            "ddlLagSeconds": null         },         "lagTimeSeconds":0,         "collectionCopy":            {               "estimatedTotalBytes":694,               "estimatedCopiedBytes":694            },         "directionMapping":            {               "Source":"cluster0: localhost:27017",               "Destination":"cluster1: localhost:27018"            },         "source":            {               "pingLatencyMs":250            },         "destination":            {               "pingLatencyMs":-1            },         "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, data migration 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.

Index Builds

If you set buildIndexes to "afterDataCopy" or "excludeHashedAfterCopy" when calling /start, mongosync blocks commit requests until it has built all source indexes on the destination cluster.

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	By default, `mongosync` blocks writes on the source cluster when you call `commit` and on the destination cluster during sync. To learn more about how `mongosync` handles write blocking, 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

reverse