Provided by: libmongoc-doc_1.9.2+dfsg-1build1_all 
NAME
mongoc_uri_t - mongoc_uri_t
SYNOPSIS
typedef struct _mongoc_uri_t mongoc_uri_t;
DESCRIPTION
mongoc_uri_t provides an abstraction on top of the MongoDB connection URI format. It provides
standardized parsing as well as convenience methods for extracting useful information such as replica
hosts or authorization information.
See Connection String URI Reference on the MongoDB website for more information.
FORMAT
mongodb[+srv]:// <1>
[username:password@] <2>
host1 <3>
[:port1] <4>
[,host2[:port2],...[,hostN[:portN]]] <5>
[/[database] <6>
[?options]] <7>
1. "mongodb" is the specifier of the MongoDB protocol. Use "mongodb+srv" with a single service name in
place of "host1" to specify the initial list of servers with an SRV record.
2. An optional username and password.
3. The only required part of the uri. This specifies either a hostname, IP address or UNIX domain
socket.
4. An optional port number. Defaults to :27017.
5. Extra optional hosts and ports. You would specify multiple hosts, for example, for connections to
replica sets.
6. The name of the database to authenticate if the connection string includes authentication credentials.
If /database is not specified and the connection string includes credentials, defaults to the 'admin'
database.
7. Connection specific options.
NOTE:
Option names are case-insensitive
The MongoDB C Driver exposes constants for each supported connection option. These constants make it
easier to discover connection options, but their string values can be used as well.
For example, the following calls are equal.
uri = mongoc_uri_new ("mongodb://localhost/?" MONGOC_URI_APPNAME "=applicationName");
uri = mongoc_uri_new ("mongodb://localhost/?appname=applicationName");
uri = mongoc_uri_new ("mongodb://localhost/?appName=applicationName");
REPLICA SET EXAMPLE
To describe a connection to a replica set named 'test' with the following mongod hosts:
• db1.example.com on port 27017
• db2.example.com on port 2500
You would use a connection string that resembles the following.
mongodb://db1.example.com,db2.example.com:2500/?replicaSet=test
SRV EXAMPLE
If you have configured an SRV record with a name like "_mongodb._tcp.server.example.com" whose records
are a list of one or more MongoDB server hostnames, use a connection string like this:
uri = mongoc_uri_new ("mongodb+srv://server.example.com/?replicaSet=rs&appName=applicationName");
The driver prefixes the service name with "_mongodb._tcp.", then performs a DNS SRV query to resolve the
service name to one or more hostnames. If this query succeeds, the driver performs a DNS TXT query on the
service name (without the "_mongodb._tcp" prefix) for additional URI options configured as TXT records.
On Unix, the MongoDB C Driver relies on libresolv to look up SRV and TXT records. If libresolv is
unavailable, then using a "mongodb+srv" URI will cause an error. If your libresolv lacks res_nsearch then
the driver will fall back to res_search, which is not thread-safe.
CONNECTION OPTIONS
┌────────────────────────────────┬──────────────────────┬───────────────────────────────────┐
│Constant │ Key │ Description │
├────────────────────────────────┼──────────────────────┼───────────────────────────────────┤
│MONGOC_URI_RETRYWRITES │ retrywrites │ If "true" and the server is │
│ │ │ a MongoDB 3.6+ replica set │
│ │ │ or sharded cluster, the │
│ │ │ driver safely retries a │
│ │ │ write that failed due to a │
│ │ │ network error or replica set │
│ │ │ failover. Only inserts, │
│ │ │ updates of single documents, │
│ │ │ or deletes of single │
│ │ │ documents are retried. │
├────────────────────────────────┼──────────────────────┼───────────────────────────────────┤
│MONGOC_URI_APPNAME │ appname │ The client application name. │
│ │ │ This value is used by │
│ │ │ MongoDB when it logs │
│ │ │ connection information and │
│ │ │ profile information, such as │
│ │ │ slow queries. │
├────────────────────────────────┼──────────────────────┼───────────────────────────────────┤
│MONGOC_URI_SSL │ ssl │ {true|false}, indicating if │
│ │ │ SSL must be used. (See also │
│ │ │ mongoc_client_set_ssl_opts │
│ │ │ and │
│ │ │ mongoc_client_pool_set_ssl_opts.) │
├────────────────────────────────┼──────────────────────┼───────────────────────────────────┤
│MONGOC_URI_COMPRESSORS │ compressors │ Comma separated list of │
│ │ │ compressors, if any, to use to │
│ │ │ compress the wire protocol │
│ │ │ messages. Snappy are Zlib are │
│ │ │ optional build time dependencies, │
│ │ │ and enable the "snappy" and │
│ │ │ "zlib" values respectively. │
│ │ │ Defaults to empty (no │
│ │ │ compressors). │
├────────────────────────────────┼──────────────────────┼───────────────────────────────────┤
│MONGOC_URI_CONNECTTIMEOUTMS │ connecttimeoutms │ This setting applies to new │
│ │ │ server connections. It is also │
│ │ │ used as the socket timeout for │
│ │ │ server discovery and monitoring │
│ │ │ operations. The default is 10,000 │
│ │ │ ms (10 seconds). │
└────────────────────────────────┴──────────────────────┴───────────────────────────────────┘
│MONGOC_URI_SOCKETTIMEOUTMS │ sockettimeoutms │ The time in milliseconds to │
│ │ │ attempt to send or receive on a │
│ │ │ socket before the attempt times │
│ │ │ out. The default is 300,000 (5 │
│ │ │ minutes). │
├────────────────────────────────┼──────────────────────┼───────────────────────────────────┤
│MONGOC_URI_REPLICASET │ replicaset │ The name of the Replica Set that │
│ │ │ the driver should connect to. │
├────────────────────────────────┼──────────────────────┼───────────────────────────────────┤
│MONGOC_URI_ZLIBCOMPRESSIONLEVEL │ zlibcompressionlevel │ When the MONGOC_URI_COMPRESSORS │
│ │ │ includes "zlib" this options │
│ │ │ configures the zlib compression │
│ │ │ level, when the zlib compressor │
│ │ │ is used to compress client data. │
└────────────────────────────────┴──────────────────────┴───────────────────────────────────┘
Setting any of the *timeoutMS options above to 0 will be interpreted as "use the default value".
AUTHENTICATION OPTIONS
┌───────────────────────────────────┬─────────────────────────┬──────────────────────────────┐
│Constant │ Key │ Description │
├───────────────────────────────────┼─────────────────────────┼──────────────────────────────┤
│MONGOC_URI_AUTHMECHANISM │ authmechanism │ Specifies the mechanism to │
│ │ │ use when authenticating as │
│ │ │ the provided user. See │
│ │ │ Authentication for supported │
│ │ │ values. │
├───────────────────────────────────┼─────────────────────────┼──────────────────────────────┤
│MONGOC_URI_AUTHMECHANISMPROPERTIES │ authmechanismproperties │ Certain authentication │
│ │ │ mechanisms have additional │
│ │ │ options that can be │
│ │ │ configured. These options │
│ │ │ should be provided as comma │
│ │ │ separated │
│ │ │ option_key:option_value pair │
│ │ │ and provided as │
│ │ │ authMechanismProperties. │
├───────────────────────────────────┼─────────────────────────┼──────────────────────────────┤
│MONGOC_URI_AUTHSOURCE │ authsource │ The authSource defines the │
│ │ │ database that should be used │
│ │ │ to authenticate to. It is │
│ │ │ unnecessary to provide this │
│ │ │ option the database name is │
│ │ │ the same as the database │
│ │ │ used in the URI. │
└───────────────────────────────────┴─────────────────────────┴──────────────────────────────┘
Mechanism Properties
┌────────────────────────────────┬──────────────────────┬──────────────────────────────┐
│Constant │ Key │ Description │
├────────────────────────────────┼──────────────────────┼──────────────────────────────┤
│MONGOC_URI_CANONICALIZEHOSTNAME │ canonicalizehostname │ Use the canonical hostname │
│ │ │ of the service, rather than │
│ │ │ its configured alias, when │
│ │ │ authenticating with │
│ │ │ Cyrus-SASL Kerberos. │
├────────────────────────────────┼──────────────────────┼──────────────────────────────┤
│MONGOC_URI_GSSAPISERVICENAME │ gssapiservicename │ Use alternative service │
│ │ │ name. The default is │
│ │ │ mongodb. │
└────────────────────────────────┴──────────────────────┴──────────────────────────────┘
SSL OPTIONS
──────────────────────────────────────────────────────────────────────────────────────────────────────────────
Constant Key Description
──────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_SSLCLIENTCERTIFICATEKEYFILE sslclientcertificatekeyfile Path to PEM formatted
Private Key, with its Public
Certificate concatenated at
the end.
──────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_SSLCLIENTCERTIFICATEKEYPASSWORD sslclientcertificatekeypassword The password, if any, to use
to unlock encrypted Private
Key.
──────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_SSLCERTIFICATEAUTHORITYFILE sslcertificateauthorityfile One, or a bundle of,
Certificate Authorities whom
should be considered to be
trusted.
──────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_SSLALLOWINVALIDCERTIFICATES sslallowinvalidcertificates Accept and ignore
certificate verification
errors (e.g. untrusted
issuer, expired, etc etc)
──────────────────────────────────────────────────────────────────────────────────────────────────────────────
MONGOC_URI_SSLALLOWINVALIDHOSTNAMES sslallowinvalidhostnames Ignore hostname verification
of the certificate (e.g. Man
In The Middle, using valid
certificate, but issued for
another hostname)
┌───────────────────────────────────────────┬─────────────────────────────────┬──────────────────────────────┐
│ │ │ │
--
CONNECTION POOL OPTIONS
These options govern the behavior of a mongoc_client_pool_t. They are ignored by a non-pooled
mongoc_client_t.
┌──────────────────────────────┬────────────────────┬──────────────────────────────┐
│Constant │ Key │ Description │
└──────────────────────────────┴────────────────────┴──────────────────────────────┘
│MONGOC_URI_MAXPOOLSIZE │ maxpoolsize │ The maximum number of │
│ │ │ clients created by a │
│ │ │ mongoc_client_pool_t total │
│ │ │ (both in the pool and │
│ │ │ checked out). The default │
│ │ │ value is 100. Once it is │
│ │ │ reached, │
│ │ │ mongoc_client_pool_pop │
│ │ │ blocks until another thread │
│ │ │ pushes a client. │
├──────────────────────────────┼────────────────────┼──────────────────────────────┤
│MONGOC_URI_MINPOOLSIZE │ minpoolsize │ Deprecated. This option's │
│ │ │ behavior does not match its │
│ │ │ name, and its actual │
│ │ │ behavior will likely hurt │
│ │ │ performance. │
├──────────────────────────────┼────────────────────┼──────────────────────────────┤
│MONGOC_URI_MAXIDLETIMEMS │ maxidletimems │ Not implemented. │
├──────────────────────────────┼────────────────────┼──────────────────────────────┤
│MONGOC_URI_WAITQUEUEMULTIPLE │ waitqueuemultiple │ Not implemented. │
├──────────────────────────────┼────────────────────┼──────────────────────────────┤
│MONGOC_URI_WAITQUEUETIMEOUTMS │ waitqueuetimeoutms │ Not implemented. │
└──────────────────────────────┴────────────────────┴──────────────────────────────┘
WRITE CONCERN OPTIONS
┌──────────────────────┬────────────┬──────────────────────────────┐
│Constant │ Key │ Description │
└──────────────────────┴────────────┴──────────────────────────────┘
MONGOC_URI_W w Determines the write concern
(guarantee). Valid values:
• 0 = The driver will
not acknowledge
write operations
but will pass or
handle any network
and socket errors
that it receives to
the client. If you
disable write
concern but enable
the getLastError
command’s w option,
w overrides the w
option.
• 1 = Provides basic
acknowledgment of
write operations.
By specifying 1,
you require that a
standalone mongod
instance, or the
primary for replica
sets, acknowledge
all write
operations. For
drivers released
after the default
write concern
change, this is the
default write
concern setting.
• majority = For
replica sets, if
you specify the
special majority
value to w option,
write operations
will only return
successfully after
a majority of the
configured replica
set members have
acknowledged the
write operation.
• n = For replica
sets, if you
specify a number n
greater than 1,
operations with
this write concern
return only after n
members of the set
have acknowledged
the write. If you
set n to a number
that is greater
than the number of
available set
members or members
that hold data,
MongoDB will wait,
potentially
indefinitely, for
these members to
become available.
• tags = For replica
sets, you can
specify a tag set
to require that all
members of the set
that have these
tags configured
return confirmation
of the write
operation.
├──────────────────────┼────────────┼──────────────────────────────┤
│MONGOC_URI_WTIMEOUTMS │ wtimeoutms │ The time in milliseconds to │
│ │ │ wait for replication to │
│ │ │ succeed, as specified in the │
│ │ │ w option, before timing out. │
│ │ │ When wtimeoutMS is 0, write │
│ │ │ operations will never time │
│ │ │ out. │
├──────────────────────┼────────────┼──────────────────────────────┤
│MONGOC_URI_JOURNAL │ journal │ Controls whether write │
│ │ │ operations will wait until │
│ │ │ the mongod acknowledges the │
│ │ │ write operations and commits │
│ │ │ the data to the on disk │
│ │ │ journal. │
│ │ │ │
│ │ │ • true = Enables │
│ │ │ journal commit │
│ │ │ acknowledgment │
│ │ │ write concern. │
│ │ │ Equivalent to │
│ │ │ specifying the │
│ │ │ getLastError │
│ │ │ command with the j │
│ │ │ option enabled. │
│ │ │ │
│ │ │ • false = Does not │
│ │ │ require that mongod │
│ │ │ commit write │
│ │ │ operations to the │
│ │ │ journal before │
│ │ │ acknowledging the │
│ │ │ write operation. │
│ │ │ This is the default │
│ │ │ option for the │
│ │ │ journal parameter. │
└──────────────────────┴────────────┴──────────────────────────────┘
READ CONCERN OPTIONS
┌────────────────────────────┬──────────────────┬──────────────────────────────┐
│Constant │ Key │ Description │
├────────────────────────────┼──────────────────┼──────────────────────────────┤
│MONGOC_URI_READCONCERNLEVEL │ readconcernlevel │ The level of isolation for │
│ │ │ read operations. If the │
│ │ │ level is left unspecified, │
│ │ │ the server default will be │
│ │ │ used. See readConcern in the │
│ │ │ MongoDB Manual for details. │
└────────────────────────────┴──────────────────┴──────────────────────────────┘
READ PREFERENCE OPTIONS
When connected to a replica set, the driver chooses which member to query using the read preference:
1. Choose members whose type matches "readPreference".
2. From these, if there are any tags sets configured, choose members matching the first tag set. If there
are none, fall back to the next tag set and so on, until some members are chosen or the tag sets are
exhausted.
3. From the chosen servers, distribute queries randomly among the server with the fastest round-trip
times. These include the server with the fastest time and any whose round-trip time is no more than
"localThresholdMS" slower.
┌───────────────────────────────┬─────────────────────┬──────────────────────────────┐
│Constant │ Key │ Description │
├───────────────────────────────┼─────────────────────┼──────────────────────────────┤
│MONGOC_URI_READPREFERENCE │ readpreference │ Specifies the replica set │
│ │ │ read preference for this │
│ │ │ connection. This setting │
│ │ │ overrides any slaveOk value. │
│ │ │ The read preference values │
│ │ │ are the following: │
│ │ │ │
│ │ │ • primary (default) │
│ │ │ │
│ │ │ • primaryPreferred │
│ │ │ │
│ │ │ • secondary │
│ │ │ │
│ │ │ • secondaryPreferred │
│ │ │ │
│ │ │ • nearest │
├───────────────────────────────┼─────────────────────┼──────────────────────────────┤
│MONGOC_URI_READPREFERENCETAGS │ readpreferencetags │ A representation of a tag │
│ │ │ set. See also │
│ │ │ mongoc-read-prefs-tag-sets. │
├───────────────────────────────┼─────────────────────┼──────────────────────────────┤
│MONGOC_URI_LOCALTHRESHOLDMS │ localthresholdms │ How far to distribute │
│ │ │ queries, beyond the server │
│ │ │ with the fastest round-trip │
│ │ │ time. By default, only │
│ │ │ servers within 15ms of the │
│ │ │ fastest round-trip time │
│ │ │ receive queries. │
├───────────────────────────────┼─────────────────────┼──────────────────────────────┤
│MONGOC_URI_MAXSTALENESSSECONDS │ maxstalenessseconds │ The maximum replication lag, │
│ │ │ in wall clock time, that a │
│ │ │ secondary can suffer and │
│ │ │ still be eligible. The │
│ │ │ smallest allowed value for │
│ │ │ maxStalenessSeconds is 90 │
│ │ │ seconds. │
└───────────────────────────────┴─────────────────────┴──────────────────────────────┘
NOTE:
When connecting to more than one mongos, libmongoc's localThresholdMS applies only to the selection of
mongos servers. The threshold for selecting among replica set members in shards is controlled by the
mongos's localThreshold command line option.
LEGACY OPTIONS
For historical reasons, the following options are available. They should however not be used.
┌───────────────────┬─────────┬───────────────────────────────────┐
│Constant │ Key │ Description │
├───────────────────┼─────────┼───────────────────────────────────┤
│MONGOC_URI_SAFE │ safe │ {true|false} Same as w={1|0} │
├───────────────────┼─────────┼───────────────────────────────────┤
│MONGOC_URI_SLAVEOK │ slaveok │ When set, same as │
│ │ │ readPreference=secondaryPreferred │
└───────────────────┴─────────┴───────────────────────────────────┘
AUTHOR
MongoDB, Inc
COPYRIGHT
2018, MongoDB, Inc