From 09a7dc6916ac4758e0273474702fc7d5ccfac4d0 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Wed, 24 Jan 2018 21:44:21 +0000 Subject: [PATCH] Update docs for read concern levels in MongoDB 3.6 Level descriptions are copied from the MongoDB manual. https://jira.mongodb.org/browse/PHPC-1078 git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@343866 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../mongodb/mongodb/driver/readconcern.xml | 117 +++++++++++++++--- .../mongodb/driver/readconcern/construct.xml | 45 +------ 2 files changed, 105 insertions(+), 57 deletions(-) diff --git a/reference/mongodb/mongodb/driver/readconcern.xml b/reference/mongodb/mongodb/driver/readconcern.xml index 3cb1dd29cf..106ed84d25 100644 --- a/reference/mongodb/mongodb/driver/readconcern.xml +++ b/reference/mongodb/mongodb/driver/readconcern.xml @@ -14,7 +14,7 @@ MongoDB\Driver\ReadConcern controls the level of isolation for read operations for replica sets and replica set shards. This - option requires the WiredTiger storage engine and MongoDB 3.2 or later. + option requires MongoDB 3.2 or later. @@ -39,6 +39,12 @@ Constants + + const + string + MongoDB\Driver\ReadConcern::AVAILABLE + "available" + const string @@ -70,17 +76,75 @@ &reftitle.constants; + + MongoDB\Driver\ReadConcern::AVAILABLE + + + Default for reads against secondaries when + afterClusterTimeand level are + unspecified. + + + The query returns the instance's most recent data. Provides no + guarantee that the data has been written to a majority of the replica set + members (i.e. may be rolled back). + + + For unsharded collections (including collections in a standalone + deployment or a replica set deployment), "local" and + "available" read concerns behave identically. + + + For a sharded cluster, "available" read concern + provides greater tolerance for partitions since it does not wait to + ensure consistency guarantees. However, a query with + "available" read concern may return orphan documents + if the shard is undergoing chunk migrations since the + "available" read concern, unlike + "local" read concern, does not contact the + shard's primary nor the config servers for updated metadata. + + + + MongoDB\Driver\ReadConcern::LINEARIZABLE - A linearizable read avoids returning reads from a - stale primary (one that has already been superseded - by a new primary but doesn't know it yet). It is important to note - that this read concern level does not by itself produce linearizable - reads; they must be issued in conjunction with - MongoDB\Driver\WriteConcern::MAJORITY writes to the - same document(s) in order to be linearizable. + The query returns data that reflects all successful writes issued with a + write concern of "majority" and + acknowledged prior to the start of the read operation. For replica sets + that run with writeConcernMajorityJournalDefault set + to &true;, linearizable read concern returns data that will never be + rolled back. + + + With writeConcernMajorityJournalDefault set to + &false;, MongoDB will not wait for w: "majority" + writes to be durable before acknowledging the writes. As such, + "majority" write operations could possibly roll back + in the event of a loss of a replica set member. + + + You can specify linearizable read concern for read operations on the + primary only. + + + Linearizable read concern guarantees only apply if read + operations specify a query filter that uniquely identifies a single + document. + + + + Always use maxTimeMS with linearizable read concern + in case a majority of data bearing members are unavailable. + maxTimeMS ensures that the operation does not block + indefinitely and instead ensures that the operation returns an error if + the read concern cannot be fulfilled. + + + + Linearizable read concern requires MongoDB 3.4. @@ -89,10 +153,14 @@ MongoDB\Driver\ReadConcern::LOCAL - Queries using this read concern will return the node's most recent - copy of the data. This provides no guarantee that the data has been - written to a majority of the nodes (i.e. it may be rolled back). This is - the default read concern for MongoDB. + Default for reads against primary if level is + unspecified and for reads against secondaries if level + is unspecified but afterClusterTime is specified. + + + The query returns the instance's most recent data. Provides no + guarantee that the data has been written to a majority of the replica set + members (i.e. may be rolled back). @@ -101,9 +169,12 @@ MongoDB\Driver\ReadConcern::MAJORITY - Queries using this read concern will return the node's most recent - copy of the data confirmed as having been written to a majority of the - nodes (i.e. the data cannot be rolled back). + The query returns the instance's most recent data acknowledged as + having been written to a majority of members in the replica set. + + + To use read concern level of "majority", replica sets + must use WiredTiger storage engine and election protocol version 1. @@ -124,6 +195,15 @@ + + 1.4.0 + + + Added the MongoDB\Driver\ReadConcern::AVAILABLE + constant. + + + 1.2.0 @@ -143,6 +223,13 @@ +
+ &reftitle.seealso; + + Read Concern reference + +
+ &reference.mongodb.mongodb.driver.entities.readconcern; diff --git a/reference/mongodb/mongodb/driver/readconcern/construct.xml b/reference/mongodb/mongodb/driver/readconcern/construct.xml index 652e9c09f3..6d53dcd2eb 100644 --- a/reference/mongodb/mongodb/driver/readconcern/construct.xml +++ b/reference/mongodb/mongodb/driver/readconcern/construct.xml @@ -25,48 +25,9 @@ level - - Read concern - - - - Value - Description - - - - - MongoDB\Driver\ReadConcern::LINEARIZABLE - - A linearizable read avoids returning reads from a - stale primary (one that has already been - superseded by a new primary but doesn't know it yet). It is - important to note that this read concern level does not by itself - produce linearizable reads; they must be issued in conjunction with - MongoDB\Driver\WriteConcern::MAJORITY writes to - the same document(s) in order to be linearizable. - - - - MongoDB\Driver\ReadConcern::LOCAL - - Queries using this read concern will return the node's most - recent copy of the data. This provides no guarantee that the data has - been written to a majority of the nodes (i.e. it may be rolled back). - This is the default read concern for MongoDB. - - - - MongoDB\Driver\ReadConcern::MAJORITY - - Queries using this read concern will return the node's most - recent copy of the data confirmed as having been written to a - majority of the nodes (i.e. the data cannot be rolled back). - - - - -
+ The read concern level. + You may use, but are not limited to, one of the + class constants.