diff --git a/source/applications/replication.txt b/source/applications/replication.txt index ab8c628ab53..b071ebc8e61 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: @@ -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: @@ -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 @@ -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 @@ -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 @@ -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: @@ -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. @@ -523,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. @@ -594,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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -614,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 @@ -622,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