Provided by: libmongoc-doc_1.22.1-1_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, IPv4 address,
IPv6 address enclosed in "[" and "]", 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. Do not repeat the same option (e.g.
"mongodb://localhost/db?opt=value1&OPT=value2") since this may have unexpected results.
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.
IPV4 AND IPV6
If connecting to a hostname that has both IPv4 and IPv6 DNS records, the behavior follows
RFC-6555. A connection to the IPv6 address is attempted first. If IPv6 fails, then a
connection is attempted to the IPv4 address. If the connection attempt to IPv6 does not
complete within 250ms, then IPv4 is tried in parallel. Whichever succeeds connection first
cancels the other. The successful DNS result is cached for 10 minutes.
As a consequence, attempts to connect to a mongod only listening on IPv4 may be delayed if
there are both A (IPv4) and AAAA (IPv6) DNS records associated with the host.
To avoid a delay, configure hostnames to match the MongoDB configuration. That is, only
create an A record if the mongod is only listening on IPv4.
CONNECTION OPTIONS
┌────────────────────────────────┬──────────────────────┬─────────────────────┬─────────────────────────────────────┐
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
└────────────────────────────────┴──────────────────────┴─────────────────────┴─────────────────────────────────────┘
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
│ │ │ │ mongoc_client_set_ssl_opts() │
│ │ │ │ mongoc_client_pool_set_ssl_opts().) │
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
├────────────────────────────────┼──────────────────────┼─────────────────────┼─────────────────────────────────────┤
└────────────────────────────────┴──────────────────────┴─────────────────────┴─────────────────────────────────────┘
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. │
│ │ │ Specifying the same │
│ │ │ option_key multiple │
│ │ │ times has undefined │
│ │ │ behavior. │
├───────────────────────────────────┼─────────────────────────┼──────────────────────────┤
│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. │
└────────────────────────────────┴──────────────────────┴──────────────────────────┘
TLS OPTIONS
┌────────────────────────────────────────────────┬──────────────────────────────────────┬────────────────────────────────────────┐
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
└────────────────────────────────────────────────┴──────────────────────────────────────┴────────────────────────────────────────┘
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
├────────────────────────────────────────────────┼──────────────────────────────────────┼────────────────────────────────────────┤
└────────────────────────────────────────────────┴──────────────────────────────────────┴────────────────────────────────────────┘
See Configuring TLS for details about these options and about building libmongoc with TLS
support.
DEPRECATED SSL OPTIONS
The following options have been deprecated and may be removed from future releases of
libmongoc.
┌───────────────────────────────────────────┬─────────────────────────────────┬──────────────────────────────────────────┬─────────────────────────────┐
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
├───────────────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
└───────────────────────────────────────────┴─────────────────────────────────┴──────────────────────────────────────────┴─────────────────────────────┘
SERVER DISCOVERY, MONITORING, AND SELECTION OPTIONS
Clients in a mongoc_client_pool_t share a topology scanner that runs on a background
thread. The thread wakes every heartbeatFrequencyMS (default 10 seconds) to scan all
MongoDB servers in parallel. Whenever an application operation requires a server that is
not known--for example, if there is no known primary and your application attempts an
insert--the thread rescans all servers every half-second. In this situation the pooled
client waits up to serverSelectionTimeoutMS (default 30 seconds) for the thread to find a
server suitable for the operation, then returns an error with domain
MONGOC_ERROR_SERVER_SELECTION.
Technically, the total time an operation may wait while a pooled client scans the topology
is controlled both by serverSelectionTimeoutMS and connectTimeoutMS. The longest wait
occurs if the last scan begins just at the end of the selection timeout, and a slow or
down server requires the full connection timeout before the client gives up.
A non-pooled client is single-threaded. Every heartbeatFrequencyMS, it blocks the next
application operation while it does a parallel scan. This scan takes as long as needed to
check the slowest server: roughly connectTimeoutMS. Therefore the default
heartbeatFrequencyMS for single-threaded clients is greater than for pooled clients: 60
seconds.
By default, single-threaded (non-pooled) clients scan only once when an operation requires
a server that is not known. If you attempt an insert and there is no known primary, the
client checks all servers once trying to find it, then succeeds or returns an error with
domain MONGOC_ERROR_SERVER_SELECTION. But if you set serverSelectionTryOnce to "false",
the single-threaded client loops, checking all servers every half-second, until
serverSelectionTimeoutMS.
The total time an operation may wait for a single-threaded client to scan the topology is
determined by connectTimeoutMS in the try-once case, or serverSelectionTimeoutMS and
connectTimeoutMS if serverSelectionTryOnce is set "false".
┌────────────────────────────────────┬──────────────────────────┬──────────────────────────┐
│Constant │ Key │ Description │
├────────────────────────────────────┼──────────────────────────┼──────────────────────────┤
│MONGOC_URI_HEARTBEATFREQUENCYMS │ heartbeatfrequencyms │ The interval between │
│ │ │ server monitoring │
│ │ │ checks. Defaults to │
│ │ │ 10,000ms (10 seconds) in │
│ │ │ pooled (multi-threaded) │
│ │ │ mode, 60,000ms (60 │
│ │ │ seconds) in non-pooled │
│ │ │ mode (single-threaded). │
├────────────────────────────────────┼──────────────────────────┼──────────────────────────┤
│MONGOC_URI_SERVERSELECTIONTIMEOUTMS │ serverselectiontimeoutms │ A timeout in │
│ │ │ milliseconds to block │
│ │ │ for server selection │
│ │ │ before throwing an │
│ │ │ exception. The default │
│ │ │ is 30,0000ms (30 │
│ │ │ seconds). │
└────────────────────────────────────┴──────────────────────────┴──────────────────────────┘
│MONGOC_URI_SERVERSELECTIONTRYONCE │ serverselectiontryonce │ If "true", the driver │
│ │ │ scans the topology │
│ │ │ exactly once after │
│ │ │ server selection fails, │
│ │ │ then either selects a │
│ │ │ server or returns an │
│ │ │ error. If it is false, │
│ │ │ then the driver │
│ │ │ repeatedly searches for │
│ │ │ a suitable server for up │
│ │ │ to │
│ │ │ serverSelectionTimeoutMS │
│ │ │ milliseconds (pausing a │
│ │ │ half second between │
│ │ │ attempts). The default │
│ │ │ for │
│ │ │ serverSelectionTryOnce │
│ │ │ is "false" for pooled │
│ │ │ clients, otherwise │
│ │ │ "true". Pooled clients │
│ │ │ ignore │
│ │ │ serverSelectionTryOnce; │
│ │ │ they signal the thread │
│ │ │ to rescan the topology │
│ │ │ every half-second until │
│ │ │ serverSelectionTimeoutMS │
│ │ │ expires. │
├────────────────────────────────────┼──────────────────────────┼──────────────────────────┤
│MONGOC_URI_SOCKETCHECKINTERVALMS │ socketcheckintervalms │ Only applies to single │
│ │ │ threaded clients. If a │
│ │ │ socket has not been used │
│ │ │ within this time, its │
│ │ │ connection is checked │
│ │ │ with a quick "hello" │
│ │ │ call before it is used │
│ │ │ again. Defaults to │
│ │ │ 5,000ms (5 seconds). │
├────────────────────────────────────┼──────────────────────────┼──────────────────────────┤
│MONGOC_URI_DIRECTCONNECTION │ directconnection │ If "true", the driver │
│ │ │ connects to a single │
│ │ │ server directly and will │
│ │ │ not monitor additional │
│ │ │ servers. If "false", │
│ │ │ the driver connects │
│ │ │ based on the presence │
│ │ │ and value of the │
│ │ │ replicaSet option. │
└────────────────────────────────────┴──────────────────────────┴──────────────────────────┘
Setting any of the *TimeoutMS options above to 0 will be interpreted as "use the default
value".
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 │ The maximum time to wait │
│ │ │ for a client to become │
│ │ │ available from the pool. │
└──────────────────────────────┴────────────────────┴──────────────────────────┘
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
acknowledgement
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 │
│ │ │ acknowledgement │
│ │ │ 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 │
│ │ │ secondaryOk 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 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} │
└────────────────┴──────┴──────────────────────────┘
AUTHOR
MongoDB, Inc
COPYRIGHT
2017-present, MongoDB, Inc