/ /

Specify Connection Options

This section explains the MongoDB connection and authentication options supported by the Node.js driver that you can set within a MongoClientOptions instance.

For more information on setting connection options directly in a connection string, see Connection Strings in the MongoDB Server manual.

Name	Accepted Values	Default Value	Description
appName	string	`null`	Specifies the app name the driver passes to the server in the client metadata as part of the connection handshake. The driver sends the `appName` value to MongoDB when establishing the connection. This value is recorded in the log file, the slow query logs, and profile collections.
authMechanism	string	`null`	Specifies the authentication mechanism method to use for connection to the server. If you do not specify a value, the driver uses the default mechanism, either `SCRAM-SHA-1` or `SCRAM-SHA-256` depending on the server version. See the Authentication Mechanisms section for available authentication mechanisms.
authMechanismProperties	comma separated key:value pairs, for example, "opt1:val1,opt2:val2"	`null`	Specifies other options provided for authentication, such as the option to enable hostname canonicalization for GSSAPI.
authSource	string	`null`	Specifies the database that connections authenticate against.
autoSelectFamily	boolean	`true`	If set to `true`, the socket attempts to connect to IPv6 and IPv4 addresses until a connection is established. If available, the driver will select the first IPv6 address.
autoSelectFamilyAttemptTimeout	non-negative integer	`null`	Specifies the amount of time in milliseconds to wait for a connection attempt to finish before trying the next address when using the `autoSelectFamily` option. If set to a positive integer less than `10`, the value `10` is used instead.
compressors	comma separated list of strings, for example, "snappy,zlib,zstd"	`null`	Specifies the allowed compression types for wire protocol messages sent to or received from the server. See Network Compression for more information.
connectTimeoutMS	non-negative integer	`30000`	Specifies the amount of time in milliseconds to wait to establish a single TCP socket connection to the server before raising an error. Specifying `0` means your application sets an infinite socket timeout when establishing a socket.
directConnection	boolean	`false`	Specifies whether to force dispatch all operations to the host specified in the connection URI.
enableUtf8Validation	boolean	`true`	Specifying `true` enables UTF-8 validation for the connection. MongoDB throws an error when it attempts to serialize string data that contains invalid UTF-8 characters to BSON. This applies to both document keys and document values, this validation adds processing overhead. Specifying `false` disables UTF-8 validation for the connection. MongoDB does not throw errors when data contains invalid UTF-8 data. If you disable validation, your application avoids the validation processing overhead. Editing data while validation is disabled can result in loss of data. Disabling UTF-8 validation is a temporary workaround to query or export data only. To learn more about UTF-8 characters, see UTF-8 on Wikipedia.
heartbeatFrequencyMS	integer greater than or equal to 500	`null`	Specifies the interval, in milliseconds, between regular server monitoring checks.
loadBalanced	boolean	`null`	Specifies whether the driver is connecting to a load balancer.
localThresholdMS	non-negative integer	`15`	Specifies the size of the latency window, in milliseconds, on round trip time for selecting between suitable servers. Specifying `0` means no wait, meaning the fastest available server.
maxIdleTimeMS	non-negative integer	`0`	Specifies the amount of time, in milliseconds, a connection can be idle before it's closed. Specifying `0` means no minimum.
maxPoolSize	non-negative integer	`100`	Specifies the maximum number of clients or connections the driver can create in its connection pool. This count includes connections in use.
maxConnecting	non-negative integer	`2`	Specifies the maximum number of connections a driver's connection pool may be establishing concurrently.
maxStalenessSeconds	-1, or an integer greater than or equal 90	`null`	Specifies the maximum replication lag, in wall clock time, that a secondary can experience and still be eligible for server selection. Specifying `-1` means no maximum.
minPoolSize	non-negative integer	`0`	Specifies the number of connections the driver creates and maintains in the connection pool even when no operations are occurring. This count includes connections in use.
proxyHost	string	`null`	Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or domain name.
proxyPort	non-negative integer	`null`	Specifies the TCP port number of the SOCKS5 proxy server. If you set the `proxyHost` option, the value of this option defaults to `1080`.
proxyUsername	string	`null`	Specifies the username for authentication to the SOCKS5 proxy server. If you set this option to a zero-length string, the driver ignores it.
proxyPassword	string	`null`	Specifies the password for authentication to the SOCKS5 proxy server. If you set this option to a zero-length string, the driver ignores it.
readConcernLevel	string	`null`	Specifies the default read concern for the client. See read concern for more information.
readPreference	string	`"primary"`	Specifies the default read preference for the client (excluding tags). See read preference for more information.
readPreferenceTags	comma-separated key:value pairs, for example, "dc:ny,rack:1" and "dc:ny can be specified multiple times, each instance of this key is a separate tag set	`null`	Specifies the default read preference tags for the client. This option is valid only if the read preference mode is not primary. The driver uses the order of the tags in the URI as the order for the read preference.
replicaSet	string	`null`	Specifies the name of the replica set to connect to.
retryReads	boolean	`true`	Enables retryable reads.
retryWrites	boolean	`true`	Enables retryable writes.
serverMonitoringMode	`auto`, `stream`, `poll`	`auto`	Specifies the monitoring mode that the driver monitors use. When this option is set to `auto`, the monitoring mode is determined by the environment in which the driver is running. The driver uses polling mode in function-as-a-service (FaaS) environments and the streaming mode in other environments.
serverSelectionTimeoutMS	non-negative integer	`30000`	Specifies the timeout, in milliseconds, to block for server selection before raising an error.
socketTimeoutMS	non-negative integer	`0`	Specifies the amount of time in milliseconds spent attempting to send or receive on a socket before timing out. Specifying `0` means your application sets an infinite socket timeout when establishing a socket.
srvMaxHosts	non-negative integer	`0`	Specifies the maximum number of SRV results to randomly select when initially populating the seedlist or, during SRV polling, adding new hosts to the topology.
srvServiceName	a valid SRV service name according to RFC 6335	`"mongodb"`	Specifies the service name to use for SRV lookup in initial DNS seedlist discovery.
ssl	boolean	`false`	The `ssl` is an alias for the `tls` option.
tls	boolean	`false`	Specifies whether TLS is required for connections to the server. Using a `srvServiceName` of `"mongodb+srv"`, or specifying other `tls`-prefixed options implicitly sets the value of `tls` to `true`.
tlsAllowInvalidCertificates	boolean	`false`	Specifies whether the driver generates an error when the server's TLS certificate is invalid. Set this option to `true` for testing purposes only.
tlsAllowInvalidHostnames	boolean	`false`	Specifies whether the driver generates an error when there is a mismatch between the server's hostname and the hostname specified by the TLS certificate. Set this option to `true` for testing purposes only.
tlsCAFile	string	`null`	Specifies the path to a file with either a single or bundle of certificate authorities to trust when making a TLS connection. To learn more about setting this connection option, see the Provide Certificate Filepaths section of the TLS guide.
tlsCertificateKeyFile	string	`null`	Specifies the path to the client certificate file or the client private key file. If you need both, you must concatenate the files. To learn more about setting this connection option, see the Provide Certificate Filepaths section of the TLS guide.
tlsCertificateKeyFilePassword	string	`null`	Specifies the password to decrypt the client private key to be used for TLS connections.
tlsInsecure	boolean	`false`	Specifies to relax TLS constraints as much as possible, such as allowing invalid certificates or hostname mismatches. Set this option to `true` for testing purposes only.
waitQueueTimeoutMS	non-negative integer	`0`	Specifies the amount of time, in milliseconds, spent attempting to check out a connection from a server's connection pool before timing out. `0` signifies no timeout.
zlibCompressionLevel	integer between `-1` and `9` (inclusive)	`-1`	Specifies the level of compression when using zlib to compress wire protocol messages. `-1` signifies the default level, `0` signifies no compression, `1` signifies the fastest speed, and `9` signifies the best compression. See Network Compression for more information.

Connection Time Out Options

Setting	Description
connectTimeoutMS	`connectTimeoutMS` is a connection option that sets the time, in milliseconds, for an individual connection from your connection pool to establish a TCP connection to the MongoDB Server before timing out. To modify the allowed time for MongoClient.connect to establish a connection to a MongoDB Server, use the `serverSelectionTimeoutMS` option instead. Default: 30000
socketTimeoutMS	`socketTimeoutMS` specifies the amount of time the driver waits for an inactive socket before closing it. The default value is to never time out the socket. This option applies only to sockets that have already been connected.
maxTimeMS	maxTimeMS specifies the maximum amount of time that the server waits for an operation to complete after it has reached the server. If an operation runs over the specified time limit, it returns a timeout error. You can pass `maxTimeMS` only to an individual operation or to a cursor.

To specify the optional settings for your MongoClient, declare one or more available settings in the options object of the constructor as follows:

const client = new MongoClient(uri, {
  connectTimeoutMS: 2000,
  socketTimeoutMS: 2000,
});

To see all the available settings, see the MongoClientOptions API Documentation.

To specify maxTimeMS, pass it as an option to an individual operation:

const filter = {};
const result = await collection.distinct('my-key', filter, {
  maxTimeMS: 50,
});

Close Sockets After Connection

If you experience unexpected network behavior or if a MongoDB process fails with an error, you might not receive confirmation that the driver correctly closed the corresponding socket.

To make sure that the driver correctly closes the socket in these cases, set the socketTimeoutMS option. When a MongoDB process times out, the driver will close the socket. We recommend that you select a value for socketTimeoutMS that is two to three times longer than the expected duration of the slowest operation that your application executes.

Prevent Long-Running Operations From Slowing Down the Server

You can prevent long-running operations from slowing down the server by specifying a timeout value. You can chain the maxTimeMS() method to an individual operation to set a timeout on a specific action.

The following example shows how you can chain the maxTimeMS() method to the find() operation, which returns a cursor:

const cursor = collection.find({ name: 'a' }).maxTimeMS(5000);

keepAlive Connection Option

The keepAlive connection option specifies whether to enable Transmission Control Protocol (TCP) keepalives on a TCP socket. If you enable keepalives, the driver checks whether the connection is active by sending periodic pings to your MongoDB deployment. This functionality works only if your operating system supports the SO_KEEPALIVE socket option.

The keepAliveInitialDelay option specifies the number of milliseconds that the driver waits before initiating a keepalive.

The 5.3 driver version release deprecated these options. Starting in version 6.0 of the driver, the keepAlive option is permanently set to true, and the keepAliveInitialDelay is set to 300000 milliseconds (300 seconds).

Warning

If your firewall ignores or drops the keepalive messages, you might not be able to identify dropped connections.

Additional Information

To learn more about connection options that you can set within a MongoClientOptions instance, see MongoClientOptions in the API Documentation.

Back

Create a MongoClient

Compress Network Traffic