/ /

/ /

commitShardRemoval (database command)

Definition

commitShardRemoval

Removes a shard from a sharded cluster.

In order to run this command, you must first drain the shard with the startShardDraining command. This command tells the balancer to move chunks from the shard to other shards in the cluster. You must also manually move any databases that use the shard as the primary shard and unsharded collections stored on the shard before running the commitShardRemoval command.

The command returns an error if the shard is not completely drained or if it contains a database or unsharded collection. If the shard is drained and all databases and unsharded collections migrated off of the shard, the command returns ok.

To check the status of a draining shard, see the shardDrainingStatus command.

New in version 8.3.

Compatibility

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

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

Note

This command is not supported in MongoDB Atlas. See Modify your Atlas Sharded Cluster to add or remove shards from your Atlas cluster.

Syntax

The command has the following syntax:

db.adminCommand( {
     commitShardRemoval: <shard>
} )

Behavior

Access Requirements

If you have authorization enabled, you must have the clusterManager role or any role that includes the removeShard action.

Database Migration Requirements

Each database in a sharded cluster has a primary shard. If the shard you want to drain is also the primary of one of the cluster's databases, then you must manually move the databases from its primary shard to a new shard after migrating all data from the shard.

If there is a database that uses the shard you want to use as a primary, the commitShardRemoval command returns an error.

For details, see the movePrimary command and the Remove Shards from a Sharded Cluster for more information.

Collection Migration Requirements

Unsharded collections are stored on individual shards. If one of these collections is on the shard you want to remove, you must first migrate the collection to a different shard.

If there is an unsharded collection stored on the shard you want to remove, the commitShardRemoval command returns an error.

To migrate an unsharded collection, see the moveCollection command.

Examples

To start draining a shard, use the db.adminCommand() method to run the startShardDraining command:

db.adminCommand( { startShardDraining: "shard04" } )

To check the status of the draining operation, use the shardDrainingStatus command:

db.adminCommand( { shardDrainingStatus: "shard04" } )

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

If the output shows any databases in the dbsToMove field, use the movePrimary command to move them onto a different shard.

If the output shows any unsharded collections in the collectionsToMove field, use the moveCollection command to move them onto a different shard.

When shardDrainingStatus shows { state: "completed" }, the balancer has finished moving chunks off the shard. You can now remove the shard:

db.adminCommand( { commitShardRemoval: "shard04" } )

Learn More

Back

commitReshardCollection

configureCollectionBalancing