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
15 authorization information.
16 See Connection String URI Reference on the MongoDB website for more
18 information.
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
47 'admin' 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
99 attempted 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 │
147 │ │ │ inserts, 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 │
158 │ │ │ information and │
159 │ │ │ profile informa‐ │
160 │ │ │ tion, 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 │
207 │ │ │ options configures the zlib │
208 │ │ │ compression level, when the │
209 │ │ │ zlib compressor is used to │
210 │ │ │ compress 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 │
231 │ │ │ options that can be │
232 │ │ │ configured. These │
233 │ │ │ options should be │
234 │ │ │ provided as comma │
235 │ │ │ separated │
236 │ │ │ option_key:option_value │
237 │ │ │ pair and provided │
238 │ │ │ as authMechanism‐ │
239 │ │ │ Properties. │
240 ├────────────────────┼────────────────────┼─────────────────────────┤
241 │MONGOC_URI_AUTH‐ │ authsource │ The authSource defines │
242 │SOURCE │ │ the database that │
243 │ │ │ should be used to │
244 │ │ │ authenticate to. It is │
245 │ │ │ unnecessary to provide │
246 │ │ │ this option the data‐ │
247 │ │ │ base name is the same │
248 │ │ │ as the database used in │
249 │ │ │ the URI. │
250 └────────────────────┴────────────────────┴─────────────────────────┘
251 Mechanism Properties
253 ┌────────────────────┬───────────────────┬─────────────────────┐
254 │Constant │ Key │ Description │
255 ├────────────────────┼───────────────────┼─────────────────────┤
256 │MONGOC_URI_CANONI‐ │ canonicalizehost‐ │ Use the canonical │
257 │CALIZEHOSTNAME │ name │ hostname of the │
258 │ │ │ service, rather │
259 │ │ │ than its configured │
260 │ │ │ alias, when authen‐ │
261 │ │ │ ticating with │
262 │ │ │ Cyrus-SASL Ker‐ │
263 │ │ │ beros. │
264 ├────────────────────┼───────────────────┼─────────────────────┤
265 │MONGOC_URI_GSSAPIS‐ │ gssapiservicename │ Use alternative │
266 │ERVICENAME │ │ service name. The │
267 │ │ │ default is mongodb. │
268 └────────────────────┴───────────────────┴─────────────────────┘
269
271 ──────────────────────────────────────────────────────────────────
272 Constant Key Description
273 ──────────────────────────────────────────────────────────────────
274 MONGOC_URI_TLSCER‐ tlscertificatekey‐ Path to PEM format‐
275 TIFICATEKEYFILE file ted Private Key,
276 with its Public
277 Certificate con‐
278 catenated at the
279 end.
280 ──────────────────────────────────────────────────────────────────
281 MONGOC_URI_TLSCER‐ tlscertificatekey‐ The password, if
282 TIFICATEKEYPASSWORD password any, to use to
283 unlock encrypted
284 Private Key.
285 ──────────────────────────────────────────────────────────────────
286 MONGOC_URI_TLSCER‐ tlscertificateau‐ One, or a bundle
287 TIFICATEAUTHORITY‐ thorityfile of, Certificate
288 FILE Authorities whom
289 should be consid‐
290 ered to be trusted.
291 ──────────────────────────────────────────────────────────────────
292 MONGOC_URI_TLSAL‐ tlsallowinvalidcer‐ Accept and ignore
293 LOWINVALIDCERTIFI‐ tificates certificate verifi‐
294 CATES cation errors (e.g.
295 untrusted issuer,
296 expired, etc etc)
297 ──────────────────────────────────────────────────────────────────
298 MONGOC_URI_TLSAL‐ tlsallowinvalid‐ Ignore hostname
299 LOWINVALIDHOSTNAMES hostnames verification of the
300 certificate (e.g.
301 Man In The Middle,
302 using valid cer‐
303 tificate, but
304 issued for another
305 hostname)
306 ──────────────────────────────────────────────────────────────────
307 MONGOC_URI_TLSINSE‐ tlsinsecure {true|false}, indi‐
308 CURE cating if insecure
309 TLS options should
310 be used. Currently
311 this implies MON‐
312 GOC_URI_TLSALLOWIN‐
313 VALIDCERTIFICATES
314 and MON‐
315 GOC_URI_TLSALLOWIN‐
316 VALIDHOSTNAMES.
317 ┌────────────────────┬─────────────────────┬─────────────────────┐
318 │ │ │ │
319 See│mongoc_ssl_opt_t for│details about these o│ptions and about build│ing
320 lib│mongoc with SSL suppo│rt. │ │
321 │ │ │ │
323 The│following options ha│ve been deprecated an│d may be removed f│rom
324 fut│ure releases of libmo│ngoc. │ │
325 │ │ │ │
326 ┌──────┼───────────────┬────┼─────────────┬───────┼──────────┬──────────┼───────┐
327 │Consta│nt │ Key│ │ Deprec│ated For │ Key │ │
328 ├──────┼───────────────┼────┼─────────────┼───────┼──────────┼──────────┼───────┤
329 │MONGOC│_URI_SSL │ ssl│ │ MONGOC│_URI_TLS │ tls │ │
330 ├──────┼───────────────┼────┼─────────────┼───────┼──────────┼──────────┼───────┤
331 │MON‐ │ │ ssl│clientcer‐ │ MON‐ │ │ tlscertif│i‐ │
332 │GOC_UR│I_SSLCLIENTCER‐ │ tif│icatekeyfile │ GOC_UR│I_TLSCER‐ │ catekeyfi│le │
333 │TIFICA│TEKEYFILE │ │ │ TIFICA│TEKEYFILE │ │ │
334 ├──────┼───────────────┼────┼─────────────┼───────┼──────────┼──────────┼───────┤
335 │MON‐ │ │ ssl│clientcer‐ │ MON‐ │ │ tlscertif│i‐ │
336 │GOC_UR│I_SSLCLIENTCER‐ │ tif│icatekeypass‐ │ GOC_UR│I_TLSCER‐ │ catekeypa│ssword │
337 │TIFICA│TEKEYPASSWORD │ wor│d │ TIFICA│TEKEYPASS‐ │ │ │
338 │ │ │ │ │ WORD │ │ │ │
339 └──────┴───────────────┴────┴─────────────┴───────┴──────────┴──────────┴───────┘
340 │MONGOC_URI_SSLCER‐ │ sslcertifi‐ │ MON‐ │ tlscertifi‐ │
342 │TIFICATEAUTHORITYFILE │ cateauthority‐ │ GOC_URI_TLSCER‐ │ cateauthority‐ │
343 │ │ file │ TIFICATEAUTHORI‐ │ file │
344 │ │ │ TYFILE │ │
345 ├──────────────────────┼──────────────────┼──────────────────┼──────────────────┤
346 │MONGOC_URI_SSLALLOW‐ │ sslallowinvalid‐ │ MON‐ │ tlsallowinvalid‐ │
347 │INVALIDCERTIFICATES │ certificates │ GOC_URI_TLSAL‐ │ certificates │
348 │ │ │ LOWINVALIDCER‐ │ │
349 │ │ │ TIFICATES │ │
350 ├──────────────────────┼──────────────────┼──────────────────┼──────────────────┤
351 │MONGOC_URI_SSLALLOW‐ │ sslallowinvalid‐ │ MON‐ │ tlsallowinvalid‐ │
352 │INVALIDHOSTNAMES │ hostnames │ GOC_URI_TLSAL‐ │ hostnames │
353 │ │ │ LOWINVALIDHOST‐ │ │
354 │ │ │ NAMES │ │
355 └──────────────────────┴──────────────────┴──────────────────┴──────────────────┘
356
358 Clients in a mongoc_client_pool_t share a topology scanner that runs on
359 a background thread. The thread wakes every heartbeatFrequencyMS
360 (default 10 seconds) to scan all MongoDB servers in parallel. Whenever
361 an application operation requires a server that is not known--for exam‐
362 ple, if there is no known primary and your application attempts an
363 insert--the thread rescans all servers every half-second. In this situ‐
364 ation the pooled client waits up to serverSelectionTimeoutMS (default
365 30 seconds) for the thread to find a server suitable for the operation,
366 then returns an error with domain MONGOC_ERROR_SERVER_SELECTION.
367 Technically, the total time an operation may wait while a pooled client
369 scans the topology is controlled both by serverSelectionTimeoutMS and
370 connectTimeoutMS. The longest wait occurs if the last scan begins just
371 at the end of the selection timeout, and a slow or down server requires
372 the full connection timeout before the client gives up.
373 A non-pooled client is single-threaded. Every heartbeatFrequencyMS, it
375 blocks the next application operation while it does a parallel scan.
376 This scan takes as long as needed to check the slowest server: roughly
377 connectTimeoutMS. Therefore the default heartbeatFrequencyMS for sin‐
378 gle-threaded clients is greater than for pooled clients: 60 seconds.
379 By default, single-threaded (non-pooled) clients scan only once when an
381 operation requires a server that is not known. If you attempt an insert
382 and there is no known primary, the client checks all servers once try‐
383 ing to find it, then succeeds or returns an error with domain MON‐
384 GOC_ERROR_SERVER_SELECTION. But if you set serverSelectionTryOnce to
385 "false", the single-threaded client loops, checking all servers every
386 half-second, until serverSelectionTimeoutMS.
387 The total time an operation may wait for a single-threaded client to
389 scan the topology is determined by connectTimeoutMS in the try-once
390 case, or serverSelectionTimeoutMS and connectTimeoutMS if serverSelec‐
391 tionTryOnce is set "false".
392 ┌────────────────────┬─────────────────────┬─────────────────────┐
394 │Constant │ Key │ Description │
395 ├────────────────────┼─────────────────────┼─────────────────────┤
396 │MONGOC_URI_HEART‐ │ heartbeatfrequen‐ │ The interval │
397 │BEATFREQUENCYMS │ cyms │ between server mon‐ │
398 │ │ │ itoring checks. │
399 │ │ │ Defaults to │
400 │ │ │ 10,000ms (10 sec‐ │
401 │ │ │ onds) in pooled │
402 │ │ │ (multi-threaded) │
403 │ │ │ mode, 60,000ms (60 │
404 │ │ │ seconds) in │
405 │ │ │ non-pooled mode │
406 │ │ │ (single-threaded). │
407 └────────────────────┴─────────────────────┴─────────────────────┘
408 │MONGOC_URI_SERVERS‐ │ serverselection‐ │ A timeout in mil‐ │
410 │ELECTIONTIMEOUTMS │ timeoutms │ liseconds to block │
411 │ │ │ for server selec‐ │
412 │ │ │ tion before throw‐ │
413 │ │ │ ing an exception. │
414 │ │ │ The default is │
415 │ │ │ 30,0000ms (30 sec‐ │
416 │ │ │ onds). │
417 ├────────────────────┼─────────────────────┼─────────────────────┤
418 │MONGOC_URI_SERVERS‐ │ serverselectiontry‐ │ If "true", the │
419 │ELECTIONTRYONCE │ once │ driver scans the │
420 │ │ │ topology exactly │
421 │ │ │ once after server │
422 │ │ │ selection fails, │
423 │ │ │ then either selects │
424 │ │ │ a server or returns │
425 │ │ │ an error. If it is │
426 │ │ │ false, then the │
427 │ │ │ driver repeatedly │
428 │ │ │ searches for a │
429 │ │ │ suitable server for │
430 │ │ │ up to serverSelec‐ │
431 │ │ │ tionTimeoutMS mil‐ │
432 │ │ │ liseconds (pausing │
433 │ │ │ a half second │
434 │ │ │ between attempts). │
435 │ │ │ The default for │
436 │ │ │ serverSelectionTry‐ │
437 │ │ │ Once is "false" for │
438 │ │ │ pooled clients, │
439 │ │ │ otherwise "true". │
440 │ │ │ Pooled clients │
441 │ │ │ ignore serverSelec‐ │
442 │ │ │ tionTryOnce; they │
443 │ │ │ signal the thread │
444 │ │ │ to rescan the │
445 │ │ │ topology every │
446 │ │ │ half-second until │
447 │ │ │ serverSelection‐ │
448 │ │ │ TimeoutMS expires. │
449 ├────────────────────┼─────────────────────┼─────────────────────┤
450 │MONGOC_URI_SOCK‐ │ socketcheckinter‐ │ Only applies to │
451 │ETCHECKINTERVALMS │ valms │ single threaded │
452 │ │ │ clients. If a │
453 │ │ │ socket has not been │
454 │ │ │ used within this │
455 │ │ │ time, its connec‐ │
456 │ │ │ tion is checked │
457 │ │ │ with a quick │
458 │ │ │ "isMaster" call │
459 │ │ │ before it is used │
460 │ │ │ again. Defaults to │
461 │ │ │ 5,000ms (5 sec‐ │
462 │ │ │ onds). │
463 └────────────────────┴─────────────────────┴─────────────────────┘
464 Setting any of the *TimeoutMS options above to 0 will be interpreted as
466 "use the default value".
467
469 These options govern the behavior of a mongoc_client_pool_t. They are
470 ignored by a non-pooled mongoc_client_t.
471 ┌────────────────────┬────────────────────┬─────────────────────┐
473 │Constant │ Key │ Description │
474 └────────────────────┴────────────────────┴─────────────────────┘
475 │MONGOC_URI_MAXPOOL‐ │ maxpoolsize │ The maximum number │
478 │SIZE │ │ of clients created │
479 │ │ │ by a mon‐ │
480 │ │ │ goc_client_pool_t │
481 │ │ │ total (both in the │
482 │ │ │ pool and checked │
483 │ │ │ out). The default │
484 │ │ │ value is 100. Once │
485 │ │ │ it is reached, mon‐ │
486 │ │ │ goc_client_pool_pop │
487 │ │ │ blocks until │
488 │ │ │ another thread │
489 │ │ │ pushes a client. │
490 ├────────────────────┼────────────────────┼─────────────────────┤
491 │MONGOC_URI_MINPOOL‐ │ minpoolsize │ Deprecated. This │
492 │SIZE │ │ option's behavior │
493 │ │ │ does not match its │
494 │ │ │ name, and its │
495 │ │ │ actual behavior │
496 │ │ │ will likely hurt │
497 │ │ │ performance. │
498 ├────────────────────┼────────────────────┼─────────────────────┤
499 │MONGOC_URI_MAXIDLE‐ │ maxidletimems │ Not implemented. │
500 │TIMEMS │ │ │
501 ├────────────────────┼────────────────────┼─────────────────────┤
502 │MONGOC_URI_WAIT‐ │ waitqueuemultiple │ Not implemented. │
503 │QUEUEMULTIPLE │ │ │
504 ├────────────────────┼────────────────────┼─────────────────────┤
505 │MONGOC_URI_WAIT‐ │ waitqueuetimeoutms │ Not implemented. │
506 │QUEUETIMEOUTMS │ │ │
507 └────────────────────┴────────────────────┴─────────────────────┘
508
510 ┌───────────────────┬────────────┬─────────────────────┐
511 │Constant │ Key │ Description │
512 └───────────────────┴────────────┴─────────────────────┘
513 MONGOC_URI_W w Determines the
546 write concern
547 (guarantee). Valid
548 values:
549 · 0 = The
551 driver
552 will not
553 acknowl‐
554 edge write
555 operations
556 but will
557 pass or
558 handle any
559 network
560 and socket
561 errors
562 that it
563 receives
564 to the
565 client. If
566 you dis‐
567 able write
568 concern
569 but enable
570 the get‐
571 LastError
572 command’s
573 w option,
574 w over‐
575 rides the
576 w option.
577 · 1 = Pro‐
579 vides
580 basic
581 acknowl‐
582 edgement
583 of write
584 opera‐
585 tions. By
586 specifying
587 1, you
588 require
589 that a
590 standalone
591 mongod
592 instance,
593 or the
594 primary
595 for
596 replica
597 sets,
598 acknowl‐
599 edge all
600 write
601 opera‐
602 tions. For
603 drivers
604 released
605 after the
606 default
607 write con‐
608 cern
609 change,
610 this is
611 the
612 default
613 write con‐
614 cern set‐
615 ting.
616 · majority =
618 For
619 replica
620 sets, if
621 you spec‐
622 ify the
623 special
624 majority
625 value to w
626 option,
627 write
628 operations
629 will only
630 return
631 success‐
632 fully
633 after a
634 majority
635 of the
636 configured
637 replica
638 set mem‐
639 bers have
640 acknowl‐
641 edged the
642 write
643 operation.
644 · n = For
646 replica
647 sets, if
648 you spec‐
649 ify a num‐
650 ber n
651 greater
652 than 1,
653 operations
654 with this
655 write con‐
656 cern
657 return
658 only after
659 n members
660 of the set
661 have
662 acknowl‐
663 edged the
664 write. If
665 you set n
666 to a num‐
667 ber that
668 is greater
669 than the
670 number of
671 available
672 set mem‐
673 bers or
674 members
675 that hold
676 data, Mon‐
677 goDB will
678 wait,
679 poten‐
680 tially
681 indefi‐
682 nitely,
683 for these
684 members to
685 become
686 available.
687 · tags = For
689 replica
690 sets, you
691 can spec‐
692 ify a tag
693 set to
694 require
695 that all
696 members of
697 the set
698 that have
699 these tags
700 configured
701 return
702 confirma‐
703 tion of
704 the write
705 operation.
706 ├───────────────────┼────────────┼─────────────────────┤
707 │MONGOC_URI_WTIME‐ │ wtimeoutms │ The time in mil‐ │
708 │OUTMS │ │ liseconds to wait │
709 │ │ │ for replication to │
710 │ │ │ succeed, as speci‐ │
711 │ │ │ fied in the w │
712 │ │ │ option, before tim‐ │
713 │ │ │ ing out. When │
714 │ │ │ wtimeoutMS is 0, │
715 │ │ │ write operations │
716 │ │ │ will never time │
717 │ │ │ out. │
718 ├───────────────────┼────────────┼─────────────────────┤
719 │MONGOC_URI_JOURNAL │ journal │ Controls whether │
720 │ │ │ write operations │
721 │ │ │ will wait until the │
722 │ │ │ mongod acknowledges │
723 │ │ │ the write opera‐ │
724 │ │ │ tions and commits │
725 │ │ │ the data to the on │
726 │ │ │ disk journal. │
727 │ │ │ │
728 │ │ │ · true = │
729 │ │ │ Enables │
730 │ │ │ journal │
731 │ │ │ commit │
732 │ │ │ acknowl‐ │
733 │ │ │ edgement │
734 │ │ │ write con‐ │
735 │ │ │ cern. │
736 │ │ │ Equivalent │
737 │ │ │ to speci‐ │
738 │ │ │ fying the │
739 │ │ │ getLastEr‐ │
740 │ │ │ ror com‐ │
741 │ │ │ mand with │
742 │ │ │ the j │
743 │ │ │ option │
744 │ │ │ enabled. │
745 │ │ │ │
746 │ │ │ · false = │
747 │ │ │ Does not │
748 │ │ │ require │
749 │ │ │ that mon‐ │
750 │ │ │ god commit │
751 │ │ │ write │
752 │ │ │ operations │
753 │ │ │ to the │
754 │ │ │ journal │
755 │ │ │ before │
756 │ │ │ acknowl‐ │
757 │ │ │ edging the │
758 │ │ │ write │
759 │ │ │ operation. │
760 │ │ │ This is │
761 │ │ │ the │
762 │ │ │ default │
763 │ │ │ option for │
764 │ │ │ the jour‐ │
765 │ │ │ nal param‐ │
766 │ │ │ eter. │
767 └───────────────────┴────────────┴─────────────────────┘
768
770 ┌────────────────────┬──────────────────┬─────────────────────┐
771 │Constant │ Key │ Description │
772 └────────────────────┴──────────────────┴─────────────────────┘
773 │MONGOC_URI_READCON‐ │ readconcernlevel │ The level of isola‐ │
775 │CERNLEVEL │ │ tion for read oper‐ │
776 │ │ │ ations. If the │
777 │ │ │ level is left │
778 │ │ │ unspecified, the │
779 │ │ │ server default will │
780 │ │ │ be used. See │
781 │ │ │ readConcern in the │
782 │ │ │ MongoDB Manual for │
783 │ │ │ details. │
784 └────────────────────┴──────────────────┴─────────────────────┘
785
787 When connected to a replica set, the driver chooses which member to
788 query using the read preference:
789 1. Choose members whose type matches "readPreference".
791 2. From these, if there are any tags sets configured, choose members
793 matching the first tag set. If there are none, fall back to the next
794 tag set and so on, until some members are chosen or the tag sets are
795 exhausted.
796 3. From the chosen servers, distribute queries randomly among the
798 server with the fastest round-trip times. These include the server
799 with the fastest time and any whose round-trip time is no more than
800 "localThresholdMS" slower.
801 ┌─────────────────────┬─────────────────────┬──────────────────────────┐
803 │Constant │ Key │ Description │
804 ├─────────────────────┼─────────────────────┼──────────────────────────┤
805 │MONGOC_URI_READ‐ │ readpreference │ Specifies the │
806 │PREFERENCE │ │ replica set read │
807 │ │ │ preference for this │
808 │ │ │ connection. This │
809 │ │ │ setting overrides │
810 │ │ │ any slaveOk value. │
811 │ │ │ The read preference │
812 │ │ │ values are the fol‐ │
813 │ │ │ lowing: │
814 │ │ │ │
815 │ │ │ · primary │
816 │ │ │ (default) │
817 │ │ │ │
818 │ │ │ · prima‐ │
819 │ │ │ ryPre‐ │
820 │ │ │ ferred │
821 │ │ │ │
822 │ │ │ · secondary │
823 │ │ │ │
824 │ │ │ · sec‐ │
825 │ │ │ ondaryPre‐ │
826 │ │ │ ferred │
827 │ │ │ │
828 │ │ │ · nearest │
829 ├─────────────────────┼─────────────────────┼──────────────────────────┤
830 │MONGOC_URI_READ‐ │ readpreferencetags │ A representation of │
831 │PREFERENCETAGS │ │ a tag set. See also │
832 │ │ │ mon‐ │
833 │ │ │ goc-read-prefs-tag-sets. │
834 └─────────────────────┴─────────────────────┴──────────────────────────┘
835 │MON‐ │ localthresholdms │ How far to distribute │
843 │GOC_URI_LOCALTHRESH‐ │ │ queries, beyond the │
844 │OLDMS │ │ server with the fastest │
845 │ │ │ round-trip time. By │
846 │ │ │ default, only servers │
847 │ │ │ within 15ms of the │
848 │ │ │ fastest round-trip time │
849 │ │ │ receive queries. │
850 ├─────────────────────┼─────────────────────┼──────────────────────────┤
851 │MONGOC_URI_MAXSTALE‐ │ maxstalenessseconds │ The maximum replication │
852 │NESSSECONDS │ │ lag, in wall clock time, │
853 │ │ │ that a secondary can │
854 │ │ │ suffer and still be eli‐ │
855 │ │ │ gible. The smallest │
856 │ │ │ allowed value for │
857 │ │ │ maxStalenessSeconds is │
858 │ │ │ 90 seconds. │
859 └─────────────────────┴─────────────────────┴──────────────────────────┘
860 NOTE:
862 When connecting to more than one mongos, libmongoc's localThresh‐
863 oldMS applies only to the selection of mongos servers. The threshold
864 for selecting among replica set members in shards is controlled by
865 the mongos's localThreshold command line option.
866
868 For historical reasons, the following options are available. They
869 should however not be used.
870 ┌───────────────────┬─────────┬─────────────────────┐
872 │Constant │ Key │ Description │
873 ├───────────────────┼─────────┼─────────────────────┤
874 │MONGOC_URI_SAFE │ safe │ {true|false} Same │
875 │ │ │ as w={1|0} │
876 ├───────────────────┼─────────┼─────────────────────┤
877 │MONGOC_URI_SLAVEOK │ slaveok │ When set, same as │
878 │ │ │ readPreference=sec‐ │
879 │ │ │ ondaryPreferred │
880 └───────────────────┴─────────┴─────────────────────┘
881
883 MongoDB, Inc
884
886 2017-present, MongoDB, Inc
8871.16.2 Feb 25, 2020 MONGOC_URI_T(3)