> This page location: /docs.md > /docs/development.md > /docs/manual/reference/command.md

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

# removeShard (database command)

## Definition

**Warning:**

Starting in MongoDB 8.3, the `removeShard` command is deprecated and will be removed in a future release.

The shard draining process has been replaced by the following commands:

- [`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)

Once the shard is drained, you can removed it with the [`commitShardRemoval`](https://www.mongodb.com/docs/manual/reference/command/commitshardremoval.md#mongodb-dbcommand-dbcmd.commitShardRemoval) command.

For details, see [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)

Removes a shard from a [sharded cluster](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-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.

**Note:**

The balancer must be enabled for `removeShard` to complete. If the balancer is disabled, the command remains in the draining state and does not finish, even if you have already moved all data off the shard.

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()`](https://www.mongodb.com/docs/manual/reference/method/sh.movecollection.md#mongodb-method-sh.moveCollection) to move unsharded collections. For details on the procedure to drain a shard, see [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)

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

**Note:**

If you want to re-add a removed shard to your sharded cluster, you must clear the [`storage.dbPath`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-storage.dbPath) of all the nodes of the shard to remove the shard's files of before you can re-add it.

## 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(
   {
     removeShard : <shardToRemove>
   }
)
```

## Behavior

### No Cluster Back Ups During Shard Removal

You cannot back up the cluster data during shard removal.

### Concurrent `removeShard` Operations

You can have more than one [`removeShard`](https://www.mongodb.com/docs/manual/reference/command/removeshard.md#mongodb-dbcommand-dbcmd.removeShard) operation in progress.

### 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 remove 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) for more information.

### Chunk Balancing

When you remove 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.

**See also:**

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

### Write Concern

[`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) converts the [write concern](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-write-concern) of the [`removeShard`](https://www.mongodb.com/docs/manual/reference/command/removeshard.md#mongodb-dbcommand-dbcmd.removeShard) command to [`"majority"`.](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-majority-)

### 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.

### DDL Operations

If you run `removeShard` while your cluster executes a DDL operation (operation that modifies a collection such as [`reshardCollection`](https://www.mongodb.com/docs/manual/reference/command/reshardcollection.md#mongodb-dbcommand-dbcmd.reshardCollection)), `removeShard` only executes after the concurrent DDL operation finishes.

## Example

From [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh), the [`removeShard`](https://www.mongodb.com/docs/manual/reference/command/removeshard.md#mongodb-dbcommand-dbcmd.removeShard) operation resembles the following:

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

Replace `bristol01` with the name of the shard to remove. When you run [`removeShard`](https://www.mongodb.com/docs/manual/reference/command/removeshard.md#mongodb-dbcommand-dbcmd.removeShard), the command returns with a message that resembles the following:

```javascript
{
   "msg" : "draining started successfully",
   "state" : "started",
   "shard" : "bristol01",
   "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(1575398919, 2),
   "$clusterTime" : {
      "clusterTime" : Timestamp(1575398919, 2),
      "signature" : {
         "hash" : BinData(0,"Oi68poWCFCA7b9kyhIcg+TzaGiA="),
         "keyId" : Long("6766255701040824328")
      }
   }
}
```

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

If you run the command again, [`removeShard`](https://www.mongodb.com/docs/manual/reference/command/removeshard.md#mongodb-dbcommand-dbcmd.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:

```javascript
{
   "msg" : "draining ongoing",
   "state" : "ongoing",
   "remaining" : {
      "chunks" : Long(2),
      "dbs" : Long(2),
      "jumboChunks" : Long(0),
      "collectionsToMove": Long(2)
   },
   "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")
      }
   }
}
```

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

| Field | Description |
| --- | --- |
| `chunks` | Total number of chunks currently remaining on the shard. |
| `dbs` | Total number of databases whose [primary shard](https://www.mongodb.com/docs/manual/core/sharded-cluster-shards.md#std-label-primary-shard) is the shard. These databases are specified in the `dbsToMove` output field. |
| `jumboChunks` | Of the total number of `chunks`, the number that are [jumbo.](https://www.mongodb.com/docs/manual/core/sharding-data-partitioning.md#std-label-jumbo-chunk) If the `jumboChunks` is greater than 0, wait until only the `jumboChunks` remain on the shard. Once only the jumbo chunks remain, you must manually clear the jumbo flag before the draining can complete. See [Clear jumbo Flag.](https://www.mongodb.com/docs/manual/tutorial/clear-jumbo-flag.md) After the `jumbo` flag clears, the balancer can migrate these chunks. For details on the migration procedure, see [Range Migration Procedure.](https://www.mongodb.com/docs/manual/core/sharding-balancer-administration.md#std-label-range-migration-procedure) |
| `collectionsToMove` | Total number of unsharded collections that you need to move from the shard. |
| `estimatedRemainingBytes` | Estimated number of bytes remaining on the shard undergoing removal. |

When you run [`transitionToDedicatedConfigServer`](https://www.mongodb.com/docs/manual/reference/command/transitiontodedicatedconfigserver.md#mongodb-dbcommand-dbcmd.transitionToDedicatedConfigServer), the `removeShard` output may include the following fields. These fields appear only after the balancer has moved all chunks and databases off the config server:

| Field | Description |
| --- | --- |
| `pendingRangeDeletions` | The number of pending range deletions remaining on the shard undergoing removal. |
| `firstNonEmptyCollection` | The first non-empty collection on the shard undergoing removal. |

Continue checking the status of the [`removeShard`](https://www.mongodb.com/docs/manual/reference/command/removeshard.md#mongodb-dbcommand-dbcmd.removeShard) command (that is, rerun the command) until the number of chunks remaining is `0`.

```javascript
{
   "msg" : "draining ongoing",
   "state" : "ongoing",
   "remaining" : {
      "chunks" : Long(0),             // All chunks have moved
      "dbs" : Long(2),
      "jumboChunks" : Long(0),
      "collectionsToMove": Long(2)
   },
   "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(1575400343, 1),
   "$clusterTime" : {
      "clusterTime" : Timestamp(1575400343, 1),
      "signature" : {
         "hash" : BinData(0,"9plu5B/hw4uWAgEmjjBP3syw1Zk="),
         "keyId" : Long("6766255701040824328")
      }
   }
}
```

After the balancer drains all chunks from the shard, you may need to manually move your collections and databases out of the drained shard.

If the `removeShard` output contains collections in the `collectionsToMove` field, use [`moveCollection`](https://www.mongodb.com/docs/manual/reference/command/movecollection.md#mongodb-dbcommand-dbcmd.moveCollection) to move those collections to a shard other than the draining shard or drop the collections (which deletes the associated data files).

If the `removeShard` output contains databases in the `dbsToMove` field, use [`movePrimary`](https://www.mongodb.com/docs/manual/reference/command/moveprimary.md#mongodb-dbcommand-dbcmd.movePrimary) for those databases or drop the databases (which deletes the associated data files).

**Note:**

For best performance, move your collections before you move your databases.

After the balancer completes moving all chunks off the shard and you have handled the `dbsToMove` and `collectionsToMove`, [`removeShard`](https://www.mongodb.com/docs/manual/reference/command/removeshard.md#mongodb-dbcommand-dbcmd.removeShard) can finish. Running [`removeShard`](https://www.mongodb.com/docs/manual/reference/command/removeshard.md#mongodb-dbcommand-dbcmd.removeShard) again returns output that resembles the following:

```javascript
{
   "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" : Long("6766255701040824328")
      }
   }
}
```
