Skip to content

Commit 62e6486

Browse files
mcmorisimcmorisi
committed
DOCSP-45010: Replica Set Operations
1 parent 37c7a77 commit 62e6486

File tree

3 files changed

+254
-0
lines changed

3 files changed

+254
-0
lines changed

‎source/fundamentals.txt

+1
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`

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

+199
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
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 both 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 ``"majority"`` 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+
76+
The following example sets the write concern to ``"majority"`` for a collection:
77+
78+
.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs
79+
:start-after: start-write-concern-collection
80+
:end-before: end-write-concern-collection
81+
:language: csharp
82+
83+
.. note:: Collections and Databases are Immutable
84+
85+
``IMongoDatabase`` and ``IMongoCollection`` instances are immutable. When you
86+
set the write concern on a database or collection, the method returns a new
87+
instance and does not affect the original instance.
88+
89+
For more information about write concern, see :manual:`Write Concern
90+
</reference/write-concern/>` in the {+mdb-server+} manual.
91+
92+
Read Concern
93+
------------
94+
95+
Read concern specifies the following behaviors:
96+
97+
- Level of :manual:`causal consistency
98+
</core/causal-consistency-read-write-concerns>` across replica sets
99+
- :manual:`Isolation guarantees </core/read-isolation-consistency-recency/>` maintained
100+
during a query
101+
102+
You can specify the read concern by setting the ``ReadConcern`` option on a
103+
``MongoClientSettings``, ``MongoDatabaseSettings``, or ``MongoCollectionSettings`` object,
104+
or by using the ``WithReadConcern()`` method on a client, database, or collection.
105+
106+
The ``ReadConcern`` option and ``WithReadConcern()`` method both accept a single parameter
107+
that specifies the read concern level.
108+
109+
You can set the following read concern levels:
110+
111+
- ``ReadConcern.Local``: The query returns the instance's most recent data. Provides no guarantee
112+
that the data has been written to a majority of the replica set members.
113+
- ``ReadConern.Available``: The query returns the instance's most recent data.
114+
Provides no guarantee that the data has been written to a majority of the
115+
replica set members. ``ReadConcern.AVAILABLE`` is not available for use with
116+
causally consistent sessions and transactions.
117+
- ``ReadConcern.Majority``: The query returns data that has been acknowledged by
118+
a majority of the replica set members.
119+
- ``ReadConcern.Linearizable``: The query returns data that reflects all
120+
successful writes that completed before the start of the read operation.
121+
``ReadConcern.Linearizable`` is not available for use with causally consistent
122+
sessions and transactions.
123+
- ``ReadConcern.Snapshot``: The query returns majority-committed data as it appears across shards, from a
124+
specific single point in the recent past.
125+
126+
For more information about the read concern levels, see :manual:`Read Concern
127+
Levels </reference/read-concern/#read-concern-levels>` in the {+mdb-server+}
128+
manual.
129+
130+
The following example sets the read concern to ``"majority"`` for an instance of
131+
``MongoClient``:
132+
133+
.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs
134+
:start-after: start-read-concern-client
135+
:end-before: end-read-concern-client
136+
:language: csharp
137+
138+
The following example sets the read concern to ``"majority"`` for a
139+
collection:
140+
141+
.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs
142+
:start-after: start-read-concern-collection
143+
:end-before: end-read-concern-collection
144+
:language: csharp
145+
146+
To learn more about read concern, see :manual:`Read Concern
147+
<reference/read-concern>` in the {+mdb-server+} manual.
148+
149+
Read Preference
150+
---------------
151+
152+
Read preference determines which member of a replica set MongoDB reads when
153+
running a query. You can set the read preference by setting the ``ReadPreference`` option on a
154+
``MongoClientSettings``, ``MongoDatabaseSettings``, or ``MongoCollectionSettings`` object,
155+
or by using the ``WithReadPreference()`` method on a client, database, or collection.
156+
157+
The ``ReadPreference`` option and ``WithReadPreference()`` method accept a read
158+
preference mode as a parameter. You can set the read preference mode to one of
159+
the following values:
160+
161+
- ``ReadPreference.Primary``: The query returns data from the primary node.
162+
- ``ReadPreference.PrimaryPreferred``: The query returns data from the primary node if
163+
available. Otherwise, the query returns data from a secondary node.
164+
- ``ReadPreference.Secondary``: The query returns data from a secondary node.
165+
- ``ReadPreference.SecondaryPreferred``: The query returns data from a secondary node if
166+
available, Otherwise, the query returns data from the primary node.
167+
- ``ReadPreference.Nearest``: The query returns data from the node with the lowest
168+
network latency.
169+
170+
The following example sets the read preference to ``"secondary"``
171+
for an instance of ``MongoClient``:
172+
173+
.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs
174+
:start-after: start-read-preference-client
175+
:end-before: end-read-preference-client
176+
:language: csharp
177+
178+
The following example sets the read preference to ``"secondary"`` for a collection:
179+
180+
.. literalinclude:: /includes/fundamentals/code-examples/ReplicaSetConfigs.cs
181+
:start-after: start-read-preference-collection
182+
:end-before: end-read-preference-collection
183+
:language: csharp
184+
185+
For more information about read preference, see :manual:`Read Preference
186+
</core/read-preference/>` in the {+mdb-server+} manual.
187+
188+
API Documentation
189+
-----------------
190+
191+
To learn more about any of the methods or types discussed in this
192+
guide, see the following API documentation:
193+
194+
- `MongoClientSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoClientSettings.html>`__
195+
- `MongoDatabaseSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoDatabaseSettings.html>`__
196+
- `MongoCollectionSettings <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCollectionSettings.html>`__
197+
- `WriteConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.WriteConcern.html>`__
198+
- `ReadConcern <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadConcern.html>`__
199+
- `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`__

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

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
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>").WithWriteConcern(WriteConcern.WMajority);
21+
// end-write-concern-collection
22+
}
23+
24+
{
25+
// start-read-concern-client
26+
var mongoClientSettings = MongoClientSettings.FromConnectionString("<connection string URI>");
27+
mongoClientSettings.ReadConcern = ReadConcern.Majority;
28+
var mongoClient = new MongoClient(mongoClientSettings);
29+
// end-read-concern-client
30+
}
31+
32+
{
33+
var database = client.GetDatabase("test");
34+
// start-read-concern-collection
35+
var collection = database.GetCollection<BsonDocument>("<collection name>").WithReadConcern(ReadConcern.Majority);
36+
// end-read-concern-collection
37+
}
38+
39+
{
40+
// start-read-preference-client
41+
var mongoClientSettings = MongoClientSettings.FromConnectionString("<connection string URI>");
42+
mongoClientSettings.ReadPreference = ReadPreference.Secondary;
43+
var mongoClient = new MongoClient(mongoClientSettings);
44+
// end-read-preference-client
45+
}
46+
47+
{
48+
var database = client.GetDatabase("test");
49+
// start-read-preference-collection
50+
var collection = database.GetCollection<BsonDocument>("<collection name>").WithReadPreference(ReadPreference.Secondary);
51+
// end-read-preference-collection
52+
}
53+
}
54+
}

0 commit comments

Comments
 (0)