From 171df0664eece80fe58a1ac24d75a34df7bc3060 Mon Sep 17 00:00:00 2001 From: "A. Jesse Jiryu Davis" Date: Thu, 6 Dec 2012 15:03:27 -0500 Subject: [PATCH 01/11] Read preferences allow choices among all members, not just secondaries --- source/applications/replication.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index ab8c628ab53..1b21e339ea4 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -97,7 +97,7 @@ Read Preference --------------- Read preference describes how MongoDB clients route read operations to -:term:`secondary` members of a :term:`replica set`. +members of a :term:`replica set`. .. index:: read preference; background .. _replica-set-read-preference-background: From 7987a4548b346b6b531282d14caa30ec391bec37 Mon Sep 17 00:00:00 2001 From: "A. Jesse Jiryu Davis" Date: Thu, 6 Dec 2012 15:04:10 -0500 Subject: [PATCH 02/11] Read prefs can improve read latency, too --- source/applications/replication.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index 1b21e339ea4..215da4e6d04 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -109,8 +109,8 @@ By default, an application directs its read operations to the :term:`primary` member in a :term:`replica set`. Reading from the primary guarantees that read operations reflect the latest version of a document. However, for an application that does not require fully up-to-date data, you -can improve read throughput by distributing some or all reads to -secondary members of the replica set. +can improve read throughput, or reduce latency, by distributing some or all +reads to secondary members of the replica set. The following are use cases where you might use secondary reads: From b3c8bb3d8caf1023852611b12ebd2bb9b485a338 Mon Sep 17 00:00:00 2001 From: "A. Jesse Jiryu Davis" Date: Thu, 6 Dec 2012 15:04:20 -0500 Subject: [PATCH 03/11] Read prefs typo --- source/applications/replication.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index 215da4e6d04..d5f29b3fc54 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -142,7 +142,7 @@ configuration, see the appropriate :ref:`driver` API documentation. preferences dictate if the application receives stale or current data from MongoDB. Use appropriate :term:`write concern` policies to ensure proper data - replication and constancy. + replication and consistency. If read operations account for a large percentage of your application's traffic, distributing reads to secondary members can From c32ea5fcc6ad2a429fc2b517cd32e9f74fa045a3 Mon Sep 17 00:00:00 2001 From: "A. Jesse Jiryu Davis" Date: Thu, 6 Dec 2012 15:04:46 -0500 Subject: [PATCH 04/11] Correct docs on configuring driver read prefs --- source/applications/replication.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index d5f29b3fc54..1a7fb60f932 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -170,9 +170,9 @@ read preference modes: - :readmode:`secondaryPreferred` - :readmode:`nearest` -You can specify a read preference mode on a per-collection or -per-operation basis. The syntax for specifying the read preference -mode is :api:`specific to the driver and to the idioms of the host +You can specify a read preference mode on connection objects, database object, +collection object, or per-operation. The syntax for specifying the read +preference mode is :api:`specific to the driver and to the idioms of the host language <>`. Read preference modes are also available to clients connecting to a From 053a00e10d82f6f5707da4a1737f5e33a030be56 Mon Sep 17 00:00:00 2001 From: "A. Jesse Jiryu Davis" Date: Thu, 6 Dec 2012 15:05:41 -0500 Subject: [PATCH 05/11] Read prefs typo --- source/applications/replication.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index 1a7fb60f932..333e4dfacf5 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -440,7 +440,7 @@ As a result, MongoDB drivers and :program:`mongos`: After this error, the driver selects a new member using the specified read preference mode. In the absence of a specified read - preference, the driver uses :readmode:`PRIMARY`. + preference, the driver uses :readmode:`primary`. - After detecting a failover situation, [#fn-failover]_ the driver attempts to refresh the state of the replica set as quickly as From f802d008d01c31cbc2b4c07be282dbd64df576c1 Mon Sep 17 00:00:00 2001 From: "A. Jesse Jiryu Davis" Date: Thu, 6 Dec 2012 15:06:04 -0500 Subject: [PATCH 06/11] Clarify how replica-set monitoring works --- source/applications/replication.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index 333e4dfacf5..44273fd32ce 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -496,10 +496,10 @@ lifetime. Member Selection ```````````````` -Both clients, by way of their drivers, and :program:`mongos` instances for -sharded clusters send periodic "ping," messages to all member of the -replica set to determine latency from the application to each -:program:`mongod` instance. +Clients, by way of their drivers, and :program:`mongos` instances for +sharded clusters periodically call :dbcommand:`isMaster` on all members of the +replica set to update their view of the set's state, and to determine latency +from the application to each :program:`mongod` instance. For any operation that targets a member *other* than the :term:`primary`, the driver: From 387d1aacc47f68e976de1952d5c4f6940c809694 Mon Sep 17 00:00:00 2001 From: "A. Jesse Jiryu Davis" Date: Thu, 6 Dec 2012 15:06:21 -0500 Subject: [PATCH 07/11] Add to read prefs member-selection logic --- source/applications/replication.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index 44273fd32ce..2afaee9ba99 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -507,6 +507,8 @@ For any operation that targets a member *other* than the #. Assembles a list of suitable members, taking into account member type (i.e. secondary, primary, or all members.) +#. Excludes members not matching the tag sets, if specified. + #. Determines which suitable member is the closest to the client in absolute terms. From 862afe47136a7ca0dbf0380b029343f80b3424aa Mon Sep 17 00:00:00 2001 From: "A. Jesse Jiryu Davis" Date: Thu, 6 Dec 2012 15:10:51 -0500 Subject: [PATCH 08/11] Document read prefs secondaryAcceptableLatencyMS option --- source/applications/replication.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index 2afaee9ba99..6209be13cee 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -525,7 +525,9 @@ for more information. .. [#acceptable-secondary-latency] Applications can configure the threshold used in this stage. The default "acceptable latency" is - 15 milliseconds. For :program:`mongos` you can use the + 15 milliseconds, which you can override in the drivers with the + `secondaryAcceptableLatencyMS` option. + For :program:`mongos` you can use the :option:`--localThreshold ` or :setting:`localThreshold` runtime options to set this value. From 55100695f419b5218142b765db7e55222f5b8e07 Mon Sep 17 00:00:00 2001 From: "A. Jesse Jiryu Davis" Date: Thu, 6 Dec 2012 15:11:08 -0500 Subject: [PATCH 09/11] Note that mongos cannot route commands to secondaries in 2.2 --- source/applications/replication.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index 6209be13cee..64c3e5b3b1e 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -598,6 +598,9 @@ for the following commands: otherwise these operations must run on the :term:`primary` members. +:program:`mongos` currently does not route commands using read preferences; all +commands are sent to shards' primaries. See :issue:`SERVER-7423`. + Uses for non-Primary Read Preferences ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 6a7d19c0311cc6a86f0b6c74c132b8b7321475a5 Mon Sep 17 00:00:00 2001 From: "A. Jesse Jiryu Davis" Date: Thu, 6 Dec 2012 15:11:39 -0500 Subject: [PATCH 10/11] Warn about secondaryPreferred possibly redirecting too much traffic to primary --- source/applications/replication.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index 64c3e5b3b1e..38e98daec4b 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -621,6 +621,16 @@ using non-:readmode:`primary` read preference modes: direct connection to a :ref:`hidden member ` of the set. +.. warning:: + + Although it is tempting to use :readmode:`secondaryPreferred` to distribute + load, if your primary cannot accept your full read load, then + using :readmode:`secondaryPreferred` is dangerous: if all secondaries + become unavailable, but you have enough arbiters to prevent the primary from + stepping down, then this mode will redirect traffic to the primary. For this + reason, use :readmode:`secondary` to distribute load, + not :readmode:`secondaryPreferred`. + - Providing local reads for geographically distributed applications. If you have application servers in multiple data centers, you may From 10f511f705cc6366d25f14985256d1b4567374d9 Mon Sep 17 00:00:00 2001 From: "A. Jesse Jiryu Davis" Date: Thu, 6 Dec 2012 15:11:56 -0500 Subject: [PATCH 11/11] A use-case for read preference mode primaryPreferred --- source/applications/replication.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/source/applications/replication.txt b/source/applications/replication.txt index 38e98daec4b..b071ebc8e61 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -639,6 +639,13 @@ using non-:readmode:`primary` read preference modes: read preference or the :readmode:`nearest` to avoid network latency. +- Maintaining availability during a failover. + + Use :readmode:`primaryPreferred` if you want your application to do + consistent reads from the primary under normal circumstances, but to allow + stale reads from secondaries in an emergency. This provides a "read-only mode" + for your application during a failover. + Using read modes other than :readmode:`primary` and :readmode:`primaryPreferred` to provide extra capacity is not in and of itself justification for non-:readmode:`primary` in many