removeShard

Definition

removeShard

Removes a shard from a sharded cluster. When you run removeShard, MongoDB drains the shard by using the balancer to move the shard's chunks to other shards in the cluster.

If the shard has unsharded collections, you must drain all the unsharded collections from the shard. Starting in MongoDB 8.0, you can use sh.moveCollection() to move unsharded collections. For details on the procedure to drain a shard, see Remove Shards from a Sharded Cluster.

Once the shard is drained, MongoDB removes the shard from the cluster.

Compatibility

This command is available in deployments hosted in the following environments:

• MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB

• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

The command has the following syntax:

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

Behavior

Example

From mongosh, the removeShard operation resembles the following:

db.adminCommand( { removeShard : "bristol01" } )

Replace bristol01 with the name of the shard to remove. When you run removeShard, the command returns with a message that resembles the following:

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

The balancer begins migrating ("draining") chunks from the shard named bristol01 to other shards in the cluster. These migrations happen slowly in order to avoid placing undue load on the cluster.

The output includes the field dbsToMove indicating the databases for which bristol01 is the primary shard. After the balancer moves all chunks and after all collections are moved by moveCollection, you must movePrimary for the database(s).

If you run the command again, removeShard returns the current status of the process. For example, if the operation is in an ongoing state, the command returns an output that resembles the following:

{
   "msg" : "draining ongoing",
   "state" : "ongoing",
   "remaining" : {
      "chunks" : NumberLong(2),
      "dbs" : NumberLong(2),
      "jumboChunks" : NumberLong(0)
   },
   "note" : "you need to drop or movePrimary these databases",
   "dbsToMove" : [
      "fizz",
      "buzz"
   ],
   "ok" : 1,
   "operationTime" : Timestamp(1575399086, 1655),
   "$clusterTime" : {
      "clusterTime" : Timestamp(1575399086, 1655),
      "signature" : {
         "hash" : BinData(0,"XBrTmjMMe82fUtVLRm13GBVtRE8="),
         "keyId" : NumberLong("6766255701040824328")
      }
   }
}

In the output, the remaining field includes the following fields:

Continue checking the status of the removeShard command (i.e. rerun the command) until the number of chunks remaining is 0.

{
   "msg" : "draining ongoing",
   "state" : "ongoing",
   "remaining" : {
      "chunks" : NumberLong(0),             // All chunks have moved
      "dbs" : NumberLong(2),
      "jumboChunks" : NumberLong(0)
   },
   "note" : "you need to drop or movePrimary these databases",
   "dbsToMove" : [
      "fizz",
      "buzz"
   ],
   "ok" : 1,
   "operationTime" : Timestamp(1575400343, 1),
   "$clusterTime" : {
      "clusterTime" : Timestamp(1575400343, 1),
      "signature" : {
         "hash" : BinData(0,"9plu5B/hw4uWAgEmjjBP3syw1Zk="),
         "keyId" : NumberLong("6766255701040824328")
      }
   }
}

After all chunks have been drained from the shard, if you have dbsToMove, you can either movePrimary for those databases or alternatively, drop the databases (which deletes the associated data files).

After the balancer completes moving all chunks off the shard and you have handled the dbsToMove, removeShard can finish. Running removeShard again returns output that resembles the following:

{
   "msg" : "removeshard completed successfully",
   "state" : "completed",
   "shard" : "bristol01",
   "ok" : 1,
   "operationTime" : Timestamp(1575400370, 2),
   "$clusterTime" : {
      "clusterTime" : Timestamp(1575400370, 2),
      "signature" : {
         "hash" : BinData(0,"JjSRciHECXDBXo0e5nJv9mdRG8M="),
         "keyId" : NumberLong("6766255701040824328")
      }
   }
}