From 7818524f60ed8676c8a6fa8f538e551f4f21f154 Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 4 Sep 2018 17:42:27 -0400 Subject: [PATCH 1/2] DOCS-11977,DOCSP-3353: 4.0.3 disable majority read concern for PSA architecture --- source/changeStreams.txt | 5 ++ .../fact-enable-majority-readConcern.rst | 4 ++ source/includes/options-conf.yaml | 11 ++--- source/includes/options-mongod.yaml | 28 +++++++++-- .../steps-change-replica-set-wiredtiger.yaml | 33 +++++++++++-- source/reference/configuration-options.txt | 2 +- source/reference/method/Mongo.watch.txt | 6 +++ .../reference/method/db.collection.watch.txt | 5 ++ source/reference/method/db.watch.txt | 6 +++ source/reference/read-concern-majority.txt | 37 ++++++++++++++ .../change-replica-set-wiredtiger.txt | 48 +++++++++++++++++-- .../change-sharded-cluster-wiredtiger.txt | 37 ++++++++++++++ source/tutorial/upgrade-revision.txt | 13 +++++ 13 files changed, 215 insertions(+), 20 deletions(-) diff --git a/source/changeStreams.txt b/source/changeStreams.txt index b0b94fe7de6..2eb4f9f2cf9 100644 --- a/source/changeStreams.txt +++ b/source/changeStreams.txt @@ -101,6 +101,11 @@ You can open change streams against: .. _open-change-stream: +.. important:: + + Change stream is only available if :readconcern:`"majority"` read + concern support is enabled (default). + Open A Change Stream -------------------- diff --git a/source/includes/fact-enable-majority-readConcern.rst b/source/includes/fact-enable-majority-readConcern.rst index 9a4174a15ac..96e50ba0444 100644 --- a/source/includes/fact-enable-majority-readConcern.rst +++ b/source/includes/fact-enable-majority-readConcern.rst @@ -1,2 +1,6 @@ To use :term:`read concern` level of :readconcern:`"majority"`, replica sets must use :ref:`WiredTiger storage engine `. + +For MongoDB 4.0.3+ (and 3.6.1+), you can disable read concern +:readconcern:`"majority"`. For more information, see +:ref:`4.0-disable-read-concern-majority`. diff --git a/source/includes/options-conf.yaml b/source/includes/options-conf.yaml index 3976553db91..9e28bcaa752 100644 --- a/source/includes/options-conf.yaml +++ b/source/includes/options-conf.yaml @@ -1900,13 +1900,10 @@ replacement: program: conf name: replication.enableMajorityReadConcern directive: setting -description: | - - .. deprecated:: 3.6 - - Starting in MongoDB 3.6, :readconcern:`"majority"` read concern - is always enabled, and this setting has no effect. - +inherit: + name: enableMajorityReadConcern + program: mongod + file: options-mongod.yaml --- program: conf name: sharding.configsvrMode diff --git a/source/includes/options-mongod.yaml b/source/includes/options-mongod.yaml index ac5f3e07c81..d5228e58d0d 100644 --- a/source/includes/options-mongod.yaml +++ b/source/includes/options-mongod.yaml @@ -2203,13 +2203,33 @@ program: mongod name: enableMajorityReadConcern directive: option optional: true -args: null +default: true description: | - .. deprecated:: 3.6 + Starting in MongoDB 3.6, MongoDB enables support for + :readconcern:`"majority"` read concern by default. + + For MongoDB 4.0.3+ and 3.6.1+, you can disable read concern + :readconcern:`"majority"` to prevent the storage cache pressure from + immobilizing a deployment with a three-member + primary-secondary-arbiter (PSA) architecture. For more information + about disabling read concern :readconcern:`"majority"`, see + :ref:`4.0-disable-read-concern-majority`. + + To disable, set {{role}} to false. + + .. important:: + + In general, avoid disabling :readconcern:`"majority"` read concern + unless necessary. However, if you have a three-member replica set + with a primary-secondary-arbiter (PSA) architecture or a sharded + cluster with a three-member PSA shards, disable to prevent the + storage cache pressure from immobilizing the deployment. + + Disabling :readconcern:`"majority"` read concern disables support + for :doc:`/changeStreams`. - Starting in MongoDB 3.6, :readconcern:`"majority"` read concern - is always enabled, and this option has no effect. + {{role}} has no effect for MongoDB versions: 4.0.0, 4.0.1, 4.0.2, 3.6.0. --- program: mongod diff --git a/source/includes/steps-change-replica-set-wiredtiger.yaml b/source/includes/steps-change-replica-set-wiredtiger.yaml index 61ed946e2cb..5bc26172906 100644 --- a/source/includes/steps-change-replica-set-wiredtiger.yaml +++ b/source/includes/steps-change-replica-set-wiredtiger.yaml @@ -5,6 +5,7 @@ pre: | action: language: sh code: | + use admin db.shutdownServer() --- title: "Prepare a data directory for the new ``mongod`` running with WiredTiger." @@ -21,7 +22,7 @@ pre: | --- title: "Start ``mongod`` with WiredTiger." ref: change-wt-repl-sync-start-mongod-w-wiredtiger -pre: | +content: | Start :binary:`~bin.mongod`, specifying ``wiredTiger`` as the :option:`--storageEngine ` and the prepared data directory for WiredTiger as the :option:`--dbpath `. Specify additional options, @@ -29,11 +30,33 @@ pre: | member. .. include:: /includes/warning-bind-ip-security-considerations.rst + + .. tabs:: + + tabs: + - id: general + name: General Use (For Most Architectures) + content: | + .. code-block:: sh + + mongod --storageEngine wiredTiger --dbpath --replSet --bind_ip localhost, + + + - id: psa36 + name: PSA Architecture + content: | + + .. important:: + + If you are running a three-member PSA architecture and + MongoDB version 4.0.3+, include + :option:`--enableMajorityReadConcern false ` to disable read concern ``majority``. |seemore| + + .. code-block:: sh + + mongod --storageEngine wiredTiger --dbpath --replSet --bind_ip localhost, --enableMajorityReadConcern false -action: - language: sh - code: | - mongod --storageEngine wiredTiger --dbpath --replSet --bind_ip localhost, post: | Since no data exists in the ``--dbpath``, the ``mongod`` will perform an :doc:`initial sync `. The length of the diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt index ab91823f024..6ac18bcd0b5 100644 --- a/source/reference/configuration-options.txt +++ b/source/reference/configuration-options.txt @@ -724,7 +724,7 @@ LDAP Parameters oplogSizeMB: replSetName: secondaryIndexPrefetch: - enableMajorityReadConcern: ## Deprecated in 3.6 + enableMajorityReadConcern: .. include:: /includes/option/setting-conf-replication.oplogSizeMB.rst diff --git a/source/reference/method/Mongo.watch.txt b/source/reference/method/Mongo.watch.txt index b5938695ac8..d9c69aa4bf7 100644 --- a/source/reference/method/Mongo.watch.txt +++ b/source/reference/method/Mongo.watch.txt @@ -73,6 +73,12 @@ Full Document Lookup of Update Operations .. include:: /includes/extracts/changestream-full-document-lookup.rst +Availability +~~~~~~~~~~~~ + +Change stream is only available if :readconcern:`"majority"` read +concern support is enabled (default). + Access Control -------------- diff --git a/source/reference/method/db.collection.watch.txt b/source/reference/method/db.collection.watch.txt index 1634ca46f4c..ad4ce5068d8 100644 --- a/source/reference/method/db.collection.watch.txt +++ b/source/reference/method/db.collection.watch.txt @@ -52,6 +52,11 @@ Behavior - For a sharded cluster, you must issue :method:`db.watch()` on a :binary:`~bin.mongos` instance. +Availability +~~~~~~~~~~~~ + +Change stream is only available if :readconcern:`"majority"` read +concern support is enabled (default). Resumability ~~~~~~~~~~~~ diff --git a/source/reference/method/db.watch.txt b/source/reference/method/db.watch.txt index 6a9f386a296..255a0a7b78d 100644 --- a/source/reference/method/db.watch.txt +++ b/source/reference/method/db.watch.txt @@ -79,6 +79,12 @@ Full Document Lookup of Update Operations .. include:: /includes/extracts/changestream-full-document-lookup.rst +Availability +~~~~~~~~~~~~ + +Change stream is only available if :readconcern:`"majority"` read +concern support is enabled (default). + Access Control -------------- diff --git a/source/reference/read-concern-majority.txt b/source/reference/read-concern-majority.txt index 4436354c165..0207f701a19 100644 --- a/source/reference/read-concern-majority.txt +++ b/source/reference/read-concern-majority.txt @@ -122,4 +122,41 @@ Read Your Own Writes .. include:: /includes/fact-read-own-writes.rst +.. _4.0-disable-read-concern-majority: +Disable Read Concern Majority +----------------------------- + +*For 3-Member Primary-Secondary-Arbiter Architecture* + +For MongoDB 4.0.3+ (and 3.6.1+ [#]_), you can disable read concern +:readconcern:`"majority"` if you have a three-member replica set with a +primary-secondary-arbiter (PSA) architecture or a sharded cluster with +a three-member PSA shards. + +With a three-member PSA architecture, the cache pressure will increase +if any data bearing node is down. To prevent the storage cache pressure +from immobilizing a deployment with a PSA architecture, you can disable +read concern by setting either: + +- :option:`--enableMajorityReadConcern ` command line option to ``false``. + +- :setting:`replication.enableMajorityReadConcern` configuration file + setting to ``false``. + +.. important:: + + In general, avoid disabling :readconcern:`"majority"` read concern + unless necessary. However, if you have a three-member replica set + with a primary-secondary-arbiter (PSA) architecture or a sharded + cluster with a three-member PSA shards, disable to prevent the + storage cache pressure from immobilizing the deployment. + + Disabling :readconcern:`"majority"` read concern disables support + for :doc:`/changeStreams`. + +.. [#] + + For MongoDB 3.6 discussion, see :v3.6:`Disable Read Concern Majority + `. diff --git a/source/tutorial/change-replica-set-wiredtiger.txt b/source/tutorial/change-replica-set-wiredtiger.txt index b96ee893c92..ec334aa4f7b 100644 --- a/source/tutorial/change-replica-set-wiredtiger.txt +++ b/source/tutorial/change-replica-set-wiredtiger.txt @@ -17,6 +17,38 @@ Change Replica Set to WiredTiger Considerations -------------- +Replica sets can have members with different storage engines. As such, +you can update members to use the WiredTiger storage engine in a +rolling fashion. + +.. _rs-mmapv1-wt-4.0-psa: + +PSA 3-member Architecture +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 3.6, :readconcern:`"majority"` read concern, +available for WiredTiger, is enabled by default. However, for MongoDB +4.0.3+, if you have a three-member replica set with a +primary-secondary-arbiter (PSA) architecture, you can disable +:readconcern:`"majority"` read concern. Disabling +:readconcern:`"majority"` for a three member PSA architecture avoids +possible cache-pressure build up. + +The procedure below disables :readconcern:`"majority"` read concern for +MongoDB 4.0.3 PSA architecture by including +:option:`--enableMajorityReadConcern false `. If you are running a MongoDB 4.0.1 or +4.0.2 PSA architecture, first upgrade to the latest 4.0 version in +order to disable this read concern. + +.. note:: + + Disabling :readconcern:`"majority"` read concern disables support + for :doc:`/changeStreams`. + +For more information on PSA architecture and read concern +:readconcern:`"majority"`, see :ref:`4.0-disable-read-concern-majority`. + MongoDB 3.0 or Greater ~~~~~~~~~~~~~~~~~~~~~~ @@ -45,6 +77,7 @@ The following procedure updates the replica set in a rolling fashion. The procedure updates the :term:`secondary` members first, then steps down the :term:`primary`, and updates the stepped-down member. + To update a member to WiredTiger, the procedure removes a member's data, starts :binary:`~bin.mongod` with WiredTiger, and performs an :doc:`initial sync `. @@ -53,9 +86,10 @@ data, starts :binary:`~bin.mongod` with WiredTiger, and performs an A. Update the secondary members to WiredTiger. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Update the secondary members one at a time: -.. container:: admonition +.. container:: .. include:: /includes/steps/change-replica-set-wiredtiger.rst @@ -65,6 +99,12 @@ at a time. B. Step down the primary. ~~~~~~~~~~~~~~~~~~~~~~~~~ +.. important:: + + If updating all members of the replica set to use WiredTiger, ensure + that all secondary members have been updated first before updating + the primary. + Once all the secondary members have been upgraded to WiredTiger, connect a :binary:`~bin.mongo` shell to the primary and use :method:`rs.stepDown()` to step down the primary and force an election @@ -76,8 +116,8 @@ of a new primary. rs.stepDown() -C. Update the old primary. -~~~~~~~~~~~~~~~~~~~~~~~~~~ +C. Update the stepped down primary. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When the primary has stepped down and become a secondary, update the secondary to use WiredTiger as before: @@ -86,3 +126,5 @@ secondary to use WiredTiger as before: .. include:: /includes/steps/change-replica-set-wiredtiger.rst + +.. |seemore| replace:: See :ref:`rs-mmapv1-wt-4.0-psa`. diff --git a/source/tutorial/change-sharded-cluster-wiredtiger.txt b/source/tutorial/change-sharded-cluster-wiredtiger.txt index b46af8d83b3..a24cc6f1979 100644 --- a/source/tutorial/change-sharded-cluster-wiredtiger.txt +++ b/source/tutorial/change-sharded-cluster-wiredtiger.txt @@ -35,6 +35,41 @@ Downtime If you change the host or port of any :term:`shard`, you must update the shard configuration as well. +.. _sharded-cluster-mmapv1-wt-4.0-psa: + +PSA 3-member Architecture +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 3.6, :readconcern:`"majority"` read concern, +available for WiredTiger, is enabled by default. However, for MongoDB +4.0.3+, if you have a three-member shard replica set with a +primary-secondary-arbiter (PSA) architecture, you can disable +:readconcern:`"majority"` read concern for that shard replica set. +Disabling :readconcern:`"majority"` for a three member PSA architecture +avoids possible cache-pressure build up. + +The procedure below disables :readconcern:`"majority"` read concern for +MongoDB 4.0.3 PSA architecture by including +:option:`--enableMajorityReadConcern false `. If you are running a MongoDB 4.0.1 or +4.0.2 PSA architecture, first upgrade to the latest 4.0 version in +order to disable this read concern. + +.. note:: + + Disabling :readconcern:`"majority"` read concern disables support + for :doc:`/changeStreams`. + +For more information on PSA architecture and read concern +:readconcern:`"majority"`, see :ref:`4.0-disable-read-concern-majority`. + +MongoDB 3.0 or Greater +~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: admonition + + .. include:: /includes/fact-wiredtiger-minimum-version.rst + Default Bind to Localhost ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -98,5 +133,7 @@ secondary to use WiredTiger as before: .. include:: /includes/steps/change-replica-set-wiredtiger.rst + Repeat the procedure for the other shards. +.. |seemore| replace:: See :ref:`sharded-cluster-mmapv1-wt-4.0-psa`. diff --git a/source/tutorial/upgrade-revision.txt b/source/tutorial/upgrade-revision.txt index 969f77e8bf5..6e5396107b4 100644 --- a/source/tutorial/upgrade-revision.txt +++ b/source/tutorial/upgrade-revision.txt @@ -43,6 +43,19 @@ Before Upgrading production environment, to ensure that your production configuration is compatible with all changes. +.. note:: + + Starting in MongoDB 3.6, MongoDB enables support for + :readconcern:`"majority"` read concern by default. + + For MongoDB 3.6.1+ and 4.0.3+, you can disable read concern + :readconcern:`"majority"` to prevent the storage cache pressure from + immobilizing a deployment with a primary-secondary-arbiter (PSA) + architecture. Disabling :readconcern:`"majority"` read concern also + disables support for :doc:`/changeStreams` + + For more information, see :ref:`4.0-disable-read-concern-majority`. + .. _upgrade-procedure: Upgrade Procedure From a0202977de856a1808071c398d42e5f023a78858 Mon Sep 17 00:00:00 2001 From: kay Date: Fri, 28 Sep 2018 14:37:03 -0400 Subject: [PATCH 2/2] ODCS-12081: blurb about txns and disabling majority read concern --- source/core/transactions.txt | 17 +++++++++++++-- source/includes/extracts-transactions.yaml | 24 ++++++++++++++-------- source/includes/options-mongod.yaml | 5 +++++ source/reference/read-concern-local.txt | 2 ++ source/reference/read-concern-majority.txt | 8 +++++++- 5 files changed, 44 insertions(+), 12 deletions(-) diff --git a/source/core/transactions.txt b/source/core/transactions.txt index b14c86dcc83..d8d4f9e4582 100644 --- a/source/core/transactions.txt +++ b/source/core/transactions.txt @@ -280,17 +280,20 @@ Read Concern Multi-document transactions support read concern :readconcern:`"snapshot"`, :readconcern:`"local"`, and -:readconcern:`"majority"`: +:readconcern:`"majority"` : - For :readconcern:`"local"` and :readconcern:`"majority"` read concern, MongoDB may sometimes substitute a stronger read concern. + Specifically, in MongoDB 4.0, all multi-documents transactions have + "snapshot" isolation. For details, see :ref:`readconcern-local-txn` + and :ref:`readconcern-majority-txn`. - For :readconcern:`"majority"` read concern, if the transaction commits with :ref:`write concern "majority" `, transaction operations are guaranteed to have read majority-committed data. Otherwise, the :readconcern:`"majority"` read concern provides no guarantees that - read operations read majority-committed data. + read operations read majority-committed data. [#psa]_ - For :readconcern:`"snapshot"` read concern, if the transaction commits with :ref:`write concern "majority" @@ -314,6 +317,16 @@ If unspecified at the transaction start, transactions use the session-level read concern or, if that is unset, the client-level read concern. +.. [#psa] + + For a three-member Primary-Secondary-Arbiter (PSA) replica set + architecture, you may have :ref:`disabled read concern "majority" + <4.0-disable-read-concern-majority>` to avoid cache pressure. + Disabling :readconcern:`"majority"` does not affect transactions; + i.e. you can specify read concern :readconcern:`"majority"` for + transactions even if read concern :readconcern:`"majority"` is + disabled. + .. _transactions-write-concern: Write Concern diff --git a/source/includes/extracts-transactions.yaml b/source/includes/extracts-transactions.yaml index ae123721123..e274010d1d3 100644 --- a/source/includes/extracts-transactions.yaml +++ b/source/includes/extracts-transactions.yaml @@ -141,13 +141,19 @@ content: | --- ref: transactions-read-concern-tip content: | - In MongoDB 4.0, all multi-documents transactions have ``snapshot`` isolation. In - future versions of MongoDB, the server will optimize around your specified read - concern (isolation level). - - For :readconcern:`"local"` and :readconcern:`"majority"` read concern, MongoDB - may provide stronger isolation guarantees than specified. If stronger guarantees - are needed, be explicit as future versions of the server may include - optimizations that remove stronger isolation guarantees than explicitly - specified. + + For :readconcern:`"local"` and :readconcern:`"majority"` read + concern, MongoDB may provide stronger isolation guarantees than + specified. Specifically, in MongoDB 4.0, all multi-documents + transactions have :readconcern:`"snapshot"` isolation. + + In future versions of MongoDB, the server will optimize around the + specified read concern (isolation level) instead of providing + stronger isolation guarantees than explicitly specified. + + As such, if stronger guarantees than :readconcern:`"local"` and + :readconcern:`"majority"` read concern are needed, explicitly + specify the appropriate read concern instead of relying on MongoDB + to promote the read concern level. + ... diff --git a/source/includes/options-mongod.yaml b/source/includes/options-mongod.yaml index d5228e58d0d..2c61cda0b7a 100644 --- a/source/includes/options-mongod.yaml +++ b/source/includes/options-mongod.yaml @@ -2229,6 +2229,11 @@ description: | Disabling :readconcern:`"majority"` read concern disables support for :doc:`/changeStreams`. + Disabling :readconcern:`"majority"` does not affect + :doc:`multi-document transactions `; i.e. you + can specify read concern "majority" for multi-document + transactions even if read concern "majority" is disabled. + {{role}} has no effect for MongoDB versions: 4.0.0, 4.0.1, 4.0.2, 3.6.0. --- diff --git a/source/reference/read-concern-local.txt b/source/reference/read-concern-local.txt index 27dcaac10be..68045383816 100644 --- a/source/reference/read-concern-local.txt +++ b/source/reference/read-concern-local.txt @@ -32,6 +32,8 @@ Causally Consistent Sessions Read concern :readconcern:`local` is available for use with causally consistent sessions. +.. _readconcern-local-txn: + Read Concern ``"local"`` and Transactions ----------------------------------------- diff --git a/source/reference/read-concern-majority.txt b/source/reference/read-concern-majority.txt index 0207f701a19..4d7028f3975 100644 --- a/source/reference/read-concern-majority.txt +++ b/source/reference/read-concern-majority.txt @@ -31,7 +31,6 @@ data read in transactions. .. include:: /includes/fact-readConcern-most-recent-data-in-node.rst - Example ------- @@ -96,6 +95,8 @@ Causally Consistent Sessions Read concern :readconcern:`majority` is available for use with causally consistent sessions. +.. _readconcern-majority-txn: + Read Concern ``"majority"`` and Transactions -------------------------------------------- @@ -156,6 +157,11 @@ read concern by setting either: Disabling :readconcern:`"majority"` read concern disables support for :doc:`/changeStreams`. + Disabling :readconcern:`"majority"` does not affect + :doc:`multi-document transactions `; i.e. you + can specify read concern :readconcern:`"majority"` for transactions + even if read concern :readconcern:`"majority"` is disabled. + .. [#] For MongoDB 3.6 discussion, see :v3.6:`Disable Read Concern Majority