Join us at MongoDB.local London on 7 May to unlock new possibilities for your data. Use WEB50 to save 50%.
Register now >
Docs Menu
Docs Home
/
Development
/
Connection Strings
Docs Home
/
Development
/
Connection Strings
Docs Home
/
Development
/
Connection Strings

Connection String Formats

You can specify the MongoDB connection string by using one of the following formats:

MongoDB Atlas clusters use SRV connection format unless you connect to an online archive.

To connect directly to a host and port specified in a connection string, set the directConnection option to true. For full details about directConnection and the other connection string options, see Connection String Options.

SRV Connection Format

MongoDB supports a DNS-constructed seed list. 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.

The SRV URI connection scheme has the following form:

mongodb+srv://[username:password@]host[/[defaultauthdb][?options]]

Connection String Components

A connection string includes the following components:

Component
Description

mongodb:// or mongodb+srv://

A required prefix to identify that this is a string in the standard connection format (mongodb://) or SRV connection format (mongodb+srv://). To learn more about each format, see Standard Connection String Format and SRV Connection Format.

username:password@

Optional. Authentication credentials.

If specified, the client will attempt to authenticate the user to the authSource. If authSource is unspecified, the client will attempt to authenticate the user to the defaultauthdb. And if the defaultauthdb is unspecified, to the admin database.

If the username or password includes the following characters, those characters must be converted using 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(s) of the mongod instance(s) 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.

If you use the SRV URI connection format, you can specify only one host and no port. Otherwise, the driver or mongosh raises a parse error and does not perform DNS resolution.

/defaultauthdb

Optional. The authentication database to use if the connection string includes username:password@ authentication credentials but the authSource option is unspecified.

If both authSource and defaultauthdb are unspecified, the client will attempt to authenticate the specified user to the admin database. For more information, see authSource.

IMPORTANT: For Atlas deployments using the SRV Connection Format, authSource is automatically set to admin in the TXT DNS record. For more information about connecting to Atlas deployments, see Connect to an Atlas Cluster.

?<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.

To use the DNS seed list, use the standard connection string syntax with a prefix of mongodb+srv instead of the standard mongodb. The +srv indicates to the client that the hostname that follows corresponds to a DNS SRV record. The driver or mongosh queries the DNS for the record and uses the record to determine which hosts run the mongod or mongos instances.

Note

The +srv connection string modifier automatically sets tls, or the equivalent ssl option, to true. To override this behavior, explicitly set tls or ssl to false in the connection query string.

When using the +srv format, you must specify the hostname, domain, and top-level domain (TLD) in the following format: <hostname>.<domain>.<TLD>. This table shows how the placeholders correspond to example values:

Placeholder
Example

<hostname>

server

<domain>

example

<TLD>

com

<hostname>.<domain>.<TLD>

server.example.com

This example shows a DNS seed list connection string that correctly uses the <hostname>.<domain>.<TLD> format. It authenticates as user myDatabaseUser with the password D1fficultP%40ssw0rd:

mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@server.example.com/

The corresponding DNS configuration resembles:

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.

Individual SRV records must be in _mongodb._tcp.<hostname>.<domain>.<TLD> format.

When a client connects to a member of the seed list, the client retrieves a list of replica set members it can connect to. Clients often use DNS aliases in their seed lists, which means the host may return a server list that differs from the original seed list. If this happens, clients use the hostnames provided by the replica set rather than the hostnames listed in the seed list to ensure that replica set members can be reached via the hostnames in the resulting replica set config.

Important

The hostnames returned in SRV records must share the same parent domain (in this example, example.com) as the given hostname. If the parent domains and hostname do not match, you can't connect.

Like the standard connection string, the DNS seed list connection string supports specifying options as a query string. With a DNS seed list connection string, you can also specify the following options via a TXT record:

  • replicaSet

  • authSource

You can only specify one TXT record per mongod instance. If multiple TXT records appear in the DNS or if the TXT record contains an option other than replicaSet or authSource, the client returns an error.

The TXT record for the server.example.com DNS entry resembles the following example:

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

Taken together, the DNS SRV records and the options specified in the TXT record resolve to the following standard format connection string:

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb1.example.com:27317,mongodb2.example.com:27017/?replicaSet=mySet&authSource=authDB

To override TXT record options, specify the option in the query string. The following example overrides the authSource option configured in the TXT record of the previous DNS entry:

mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@server.example.com/?connectTimeoutMS=300000&authSource=aDifferentAuthDB

Given the override for the authSource, the equivalent connection string in the standard format would resemble the following example:

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb1.example.com:27317,mongodb2.example.com:27017/?connectTimeoutMS=300000&replicaSet=mySet&authSource=aDifferentAuthDB

Note

The mongodb+srv option fails if there is no available DNS with records that correspond to the hostname identified in the connection string. If you use the +srv connection string modifier, the tls (or the equivalent ssl) option is set to true for the connection. To override this behavior, explicitly set tls or ssl to false in the connection query string.

To connect mongosh to a replica set using the DNS seed list format, see mongosh Connection Options.

Standard Connection String Format

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

The standard URI connection scheme has the form:

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

Connection String Database Options

You can specify a default database in the [/defaultauthdb] field of the connection string. The client uses the specified [/defaultauthdb] database as the default database. If unspecified by the connection string, MongoDB uses the test database as the default.

You can specify the authentication database in your connection string using the authSource connection option. If specified, the client uses this database to verify your identity and credentials. If unspecified, authSource defaults to [/defaultauthdb], or admin if both authSource and [/defaultauthdb] are unspecified.

The following example connection string sets the default database to myDefaultDB and the authentication database to admin:

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb0.example.com:27017/myDefaultDB?authSource=admin

Connection String Components

A connection string includes the following components:

Component
Description

mongodb:// or mongodb+srv://

A required prefix to identify that this is a string in the standard connection format (mongodb://) or SRV connection format (mongodb+srv://). To learn more about each format, see Standard Connection String Format and SRV Connection Format.

username:password@

Optional. Authentication credentials.

If specified, the client will attempt to authenticate the user to the authSource. If authSource is unspecified, the client will attempt to authenticate the user to the defaultauthdb. And if the defaultauthdb is unspecified, to the admin database.

If the username or password includes the following characters, those characters must be converted using 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(s) of the mongod instance(s) 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.

If you use the SRV URI connection format, you can specify only one host and no port. Otherwise, the driver or mongosh raises a parse error and does not perform DNS resolution.

/defaultauthdb

Optional. The authentication database to use if the connection string includes username:password@ authentication credentials but the authSource option is unspecified.

If both authSource and defaultauthdb are unspecified, the client will attempt to authenticate the specified user to the admin database. For more information, see authSource.

IMPORTANT: For Atlas deployments using the SRV Connection Format, authSource is automatically set to admin in the TXT DNS record. For more information about connecting to Atlas deployments, see Connect to an Atlas Cluster.

?<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.

Learn More

For more connection string examples, see Connection Strings.

Back

Options

Next

Atlas Cluster Connection

On this page