Connection String Options
On this page
This page lists all connection option for both SRV connection strings and standard connection strings.
Connection options are pairs in the following form: name=value
.
The option
name
is case insensitive when using a driver.The option
name
is case insensitive when usingmongosh
.The
value
is always case sensitive.
Separate options with the ampersand (&
) character
name1=value1&name2=value2
. In the following example, a
connection includes the replicaSet
and
connectTimeoutMS
options:
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db1.example.net:27017,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000
Note
Semi-colon separator for connection string arguments
To provide backwards compatibility, drivers currently accept
semi-colons (;
) as option separators.
Replica Set Option
The following connection string connects to a replica set named
myRepl
with members running on the specified hosts. It
authenticates as user myDatabaseUser
with the password
D1fficultP%40ssw0rd
:
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com:27017,db1.example.com:27017,db2.example.com:27017/?replicaSet=myRepl
Connection Option | Description |
---|---|
Specifies the name of the replica set, if the
When connecting to a replica set, provide a seed list of
the replica set member(s) to the | |
Specifies whether the client connects directly to the
|
Connection Options
TLS Options
The following connection string to a replica set includes
tls=true
option. It authenticates as user myDatabaseUser
with the password D1fficultP%40ssw0rd
.
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&tls=true
Alternatively, you can also use the equivalent ssl=true
option:
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&ssl=true
Connection Option | Description |
---|---|
Enables or disables TLS/SSL for the connection:
If the | |
A boolean to enable or disable TLS/SSL for the connection:
If the | |
Specifies the location of a local The client presents this file to the
This option is not supported by all drivers. Refer to the Drivers documentation. This connection string option is not available for the | |
Specifies the password to de-crypt the
This option is not supported by all drivers. Refer to the Drivers documentation. This connection string option is not available for the | |
Specifies the location of a local This option is not supported by all drivers. Refer to the Drivers documentation. This connection string option is not available for the | |
Bypasses validation of the certificates presented by the
Set to This option is not supported by all drivers. Refer to the Drivers documentation. This connection string option is not available for the WarningDisabling certificate validation creates a vulnerability. | |
Disables hostname validation of the certificate presented by
the Set to This option is not supported by all drivers. Refer to the Drivers documentation. This connection string option is not available for the WarningDisabling certificate validation creates a vulnerability. | |
Disables various certificate validations. Set to This connection string option is not available for the WarningDisabling certificate validation creates a vulnerability. |
Timeout Options
Connection Option | Description |
---|---|
The time in milliseconds to attempt a connection before timing
out. The default is 10,000 milliseconds, but specific drivers
might have a different default. For details, 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. |
Compression Options
Connection Option | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
Comma-delimited string of compressors to enable
network compression for communication between this
client and a You can specify the following compressors: 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 ImportantMessages are compressed when both parties enable network compression. Otherwise, messages between the parties are uncompressed. If the parties do not share at least one common compressor, messages between the parties are uncompressed.
| |||||||||
An integer that specifies the compression level if using
zlib for You can specify an integer value ranging from
Supported by |
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 NoteThe | |
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 multiplies the This option is not supported by all drivers. | |
The maximum time in milliseconds that a thread can wait for a connection to become available. For default values, see the driver documentation. This option is not supported by all drivers. |
Write Concern Options
Write concern describes the level of acknowledgment requested from MongoDB. The write concern option is supported by the:
MongoDB drivers
You can specify the write concern both in the connection string and
as a parameter to methods like insert
or update
. If the
write concern is specified in both places, the method parameter
overrides the connection-string setting.
MongoDB Atlas deployment connection strings use "majority"
by default. If you don't specify write concern for an MongoDB Atlas
deployment, MongoDB Atlas enforces "majority"
.
The following connection string to a replica set specifies
"majority"
write concern and a 5 second
timeout using the wtimeoutMS
write concern parameter:
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&w=majority&wtimeoutMS=5000
Connection Option | Description |
---|---|
Corresponds to the write concern When | |
For more information, see Write Concern.
readConcern Options
For the WiredTiger storage engine, MongoDB 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.
The following connection string to a replica set specifies
readConcernLevel=majority
:
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readConcernLevel=majority
Connection Option | Description |
---|---|
The level of isolation. Can accept one of the following values: This connection string option is not available for
|
For more information, 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.
For example:
The following connection string to a replica set specifies
secondary
read preference mode and amaxStalenessSeconds
value of 120 seconds:mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readPreference=secondary&maxStalenessSeconds=120 The following connection string to a sharded cluster specifies
secondary
read preference mode and amaxStalenessSeconds
value of 120 seconds:mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongos1.example.com,mongos2.example.com/?readPreference=secondary&maxStalenessSeconds=120 The following connection string to a sharded cluster specifies
secondary
read preference mode as well as threereadPreferenceTags
:mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongos1.example.com,mongos2.example.com/?readPreference=secondary&readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=dc:ny&readPreferenceTags=
Order matters when using multiple readPreferenceTags
. The
readPreferenceTags
are tried in order until a match is found. Once
found, that specification is used to find all eligible matching
members and any remaining readPreferenceTags
are ignored.
For details, see Order of Tag Matching.
Connection Option | Description |
---|---|
Specifies the read preferences for this connection. Possible values are: Distributed transactions that contain
read operations must use read preference This connection string option is not available for the
| |
Specifies, in seconds, how stale a secondary can be before the client
stops using it for read operations. For details, see
Read Preference 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 | |
Specifies the tags document as a comma-separated list of colon-separated key-value pairs. For example,
To specify a list of tag documents, use multiple
Order matters when using multiple This connection string option is not available for the
|
For more information, see Read preferences.
Authentication Options
The following connection string to a replica set specifies the
authSource
to the admin
database. That is, the user
credentials are authenticated against the admin
database.
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?replicaSet=myRepl&authSource=admin
Note
If the username or password includes the following characters:
: / ? # [ ] @
those characters must be converted using percent encoding.
Connection Option | Description | |
---|---|---|
Specify the database name associated with the user's
credentials. If The MongoDB will ignore | ||
Specify the authentication mechanism that MongoDB uses to
authenticate the connection. If you don't specify an
Only MongoDB Enterprise To use To use When using NoteIf the AWS access key ID, the secret access key, or the session token include the following characters:
those characters must be converted using percent encoding. Alternatively, if the AWS access key ID, secret access key, or
session token are defined on your platform using their respective
AWS IAM environment variables
See Connect to an Atlas Cluster for example usage of
the See Authentication on Self-Managed Deployments for more information about the authentication system in MongoDB. Also consider Use x.509 Certificates to Authenticate Clients on Self-Managed Deployments for more information on x509 authentication. | ||
Specify properties for the specified Possible key-value pairs are:
| ||
Set the Kerberos service name when connecting to Kerberized MongoDB instances. This value must match the service name set on MongoDB instances to which you are connecting.
|
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 |
---|---|
The size (in milliseconds) of the latency window for selecting among multiple suitable MongoDB instances. Default: 15 milliseconds. All drivers use | |
Specifies how long (in milliseconds) to block for server
selection before throwing an exception. Default: 30,000
milliseconds. | |
Single-threaded drivers only. When Multi-threaded drivers and | |
Default:
| |
Single-threaded clients only. Controls how often the client checks the state of the TCP connection to the MongoDB deployment. If you specify a lower value, the client detects network issues faster but uses more CPU. Default: 5 seconds. This option is not supported by all drivers. Refer to the Drivers documentation. |
Miscellaneous Configuration
Connection Option | Description |
---|---|
Specify a custom app name. The app name appears in:
The
| |
Enables retryable reads. Possible values are:
| |
Enable retryable writes. Possible values are:
MongoDB drivers retry
transaction commit and abort operations
regardless of the value of | |
Possible values are:
For the default, see the Drivers documentation for your driver. NoteNot all drivers support the | |
Specifies whether the client is connecting to a load balancer. This option is
You can set this option to
| |