Skip to content

Commit fe3281c

Browse files
mcmorisimcmorisi
committed
DOCSP-45010: Replica Set Operations (#322)
(cherry picked from commit 4e440bf)
1 parent f53ae74 commit fe3281c

File tree

3 files changed

+264
-0
lines changed

3 files changed

+264
-0
lines changed

‎source/fundamentals.txt

+2
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Fundamentals
3030
Time Series Collections </fundamentals/time-series>
3131
In-Use Encryption </fundamentals/encrypt-fields>
3232
Search Geospatially </fundamentals/geo>
33+
Replica Set Operations </fundamentals/read-write-configuration>
3334

3435
- :ref:`Connecting to MongoDB <csharp-connection>`
3536
- :ref:`csharp-db-coll`
@@ -50,3 +51,4 @@ Fundamentals
5051
- :ref:`csharp-time-series`
5152
- :ref:`Encrypt Fields <csharp-fle>`
5253
- :ref:`csharp-geo`
54+
- :ref:`csharp-read-write-config`

‎source/fundamentals/read-write-configuration.txt

+205
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
.. _csharp-read-write-config:
2+
3+
====================================
4+
Configure Operations on Replica Sets
5+
====================================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: configuration, availability, causal consistency, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the **write concern**, **read concern**,
24+
and **read preference** configurations to modify the way that MongoDB runs
25+
create, read, update, and delete (CRUD) operations on replica sets.
26+
27+
You can set these configurations at the following levels:
28+
29+
1. Client, which sets the default for all operation executions unless overridden
30+
#. Transaction
31+
#. Database
32+
#. Collection
33+
34+
This list is in increasing order of precedence. For example, if you set
35+
read concerns at both the client and the database levels, the read
36+
concern specified at the database level overrides the read concern at the
37+
client level.
38+
39+
Write Concern
40+
-------------
41+
42+
Write concern specifies the level of acknowledgement requested from MongoDB for
43+
write operations before the operation successfully returns. Operations that
44+
don't specify an explicit write concern inherit the global default write concern
45+
setting.
46+
47+
You can set the write concern by setting the ``WriteConcern`` option on a
48+
``MongoClientSettings``, ``MongoDatabaseSettings``, or ``MongoCollectionSettings`` object,
49+
or by using the ``WithWriteConcern()`` method of a client, database, or collection instance.
50+
51+
The ``WriteConcern`` option and ``WithWriteConcern()`` method accept a
52+
``WriteConcern`` instance as a parameter. You can specify the write concern by
53+
using one of the following values:
54+
55+
- ``WriteConcern.Acknowledged``: The write operation returns after the operation
56+
is written to memory.
57+
- ``WriteConcern.W1``: The write operation returns after only the primary node acknowledges
58+
the write operation, without waiting for acknowledgement from secondary nodes.
59+
- ``WriteConcern.W2``: The write operation returns after the primary node and
60+
at least one secondary node acknowledge the write operation.
61+
- ``WriteConcern.W3``: The write operation returns after the primary node and
62+
at least two secondary nodes acknowledge the write operation.
63+
- ``WriteConcern.WMajority``: The write operation returns after a majority of the
64+
replica set members acknowledge the write operation.
65+
- ``WriteConcern.Unacknowledged``: The write operation returns after the primary
66+
node processes the write operation.
67+
68+
The following example sets the write concern to ``WriteConcern.WMajority`` for an instance of
69+
``MongoClient``:
70+
71+
.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs
72+
:start-after: start-write-concern-client
73+
:end-before: end-write-concern-client
74+
:language: csharp
75+
:dedent:
76+
77+
The following example sets the write concern to ``WriteConcern.WMajority`` for a collection:
78+
79+
.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs
80+
:start-after: start-write-concern-collection
81+
:end-before: end-write-concern-collection
82+
:language: csharp
83+
:dedent:
84+
85+
.. note:: Clients, Collections, and Databases are Immutable
86+
87+
``IMongoClient``, ``IMongoDatabase``, and ``IMongoCollection`` instances are immutable.
88+
When you set the write concern on a client, database, or collection, the method returns a new
89+
instance with the specified settings and does not affect the original instance.
90+
91+
For more information about write concern, see :manual:`Write Concern
92+
</reference/write-concern/>` in the {+mdb-server+} manual.
93+
94+
Read Concern
95+
------------
96+
97+
Read concern specifies the following behaviors:
98+
99+
- Level of :manual:`causal consistency
100+
</core/causal-consistency-read-write-concerns>` across replica sets
101+
- :manual:`Isolation guarantees </core/read-isolation-consistency-recency/>` maintained
102+
during a query
103+
104+
You can specify the read concern by setting the ``ReadConcern`` option on a
105+
``MongoClientSettings``, ``MongoDatabaseSettings``, or ``MongoCollectionSettings`` object,
106+
or by using the ``WithReadConcern()`` method on a client, database, or collection.
107+
108+
The ``ReadConcern`` option and ``WithReadConcern()`` method both accept a single parameter
109+
that specifies the read concern level.
110+
111+
You can set the following read concern levels:
112+
113+
- ``ReadConcern.Local``: The query returns the instance's most recent data. Provides no guarantee
114+
that the data has been written to a majority of the replica set members.
115+
- ``ReadConern.Available``: The query returns the instance's most recent data.
116+
Provides no guarantee that the data has been written to a majority of the
117+
replica set members. ``ReadConcern.Available`` is not available for use with
118+
causally consistent sessions and transactions.
119+
- ``ReadConcern.Majority``: The query returns data that has been acknowledged by
120+
a majority of the replica set members.
121+
- ``ReadConcern.Linearizable``: The query returns data that reflects all
122+
successful writes that completed before the start of the read operation.
123+
``ReadConcern.Linearizable`` is not available for use with causally consistent
124+
sessions and transactions.
125+
- ``ReadConcern.Snapshot``: The query returns majority-committed data as it appears across shards, from a
126+
specific single point in the recent past.
127+
128+
For more information about the read concern levels, see :manual:`Read Concern
129+
Levels </reference/read-concern/#read-concern-levels>` in the {+mdb-server+}
130+
manual.
131+
132+
The following example sets the read concern to ``ReadConcern.Majority`` for an instance of
133+
``MongoClient``:
134+
135+
.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs
136+
:start-after: start-read-concern-client
137+
:end-before: end-read-concern-client
138+
:language: csharp
139+
:dedent:
140+
141+
The following example sets the read concern to ``ReadConcern.Majority`` for a
142+
collection:
143+
144+
.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs
145+
:start-after: start-read-concern-collection
146+
:end-before: end-read-concern-collection
147+
:language: csharp
148+
:dedent:
149+
150+
To learn more about read concern, see :manual:`Read Concern
151+
</reference/read-concern>` in the {+mdb-server+} manual.
152+
153+
Read Preference
154+
---------------
155+
156+
Read preference determines which member of a replica set MongoDB reads when
157+
running a query. You can set the read preference by setting the ``ReadPreference`` option on a
158+
``MongoClientSettings``, ``MongoDatabaseSettings``, or ``MongoCollectionSettings`` object,
159+
or by using the ``WithReadPreference()`` method on a client, database, or collection.
160+
161+
The ``ReadPreference`` option and ``WithReadPreference()`` method accept a read
162+
preference mode as a parameter. You can set the read preference mode to one of
163+
the following values:
164+
165+
- ``ReadPreference.Primary``: The query returns data from the primary node.
166+
- ``ReadPreference.PrimaryPreferred``: The query returns data from the primary node if
167+
available. Otherwise, the query returns data from a secondary node.
168+
- ``ReadPreference.Secondary``: The query returns data from a secondary node.
169+
- ``ReadPreference.SecondaryPreferred``: The query returns data from a secondary node if
170+
available, Otherwise, the query returns data from the primary node.
171+
- ``ReadPreference.Nearest``: The query returns data from the node with the lowest
172+
network latency.
173+
174+
The following example sets the read preference to ``ReadPreference.Secondary``
175+
for an instance of ``MongoClient``:
176+
177+
.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs
178+
:start-after: start-read-preference-client
179+
:end-before: end-read-preference-client
180+
:language: csharp
181+
:dedent:
182+
183+
The following example sets the read preference to ``ReadPreference.Secondary`` for a collection:
184+
185+
.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs
186+
:start-after: start-read-preference-collection
187+
:end-before: end-read-preference-collection
188+
:language: csharp
189+
:dedent:
190+
191+
For more information about read preference, see :manual:`Read Preference
192+
</core/read-preference/>` in the {+mdb-server+} manual.
193+
194+
API Documentation
195+
-----------------
196+
197+
To learn more about any of the types discussed in this
198+
guide, see the following API documentation:
199+
200+
- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__
201+
- `MongoDatabaseSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoDatabaseSettings.html>`__
202+
- `MongoCollectionSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCollectionSettings.html>`__
203+
- `WriteConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.WriteConcern.html>`__
204+
- `ReadConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcern.html>`__
205+
- `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`__

‎source/includes/fundamentals/code-examples/ReplicaSetConfigs.cs

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
using MongoDB.Bson;
2+
using MongoDB.Driver;
3+
4+
public class ReplicaSetConfigs
5+
{
6+
public static void Main(string[] args)
7+
{
8+
var client = new MongoClient("mongodb://localhost:27017");
9+
{
10+
// start-write-concern-client
11+
var mongoClientSettings = MongoClientSettings.FromConnectionString("<connection string URI>");
12+
mongoClientSettings.WriteConcern = WriteConcern.WMajority;
13+
var mongoClient = new MongoClient(mongoClientSettings);
14+
// end-write-concern-client
15+
}
16+
17+
{
18+
var database = client.GetDatabase("test");
19+
// start-write-concern-collection
20+
var collection = database.GetCollection<BsonDocument>("<collection name>")
21+
.WithWriteConcern(WriteConcern.WMajority);
22+
// end-write-concern-collection
23+
}
24+
25+
{
26+
// start-read-concern-client
27+
var mongoClientSettings = MongoClientSettings.FromConnectionString("<connection string URI>");
28+
mongoClientSettings.ReadConcern = ReadConcern.Majority;
29+
var mongoClient = new MongoClient(mongoClientSettings);
30+
// end-read-concern-client
31+
}
32+
33+
{
34+
var database = client.GetDatabase("test");
35+
// start-read-concern-collection
36+
var collection = database.GetCollection<BsonDocument>("<collection name>")
37+
.WithReadConcern(ReadConcern.Majority);
38+
// end-read-concern-collection
39+
}
40+
41+
{
42+
// start-read-preference-client
43+
var mongoClientSettings = MongoClientSettings.FromConnectionString("<connection string URI>");
44+
mongoClientSettings.ReadPreference = ReadPreference.Secondary;
45+
var mongoClient = new MongoClient(mongoClientSettings);
46+
// end-read-preference-client
47+
}
48+
49+
{
50+
var database = client.GetDatabase("test");
51+
// start-read-preference-collection
52+
var collection = database.GetCollection<BsonDocument>("<collection name>")
53+
.WithReadPreference(ReadPreference.Secondary);
54+
// end-read-preference-collection
55+
}
56+
}
57+
}

0 commit comments

Comments
 (0)