removeShard¶

On this page

removeShard¶

Removes a shard from a 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. Once the shard is drained, MongoDB removes the shard from the cluster.

To run removeShard, use the db.runCommand( { <command> } ) method.

Behavior¶

You can only remove one shard at a time. removeShard returns an error if an existing removeShard operation is in progress.

Access Requirements¶

You must run removeShard while connected to a mongos. Issue the command against the admin database or use the sh._adminCommand() helper.

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 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 command and the Remove Shards from an Existing Sharded Cluster 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.

Example¶

From the mongo shell, the removeShard operation resembles the following:

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

Replace bristol01 with the name of the shard to remove. When you run removeShard, the command returns immediately, with a message that resembles the following:

{
   "msg" : "draining started successfully",
   "state" : "started",
   "shard" : "bristol01",
   "note" : "you need to drop or movePrimary these databases",
   "dbsToMove" : [
      "fizz",
      "buzz"
   ],
   "ok" : 1
}

The balancer begins migrating chunks from the shard named bristol01 to other shards in the cluster. These migrations happen slowly in order to avoid placing undue load on the cluster. Since bristol01 is the primary shard for the fizz and buzz databases, removeShard notes that you must use the movePrimary command to move those databases to another shard. Alternatively, you can use dropDatabase to drop the database and delete its associated data files.

Note

If the shard you are removing is not the primary shard for any databases, the dbsToMove array will be empty and removeShard can complete the migration without intervention.

If you run the command again, removeShard returns output that resembles the following:

{
   "msg" : "draining ongoing",
   "state" : "ongoing",
   "remaining" : {
      "chunks" : NumberLong(2),
      "dbs" : NumberLong(2)
   },
   "note" : "you need to drop or movePrimary these databases",
   "dbsToMove" : [
      "fizz",
      "buzz"
   ],
   "ok" : 1
}

The remaining document specifies how many chunks and databases remain on the shard. Use the movePrimary command to move each database listed in dbsToMove to another shard. Alternatively, use dropDatabase to drop the database.

When the balancer completes moving all chunks off of the shard and you have either moved or dropped any database listed in dbsToMove, running removeShard again returns output that resembles the following:

{
    "msg" : "removeshard completed successfully",
    "state" : "completed",
    "shard" : "bristol01",
    "ok" : 1
}

← mergeChunks removeShardFromZone →