start
On this page
Description
Starts the synchronization between a source and destination cluster.
Requirements
State
To use the start
endpoint, mongosync
must be in the IDLE
state.
Permissions
The user specified in the mongosync
connection string must have the
required permissions on the source and destination clusters. Refer to
User Permissions to ensure that the user has the correct
permissions to start the synchronization.
Multiple mongosync
Instances
Ensure that you use the configured mongosync
user in the connection
strings for the cluster0
or cluster1
settings when
you start mongosync
.
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 Start Multiple Mongosyncs.
Request
POST /api/v1/start
Request Body Parameters
Parameter | Type | Necessity | Description | |
---|---|---|---|---|
source | string | Required | Name of the source cluster. | |
destination | string | Required | Name of the destination cluster. | |
buildIndexes | string | Optional | Configures index builds during sync. Supported Options:
If you call New in version 1.3.0. | |
documentFilter | document | Optional | ImportantCluster-to-Cluster Sync Beta ProgramThis feature is only available in Starting in To learn more, see Document Filtering. New in version 1.8: Beta | |
enableUserWriteBlocking | boolean | Optional | If set to To reverse sync, the
Default value is | |
includeNamespaces | array | Optional | Filters the databases or collections to include in sync. If you configure a filter on a source cluster that has multiple
databases, If you want to modify the filter to add a newly created database, you have to restart the filtered sync from the beginning. For more details, see Filtered Sync. For current limitations, see Filtered Sync. New in version 1.1. | |
excludeNamespaces | array | Optional | Filters the databases or collections to exclude from sync. If you configure a filter on a source cluster that has multiple
databases, If you want to modify the filter to add a newly created database, you have to restart the filtered sync from the beginning. For more details, see Filtered Sync. For current limitations, see Filtered Sync. New in version 1.6. | |
namespaceRemap | array | Optional | ImportantCluster-to-Cluster Sync Beta ProgramThis feature is only available in Array of documents that specify namespace changes to make during sync. For more information, see Namespace Remapping. New in version 1.8: Beta | |
reversible | boolean | Optional | If set to To reverse sync, the This option is not supported for the following configurations:
For more information, see the reverse endpoint. Default value is | |
sharding | document | Optional | Configures sync between a replica set and sharded cluster. Sync from a replica set to a sharded cluster requires this option. For more information, see Sharding Parameters. New in version 1.1. |
Sharding Parameters
New in version 1.1.
To sync from a replica set to a sharded cluster, set the
sharding
option to shard collections on the destination cluster.
The sharding
option has the following parameters:
Parameter | Type | Description |
---|---|---|
createSupportingIndexes | boolean | Optional. Sets whether sync creates a supporting index
for the shard key, if none exists. Defaults to false . |
shardingEntries | array of documents | Required. Sets the namespace and key of collections to shard during sync. Collections not included in this array sync to unsharded collections on the destination cluster. If set with an empty array, no collections are sharded. |
shardingEntries .collection | string | Sets the collection to shard. |
shardingEntries .database | string | Sets the database of the collection to shard. |
shardingEntries .shardCollection | document | Sets the shard key to generate on the destination cluster. |
shardingEntries .shardCollection .key | array | Sets the fields to use for the shard key. For more information, see Shard Keys. |
mongosync
throws an error if the sharding
option is not set when
syncing from a replica set to a sharded cluster. mongosync
also
throws an error if the sharding
option is set with any other
configuration.
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: Start a Sync Job
The following example starts a sync job between cluster0
and
cluster1
. The source cluster is cluster0
and the destination
cluster is cluster1
.
Request
curl localhost:27182/api/v1/start -XPOST \ --data ' { "source": "cluster0", "destination": "cluster1" } '
Response
{"success":true}
Example: Start a Reversible Sync Job
The following example starts a sync job between cluster0
and
cluster1
. The source cluster is cluster0
and the destination
cluster is cluster1
.
The reversible
and enableUserWriteBlocking
fields allow the sync
to be reversed. To reverse the sync direction, see: reverse.
Request
curl localhost:27182/api/v1/start -XPOST \ --data ' { "source": "cluster0", "destination": "cluster1", "reversible": true, "enableUserWriteBlocking": true } '
Response
{"success":true}
Example: Start a Filtered Sync Job
The following example starts a sync job between cluster0
and
cluster1
. The source cluster is cluster0
and the destination
cluster is cluster1
.
cluster0
contains the sales
, marketing
, and
engineering
databases.
The sales
database contains the EMEA
, APAC
, and AMER
collections.
The includeNamespaces
array in this example defines a filter on two
of the databases, sales
and marketing
.
The sales
database also filters on the EMEA
and APAC
collections.
"includeNamespaces" : [ { "database" : "sales", "collections": [ "EMEA", "APAC" ] }, { "database" : "marketing" } ]
After you call the /start
API with this filter in place,
mongosync
:
Syncs all of the collections in the
marketing
databaseFilters out the
engineering
databaseSyncs the
EMEA
andAPAC
collections from thesales
databaseFilters out the
AMER
collection
The includeNamespaces
option creates a filter. To filter the sync,
see: Filtered Sync
Request
curl -X POST "http://localhost:27182/api/v1/start" --data ' { "source": "cluster0", "destination": "cluster1", "includeNamespaces": [ { "database": "sales", "collectionsRegex": { "pattern": "^accounts_.+$", "options": "i" } }, { "database": "marketing" } ] } '
Response
{"success":true}
Example: Start Sync from Replica Set to Sharded Cluster
Request
curl localhost:27182/api/v1/start -XPOST \ --data ' { "source": "cluster0", "destination": "cluster1", "sharding": { "createSupportingIndexes": true, "shardingEntries": [ { "database": "accounts", "collection": "us_east", "shardCollection": { "key": [ { "location": 1 }, { "region": 1 }, ] } } ] } } '
Response
{"success":true}
Behavior
State
If the start
request is successful, mongosync
enters the
RUNNING
state.
Pre-Split Chunks
New in version 1.1.
When mongosync
syncs to a sharded cluster, it pre-splits chunks for
sharded collections on the destination cluster. This is supported in the
following configurations:
Sync from a replica set to a sharded cluster.
Sync between sharded clusters that differ in the number of shards.
Shard Replica Sets
New in version 1.1.
Sync from a replica set to a sharded cluster requires the
sharding
option. This option configures how mongosync
shards
collections.
The sharding.shardingEntries
array specifies the collections to shard.
Collections that are not listed in this array replicate as unsharded.
Supporting Indexes
New in version 1.1.
mongosync
syncs indexes from the source cluster to the destination
cluster. But, when syncing from a replica set to a sharded cluster,
mongosync
may require an additional index to support the shard key,
which may not exist on the source cluster.
mongosync
can create supporting indexes for sharded collections during sync.
This is done by setting the sharding.createSupportingIndexes
option.
When sharding.createSupportingIndexes
is false
(the default):
Each shard key you provide for the
sharding.shardingEntries
option must have an existing index on the source cluster.One of the indexes used for the shard key must have simple collation if the collection uses any other collation.
To use a unique index in the shard key, you must specify its uniqueness when you create the index on the source cluster.
Unique indexes on the source cluster that are incompatible with the requested shard key on the destination cluster, such as a unique index on the source that does not contain the requested shard key as a prefix on the destination, can cause
mongosync
to fail.
When sharding.createSupportingIndexes
is true
:
If the supporting indexes exist on the source cluster,
mongosync
syncs the indexes to the destination cluster and uses them as shard keys.If the supporting indexes don't exist,
mongosync
creates them on the destination cluster.
The sharding.createSupportingIndexes
option affects all sharded
collections.
Rename During Sync
New in version 1.1.
Collections listed in the sharding.shardingEntries
array
when synced from a replica set to a sharded cluster
become sharded collections on the destination cluster.
Renaming a collection (such as with the renameCollection
command)
on the source cluster after calling start
but before mongosync
begins
to copy the collection can block the collection from sharding on the destination.
Note
Renaming collections to use a different database while syncing from a replica set to a sharded cluster is not supported.
To check whether it is safe to rename collections, call the
progress
endpoint and check the value of the
collectionCopy.estimatedCopiedBytes
field in the return document.
A value of 0 indicates that
mongosync
has not started to copy the collection.Renaming a collection at this point may result in an unsharded collection on the destination cluster, as the transition to copying can happen before the rename takes effect on the source.
A value greater than 0 indicates that
mongosync
has started the copy. Renaming the collection from this point on does not block its sharding on the destination cluster, even in the event of a crash.
Required Indexes
When you call /start
with the buildIndexes
option set to never
,
mongosync
skips building unnecessary indexes.
Indexes that are always built include:
mongosync
builds an index on the_id
field of every collection it copies.mongosync
builds dummy indexes for each sharded collection that does not have an index to support the shard key on the destination cluster. WhenbuildIndexes
is set tonever
,mongosync
retains this index after commit.
Endpoint Protection
mongosync
does not protect the start
endpoint. However, by default
the API binds to localhost only and does not accept calls from other sources.
Additionally, the start
call does not expose connection credentials
or user data.