1MONGOC_URI_T(3)                    libmongoc                   MONGOC_URI_T(3)
2
3
4

NAME

6       mongoc_uri_t - mongoc_uri_t
7

SYNOPSIS

9          typedef struct _mongoc_uri_t mongoc_uri_t;
10

DESCRIPTION

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
17       See Connection String URI Reference on the MongoDB website for more in‐
18       formation.
19

FORMAT

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
29       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
33       2. An optional username and password.
34
35       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
39       4. An optional port number.  Defaults to :27017.
40
41       5. Extra  optional  hosts and ports.  You would specify multiple hosts,
42          for example, for connections to replica sets.
43
44       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
49       7. Connection specific options.
50
51       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
56       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
60       For example, the following calls are equal.
61
62          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

REPLICA SET EXAMPLE

67       To describe a connection to a replica set named 'test' with the follow‐
68       ing mongod hosts:
69
70db1.example.com on port 27017
71
72db2.example.com on port 2500
73
74       You would use a connection string that resembles the following.
75
76          mongodb://db1.example.com,db2.example.com:2500/?replicaSet=test
77

SRV EXAMPLE

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
83          uri = mongoc_uri_new ("mongodb+srv://server.example.com/?replicaSet=rs&appName=applicationName");
84
85       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
91       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

IPV4 AND IPV6

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
105       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
109       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

CONNECTION OPTIONS

114┌───────────────────┬──────────────────┬──────────────────┬─────────────────────────────────────┐
115│Constant           │ Key              │ Default          │ Description                         │
116├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
117│MON‐               │ retryreads       │ true             │ If   "true"  and                    │
118│GOC_URI_RETRYREADS │                  │                  │ the server is  a                    │
119│                   │                  │                  │ MongoDB     3.6+                    │
120│                   │                  │                  │ standalone,                         │
121│                   │                  │                  │ replica  set, or                    │
122│                   │                  │                  │ sharded cluster,                    │
123│                   │                  │                  │ the       driver                    │
124│                   │                  │                  │ safely retries a                    │
125│                   │                  │                  │ read that failed                    │
126│                   │                  │                  │ due to a network                    │
127│                   │                  │                  │ error or replica                    │
128│                   │                  │                  │ set failover.                       │
129└───────────────────┴──────────────────┴──────────────────┴─────────────────────────────────────┘
130
131
132
133
134
135
136
137│MONGOC_URI_RETRY‐  │ retrywrites      │ true  if  driver │ If  "true"   and                    │
138│WRITES             │                  │ built w/ TLS     │ the  server is a                    │
139│                   │                  │                  │ MongoDB     3.6+                    │
140│                   │                  │                  │ replica  set  or                    │
141│                   │                  │                  │ sharded cluster,                    │
142│                   │                  │                  │ the       driver                    │
143│                   │                  │                  │ safely retries a                    │
144│                   │                  │                  │ write       that                    │
145│                   │                  │                  │ failed due to  a                    │
146│                   │                  │                  │ network error or                    │
147│                   │                  │                  │ replica      set                    │
148│                   │                  │                  │ failover.   Only                    │
149│                   │                  │                  │ inserts, updates                    │
150│                   │                  │                  │ of  single docu‐                    │
151│                   │                  │                  │ ments,        or                    │
152│                   │                  │                  │ deletes  of sin‐                    │
153│                   │                  │                  │ gle    documents                    │
154│                   │                  │                  │ are retried.                        │
155├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
156│MONGOC_URI_APPNAME │ appname          │ Empty  (no  app‐ │ The  client  ap‐                    │
157│                   │                  │ name)            │ plication  name.                    │
158│                   │                  │                  │ This  value   is                    │
159│                   │                  │                  │ used  by MongoDB                    │
160│                   │                  │                  │ when   it   logs                    │
161│                   │                  │                  │ connection   in‐                    │
162│                   │                  │                  │ formation    and                    │
163│                   │                  │                  │ profile informa‐                    │
164│                   │                  │                  │ tion,  such   as                    │
165│                   │                  │                  │ slow queries.                       │
166├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
167│MONGOC_URI_TLS     │ tls              │ Empty  (not set, │ {true|false},                       │
168│                   │                  │ same as false)   │ indicating    if                    │
169│                   │                  │                  │ TLS   must    be                    │
170│                   │                  │                  │ used.  (See also                    │
171│                   │                  │                  │ mongoc_client_set_ssl_opts()
172│                   │                  │                  │ and                                 │
173│                   │                  │                  │ mongoc_client_pool_set_ssl_opts().) │
174├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
175│MONGOC_URI_COM‐    │ compressors      │ Empty  (no  com‐ │ Comma  separated  list  of compres‐ │
176│PRESSORS           │                  │ pressors)        │ sors, if any, to  use  to  compress │
177│                   │                  │                  │ the wire protocol messages. Snappy, │
178│                   │                  │                  │ zlib, and zstd are  optional  build │
179│                   │                  │                  │ time  dependencies,  and enable the │
180│                   │                  │                  │ "snappy", "zlib", and "zstd" values │
181│                   │                  │                  │ respectively.                       │
182├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
183│MONGOC_URI_CON‐    │ connecttimeoutms │ 10,000  ms   (10 │ This  setting applies to new server │
184│NECTTIMEOUTMS      │                  │ seconds)         │ connections. It is also used as the │
185│                   │                  │                  │ socket timeout for server discovery │
186│                   │                  │                  │ and monitoring operations.          │
187├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
188│MONGOC_URI_SOCKET‐ │ sockettimeoutms  │ 300,000   ms  (5 │ The time in milliseconds to attempt │
189│TIMEOUTMS          │                  │ minutes)         │ to  send or receive on a socket be‐ │
190│                   │                  │                  │ fore the attempt times out.         │
191├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
192│MONGOC_URI_REPLI‐  │ replicaset       │ Empty (no repli‐ │ The name of the  Replica  Set  that │
193│CASET              │                  │ caset)           │ the driver should connect to.       │
194├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
195│MONGOC_URI_ZLIB‐   │ zlibcompression‐ │ -1               │ When the MONGOC_URI_COMPRESSORS in‐ │
196│COMPRESSIONLEVEL   │ level            │                  │ cludes "zlib" this options  config‐ │
197│                   │                  │                  │ ures  the  zlib  compression level, │
198│                   │                  │                  │ when the zlib compressor is used to │
199│                   │                  │                  │ compress client data.               │
200└───────────────────┴──────────────────┴──────────────────┴─────────────────────────────────────┘
201
202
203
204
205│MONGOC_URI_LOAD‐   │ loadbalanced     │ false            │ If true, this indicates the  driver │
206│BALANCED           │                  │                  │ is  connecting to a MongoDB cluster │
207│                   │                  │                  │ behind a load balancer.             │
208├───────────────────┼──────────────────┼──────────────────┼─────────────────────────────────────┤
209│MONGOC_URI_SRVMAX‐ │ srvmaxhosts      │ 0                │ If zero, the number of hosts in DNS │
210│HOSTS              │                  │                  │ results is  unlimited.  If  greater │
211│                   │                  │                  │ than  zero,  the number of hosts in │
212│                   │                  │                  │ DNS results  is  limited  to  being │
213│                   │                  │                  │ less  than  or  equal  to the given │
214│                   │                  │                  │ value.                              │
215└───────────────────┴──────────────────┴──────────────────┴─────────────────────────────────────┘
216
217       Setting any of the *timeoutMS options above to 0 will be interpreted as
218       "use the default value".
219

AUTHENTICATION OPTIONS

221          ┌────────────────────┬────────────────────┬─────────────────────┐
222          │Constant            │ Key                │ Description         │
223          ├────────────────────┼────────────────────┼─────────────────────┤
224          │MONGOC_URI_AUTH‐    │ authmechanism      │ Specifies the mech‐ │
225          │MECHANISM           │                    │ anism  to  use when │
226          │                    │                    │ authenticating   as │
227          │                    │                    │ the  provided user. │
228          │                    │                    │ See  Authentication
229          │                    │                    │ for  supported val‐ │
230          │                    │                    │ ues.                │
231          ├────────────────────┼────────────────────┼─────────────────────┤
232          │MONGOC_URI_AUTH‐    │ authmechanismprop‐ │ Certain authentica‐ │
233          │MECHANISMPROPERTIES │ erties             │ tion     mechanisms │
234          │                    │                    │ have additional op‐ │
235          │                    │                    │ tions  that  can be │
236          │                    │                    │ configured.   These │
237          │                    │                    │ options  should  be │
238          │                    │                    │ provided  as  comma │
239          │                    │                    │ separated       op‐ │
240          │                    │                    │ tion_key:op‐        │
241          │                    │                    │ tion_value pair and │
242          │                    │                    │ provided  as  auth‐ │
243          │                    │                    │ MechanismProper‐    │
244          │                    │                    │ ties.    Specifying │
245          │                    │                    │ the same option_key │
246          │                    │                    │ multiple times  has │
247          │                    │                    │ undefined behavior. │
248          ├────────────────────┼────────────────────┼─────────────────────┤
249          │MONGOC_URI_AUTH‐    │ authsource         │ The authSource  de‐ │
250          │SOURCE              │                    │ fines  the database │
251          │                    │                    │ that should be used │
252          │                    │                    │ to authenticate to. │
253          │                    │                    │ It  is  unnecessary │
254          │                    │                    │ to provide this op‐ │
255          │                    │                    │ tion  the  database │
256          │                    │                    │ name is the same as │
257          │                    │                    │ the  database  used │
258          │                    │                    │ in the URI.         │
259          └────────────────────┴────────────────────┴─────────────────────┘
260
261   Mechanism Properties
262           ┌────────────────────┬───────────────────┬─────────────────────┐
263           │Constant            │ Key               │ Description         │
264           └────────────────────┴───────────────────┴─────────────────────┘
265
266
267
268
269
270
271
272
273           │MONGOC_URI_CANONI‐  │ canonicalizehost‐ │ Use  the  canonical │
274           │CALIZEHOSTNAME      │ name              │ hostname   of   the │
275           │                    │                   │ service,     rather │
276           │                    │                   │ than its configured │
277           │                    │                   │ alias, when authen‐ │
278           │                    │                   │ ticating       with │
279           │                    │                   │ Cyrus-SASL     Ker‐ │
280           │                    │                   │ beros.              │
281           ├────────────────────┼───────────────────┼─────────────────────┤
282           │MONGOC_URI_GSSAPIS‐ │ gssapiservicename │ Use     alternative │
283           │ERVICENAME          │                   │ service  name.  The │
284           │                    │                   │ default is mongodb. │
285           └────────────────────┴───────────────────┴─────────────────────┘
286

TLS OPTIONS

288          ┌────────────────────┬─────────────────────┬─────────────────────┐
289          │Constant            │ Key                 │ Description         │
290          ├────────────────────┼─────────────────────┼─────────────────────┤
291          │MONGOC_URI_TLS      │ tls                 │ {true|false}, indi‐ │
292          │                    │                     │ cating if TLS  must │
293          │                    │                     │ be used.            │
294          ├────────────────────┼─────────────────────┼─────────────────────┤
295          │MONGOC_URI_TLSCER‐  │ tlscertificatekey‐  │ Path to PEM format‐ │
296          │TIFICATEKEYFILE     │ file                │ ted  Private   Key, │
297          │                    │                     │ with   its   Public │
298          │                    │                     │ Certificate    con‐ │
299          │                    │                     │ catenated   at  the │
300          │                    │                     │ end.                │
301          ├────────────────────┼─────────────────────┼─────────────────────┤
302          │MONGOC_URI_TLSCER‐  │ tlscertificatekey‐  │ The   password,  if │
303          │TIFICATEKEY‐        │ password            │ any, to use to  un‐ │
304          │FILEPASSWORD        │                     │ lock encrypted Pri‐ │
305          │                    │                     │ vate Key.           │
306          ├────────────────────┼─────────────────────┼─────────────────────┤
307          │MON‐                │ tlscafile           │ One,  or  a  bundle │
308          │GOC_URI_TLSCAFILE   │                     │ of, Certificate Au‐ │
309          │                    │                     │ thorities      whom │
310          │                    │                     │ should  be  consid‐ │
311          │                    │                     │ ered to be trusted. │
312          ├────────────────────┼─────────────────────┼─────────────────────┤
313          │MONGOC_URI_TLSAL‐   │ tlsallowinvalidcer‐ │ Accept  and  ignore │
314          │LOWINVALIDCERTIFI‐  │ tificates           │ certificate verifi‐ │
315          │CATES               │                     │ cation errors (e.g. │
316          │                    │                     │ untrusted   issuer, │
317          │                    │                     │ expired, etc.)      │
318          ├────────────────────┼─────────────────────┼─────────────────────┤
319          │MONGOC_URI_TLSAL‐   │ tlsallowinvalid‐    │ Ignore     hostname │
320          │LOWINVALIDHOSTNAMES │ hostnames           │ verification of the │
321          │                    │                     │ certificate   (e.g. │
322          │                    │                     │ Man  In The Middle, │
323          │                    │                     │ using  valid   cer‐ │
324          │                    │                     │ tificate,  but  is‐ │
325          │                    │                     │ sued  for   another │
326          │                    │                     │ hostname)           │
327          ├────────────────────┼─────────────────────┼─────────────────────┤
328          │MONGOC_URI_TLSINSE‐ │ tlsinsecure         │ {true|false}, indi‐ │
329          │CURE                │                     │ cating  if insecure │
330          │                    │                     │ TLS options  should │
331          │                    │                     │ be  used. Currently │
332          │                    │                     │ this  implies  MON‐ │
333          │                    │                     │ GOC_URI_TLSALLOWIN‐ │
334          │                    │                     │ VALIDCERTIFICATES   │
335          │                    │                     │ and  MONGOC_URI_TL‐ │
336          │                    │                     │ SALLOWINVALIDHOST‐  │
337          │                    │                     │ NAMES.              │
338          └────────────────────┴─────────────────────┴─────────────────────┘
339
340
341          │MONGOC_URI_TLSDIS‐  │ tlsdisablecertifi‐  │ {true|false}, indi‐ │
342          │ABLECERTIFICATERE‐  │ caterevocationcheck │ cates if revocation │
343          │VOCATIONCHECK       │                     │ checking   (CRL   / │
344          │                    │                     │ OCSP)   should   be │
345          │                    │                     │ disabled.           │
346          ├────────────────────┼─────────────────────┼─────────────────────┤
347          │MONGOC_URI_TLSDIS‐  │ tlsdisableocspend‐  │ {true|false}, indi‐ │
348          │ABLEOCSPEND‐        │ pointcheck          │ cates if  OCSP  re‐ │
349          │POINTCHECK          │                     │ sponder   endpoints │
350          │                    │                     │ should not  be  re‐ │
351          │                    │                     │ quested   when   an │
352          │                    │                     │ OCSP  response   is │
353          │                    │                     │ not stapled.        │
354          └────────────────────┴─────────────────────┴─────────────────────┘
355
356       See  Configuring TLS for details about these options and about building
357       libmongoc with TLS support.
358

DEPRECATED SSL OPTIONS

360       The following options have been deprecated and may be removed from  fu‐
361       ture releases of libmongoc.
362
363  ┌──────────────────────┬──────────────────┬───────────────────┬──────────────────┐
364  │Constant              │ Key              │ Deprecated For    │ Key              │
365  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
366  │MONGOC_URI_SSL        │ ssl              │ MONGOC_URI_TLS    │ tls              │
367  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
368  │MON‐                  │ sslclientcer‐    │ MON‐              │ tlscertifi‐      │
369  │GOC_URI_SSLCLIENTCER‐ │ tificatekeyfile  │ GOC_URI_TLSCER‐   │ catekeyfile      │
370  │TIFICATEKEYFILE       │                  │ TIFICATEKEYFILE   │                  │
371  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
372  │MON‐                  │ sslclientcer‐    │ MON‐              │ tlscertifi‐      │
373  │GOC_URI_SSLCLIENTCER‐ │ tificatekeypass‐ │ GOC_URI_TLSCER‐   │ catekeypassword  │
374  │TIFICATEKEYPASSWORD   │ word             │ TIFICATEKEY‐      │                  │
375  │                      │                  │ FILEPASSWORD      │                  │
376  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
377  │MONGOC_URI_SSLCER‐    │ sslcertifi‐      │ MON‐              │ tlscafile        │
378  │TIFICATEAUTHORITYFILE │ cateauthority‐   │ GOC_URI_TLSCAFILE │                  │
379  │                      │ file             │                   │                  │
380  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
381  │MONGOC_URI_SSLALLOW‐  │ sslallowinvalid‐ │ MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │
382  │INVALIDCERTIFICATES   │ certificates     │ LOWINVALIDCER‐    │ certificates     │
383  │                      │                  │ TIFICATES         │                  │
384  ├──────────────────────┼──────────────────┼───────────────────┼──────────────────┤
385  │MONGOC_URI_SSLALLOW‐  │ sslallowinvalid‐ │ MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │
386  │INVALIDHOSTNAMES      │ hostnames        │ LOWINVALIDHOST‐   │ hostnames        │
387  │                      │                  │ NAMES             │                  │
388  └──────────────────────┴──────────────────┴───────────────────┴──────────────────┘
389

SERVER DISCOVERY, MONITORING, AND SELECTION OPTIONS

391       Clients in a mongoc_client_pool_t share a topology scanner that runs on
392       a  background  thread. The thread wakes every heartbeatFrequencyMS (de‐
393       fault 10 seconds) to scan all MongoDB servers in parallel. Whenever  an
394       application operation requires a server that is not known--for example,
395       if there is no known primary  and  your  application  attempts  an  in‐
396       sert--the  thread rescans all servers every half-second. In this situa‐
397       tion the pooled client waits up to serverSelectionTimeoutMS (default 30
398       seconds)  for  the  thread to find a server suitable for the operation,
399       then returns an error with domain MONGOC_ERROR_SERVER_SELECTION.
400
401       Technically, the total time an operation may wait while a pooled client
402       scans  the  topology is controlled both by serverSelectionTimeoutMS and
403       connectTimeoutMS. The longest wait occurs if the last scan begins  just
404       at the end of the selection timeout, and a slow or down server requires
405       the full connection timeout before the client gives up.
406
407       A non-pooled client is single-threaded. Every heartbeatFrequencyMS,  it
408       blocks  the  next  application operation while it does a parallel scan.
409       This scan takes as long as needed to check the slowest server:  roughly
410       connectTimeoutMS.  Therefore  the default heartbeatFrequencyMS for sin‐
411       gle-threaded clients is greater than for pooled clients: 60 seconds.
412
413       By default, single-threaded (non-pooled) clients scan only once when an
414       operation requires a server that is not known. If you attempt an insert
415       and there is no known primary, the client checks all servers once  try‐
416       ing  to  find  it,  then  succeeds or returns an error with domain MON‐
417       GOC_ERROR_SERVER_SELECTION. But if you  set  serverSelectionTryOnce  to
418       "false",  the  single-threaded client loops, checking all servers every
419       half-second, until serverSelectionTimeoutMS.
420
421       The total time an operation may wait for a  single-threaded  client  to
422       scan  the  topology  is  determined by connectTimeoutMS in the try-once
423       case, or serverSelectionTimeoutMS and connectTimeoutMS if  serverSelec‐
424       tionTryOnce is set "false".
425
426          ┌────────────────────┬─────────────────────┬─────────────────────┐
427          │Constant            │ Key                 │ Description         │
428          ├────────────────────┼─────────────────────┼─────────────────────┤
429          │MONGOC_URI_HEART‐   │ heartbeatfrequen‐   │ The   interval  be‐ │
430          │BEATFREQUENCYMS     │ cyms                │ tween server  moni‐ │
431          │                    │                     │ toring  checks. De‐ │
432          │                    │                     │ faults to  10,000ms │
433          │                    │                     │ (10   seconds)   in │
434          │                    │                     │ pooled              │
435          │                    │                     │ (multi-threaded)    │
436          │                    │                     │ mode, 60,000ms  (60 │
437          │                    │                     │ seconds)         in │
438          │                    │                     │ non-pooled     mode │
439          │                    │                     │ (single-threaded).  │
440          ├────────────────────┼─────────────────────┼─────────────────────┤
441          │MONGOC_URI_SERVERS‐ │ serverselection‐    │ A  timeout  in mil‐ │
442          │ELECTIONTIMEOUTMS   │ timeoutms           │ liseconds to  block │
443          │                    │                     │ for  server  selec‐ │
444          │                    │                     │ tion before  throw‐ │
445          │                    │                     │ ing  an  exception. │
446          │                    │                     │ The   default    is │
447          │                    │                     │ 30,0000ms  (30 sec‐ │
448          │                    │                     │ onds).              │
449          └────────────────────┴─────────────────────┴─────────────────────┘
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477          │MONGOC_URI_SERVERS‐ │ serverselectiontry‐ │ If   "true",    the │
478          │ELECTIONTRYONCE     │ once                │ driver   scans  the │
479          │                    │                     │ topology    exactly │
480          │                    │                     │ once  after  server │
481          │                    │                     │ selection    fails, │
482          │                    │                     │ then either selects │
483          │                    │                     │ a server or returns │
484          │                    │                     │ an  error. If it is │
485          │                    │                     │ false,   then   the │
486          │                    │                     │ driver   repeatedly │
487          │                    │                     │ searches   for    a │
488          │                    │                     │ suitable server for │
489          │                    │                     │ up to  serverSelec‐ 
490          │                    │                     │ tionTimeoutMS  mil‐ │
491          │                    │                     │ liseconds  (pausing │
492          │                    │                     │ a  half  second be‐ │
493          │                    │                     │ tween    attempts). │
494          │                    │                     │ The   default   for │
495          │                    │                     │ serverSelectionTry‐ 
496          │                    │                     │ Once is "false" for │
497          │                    │                     │ pooled     clients, │
498          │                    │                     │ otherwise   "true". │
499          │                    │                     │ Pooled clients  ig‐ │
500          │                    │                     │ nore   serverSelec‐ │
501          │                    │                     │ tionTryOnce;   they │
502          │                    │                     │ signal  the  thread │
503          │                    │                     │ to    rescan    the │
504          │                    │                     │ topology      every │
505          │                    │                     │ half-second   until │
506          │                    │                     │ serverSelection‐    │
507          │                    │                     │ TimeoutMS expires.  │
508          ├────────────────────┼─────────────────────┼─────────────────────┤
509          │MONGOC_URI_SOCK‐    │ socketcheckinter‐   │ Only   applies   to │
510          │ETCHECKINTERVALMS   │ valms               │ single     threaded │
511          │                    │                     │ clients.    If    a │
512          │                    │                     │ socket has not been │
513          │                    │                     │ used  within   this │
514          │                    │                     │ time,  its  connec‐ │
515          │                    │                     │ tion   is   checked │
516          │                    │                     │ with     a    quick │
517          │                    │                     │ "hello" call before │
518          │                    │                     │ it  is  used again. │
519          │                    │                     │ Defaults to 5,000ms │
520          │                    │                     │ (5 seconds).        │
521          ├────────────────────┼─────────────────────┼─────────────────────┤
522          │MONGOC_URI_DIRECT‐  │ directconnection    │ If   "true",    the │
523          │CONNECTION          │                     │ driver  connects to │
524          │                    │                     │ a single server di‐ │
525          │                    │                     │ rectly and will not │
526          │                    │                     │ monitor  additional │
527          │                    │                     │ servers.         If │
528          │                    │                     │ "false", the driver │
529          │                    │                     │ connects  based  on │
530          │                    │                     │ the  presence   and │
531          │                    │                     │ value of the repli‐ 
532          │                    │                     │ caSet option.       │
533          └────────────────────┴─────────────────────┴─────────────────────┘
534
535       Setting any of the *TimeoutMS options above to 0 will be interpreted as
536       "use the default value".
537

CONNECTION POOL OPTIONS

539       These  options  govern the behavior of a mongoc_client_pool_t. They are
540       ignored by a non-pooled mongoc_client_t.
541
542
543
544
545        ┌────────────────────┬────────────────────┬──────────────────────────┐
546        │Constant            │ Key                │ Description              │
547        ├────────────────────┼────────────────────┼──────────────────────────┤
548        │MONGOC_URI_MAXPOOL‐ │ maxpoolsize        │ The  maximum number      │
549        │SIZE                │                    │ of clients  created      │
550        │                    │                    │ by                a      │
551        │                    │                    │ mongoc_client_pool_t
552        │                    │                    │ total  (both in the      │
553        │                    │                    │ pool  and   checked      │
554        │                    │                    │ out).  The  default      │
555        │                    │                    │ value is 100.  Once      │
556        │                    │                    │ it    is   reached,      │
557        │                    │                    │ mongoc_client_pool_pop()
558        │                    │                    │ blocks   until  an‐      │
559        │                    │                    │ other thread pushes      │
560        │                    │                    │ a client.                │
561        ├────────────────────┼────────────────────┼──────────────────────────┤
562        │MONGOC_URI_MINPOOL‐ │ minpoolsize        │ Deprecated.   This   op‐ │
563        │SIZE                │                    │ tion's behavior does not │
564        │                    │                    │ match its name, and  its │
565        │                    │                    │ actual   behavior   will │
566        │                    │                    │ likely hurt performance. │
567        ├────────────────────┼────────────────────┼──────────────────────────┤
568        │MONGOC_URI_MAXIDLE‐ │ maxidletimems      │ Not implemented.         │
569        │TIMEMS              │                    │                          │
570        ├────────────────────┼────────────────────┼──────────────────────────┤
571        │MONGOC_URI_WAIT‐    │ waitqueuemultiple  │ Not implemented.         │
572        │QUEUEMULTIPLE       │                    │                          │
573        ├────────────────────┼────────────────────┼──────────────────────────┤
574        │MONGOC_URI_WAIT‐    │ waitqueuetimeoutms │ The maximum time to wait │
575        │QUEUETIMEOUTMS      │                    │ for a client  to  become │
576        │                    │                    │ available from the pool. │
577        └────────────────────┴────────────────────┴──────────────────────────┘
578

WRITE CONCERN OPTIONS

580               ┌───────────────────┬────────────┬─────────────────────┐
581               │Constant           │ Key        │ Description         │
582               └───────────────────┴────────────┴─────────────────────┘
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613                MONGOC_URI_W         w            Determines      the
614                                                  write       concern
615                                                  (guarantee).  Valid
616                                                  values:
617
618                                                         • 0  =   The
619                                                           driver
620                                                           will   not
621                                                           acknowl‐
622                                                           edge write
623                                                           operations
624                                                           but   will
625                                                           pass    or
626                                                           handle any
627                                                           network
628                                                           and socket
629                                                           errors
630                                                           that    it
631                                                           receives
632                                                           to     the
633                                                           client. If
634                                                           you   dis‐
635                                                           able write
636                                                           concern
637                                                           but enable
638                                                           the   get‐
639                                                           LastError
640                                                           command’s
641                                                           w  option,
642                                                           w    over‐
643                                                           rides  the
644                                                           w option.
645
646                                                         • 1  =  Pro‐
647                                                           vides  ba‐
648                                                           sic    ac‐
649                                                           knowledge‐
650                                                           ment    of
651                                                           write  op‐
652                                                           erations.
653                                                           By  speci‐
654                                                           fying   1,
655                                                           you    re‐
656                                                           quire that
657                                                           a   stand‐
658                                                           alone mon‐
659                                                           god    in‐
660                                                           stance, or
661                                                           the   pri‐
662                                                           mary   for
663                                                           replica
664                                                           sets,  ac‐
665                                                           knowledge
666                                                           all  write
667                                                           opera‐
668                                                           tions. For
669                                                           drivers
670                                                           released
671                                                           after  the
672                                                           default
673                                                           write con‐
674                                                           cern
675                                                           change,
676                                                           this    is
677                                                           the    de‐
678                                                           fault
679                                                           write con‐
680                                                           cern  set‐
681                                                           ting.
682
683                                                         • majority =
684                                                           For
685                                                           replica
686                                                           sets,   if
687                                                           you  spec‐
688                                                           ify    the
689                                                           special
690                                                           majority
691                                                           value to w
692                                                           option,
693                                                           write  op‐
694                                                           erations
695                                                           will  only
696                                                           return
697                                                           success‐
698                                                           fully  af‐
699                                                           ter  a ma‐
700                                                           jority  of
701                                                           the   con‐
702                                                           figured
703                                                           replica
704                                                           set   mem‐
705                                                           bers  have
706                                                           acknowl‐
707                                                           edged  the
708                                                           write  op‐
709                                                           eration.
710
711                                                         • n   =  For
712                                                           replica
713                                                           sets,   if
714                                                           you  spec‐
715                                                           ify a num‐
716                                                           ber      n
717                                                           greater
718                                                           than    1,
719                                                           operations
720                                                           with  this
721                                                           write con‐
722                                                           cern   re‐
723                                                           turn  only
724                                                           after    n
725                                                           members of
726                                                           the    set
727                                                           have   ac‐
728                                                           knowledged
729                                                           the write.
730                                                           If you set
731                                                           n   to   a
732                                                           number
733                                                           that    is
734                                                           greater
735                                                           than   the
736                                                           number  of
737                                                           available
738                                                           set   mem‐
739                                                           bers    or
740                                                           members
741                                                           that  hold
742                                                           data, Mon‐
743                                                           goDB  will
744                                                           wait,  po‐
745                                                           tentially
746                                                           indefi‐
747                                                           nitely,
748                                                           for  these
749                                                           members to
750                                                           become
751                                                           available.
752
753                                                         • tags = For
754                                                           replica
755                                                           sets,  you
756                                                           can  spec‐
757                                                           ify  a tag
758                                                           set to re‐
759                                                           quire that
760                                                           all   mem‐
761                                                           bers    of
762                                                           the    set
763                                                           that  have
764                                                           these tags
765                                                           configured
766                                                           return
767                                                           confirma‐
768                                                           tion    of
769                                                           the  write
770                                                           operation.
771               ├───────────────────┼────────────┼─────────────────────┤
772               │MONGOC_URI_WTIME‐  │ wtimeoutms │ The  time  in  mil‐ │
773               │OUTMS              │            │ liseconds  to  wait │
774               │                   │            │ for  replication to │
775               │                   │            │ succeed, as  speci‐ │
776               │                   │            │ fied  in  the w op‐ │
777               │                   │            │ tion, before timing │
778               │                   │            │ out.   When  wtime‐ │
779               │                   │            │ outMS is  0,  write │
780               │                   │            │ operations     will │
781               │                   │            │ never time out.     │
782               ├───────────────────┼────────────┼─────────────────────┤
783               │MONGOC_URI_JOURNAL │ journal    │ Controls    whether │
784               │                   │            │ write    operations │
785               │                   │            │ will wait until the │
786               │                   │            │ mongod acknowledges │
787               │                   │            │ the  write   opera‐ │
788               │                   │            │ tions  and  commits │
789               │                   │            │ the data to the  on │
790               │                   │            │ disk journal.       │
791               │                   │            │                     │
792               │                   │            │        • true     = │
793               │                   │            │          Enables    │
794               │                   │            │          journal    │
795               │                   │            │          commit ac‐ │
796               │                   │            │          knowledge‐ │
797               │                   │            │          ment write │
798               │                   │            │          concern.   │
799               │                   │            │          Equivalent │
800               │                   │            │          to  speci‐ │
801               │                   │            │          fying  the │
802               │                   │            │          getLastEr‐ │
803               │                   │            │          ror   com‐ │
804               │                   │            │          mand  with │
805               │                   │            │          the j  op‐ │
806               │                   │            │          tion   en‐ │
807               │                   │            │          abled.     │
808               │                   │            │                     │
809               │                   │            │        • false    = │
810               │                   │            │          Does   not │
811               │                   │            │          require    │
812               │                   │            │          that  mon‐ │
813               │                   │            │          god commit │
814               │                   │            │          write  op‐ │
815               │                   │            │          erations   │
816               │                   │            │          to     the │
817               │                   │            │          journal    │
818               │                   │            │          before ac‐ │
819               │                   │            │          knowledg‐  │
820               │                   │            │          ing    the │
821               │                   │            │          write  op‐ │
822               │                   │            │          eration.   │
823               │                   │            │          This    is │
824               │                   │            │          the    de‐ │
825               │                   │            │          fault  op‐ │
826               │                   │            │          tion   for │
827               │                   │            │          the  jour‐ │
828               │                   │            │          nal param‐ │
829               │                   │            │          eter.      │
830               └───────────────────┴────────────┴─────────────────────┘
831

READ CONCERN OPTIONS

833           ┌────────────────────┬──────────────────┬─────────────────────┐
834           │Constant            │ Key              │ Description         │
835           └────────────────────┴──────────────────┴─────────────────────┘
836
837
838
839           │MONGOC_URI_READCON‐ │ readconcernlevel │ The level of isola‐ │
840           │CERNLEVEL           │                  │ tion for read oper‐ │
841           │                    │                  │ ations.    If   the │
842           │                    │                  │ level is  left  un‐ │
843           │                    │                  │ specified,      the │
844           │                    │                  │ server default will │
845           │                    │                  │ be     used.    See │
846           │                    │                  │ readConcern in  the
847           │                    │                  │ MongoDB  Manual for │
848           │                    │                  │ details.            │
849           └────────────────────┴──────────────────┴─────────────────────┘
850

READ PREFERENCE OPTIONS

852       When connected to a replica set, the driver  chooses  which  member  to
853       query using the read preference:
854
855       1. Choose members whose type matches "readPreference".
856
857       2. From  these,  if  there are any tags sets configured, choose members
858          matching the first tag set. If there are none, fall back to the next
859          tag set and so on, until some members are chosen or the tag sets are
860          exhausted.
861
862       3. From the chosen  servers,  distribute  queries  randomly  among  the
863          server  with  the fastest round-trip times. These include the server
864          with the fastest time and any whose round-trip time is no more  than
865          "localThresholdMS" slower.
866
867          ┌────────────────────┬─────────────────────┬─────────────────────┐
868          │Constant            │ Key                 │ Description         │
869          ├────────────────────┼─────────────────────┼─────────────────────┤
870          │MONGOC_URI_READ‐    │ readpreference      │ Specifies       the │
871          │PREFERENCE          │                     │ replica   set  read │
872          │                    │                     │ preference for this │
873          │                    │                     │ connection.    This │
874          │                    │                     │ setting   overrides │
875          │                    │                     │ any     secondaryOk │
876          │                    │                     │ value.   The   read │
877          │                    │                     │ preference   values │
878          │                    │                     │ are the following:  │
879          │                    │                     │                     │
880          │                    │                     │        • primary    │
881          │                    │                     │          (default)  │
882          │                    │                     │                     │
883          │                    │                     │        • prima‐     │
884          │                    │                     │          ryPre‐     │
885          │                    │                     │          ferred     │
886          │                    │                     │                     │
887          │                    │                     │        • secondary  │
888          │                    │                     │                     │
889          │                    │                     │        • sec‐       │
890          │                    │                     │          ondaryPre‐ │
891          │                    │                     │          ferred     │
892          │                    │                     │                     │
893          │                    │                     │        • nearest    │
894          ├────────────────────┼─────────────────────┼─────────────────────┤
895          │MONGOC_URI_READ‐    │ readpreferencetags  │ A representation of │
896          │PREFERENCETAGS      │                     │ a tag set. See also │
897          │                    │                     │ Tag Sets.           │
898          └────────────────────┴─────────────────────┴─────────────────────┘
899
900
901
902
903
904
905
906
907          │MONGOC_URI_LO‐      │ localthresholdms    │ How far to distrib‐ │
908          │CALTHRESHOLDMS      │                     │ ute queries, beyond │
909          │                    │                     │ the server with the │
910          │                    │                     │ fastest  round-trip │
911          │                    │                     │ time.  By  default, │
912          │                    │                     │ only servers within │
913          │                    │                     │ 15ms of the fastest │
914          │                    │                     │ round-trip time re‐ │
915          │                    │                     │ ceive queries.      │
916          ├────────────────────┼─────────────────────┼─────────────────────┤
917          │MONGOC_URI_MAXSTAL‐ │ maxstalenessseconds │ The maximum  repli‐ │
918          │ENESSSECONDS        │                     │ cation lag, in wall │
919          │                    │                     │ clock time, that  a │
920          │                    │                     │ secondary  can suf‐ │
921          │                    │                     │ fer  and  still  be │
922          │                    │                     │ eligible.       The │
923          │                    │                     │ smallest    allowed │
924          │                    │                     │ value for maxStale‐ │
925          │                    │                     │ nessSeconds  is  90 │
926          │                    │                     │ seconds.            │
927          └────────────────────┴─────────────────────┴─────────────────────┘
928
929       NOTE:
930          When  connecting  to  more than one mongos, libmongoc's localThresh‐
931          oldMS applies only to the selection of mongos servers. The threshold
932          for  selecting  among replica set members in shards is controlled by
933          the mongos's localThreshold command line option.
934

LEGACY OPTIONS

936       For historical reasons,  the  following  options  are  available.  They
937       should however not be used.
938
939                   ┌────────────────┬──────┬─────────────────────┐
940                   │Constant        │ Key  │ Description         │
941                   ├────────────────┼──────┼─────────────────────┤
942                   │MONGOC_URI_SAFE │ safe │ {true|false}   Same │
943                   │                │      │ as w={1|0}          │
944                   └────────────────┴──────┴─────────────────────┘
945

AUTHOR

947       MongoDB, Inc
948
950       2017-present, MongoDB, Inc
951
952
953
954
9551.23.1                           Oct 20, 2022                  MONGOC_URI_T(3)
Impressum