For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Docs Menu
Docs Home
/ /
Connect
Docs Home
/ /
Java Reactive Streams Driver
/
Connect
Docs Home
/
Client Libraries
/
Java
/
Java Reactive Streams Driver
/
Connect

Specify Connection URI Options

Overview

This section describes the MongoDB connection and authentication options you can pass in as parameters of the connection URI in the Java Reactive Streams driver.

Using the Connection URI

If you pass a connection URI to the MongoClient constructor, you can include connection options in the string as <name>=<value> pairs. In the following example, the connection URI contains the connectTimeoutMS option with a value of 60000 and the tls option with a value of true:

public class MongoConnection {
public static void main(String[] args) {
    String uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true";
    try (MongoClient client = MongoClients.create(uri)) {
            // Use client here
        }
    }
}

Connection Options

The following sections describe the connection options available in the Java Reactive Streams driver. You can pass these options in as parameters of the connection URI to specify the behavior of the client.

Authentication

Connection Option
Description

authMechanism

Sets the mechanism the Java Reactive Streams driver uses to authenticate the
application. Valid options are defined in the Class ConnectionString API documentation.

Data Type: String
Default: "SCRAM-SHA-256" when connecting to MongoDB v4.0 or later.
"SCRAM-SHA-1" when connecting to MongoDB v3.0 through v3.13.
Connection URI Example: authMechanism=MONGODB-X509

authMechanismProperties

Sets options specific to the authentication mechanism.

Data Type: String
Default: ""
Connection URI Example: authMechanismProperties=AWS_SESSION_TOKEN:12435

authSource

Sets the source of authentication credentials. The source is typically a
database. This option is only respected when authMechanism is set
to MONGO-CR.

Data Type: String
Default: The database in the connection URI, or "admin" if none is provided
Connection URI Example: authSource=admin

username

Sets the username for authentication. When this option is included in a connection
URI, you must percent-escape it.

Data Type: String
Default: ""
Connection URI Example: username=my+user

password

Sets the password for authentication. When this option is included in a connection
URI, you must percent-escape it.

Data Type: String
Default: ""
Connection URI Example: password=strong+password

Connection Configuration

Connection Option
Description

connectTimeoutMS

Sets the number of milliseconds the connection can take before timing out. If an
operation doesn't finish in the specified time, the Java Reactive Streams driver raises a timeout exception.

Data Type: Integer
Default: null
Connection URI Example: connectTimeoutMS=6000

maxIdleTimeMS

Sets the maximum number of milliseconds that a connection can
remain idle in the pool before being removed and closed. Set this value
higher than your application's expected idle period but lower than firewall
or proxy connection timeouts to prevent unexpected disconnections.

Data Type: Integer
Default: null
Connection URI Example: maxIdleTimeMS=6000

maxLifeTimeMS

Sets the maximum lifetime in milliseconds of a pooled connection. If an
operation doesn't finish in the specified time, the Java Reactive Streams driver
closes the connection.

Data Type: Integer
Default: null
Connection URI Example: maxLifeTimeMS=6000

socketTimeoutMS (deprecated)

This option is deprecated. You can configure this timeout by
setting the the client-level timeout
instead.

Milliseconds a receive on a socket can take
before timing out. If an operation doesn't finish in the
specified time, the Java Reactive Streams driver raises a timeout exception.

Data Type: Integer
Default: null
Connection URI Example: socketTimeoutMS=6000

ssl

Sets whether to connect using TLS/SSL.

Data Type: boolean
Default: null
Connection URI Example: ssl=true

sslInvalidHostNameAllowed

Allows invalid host names for TLS/SSL connections.

Data Type: boolean
Default: null
Connection URI Example: sslInvalidHostNameAllowed=true

tls

Sets whether to connect using TLS. Supersedes the ssl option.

Data Type: boolean
Default: null
Connection URI Example: tls=true

tlsAllowInvalidHostnames

Allows invalid host names for TLS connections. Supersedes the
sslInvalidHostNameAllowed option.

Data Type: boolean
Default: null
Connection URI Example: tlsAllowInvalidHostnames=true

tlsInsecure

Enables insecure TLS connections when connecting using TLS.

Data Type: boolean
Default: null
Connection URI Example: tlsInsecure=true

Connection Pool Configuration

Connection Option
Description

maxConnecting

Sets the maximum number of connections a pool can establish concurrently.

Data Type: Integer
Default: null
Connection URI Example: maxConnecting=5

maxPoolSize

Sets the maximum number of connections in the connection pool. If an operation needs a new connection while the connection pool has maxPoolSize connections open, the new operation waits for a new connection to open. To limit this waiting time, use the single timeout setting. To learn more, see the Limit Server Execution Time guide.

Data Type: Integer
Default: null
Connection URI Example: maxPoolSize=5

minPoolSize

Sets the minimum number of connections in the connection pool.

Data Type: Integer
Default: null
Connection URI Example: minPoolSize=3

waitQueueTimeoutMS (deprecated)

This option is deprecated. You can configure this timeout by
setting the the client-level timeout
instead.

Maximum amount of time to wait in milliseconds before either
an in-use connection becomes available or a connection is created and
starts becoming established.

Data Type: Integer
Default: null
Connection URI Example: waitQueueTimeoutMS=6000

Compressor Configuration

Connection Option
Description

compressors

Sets preferred compression types, in order, for wire-protocol messages sent to
or received from the server. Compression types must be passed in as a
comma-separated list. The driver uses the first of these compression types
that the server supports.

Data Type: String
Default: null
Connection URI Example: compressors=snappy,zstd,zlib

zlibCompressionLevel

Sets the compression level for zlib to use. This option accepts
an integer value between -1 and 9:

- -1: (Default). zlib uses its default compression level (usually 6).
- 0: No compression.
- 1: Fastest speed but lowest compression.
- 9: Best compression but slowest speed.

Data Type: Integer
Default: -1
Connection URI Example: zLibCompressionLevel=3

General Configuration

Connection Option
Description

directConnection

Sets whether the driver connects directly to the host.

Data Type: boolean
Default: null
Connection URI Example: directConnection=true

loadBalanced

Sets whether or not the driver is connecting to MongoDB using a load
balancer. If true, the driver assumes that it is connecting through a
load balancer.

Data Type: boolean
Default: null
Connection URI Example: directConnection=true

retryWrites

Sets whether or not the driver retries supported write operations if
they fail due to a network error.

Data Type: boolean
Default: True
Connection URI Example: retryWrites=true

retryReads

Sets whether or not the driver retries supported read operations if
they fail due to a network error.

Data Type: boolean
Default: True
Connection URI Example: retryReads=true

maxAdaptiveRetries

Sets the maximum number of times the driver retries a command
that fails with a retryable overload error. A retryable overload error
carries both the SystemOverloadedError and RetryableError labels.

Note: This option applies to write commands only when retryWrites
is set to true, and applies to read commands only when retryReads is set to true.
Setting the value to 0 disables retry attempts for retryable overload
errors.

Data Type: Integer
Default: null, although the driver typically sets
the value to 2.
Connection URI Example: maxAdaptiveRetries=2

enableOverloadRetargeting

Sets whether the driver may deprioritize servers during server
selection for subsequent retry attempts if they previously returned overload errors.

Note: This applies only if the retryWrites and retryReads
options are set to true, as applicable. This setting does not
apply to sharded clusters.

Data Type: boolean
Default: false
Connection URI Example: enableOverloadRetargeting=true

uuidRepresentation

Sets the mechanism the Java Reactive Streams driver uses to encode instances of
UUID. See the Uuid Representation API documentation for a list of all
valid options.

Data Type: String
Default: unspecified
Connection URI Example: uuidRepresentation=unspecified

Note

Load Shedding in Intelligent Workload Management (IWM)

If errors with SystemOverloadedError or RetryableError labels are causing failures in your application or appearing in your application logs, Load Shedding may be active on your cluster and your driver may not be upgraded to a version that supports it. We recommend upgrading your MongoDB Java Reactive Streams Driver to version 5.8 or later. If you continue to see these errors after upgrading, you can address them through server-side changes, such as reviewing your Load Shedding configuration, or through application-side changes, such as implementing custom error handling or client-side request throttling. Depending on your situation, application-side changes may be preferable or necessary.

Load Shedding is a feature of IWM, and helps manage server load by rejecting excess operations during sustained overload. This feature is available on MongoDB 9.0 and later.

For more information about IWM or handling overload errors, see the Intelligent Workload Management page or Overload Errors page in the Atlas documentation.

Proxy Configuration

Connection Option
Description

proxyHost

Establishes the SOCKS5 proxy host to establish a connection through.
The value of the proxyHost can be a valid IPv4 address, IPv6
address, or a domain name.
Required if either proxyPassword, proxyUsername or proxyPort are specified.

Data Type: String
Default: null
Connection URI Example: proxyHost=example.com

proxyPort

Sets the port number for the SOCKS5 proxy server. Must be a non-negative integer.

Data Type: Integer
Default: null
Connection URI Example: proxyPort=27

proxyUsername

Sets the username for authenticating with the proxy server. Required if proxyPassword is specified.

Data Type: String
Default: null
Connection URI Example: proxyUsername=example

proxyPassword

Sets the password for authenticating with the proxy server. Required if
proxyPassword is specified.

Data Type: String
Default: null
Connection URI Example: proxyPassword=password

Read Preference Configuration

Connection Option
Description

readPreference

Sets the read preference for this connection. Enumerated values are:
primary, primaryPreferred, secondary, secondaryPreferred, and nearest.

Data Type: Enum
Default: primary
Connection URI Example: readPreference.primary

readPreferenceTags

Specifies a tag set as a comma-separated list of
colon-separated key-value pairs, e.g. dc:ny,rack:1.
Spaces are stripped from beginning and end of all keys and values. To
specify a list of tag sets, use multiple readPreferenceTags, separated
by semicolons. To learn more about readPreferenceTags, see the Class ConnectionString API documentation.

Data Type: String
Default: null
Connection URI Example: readPreferenceTags=dc:ny

maxStalenessSeconds

Sets the maximum staleness in seconds. To learn more about staleness,
see the Class ConnectionString API documentation.

Data Type: Integer
Default: null
Connection URI Example: maxStalenessSeconds=60

Replica Set Configuration

Connection Option
Description

replicaSet

Specifies the name of the replica set to connect to.

Data Type: String
Default: null
Connection URI Example: replicaSet=replicaSet

Server Configuration

Connection Option
Description

appName

Sets the logical name of the application.
The application name may be used by the client to identify the
application to the server,
for use in server logs, slow query logs, and profile collection.

Data Type: String
Default: null
Connection URI Example: appName=name

heartbeatFrequencyMS

The frequency in milliseconds of the driver determining the current state of each server in the cluster.

Data Type: Integer
Default: null
Connection URI Example: heartbeatFrequencyMS=6000

localThresholdMS

Sets a ping time threshold for choosing among multiple MongoDB servers
to send a request. When this value is set, the driver will only send
that request to a server whose
ping time is less than or equal to the server with the fastest ping time plus the local threshold.

Data Type: Integer
Default: null
Connection URI Example: localThresholdMS=6000

serverMonitoringMode

Sets the server monitoring mode, which defines the monitoring protocol to use. The enumerated values are: stream, poll, and auto.

Data Type: Enum
Default: auto
Connection URI Example: serverMonitoringMode.auto

serverSelectionTimeoutMS

Sets how long the driver will wait for server selection to succeed before throwing an exception.

Data Type: Integer
Default: null
Connection URI Example: serverSelectionTimeoutMS=6000

SRV Configuration

Connection Option
Description

srvServiceName

Sets the SRV service name. See
the ClusterSettings.getSrvServiceName()
API documentation to learn more.

Data Type: String
Default: "mongodb"
Connection URI Example: srvServiceName=mongodb

srvMaxHosts

Sets the maximum number of hosts from the SRV record to connect to.

Data Type: Integer
Default: null
Connection URI Example: srvMaxHosts=5

srvAllowedHostsSuffix

Sets the domain suffix that the driver uses to validate the host names returned by the SRV record lookup, instead of the domain inferred from the SRV host name. If the value doesn't begin with a period (.), the driver adds one. You can use this option only with the mongodb+srv connection string format.

Data Type: String
Default: null. The driver validates host names against the domain inferred from the SRV host name.
Connection URI Example:

srvAllowedHostsSuffix=.internal.example.com

Warning

Changing the default SRV host name validation can create security vulnerabilities, because it relaxes a built-in safeguard against DNS spoofing. Specify the narrowest suffix that covers the hosts in your deployment. For example, if your SRV host name is cluster.test.internal.example.com, set srvAllowedHostsSuffix to .internal.example.com. Do not set it to .example.com, which accepts any host in the example.com domain.

Write Concern Configuration

Connection Option
Description

safe

Sets whether the driver ensures that all writes are acknowledged by the
MongoDB server, or else throws an exception. If false, the driver
does not ensure that all writes are acknowledged by the MongoDB server.

Data Type: boolean
Default: null
Connection URI Example: safe=true

journal

Sets whether the driver waits for the server to group commit to the
journal file on disk.

Data Type: boolean
Default: null
Connection URI Example: journal=true

w

If set, the driver adds { w : wValue } to all write commands. If set,
implies that safe=True.

Data Type: Integer or String
Default: null
Connection URI Example: w=60

wtimeoutMS (deprecated)

This option is deprecated. You can configure this timeout by
setting the the client-level timeout
instead.

If set, The driver adds { wtimeout : ms } to all write commands. If
set, implies safe=true. This option is used in combination with w.

Data Type: Integer
Default: null
Connection URI Example: wtimeoutMS=6000

For more information about the connection options in this section, see the Databases and Collections guide.

Back
Choose a Connection Target
Next
Databases & Collections
Rate this page

On this page