From 62e6486763f93f8dd1c092a601fa8fe9849e9ea6 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 21 Nov 2024 16:41:48 -0500 Subject: [PATCH 1/5] DOCSP-45010: Replica Set Operations --- source/fundamentals.txt | 1 + .../fundamentals/read-write-configuration.txt | 199 ++++++++++++++++++ .../code-examples/ReplicaSetConfigs.cs | 54 +++++ 3 files changed, 254 insertions(+) create mode 100644 source/fundamentals/read-write-configuration.txt create mode 100644 source/includes/fundamentals/code-examples/ReplicaSetConfigs.cs diff --git a/source/fundamentals.txt b/source/fundamentals.txt index 2dcad614..5ddcc935 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -30,6 +30,7 @@ Fundamentals Time Series Collections In-Use Encryption Search Geospatially + Replica Set Operations - :ref:`Connecting to MongoDB ` - :ref:`csharp-db-coll` diff --git a/source/fundamentals/read-write-configuration.txt b/source/fundamentals/read-write-configuration.txt new file mode 100644 index 00000000..2ffe6c43 --- /dev/null +++ b/source/fundamentals/read-write-configuration.txt @@ -0,0 +1,199 @@ +.. _csharp-read-write-config: + +==================================== +Configure Operations on Replica Sets +==================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: configuration, availability, causal consistency, code example + +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 these configurations at the following levels: + +1. Client, which sets the default for all operation executions unless overridden +#. Transaction +#. Database +#. Collection + +This list is in increasing order of precedence. For example, if you set +read concerns at both the client and the database levels, the read +concern specified at the database level overrides the read concern at the +client level. + +Write Concern +------------- + +Write concern specifies the level of acknowledgement requested from MongoDB for +write operations before the operation successfully returns. Operations that +don't specify an explicit write concern inherit the global default write concern +setting. + +You can set the write concern by setting the ``WriteConcern`` option on a +``MongoClientSettings``, ``MongoDatabaseSettings``, or ``MongoCollectionSettings`` object, +or by using the ``WithWriteConcern()`` method of a client, database, or collection instance. + +The ``WriteConcern`` option and ``WithWriteConcern()`` method both accept a +``WriteConcern`` instance as a parameter. You can specify the write concern by +using one of the following values: + +- ``WriteConcern.Acknowledged``: The write operation returns after the operation + is written to memory. +- ``WriteConcern.W1``: The write operation returns after only the primary node acknowledges + the write operation, without waiting for acknowledgement from secondary nodes. +- ``WriteConcern.W2``: The write operation returns after the primary node and + at least one secondary node acknowledge the write operation. +- ``WriteConcern.W3``: The write operation returns after the primary node and + at least two secondary nodes acknowledge the write operation. +- ``WriteConcern.WMajority``: The write operation returns after a majority of the + replica set members acknowledge the write operation. +- ``WriteConcern.Unacknowledged``: The write operation returns after the primary + node processes the write operation. + +The following example sets the write concern to ``"majority"`` for an instance of +``MongoClient``: + +.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs + :start-after: start-write-concern-client + :end-before: end-write-concern-client + :language: csharp + +The following example sets the write concern to ``"majority"`` for a collection: + +.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs + :start-after: start-write-concern-collection + :end-before: end-write-concern-collection + :language: csharp + +.. note:: Collections and Databases are Immutable + + ``IMongoDatabase`` and ``IMongoCollection`` instances are immutable. When you + set the write concern on a database or collection, the method returns a new + instance and does not affect the original instance. + +For more information about write concern, see :manual:`Write Concern +` in the {+mdb-server+} manual. + +Read Concern +------------ + +Read concern specifies the following behaviors: + +- Level of :manual:`causal consistency + ` across replica sets +- :manual:`Isolation guarantees ` maintained + during a query + +You can specify the read concern by setting the ``ReadConcern`` option on a +``MongoClientSettings``, ``MongoDatabaseSettings``, or ``MongoCollectionSettings`` object, +or by using the ``WithReadConcern()`` method on a client, database, or collection. + +The ``ReadConcern`` option and ``WithReadConcern()`` method both accept a single parameter +that specifies the read concern level. + +You can set the following read concern levels: + +- ``ReadConcern.Local``: 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. +- ``ReadConern.Available``: 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. ``ReadConcern.AVAILABLE`` is not available for use with + causally consistent sessions and transactions. +- ``ReadConcern.Majority``: The query returns data that has been acknowledged by + a majority of the replica set members. +- ``ReadConcern.Linearizable``: The query returns data that reflects all + successful writes that completed before the start of the read operation. + ``ReadConcern.Linearizable`` is not available for use with causally consistent + sessions and transactions. +- ``ReadConcern.Snapshot``: The query returns majority-committed data as it appears across shards, from a + specific single point in the recent past. + +For more information about the read concern levels, see :manual:`Read Concern +Levels ` in the {+mdb-server+} +manual. + +The following example sets the read concern to ``"majority"`` for an instance of +``MongoClient``: + +.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs + :start-after: start-read-concern-client + :end-before: end-read-concern-client + :language: csharp + +The following example sets the read concern to ``"majority"`` for a +collection: + +.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs + :start-after: start-read-concern-collection + :end-before: end-read-concern-collection + :language: csharp + +To learn more about read concern, see :manual:`Read Concern +` in the {+mdb-server+} manual. + +Read Preference +--------------- + +Read preference determines which member of a replica set MongoDB reads when +running a query. You can set the read preference by setting the ``ReadPreference`` option on a +``MongoClientSettings``, ``MongoDatabaseSettings``, or ``MongoCollectionSettings`` object, +or by using the ``WithReadPreference()`` method on a client, database, or collection. + +The ``ReadPreference`` option and ``WithReadPreference()`` method accept a read +preference mode as a parameter. You can set the read preference mode to one of +the following values: + +- ``ReadPreference.Primary``: The query returns data from the primary node. +- ``ReadPreference.PrimaryPreferred``: The query returns data from the primary node if + available. Otherwise, the query returns data from a secondary node. +- ``ReadPreference.Secondary``: The query returns data from a secondary node. +- ``ReadPreference.SecondaryPreferred``: The query returns data from a secondary node if + available, Otherwise, the query returns data from the primary node. +- ``ReadPreference.Nearest``: The query returns data from the node with the lowest + network latency. + +The following example sets the read preference to ``"secondary"`` +for an instance of ``MongoClient``: + +.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs + :start-after: start-read-preference-client + :end-before: end-read-preference-client + :language: csharp + +The following example sets the read preference to ``"secondary"`` for a collection: + +.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs + :start-after: start-read-preference-collection + :end-before: end-read-preference-collection + :language: csharp + +For more information about read preference, see :manual:`Read Preference +` in the {+mdb-server+} manual. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__ +- `MongoDatabaseSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoDatabaseSettings.html>`__ +- `MongoCollectionSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCollectionSettings.html>`__ +- `WriteConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.WriteConcern.html>`__ +- `ReadConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcern.html>`__ +- `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`__ \ No newline at end of file diff --git a/source/includes/fundamentals/code-examples/ReplicaSetConfigs.cs b/source/includes/fundamentals/code-examples/ReplicaSetConfigs.cs new file mode 100644 index 00000000..e15c72a6 --- /dev/null +++ b/source/includes/fundamentals/code-examples/ReplicaSetConfigs.cs @@ -0,0 +1,54 @@ +using MongoDB.Bson; +using MongoDB.Driver; + +public class ReplicaSetConfigs +{ + public static void Main(string[] args) + { + var client = new MongoClient("mongodb://localhost:27017"); + { + // start-write-concern-client + var mongoClientSettings = MongoClientSettings.FromConnectionString(""); + mongoClientSettings.WriteConcern = WriteConcern.WMajority; + var mongoClient = new MongoClient(mongoClientSettings); + // end-write-concern-client + } + + { + var database = client.GetDatabase("test"); + // start-write-concern-collection + var collection = database.GetCollection("").WithWriteConcern(WriteConcern.WMajority); + // end-write-concern-collection + } + + { + // start-read-concern-client + var mongoClientSettings = MongoClientSettings.FromConnectionString(""); + mongoClientSettings.ReadConcern = ReadConcern.Majority; + var mongoClient = new MongoClient(mongoClientSettings); + // end-read-concern-client + } + + { + var database = client.GetDatabase("test"); + // start-read-concern-collection + var collection = database.GetCollection("").WithReadConcern(ReadConcern.Majority); + // end-read-concern-collection + } + + { + // start-read-preference-client + var mongoClientSettings = MongoClientSettings.FromConnectionString(""); + mongoClientSettings.ReadPreference = ReadPreference.Secondary; + var mongoClient = new MongoClient(mongoClientSettings); + // end-read-preference-client + } + + { + var database = client.GetDatabase("test"); + // start-read-preference-collection + var collection = database.GetCollection("").WithReadPreference(ReadPreference.Secondary); + // end-read-preference-collection + } + } +} \ No newline at end of file From 915ec54bf0ac8f239fbc9c55e44ecebd32eeba86 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 21 Nov 2024 16:48:15 -0500 Subject: [PATCH 2/5] Fix --- source/fundamentals/read-write-configuration.txt | 8 +++++++- .../fundamentals/code-examples/ReplicaSetConfigs.cs | 9 ++++++--- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/read-write-configuration.txt b/source/fundamentals/read-write-configuration.txt index 2ffe6c43..ca3c19a3 100644 --- a/source/fundamentals/read-write-configuration.txt +++ b/source/fundamentals/read-write-configuration.txt @@ -72,6 +72,7 @@ The following example sets the write concern to ``"majority"`` for an instance o :start-after: start-write-concern-client :end-before: end-write-concern-client :language: csharp + :dedent: The following example sets the write concern to ``"majority"`` for a collection: @@ -79,6 +80,7 @@ The following example sets the write concern to ``"majority"`` for a collection: :start-after: start-write-concern-collection :end-before: end-write-concern-collection :language: csharp + :dedent: .. note:: Collections and Databases are Immutable @@ -134,6 +136,7 @@ The following example sets the read concern to ``"majority"`` for an instance of :start-after: start-read-concern-client :end-before: end-read-concern-client :language: csharp + :dedent: The following example sets the read concern to ``"majority"`` for a collection: @@ -142,6 +145,7 @@ collection: :start-after: start-read-concern-collection :end-before: end-read-concern-collection :language: csharp + :dedent: To learn more about read concern, see :manual:`Read Concern ` in the {+mdb-server+} manual. @@ -174,6 +178,7 @@ for an instance of ``MongoClient``: :start-after: start-read-preference-client :end-before: end-read-preference-client :language: csharp + :dedent: The following example sets the read preference to ``"secondary"`` for a collection: @@ -181,6 +186,7 @@ The following example sets the read preference to ``"secondary"`` for a collecti :start-after: start-read-preference-collection :end-before: end-read-preference-collection :language: csharp + :dedent: For more information about read preference, see :manual:`Read Preference ` in the {+mdb-server+} manual. @@ -188,7 +194,7 @@ For more information about read preference, see :manual:`Read Preference API Documentation ----------------- -To learn more about any of the methods or types discussed in this +To learn more about any of the types discussed in this guide, see the following API documentation: - `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__ diff --git a/source/includes/fundamentals/code-examples/ReplicaSetConfigs.cs b/source/includes/fundamentals/code-examples/ReplicaSetConfigs.cs index e15c72a6..fcb35edd 100644 --- a/source/includes/fundamentals/code-examples/ReplicaSetConfigs.cs +++ b/source/includes/fundamentals/code-examples/ReplicaSetConfigs.cs @@ -17,7 +17,8 @@ public static void Main(string[] args) { var database = client.GetDatabase("test"); // start-write-concern-collection - var collection = database.GetCollection("").WithWriteConcern(WriteConcern.WMajority); + var collection = database.GetCollection("") + .WithWriteConcern(WriteConcern.WMajority); // end-write-concern-collection } @@ -32,7 +33,8 @@ public static void Main(string[] args) { var database = client.GetDatabase("test"); // start-read-concern-collection - var collection = database.GetCollection("").WithReadConcern(ReadConcern.Majority); + var collection = database.GetCollection("") + .WithReadConcern(ReadConcern.Majority); // end-read-concern-collection } @@ -47,7 +49,8 @@ public static void Main(string[] args) { var database = client.GetDatabase("test"); // start-read-preference-collection - var collection = database.GetCollection("").WithReadPreference(ReadPreference.Secondary); + var collection = database.GetCollection("") + .WithReadPreference(ReadPreference.Secondary); // end-read-preference-collection } } From 2794486dc19ae4aa123aa2db808f059b2fb7c5e6 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 21 Nov 2024 16:49:34 -0500 Subject: [PATCH 3/5] Fix --- source/fundamentals/read-write-configuration.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/fundamentals/read-write-configuration.txt b/source/fundamentals/read-write-configuration.txt index ca3c19a3..08d68f35 100644 --- a/source/fundamentals/read-write-configuration.txt +++ b/source/fundamentals/read-write-configuration.txt @@ -65,7 +65,7 @@ using one of the following values: - ``WriteConcern.Unacknowledged``: The write operation returns after the primary node processes the write operation. -The following example sets the write concern to ``"majority"`` for an instance of +The following example sets the write concern to ``WriteConcern.WMajority`` for an instance of ``MongoClient``: .. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs @@ -74,7 +74,7 @@ The following example sets the write concern to ``"majority"`` for an instance o :language: csharp :dedent: -The following example sets the write concern to ``"majority"`` for a collection: +The following example sets the write concern to ``WriteConcern.WMajority`` for a collection: .. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs :start-after: start-write-concern-collection @@ -129,7 +129,7 @@ For more information about the read concern levels, see :manual:`Read Concern Levels ` in the {+mdb-server+} manual. -The following example sets the read concern to ``"majority"`` for an instance of +The following example sets the read concern to ``ReadConcern.Majority`` for an instance of ``MongoClient``: .. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs @@ -138,7 +138,7 @@ The following example sets the read concern to ``"majority"`` for an instance of :language: csharp :dedent: -The following example sets the read concern to ``"majority"`` for a +The following example sets the read concern to ``ReadConcern.Majority`` for a collection: .. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs @@ -171,7 +171,7 @@ the following values: - ``ReadPreference.Nearest``: The query returns data from the node with the lowest network latency. -The following example sets the read preference to ``"secondary"`` +The following example sets the read preference to ``ReadPreference.Secondary`` for an instance of ``MongoClient``: .. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs @@ -180,7 +180,7 @@ for an instance of ``MongoClient``: :language: csharp :dedent: -The following example sets the read preference to ``"secondary"`` for a collection: +The following example sets the read preference to ``ReadPreference.Secondary`` for a collection: .. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs :start-after: start-read-preference-collection From 5aa29c01ea18aabf310d245b333b4298c252df69 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 22 Nov 2024 09:18:12 -0500 Subject: [PATCH 4/5] SA feedback --- source/fundamentals.txt | 1 + source/fundamentals/read-write-configuration.txt | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/source/fundamentals.txt b/source/fundamentals.txt index 5ddcc935..181bd766 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -51,3 +51,4 @@ Fundamentals - :ref:`csharp-time-series` - :ref:`Encrypt Fields ` - :ref:`csharp-geo` +- :ref:`csharp-read-write-config` diff --git a/source/fundamentals/read-write-configuration.txt b/source/fundamentals/read-write-configuration.txt index 08d68f35..4f37ab0b 100644 --- a/source/fundamentals/read-write-configuration.txt +++ b/source/fundamentals/read-write-configuration.txt @@ -48,7 +48,7 @@ You can set the write concern by setting the ``WriteConcern`` option on a ``MongoClientSettings``, ``MongoDatabaseSettings``, or ``MongoCollectionSettings`` object, or by using the ``WithWriteConcern()`` method of a client, database, or collection instance. -The ``WriteConcern`` option and ``WithWriteConcern()`` method both accept a +The ``WriteConcern`` option and ``WithWriteConcern()`` method accept a ``WriteConcern`` instance as a parameter. You can specify the write concern by using one of the following values: @@ -114,7 +114,7 @@ You can set the following read concern levels: that the data has been written to a majority of the replica set members. - ``ReadConern.Available``: 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. ``ReadConcern.AVAILABLE`` is not available for use with + replica set members. ``ReadConcern.Available`` is not available for use with causally consistent sessions and transactions. - ``ReadConcern.Majority``: The query returns data that has been acknowledged by a majority of the replica set members. @@ -148,7 +148,7 @@ collection: :dedent: To learn more about read concern, see :manual:`Read Concern -` in the {+mdb-server+} manual. +` in the {+mdb-server+} manual. Read Preference --------------- From 9c7326cb40a981924b103cab4a732f5c25bf353d Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 25 Nov 2024 16:30:22 -0500 Subject: [PATCH 5/5] Address technical feedback --- source/fundamentals/read-write-configuration.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/read-write-configuration.txt b/source/fundamentals/read-write-configuration.txt index 4f37ab0b..01ea55ed 100644 --- a/source/fundamentals/read-write-configuration.txt +++ b/source/fundamentals/read-write-configuration.txt @@ -82,11 +82,11 @@ The following example sets the write concern to ``WriteConcern.WMajority`` for a :language: csharp :dedent: -.. note:: Collections and Databases are Immutable +.. note:: Clients, Collections, and Databases are Immutable - ``IMongoDatabase`` and ``IMongoCollection`` instances are immutable. When you - set the write concern on a database or collection, the method returns a new - instance and does not affect the original instance. + ``IMongoClient``, ``IMongoDatabase``, and ``IMongoCollection`` instances are immutable. + When you set the write concern on a client, database, or collection, the method returns a new + instance with the specified settings and does not affect the original instance. For more information about write concern, see :manual:`Write Concern ` in the {+mdb-server+} manual.