Provided by: libmongoc-doc_1.3.1-1_all 
NAME
mongoc_uri_t - 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.
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:// <1>
[username:password@] <2>
host1 <3>
[:port1] <4>
[,host2[:port2],...[,hostN[:portN]]] <5>
[/[database] <6>
[?options]] <7>
\[bu]
mongodb is the specifier of the MongoDB protocol.
\[bu]
An optional username and password.
\[bu]
The only required part of the uri. This specifies either a hostname, IP address or UNIX
domain socket.
\[bu]
An optional port number. Defaults to :27017.
\[bu]
Extra optional hosts and ports. You would specify multiple hosts, for example, for
connections to replica sets.
\[bu]
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.
\[bu]
Connection specific options.
REPLICA SET EXAMPLE
To describe a connection to a replica set named 'test' with the following mongod hosts:
\[bu]
db1.example.com on port 27017
\[bu]
db2.example.com on port 2500
You would use the connection string that resembles the following.
mongodb://db1.example.com,db2.example.com:2500/?replicaSet=test
CONNECTION OPTIONS
ssl {true|false}, indicating if SSL must be used. (See also mongoc_client_set_ssl_opts
and mongoc_client_pool_set_ssl_opts \&.)
connectTimeoutMS
A timeout in milliseconds to attempt a connection before timing out. This setting
applies to server discovery and monitoring connections as well as to connections
for application operations. The default is 10 seconds.
socketTimeoutMS
The time in milliseconds to attempt to send or receive on a socket before the
attempt times out. The default is 5 minutes.
NOTE
Setting any of the *TimeoutMS options above to 0 will be interpreted as "use the
default value"
SERVER DISCOVERY, MONITORING, AND SELECTION OPTIONS
NOTE
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".
heartbeatFrequencyMS
The interval between server monitoring checks. Defaults to 10 seconds in pooled
(multi‐threaded) mode, 60 seconds in non‐pooled mode (single‐threaded).
serverSelectionTimeoutMS
A timeout in milliseconds to block for server selection before throwing an
exception. The default is 30 seconds.
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.
socketCheckIntervalMS
Only applies to single threaded clients. If a socket has not been used within this
time, its connection is checked with a quick "isMaster" call before it is used
again. Defaults to 5 seconds.
NOTE
Setting any of the *TimeoutMS options above to 0 will be interpreted as "use the
default value"
CONNECTION POOL OPTIONS
maxPoolSize
The maximum number of connections in the pool. The default value is 100.
minPoolSize
The minimum number of connections in the connection pool. Default value is 0. These
are lazily created.
maxIdleTimeMS
Not implemented.
waitQueueMultiple
Not implemented.
waitQueueTimeoutMS
Not implemented.
WRITE CONCERN OPTIONS
w
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.
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.
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
readConcernLevel
The level of isolation for read operations. If the level is left unspecified, the
server default will be used. See the readConcern in the MongoDB Manual for details.
READ PREFERENCE OPTIONS
readPreference
Specifies the replica set read preference for this connection. This setting
overrides any slaveOk value. The read preference values are the following:
\[bu]
primary
\[bu]
primaryPreferred
\[bu]
secondary
\[bu]
secondaryPreferred
\[bu]
nearest
readPreferenceTags
Specifies a tag set as a comma‐seperated list of colon‐separted key‐value pairs.
COLOPHON
This page is part of MongoDB C Driver. Please report any bugs at
https://jira.mongodb.org/browse/CDRIVER.