- Reference >
- Connection String URI Format
Connection String URI Format¶
This document describes the URI format for defining connections between applications and MongoDB instances in the official MongoDB drivers.
Standard Connection String Format¶
This section describes the standard format of the MongoDB connection URI used to connect to a MongoDB database server. The format is the same for all official MongoDB drivers. For a list of drivers and links to driver documentation, see /drivers.
The following is the standard URI connection scheme:
The components of this string are:
mongodb:// |
A required prefix to identify that this is a string in the standard connection format. |
username:password@ |
Optional. If specified, the client will attempt to log in to the
specific database using these credentials after connecting to
the mongod instance. |
host1 |
Required. It identifies a server address to connect to. It identifies either a hostname, IP address, or UNIX domain socket. For a replica set, specify the hostname of the For a sharded cluster, specify the hostname of the
|
:port1 |
Optional. The default value is :27017 if not specified. |
hostN |
Optional. You can specify as many hosts as necessary. You would specify multiple hosts, for example, for connections to replica sets. For a replica set, specify the hostname of the For a sharded cluster, specify the hostname of the
|
:portX |
Optional. The default value is :27017 if not specified. |
/database |
Optional. The name of the database to authenticate if the
connection string includes authentication credentials in the
form of username:password@ . If /database is not
specified and the connection string includes credentials, the
driver will authenticate to the admin database. |
?options |
Connection specific options. See Connection String Options for a full description of these options. If the connection string does not specify a database/ you must
specify a slash (i.e. |
Example
To describe a connection to a replica set named test
, with the
following mongod
hosts:
db1.example.net
on port27017
anddb2.example.net
on port2500
.
You would use a connection string that resembles the following:
For a replica set, specify the hostname of the mongod
instance as listed in the replica set configuration.
Example
To describe a connection to a sharded cluster with the
following mongos
hosts:
r1.example.net
on port27017
andr2.example.net
on port27017
.
You would use a connection string that resembles the following:
Connection String Options¶
This section lists all connection options used in the Standard Connection String Format.
Connection options are pairs in the following form: name=value
. The
value
is always case sensitive. Separate options with the ampersand
(i.e. &
) character. In the following example, a connection uses the
replicaSet
and connectTimeoutMS
options:
Semi-colon separator for connection string arguments
To provide backwards compatibility, drivers currently accept
semi-colons (i.e. ;
) as option separators.
Replica Set Option¶
Connection Option | Description |
---|---|
|
Specifies the name of the replica set, if the
When connecting to a replica set it is important to give a seed
list of at least two |
Connection Options¶
Connection Option | Description |
---|---|
|
The default value is Note The |
|
The time in milliseconds to attempt a connection before timing out. The default is never to timeout, though different drivers might vary. See the driver documentation. |
|
The time in milliseconds to attempt a send or receive on a socket before the attempt times out. The default is never to timeout, though different drivers might vary. See the driver documentation. |
Connection Pool Options¶
Most drivers implement some kind of connection pool handling. Some drivers do not support connection pools. See your driver documentation for more information on the connection pooling implementation. These options allow applications to configure the connection pool when connecting to the MongoDB deployment.
Connection Option | Description |
---|---|
|
The maximum number of connections in the connection pool. The
default value is 100 . |
|
The minimum number of connections in the connection pool. The
default value is Note The |
|
The maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed. This option is not supported by all drivers. |
|
A number that the driver multiples the maxPoolSize
value to, to provide the maximum number of threads allowed to
wait for a connection to become available from the pool. For
default values, see the /drivers
documentation. |
|
The maximum time in milliseconds that a thread can wait for a connection to become available. For default values, see the /drivers documentation. |
Write Concern Options¶
Write concern describes the kind of assurances
that the mongod
and the driver provide to the application
regarding the success and durability of the write operation. For a
full explanation of write concern and write operations in general, see
Write Concern.
Note
You can specify the write concern both in the connection string and
as a parameter to method calls like insert
or update
. If the
write concern is specified in both places, the method parameter
overrides the connection-string setting.
Connection Option | Description |
---|---|
|
Corresponds to the write concern w Option. The You can specify a For details, see w Option. |
|
Corresponds to the write concern wtimeout.
When |
|
Corresponds to the write concern j Option option. The
If you set Changed in version 2.6: If you set |
readConcern
Options¶
New in version 3.2: For the WiredTiger storage engine, MongoDB 3.2 introduces the readConcern option for replica sets and replica set shards.
Read Concern allows clients to choose a level of isolation for their reads from replica sets.
Connection Option | Description |
---|---|
|
The level of isolation. Accepts either For details, see Read Concern. |
Read Preference Options¶
Read preferences describe the behavior of read operations with regards to replica sets. These parameters allow you to specify read preferences on a per-connection basis in the connection string:
Connection Option | Description |
---|---|
|
Specifies the replica set read preference for this connection. The read preference values are the following: For descriptions of each value, see Read Preference Modes. The default value is |
|
Specifies a tag set as a comma-separated list of colon-separated key-value pairs. For example: To specify a list of tag sets, use multiple
The following specifies two tag sets and an empty tag set: Order matters when using multiple |
Authentication Options¶
Connection Option | Description |
---|---|
|
Specify the database name associated with the user’s
credentials, if the For authentication mechanisms that delegate credential storage
to other services, the MongoDB will ignore |
|
Changed in version 2.6: Added support for the Changed in version 3.0: Added support for the Specify the authentication mechanism that MongoDB will use to authenticate the connection. Possible values include:
Only MongoDB Enterprise See Authentication for more information about the authentication system in MongoDB. Also consider Use x.509 Certificates to Authenticate Clients for more information on x509 authentication. |
|
Set the Kerberos service name when connecting to Kerberized MongoDB instances. This value must match the service name set on MongoDB instances.
|
Miscellaneous Configuration¶
Connection Option | Description |
---|---|
|
Possible values are:
For the default, see the drivers documentation for your driver. Note Not all drivers support the |
Examples¶
The following provide example URI strings for common connection targets.
Database Server Running Locally¶
The following connects to a database server running locally on the default port:
admin
Database¶
The following connects and logs in to the admin
database as user
sysop
with the password moon
:
records
Database¶
The following connects and logs in to the records
database as user
sysop
with the password moon
:
UNIX Domain Socket¶
The following connects to a UNIX domain socket:
Note
Not all drivers support UNIX domain sockets. For information on your driver, see the drivers documentation.
Replica Set with Members on Different Machines¶
The following connects to a replica set with two members, one on
db1.example.net
and the other on db2.example.net
:
Note
For a replica set, specify the hostname of the mongod
instance as listed in the replica set configuration.
Replica Set with Members on localhost
¶
The following connects to a replica set with three members running on localhost
on
ports 27017
, 27018
, and 27019
:
Note
For a replica set, specify the hostname of the mongod
instance as listed in the replica set configuration.
Replica Set with Read Distribution¶
The following connects to a replica set with three members and distributes reads to the secondaries:
Note
For a replica set, specify the hostname of the mongod
instance as listed in the replica set configuration.
Replica Set with a High Level of Write Concern¶
The following connects to a replica set with write concern configured to wait for replication to succeed on at least two members, with a two-second timeout.
Note
For a replica set, specify the hostname of the mongod
instance as listed in the replica set configuration.