> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# shardDrainingStatus (database command)

## Definition

Shows the status of a draining shard, whether the balancer is still moving chunks to other shards in the cluster or that the process is complete.

The command returns an error if the shard doesn't exist, otherwise it returns the status of the draining operation.

To start draining a shard, see the [`startShardDraining`](https://www.mongodb.com/docs/manual/reference/command/startsharddraining.md#mongodb-dbcommand-dbcmd.startShardDraining) command.

To stop draining a shard, see the [`stopShardDraining`](https://www.mongodb.com/docs/manual/reference/command/stopsharddraining.md#mongodb-dbcommand-dbcmd.stopShardDraining) command.

To remove a drained shard, see the [`commitShardRemoval`](https://www.mongodb.com/docs/manual/reference/command/commitshardremoval.md#mongodb-dbcommand-dbcmd.commitShardRemoval) command.

**Tip:**

In [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#std-program-mongosh), this command can also be run through the [`sh.shardDrainingStatus()`](https://www.mongodb.com/docs/manual/reference/method/sh.sharddrainingstatus.md#mongodb-method-sh.shardDrainingStatus) and.

Helper methods are convenient for [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#std-program-mongosh) users, but they may not return the same level of information as database commands.  In cases where the convenience is not needed or the additional return fields are required, use the database command.

**New in version 8.3**

## Compatibility

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

- [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

- [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

**Note:**

This command is not supported in [MongoDB Atlas](https://www.mongodb.com/docs/atlas). See [Modify your Atlas Sharded Cluster](https://www.mongodb.com/docs/atlas/scale-cluster/#modify-the-number-of-shards) to add or remove shards from your Atlas cluster.

## Syntax

The command has the following syntax:

```javascript
db.adminCommand( {
     shardDrainingStatus: <shard>
} )
```

## Output Fields

This command returns the following output:

| Field | Type | Description |
| --- | --- | --- |
| `msg` | string | Provides the current draining operation being performed by the balancer. |
| `state` | string | Provides the status of the draining operation. |
| `shard` | string | Indicates the draining shard. |
| `remaining` | document | Shows the remaining tasks the balancer must perform to drain the shard. |
| `remaining.chunks` | long | Indicates the number of chunks still on the shard. |
| `remaining.dbs` | long | Indicates the number of databases still on the shard. |
| `remaining.jumboChunks` | long | Indicates the number of large chunks still on the shard. |
| `remaining.collectionsToMove` | long | Indicates the number of collections still on the shard. |
| `remaining.estimatedRemainingBytes` | long | Estimated number of bytes remaining on the shard undergoing removal. |
| `note` | string | Provides additional message for the user. |
| `dbsToMove` | array | Indicates databases that use the draining shard as the [primary shard](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary-shard). Before you can remove the shard from the cluster, you must manually move these databases to a new shard using the [`movePrimary`](https://www.mongodb.com/docs/manual/reference/command/moveprimary.md#mongodb-dbcommand-dbcmd.movePrimary) command. |
| `collectionsToMove` | array | Indicates unsharded collections stored on the draining shard. Before you can remove the shard from the cluster, you must manually move these collections to another shard using the [`moveCollection`](https://www.mongodb.com/docs/manual/reference/command/movecollection.md#mongodb-dbcommand-dbcmd.moveCollection) command. |
| `pendingRangeDeletions` | long | The number of pending range deletions remaining on the shard undergoing removal. Present only during a [`transitionToDedicatedConfigServer`](https://www.mongodb.com/docs/manual/reference/command/transitiontodedicatedconfigserver.md#mongodb-dbcommand-dbcmd.transitionToDedicatedConfigServer) operation, after the balancer has moved all chunks and databases off the config server. |
| `firstNonEmptyCollection` | string | The first non-empty collection on the shard undergoing removal. Present only during a [`transitionToDedicatedConfigServer`](https://www.mongodb.com/docs/manual/reference/command/transitiontodedicatedconfigserver.md#mongodb-dbcommand-dbcmd.transitionToDedicatedConfigServer) operation, after the balancer has moved all chunks and databases off the config server. |

## Behavior

### Access Requirements

If you have [`authorization`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-security.authorization) enabled, you must have the [`clusterManager`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-clusterManager) role or any role that includes the [`removeShard`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-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 to a new shard after migrating all data from the shard. See the [`movePrimary`](https://www.mongodb.com/docs/manual/reference/command/moveprimary.md#mongodb-dbcommand-dbcmd.movePrimary) command and the [Remove Shards from a Sharded Cluster](https://www.mongodb.com/docs/manual/tutorial/remove-shards-from-cluster.md#std-label-remove-shards-from-cluster-tutorial) 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.

To migrate an unsharded collection, see the [`moveCollection`](https://www.mongodb.com/docs/manual/reference/command/movecollection.md#mongodb-dbcommand-dbcmd.moveCollection) command.

## Examples

To start draining a shard, use the [`db.adminCommand()`](https://www.mongodb.com/docs/manual/reference/method/db.admincommand.md#mongodb-method-db.adminCommand) method to run the [`startShardDraining`](https://www.mongodb.com/docs/manual/reference/command/startsharddraining.md#mongodb-dbcommand-dbcmd.startShardDraining) command:

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

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

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

**Output:**

```javascript
{
   msg: "draining ongoing",
   state: "ongoing",
   remaining: {
      chunks: Long(2),
      dbs: Long(2),
      jumboChunks: Long(0),
      collectionsToMove: Long(2)
   },
   shard: "shard04",
   note: "you need to call moveCollection for collectionsToMove and afterwards movePrimary for the dbsToMove",
   dbsToMove: [
      "fizz",
      "buzz"
   ],
   collectionsToMove: [
      "fizz.coll1",
      "buzz.coll1"
   ],
   ok: 1,
   operationTime: Timestamp(1575399086, 1655),
   $clusterTime: {
      clusterTime: Timestamp(1575399086, 1655),
      signature: {
         hash: BinData(0,"XBrTmjMMe82fUtVLRm13GBVtRE8="),
         keyId: Long("6766255701040824328")
      }
   }
}
```

## Learn More

- [`startShardDraining`](https://www.mongodb.com/docs/manual/reference/command/startsharddraining.md#mongodb-dbcommand-dbcmd.startShardDraining)

- [`commitShardRemoval`](https://www.mongodb.com/docs/manual/reference/command/commitshardremoval.md#mongodb-dbcommand-dbcmd.commitShardRemoval)