1MONGOC_URI_T(3) libmongoc MONGOC_URI_T(3)
2
6 mongoc_uri_t - mongoc_uri_t
7
9 typedef struct _mongoc_uri_t mongoc_uri_t;
10
12 mongoc_uri_t provides an abstraction on top of the MongoDB connection
13 URI format. It provides standardized parsing as well as convenience
14 methods for extracting useful information such as replica hosts or au‐
15 thorization information.
16 See Connection String URI Reference on the MongoDB website for more in‐
18 formation.
19
21 mongodb[+srv]:// <1>
22 [username:password@] <2>
23 host1 <3>
24 [:port1] <4>
25 [,host2[:port2],...[,hostN[:portN]]] <5>
26 [/[database] <6>
27 [?options]] <7>
28 1. "mongodb" is the specifier of the MongoDB protocol. Use "mon‐
30 godb+srv" with a single service name in place of "host1" to specify
31 the initial list of servers with an SRV record.
32 2. An optional username and password.
34 3. The only required part of the uri. This specifies either a host‐
36 name, IPv4 address, IPv6 address enclosed in "[" and "]", or UNIX
37 domain socket.
38 4. An optional port number. Defaults to :27017.
40 5. Extra optional hosts and ports. You would specify multiple hosts,
42 for example, for connections to replica sets.
43 6. The name of the database to authenticate if the connection string
45 includes authentication credentials. If /database is not specified
46 and the connection string includes credentials, defaults to the 'ad‐
47 min' database.
48 7. Connection specific options.
50 NOTE:
52 Option names are case-insensitive. Do not repeat the same option
53 (e.g. "mongodb://localhost/db?opt=value1&OPT=value2") since this may
54 have unexpected results.
55 The MongoDB C Driver exposes constants for each supported connection
57 option. These constants make it easier to discover connection options,
58 but their string values can be used as well.
59 For example, the following calls are equal.
61 uri = mongoc_uri_new ("mongodb://localhost/?" MONGOC_URI_APPNAME "=applicationName");
63 uri = mongoc_uri_new ("mongodb://localhost/?appname=applicationName");
64 uri = mongoc_uri_new ("mongodb://localhost/?appName=applicationName");
65
67 To describe a connection to a replica set named 'test' with the follow‐
68 ing mongod hosts:
69 • db1.example.com on port 27017
71 • db2.example.com on port 2500
73 You would use a connection string that resembles the following.
75 mongodb://db1.example.com,db2.example.com:2500/?replicaSet=test
77
79 If you have configured an SRV record with a name like "_mon‐
80 godb._tcp.server.example.com" whose records are a list of one or more
81 MongoDB server hostnames, use a connection string like this:
82 uri = mongoc_uri_new ("mongodb+srv://server.example.com/?replicaSet=rs&appName=applicationName");
84 The driver prefixes the service name with "_mongodb._tcp.", then per‐
86 forms a DNS SRV query to resolve the service name to one or more host‐
87 names. If this query succeeds, the driver performs a DNS TXT query on
88 the service name (without the "_mongodb._tcp" prefix) for additional
89 URI options configured as TXT records.
90 On Unix, the MongoDB C Driver relies on libresolv to look up SRV and
92 TXT records. If libresolv is unavailable, then using a "mongodb+srv"
93 URI will cause an error. If your libresolv lacks res_nsearch then the
94 driver will fall back to res_search, which is not thread-safe.
95
97 If connecting to a hostname that has both IPv4 and IPv6 DNS records,
98 the behavior follows RFC-6555. A connection to the IPv6 address is at‐
99 tempted first. If IPv6 fails, then a connection is attempted to the
100 IPv4 address. If the connection attempt to IPv6 does not complete
101 within 250ms, then IPv4 is tried in parallel. Whichever succeeds con‐
102 nection first cancels the other. The successful DNS result is cached
103 for 10 minutes.
104 As a consequence, attempts to connect to a mongod only listening on
106 IPv4 may be delayed if there are both A (IPv4) and AAAA (IPv6) DNS
107 records associated with the host.
108 To avoid a delay, configure hostnames to match the MongoDB configura‐
110 tion. That is, only create an A record if the mongod is only listening
111 on IPv4.
112
114 ┌────────────────────┬──────────────────┬────────────────────────────────┐
115 │Constant │ Key │ Description │
116 ├────────────────────┼──────────────────┼────────────────────────────────┤
117 │MON‐ │ retryreads │ If "true" and the │
118 │GOC_URI_RETRYREADS │ │ server is a MongoDB │
119 │ │ │ 3.6+ standalone, │
120 │ │ │ replica set, or │
121 │ │ │ sharded cluster, │
122 │ │ │ the driver safely │
123 │ │ │ retries a read that │
124 │ │ │ failed due to a │
125 │ │ │ network error or │
126 │ │ │ replica set │
127 │ │ │ failover. │
128 └────────────────────┴──────────────────┴────────────────────────────────┘
129 │MONGOC_URI_RETRY‐ │ retrywrites │ If "true" and the │
138 │WRITES │ │ server is a MongoDB │
139 │ │ │ 3.6+ replica set or │
140 │ │ │ sharded cluster, │
141 │ │ │ the driver safely │
142 │ │ │ retries a write │
143 │ │ │ that failed due to │
144 │ │ │ a network error or │
145 │ │ │ replica set │
146 │ │ │ failover. Only in‐ │
147 │ │ │ serts, updates of │
148 │ │ │ single documents, │
149 │ │ │ or deletes of sin‐ │
150 │ │ │ gle documents are │
151 │ │ │ retried. │
152 ├────────────────────┼──────────────────┼────────────────────────────────┤
153 │MONGOC_URI_APPNAME │ appname │ The client applica‐ │
154 │ │ │ tion name. This │
155 │ │ │ value is used by │
156 │ │ │ MongoDB when it │
157 │ │ │ logs connection in‐ │
158 │ │ │ formation and pro‐ │
159 │ │ │ file information, │
160 │ │ │ such as slow │
161 │ │ │ queries. │
162 ├────────────────────┼──────────────────┼────────────────────────────────┤
163 │MONGOC_URI_TLS │ tls │ {true|false}, indi‐ │
164 │ │ │ cating if TLS must │
165 │ │ │ be used. (See also │
166 │ │ │ mon‐ │
167 │ │ │ goc_client_set_ssl_opts │
168 │ │ │ and mon‐ │
169 │ │ │ goc_client_pool_set_ssl_opts.) │
170 ├────────────────────┼──────────────────┼────────────────────────────────┤
171 │MONGOC_URI_COMPRES‐ │ compressors │ Comma separated list of com‐ │
172 │SORS │ │ pressors, if any, to use to │
173 │ │ │ compress the wire protocol │
174 │ │ │ messages. Snappy, zlib, and │
175 │ │ │ zstd are optional build time │
176 │ │ │ dependencies, and enable the │
177 │ │ │ "snappy", "zlib", and "zstd" │
178 │ │ │ values respectively. Defaults │
179 │ │ │ to empty (no compressors). │
180 ├────────────────────┼──────────────────┼────────────────────────────────┤
181 │MONGOC_URI_CONNECT‐ │ connecttimeoutms │ This setting applies to new │
182 │TIMEOUTMS │ │ server connections. It is also │
183 │ │ │ used as the socket timeout for │
184 │ │ │ server discovery and monitor‐ │
185 │ │ │ ing operations. The default is │
186 │ │ │ 10,000 ms (10 seconds). │
187 ├────────────────────┼──────────────────┼────────────────────────────────┤
188 │MONGOC_URI_SOCKET‐ │ sockettimeoutms │ The time in milliseconds to │
189 │TIMEOUTMS │ │ attempt to send or receive on │
190 │ │ │ a socket before the attempt │
191 │ │ │ times out. The default is │
192 │ │ │ 300,000 (5 minutes). │
193 ├────────────────────┼──────────────────┼────────────────────────────────┤
194 │MONGOC_URI_REPLI‐ │ replicaset │ The name of the Replica Set │
195 │CASET │ │ that the driver should connect │
196 │ │ │ to. │
197 └────────────────────┴──────────────────┴────────────────────────────────┘
198 │MONGOC_URI_ZLIBCOM‐ │ zlibcompression‐ │ When the MONGOC_URI_COMPRES‐ │
206 │PRESSIONLEVEL │ level │ SORS includes "zlib" this op‐ │
207 │ │ │ tions configures the zlib com‐ │
208 │ │ │ pression level, when the zlib │
209 │ │ │ compressor is used to compress │
210 │ │ │ client data. │
211 └────────────────────┴──────────────────┴────────────────────────────────┘
212 Setting any of the *timeoutMS options above to 0 will be interpreted as
214 "use the default value".
215
217 ┌────────────────────┬────────────────────┬─────────────────────┐
218 │Constant │ Key │ Description │
219 ├────────────────────┼────────────────────┼─────────────────────┤
220 │MONGOC_URI_AUTH‐ │ authmechanism │ Specifies the mech‐ │
221 │MECHANISM │ │ anism to use when │
222 │ │ │ authenticating as │
223 │ │ │ the provided user. │
224 │ │ │ See Authentication │
225 │ │ │ for supported val‐ │
226 │ │ │ ues. │
227 ├────────────────────┼────────────────────┼─────────────────────┤
228 │MONGOC_URI_AUTH‐ │ authmechanismprop‐ │ Certain authentica‐ │
229 │MECHANISMPROPERTIES │ erties │ tion mechanisms │
230 │ │ │ have additional op‐ │
231 │ │ │ tions that can be │
232 │ │ │ configured. These │
233 │ │ │ options should be │
234 │ │ │ provided as comma │
235 │ │ │ separated op‐ │
236 │ │ │ tion_key:op‐ │
237 │ │ │ tion_value pair and │
238 │ │ │ provided as auth‐ │
239 │ │ │ MechanismProper‐ │
240 │ │ │ ties. │
241 ├────────────────────┼────────────────────┼─────────────────────┤
242 │MONGOC_URI_AUTH‐ │ authsource │ The authSource de‐ │
243 │SOURCE │ │ fines the database │
244 │ │ │ that should be used │
245 │ │ │ to authenticate to. │
246 │ │ │ It is unnecessary │
247 │ │ │ to provide this op‐ │
248 │ │ │ tion the database │
249 │ │ │ name is the same as │
250 │ │ │ the database used │
251 │ │ │ in the URI. │
252 └────────────────────┴────────────────────┴─────────────────────┘
253 Mechanism Properties
255 ┌────────────────────┬───────────────────┬─────────────────────┐
256 │Constant │ Key │ Description │
257 ├────────────────────┼───────────────────┼─────────────────────┤
258 │MONGOC_URI_CANONI‐ │ canonicalizehost‐ │ Use the canonical │
259 │CALIZEHOSTNAME │ name │ hostname of the │
260 │ │ │ service, rather │
261 │ │ │ than its configured │
262 │ │ │ alias, when authen‐ │
263 │ │ │ ticating with │
264 │ │ │ Cyrus-SASL Ker‐ │
265 │ │ │ beros. │
266 ├────────────────────┼───────────────────┼─────────────────────┤
267 │MONGOC_URI_GSSAPIS‐ │ gssapiservicename │ Use alternative │
268 │ERVICENAME │ │ service name. The │
269 │ │ │ default is mongodb. │
270 └────────────────────┴───────────────────┴─────────────────────┘
271
273 ──────────────────────────────────────────────────────────────────
274 Constant Key Description
275 ──────────────────────────────────────────────────────────────────
276 MONGOC_URI_TLS tls {true|false}, indi‐
277 cating if TLS must
278 be used.
279 ──────────────────────────────────────────────────────────────────
280 MONGOC_URI_TLSCER‐ tlscertificatekey‐ Path to PEM format‐
281 TIFICATEKEYFILE file ted Private Key,
282 with its Public
283 Certificate con‐
284 catenated at the
285 end.
286 ──────────────────────────────────────────────────────────────────
287 MONGOC_URI_TLSCER‐ tlscertificatekey‐ The password, if
288 TIFICATEKEYPASSWORD password any, to use to un‐
289 lock encrypted Pri‐
290 vate Key.
291 ──────────────────────────────────────────────────────────────────
292 MON‐ tlscafile One, or a bundle
293 GOC_URI_TLSCAFILE of, Certificate Au‐
294 thorities whom
295 should be consid‐
296 ered to be trusted.
297 ──────────────────────────────────────────────────────────────────
298 MONGOC_URI_TLSAL‐ tlsallowinvalidcer‐ Accept and ignore
299 LOWINVALIDCERTIFI‐ tificates certificate verifi‐
300 CATES cation errors (e.g.
301 untrusted issuer,
302 expired, etc.)
303 ──────────────────────────────────────────────────────────────────
304 MONGOC_URI_TLSAL‐ tlsallowinvalid‐ Ignore hostname
305 LOWINVALIDHOSTNAMES hostnames verification of the
306 certificate (e.g.
307 Man In The Middle,
308 using valid cer‐
309 tificate, but is‐
310 sued for another
311 hostname)
312 ──────────────────────────────────────────────────────────────────
313 MONGOC_URI_TLSINSE‐ tlsinsecure {true|false}, indi‐
314 CURE cating if insecure
315 TLS options should
316 be used. Currently
317 this implies MON‐
318 GOC_URI_TLSALLOWIN‐
319 VALIDCERTIFICATES
320 and MONGOC_URI_TL‐
321 SALLOWINVALIDHOST‐
322 NAMES.
323 ──────────────────────────────────────────────────────────────────
324 MONGOC_URI_TLSDIS‐ tlsdisablecertifi‐ {true|false}, indi‐
325 ABLECERTIFICATERE‐ caterevocationcheck cates if revocation
326 VOCATIONCHECK checking (CRL /
327 OCSP) should be
328 disabled.
329 ──────────────────────────────────────────────────────────────────
330 MONGOC_URI_TLSDIS‐ tlsdisableocspend‐ {true|false}, indi‐
331 ABLEOCSPEND‐ pointcheck cates if OCSP re‐
332 POINTCHECK sponder endpoints
333 should not be re‐
334 quested when an
335 OCSP response is
336 not stapled.
337 ┌────────────────────┬─────────────────────┬─────────────────────┐
338 │ │ │ │
339 See│ configuring_tls for│details about these o│ptions and about build│ing
340 lib│mongoc with TLS suppo│rt. │ │
341 │ │ │ │
343 The│following options ha│ve been deprecated and│may be removed from │fu‐
344 ture releases of libmongoc.
345 ┌──────────────────────┬──────────────────┬───────────────────┬──────────────────┐
347 │Constant │ Key │ Deprecated For │ Key │
348 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
349 │MONGOC_URI_SSL │ ssl │ MONGOC_URI_TLS │ tls │
350 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
351 │MON‐ │ sslclientcer‐ │ MON‐ │ tlscertifi‐ │
352 │GOC_URI_SSLCLIENTCER‐ │ tificatekeyfile │ GOC_URI_TLSCER‐ │ catekeyfile │
353 │TIFICATEKEYFILE │ │ TIFICATEKEYFILE │ │
354 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
355 │MON‐ │ sslclientcer‐ │ MON‐ │ tlscertifi‐ │
356 │GOC_URI_SSLCLIENTCER‐ │ tificatekeypass‐ │ GOC_URI_TLSCER‐ │ catekeypassword │
357 │TIFICATEKEYPASSWORD │ word │ TIFICATEKEYPASS‐ │ │
358 │ │ │ WORD │ │
359 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
360 │MONGOC_URI_SSLCER‐ │ sslcertifi‐ │ MON‐ │ tlscafile │
361 │TIFICATEAUTHORITYFILE │ cateauthority‐ │ GOC_URI_TLSCAFILE │ │
362 │ │ file │ │ │
363 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
364 │MONGOC_URI_SSLALLOW‐ │ sslallowinvalid‐ │ MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │
365 │INVALIDCERTIFICATES │ certificates │ LOWINVALIDCER‐ │ certificates │
366 │ │ │ TIFICATES │ │
367 ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
368 │MONGOC_URI_SSLALLOW‐ │ sslallowinvalid‐ │ MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │
369 │INVALIDHOSTNAMES │ hostnames │ LOWINVALIDHOST‐ │ hostnames │
370 │ │ │ NAMES │ │
371 └──────────────────────┴──────────────────┴───────────────────┴──────────────────┘
372
374 Clients in a mongoc_client_pool_t share a topology scanner that runs on
375 a background thread. The thread wakes every heartbeatFrequencyMS (de‐
376 fault 10 seconds) to scan all MongoDB servers in parallel. Whenever an
377 application operation requires a server that is not known--for example,
378 if there is no known primary and your application attempts an in‐
379 sert--the thread rescans all servers every half-second. In this situa‐
380 tion the pooled client waits up to serverSelectionTimeoutMS (default 30
381 seconds) for the thread to find a server suitable for the operation,
382 then returns an error with domain MONGOC_ERROR_SERVER_SELECTION.
383 Technically, the total time an operation may wait while a pooled client
385 scans the topology is controlled both by serverSelectionTimeoutMS and
386 connectTimeoutMS. The longest wait occurs if the last scan begins just
387 at the end of the selection timeout, and a slow or down server requires
388 the full connection timeout before the client gives up.
389 A non-pooled client is single-threaded. Every heartbeatFrequencyMS, it
391 blocks the next application operation while it does a parallel scan.
392 This scan takes as long as needed to check the slowest server: roughly
393 connectTimeoutMS. Therefore the default heartbeatFrequencyMS for sin‐
394 gle-threaded clients is greater than for pooled clients: 60 seconds.
395 By default, single-threaded (non-pooled) clients scan only once when an
397 operation requires a server that is not known. If you attempt an insert
398 and there is no known primary, the client checks all servers once try‐
399 ing to find it, then succeeds or returns an error with domain MON‐
400 GOC_ERROR_SERVER_SELECTION. But if you set serverSelectionTryOnce to
401 "false", the single-threaded client loops, checking all servers every
402 half-second, until serverSelectionTimeoutMS.
403 The total time an operation may wait for a single-threaded client to
405 scan the topology is determined by connectTimeoutMS in the try-once
406 case, or serverSelectionTimeoutMS and connectTimeoutMS if serverSelec‐
407 tionTryOnce is set "false".
408 ┌────────────────────┬─────────────────────┬─────────────────────┐
410 │Constant │ Key │ Description │
411 └────────────────────┴─────────────────────┴─────────────────────┘
412 │MONGOC_URI_HEART‐ │ heartbeatfrequen‐ │ The interval be‐ │
416 │BEATFREQUENCYMS │ cyms │ tween server moni‐ │
417 │ │ │ toring checks. De‐ │
418 │ │ │ faults to 10,000ms │
419 │ │ │ (10 seconds) in │
420 │ │ │ pooled │
421 │ │ │ (multi-threaded) │
422 │ │ │ mode, 60,000ms (60 │
423 │ │ │ seconds) in │
424 │ │ │ non-pooled mode │
425 │ │ │ (single-threaded). │
426 ├────────────────────┼─────────────────────┼─────────────────────┤
427 │MONGOC_URI_SERVERS‐ │ serverselection‐ │ A timeout in mil‐ │
428 │ELECTIONTIMEOUTMS │ timeoutms │ liseconds to block │
429 │ │ │ for server selec‐ │
430 │ │ │ tion before throw‐ │
431 │ │ │ ing an exception. │
432 │ │ │ The default is │
433 │ │ │ 30,0000ms (30 sec‐ │
434 │ │ │ onds). │
435 ├────────────────────┼─────────────────────┼─────────────────────┤
436 │MONGOC_URI_SERVERS‐ │ serverselectiontry‐ │ If "true", the │
437 │ELECTIONTRYONCE │ once │ driver scans the │
438 │ │ │ topology exactly │
439 │ │ │ once after server │
440 │ │ │ selection fails, │
441 │ │ │ then either selects │
442 │ │ │ a server or returns │
443 │ │ │ an error. If it is │
444 │ │ │ false, then the │
445 │ │ │ driver repeatedly │
446 │ │ │ searches for a │
447 │ │ │ suitable server for │
448 │ │ │ up to serverSelec‐ │
449 │ │ │ tionTimeoutMS mil‐ │
450 │ │ │ liseconds (pausing │
451 │ │ │ a half second be‐ │
452 │ │ │ tween attempts). │
453 │ │ │ The default for │
454 │ │ │ serverSelectionTry‐ │
455 │ │ │ Once is "false" for │
456 │ │ │ pooled clients, │
457 │ │ │ otherwise "true". │
458 │ │ │ Pooled clients ig‐ │
459 │ │ │ nore serverSelec‐ │
460 │ │ │ tionTryOnce; they │
461 │ │ │ signal the thread │
462 │ │ │ to rescan the │
463 │ │ │ topology every │
464 │ │ │ half-second until │
465 │ │ │ serverSelection‐ │
466 │ │ │ TimeoutMS expires. │
467 ├────────────────────┼─────────────────────┼─────────────────────┤
468 │MONGOC_URI_SOCK‐ │ socketcheckinter‐ │ Only applies to │
469 │ETCHECKINTERVALMS │ valms │ single threaded │
470 │ │ │ clients. If a │
471 │ │ │ socket has not been │
472 │ │ │ used within this │
473 │ │ │ time, its connec‐ │
474 │ │ │ tion is checked │
475 │ │ │ with a quick "is‐ │
476 │ │ │ Master" call before │
477 │ │ │ it is used again. │
478 │ │ │ Defaults to 5,000ms │
479 │ │ │ (5 seconds). │
480 └────────────────────┴─────────────────────┴─────────────────────┘
481 │MONGOC_URI_DIRECT‐ │ directconnection │ If "true", the │
486 │CONNECTION │ │ driver connects to │
487 │ │ │ a single server di‐ │
488 │ │ │ rectly and will not │
489 │ │ │ monitor additional │
490 │ │ │ servers. If │
491 │ │ │ "false", the driver │
492 │ │ │ connects based on │
493 │ │ │ the presence and │
494 │ │ │ value of the repli‐ │
495 │ │ │ caSet option. │
496 └────────────────────┴─────────────────────┴─────────────────────┘
497 Setting any of the *TimeoutMS options above to 0 will be interpreted as
499 "use the default value".
500
502 These options govern the behavior of a mongoc_client_pool_t. They are
503 ignored by a non-pooled mongoc_client_t.
504 ┌────────────────────┬────────────────────┬─────────────────────┐
506 │Constant │ Key │ Description │
507 ├────────────────────┼────────────────────┼─────────────────────┤
508 │MONGOC_URI_MAXPOOL‐ │ maxpoolsize │ The maximum number │
509 │SIZE │ │ of clients created │
510 │ │ │ by a mon‐ │
511 │ │ │ goc_client_pool_t │
512 │ │ │ total (both in the │
513 │ │ │ pool and checked │
514 │ │ │ out). The default │
515 │ │ │ value is 100. Once │
516 │ │ │ it is reached, mon‐ │
517 │ │ │ goc_client_pool_pop │
518 │ │ │ blocks until an‐ │
519 │ │ │ other thread pushes │
520 │ │ │ a client. │
521 ├────────────────────┼────────────────────┼─────────────────────┤
522 │MONGOC_URI_MINPOOL‐ │ minpoolsize │ Deprecated. This │
523 │SIZE │ │ option's behavior │
524 │ │ │ does not match its │
525 │ │ │ name, and its ac‐ │
526 │ │ │ tual behavior will │
527 │ │ │ likely hurt perfor‐ │
528 │ │ │ mance. │
529 ├────────────────────┼────────────────────┼─────────────────────┤
530 │MONGOC_URI_MAXIDLE‐ │ maxidletimems │ Not implemented. │
531 │TIMEMS │ │ │
532 ├────────────────────┼────────────────────┼─────────────────────┤
533 │MONGOC_URI_WAIT‐ │ waitqueuemultiple │ Not implemented. │
534 │QUEUEMULTIPLE │ │ │
535 ├────────────────────┼────────────────────┼─────────────────────┤
536 │MONGOC_URI_WAIT‐ │ waitqueuetimeoutms │ The maximum time to │
537 │QUEUETIMEOUTMS │ │ wait for a client │
538 │ │ │ to become available │
539 │ │ │ from the pool. │
540 └────────────────────┴────────────────────┴─────────────────────┘
541
543 ┌───────────────────┬────────────┬─────────────────────┐
544 │Constant │ Key │ Description │
545 └───────────────────┴────────────┴─────────────────────┘
546 MONGOC_URI_W w Determines the
556 write concern
557 (guarantee). Valid
558 values:
559 • 0 = The
561 driver
562 will not
563 acknowl‐
564 edge write
565 operations
566 but will
567 pass or
568 handle any
569 network
570 and socket
571 errors
572 that it
573 receives
574 to the
575 client. If
576 you dis‐
577 able write
578 concern
579 but enable
580 the get‐
581 LastError
582 command’s
583 w option,
584 w over‐
585 rides the
586 w option.
587 • 1 = Pro‐
589 vides ba‐
590 sic ac‐
591 knowledge‐
592 ment of
593 write op‐
594 erations.
595 By speci‐
596 fying 1,
597 you re‐
598 quire that
599 a stand‐
600 alone mon‐
601 god in‐
602 stance, or
603 the pri‐
604 mary for
605 replica
606 sets, ac‐
607 knowledge
608 all write
609 opera‐
610 tions. For
611 drivers
612 released
613 after the
614 default
615 write con‐
616 cern
617 change,
618 this is
619 the de‐
620 fault
621 write con‐
622 cern set‐
623 ting.
624 • majority =
626 For
627 replica
628 sets, if
629 you spec‐
630 ify the
631 special
632 majority
633 value to w
634 option,
635 write op‐
636 erations
637 will only
638 return
639 success‐
640 fully af‐
641 ter a ma‐
642 jority of
643 the con‐
644 figured
645 replica
646 set mem‐
647 bers have
648 acknowl‐
649 edged the
650 write op‐
651 eration.
652 • n = For
654 replica
655 sets, if
656 you spec‐
657 ify a num‐
658 ber n
659 greater
660 than 1,
661 operations
662 with this
663 write con‐
664 cern re‐
665 turn only
666 after n
667 members of
668 the set
669 have ac‐
670 knowledged
671 the write.
672 If you set
673 n to a
674 number
675 that is
676 greater
677 than the
678 number of
679 available
680 set mem‐
681 bers or
682 members
683 that hold
684 data, Mon‐
685 goDB will
686 wait, po‐
687 tentially
688 indefi‐
689 nitely,
690 for these
691 members to
692 become
693 available.
694 • tags = For
696 replica
697 sets, you
698 can spec‐
699 ify a tag
700 set to re‐
701 quire that
702 all mem‐
703 bers of
704 the set
705 that have
706 these tags
707 configured
708 return
709 confirma‐
710 tion of
711 the write
712 operation.
713 ├───────────────────┼────────────┼─────────────────────┤
714 │MONGOC_URI_WTIME‐ │ wtimeoutms │ The time in mil‐ │
715 │OUTMS │ │ liseconds to wait │
716 │ │ │ for replication to │
717 │ │ │ succeed, as speci‐ │
718 │ │ │ fied in the w op‐ │
719 │ │ │ tion, before timing │
720 │ │ │ out. When wtime‐ │
721 │ │ │ outMS is 0, write │
722 │ │ │ operations will │
723 │ │ │ never time out. │
724 ├───────────────────┼────────────┼─────────────────────┤
725 │MONGOC_URI_JOURNAL │ journal │ Controls whether │
726 │ │ │ write operations │
727 │ │ │ will wait until the │
728 │ │ │ mongod acknowledges │
729 │ │ │ the write opera‐ │
730 │ │ │ tions and commits │
731 │ │ │ the data to the on │
732 │ │ │ disk journal. │
733 │ │ │ │
734 │ │ │ • true = │
735 │ │ │ Enables │
736 │ │ │ journal │
737 │ │ │ commit ac‐ │
738 │ │ │ knowledge‐ │
739 │ │ │ ment write │
740 │ │ │ concern. │
741 │ │ │ Equivalent │
742 │ │ │ to speci‐ │
743 │ │ │ fying the │
744 │ │ │ getLastEr‐ │
745 │ │ │ ror com‐ │
746 │ │ │ mand with │
747 │ │ │ the j op‐ │
748 │ │ │ tion en‐ │
749 │ │ │ abled. │
750 │ │ │ │
751 │ │ │ • false = │
752 │ │ │ Does not │
753 │ │ │ require │
754 │ │ │ that mon‐ │
755 │ │ │ god commit │
756 │ │ │ write op‐ │
757 │ │ │ erations │
758 │ │ │ to the │
759 │ │ │ journal │
760 │ │ │ before ac‐ │
761 │ │ │ knowledg‐ │
762 │ │ │ ing the │
763 │ │ │ write op‐ │
764 │ │ │ eration. │
765 │ │ │ This is │
766 │ │ │ the de‐ │
767 │ │ │ fault op‐ │
768 │ │ │ tion for │
769 │ │ │ the jour‐ │
770 │ │ │ nal param‐ │
771 │ │ │ eter. │
772 └───────────────────┴────────────┴─────────────────────┘
773
775 ┌────────────────────┬──────────────────┬─────────────────────┐
776 │Constant │ Key │ Description │
777 └────────────────────┴──────────────────┴─────────────────────┘
778 │MONGOC_URI_READCON‐ │ readconcernlevel │ The level of isola‐ │
784 │CERNLEVEL │ │ tion for read oper‐ │
785 │ │ │ ations. If the │
786 │ │ │ level is left un‐ │
787 │ │ │ specified, the │
788 │ │ │ server default will │
789 │ │ │ be used. See │
790 │ │ │ readConcern in the │
791 │ │ │ MongoDB Manual for │
792 │ │ │ details. │
793 └────────────────────┴──────────────────┴─────────────────────┘
794
796 When connected to a replica set, the driver chooses which member to
797 query using the read preference:
798 1. Choose members whose type matches "readPreference".
800 2. From these, if there are any tags sets configured, choose members
802 matching the first tag set. If there are none, fall back to the next
803 tag set and so on, until some members are chosen or the tag sets are
804 exhausted.
805 3. From the chosen servers, distribute queries randomly among the
807 server with the fastest round-trip times. These include the server
808 with the fastest time and any whose round-trip time is no more than
809 "localThresholdMS" slower.
810 ┌────────────────────┬─────────────────────┬──────────────────────────┐
812 │Constant │ Key │ Description │
813 ├────────────────────┼─────────────────────┼──────────────────────────┤
814 │MONGOC_URI_READ‐ │ readpreference │ Specifies the │
815 │PREFERENCE │ │ replica set read │
816 │ │ │ preference for this │
817 │ │ │ connection. This │
818 │ │ │ setting overrides │
819 │ │ │ any slaveOk value. │
820 │ │ │ The read preference │
821 │ │ │ values are the fol‐ │
822 │ │ │ lowing: │
823 │ │ │ │
824 │ │ │ • primary │
825 │ │ │ (default) │
826 │ │ │ │
827 │ │ │ • prima‐ │
828 │ │ │ ryPre‐ │
829 │ │ │ ferred │
830 │ │ │ │
831 │ │ │ • secondary │
832 │ │ │ │
833 │ │ │ • sec‐ │
834 │ │ │ ondaryPre‐ │
835 │ │ │ ferred │
836 │ │ │ │
837 │ │ │ • nearest │
838 ├────────────────────┼─────────────────────┼──────────────────────────┤
839 │MONGOC_URI_READ‐ │ readpreferencetags │ A representation of │
840 │PREFERENCETAGS │ │ a tag set. See also │
841 │ │ │ mon‐ │
842 │ │ │ goc-read-prefs-tag-sets. │
843 └────────────────────┴─────────────────────┴──────────────────────────┘
844 │MONGOC_URI_LO‐ │ localthresholdms │ How far to distribute │
854 │CALTHRESHOLDMS │ │ queries, beyond the │
855 │ │ │ server with the fastest │
856 │ │ │ round-trip time. By de‐ │
857 │ │ │ fault, only servers │
858 │ │ │ within 15ms of the │
859 │ │ │ fastest round-trip time │
860 │ │ │ receive queries. │
861 ├────────────────────┼─────────────────────┼──────────────────────────┤
862 │MONGOC_URI_MAXSTAL‐ │ maxstalenessseconds │ The maximum replication │
863 │ENESSSECONDS │ │ lag, in wall clock time, │
864 │ │ │ that a secondary can │
865 │ │ │ suffer and still be eli‐ │
866 │ │ │ gible. The smallest al‐ │
867 │ │ │ lowed value for maxStal‐ │
868 │ │ │ enessSeconds is 90 sec‐ │
869 │ │ │ onds. │
870 └────────────────────┴─────────────────────┴──────────────────────────┘
871 NOTE:
873 When connecting to more than one mongos, libmongoc's localThresh‐
874 oldMS applies only to the selection of mongos servers. The threshold
875 for selecting among replica set members in shards is controlled by
876 the mongos's localThreshold command line option.
877
879 For historical reasons, the following options are available. They
880 should however not be used.
881 ┌───────────────────┬─────────┬─────────────────────┐
883 │Constant │ Key │ Description │
884 ├───────────────────┼─────────┼─────────────────────┤
885 │MONGOC_URI_SAFE │ safe │ {true|false} Same │
886 │ │ │ as w={1|0} │
887 ├───────────────────┼─────────┼─────────────────────┤
888 │MONGOC_URI_SLAVEOK │ slaveok │ When set, same as │
889 │ │ │ readPreference=sec‐ │
890 │ │ │ ondaryPreferred │
891 └───────────────────┴─────────┴─────────────────────┘
892
894 MongoDB, Inc
895
897 2017-present, MongoDB, Inc
8981.17.6 Jun 03, 2021 MONGOC_URI_T(3)