Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
Database Commands
/
Sharding

addShard

On this page

  • Definition
  • Compatibility
  • Syntax
  • Considerations
  • Examples

Definition

addShard

Adds a shard replica set to a sharded cluster.

Tip

In mongosh, this command can also be run through the sh.addShard() helper method.

Helper methods are convenient for 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.

Compatibility

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

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Important

This command is not supported in serverless instances. For more information, see Unsupported Commands.

Syntax

The command has the following syntax:

db.adminCommand(
   {
     addShard: "<replica_set>/<hostname><:port>",
     maxSize: <size>,
     name: "<shard_name>"
   }
)

Command Fields

The command contains the following fields:

Field
Type
Description

addShard

string

The replica set name, hostname, and port of at least one member of the shard's replica set. Any additional replica set member hostnames must be comma separated. For example:

<replica_set>/<hostname><:port>,<hostname><:port>, ...

maxSize

integer

Optional. The maximum size in megabytes of the shard. If you set maxSize to 0, MongoDB does not limit the size of the shard.

name

string

Optional. A name for the shard. If this is not specified, MongoDB automatically provides a unique name.

The addShard command stores shard configuration information in the config database. Always run addShard when using the admin database.

Specify a maxSize when you have machines with different disk capacities, or if you want to limit the amount of data on some shards. The maxSize constraint prevents the balancer from migrating chunks to the shard when the totalSize returned from running listDatabases on the shard exceeds the value of maxSize.

Considerations

Balancing

When you add a shard to a sharded cluster, you affect the balance of chunks among the shards of a cluster for all existing sharded collections. The balancer will begin migrating chunks so that the cluster will achieve balance. See Balancer Internals for more information.

Chunk migrations can have an impact on disk space, as the source shard automatically archives the migrated documents by default. For details, see moveChunk directory.

Hidden Members

Important

You cannot include a hidden member in the seed list provided to addShard.

Examples

The following command adds a replica set as a shard:

use admin
db.runCommand( { addShard: "repl0/mongodb3.example.net:27327"} )

Warning

Do not use localhost for the hostname unless your config server is also running on localhost.

Back

abortReshardCollection

Next

addShardToZone