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

# commitShardRemoval (database command)

## Definition

Removes a shard from a sharded cluster.

In order to run this command, you must first drain the shard with the [`startShardDraining`](https://www.mongodb.com/docs/manual/reference/command/startsharddraining.md#mongodb-dbcommand-dbcmd.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](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-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 start draining a shard, see the [`startShardDraining`](https://www.mongodb.com/docs/manual/reference/command/startsharddraining.md#mongodb-dbcommand-dbcmd.startShardDraining) command.

To check the status of a draining shard, see the [`shardDrainingStatus`](https://www.mongodb.com/docs/manual/reference/command/sharddrainingstatus.md#mongodb-dbcommand-dbcmd.shardDrainingStatus) command.

To stop draining a shard, see the [`stopShardDraining`](https://www.mongodb.com/docs/manual/reference/command/stopsharddraining.md#mongodb-dbcommand-dbcmd.stopShardDraining) 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( {
     commitShardRemoval: <shard>
} )
```

## 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 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`](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.

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`](https://www.mongodb.com/docs/manual/reference/command/movecollection.md#mongodb-dbcommand-dbcmd.moveCollection) command.

### Open Change Streams

Removing a shard may cause an open [change stream cursor](https://www.mongodb.com/docs/manual/changestreams.md#std-label-changeStreams) to close, and the closed change stream cursor may not be fully resumable.

## 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`](https://www.mongodb.com/docs/manual/reference/command/sharddrainingstatus.md#mongodb-dbcommand-dbcmd.shardDrainingStatus) command:

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

**Output:**

```javascript
{
   "msg" : "draining completed successfully",
   "state" : "drainingComplete",
   "ok" : 1,
   "$clusterTime" : {
      "clusterTime" : Timestamp(1771839836, 139),
      "signature" : {
         "hash" : BinData(0,"AAAAAAAAAAAAAAAAAAAAAAAAAAA="),
         "keyId" : NumberLong(0)
      }
   },
   "operationTime" : Timestamp(1771839836, 139)
}
```

If the output shows any databases in the `dbsToMove` field, use the [`movePrimary`](https://www.mongodb.com/docs/manual/reference/command/moveprimary.md#mongodb-dbcommand-dbcmd.movePrimary) command to move them onto a different shard.

If the output shows any unsharded collections in the `collectionsToMove` field, use the [`moveCollection`](https://www.mongodb.com/docs/manual/reference/command/movecollection.md#mongodb-dbcommand-dbcmd.moveCollection) command to move them onto a different shard.

When [`shardDrainingStatus`](https://www.mongodb.com/docs/manual/reference/command/sharddrainingstatus.md#mongodb-dbcommand-dbcmd.shardDrainingStatus) shows `{ state:
"drainingComplete" }`, the balancer has finished moving chunks off the shard. You can now remove the shard:

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

**Output:**

```javascript
{
   "ok" : 1,
   "$clusterTime" : {
      "clusterTime" : Timestamp(1771840037, 12),
      "signature" : {
         "hash" : BinData(0,"AAAAAAAAAAAAAAAAAAAAAAAAAAA="),
         "keyId" : NumberLong(0)
      }
   },
   "operationTime" : Timestamp(1771840037, 12)
}
```

## Learn More

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

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

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