movePrimary
On this page
movePrimary
In a sharded cluster,
movePrimary
reassigns the primary shard which holds all un-sharded collections in the database.movePrimary
first 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:db.adminCommand( { movePrimary: <databaseName>, to: <newPrimaryShard> } ) For example, the following command moves the primary shard from
test
toshard0001
:db.adminCommand( { movePrimary : "test", to : "shard0001" } ) When the command returns, the database's primary shard location has switched to the specified shard. To fully decommission a shard, use the
removeShard
command.movePrimary
is an administrative command that is only available formongos
instances.Warning
After starting
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.
Considerations
mongos
uses "majority"
write concern for
movePrimary
.
Issue movePrimary
During A Maintenance Window
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.
Using movePrimary
To Move Unsharded Collections
For MongoDB 4.2 and previous, if using the movePrimary
command on a database that contains an unsharded collection, you
must perform the following additional steps.
Note
MongoDB 4.4 does not require these additional steps when moving databases that contain unsharded collections.
For MongoDB 4.2, you must either:
Restart all
mongos
instances and allmongod
shard members (including the secondary members);Use the
flushRouterConfig
command on allmongos
instances and allmongod
shard members (including the secondary members) before reading or writing any data to any unsharded collections that were moved.
For MongoDB 4.0 and earlier, you must either:
Restart all
mongos
instances;Use the
flushRouterConfig
command on allmongos
instances before reading or writing any data to any unsharded collections that were moved.
These steps ensure that all cluster nodes refresh their metadata cache, which includes the location of the primary shard. Otherwise, you may miss data on reads, and may not write data to the correct shard. To recover, you must manually intervene.
Namespace Conflicts Prevent Migration
movePrimary
fails if the destination shard contains a
conflicting collection namespace. For example:
An administrator issues
movePrimary
to change the primary shard for thehr
database.A user or application issues a write operation against an unsharded collection in
hr
whilemovePrimary
is moving that collection. The write operation creates the collection in the original primary shard.An administrator later issues
movePrimary
to restore the original primary shard for thehr
database.movePrimary
fails due to the conflicting namespace left behind from the interleaving write operation.
Destination Shard Must Rebuild Indexes
As part of the movePrimary
operation, the destination shard must
rebuild indexes on the migrated collections after becoming the primary
shard. 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 Builds on Populated Collections for more information on the index build process.
Additional Information
See Remove Shards from an Existing Sharded Cluster for a complete procedure.