Skip to content

Commit f7f34e9

Browse files
rustagirrustagir
authored
DOCSP-13849: Modify CRUD op execution (#159)
* DOCSP-13849-crud-modification-pg * first pass fixes * code fixes * indent fix * PR comments 1 * last PR comments
1 parent 8e026fc commit f7f34e9

File tree

2 files changed

+272
-0
lines changed

2 files changed

+272
-0
lines changed

‎source/fundamentals/crud.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ CRUD Operations
1212
/fundamentals/crud/read-operations
1313
/fundamentals/crud/write-operations
1414
/fundamentals/crud/compound-operations
15+
/fundamentals/crud/write-read-pref.txt
1516

1617
CRUD (Create, Read, Update, Delete) operations enable you to work with
1718
data stored in MongoDB.
@@ -23,3 +24,5 @@ data stored in MongoDB.
2324

2425
Some operations combine aspects of read and write operations. To learn
2526
more about these hybrid methods, see :ref:`golang-compound-operations`.
27+
28+
To learn about how to modify the way your CRUD operations execute, see :ref:`golang-write-read-pref`.

‎source/fundamentals/crud/write-read-pref.txt

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
.. _golang-write-read-pref:
2+
3+
===================================
4+
Modify Execution of CRUD Operations
5+
===================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Overview
16+
--------
17+
18+
In this guide, you can learn how to modify the way that the {+driver-long+}
19+
executes create, read, update, and delete (CRUD) operations using
20+
**write concern**, **read concern**, and **read preference** configurations
21+
for replica sets.
22+
23+
You can set write concern, read concern, and read preference options at
24+
the following levels:
25+
26+
- Client level, which sets the *default for all operation executions*
27+
unless overridden
28+
- Session level
29+
- Transaction level
30+
- Database level
31+
- Collection level
32+
- Query level
33+
34+
You should read this guide if you need to customize the consistency and
35+
availability of the data in your replica sets.
36+
37+
Write Concern
38+
-------------
39+
40+
A write concern describes the number of data-bearing
41+
members in a replica set that must acknowledge a write operation, such
42+
as an insert or update, before the operation is returned as successful.
43+
By default, the write concern requires only the primary
44+
replica set member to acknowledge the write operation before the
45+
operation is deemed successful.
46+
47+
Options
48+
~~~~~~~
49+
50+
The {+driver-long+} provides the ``writeconcern`` package, which lets
51+
you specify the write concern for a replica set. Set the write
52+
concern using the ``SetWriteConcern()`` method with an ``Option``
53+
type. The ``Option`` type has the following methods to specify the
54+
write concern:
55+
56+
.. list-table::
57+
:widths: 25 75
58+
:header-rows: 1
59+
60+
* - Method
61+
- Description
62+
63+
* - ``J()``
64+
- | The client requests acknowledgement that write operations are written to the
65+
journal. For more information, see the
66+
:rapid:`Write Concern specification </reference/write-concern/#j-option>`.
67+
|
68+
| **Parameter**: ``bool``
69+
70+
* - ``W()``
71+
- | The client requests acknowledgement that write operations propagate to the
72+
specified number of ``mongod`` instances. For more information, see the
73+
:rapid:`Write Concern specification </reference/write-concern/#mongodb-writeconcern-writeconcern.-number->`.
74+
|
75+
| **Parameter**: ``int``
76+
77+
* - ``WMajority()``
78+
- | The client requests acknowledgement that write operations propagate to the
79+
majority of ``mongod`` instances. For more information, see the
80+
:rapid:`Write Concern specification
81+
</reference/write-concern/#mongodb-writeconcern-writeconcern.-majority->`.
82+
|
83+
| **Parameter**: none
84+
85+
* - ``WTagSet()``
86+
- | The client requests acknowledgement that write operations propagate to the
87+
specified ``mongod`` instance. For more
88+
information, see the :rapid:`Write Concern specification
89+
</reference/write-concern/#mongodb-writeconcern-writeconcern.-custom-write-concern-name->`.
90+
|
91+
| **Parameter**: ``string``
92+
93+
.. tip::
94+
95+
You can alternatively specify a write concern in your connection
96+
string. See the :manual:`Server Manual entry on Write Concern Options
97+
</reference/connection-string/#write-concern-options>` for more information.
98+
99+
Example
100+
~~~~~~~
101+
102+
The following code shows how you can specify a write concern to request
103+
acknowledgement from two replica set members. The code then creates a ``Client``
104+
with this option.
105+
106+
.. code-block:: go
107+
:emphasize-lines: 2-3
108+
109+
uri := "mongodb://<hostname>:<port>"
110+
wc := writeconcern.W(2)
111+
opts := options.Client().ApplyURI(uri).SetWriteConcern(writeconcern.New(wc))
112+
client, err := mongo.Connect(context.TODO(), opts)
113+
114+
Read Concern
115+
------------
116+
117+
The read concern option allows you to determine which data the client
118+
returns from a query. The default read concern level is "local", meaning
119+
that the client returns the instance’s most recent data, with no guarantee that
120+
the data has been written to a majority of the replica set members.
121+
122+
Options
123+
~~~~~~~
124+
125+
The {+driver-long+} provides the ``readconcern`` package, which lets
126+
you specify the read concern for a replica set. Set the read concern using the
127+
``SetReadConcern()`` method with a ``ReadConcern`` type. The ``ReadConcern``
128+
type has the following methods to specify the read concern:
129+
130+
.. list-table::
131+
:widths: 25 75
132+
:header-rows: 1
133+
134+
* - Method
135+
- Description
136+
137+
* - ``Available()``
138+
- The query returns data from the instance
139+
with no guarantee that the data has been written to a majority of
140+
the replica set members. For more information, see the
141+
:rapid:`Read Concern specification </reference/read-concern-available/#mongodb-readconcern-readconcern.-available->`.
142+
143+
* - ``Linearizable()``
144+
- The query returns data that reflects all
145+
successful writes issued with a write concern of ``majority`` and
146+
acknowledged prior to the start of the read operation. For more information, see the
147+
:rapid:`Read Concern specification </reference/read-concern-linearizable/#mongodb-readconcern-readconcern.-linearizable->`.
148+
149+
* - ``Local()``
150+
- The query returns the instance’s most recent
151+
data. For more information, see the
152+
:rapid:`Read Concern specification </reference/read-concern-local/#mongodb-readconcern-readconcern.-local->`.
153+
154+
* - ``Majority()``
155+
- The query returns the instance’s most recent
156+
data acknowledged as having been written to a majority of members
157+
in the replica set. For more information, see the
158+
:rapid:`Read Concern specification </reference/read-concern-majority/#mongodb-readconcern-readconcern.-majority->`.
159+
160+
* - ``Snapshot()``
161+
- The query returns a complete copy of the
162+
data in a ``mongod`` instance at a specific point in time. Only
163+
available for operations within multi-document transactions. For more information, see the
164+
:rapid:`Read Concern specification </reference/read-concern-snapshot/#mongodb-readconcern-readconcern.-snapshot->`.
165+
166+
Example
167+
~~~~~~~
168+
169+
The following code shows how you can specify a read concern of
170+
"majority". The code then selects a ``Collection``
171+
with this option.
172+
173+
.. code-block:: go
174+
:emphasize-lines: 1-2
175+
176+
rc := readconcern.Majority()
177+
opts := options.Collection().SetReadConcern(rc)
178+
database := client.Database("myDB")
179+
coll := database.Collection("myCollection", opts)
180+
181+
Read Preference
182+
---------------
183+
184+
The read preference option specifies how the MongoDB client routes read
185+
operations to the members of a replica set. By default, an application
186+
directs its read operations to the primary member in a replica set.
187+
188+
Read preference consists of the read preference mode and, optionally, a
189+
:rapid:`tag set list </core/read-preference-tags/>`, the
190+
:rapid:`maxStalenessSeconds </core/read-preference-staleness/>` option, and the
191+
:rapid:`hedged read </core/read-preference-hedge-option/>` option.
192+
193+
Options
194+
~~~~~~~
195+
196+
The {+driver-long+} provides the ``readpref`` package, which lets
197+
you specify the read preference for a replica set. Set the read preference using the
198+
``SetReadPreference()`` method with a ``ReadPref`` type. The ``ReadPref``
199+
type has the following methods to specify the read preference:
200+
201+
.. list-table::
202+
:widths: 25 75
203+
:header-rows: 1
204+
205+
* - Method
206+
- Description
207+
208+
* - ``Nearest()``
209+
- The client reads from a random eligible replica set member,
210+
primary or secondary, based on a specified latency threshold. For more information, see the
211+
:rapid:`Read Preference Server Manual entry </core/read-preference/#mongodb-readmode-nearest>`.
212+
213+
* - ``Primary()``
214+
- The client reads from the current replica set primary node. For more information, see the
215+
:rapid:`Read Preference Server Manual entry </core/read-preference/#mongodb-readmode-primary>`.
216+
217+
* - ``PrimaryPreferred()``
218+
- The client reads from the primary node in most situations. If the primary is
219+
unavailable, operations read from secondary members. For more
220+
information, see the :rapid:`Read Preference Server Manual entry </core/read-preference/#mongodb-readmode-primaryPreferred>`.
221+
222+
* - ``Secondary()``
223+
- The client reads from the secondary members of the replica set. For more information, see the
224+
:rapid:`Read Preference Server Manual entry </core/read-preference/#mongodb-readmode-secondary>`.
225+
226+
* - ``SecondaryPreferred()``
227+
- The client reads from the secondary nodes in most situations. If the secondaries are
228+
unavailable, operations read from the primary member. For more information, see the
229+
:rapid:`Read Preference Server Manual entry </core/read-preference/#mongodb-readmode-secondaryPreferred>`.
230+
231+
.. tip::
232+
233+
You can alternatively specify a read preference in your connection
234+
string. See the :manual:`Server Manual entry on Read Preference
235+
Options </reference/connection-string/#read-preference-options>` for
236+
more information.
237+
238+
Example
239+
~~~~~~~
240+
241+
The following code shows how you can specify a read preference to read
242+
from secondary nodes. The code then selects a ``Database``
243+
with this option.
244+
245+
.. code-block:: go
246+
:emphasize-lines: 1-2
247+
248+
rp := readpref.Secondary()
249+
opts := options.Database().SetReadPreference(rp)
250+
database := client.Database("myDB", opts)
251+
252+
Additional Information
253+
----------------------
254+
255+
For more information about the concepts in this guide, see the following
256+
Server documentation:
257+
258+
- :ref:`Connection Guide <golang-connection-guide>`
259+
- :rapid:`Write Concern for Replica Sets </core/replica-set-write-concern/>`
260+
- :rapid:`Read Concern </reference/read-concern/>`
261+
- :rapid:`Read Preference </core/read-preference/>`
262+
263+
API Documentation
264+
~~~~~~~~~~~~~~~~~
265+
266+
- `Option <{+api+}/mongo/writeconcern#Option>`__
267+
- `WriteConcern <{+api+}/mongo/writeconcern#WriteConcern>`__
268+
- `ReadConcern <{+api+}/mongo/readconcern#ReadConcern>`__
269+
- `ReadPref <{+api+}/mongo/readpref#ReadPref>`__

0 commit comments

Comments
 (0)