Remove Shards from an Existing Sharded Cluster
On this page
To remove a shard you must ensure the shard’s data is migrated to the remaining shards in the cluster. This procedure describes how to safely migrate data and how to remove a shard.
When you remove a shard in a cluster with an uneven chunk distribution, the balancer first removes the chunks from the draining shard and then balances the remaining uneven chunk distribution.
This procedure describes how to safely remove a single shard. Do not use this procedure to migrate an entire cluster to new hardware. To migrate an entire shard to new hardware, migrate individual shards as if they were independent replica sets.
To remove a shard, first connect to one of the cluster’s mongos instances using mongo shell. Then use the sequence of tasks in this document to remove a shard from the cluster.
Considerations
A shard removal may cause an open change stream cursor to close, and the closed change stream cursor may not be fully resumable.
Ensure the Balancer Process is Enabled
To successfully migrate data from a shard, the balancer process must be enabled. Check the balancer state using the sh.getBalancerState() helper in the mongo shell. For more information, see the section on balancer operations.
Determine the Name of the Shard to Remove
To determine the name of the shard, connect to a mongos instance with the mongo shell and either:
Use the
listShardscommand, as in the following:db.adminCommand( { listShards: 1 } )Run either the
sh.status()or thedb.printShardingStatus()method.
The shards._id field lists the name of each shard.
Remove Chunks from the Shard
From the admin database, run the removeShard command. This begins “draining” chunks from the shard you are removing to other shards in the cluster. For example, for a shard named mongodb0, run:
db.adminCommand( { removeShard: "mongodb0" } )
This operation returns immediately, with the following response:
{
"msg" : "draining started successfully",
"state" : "started",
"shard" : "mongodb0",
"note" : "you need to drop or movePrimary these databases",
"dbsToMove" : [
"fiz",
"buzz"
],
"ok" : 1,
"$clusterTime" : {
"clusterTime" : Timestamp(1510716515, 1),
"signature" : {
"hash" : BinData(0,"B2ViX7XLzFLS5Fl9XEuFXbwKIM4="),
"keyId" : NumberLong("6488045157173166092")
}
},
"operationTime" : Timestamp(1510716515, 1)
}
The balancer begins migrating chunks from the shard named bristol01 to other shards in the cluster. These migrations happens slowly to avoid placing undue load on the overall cluster. Depending on your network capacity and the amount of data, this operation can take from a few minutes to several days to complete.
Note
Each database in a sharded cluster has a primary shard. If the shard you want to remove is also the primary of one of the cluster’s databases, removeShard lists the database in the dbsToMove field. To finish removing the shard, you must either move the database to a new shard after migrating all data from the shard or drop the database, deleting the associated data files.
Check the Status of the Migration
To check the progress of the migration at any stage in the process, run removeShard from the admin database again. For example, for a shard named mongodb0, run:
db.adminCommand( { removeShard: "mongodb0" } )
The command returns output similar to the following:
{
"msg" : "draining ongoing",
"state" : "ongoing",
"remaining" : {
"chunks" : NumberLong(2),
"dbs" : NumberLong(2)
},
"note" : "you need to drop or movePrimary these databases",
"dbsToMove" : [
"fizz",
"buzz"
],
"ok" : 1,
"$clusterTime" : {
"clusterTime" : Timestamp(1510716515, 1),
"signature" : {
"hash" : BinData(0,"B2ViX7XLzFLS5Fl9XEuFXbwKIM4="),
"keyId" : NumberLong("6488045157173166092")
}
},
"operationTime" : Timestamp(1510716515, 1)
}
In the output, the remaining document displays the remaining number of chunks that MongoDB must migrate to other shards and the number of MongoDB databases that have “primary” status on this shard.
Continue checking the status of the removeShard command until the number of chunks remaining is 0. Always run the command on the admin database. If you are on a database other than admin, you can use sh._adminCommand to run the command on admin.
Move Databases to Another Primary Shard
If the shard is the primary shard for one or more databases in the cluster, then you must make that database use a different shard as its primary shard. removeShard lists any databases that you need to move in the dbsToMove field in the command output. If the shard is not the primary shard for any databases, skip to the next task, Finalize the Migration.
Warning
Do not perform this procedure until you have finished draining the shard.
To move a database to another shard, use the movePrimary command.
Important
To ensure a smooth migration, refer to the considerations in the movePrimary command documentation before running movePrimary.
To migrate the fizz database from mongodb0 to mongodb1, issue the following command:
db.adminCommand( { movePrimary: "fizz", to: "mongodb1" })
This command does not return until MongoDB completes moving all data. The response from this command will resemble the following:
{
"primary" : "mongodb1",
"ok" : 1,
"$clusterTime" : {
"clusterTime" : Timestamp(1510767932, 10),
"signature" : {
"hash" : BinData(0,"OJyZ0B4/Cp9z+mdrXLbJtNC7iuo="),
"keyId" : NumberLong("6488693018630029321")
}
},
"operationTime" : Timestamp(1510767932, 10)
}
Warning
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 movePrimary, the mongos may miss data on reads, and may not write data to the correct shard. To recover, you must manually intervene.
Finalize the Migration
To clean up all metadata information and finalize the removal, run removeShard again. For example, for a shard named mongodb0, run:
db.adminCommand( { removeShard: "mongodb0" } )
A success message appears at completion:
{
"msg" : "removeshard completed successfully",
"state" : "completed",
"shard" : "mongodb0",
"ok" :