Remove Shards from a Sharded Cluster

Ensure the balancer is enabled

To migrate data from a shard, the balancer process must be enabled. To check the balancer state, use the sh.getBalancerState() method:

sh.getBalancerState()

If the operation returns true, the balancer is enabled.

If the operation returns false, see Enable the Balancer.

Determine the name of the shard to remove

To find the name of the shard, run the listShards command:

db.adminCommand( { listShards: 1 } )

The shards._id field contains the shard name.

Remove chunks from the shard

Run the removeShard command for the shard you want to remove:

db.adminCommand( { removeShard: "<shardName>" } )

The removeShard operation returns:

{
   "msg" : "draining started successfully",
   "state" : "started",
   "shard" : "<shardName>",
   "note" : "you need to drop or movePrimary these databases",
   "dbsToMove" : [
      "db1",
      "db2"
   ],
   "ok" : 1,
   "operationTime" : Timestamp(1575398919, 2),
   "$clusterTime" : {
      "clusterTime" : Timestamp(1575398919, 2),
      "signature" : {
         "hash" : BinData(0,"Oi68poWCFCA7b9kyhIcg+TzaGiA="),
         "keyId" : NumberLong("6766255701040824328")
      }
   }
}

The shard enters the draining state and the balancer begins migrating chunks from the removed shard to other shards in the cluster. These migrations happens slowly to avoid severe impact 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.

List sharded collection namespaces

To return a list of sharded collection namespaces, use the $shardedDataDistribution stage and project the ns field:

use admin
db.aggregate(
   [
      { $shardedDataDistribution: { } },
      { $project: { ns: 1 } }
   ]
)

Record the output to reference later in this tutorial.

List all databases in the cluster

db.adminCommand( { listDatabases: 1, nameOnly: true } )

Move collections off of the shard

For each database in the cluster, excluding admin and config, perform these steps:

1. List the database collections

   List the collections in the database, omitting the following types of collections:

   • Internal collections that support CSFLE

   • System collections

   • Time series collections

   • Views

   use <databaseName>
   db.getCollectionInfos(
      {
         $and: [
            { type: { $nin: [ "view", "timeseries" ] } },
            { name: { $not: { $regex: "^system\." } } },
            { name: { $not: { $regex: "^enxcol_\..*(\.esc|\.ecc|\.ecoc|\.ecoc\.compact)$" } } }
         ]
      },
      { nameOnly: true }
   )

2. Move necessary collections

   For each collection returned by getCollectionInfos() perform the following steps.

   Note

   Only one moveCollection operation can be in progress at a time. Complete all sub-steps before moving on to the next collection.

   1. Determine whether the collection needs to be moved.

      Run the $collStats aggregation stage and project the ns and shard fields:

      db.<collName>.aggregate(
         [
            {
               $collStats: { }
            },
            {
               $project: {
                  ns: 1,
                  shard: 1
               }
            }
         ]
      )

      If any of the following criteria are met, skip the collection and return to step i for the next collection in the database:

      • The ns field is present in the $shardedDataDistribution output from step 4.

      • The shard field is not the shard being removed.

      If neither of the preceding criteria are met, continue to step ii for the current collection.

   2. Move the collection.

      To move the collection, run sh.moveCollection() on the collection:

      sh.moveCollection( "<namespace>.<collection>", "<ID of recipient shard>" )

      Note

      moveCollection fails if you run the command on a namespace that is sharded. If you receive this error message, ignore it and return to step i for the next collection.

   3. Return to step i for each collection in the database.

3. Repeat the procedure for other databases

   Repeat step 6, Move collections off of the shard (and sub-steps) for each database in the cluster.

Change primary shard

Run the db.printShardingStatus() method:

db.printShardingStatus()

In the databases section of the command output, check the database.primary field. If the primary field is the removed shard, you must move that database's primary to a different shard.

To change a database's primary shard, run the movePrimary command.

db.adminCommand(
   {
      movePrimary: <dbName>,
      to: <shardName>
   }
)

Check migration status

To check the progress of the migration, run removeShard from the admin database again:

db.adminCommand( { removeShard: "<shardName>" } )

In the output, the remaining field includes these fields:

Continue checking the status of the removeShard command until the number of chunks remaining is 0.

db.adminCommand( { removeShard: "<shardName>" } )

Finalize shard removal

To finalize the shard removal process, re-run the removeShard command:

db.adminCommand( { removeShard: <shardName> } )

If the shard is removed, the command output resembles the following:

{
   msg: 'removeshard completed successfully',
   state: 'completed',
   shard: '<shardName>',
   ok: 1,
   '$clusterTime': {
      clusterTime: Timestamp({ t: 1721941519, i: 7 }),
      signature: {
         hash: Binary.createFromBase64('AAAAAAAAAAAAAAAAAAAAAAAAAAA=', 0),
         keyId: Long('0')
      }
   },
   operationTime: Timestamp({ t: 1721941519, i: 7 })
}