Docs4dev
Docs
mongodb / v3.6 / reference / reference-connection-string.html

Connection String URI Format

On this page

This document describes the URI format for defining connections between applications using MongoDB drivers and MongoDB instances.

Connection String Formats

You can specify the MongoDB connection string using either:

Standard Connection String Format

This section describes the standard format of the MongoDB connection URI used to connect to a MongoDB deployment: standalone, replica set, or a sharded cluster.

The standard URI connection scheme has the form:

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

Examples

  • Standalone
  • Replica Set
  • Sharded Cluster

  • For a standalone:

    mongodb://mongodb0.example.com:27017/admin

  • For a standalone that enforces access control:

    mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017/admin

    If the username or password includes the at sign @, colon :, slash /, or the percent sign % character, use percent encoding .

Note

For a replica set, specify the hostname of the mongod instance as listed in the replica set configuration.

For a replica set, include the replicaSet option.

  • For a replica set:

    mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/admin?replicaSet=myRepl

  • For a replica set that enforces access control, include user credentials:

    mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/admin?replicaSet=myRepl

    If the username or password includes the at sign @, colon :, slash /, or the percent sign % character, use percent encoding .

Note

For a connection string to a sharded cluster, specify mongos hosts in the connection string.

  • For a sharded cluster:

    mongodb://mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017/admin

  • For a sharded cluster that enforces access control, include user credentials:

    mongodb://myDBReader:D1fficultP%40ssw0rd@mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017/admin

    If the username or password includes the at sign @, colon :, slash /, or the percent sign % character, use percent encoding .

For more examples, see Examples.

Components

The standard URI connection string includes the following components:

mongodb:// A required prefix to identify that this is a string in the standard connection format.
username:password@

Optional. Authentication credentials. If specified, the client will attempt to log in to the specific database using these credentials after connecting.

If the username or password includes the at sign @, colon :, slash /, or the percent sign % character, use percent encoding .

See also authSource.
host[:port]

The host (and optional port number) where the mongod instance (or mongos instance for a sharded cluster) is running. You can specify a hostname, IP address, or UNIX domain socket. Specify as many hosts as appropriate for your deployment topology:

  • For a standalone, specify the hostname of the standalone mongod instance.
  • 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(s) of the mongos instance(s).

If the port number is not specified, the default port 27017 is used.
/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. See also authSource.
?options

Optional. A query string that specifies connection specific options as <name>=<value> pairs. 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 (/) between the last host and the question mark (?) that begins the string of options.

DNS Seedlist Connection Format

New in version 3.6.

In addition to the standard connection format, MongoDB supports a DNS-constructed seedlist. Using DNS to construct the available servers list allows more flexibility of deployment and the ability to change the servers in rotation without reconfiguring clients.

In order to leverage the DNS seedlist, use a connection string prefix of mongodb+srv: in place of the mongodb: string above.

The +srv indicates to the mongo client that the hostname that follows corresponds to a DNS SRV record. The client driver will then query the DNS for the record to determine the hosts that are running the mongod instances.

For example, to connect to a DNS-listed hostname:

mongodb+srv://server.example.com/

A typical DNS configuration for the connection string above might look something like this:

Record                            TTL   Class    Priority Weight Port  Target
_mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27317 mongodb1.example.com.
_mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27017 mongodb2.example.com.

Note

The hostnames returned in SRV records must share the same parent domain (in this example, example.com) as the given hostname.

The DNS seedlist connection string can also provide options as a query string, with a trailing “/?” as in the standard connection string above. However, the +srv appended to the standard connection string signals the driver to query the DNS for options as a configured TXT record.

Only two options are available for configuration via a TXT record – replicaSet and authSource, and only one TXT record is allowed per server. If multiple TXT records appear in the DNS and/or if the TXT record contains an option other than replicaSet or authSource, an error will be thrown by the driver.

An example of a properly configured TXT record:

Record              TTL   Class    Text
server.example.com. 86400 IN TXT   "replicaSet=mySet&authSource=authDB"

In this case, taking into account both the DNS SRV records and the options retrieved from the TXT records, the parsed string will look like:

mongodb://mongodb1.example.com:27317,mongodb2.example.com:27017/?replicaSet=mySet&authSource=authDB

Options set in a TXT record can be overridden by passing in a query string with the URI. In the example below, the query string has provided an override for the authSource option configured in the TXT record of the DNS entry above.

mongodb+srv://server.example.com/?connectTimeoutMS=300000&authSource=aDifferentAuthDB

The rest of the option string will remain, and we can expect that the resulting URI would look like this (after parse).

mongodb://mongodb1.example.com:27317,mongodb2.example.com:27017/?connectTimeoutMS=300000&replicaSet=mySet&authSource=aDifferentAuthDB

Note

The mongodb+srv option will fail if there is no available DNS with records that correspond to the hostname identified in the connection string. In addition, use of the +srv connection string modifier sets the ssl option to true automatically for the connection. This can be overridden by explicitly setting the ssl option to false with ssl=false in the query string.

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

The following connection string to a replica set named myRepl with members running on the specified hosts:

mongodb://db0.example.com:27017,db1.example.com:27017,db2.example.com:27017/admin?replicaSet=myRepl
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, provide a seed list of the replica set member(s) to the host[:port] component of the uri. For specific details, refer to your driver documentation.

Connection Options

The following connection string to a replica set includes ssl=true option:

mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&ssl=true
Connection Option Description
ssl

A boolean to enable or disables TLS/SSL for the connection:
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.
compressors

Comma-delimited string of compressors to enable network compression for communication between this client and a mongod/mongos instance.

You can specify the following compressors:

  • snappy
  • zlib (Available in MongoDB 3.6 or greater)

If you specify multiple compressors, then the order in which you list the compressors matter as well as the communication initiator. For example, if the client specifies the following network compressors "zlib,snappy" and the mongod specifies "snappy,zlib", messages between the client and the mongod uses zlib.

Important

Messages are