Definition
startShardDrainingStarts the process of draining chunks from a shard to prepare it for removal from a sharded cluster.
When the command runs, it tells the balancer that you want to drain the given shard. Asynchronously, the balancer then begins moving chunks from the shard to other shards in the cluster. When the balancer completes this process, the shard contains no data and can be safely removed from the cluster.
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( { startShardDraining: <shardToDrain> } )
Behavior
Access Requirements
If you have authorization enabled, you must
have the clusterManager role or any role that
includes the removeShard action.
No Cluster Back Ups During Shard Drain
You cannot back up the cluster while draining the shard.
Concurrent Drain Shard Operations
You can have more than one shard draining operation in progress at a time.
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
to a new shard after migrating all data from the shard. See the
movePrimary command and the
Remove Shards from a Sharded Cluster for more information.
Chunk Balancing
When you drain 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.
Write Concern
mongos converts the write concern of the startShardDraining command to
"majority".
Change Streams
Draining a shard may cause an open change stream cursor to close, and the closed change stream cursor may not be fully resumable.
DDL Operations
If you run startShardDraining while your cluster is
executing a DDL operation (operation that modifies a collection
such as reshardCollection), the shard draining only
executes after the concurrent DDL operation finishes.
Examples
To start draining a shard, use the db.adminCommand()
method:
db.adminCommand( { startShardDraining: "shard04" } )