In a sharded cluster,
movePrimaryreassigns the primary shard which holds all un-sharded collections in the database.
movePrimaryfirst changes the primary shard in the cluster metadata, and then migrates all un-sharded collections to the specified shard. Use the command with the following form:
For example, the following command moves the primary shard from
When the command returns, the database’s primary shard location has switched to the specified shard. To fully decommission a shard, use the
movePrimary, do not perform any read or write operations against any unsharded collection in that database until the command completes. Read or write operations issued against those collections during the migration can result in unexpected behavior, including potential failure of the migration operation or loss of data.
movePrimary may require a significant time to complete depending on the size of the database and factors such as network health or machine resources. Read or write operations issued against the database during the migration can result in unexpected behavior, including potential failure of the migration operation or loss of data.
Consider scheduling a maintenance window during which applications stop all reads and writes to the cluster. Issuing
movePrimary during planned downtime mitigates the risk of encountering undefined behavior due to interleaving reads or writes to the unsharded collections in the database.
If you use the
movePrimary command to move un-sharded collections, you must either restart all
mongos instances, or use the
flushRouterConfig command on all
mongos instances before reading or writing any data to any unsharded collections that were moved. This action ensures that the
mongos is aware of the new shard for these collections.
If you do not update the
mongos instances’ metadata cache after using
mongos may miss data on reads, and may not write data to the correct shard. To recover, you must manually intervene.
movePrimary fails if the destination shard contains a conflicting collection namespace. For example:
- An administrator issues
movePrimaryto change the primary shard for the
- A user or application issues a write operation against an unsharded collection in
movePrimaryis moving that collection. The write operation creates the collection in the original primary shard.
- An administrator later issues
movePrimaryto restore the original primary shard for the
movePrimaryfails due to the conflicting namespace left behind from the interleaving write operation.
The destination shard must rebuild its indexes in the foreground when it becomes the primary shard. The collection locks while the indexes are building, preventing reads and writes until the indexes are finished. This may require a significant amount of time depending on the number of indexes per collection and the amount of data to index.
See Index Build Operations on a Populated Collection for more information on the index build process.
See Remove Shards from an Existing Sharded Cluster for a complete procedure.