From 3d7ae37c6e121982e011d1eafc92df803ad3446b Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 12:15:40 -0400 Subject: [PATCH 01/11] DOCSP-41965: Read and write settings --- source/databases-collections.txt | 3 + source/read-write-pref.txt | 201 +++++++++++++++++++++++++++++++ 2 files changed, 204 insertions(+) create mode 100644 source/read-write-pref.txt diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 1a650dc9..356926ec 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -199,6 +199,9 @@ You can change these settings by passing an options array to the ``MongoDB\Client::selectDatabase()``, ``MongoDB\Client::selectCollection()``, or ``MongoDB\Database::selectCollection()`` methods. +To learn more about setting a read preference, read concern, and write concern, +see the :ref:`php-crud-write-read-pref` guide. + To change the read preference, read concern, and write concern of your database or collection, set the following options in the array parameter: diff --git a/source/read-write-pref.txt b/source/read-write-pref.txt new file mode 100644 index 00000000..995ccfcd --- /dev/null +++ b/source/read-write-pref.txt @@ -0,0 +1,201 @@ +.. _php-read-write-pref: + +=============================================== +Specify How CRUD Operations Run on Replica Sets +=============================================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: customize, preferences, replica set, consistency + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the **write concern**, **read concern**, and +**read preference** configurations to modify the way that MongoDB runs +create, read, update, and delete (CRUD) operations on replica sets. + +You can set write concern, read concern, and read preference options at the following +levels: + +- Client, which sets the *default for all operation executions* unless overridden +- Session +- Transaction +- Database +- Collection + +This list also indicates the increasing order of precedence of the option settings. For +example, if you set a read concern level for a transaction, it will override a read +concern level set for the client. + +These options allow you to customize the causal consistency and availability of the data +in your replica sets. + +.. _php-read-write-config: + +Configure Read and Write Operations +----------------------------------- + +This section shows how to configure the read preference, read concern, and write +concern at various levels by passing an options array parameter to the following +objects and methods: + +- :ref:`MongoDB\\Client ` +- :ref:`MongoDB\\Driver\\Session ` +- :ref:`MongoDB\\with_transaction() ` +- :ref:`MongoDB\\Database ` +- :ref:`MongoDB\\Collection ` + +In the options parameter, specify the following values: + +- ``readPreference``: Sets the read preference. For a list of available read + preferences, see :php:`MongoDB\Driver\ReadPreference ` + in the extension API documentation. +- ``readConcern``: Sets the read concern. For a list of available read + concerns, see :php:`MongoDB\Driver\ReadConcern ` + in the extension API documentation. +- ``writeConcern``: Sets the write concern. For a list of available write + concerns, see :php:`MongoDB\Driver\WriteConcern ` + in the extension API documentation. + +.. _php-read-write-client: + +Client Configuration Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to set the read preference, read concern, and +write concern of a ``MongoDB\Client`` instance by passing an array to +the constructor: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-database-settings + :end-before: end-database-settings + +.. _php-read-write-session: + +Session Configuration Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _php-read-write-transaction: + +Transaction Configuration Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _php-read-write-database: + +Database Configuration Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to set the read preference, read concern, and +write concern of a database called ``test_database`` by passing an options +array to ``selectDatabase()``: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-database-settings + :end-before: end-database-settings + +.. _php-read-write-collection: + +Collection Configuration Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example shows how to set the read preference, read concern, and +write concern of a collection called ``test_collection`` by passing an options +array to ``selectCollection()``: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-collection-settings + :end-before: end-collection-settings + +Advanced Read Configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tag Sets +```````` + +In {+mdb-server+}, you can apply key-value :manual:`tags +` to replica-set +members according to any criteria you choose. You can then use +those tags to target one or more members for a read operation. + +By default, the {+php-library+} ignores tags when choosing a member +to read from. To instruct the {+php-library+} to prefer certain tags, +pass them as a parameter to your ``MongoDB\Driver\ReadPreference`` class +constructor. Then, set the ``MongoDB\Driver\ReadPreference`` object as +the value of the ``readPreference`` database option. + +This code example sets the ``readPreference`` option to a tag set +that instructs ``test_database`` to prefer reads from secondary replica set +members in the following order: + +1. Members from the New York data center (``['dc' => 'ny']``) +#. Members from the San Francisco data center (``['dc' => 'sf']``) +#. Any secondary members (``[]``) + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-tag-set + :end-before: end-tag-set + +Local Threshold +``````````````` + +If multiple replica-set members match the read preference and tag sets you specify, +the {+php-library+} reads from the nearest replica-set members, chosen according to +their ping time. + +By default, the library uses only members whose ping times are within 15 milliseconds +of the nearest member for queries. To distribute reads between members with +higher latencies, pass an options array to the ``MongoDB\Client`` constructor that +sets the ``localThresholdMS`` option. + +The following example specifies a local threshold of 35 milliseconds: + +.. literalinclude:: /includes/databases-collections/databases-collections.php + :language: php + :dedent: + :start-after: start-local-threshold + :end-before: end-local-threshold + +In the preceding example, the {+php-library+} distributes reads among matching members +within 35 milliseconds of the closest member's ping time. + +.. note:: + + The {+php-library+} ignores the value of ``localThresholdMS`` when communicating with a + replica set through a ``mongos`` instance. In this case, use the + :manual:`localThreshold ` + command-line option. + + +Additional Information +---------------------- + +To learn more about read preferences and read and write concerns, see the +following guides in the {+mdb-server+} manual: + +- :manual:`Read Preference ` +- :manual:`Read Concern ` +- :manual:`Write Concern ` + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: \ No newline at end of file From 857753bfff2c8eb0ddd7fe810d5419da289bd792 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 14:13:04 -0400 Subject: [PATCH 02/11] more info --- source/databases-collections.txt | 111 +--------------------------- source/includes/read-write-pref.php | 102 +++++++++++++++++++++++++ source/read-write-pref.txt | 91 +++++++++++++++++++---- 3 files changed, 178 insertions(+), 126 deletions(-) create mode 100644 source/includes/read-write-pref.php diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 356926ec..092375ae 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -200,116 +200,7 @@ You can change these settings by passing an options array to the ``MongoDB\Database::selectCollection()`` methods. To learn more about setting a read preference, read concern, and write concern, -see the :ref:`php-crud-write-read-pref` guide. - -To change the read preference, read concern, and write concern of your database -or collection, set the following options in the array parameter: - -- ``readPreference``: Sets the read preference. For a list of available read - preferences, see :php:`MongoDB\Driver\ReadPreference ` - in the extension API documentation. -- ``readConcern``: Sets the read concern. For a list of available read - concerns, see :php:`MongoDB\Driver\ReadConcern ` - in the extension API documentation. -- ``writeConcern``: Sets the write concern. For a list of available write - concerns, see :php:`MongoDB\Driver\WriteConcern ` - in the extension API documentation. - -.. tip:: - - To learn more about read preferences and read and write concerns, see the - following guides in the MongoDB Server manual: - - - :manual:`Read Preference ` - - :manual:`Read Concern ` - - :manual:`Write Concern ` - -Database Configuration Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following example shows how to set the read preference, read concern, and -write concern of a database called ``test_database`` by passing an options -array to ``selectDatabase()``: - -.. literalinclude:: /includes/databases-collections/databases-collections.php - :language: php - :dedent: - :start-after: start-database-settings - :end-before: end-database-settings - -Collection Configuration Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following example shows how to set the read preference, read concern, and -write concern of a collection called ``test_collection`` by passing an options -array to ``selectCollection()``: - -.. literalinclude:: /includes/databases-collections/databases-collections.php - :language: php - :dedent: - :start-after: start-collection-settings - :end-before: end-collection-settings - -Advanced Read Configurations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Tag Sets -```````` - -In {+mdb-server+}, you can apply key-value :manual:`tags -` to replica-set -members according to any criteria you choose. You can then use -those tags to target one or more members for a read operation. - -By default, the {+php-library+} ignores tags when choosing a member -to read from. To instruct the {+php-library+} to prefer certain tags, -pass them as a parameter to your ``MongoDB\Driver\ReadPreference`` class -constructor. Then, set the ``MongoDB\Driver\ReadPreference`` object as -the value of the ``readPreference`` database option. - -This code example sets the ``readPreference`` option to a tag set -that instructs ``test_database`` to prefer reads from secondary replica set -members in the following order: - -1. Members from the New York data center (``['dc' => 'ny']``) -#. Members from the San Francisco data center (``['dc' => 'sf']``) -#. Any secondary members (``[]``) - -.. literalinclude:: /includes/databases-collections/databases-collections.php - :language: php - :dedent: - :start-after: start-tag-set - :end-before: end-tag-set - -Local Threshold -``````````````` - -If multiple replica-set members match the read preference and tag sets you specify, -the {+php-library+} reads from the nearest replica-set members, chosen according to -their ping time. - -By default, the library uses only members whose ping times are within 15 milliseconds -of the nearest member for queries. To distribute reads between members with -higher latencies, pass an options array to the ``MongoDB\Client`` constructor that -sets the ``localThresholdMS`` option. - -The following example specifies a local threshold of 35 milliseconds: - -.. literalinclude:: /includes/databases-collections/databases-collections.php - :language: php - :dedent: - :start-after: start-local-threshold - :end-before: end-local-threshold - -In the preceding example, the {+php-library+} distributes reads among matching members -within 35 milliseconds of the closest member's ping time. - -.. note:: - - The {+php-library+} ignores the value of ``localThresholdMS`` when communicating with a - replica set through a ``mongos`` instance. In this case, use the - :manual:`localThreshold ` - command-line option. +see the :ref:`php-read-write-pref` guide. API Documentation ----------------- diff --git a/source/includes/read-write-pref.php b/source/includes/read-write-pref.php new file mode 100644 index 00000000..570129c8 --- /dev/null +++ b/source/includes/read-write-pref.php @@ -0,0 +1,102 @@ + 'secondary', + 'readConcernLevel' => 'local', + 'w' => 'majority', +]; + +$client = new Client('mongodb://localhost:27017', $clientOptions); +// end-client-settings + +// start-client-settings-uri +$uri = 'mongodb://localhost:27017/?readPreference=secondary&readConcernLevel=local&w=majority'; +$client = new Client($uri); +// end-client-settings-uri + +// start-session-settings +$sessionOptions = [ + 'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY), + 'readConcern' => new ReadConcern(ReadConcern::LOCAL), + 'writeConcern' => new WriteConcern(WriteConcern::MAJORITY), +]; + +$session = $client->startSession($sessionOptions); +// end-session-settings + +// start-transaction-settings +$transactionOptions = [ + 'readPreference' => new ReadPreference(ReadPreference::RP_PRIMARY), + 'readConcern' => new ReadConcern(ReadConcern::AVAILABLE), + 'writeConcern' => new WriteConcern(WriteConcern::MAJORITY), +]; + +// Start the transaction +$session->startTransaction($transactionOptions); +// end-transaction-settings + +// Sets read and write settings for the "test_database" database +// start-database-settings +$readPreference = new ReadPreference(ReadPreference::RP_PRIMARY_PREFERRED); +$readConcern = new ReadConcern(ReadConcern::LOCAL); +$writeConcern = new WriteConcern(WriteConcern::MAJORITY); + +$db = $client->selectDatabase('test_database', [ + 'readPreference' => $readPreference, + 'readConcern' => $readConcern, + 'writeConcern' => $writeConcern, +]); +// end-database-settings + +// Sets read and write settings for the "test_collection" collection +// start-collection-settings +$readPreference = new ReadPreference(ReadPreference::RP_PRIMARY); +$readConcern = new ReadConcern(ReadConcern::AVAILABLE); +$writeConcern = new WriteConcern(WriteConcern::MAJORITY); + +$collection = $client->selectCollection('test_database', 'test_collection', [ + 'readPreference' => $readPreference, + 'readConcern' => $readConcern, + 'writeConcern' => $writeConcern, +]); + +// end-collection-settings + +// Instructs the library to prefer reads from secondary replica set members +// located in New York, followed by a secondary in San Francisco, and +// lastly fall back to any secondary. +// start-tag-set +$readPreference = new ReadPreference( + ReadPreference::RP_SECONDARY, + [ + ['dc' => 'ny'], + ['dc' => 'sf'], + [], + ], +); + +$db = $client->selectDatabase( + 'test_database', + ['readPreference' => $readPreference], +); + +// end-tag-set + +// Instructs the library to distribute reads between members within 35 milliseconds +// of the closest member's ping time +// start-local-threshold +$options = [ + 'replicaSet' => 'repl0', + 'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY_PREFERRED), + 'localThresholdMS' => 35, +]; + +$client = new Client('', [], $options); +// end-local-threshold diff --git a/source/read-write-pref.txt b/source/read-write-pref.txt index 995ccfcd..de625b66 100644 --- a/source/read-write-pref.txt +++ b/source/read-write-pref.txt @@ -47,13 +47,18 @@ Configure Read and Write Operations This section shows how to configure the read preference, read concern, and write concern at various levels by passing an options array parameter to the following -objects and methods: - -- :ref:`MongoDB\\Client ` -- :ref:`MongoDB\\Driver\\Session ` -- :ref:`MongoDB\\with_transaction() ` -- :ref:`MongoDB\\Database ` -- :ref:`MongoDB\\Collection ` +methods: + +- :ref:`MongoDB\\Client::__construct() `: Configures read + and write settings at the client level +- :ref:`MongoDB\\Client::startSession() `: Configures read + and write settings at the session level +- :ref:`MongoDB\\Driver\\Session::startTransaction() `: + Configures read and write settings at the transaction level +- :ref:`MongoDB\\Client::selectDatabase() `: Configures read + and write settings at the database level +- :ref:`MongoDB\\Client::selectCollection() `: Configures read + and write settings at the collection level In the options parameter, specify the following values: @@ -67,6 +72,13 @@ In the options parameter, specify the following values: concerns, see :php:`MongoDB\Driver\WriteConcern ` in the extension API documentation. +.. note:: + + When setting a write concern at the ``MongoDB\Client`` level, specify the ``w`` + value in an options array rather than ``writeConcern.`` You can also specify + read and write settings in the connection URI. For more information, + see the :ref:`php-read-write-client`. + .. _php-read-write-client: Client Configuration Example @@ -76,22 +88,51 @@ The following example shows how to set the read preference, read concern, and write concern of a ``MongoDB\Client`` instance by passing an array to the constructor: -.. literalinclude:: /includes/databases-collections/databases-collections.php +.. literalinclude:: /includes/read-write-pref.php :language: php :dedent: - :start-after: start-database-settings - :end-before: end-database-settings + :start-after: start-client-settings + :end-before: end-client-settings + +Alternatively, you can specify the read and write settings in the connection +URI, which is passed as a parameter to the ``MongoDB\Client`` constructor: + +.. literalinclude:: /includes/read-write-pref.php + :language: php + :dedent: + :start-after: start-client-settings-uri + :end-before: end-client-settings-uri .. _php-read-write-session: Session Configuration Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The following example shows how to set the read preference, read concern, and +write concern of a session by passing an array to the ``startSession()`` +method: + +.. literalinclude:: /includes/read-write-pref.php + :language: php + :dedent: + :start-after: start-session-settings + :end-before: end-session-settings + .. _php-read-write-transaction: Transaction Configuration Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The following example shows how to set the read preference, read concern, and +write concern of a transaction by passing an array to the ``startTransaction()`` +method: + +.. literalinclude:: /includes/read-write-pref.php + :language: php + :dedent: + :start-after: start-transaction-settings + :end-before: end-transaction-settings + .. _php-read-write-database: Database Configuration Example @@ -99,7 +140,7 @@ Database Configuration Example The following example shows how to set the read preference, read concern, and write concern of a database called ``test_database`` by passing an options -array to ``selectDatabase()``: +array to the ``selectDatabase()`` method: .. literalinclude:: /includes/databases-collections/databases-collections.php :language: php @@ -114,7 +155,7 @@ Collection Configuration Example The following example shows how to set the read preference, read concern, and write concern of a collection called ``test_collection`` by passing an options -array to ``selectCollection()``: +array to the ``selectCollection()`` method: .. literalinclude:: /includes/databases-collections/databases-collections.php :language: php @@ -122,11 +163,21 @@ array to ``selectCollection()``: :start-after: start-collection-settings :end-before: end-collection-settings +.. _php-read-write-advanced: + Advanced Read Configurations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- + +This section shows how to further customize your read operation +settings in the following ways: + +- :ref:`Apply a tag set ` +- :ref:`Specify a local threshold ` + +.. _php-tag-sets: Tag Sets -```````` +~~~~~~~~ In {+mdb-server+}, you can apply key-value :manual:`tags ` to replica-set @@ -153,8 +204,10 @@ members in the following order: :start-after: start-tag-set :end-before: end-tag-set +.. _php-local-threshold: + Local Threshold -``````````````` +~~~~~~~~~~~~~~~ If multiple replica-set members match the read preference and tag sets you specify, the {+php-library+} reads from the nearest replica-set members, chosen according to @@ -198,4 +251,10 @@ API Documentation ~~~~~~~~~~~~~~~~~ To learn more about any of the methods or types discussed in this -guide, see the following API documentation: \ No newline at end of file +guide, see the following API documentation: + +- :phpmethod:`MongoDB\Client::__construct()` +- :phpmethod:`MongoDB\Client::startSession()` +- :php:`MongoDB\Driver\Session::startTransaction()` +- :phpmethod:`MongoDB\Client::selectDatabase()` +- :phpmethod:`MongoDB\Client::selectCollection()` From 2aab86aa08b2a3ebfb0b3f4566689ad2abd44f19 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 14:47:40 -0400 Subject: [PATCH 03/11] edits --- source/databases-collections.txt | 6 +-- source/includes/read-write-pref.php | 18 ++++---- source/read-write-pref.txt | 64 ++++++++++++++++++++++++----- 3 files changed, 65 insertions(+), 23 deletions(-) diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 092375ae..5bfadbaf 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -187,10 +187,8 @@ The following example deletes the ``test_collection`` collection: Configure Read and Write Operations ----------------------------------- -You can control how the library routes read operations by setting a **read preference**. -You can also control options for how the library waits for acknowledgment of -read and write operations on a replica set by setting a **read concern** and a -**write concern**. +You can control how read and write operations run on replica sets +by specifying a read preference, read concern, and write concern. By default, databases inherit read and write settings from the ``MongoDB\Client`` instance. Collections inherit these settings from the ``MongoDB\Client`` or diff --git a/source/includes/read-write-pref.php b/source/includes/read-write-pref.php index 570129c8..ae938a7f 100644 --- a/source/includes/read-write-pref.php +++ b/source/includes/read-write-pref.php @@ -10,7 +10,7 @@ $clientOptions = [ 'readPreference' => 'secondary', 'readConcernLevel' => 'local', - 'w' => 'majority', + 'w' => '2', ]; $client = new Client('mongodb://localhost:27017', $clientOptions); @@ -23,7 +23,7 @@ // start-session-settings $sessionOptions = [ - 'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY), + 'readPreference' => new ReadPreference(ReadPreference::PRIMARY_PREFERRED), 'readConcern' => new ReadConcern(ReadConcern::LOCAL), 'writeConcern' => new WriteConcern(WriteConcern::MAJORITY), ]; @@ -33,9 +33,9 @@ // start-transaction-settings $transactionOptions = [ - 'readPreference' => new ReadPreference(ReadPreference::RP_PRIMARY), - 'readConcern' => new ReadConcern(ReadConcern::AVAILABLE), - 'writeConcern' => new WriteConcern(WriteConcern::MAJORITY), + 'readPreference' => new ReadPreference(ReadPreference::PRIMARY), + 'readConcern' => new ReadConcern(ReadConcern::MAJORITY), + 'writeConcern' => new WriteConcern(1), ]; // Start the transaction @@ -44,8 +44,8 @@ // Sets read and write settings for the "test_database" database // start-database-settings -$readPreference = new ReadPreference(ReadPreference::RP_PRIMARY_PREFERRED); -$readConcern = new ReadConcern(ReadConcern::LOCAL); +$readPreference = new ReadPreference(ReadPreference::PRIMARY_PREFERRED); +$readConcern = new ReadConcern(ReadConcern::AVAILABLE); $writeConcern = new WriteConcern(WriteConcern::MAJORITY); $db = $client->selectDatabase('test_database', [ @@ -57,9 +57,9 @@ // Sets read and write settings for the "test_collection" collection // start-collection-settings -$readPreference = new ReadPreference(ReadPreference::RP_PRIMARY); +$readPreference = new ReadPreference(ReadPreference::SECONDARY_PREFERRED); $readConcern = new ReadConcern(ReadConcern::AVAILABLE); -$writeConcern = new WriteConcern(WriteConcern::MAJORITY); +$writeConcern = new WriteConcern(0); $collection = $client->selectCollection('test_database', 'test_collection', [ 'readPreference' => $readPreference, diff --git a/source/read-write-pref.txt b/source/read-write-pref.txt index de625b66..8a8a02bf 100644 --- a/source/read-write-pref.txt +++ b/source/read-write-pref.txt @@ -45,6 +45,11 @@ in your replica sets. Configure Read and Write Operations ----------------------------------- +You can control how the library routes read operations by setting a **read preference**. +You can also control options for how the library waits for acknowledgment of +read and write operations on a replica set by setting a **read concern** and a +**write concern**. + This section shows how to configure the read preference, read concern, and write concern at various levels by passing an options array parameter to the following methods: @@ -84,9 +89,17 @@ In the options parameter, specify the following values: Client Configuration Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following example shows how to set the read preference, read concern, and +This example shows how to set the read preference, read concern, and write concern of a ``MongoDB\Client`` instance by passing an array to -the constructor: +the constructor. The code configures the following settings: + +- ``secondary`` read preference: Read operations retrieve data from + secondary replica set members +- ``local`` read concern: Read operations return the instance's most recent data + without guaranteeing that the data has been written to a majority of the replica + set members +- ``2`` write concern: The primary and one secondary replica set member + must acknowledge the write operation .. literalinclude:: /includes/read-write-pref.php :language: php @@ -108,9 +121,18 @@ URI, which is passed as a parameter to the ``MongoDB\Client`` constructor: Session Configuration Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following example shows how to set the read preference, read concern, and +This example shows how to set the read preference, read concern, and write concern of a session by passing an array to the ``startSession()`` -method: +method. The code configures the following settings: + +- ``PRIMARY_PREFERRED`` read preference: Read operations retrieve data from + the primary replica set member, or secondary members if the primary is unavailable +- ``LOCAL`` read concern: Read operations return the instance's most recent data + without guaranteeing that the data has been written to a majority of the replica + set members +- ``MAJORITY`` write concern: The majority of all replica set members + must acknowledge the write operation + .. literalinclude:: /includes/read-write-pref.php :language: php @@ -123,9 +145,16 @@ method: Transaction Configuration Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following example shows how to set the read preference, read concern, and +This example shows how to set the read preference, read concern, and write concern of a transaction by passing an array to the ``startTransaction()`` -method: +method. The code configures the following settings: + +- ``PRIMARY`` read preference: Read operations retrieve data from + the primary replica set member +- ``MAJORITY`` read concern: Read operations return the instance's most recent data + that has been written to a majority of replica set members +- ``1`` write concern: The primary replica set member must acknowledge the + write operation .. literalinclude:: /includes/read-write-pref.php :language: php @@ -138,9 +167,17 @@ method: Database Configuration Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following example shows how to set the read preference, read concern, and +This example shows how to set the read preference, read concern, and write concern of a database called ``test_database`` by passing an options -array to the ``selectDatabase()`` method: +array to the ``selectDatabase()`` method. The code configures the following settings: + +- ``PRIMARY_PREFERRED`` read preference: Read operations retrieve data from + the primary replica set member, or secondary members if the primary is unavailable +- ``AVAILABLE`` read concern: Read operations return the instance's most recent data + without guaranteeing that the data has been written to a majority of the replica + set members +- ``MAJORITY`` write concern: The majority of all replica set members + must acknowledge the write operation .. literalinclude:: /includes/databases-collections/databases-collections.php :language: php @@ -153,9 +190,16 @@ array to the ``selectDatabase()`` method: Collection Configuration Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following example shows how to set the read preference, read concern, and +This example shows how to set the read preference, read concern, and write concern of a collection called ``test_collection`` by passing an options -array to the ``selectCollection()`` method: +array to the ``selectCollection()`` method. The code configures the following settings: + +- ``SECONDARY_PREFERRED`` read preference: Read operations retrieve data from + secondary replica set members, or the primary members if no secondaries are available +- ``AVAILABLE`` read concern: Read operations return the instance's most recent data + without guaranteeing that the data has been written to a majority of the replica + set members +- ``0`` write concern: Requests no acknowledgment of the write operation .. literalinclude:: /includes/databases-collections/databases-collections.php :language: php From d0e69345675177e32e3e0014c9c1c76558c959ac Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 14:55:53 -0400 Subject: [PATCH 04/11] edits --- source/includes/read-write-pref.php | 2 +- source/index.txt | 1 + source/read-write-pref.txt | 52 +++++++++-------------------- 3 files changed, 18 insertions(+), 37 deletions(-) diff --git a/source/includes/read-write-pref.php b/source/includes/read-write-pref.php index ae938a7f..4f638a8c 100644 --- a/source/includes/read-write-pref.php +++ b/source/includes/read-write-pref.php @@ -17,7 +17,7 @@ // end-client-settings // start-client-settings-uri -$uri = 'mongodb://localhost:27017/?readPreference=secondary&readConcernLevel=local&w=majority'; +$uri = 'mongodb://localhost:27017/?readPreference=secondary&readConcernLevel=local&w=2'; $client = new Client($uri); // end-client-settings-uri diff --git a/source/index.txt b/source/index.txt index 0a589f6e..89e32579 100644 --- a/source/index.txt +++ b/source/index.txt @@ -17,6 +17,7 @@ MongoDB PHP Library /aggregation /indexes /security + /read-write-pref /tutorial /upgrade /reference diff --git a/source/read-write-pref.txt b/source/read-write-pref.txt index 8a8a02bf..872b4feb 100644 --- a/source/read-write-pref.txt +++ b/source/read-write-pref.txt @@ -45,44 +45,24 @@ in your replica sets. Configure Read and Write Operations ----------------------------------- -You can control how the library routes read operations by setting a **read preference**. -You can also control options for how the library waits for acknowledgment of -read and write operations on a replica set by setting a **read concern** and a -**write concern**. +You can control how the library routes read operations by setting a read preference. +You can also control how the library waits for acknowledgment of read and write operations +on a replica set by setting a read and write concern. This section shows how to configure the read preference, read concern, and write concern at various levels by passing an options array parameter to the following methods: -- :ref:`MongoDB\\Client::__construct() `: Configures read - and write settings at the client level -- :ref:`MongoDB\\Client::startSession() `: Configures read - and write settings at the session level -- :ref:`MongoDB\\Driver\\Session::startTransaction() `: - Configures read and write settings at the transaction level -- :ref:`MongoDB\\Client::selectDatabase() `: Configures read - and write settings at the database level -- :ref:`MongoDB\\Client::selectCollection() `: Configures read - and write settings at the collection level - -In the options parameter, specify the following values: - -- ``readPreference``: Sets the read preference. For a list of available read - preferences, see :php:`MongoDB\Driver\ReadPreference ` - in the extension API documentation. -- ``readConcern``: Sets the read concern. For a list of available read - concerns, see :php:`MongoDB\Driver\ReadConcern ` - in the extension API documentation. -- ``writeConcern``: Sets the write concern. For a list of available write - concerns, see :php:`MongoDB\Driver\WriteConcern ` - in the extension API documentation. - -.. note:: - - When setting a write concern at the ``MongoDB\Client`` level, specify the ``w`` - value in an options array rather than ``writeConcern.`` You can also specify - read and write settings in the connection URI. For more information, - see the :ref:`php-read-write-client`. +- :ref:`MongoDB\Client::__construct() `: Configures client-level + settings +- :ref:`MongoDB\Client::startSession() `: Configures session-level + settings +- :ref:`MongoDB\Driver\Session::startTransaction() `: + Configures transaction-level settings +- :ref:`MongoDB\Client::selectDatabase() `: Configures + database-level settings +- :ref:`MongoDB\Client::selectCollection() `: Configures read + collection-level settings .. _php-read-write-client: @@ -179,7 +159,7 @@ array to the ``selectDatabase()`` method. The code configures the following sett - ``MAJORITY`` write concern: The majority of all replica set members must acknowledge the write operation -.. literalinclude:: /includes/databases-collections/databases-collections.php +.. literalinclude:: /includes/read-write-pref.php :language: php :dedent: :start-after: start-database-settings @@ -201,7 +181,7 @@ array to the ``selectCollection()`` method. The code configures the following se set members - ``0`` write concern: Requests no acknowledgment of the write operation -.. literalinclude:: /includes/databases-collections/databases-collections.php +.. literalinclude:: /includes/read-write-pref.php :language: php :dedent: :start-after: start-collection-settings @@ -299,6 +279,6 @@ guide, see the following API documentation: - :phpmethod:`MongoDB\Client::__construct()` - :phpmethod:`MongoDB\Client::startSession()` -- :php:`MongoDB\Driver\Session::startTransaction()` +- :php:`MongoDB\Driver\Session::startTransaction` - :phpmethod:`MongoDB\Client::selectDatabase()` - :phpmethod:`MongoDB\Client::selectCollection()` From 0966a2a610ddda17f4862ac844133592372d55f5 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 14:59:37 -0400 Subject: [PATCH 05/11] headers --- source/read-write-pref.txt | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/read-write-pref.txt b/source/read-write-pref.txt index 872b4feb..533b755e 100644 --- a/source/read-write-pref.txt +++ b/source/read-write-pref.txt @@ -66,8 +66,8 @@ methods: .. _php-read-write-client: -Client Configuration Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Client Configuration +~~~~~~~~~~~~~~~~~~~~ This example shows how to set the read preference, read concern, and write concern of a ``MongoDB\Client`` instance by passing an array to @@ -98,8 +98,8 @@ URI, which is passed as a parameter to the ``MongoDB\Client`` constructor: .. _php-read-write-session: -Session Configuration Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Session Configuration +~~~~~~~~~~~~~~~~~~~~~ This example shows how to set the read preference, read concern, and write concern of a session by passing an array to the ``startSession()`` @@ -122,8 +122,8 @@ method. The code configures the following settings: .. _php-read-write-transaction: -Transaction Configuration Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Transaction Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~ This example shows how to set the read preference, read concern, and write concern of a transaction by passing an array to the ``startTransaction()`` @@ -144,8 +144,8 @@ method. The code configures the following settings: .. _php-read-write-database: -Database Configuration Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Database Configuration +~~~~~~~~~~~~~~~~~~~~~~ This example shows how to set the read preference, read concern, and write concern of a database called ``test_database`` by passing an options @@ -167,8 +167,8 @@ array to the ``selectDatabase()`` method. The code configures the following sett .. _php-read-write-collection: -Collection Configuration Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Collection Configuration +~~~~~~~~~~~~~~~~~~~~~~~~ This example shows how to set the read preference, read concern, and write concern of a collection called ``test_collection`` by passing an options From e31a674477e6219b3e5700e8a065d0ff9c33f97e Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 15:04:22 -0400 Subject: [PATCH 06/11] fix link --- source/read-write-pref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/read-write-pref.txt b/source/read-write-pref.txt index 533b755e..099edef1 100644 --- a/source/read-write-pref.txt +++ b/source/read-write-pref.txt @@ -279,6 +279,6 @@ guide, see the following API documentation: - :phpmethod:`MongoDB\Client::__construct()` - :phpmethod:`MongoDB\Client::startSession()` -- :php:`MongoDB\Driver\Session::startTransaction` +- :php:`MongoDB\Driver\Session::startTransaction() ` - :phpmethod:`MongoDB\Client::selectDatabase()` - :phpmethod:`MongoDB\Client::selectCollection()` From 79e360878478a32eb2320520e1e49be61228d8b6 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 15:15:53 -0400 Subject: [PATCH 07/11] fix --- source/read-write-pref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/read-write-pref.txt b/source/read-write-pref.txt index 099edef1..eb8c835e 100644 --- a/source/read-write-pref.txt +++ b/source/read-write-pref.txt @@ -279,6 +279,6 @@ guide, see the following API documentation: - :phpmethod:`MongoDB\Client::__construct()` - :phpmethod:`MongoDB\Client::startSession()` -- :php:`MongoDB\Driver\Session::startTransaction() ` +- :php:`MongoDB\Driver\Session::startTransaction() ` - :phpmethod:`MongoDB\Client::selectDatabase()` - :phpmethod:`MongoDB\Client::selectCollection()` From a36917dcd0cdd682d6bfa7cedbd007fa79edbb27 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 24 Sep 2024 10:15:51 -0400 Subject: [PATCH 08/11] RR feedback --- source/databases-collections.txt | 2 +- source/includes/read-write-pref.php | 23 +++++--------- source/read-write-pref.txt | 47 ++++++++++++++++++----------- 3 files changed, 38 insertions(+), 34 deletions(-) diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 5bfadbaf..456e65f1 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -188,7 +188,7 @@ Configure Read and Write Operations ----------------------------------- You can control how read and write operations run on replica sets -by specifying a read preference, read concern, and write concern. +by specifying a read preference, read concern, or write concern. By default, databases inherit read and write settings from the ``MongoDB\Client`` instance. Collections inherit these settings from the ``MongoDB\Client`` or diff --git a/source/includes/read-write-pref.php b/source/includes/read-write-pref.php index 4f638a8c..9c0c8ed9 100644 --- a/source/includes/read-write-pref.php +++ b/source/includes/read-write-pref.php @@ -38,33 +38,24 @@ 'writeConcern' => new WriteConcern(1), ]; -// Start the transaction $session->startTransaction($transactionOptions); // end-transaction-settings // Sets read and write settings for the "test_database" database // start-database-settings -$readPreference = new ReadPreference(ReadPreference::PRIMARY_PREFERRED); -$readConcern = new ReadConcern(ReadConcern::AVAILABLE); -$writeConcern = new WriteConcern(WriteConcern::MAJORITY); - $db = $client->selectDatabase('test_database', [ - 'readPreference' => $readPreference, - 'readConcern' => $readConcern, - 'writeConcern' => $writeConcern, + 'readPreference' => new ReadPreference(ReadPreference::PRIMARY_PREFERRED), + 'readConcern' => new ReadConcern(ReadConcern::AVAILABLE), + 'writeConcern' => new WriteConcern(WriteConcern::MAJORITY), ]); // end-database-settings // Sets read and write settings for the "test_collection" collection // start-collection-settings -$readPreference = new ReadPreference(ReadPreference::SECONDARY_PREFERRED); -$readConcern = new ReadConcern(ReadConcern::AVAILABLE); -$writeConcern = new WriteConcern(0); - $collection = $client->selectCollection('test_database', 'test_collection', [ - 'readPreference' => $readPreference, - 'readConcern' => $readConcern, - 'writeConcern' => $writeConcern, + 'readPreference' => new ReadPreference(ReadPreference::SECONDARY_PREFERRED), + 'readConcern' => new ReadConcern(ReadConcern::AVAILABLE), + 'writeConcern' => new WriteConcern(0), ]); // end-collection-settings @@ -98,5 +89,5 @@ 'localThresholdMS' => 35, ]; -$client = new Client('', [], $options); +$client = new Client('mongodb://localhost:27017', [], $options); // end-local-threshold diff --git a/source/read-write-pref.txt b/source/read-write-pref.txt index eb8c835e..d042abe6 100644 --- a/source/read-write-pref.txt +++ b/source/read-write-pref.txt @@ -20,9 +20,9 @@ Specify How CRUD Operations Run on Replica Sets Overview -------- -In this guide, you can learn how to use the **write concern**, **read concern**, and -**read preference** configurations to modify the way that MongoDB runs -create, read, update, and delete (CRUD) operations on replica sets. +In this guide, you can learn how to configure **write concern**, **read concern**, +and **read preference** options to modify the way that the {+php-library+} runs create, +read, update, and delete (CRUD) operations on replica sets. You can set write concern, read concern, and read preference options at the following levels: @@ -35,10 +35,15 @@ levels: This list also indicates the increasing order of precedence of the option settings. For example, if you set a read concern level for a transaction, it will override a read -concern level set for the client. +concern level inherited from the client. These options allow you to customize the causal consistency and availability of the data -in your replica sets. +in your replica sets. To see a full list of read preference, read concern, and write concern +options, see the following guides in the {+mdb-server+} manual: + +- :manual:`Read Preference ` +- :manual:`Read Concern ` +- :manual:`Write Concern ` .. _php-read-write-config: @@ -47,11 +52,11 @@ Configure Read and Write Operations You can control how the library routes read operations by setting a read preference. You can also control how the library waits for acknowledgment of read and write operations -on a replica set by setting a read and write concern. +on a replica set by setting read and write concerns. This section shows how to configure the read preference, read concern, and write -concern at various levels by passing an options array parameter to the following -methods: +concern at various levels by passing an options array parameter to any one of the +following methods: - :ref:`MongoDB\Client::__construct() `: Configures client-level settings @@ -96,6 +101,14 @@ URI, which is passed as a parameter to the ``MongoDB\Client`` constructor: :start-after: start-client-settings-uri :end-before: end-client-settings-uri +.. note:: + + The ``readPreference``, ``readConcernLevel``, and ``w`` client options accept + string values. When configuring read and write settings at any other level, + you must assign values of type ``MongoDB\Driver\ReadPreference``, + ``MongoDB\Driver\ReadConcern``, and ``MongoDB\Driver\WriteConcern`` to the corresponding + options. + .. _php-read-write-session: Session Configuration @@ -113,7 +126,6 @@ method. The code configures the following settings: - ``MAJORITY`` write concern: The majority of all replica set members must acknowledge the write operation - .. literalinclude:: /includes/read-write-pref.php :language: php :dedent: @@ -203,7 +215,7 @@ settings in the following ways: Tag Sets ~~~~~~~~ -In {+mdb-server+}, you can apply key-value :manual:`tags +The {+mdb-server+} allows you to apply key-value :manual:`tags ` to replica-set members according to any criteria you choose. You can then use those tags to target one or more members for a read operation. @@ -214,19 +226,20 @@ pass them as a parameter to your ``MongoDB\Driver\ReadPreference`` class constructor. Then, set the ``MongoDB\Driver\ReadPreference`` object as the value of the ``readPreference`` database option. -This code example sets the ``readPreference`` option to a tag set -that instructs ``test_database`` to prefer reads from secondary replica set -members in the following order: +Suppose you are connected to a replica set that contains members hosted +at multiple data centers across the United States. This code example sets +the ``readPreference`` option to a tag set that instructs ``test_database`` +to prefer reads from secondary replica set members in the following order: 1. Members from the New York data center (``['dc' => 'ny']``) #. Members from the San Francisco data center (``['dc' => 'sf']``) #. Any secondary members (``[]``) .. literalinclude:: /includes/databases-collections/databases-collections.php - :language: php - :dedent: - :start-after: start-tag-set - :end-before: end-tag-set + :language: php + :dedent: + :start-after: start-tag-set + :end-before: end-tag-set .. _php-local-threshold: From 1bcd46eab1bd04c41ed4fb85c669015158798fc9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 24 Sep 2024 10:17:37 -0400 Subject: [PATCH 09/11] api docs --- source/read-write-pref.txt | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/source/read-write-pref.txt b/source/read-write-pref.txt index d042abe6..a65ff5b5 100644 --- a/source/read-write-pref.txt +++ b/source/read-write-pref.txt @@ -273,25 +273,16 @@ within 35 milliseconds of the closest member's ping time. :manual:`localThreshold ` command-line option. - -Additional Information ----------------------- - -To learn more about read preferences and read and write concerns, see the -following guides in the {+mdb-server+} manual: - -- :manual:`Read Preference ` -- :manual:`Read Concern ` -- :manual:`Write Concern ` - API Documentation -~~~~~~~~~~~~~~~~~ +----------------- To learn more about any of the methods or types discussed in this -guide, see the following API documentation: +guide, see the following library API documentation: - :phpmethod:`MongoDB\Client::__construct()` - :phpmethod:`MongoDB\Client::startSession()` -- :php:`MongoDB\Driver\Session::startTransaction() ` - :phpmethod:`MongoDB\Client::selectDatabase()` - :phpmethod:`MongoDB\Client::selectCollection()` + +To learn more about the ``startTransaction()`` method, see :php:`MongoDB\Driver\Session::startTransaction() +` in the extension API documentation. From 2f570f5f9a83343fb9bf9a99b8c55815bde36ffa Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 24 Sep 2024 10:20:48 -0400 Subject: [PATCH 10/11] fix --- source/read-write-pref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/read-write-pref.txt b/source/read-write-pref.txt index a65ff5b5..75a81556 100644 --- a/source/read-write-pref.txt +++ b/source/read-write-pref.txt @@ -66,7 +66,7 @@ following methods: Configures transaction-level settings - :ref:`MongoDB\Client::selectDatabase() `: Configures database-level settings -- :ref:`MongoDB\Client::selectCollection() `: Configures read +- :ref:`MongoDB\Client::selectCollection() `: Configures collection-level settings .. _php-read-write-client: From e48c5b4310585ba012bd5b847ec877f7c8a8c269 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 24 Sep 2024 11:54:42 -0400 Subject: [PATCH 11/11] fix --- source/read-write-pref.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/read-write-pref.txt b/source/read-write-pref.txt index 75a81556..fd324f9d 100644 --- a/source/read-write-pref.txt +++ b/source/read-write-pref.txt @@ -235,7 +235,7 @@ to prefer reads from secondary replica set members in the following order: #. Members from the San Francisco data center (``['dc' => 'sf']``) #. Any secondary members (``[]``) -.. literalinclude:: /includes/databases-collections/databases-collections.php +.. literalinclude:: /includes/read-write-pref.php :language: php :dedent: :start-after: start-tag-set @@ -257,7 +257,7 @@ sets the ``localThresholdMS`` option. The following example specifies a local threshold of 35 milliseconds: -.. literalinclude:: /includes/databases-collections/databases-collections.php +.. literalinclude:: /includes/read-write-pref.php :language: php :dedent: :start-after: start-local-threshold