From 0c564cb17de21440d3acc736b68f82bbb87b1a44 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Wed, 3 Mar 2021 17:13:52 +0100 Subject: [PATCH] DOCSP-8628: Document new 'hello' command --- config/redirects | 8 + source/core/replica-set-hidden-member.txt | 2 +- source/core/sharded-cluster-query-router.txt | 6 +- ...xtracts-server-status-projection-base.yaml | 8 +- source/includes/extracts-transactions.yaml | 2 +- .../fact-bulkwrite-operation-batches.rst | 2 +- source/reference/command.txt | 4 +- .../command/{isMaster.txt => hello.txt} | 163 +++++++++--------- source/reference/command/isdbgrid.txt | 4 +- source/reference/command/nav-replication.txt | 10 +- source/reference/command/serverStatus.txt | 29 +++- source/reference/method.txt | 8 +- source/reference/method/db.auth.txt | 16 +- .../method/{db.isMaster.txt => db.hello.txt} | 16 +- source/reference/method/js-database.txt | 10 +- source/reference/mongodb-wire-protocol.txt | 3 +- source/reference/replica-configuration.txt | 2 +- source/reference/replication.txt | 5 +- ...-client-side-query-aggregation-support.txt | 2 +- source/release-notes/5.0.txt | 10 ++ .../configure-a-hidden-replica-set-member.txt | 2 +- source/tutorial/expand-replica-set.txt | 2 +- source/tutorial/remove-replica-set-member.txt | 4 +- source/tutorial/restore-sharded-cluster.txt | 16 +- source/tutorial/use-database-commands.txt | 8 +- 25 files changed, 187 insertions(+), 155 deletions(-) rename source/reference/command/{isMaster.txt => hello.txt} (70%) rename source/reference/method/{db.isMaster.txt => db.hello.txt} (58%) diff --git a/config/redirects b/config/redirects index ac749720007..a2fd77b2c91 100644 --- a/config/redirects +++ b/config/redirects @@ -1784,3 +1784,11 @@ raw: /manual/core/wildcard -> ${base}/manual/core/index-wildcard/ [v3.4-v4.0]: /${version}/reference/mongodb-defaults -> ${base}/${version}/reference/ [v3.6-*]: /${version}/reference/command/clean -> ${base}/${version}/reference/command/nav-administration/ + +# +# Redirects for 5.0 and greater (if pages are removed in 4.4 that used to exist in earlier versions) +# + +[v5.0-*]: /${version}/reference/command/isMaster -> ${base}/${version}/reference/command/hello +[v5.0-*]: /${version}/reference/method/db.isMaster -> ${base}/${version}/reference/method/db.hello + diff --git a/source/core/replica-set-hidden-member.txt b/source/core/replica-set-hidden-member.txt index c9ff657e579..e26261655ab 100644 --- a/source/core/replica-set-hidden-member.txt +++ b/source/core/replica-set-hidden-member.txt @@ -19,7 +19,7 @@ data set but is **invisible** to client applications. Hidden members are good for workloads with different usage patterns from the other members in the :term:`replica set`. Hidden members must always be :ref:`priority 0 members ` and -so **cannot become primary**. The :method:`db.isMaster()` method does not +so **cannot become primary**. The :method:`db.hello()` method does not display hidden members. Hidden members, however, **may vote** in :ref:`elections `. diff --git a/source/core/sharded-cluster-query-router.txt b/source/core/sharded-cluster-query-router.txt index c1fd983a579..49dfabda4a9 100644 --- a/source/core/sharded-cluster-query-router.txt +++ b/source/core/sharded-cluster-query-router.txt @@ -205,15 +205,15 @@ Confirm Connection to ``mongos`` Instances ------------------------------------------ To detect if the MongoDB instance that your client is connected -to is :binary:`~bin.mongos`, use the :dbcommand:`isMaster` command. When a -client connects to a :binary:`~bin.mongos`, :dbcommand:`isMaster` returns +to is :binary:`~bin.mongos`, use the :dbcommand:`hello` command. When a +client connects to a :binary:`~bin.mongos`, :dbcommand:`hello` returns a document with a ``msg`` field that holds the string ``isdbgrid``. For example: .. code-block:: javascript { - "ismaster" : true, + "isWritablePrimary" : true, "msg" : "isdbgrid", "maxBsonObjectSize" : 16777216, "ok" : 1, diff --git a/source/includes/extracts-server-status-projection-base.yaml b/source/includes/extracts-server-status-projection-base.yaml index b1bcc6fb196..c0388a1ac2c 100644 --- a/source/includes/extracts-server-status-projection-base.yaml +++ b/source/includes/extracts-server-status-projection-base.yaml @@ -27,13 +27,13 @@ content: | - :serverstatus:`metrics.commands.update.arrayFilters` - - :serverstatus:`metrics.commands.findAndModify.arrayFilters` + - :serverstatus:`metrics.commands.findAndModify.arrayFilters` - Added new metric to track number of times ``newlyAdded`` fields were automatically removed: - :serverstatus:`metrics.repl.reconfig.numAutoReconfigsForRemovalOfNewlyAddedFields` - + - Replaced :serverstatus:`opReadConcernCounters` with :serverstatus:`readConcernCounters` to track use of read concern levels specified by query operations @@ -56,6 +56,10 @@ content: | - :serverstatus:`metrics.cursor.totalOpened` + - Added new metric to track hello commands: + + - :serverstatus:`connections.exhaustHello` + - Starting in MongoDB 4.4, {{operationName}}: - Added new metrics to track write concern failures caused diff --git a/source/includes/extracts-transactions.yaml b/source/includes/extracts-transactions.yaml index 77bcb637867..a3dd5e0438d 100644 --- a/source/includes/extracts-transactions.yaml +++ b/source/includes/extracts-transactions.yaml @@ -115,7 +115,7 @@ content: | ref: transactions-operations-restrictions-info content: | - Informational commands, such as :dbcommand:`isMaster`, + Informational commands, such as :dbcommand:`hello`, :dbcommand:`buildInfo`, :dbcommand:`connectionStatus` (and their helper methods) are allowed in transactions; however, they cannot be the first operation in the transaction. diff --git a/source/includes/fact-bulkwrite-operation-batches.rst b/source/includes/fact-bulkwrite-operation-batches.rst index 1ac92e29f53..51ef94797f8 100644 --- a/source/includes/fact-bulkwrite-operation-batches.rst +++ b/source/includes/fact-bulkwrite-operation-batches.rst @@ -1,7 +1,7 @@ The number of operations in each group cannot exceed the value of the :limit:`maxWriteBatchSize ` of the database. As of MongoDB 3.6, this value is ``100,000``. -This value is shown in the :data:`isMaster.maxWriteBatchSize` field. +This value is shown in the :data:`hello.maxWriteBatchSize` field. This limit prevents issues with oversized error messages. If a group exceeds this :limit:`limit `, diff --git a/source/reference/command.txt b/source/reference/command.txt index adc8bae91db..0aae61d7b0d 100644 --- a/source/reference/command.txt +++ b/source/reference/command.txt @@ -335,9 +335,9 @@ Replication Commands - Internal command that applies :term:`oplog` entries to the current data set. - * - :dbcommand:`isMaster` + * - :dbcommand:`hello` - - Displays information about this member's role in the replica set, including whether it is the master. + - Displays information about this member's role in the replica set, including whether it is the primary. * - :dbcommand:`replSetAbortPrimaryCatchUp` diff --git a/source/reference/command/isMaster.txt b/source/reference/command/hello.txt similarity index 70% rename from source/reference/command/isMaster.txt rename to source/reference/command/hello.txt index cec56f6fa2e..8b3c3567a42 100644 --- a/source/reference/command/isMaster.txt +++ b/source/reference/command/hello.txt @@ -1,6 +1,6 @@ -======== -isMaster -======== +===== +hello +===== .. default-domain:: mongodb @@ -10,28 +10,33 @@ isMaster :depth: 1 :class: singlecol +.. meta:: + :keywords: isMaster + Definition ---------- -.. dbcommand:: isMaster +.. dbcommand:: hello + + .. versionadded:: 5.0 (and 4.4.2, 4.2.10, 4.0.21, and 3.6.21) - :dbcommand:`isMaster` returns a document that describes the role of + :dbcommand:`hello` returns a document that describes the role of the :binary:`~bin.mongod` instance. If the optional field ``saslSupportedMechs`` is specified, the command also returns an - :data:`array of SASL mechanisms ` used + :data:`array of SASL mechanisms ` used to create the specified user's credentials. If the instance is a member of a - replica set, then :dbcommand:`isMaster` returns a subset of the + replica set, then :dbcommand:`hello` returns a subset of the replica set configuration and status including whether or not the instance is the :term:`primary` of the replica set. When sent to a :binary:`~bin.mongod` instance that is not a member of a - replica set, :dbcommand:`isMaster` returns a subset of this + replica set, :dbcommand:`hello` returns a subset of this information. MongoDB :term:`drivers ` and :term:`clients ` use - :dbcommand:`isMaster` to determine the state of the replica set + :dbcommand:`hello` to determine the state of the replica set members and to discover additional members of a :term:`replica set`. @@ -42,24 +47,24 @@ The command takes the following form: .. code-block:: javascript - db.runCommand( { isMaster: 1 } ) + db.runCommand( { hello: 1 } ) -Starting in MongoDB 4.0, the :dbcommand:`isMaster` command accepts -optional fields ``saslSupportedMechs: `` to return an -additional field :data:`isMaster.saslSupportedMechs` in its result -and ``comment `` to add a log comment associated with the command. +The :dbcommand:`hello` command accepts optional fields +``saslSupportedMechs: `` to return an additional field +:data:`hello.saslSupportedMechs` in its result and ``comment `` to +add a log comment associated with the command. .. code-block:: javascript - db.runCommand( { isMaster: 1, saslSupportedMechs: "", comment: } ) - -The :method:`db.isMaster()` method in the :binary:`~bin.mongo` shell -provides a wrapper around :dbcommand:`isMaster`. + db.runCommand( { hello: 1, saslSupportedMechs: "", comment: } ) + +The :method:`db.hello()` method in the :binary:`~bin.mongo` shell +provides a wrapper around :dbcommand:`hello`. Behavior -------- -.. |operation| replace:: :dbcommand:`isMaster` +.. |operation| replace:: :dbcommand:`hello` Client Disconnection ~~~~~~~~~~~~~~~~~~~~~ @@ -72,10 +77,10 @@ Output All Instances ~~~~~~~~~~~~~ -The following :dbcommand:`isMaster` fields are common across all +The following :dbcommand:`hello` fields are common across all roles: -.. data:: isMaster.ismaster +.. data:: hello.isWritablePrimary A boolean value that reports when this node is writable. If ``true``, then this instance is a :term:`primary` in a @@ -86,24 +91,22 @@ roles: :term:`secondary` member of a replica set or if the member is an :term:`arbiter` of a replica set. -.. data:: isMaster.topologyVersion +.. data:: hello.topologyVersion *For internal use by MongoDB.* - .. versionadded:: 4.4 - -.. data:: isMaster.maxBsonObjectSize +.. data:: hello.maxBsonObjectSize The maximum permitted size of a :term:`BSON` object in bytes for this :binary:`~bin.mongod` process. If not provided, clients should assume a max size of "``16 * 1024 * 1024``". -.. data:: isMaster.maxMessageSizeBytes +.. data:: hello.maxMessageSizeBytes The maximum permitted size of a :term:`BSON` wire protocol message. The default value is ``48000000`` bytes. -.. data:: isMaster.maxWriteBatchSize +.. data:: hello.maxWriteBatchSize The maximum number of write operations permitted in a write batch. If a batch exceeds this @@ -113,60 +116,50 @@ roles: The value of this limit is ``100,000`` writes. - .. versionchanged:: 3.6 - The limit raises from ``1,000`` to ``100,000`` writes. This limit also applies to legacy ``OP_INSERT`` messages. -.. data:: isMaster.localTime +.. data:: hello.localTime Returns the local server time in UTC. This value is an :term:`ISO date `. -.. data:: isMaster.logicalSessionTimeoutMinutes - - .. versionadded:: 3.6 +.. data:: hello.logicalSessionTimeoutMinutes .. include:: /includes/fact-session-timeout.rst Only available when ``featureCompatibilityVersion`` is ``"3.6"`` or greater. See :ref:`3.6-compatibility-enabled`. - -.. data:: isMaster.connectionId - .. versionadded:: 4.2 +.. data:: hello.connectionId An identifier for the :binary:`~bin.mongod`/:binary:`~bin.mongos` instance's outgoing connection to the client. -.. data:: isMaster.minWireVersion +.. data:: hello.minWireVersion The earliest version of the wire protocol that this :binary:`~bin.mongod` or :binary:`~bin.mongos` instance is capable of using to communicate with clients. - Clients may use :data:`~isMaster.minWireVersion` to help negotiate + Clients may use :data:`~hello.minWireVersion` to help negotiate compatibility with MongoDB. -.. data:: isMaster.maxWireVersion +.. data:: hello.maxWireVersion The latest version of the wire protocol that this :binary:`~bin.mongod` or :binary:`~bin.mongos` instance is capable of using to communicate with clients. - Clients may use :data:`~isMaster.maxWireVersion` to help negotiate + Clients may use :data:`~hello.maxWireVersion` to help negotiate compatibility with MongoDB. -.. data:: isMaster.readOnly +.. data:: hello.readOnly - .. versionadded:: 3.4 - A boolean value that, when ``true``, indicates that the :binary:`~bin.mongod` or :binary:`~bin.mongos` is running in read-only mode. -.. data:: isMaster.compression - - .. versionadded:: 3.4 +.. data:: hello.compression An array listing the compression algorithms used or available for use (i.e. common to both the client and the :binary:`~bin.mongod` or @@ -178,26 +171,26 @@ roles: - If the :binary:`~bin.mongod` is enabled to use both the ``snappy,zlib`` compressors and a client has specified ``zlib``, - the :data:`~isMaster.compression` field would contain: + the :data:`~hello.compression` field would contain: .. code-block:: javascript - + "compression": [ "zlib" ] - If the :binary:`~bin.mongod` is enabled to use both the ``snappy,zlib`` compressors and a client has specified ``zlib,snappy``, - the :data:`~isMaster.compression` field would contain: + the :data:`~hello.compression` field would contain: .. code-block:: javascript - + "compression": [ "zlib", "snappy" ] - If the :binary:`~bin.mongod` is enabled to use the ``snappy`` compressor and a client has specified ``zlib,snappy``, - the :data:`~isMaster.compression` field would contain : + the :data:`~hello.compression` field would contain : .. code-block:: javascript - + "compression": [ "snappy" ] - If the :binary:`~bin.mongod` is enabled to use the ``snappy`` @@ -209,7 +202,7 @@ roles: :binary:`~bin.mongod` or :binary:`~bin.mongos` instance, the field does not return. -.. data:: isMaster.saslSupportedMechs +.. data:: hello.saslSupportedMechs An array of SASL mechanisms used to create the user's credential or credentials. Supported SASL mechanisms are: @@ -220,53 +213,53 @@ roles: The field is returned only when the command is run with the ``saslSupportedMechs`` field: - + .. code-block:: javascript - db.runCommand( { isMaster: 1, saslSupportedMechs: "" } ) + db.runCommand( { hello: 1, saslSupportedMechs: "" } ) Sharded Instances ~~~~~~~~~~~~~~~~~ :binary:`~bin.mongos` instances add the following field to the -:dbcommand:`isMaster` response document: +:dbcommand:`hello` response document: -.. data:: isMaster.msg +.. data:: hello.msg - Contains the value ``isdbgrid`` when :dbcommand:`isMaster` + Contains the value ``isdbgrid`` when :dbcommand:`hello` returns from a :binary:`~bin.mongos` instance. Replica Sets ~~~~~~~~~~~~ -:dbcommand:`isMaster` contains these fields when returned by a member +:dbcommand:`hello` contains these fields when returned by a member of a replica set: -.. data:: isMaster.hosts +.. data:: hello.hosts An array of strings in the format of ``"[hostname]:[port]"`` that lists all members of the :term:`replica set` that are neither :term:`hidden `, :term:`passive `, nor :term:`arbiters `. - Drivers use this array and the :data:`isMaster.passives` to determine + Drivers use this array and the :data:`hello.passives` to determine which members to read from. -.. data:: isMaster.setName +.. data:: hello.setName The name of the current :replica set. -.. data:: isMaster.setVersion +.. data:: hello.setVersion The current replica set config version. -.. data:: isMaster.secondary +.. data:: hello.secondary A boolean value that, when ``true``, indicates if the :binary:`~bin.mongod` is a :term:`secondary` member of a :term:`replica set`. -.. data:: isMaster.passives +.. data:: hello.passives An array of strings in the format of ``"[hostname]:[port]"`` listing all members of the :term:`replica set` which have a @@ -275,10 +268,10 @@ of a replica set: This field only appears if there is at least one member with a :rsconf:`members[n].priority` of ``0``. - Drivers use this array and the :data:`isMaster.hosts` to determine + Drivers use this array and the :data:`hello.hosts` to determine which members to read from. -.. data:: isMaster.arbiters +.. data:: hello.arbiters An array of strings in the format of ``"[hostname]:[port]"`` listing all members of the :term:`replica set` that are @@ -287,31 +280,31 @@ of a replica set: This field only appears if there is at least one arbiter in the replica set. -.. data:: isMaster.primary +.. data:: hello.primary A string in the format of ``"[hostname]:[port]"`` listing the current :term:`primary` member of the replica set. -.. data:: isMaster.arbiterOnly +.. data:: hello.arbiterOnly A boolean value that , when ``true``, indicates that the current - instance is an :term:`arbiter`. The :data:`~isMaster.arbiterOnly` + instance is an :term:`arbiter`. The :data:`~hello.arbiterOnly` field is only present, if the instance is an arbiter. -.. data:: isMaster.passive +.. data:: hello.passive A boolean value that, when ``true``, indicates that the current instance is :term:`passive `. The - :data:`~isMaster.passive` field is only present for members with a + :data:`~hello.passive` field is only present for members with a :rsconf:`members[n].priority` of ``0``. -.. data:: isMaster.hidden +.. data:: hello.hidden A boolean value that, when ``true``, indicates that the current instance is :term:`hidden `. The - :data:`~isMaster.hidden` field is only present for hidden members. + :data:`~hello.hidden` field is only present for hidden members. -.. data:: isMaster.tags +.. data:: hello.tags .. include:: /includes/fact-tags-field.rst @@ -320,39 +313,37 @@ of a replica set: :rsconf:`members[n].tags` -.. data:: isMaster.me +.. data:: hello.me The ``[hostname]:[port]`` of the member that returned - :dbcommand:`isMaster`. + :dbcommand:`hello`. -.. data:: isMaster.electionId +.. data:: hello.electionId A unique identifier for each election. Included only in the output - of :dbcommand:`isMaster` for the :term:`primary`. Used by clients + of :dbcommand:`hello` for the :term:`primary`. Used by clients to determine when elections occur. -.. data:: isMaster.lastWrite - - .. versionadded:: 3.4 +.. data:: hello.lastWrite A document containing :term:`optime` and date information for the database's most recent write operation. - .. data:: isMaster.lastWrite.opTime + .. data:: hello.lastWrite.opTime An object giving the :term:`optime` of the last write operation. - .. data:: isMaster.lastWrite.lastWriteDate + .. data:: hello.lastWrite.lastWriteDate A date object containing the time of the last write operation. - .. data:: isMaster.lastWrite.majorityOpTime + .. data:: hello.lastWrite.majorityOpTime An object giving the :term:`optime` of the last write operation readable by :readconcern:`majority <"majority">` reads. - .. data:: isMaster.lastWrite.majorityWriteDate + .. data:: hello.lastWrite.majorityWriteDate A date object containing the time of the last write operation readable by diff --git a/source/reference/command/isdbgrid.txt b/source/reference/command/isdbgrid.txt index 24f018b4340..2179b70480c 100644 --- a/source/reference/command/isdbgrid.txt +++ b/source/reference/command/isdbgrid.txt @@ -40,7 +40,7 @@ isdbgrid "ok" : 0 } - You can instead use the :dbcommand:`isMaster` command to determine + You can instead use the :dbcommand:`hello` command to determine connection to a :binary:`~bin.mongos`. When connected to a - :binary:`~bin.mongos`, the :dbcommand:`isMaster` command returns a document that + :binary:`~bin.mongos`, the :dbcommand:`hello` command returns a document that contains the string ``isdbgrid`` in the ``msg`` field. diff --git a/source/reference/command/nav-replication.txt b/source/reference/command/nav-replication.txt index 9a182001a59..4598a6f8d13 100644 --- a/source/reference/command/nav-replication.txt +++ b/source/reference/command/nav-replication.txt @@ -24,9 +24,9 @@ Replication Commands - Internal command that applies :term:`oplog` entries to the current data set. - * - :dbcommand:`isMaster` + * - :dbcommand:`hello` - - Displays information about this member's role in the replica set, including whether it is the master. + - Displays information about this member's role in the replica set, including whether it is the primary. * - :dbcommand:`replSetAbortPrimaryCatchUp` @@ -70,11 +70,11 @@ Replication Commands .. toctree:: - :titlesonly: - :hidden: + :titlesonly: + :hidden: /reference/command/applyOps - /reference/command/isMaster + /reference/command/hello /reference/command/replSetAbortPrimaryCatchUp /reference/command/replSetFreeze /reference/command/replSetGetConfig diff --git a/source/reference/command/serverStatus.txt b/source/reference/command/serverStatus.txt index 506b6296cdc..61adf878d8a 100644 --- a/source/reference/command/serverStatus.txt +++ b/source/reference/command/serverStatus.txt @@ -273,6 +273,7 @@ connections "active" : , "threaded" : , "exhaustIsMaster" : , + "exhaustHello" : , "awaitingTopologyChanges" : }, @@ -324,15 +325,31 @@ connections .. serverstatus:: connections.exhaustIsMaster The number of connections whose last request was an - :dbcommand:`isMaster` request with - :ref:`exhaustAllowed `. + ``isMaster`` request with :ref:`exhaustAllowed `. + + .. note:: + + If you are running MongoDB 5.0 or later, do not use the + ``isMaster`` command. Instead, use :dbcommand:`hello`. .. versionadded:: 4.4 +.. serverstatus:: connections.exhaustHello + + The number of connections whose last request was a :dbcommand:`hello` + request with :ref:`exhaustAllowed `. + + .. versionadded:: 5.0 (and 4.4.2) + .. serverstatus:: connections.awaitingTopologyChanges - The number of clients currently waiting in an :dbcommand:`isMaster` - request for a topology change. + The number of clients currently waiting in a :dbcommand:`hello` or + ``isMaster`` request for a topology change. + + .. note:: + + If you are running MongoDB 5.0 or later, do not use the + ``isMaster`` command. Instead, use :dbcommand:`hello`. .. versionadded:: 4.4 @@ -2308,7 +2325,7 @@ repl ], "setName" : , "setVersion" : , - "ismaster" : , + "isWritablePrimary" : , "secondary" : , "primary" : , "me" : , @@ -2343,7 +2360,7 @@ repl argument, or :setting:`~replication.replSetName` value in the configuration file. -.. serverstatus:: repl.ismaster +.. serverstatus:: repl.isWritablePrimary A boolean that indicates whether the current node is the :term:`primary` of the replica set. diff --git a/source/reference/method.txt b/source/reference/method.txt index 2f43ac8c27b..bb25d134ecf 100644 --- a/source/reference/method.txt +++ b/source/reference/method.txt @@ -489,6 +489,10 @@ Database - Provides access to the specified database. + * - :method:`db.hello()` + + - Returns a document that reports the state of the replica set. + * - :method:`db.help()` - Displays descriptions of common ``db`` object methods. @@ -497,10 +501,6 @@ Database - Returns a document with information about the system MongoDB runs on. Wraps :dbcommand:`hostInfo` - * - :method:`db.isMaster()` - - - Returns a document that reports the state of the replica set. - * - :method:`db.killOp()` - Terminates a specified operation. diff --git a/source/reference/method/db.auth.txt b/source/reference/method/db.auth.txt index abb05102142..aeef279d349 100644 --- a/source/reference/method/db.auth.txt +++ b/source/reference/method/db.auth.txt @@ -147,16 +147,14 @@ The :method:`db.auth()` has the following syntax forms: - string - Optional. The :ref:`authentication mechanism - ` to use. - + ` to use. + For available mechanisms, see :ref:`authentication mechanisms - `. - - If unspecified, uses the :dbcommand:`isMaster` to determine the SASL - mechanism or mechanisms for the specified user. See - :data:`~isMaster.saslSupportedMechs`. - - + `. + + If unspecified, uses the :dbcommand:`hello` command to determine + the SASL mechanism or mechanisms for the specified user. See + :data:`~hello.saslSupportedMechs`. * - ``digestPassword`` diff --git a/source/reference/method/db.isMaster.txt b/source/reference/method/db.hello.txt similarity index 58% rename from source/reference/method/db.isMaster.txt rename to source/reference/method/db.hello.txt index e1ce9178135..9b5aaf817c7 100644 --- a/source/reference/method/db.isMaster.txt +++ b/source/reference/method/db.hello.txt @@ -1,6 +1,6 @@ -============= -db.isMaster() -============= +========== +db.hello() +========== .. default-domain:: mongodb @@ -10,17 +10,19 @@ db.isMaster() :depth: 1 :class: singlecol -.. method:: db.isMaster() +.. method:: db.hello() + + .. versionadded:: 5.0 (and 4.4.2, 4.2.10, 4.0.21, and 3.6.21) Returns a document that describes the role of the :binary:`~bin.mongod` instance. If the :binary:`~bin.mongod` is a member of a :term:`replica set`, then - the :data:`~isMaster.ismaster` and :data:`~isMaster.secondary` + the :data:`~hello.isWritablePrimary` and :data:`~hello.secondary` fields report if the instance is the :term:`primary` or if it is a :term:`secondary` member of the replica set. .. see:: - :dbcommand:`isMaster` for the complete documentation of - the output of :method:`db.isMaster()`. + :dbcommand:`hello` for the complete documentation of + the output of :method:`db.hello()`. diff --git a/source/reference/method/js-database.txt b/source/reference/method/js-database.txt index e22189144dc..8e24356e4f1 100644 --- a/source/reference/method/js-database.txt +++ b/source/reference/method/js-database.txt @@ -116,6 +116,10 @@ Database Methods - Provides access to the specified database. + * - :method:`db.hello()` + + - Returns a document that reports the state of the replica set. + * - :method:`db.help()` - Displays descriptions of common ``db`` object methods. @@ -124,10 +128,6 @@ Database Methods - Returns a document with information about the system MongoDB runs on. Wraps :dbcommand:`hostInfo` - * - :method:`db.isMaster()` - - - Returns a document that reports the state of the replica set. - * - :method:`db.killOp()` - Terminates a specified operation. @@ -238,9 +238,9 @@ Database Methods /reference/method/db.getProfilingStatus /reference/method/db.getReplicationInfo /reference/method/db.getSiblingDB + /reference/method/db.hello /reference/method/db.help /reference/method/db.hostInfo - /reference/method/db.isMaster /reference/method/db.killOp /reference/method/db.listCommands /reference/method/db.logout diff --git a/source/reference/mongodb-wire-protocol.txt b/source/reference/mongodb-wire-protocol.txt index 6738cd8e70b..a3cff069fc8 100644 --- a/source/reference/mongodb-wire-protocol.txt +++ b/source/reference/mongodb-wire-protocol.txt @@ -121,7 +121,8 @@ Request Opcodes ~~~~~~~~~~~~~~~ .. note:: - Starting with MongoDB 2.6 and :data:`~isMaster.maxWireVersion` ``3``, + + Starting with MongoDB 2.6 and :data:`~hello.maxWireVersion` ``3``, MongoDB drivers use the :ref:`database commands` :dbcommand:`insert`, :dbcommand:`update`, and :dbcommand:`delete` instead of ``OP_INSERT``, ``OP_UPDATE``, and ``OP_DELETE`` for diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index ba77d6cfdf0..5ea1619cd34 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -317,7 +317,7 @@ Replica Set Configuration Fields When this value is ``true``, the replica set hides this instance and does not include the member in the output of - :method:`db.isMaster()` or :dbcommand:`isMaster`. This prevents + :method:`db.hello()` or :dbcommand:`hello`. This prevents read operations (i.e. queries) from ever reaching this host by way of secondary :term:`read preference`. diff --git a/source/reference/replication.txt b/source/reference/replication.txt index c2c4f1d685e..be2cb765e60 100644 --- a/source/reference/replication.txt +++ b/source/reference/replication.txt @@ -99,9 +99,10 @@ Replication Database Commands - Internal command that applies :term:`oplog` entries to the current data set. - * - :dbcommand:`isMaster` + * - :dbcommand:`hello` - - Displays information about this member's role in the replica set, including whether it is the master. + - Displays information about this member's role in the replica set, + including whether it is the primary. * - :dbcommand:`replSetAbortPrimaryCatchUp` diff --git a/source/reference/security-client-side-query-aggregation-support.txt b/source/reference/security-client-side-query-aggregation-support.txt index fb8f5485c30..c784d5db174 100644 --- a/source/reference/security-client-side-query-aggregation-support.txt +++ b/source/reference/security-client-side-query-aggregation-support.txt @@ -71,8 +71,8 @@ field level encryption pass these commands directly to the - :dbcommand:`getMore` [#]_ - :dbcommand:`authenticate` - :dbcommand:`getnonce` +- :dbcommand:`hello` - :dbcommand:`logout` -- :dbcommand:`isMaster` - :dbcommand:`abortTransaction` - :dbcommand:`commitTransaction` - :dbcommand:`endSessions` diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index e17d5aa9130..0b086eaae26 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -147,6 +147,16 @@ Removed Commands Replica Sets ------------ +``hello`` Command +~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 5.0 (and 4.4.2, 4.2.10, 4.0.21, and 3.6.21), the +:dbcommand:`hello` command and the :method:`db.hello()` method were +introduced as replacements for the ``isMaster`` command +and the ``db.isMaster()`` method. The new topology metric +:serverstatus:`connections.exhaustHello` tracks this in +:serverstatus:`connections`. + Quiesce Period ~~~~~~~~~~~~~~ diff --git a/source/tutorial/configure-a-hidden-replica-set-member.txt b/source/tutorial/configure-a-hidden-replica-set-member.txt index 7a8e941ca63..04d26864c8a 100644 --- a/source/tutorial/configure-a-hidden-replica-set-member.txt +++ b/source/tutorial/configure-a-hidden-replica-set-member.txt @@ -68,7 +68,7 @@ to configure by its array index in the After re-configuring the set, this secondary member has a priority of ``0`` so that it cannot become primary and is hidden. The other members in the set will not advertise the hidden member in the -:dbcommand:`isMaster` or :method:`db.isMaster()` output. +:dbcommand:`hello` command or :method:`db.hello()` method output. .. include:: /includes/fact-rs-conf-array-index.rst diff --git a/source/tutorial/expand-replica-set.txt b/source/tutorial/expand-replica-set.txt index dbe91072b5f..02f227547d9 100644 --- a/source/tutorial/expand-replica-set.txt +++ b/source/tutorial/expand-replica-set.txt @@ -151,7 +151,7 @@ Add a Member to an Existing Replica Set You can only add members while connected to the primary. If you do not know which member is the primary, log into any member of the - replica set and issue the :method:`db.isMaster()` command. + replica set and issue the :method:`db.hello()` command. #. Use :method:`rs.add()` to add the new member to the replica set. Pass the :rsconf:`member configuration document ` to the diff --git a/source/tutorial/remove-replica-set-member.txt b/source/tutorial/remove-replica-set-member.txt index 689c5cd0495..b4b5d8484ee 100644 --- a/source/tutorial/remove-replica-set-member.txt +++ b/source/tutorial/remove-replica-set-member.txt @@ -22,7 +22,7 @@ Remove a Member Using ``rs.remove()`` method. #. Connect to the replica set's current :term:`primary`. To determine - the current primary, use :method:`db.isMaster()` while connected to + the current primary, use :method:`db.hello()` while connected to any member of the replica set. #. Use :method:`rs.remove()` in either of the following forms to @@ -64,7 +64,7 @@ Procedure method. #. Connect to the replica set's current :term:`primary`. To determine - the current primary, use :method:`db.isMaster()` while connected to + the current primary, use :method:`db.hello()` while connected to any member of the replica set. #. Issue the :method:`rs.conf()` method to view the current diff --git a/source/tutorial/restore-sharded-cluster.txt b/source/tutorial/restore-sharded-cluster.txt index 01bfa86dcb0..d47bd6ccb31 100644 --- a/source/tutorial/restore-sharded-cluster.txt +++ b/source/tutorial/restore-sharded-cluster.txt @@ -91,24 +91,24 @@ Shut Down Running MongoDB Processes For hosts running a :binary:`mongod `, connect a :binary:`mongo ` shell to the ``mongod`` and - run :method:`db.isMaster()`: + run :method:`db.hello()`: - * If :data:`~isMaster.ismaster` is false, the ``mongod`` is a - :term:`secondary` member of a replica set. You + * If :data:`~hello.isWritablePrimary` is false, the ``mongod`` is a + :term:`secondary` member of a replica set. You can shut it down by running :method:`db.shutdownServer()` from the ``admin`` database. - * If :data:`~isMaster.ismaster` is true, the ``mongod`` is the + * If :data:`~hello.isWritablePrimary` is true, the ``mongod`` is the :term:`primary` member of a replica set. Shut down the secondary members of the replica set *first*. Use :method:`rs.status()` to identify the other members of the replica set. - The primary automatically steps down after it detects a + The primary automatically steps down after it detects a majority of members are offline. After it steps down - (:method:`db.isMaster` returns - :data:`ismaster: false `), you can safely - shut down the ``mongod`` + (:method:`db.hello` returns + :data:`isWritablePrimary: false `), you can + safely shut down the ``mongod``. Prepare Data Directory Create a directory on the target host for the restored database diff --git a/source/tutorial/use-database-commands.txt b/source/tutorial/use-database-commands.txt index 04d63a9526c..d263e4b8749 100644 --- a/source/tutorial/use-database-commands.txt +++ b/source/tutorial/use-database-commands.txt @@ -25,12 +25,12 @@ Database Command Form You specify a command first by constructing a standard :term:`BSON` document whose first key is the name of the command. For example, -specify the :dbcommand:`isMaster` command using the following +specify the :dbcommand:`hello` command using the following :term:`BSON` document: .. code-block:: javascript - { isMaster: 1 } + { hello: 1 } .. _issue-commands: @@ -43,7 +43,7 @@ commands called :method:`db.runCommand()`. The following operation in .. code-block:: javascript - db.runCommand( { isMaster: 1 } ) + db.runCommand( { hello: 1 } ) Many :driver:`Drivers ` provide an equivalent for the :method:`db.runCommand()` method. Internally, running commands @@ -52,7 +52,7 @@ against the :term:`$cmd` collection. Many common commands have their own shell helpers or wrappers in the :binary:`~bin.mongo` shell and drivers, such as the -:method:`db.isMaster()` method in the :binary:`~bin.mongo` JavaScript +:method:`db.hello()` method in the :binary:`~bin.mongo` JavaScript shell. You can use the ``maxTimeMS`` option to specify a time limit for the