From 34621ca68a0a6036e3fdfbae890fe0bad349b9a8 Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Thu, 11 Apr 2013 15:27:08 -0400 Subject: [PATCH 1/5] DOCS-1377 document missing isMaster fields and related edits --- source/reference/command/isMaster.txt | 147 +++++++++++++++++------- source/reference/glossary.txt | 4 + source/reference/method/db.isMaster.txt | 15 ++- 3 files changed, 117 insertions(+), 49 deletions(-) diff --git a/source/reference/command/isMaster.txt b/source/reference/command/isMaster.txt index 6bd2d27afa2..41ff003b6af 100644 --- a/source/reference/command/isMaster.txt +++ b/source/reference/command/isMaster.txt @@ -6,12 +6,25 @@ isMaster .. dbcommand:: isMaster - The :dbcommand:`isMaster` command provides a basic overview of the current - replication configuration. MongoDB :term:`drivers ` and + The :dbcommand:`isMaster` command returns a document describing the + role of the :program:`mongod` instance it is run against. If the + instance is a member of a replica set, then :dbcommand:`isMaster` + returns a subset of the replica set configuration and status including + whether or not the instance is the :term:`primary` of the replica set. + + If sent to a :program:`mongod` instance which is not a member of a + replica set, a subset of information is returned. + + MongoDB :term:`drivers ` and :term:`clients ` use this command to determine what kind of member they're connected to and to discover additional members of a - :term:`replica set`. The :method:`db.isMaster()` method provides a - wrapper around this database command. + :term:`replica set`. + + The :method:`db.isMaster()` method provides a wrapper around this + database command. + + The :dbcommand:`isMaster` command returns a :term:`document` whose + contents vary depending on the role of the :program:`mongod` instance. The command takes the following form: @@ -19,20 +32,57 @@ isMaster { isMaster: 1 } - This command returns a :term:`document` containing the - following fields: - - .. data:: isMaster.setname + **Common Fields** - The name of the current replica set, if applicable. + The following :dbcommand:`isMaster` fields are common across all roles: - .. data:: isMaster.ismaster + .. data:: ismaster A boolean value that reports when this node is writable. If - ``true``, then the current node is either a :term:`primary` in a - :term:`replica set`, a :term:`master` in a master-slave + ``true``, then this instance is a :term:`primary` in a + :term:`replica set`, or a :term:`master` in a master-slave configuration, or a standalone :program:`mongod`. + This field will only be ``false`` if the instance is a + :term:`secondary` member of a replica set. + + .. data:: isMaster.maxBsonObjectSize + + The maximum permitted size of a :term:`BSON` object in bytes for + this :program:`mongod` process. If not provided, clients should + assume a max size of "``4 * 1024 * 1024``". + + .. data:: isMaster.maxMessageSizeBytes + + The maximum permitted size of a :term:`BSON` wire protocol message. + The default value is ``48000000`` bytes. + + .. data:: isMaster.localTime + + .. versionadded:: 2.1.1 + + Returns the local server time in UTC. This value is an + :term:`ISOdate`. + + **Shard Servers** + + :program:`mongos` instances add the following field to the + :dbcommand:`isMaster` response document: + + .. data:: isMaster.msg + + Contains the value ``isdbgrid`` when :dbcommand:`isMaster` + is sent to a :program:`mongos` instance. + + **Replica Sets** + + The following :dbcommand:`isMaster` fields are added to the common + fields when the instance is a member of a replica set: + + .. data:: isMaster.setName + + The name of the current replica set. + .. data:: isMaster.secondary A boolean value that, when ``true``, indicates that the @@ -41,52 +91,63 @@ isMaster .. data:: isMaster.hosts - An array of strings in the format of "``[hostname]:[port]``" - listing all members of the :term:`replica set` that are not - ":term:`hidden `". + An array of strings in the format of ``"[hostname]:[port]"`` + listing all members of the :term:`replica set` that are neither + :term:`hidden ` nor :term:`passive `. - .. data:: isMaster.arbiter + .. data:: isMaster.passives - An array of strings in the format of "``[hostname]:[port]``" - listing all members of the :term:`replica set` that are - :term:`arbiters ` + An array of strings in the format of ``"[hostname]:[port]"`` + listing all members of the :term:`replica set` which have a + :ref:`priority ` of ``0``. - Only appears in the :dbcommand:`isMaster` response for replica - sets that have arbiter members. + This field only appears if there is at least one member with a + :ref:`priority ` of ``0``. - .. data:: isMaster.arbiterOnly + .. data:: isMaster.arbiters - A boolean value that, when ``true`` indicates that the current - instance is an :term:`arbiter`. + An array of strings in the format of ``"[hostname]:[port]"`` + listing all members of the :term:`replica set` that are + :term:`arbiters `. - :data:`~isMaster.arbiterOnly` only appears in the - :dbcommand:`isMaster` response from arbiters. + This field only appears if there is at least one arbiter in the + replica set. .. data:: isMaster.primary - The ``[hostname]:[port]`` for the current - :term:`replica set` :term:`primary`, if applicable. + A string in the format of ``"[hostname]:[port]"`` listing the + current :term:`primary` member of the replica set. - .. data:: isMaster.me + .. data:: isMaster.arbiterOnly - The ``[hostname]:[port]`` of the node responding to this - command. + A boolean value that indicates that the current instance is an + :term:`arbiter`. + The :data:`~isMaster.arbiterOnly` field will only be present, with + a value of ``true``, if the instance is an arbiter. - .. data:: isMaster.maxBsonObjectSize + .. data:: isMaster.passive - The maximum permitted size of a :term:`BSON` object in bytes for - this :program:`mongod` process. If not provided, clients should - assume a max size of "``4 * 1024 * 1024``". + A boolean value that indicates that the current instance is + :term:`hidden`. + The :data:`~isMaster.passive` field will only be present, with + a value of ``true``, if the instance is hidden. - .. data:: isMaster.localTime + .. data:: isMaster.hidden - .. versionadded:: 2.1.1 + A boolean value that indicates that the current instance is + :term:`hidden`. + The :data:`~isMaster.hidden` field will only be present, with + a value of ``true``, if the instance is hidden. + + .. data:: isMaster.tags + + A document that lists any tags assigned to this member. + This field is only present if there are tags assigned to the member. + + .. data:: isMaster.me - Returns the local server time in UTC. This value is a - :term:`ISOdate`. You can use the :js:func:`toString()` - JavaScript method to convert this value to a local date string, - as in the following example: + The ``[hostname]:[port]`` of the member responding to this command. - .. code-block:: javascript + .. seealso:: - db.isMaster().localTime.toString(); + :method:`db.isMaster()` diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index fde266d4184..82ba646f0d4 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -612,6 +612,10 @@ Glossary :dbcommand:`isMaster`, :method:`db.isMaster`, and :data:`local.system.replset.members[n].hidden`. + passive member + A member of a :term:`replica set` that cannot become primary + because its :ref:`priority ` is ``0``. + delayed member A member of a :term:`replica set` that cannot become primary and applies operations at a specified delay. This delay is useful diff --git a/source/reference/method/db.isMaster.txt b/source/reference/method/db.isMaster.txt index 9f232cede56..570f2458e5b 100644 --- a/source/reference/method/db.isMaster.txt +++ b/source/reference/method/db.isMaster.txt @@ -6,10 +6,13 @@ db.isMaster() .. method:: db.isMaster() - Returns a status document with fields that includes the - ``ismaster`` field that reports if the current node is the - :term:`primary` node, as well as a report of a subset of current - replica set configuration. + :returns: A document describing the role of the :program:`mongod` + instance. If the instance is a member of a replica set, then + the fields :data:`isMaster.ismaster` and :data:`isMaster.secondary` + can be used to determine if the instance is the :term:`primary` or + if it is a :term:`secondary` member. - This function provides a wrapper around the :term:`database command` - :dbcommand:`isMaster` + .. see:: + + :dbcommand:`isMaster` for the complete description of the output + of this command. From 8fc0e7248091929b6ce659ea0d0c8f2b43c87030 Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Thu, 11 Apr 2013 15:29:30 -0400 Subject: [PATCH 2/5] DOCS-1377 minor sphinx correction --- source/reference/command/isMaster.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reference/command/isMaster.txt b/source/reference/command/isMaster.txt index 41ff003b6af..03c0e7027e2 100644 --- a/source/reference/command/isMaster.txt +++ b/source/reference/command/isMaster.txt @@ -36,7 +36,7 @@ isMaster The following :dbcommand:`isMaster` fields are common across all roles: - .. data:: ismaster + .. data:: isMaster.ismaster A boolean value that reports when this node is writable. If ``true``, then this instance is a :term:`primary` in a From 86562b99b22e6b3cabfc7fa08aae83a547e9b885 Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Fri, 12 Apr 2013 01:52:05 -0400 Subject: [PATCH 3/5] DOCS-1377 edits incorporating hannes' comments --- source/reference/command/isMaster.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/reference/command/isMaster.txt b/source/reference/command/isMaster.txt index 03c0e7027e2..6ed0145f747 100644 --- a/source/reference/command/isMaster.txt +++ b/source/reference/command/isMaster.txt @@ -41,10 +41,12 @@ isMaster A boolean value that reports when this node is writable. If ``true``, then this instance is a :term:`primary` in a :term:`replica set`, or a :term:`master` in a master-slave - configuration, or a standalone :program:`mongod`. + configuration, or a :program:`mongos` instance, or a standalone + :program:`mongod`. - This field will only be ``false`` if the instance is a - :term:`secondary` member of a replica set. + This field will be ``false`` if the instance is a + :term:`secondary` member of a replica set or if the member is an + :term:`arbiter` of a replica set. .. data:: isMaster.maxBsonObjectSize From 1afeeae59f1bce3899e4a14a1175b3eccb9382d7 Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Fri, 12 Apr 2013 14:55:44 -0400 Subject: [PATCH 4/5] DOCS-1377 incorporating comments --- source/reference/command/isMaster.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/source/reference/command/isMaster.txt b/source/reference/command/isMaster.txt index 6ed0145f747..f1cb24b189e 100644 --- a/source/reference/command/isMaster.txt +++ b/source/reference/command/isMaster.txt @@ -56,6 +56,8 @@ isMaster .. data:: isMaster.maxMessageSizeBytes + .. versionadded:: 2.3.2 + The maximum permitted size of a :term:`BSON` wire protocol message. The default value is ``48000000`` bytes. @@ -95,7 +97,8 @@ isMaster An array of strings in the format of ``"[hostname]:[port]"`` listing all members of the :term:`replica set` that are neither - :term:`hidden ` nor :term:`passive `. + :term:`hidden `, :term:`passive `, + nor :term:`arbiters `. .. data:: isMaster.passives From e156bd588b806fc76727ac2313475d48756e8489 Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Sun, 14 Apr 2013 15:32:12 -0400 Subject: [PATCH 5/5] minor: add phrasing around hosts and arbiters arrays per hannes --- source/reference/command/isMaster.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/reference/command/isMaster.txt b/source/reference/command/isMaster.txt index f1cb24b189e..c366df5c4fc 100644 --- a/source/reference/command/isMaster.txt +++ b/source/reference/command/isMaster.txt @@ -100,6 +100,9 @@ isMaster :term:`hidden `, :term:`passive `, nor :term:`arbiters `. + Drivers use this array and the :data:`isMaster.passives` to determine + which members to read from. + .. data:: isMaster.passives An array of strings in the format of ``"[hostname]:[port]"`` @@ -109,6 +112,9 @@ isMaster This field only appears if there is at least one member with a :ref:`priority ` of ``0``. + Drivers use this array and the :data:`isMaster.hosts` to determine + which members to read from. + .. data:: isMaster.arbiters An array of strings in the format of ``"[hostname]:[port]"``