• 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 MongoDB Drivers and Client Libraries.

The following is the standard URI connection scheme:

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]

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 mongod instance as listed in the replica set configuration. For a sharded cluster, specify the hostname of the mongos instance.
: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 mongod instance as listed in the replica set configuration. For a sharded cluster, specify the hostname of the mongos instance.
: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. /) between the last hostN and the question mark that begins the string of options.

Example

To describe a connection to a replica set named test, with the following mongod hosts:

• db1.example.net on port 27017 and
• db2.example.net on port 2500.

You would use a connection string that resembles the following:

mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test

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 port 27017 and
• r2.example.net on port 27017.

You would use a connection string that resembles the following:

mongodb://r1.example.net:27017,r2.example.net:27017/

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:

mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000

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
replicaSet	Specifies the name of the replica set, if the mongod is a member of a replica set. When connecting to a replica set it is important to give a seed list of at least two mongod instances. If you only provide the connection point of a single mongod instance, and omit the replicaSet, the client will create a standalone connection.

Connection Options

Connection Option	Description
ssl	true: Initiate the connection with TLS/SSL. false: Initiate the connection without TLS/SSL. The default value is false. Note The ssl option is not supported by all drivers. See your driver documentation and the Configure mongod and mongos for TLS/SSL document.
connectTimeoutMS	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.
socketTimeoutMS	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
maxPoolSize	The maximum number of connections in the connection pool. The default value is 100.
minPoolSize	The minimum number of connections in the connection pool. The default value is 0. Note The minPoolSize option is not supported by all drivers. For information on your driver, see the drivers documentation.
maxIdleTimeMS	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.
waitQueueMultiple	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 MongoDB Drivers and Client Libraries documentation.
waitQueueTimeoutMS	The maximum time in milliseconds that a thread can wait for a connection to become available. For default values, see the MongoDB Drivers and Client Libraries 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
w	Corresponds to the write concern w Option. The w option requests acknowledgement that the write operation has propagated to a specified number of mongod instances or to mongod instances with specified tags. You can specify a number, the string majority, or a tag set. For details, see w Option.
wtimeoutMS	Corresponds to the write concern wtimeout. wtimeoutMS specifies a time limit, in milliseconds, for the write concern. When wtimeoutMS is 0, write operations will never time out. For more information, see wtimeout.
journal	Corresponds to the write concern j Option option. The journal option requests acknowledgement from MongoDB that the write operation has been written to the journal. For details, see j Option. If you set journal to true, and specify a w value less than 1, journal prevails. Changed in version 2.6: If you set journal to true, and the mongod does not have journaling enabled, as with storage.journal.enabled, then MongoDB will error. In previous versions, MongoDB would provide basic receipt acknowledgement (i.e. w:1), ignore journal, and include a jnote field in its return document.

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
readConcernLevel	The level of isolation. Accepts either "local" or "majority". 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
readPreference	Specifies the replica set read preference for this connection. The read preference values are the following: primary primaryPreferred secondary secondaryPreferred nearest For descriptions of each value, see Read Preference Modes. The default value is primary, which sends all read operations to the replica set’s primary.
maxStalenessSeconds	New in version 3.4. Specifies, in seconds, how stale a secondary can be before the client stops using it for read operations. For details, see: maxStalenessSeconds. By default, there is no maximum staleness and clients will not consider a secondary’s lag when choosing where to direct a read operation. The minimum maxStalenessSeconds value is 90 seconds. Specifying a value between 0 and 90 seconds will produce an error. MongoDB drivers treat a maxStalenessSeconds value of -1 as “no max staleness”, the same as if maxStalenessSeconds is omitted. Important To use maxStalenessSeconds, all of the MongoDB instances in your deployment must be using MongoDB 3.4 or later. If any instances are on an earlier version of MongoDB, the driver or mongos will raise an error. The following specifies a maxStalenessSeconds value of 120 seconds with the secondary read preference mode: mongodb://host.example.com/?readPreference=secondary&maxStalenessSeconds=120
readPreferenceTags	Specifies a tag set as a comma-separated list of colon-separated key-value pairs. For example: dc:ny,rack:1 To specify a list of tag sets, use multiple readPreferenceTags. The following specifies two tag sets and an empty tag set: readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags= Order matters when using multiple readPreferenceTags.

Authentication Options

Connection Option	Description
authSource	Specify the database name associated with the user’s credentials. authSource defaults to the database specified in the connection string. For authentication mechanisms that delegate credential storage to other services, the authSource value should be $external as with the PLAIN (LDAP) and GSSAPI (Kerberos) authentication mechanisms. MongoDB will ignore authSource values if the connection string specifies no username.
authMechanism	Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms. Changed in version 3.0: Added support for the SCRAM-SHA-1 authentication mechanism. Specify the authentication mechanism that MongoDB will use to authenticate the connection. Possible values include: SCRAM-SHA-1 MONGODB-CR MONGODB-X509 GSSAPI (Kerberos) PLAIN (LDAP SASL) Only MongoDB Enterprise mongod and mongos instances provide GSSAPI (Kerberos) and PLAIN (LDAP) mechanisms. To use MONGODB-X509, you must have TLS/SSL Enabled. 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.
gssapiServiceName	Set the Kerberos service name when connecting to Kerberized MongoDB instances. This value must match the service name set on MongoDB instances. gssapiServiceName defaults to mongodb for all clients and for MongoDB instance. If you change saslServiceName setting on a MongoDB instance, you will need to set gssapiServiceName to the same value.

Server Selection and Discovery Options

MongoDB provides the following options to configure how MongoDB drivers and mongos instances select a server to which to direct read or write operations.

Connection Option	Description
localThresholdMS	The size (in milliseconds) of the latency window for selecting among multiple suitable MongoDB instances. Default: 15 milliseconds. All drivers use localThresholdMS. Use the localThreshold alias when specifying the latency window size to mongos.
serverSelectionTimeoutMS	Specifies how long (in milliseconds) to block for server selection before throwing an exception. Default: 30,000 milliseconds.
serverSelectionTryOnce	Single-threaded drivers only. When true, instructs the driver to scan the MongoDB deployment exactly once after server selection fails and then either select a server or raise an error. When false, the driver blocks and searches for a server up to the serverSelectionTimeoutMS value. Default: true. Multi-threaded drivers and mongos do not support serverSelectionTryOnce.
heartbeatFrequencyMS	heartbeatFrequencyMS controls when the driver checks the state of the MongoDB deployment. Specify the interval (in milliseconds) between checks, counted from the end of the previous check until the beginning of the next one. Default: Single-threaded drivers: 60 seconds. Multi-threaded drivers: 10 seconds. mongos does not support changing the frequency of the heartbeat checks.

Miscellaneous Configuration

Connection Option

Description

uuidRepresentation

Possible values are: standard The standard binary representation. csharpLegacy The default representation for the C# driver. javaLegacy The default representation for the Java driver. pythonLegacy The default representation for the Python driver. For the default, see the drivers documentation for your driver. Note Not all drivers support the uuidRepresentation option. For information on your driver, see the drivers documentation.

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:

mongodb://localhost

admin Database

The following connects and logs in to the admin database as user sysop with the password moon:

mongodb://sysop:moon@localhost

records Database

The following connects and logs in to the records database as user sysop with the password moon:

mongodb://sysop:moon@localhost/records

UNIX Domain Socket

Use a URL encoded connection string when connecting to a UNIX domain socket.

The following connects to a UNIX domain socket with file path /tmp/mongodb-27017.sock:

mongodb://%2Ftmp%2Fmongodb-27017.sock

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.

mongodb://db1.example.net,db2.example.com/?replicaSet=test

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.

mongodb://localhost,localhost:27018,localhost:27019/?replicaSet=test

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.

mongodb://example1.com,example2.com,example3.com/?replicaSet=test&readPreference=secondary

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.

mongodb://example1.com,example2.com,example3.com/?replicaSet=test&w=2&wtimeoutMS=2000

Sharded Cluster

The following connects to a sharded cluster with three mongos instances:

mongodb://router1.example.com:27017,router2.example2.com:27017,router3.example3.com:27017/

←   System Collections Collation  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.