addShard
Definition
addShard
Adds a shard replica set to a sharded cluster.
Tip
In
mongosh
, this command can also be run through thesh.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.
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
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:
| |
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
.