diff --git a/source/administration/sharding.txt b/source/administration/sharding.txt index 77353311024..44ed7c91538 100644 --- a/source/administration/sharding.txt +++ b/source/administration/sharding.txt @@ -96,8 +96,8 @@ use the following procedure as a quick starting point: sh.addShard( "/mongodb0.example.net:27027" ) Replace, ```` with the name of the replica set, and - MongoDB will discover all other members of the replica set. Repeat - this step for each new shard in your cluster. + MongoDB will discover all other members of the replica set. + Repeat this step for each new shard in your cluster. .. optional:: @@ -222,6 +222,8 @@ procedure: Replace ```` and ```` with the hostname and TCP port number of where the shard is accessible. + Alternately specify a :term:`replica set` name and at least one + hostname which is a member of the replica set. For example: diff --git a/source/reference/command/addShard.txt b/source/reference/command/addShard.txt index 552ed694a7c..650611d4aaf 100644 --- a/source/reference/command/addShard.txt +++ b/source/reference/command/addShard.txt @@ -6,29 +6,65 @@ addShard .. dbcommand:: addShard - :option name: Optional. Unless specified, a name will be - automatically provided to uniquely identify - the shard. + :param string hostname: a hostname or replica-set/hostname string. - :option maxSize: Optional. Unless specified, shards will consume - the total amount of available space on their - machines if necessary. Use the ``maxSize`` value - to limit the amount of space the database can - use. Specify this value in megabytes. + :param string name: Optional. Unless specified, a name will be + automatically provided to uniquely identify + the shard. - The :dbcommand:`addShard` command registers a new with a sharded - cluster. You must run this command against a :program:`mongos` - instance. The command takes the following form: + :param integer maxSize: Optional. Unless specified, shards will consume + the total amount of available space on their + machines if necessary. Use the ``maxSize`` value + to limit the amount of space the database can + use. Specify this value in megabytes. + + Use the :dbcommand:`addShard` command to add a database instance + or replica set to a :term:`sharded cluster`. + You must run this command against a :program:`mongos` instance. + + The command takes the following form: .. code-block:: javascript { addShard: ":" } + .. example:: + + .. code-block:: javascript + + db.runCommand({addShard: "mongodb0.example.net:27027"}) + Replace ``:`` with the hostname and port of the - database instance you want to add as a shard. Because the - :program:`mongos` instances do not have state and distribute - configuration in the :term:`config database`, send this - command to only one :program:`mongos` instance. + database instance you want to add as a shard. + + .. warning:: + + Do not use ``localhost`` for the hostname unless your + :term:`configuration server ` + is also running on ``localhost``. + + The optimal configuration is to deploy shards across + :term:`replica sets `. + To add a shard on a replica set you must specify the name of the + replica set and the hostname of at least one member of the replica + set. You may specify all of the hostnames, but at least one member + must be specified. + + .. code-block:: javascript + + { addShard: "replica-set/hostname:port" } + + .. example:: + + .. code-block:: javascript + + db.runCommand({ addShard: "repl0/mongodb3.example.net:27327"}) + + If you specify additional hostnames, all must be members of the same + replica set. + + Send this command to only one :program:`mongos` instance, it will + store shard configuration information in the :term:`config database`. .. note:: @@ -39,3 +75,10 @@ addShard The ``maxSize`` constraint prevents the :term:`balancer` from migrating chunks to the shard when the value of :status:`mem.mapped` exceeds the value of ``maxSize``. + + .. seealso:: + + * :method:`sh.addShard()` + * :doc:`/administration/sharding` + * :doc:`/tutorial/add-shards-to-shard-cluster` + * :doc:`/tutorial/remove-shards-from-cluster` diff --git a/source/reference/method/db.printShardingStatus.txt b/source/reference/method/db.printShardingStatus.txt index 336d558373c..55c5e0adf9e 100644 --- a/source/reference/method/db.printShardingStatus.txt +++ b/source/reference/method/db.printShardingStatus.txt @@ -9,4 +9,9 @@ db.printShardingStatus() Provides a formatted report of the sharding configuration and the information regarding existing chunks in a :term:`sharded cluster`. - .. seealso:: :method:`sh.status()` + This method must be executed on a :program:`mongos` instance. + + This method is a wrapper around the :dbcommand:`printShardingStatus` + command. + + .. seealso:: :method:`sh.status()`, :dbcommand:`printShardingStatus` diff --git a/source/reference/method/sh.addShard.txt b/source/reference/method/sh.addShard.txt index 5d9fd7e1d81..5bf8dfbd718 100644 --- a/source/reference/method/sh.addShard.txt +++ b/source/reference/method/sh.addShard.txt @@ -6,10 +6,13 @@ sh.addShard() .. method:: sh.addShard(host) - :param host: Specify the hostname of a new shard server. + :param string host: Specify the hostname of a database instance or a + replica set configuration. - Use this to add shard instances to the current :term:`cluster`. The - ``host`` parameter can be in any of the following forms: :: + Use this method to add a database instance or replica set to a + :term:`sharded cluster`. + This method must be run on a :program:`mongos` instance. + The ``host`` parameter can be in any of the following forms: :: [hostname] [hostname]:[port] @@ -17,11 +20,43 @@ sh.addShard() [set]/[hostname],[hostname]:port You can specify shards using the hostname, or a hostname and port - combination if the shard is running on a non-standard port. A - :term:`replica set` can also function as a shard member. In these - cases supply :method:`addShard ` with the set name, - followed by at least one existing member of the set as a seed in a - comma separated list, as in the final two examples. - - This function provides a wrapper around the administrative command - :dbcommand:`addShard`. + combination if the shard is running on a non-standard port. + + .. warning:: + + Do not use ``localhost`` for the hostname unless your + :term:`configuration server ` + is also running on ``localhost``. + + The optimal configuration is to deploy shards across + :term:`replica sets `. + To add a shard on a replica set you must specify the name of the + replica set and the hostname of at least one member of the replica + set. You may specify all of the hostnames, but at least one member + must be specified. + + If you specify additional hostnames, all must be members of the same + replica set. + + .. code-block:: javascript + + sh.addShard("set-name/seed-hostname") + + .. example:: + + .. code-block:: javascript + + sh.addShard("repl0/mongodb3.example.net:27327") + + The :method:`sh.addShard()` method is a helper for the + :dbcommand:`addShard` command. + The :dbcommand:`addShard` command has additional options which are + not available with this helper. + + .. seealso:: + + * :dbcommand:`addShard` + * :doc:`/administration/sharding` + * :doc:`/tutorial/add-shards-to-shard-cluster` + * :doc:`/tutorial/remove-shards-from-cluster` + diff --git a/source/sharding.txt b/source/sharding.txt index cc6f7c0d0da..d644727bdfa 100644 --- a/source/sharding.txt +++ b/source/sharding.txt @@ -7,19 +7,17 @@ Sharding Sharding distributes a single logical database system across a cluster of machines. Sharding uses range-based portioning to distribute :term:`documents ` -based on a -specific :term:`shard key`. +based on a specific :term:`shard key`. This page lists the documents, tutorials, and reference pages that describe sharding. For an overview, see :doc:`/core/sharding`. To configure, maintain, and -troubleshoot sharded clusters, see :doc:`/administration/sharding`. For -deployment architectures, see -:doc:`/administration/sharding-architectures`. For details on the -internal operations of sharding, see :doc:`/core/sharding-internals`. -For procedures for performing certain sharding tasks, see the :ref:`Tutorials ` -list. +troubleshoot sharded clusters, see :doc:`/administration/sharding`. +For deployment architectures, see :doc:`/administration/sharding-architectures`. +For details on the internal operations of sharding, see :doc:`/core/sharding-internals`. +For procedures for performing certain sharding tasks, see the +:ref:`Tutorials ` list. Documentation ------------- diff --git a/source/tutorial/add-shards-to-shard-cluster.txt b/source/tutorial/add-shards-to-shard-cluster.txt index 7804ab4fbbc..8ed6bbc1e6e 100644 --- a/source/tutorial/add-shards-to-shard-cluster.txt +++ b/source/tutorial/add-shards-to-shard-cluster.txt @@ -48,6 +48,12 @@ Or you can use the :method:`sh.addShard()` helper in the Replace ``[hostname]`` and ``[port]`` with the hostname and TCP port number of where the shard is accessible. +.. warning:: + + Do not use ``localhost`` for the hostname unless your + :term:`configuration server ` + is also running on ``localhost``. + For example: .. code-block:: javascript diff --git a/source/tutorial/deploy-shard-cluster.txt b/source/tutorial/deploy-shard-cluster.txt index 6dab0739474..335a5e48371 100644 --- a/source/tutorial/deploy-shard-cluster.txt +++ b/source/tutorial/deploy-shard-cluster.txt @@ -74,7 +74,7 @@ The :program:`mongos` instance runs on the default MongoDB TCP port: To start :program:`mongos` instance running on the ``mongos0.example.net`` host, that connects to the config server -instances running on the following hosts: +instances running on the following hosts: - ``mongoc0.example.net`` - ``mongoc1.example.net`` @@ -112,18 +112,19 @@ port ``27017``, issue the following command: mongo mongos0.example.net -Then, from the :program:`mongo` shell connected to the :program:`mongos` +Then, from a :program:`mongo` shell connected to the :program:`mongos` instance, call the :method:`sh.addShard()` method for each shard that you want to add to the cluster: .. code-block:: javascript - sh.addShard( "sfo30.example.net" ) - sh.addShard( "sfo40.example.net" ) + sh.addShard( "s0/sfo30.example.net" ) + sh.addShard( "s1/sfo40.example.net" ) -If ``sfo30.example.net`` and ``sfo40.example.net`` are members of a -replica set, MongoDB will discover all other members of the replica -set. +If the host you are adding is a member of a replica set, you +*must* specify the name of the replica set. :program:`mongos` +will discover the names of other members of the replica set based on +the name and the hostname you provide. These operations add two shards, provided by: