/ /

Specify Connection Options

Overview

This section describes the MongoDB connection and authentication options available in Rust driver. You can configure your connection by using either the connection URI (also called a connection string) or by setting fields on a ClientOptions instance when you create a Client.

Using the Connection URI

If you pass a connection URI to the Client::with_uri_str method, you can include connection options in the string as <name>=<value> pairs. The following example shows a connection URI containing the connectTimeoutMS option with a value of 60000 and the tls option with a value of true:

 use mongodb::Client;
   let uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true";
   let client = Client::with_uri_str(uri).await?;

Using ClientOptions

You can set connection options on a ClientOptions instance instead of including them in your connection URI. When you configure your connection using a ClientOptions instance, it is easier for you to change settings at runtime and catch errors during compilation. The following example shows how to use ClientOptions to set connection options:

  use std::time::Duration;
  use mongodb::{Client, options::ClientOptions};
  let uri = "mongodb://<hostname>:<port>/";
  let mut client_options = ClientOptions::parse(uri).await?;
  client_options.connect_timeout = Some(Duration::from_secs(60000));
  //Set additional options on client_options here
  let client = Client::with_options(client_options)?;

Connection Options

The following sections describe the connection options available in the Rust driver. To see a full list of connection options, visit the Connection String Options section of the Server manual guide on Connection Strings.

Network Compression

Option Name	Accepted Values	Default Value	Description
compressors	A comma-separated list of strings	None	Specifies compressors that the `Client` instance uses in the specified order. To learn more about network compression, see the Network Compression guide.
zlibCompressionLevel	Integer between `0` and `9`	`6`	Specifies the level field of the `zlib` compression if you use that compressor. A higher level value results in more compression, which is slower. Setting a value of `0` specifies no compression, and setting a value of `9` specifies maximum compression. To learn more about network compression, see the Network Compression guide.

Timeout

Option Name	Accepted Values	Default Value	Description
connectTimeoutMS	Non-negative integer	`10000` (10 seconds)	Specifies the connection timeout, in milliseconds, passed to each underlying TCP stream when attempting to connect to the server.

Server Selection

Option Name	Accepted Values	Default Value	Description
heartbeatFrequencyMS	Integer greater than or equal to 500	`10000` (10 seconds)	Specifies the amount of time in milliseconds that each monitoring thread waits between performing server checks.
maxStalenessSeconds	`-1`, or any integer greater than or equal to `90`	`-1`	Specifies the maximum lag, in seconds, behind the primary node that a secondary node can be considered for the given operation. The value of this option must be at least `90`, or the operation raises an error. A value of `-1` means there is no maximum lag.
serverSelectionTimeoutMS	Non-negative integer	`30000` (30 seconds)	Specifies the amount of time in milliseconds that the `Client` instance waits when attempting to select a server for an operation before timing out.

Authentication

Option Name	Accepted Values	Default Value	Description
authMechanism	String	None	Specifies which authentication mechanism to use. If you do not specify this option, the driver uses the default authentication mechanism. To learn more about authentication in the Rust driver, see the guide on Authentication Mechanisms.
authMechanismProperties	String	None	Specifies more properties for the authentication mechanism set in the `authMechanism` option.
authSource	String	See description	Specifies the database used to authenticate. This option defaults to `admin` for SCRAM-based authentication mechanisms, `$external` for the `MONGODB-X509` mechanism, and the database name or `$external` for the `PLAIN` mechanism.
tls	Boolean	`false`	Specifies the TLS configuration for the `Client` instance to use in its connections with the server. By default, TLS is off.
tlsAllowInvalidCertificates	Boolean	`false`	Specifies whether the `Client` instance returns an error if the server presents an invalid certificate. We recommend that you set this option to `true` only in testing environments to avoid creating vulnerabilities in your application.
tlsCAFile	String	See description	Specifies the path to the certificate authority (CA) file that the `Client` instance uses for TLS. If you do not specify this option, the driver uses the Mozilla root certificates from the `webpki-roots` crate.
tlsCertificateKeyFile	String	None	Specifies the path to the certificate file that the `Client` instance presents to the server to verify its identify. If you do not set this option, the `Client` instance does not attempt to verify its identity to the server.
tlsCertificateKeyFilePassword	String	None	Specifies the password to decrypt the private key in your certificate file, if the key is encrypted.
tlsInsecure	Boolean	`false`	Specifies whether the `Client` instance returns an error if the server presents an invalid certificate. We recommend that you set this option to `true` only in testing environments to avoid creating vulnerabilities in your application.

Read and Write Operations

Option Name	Accepted Values	Default Value	Description
directConnection	Boolean	`false`	Specifies whether the `Client` instance directly connects to a single host instead of discovering and connecting to all servers in the cluster.
enableOverloadRetargeting	Boolean	`false`	Specifies if the driver deprioritizes a server that returns an overload error, reducing the likelihood of retrying on the same overloaded server.
journal	Boolean	`false`	Requests acknowledgment that the operation propagated to the on-disk journal.
localThresholdMS	Non-negative integer	`15`	Specifies the amount of time in milliseconds that the average round-trip time between the driver and server can last compared to the shortest round-trip time of all the suitable servers. A value of `0` indicates that there is no latency window, so only the server with the lowest average round-trip time is eligible.
maxAdaptiveRetries	Non-negative integer	`2`	Specifies the maximum number of retries to attempt when the driver encounters overload errors.
readConcernLevel	String	None	Specifies the default read concern for operations performed on the `Client` instance. To learn more, see Read Concern in the Server manual.
readPreference	String	`primary`	Specifies how the driver routes a read operation to members of a replica set. To learn more, see Read Preference in the Server manual.
readPreferenceTags	A list of comma-separated key-value pairs	None	Specifies which replica set members are considered for operations. Each instance of this key is a separate tag set. The driver checks each tag set until it finds one or more servers with each tag in the set.
replicaSet	String	None	Specifies the name of the replica set that the `Client` instance connects to.
retryReads	Boolean	`true`	Specifies whether the client retries a read operation if the operation fails.
w	Non-negative integer or string	None	Requests acknowledgment that the operation has propagated to a specific number or variety of servers. To learn more, see Write Concern in the Server manual.
wTimeoutMS	Non-negative integer	No timeout	Specifies a time limit, in milliseconds, for the write concern. If an operation has not propagated to the requested level within the time limit, the driver raises an error.

Connection Pools

Option Name	Accepted Values	Default Value	Description
maxIdleTimeMS	Non-negative integer	`0`	Specifies the amount of time in milliseconds that a connection can remain idle in a connection pool before the server closes it. A value of `0` indicates that the client does not close idle connections.
maxPoolSize	Non-negative integer	`10`	Specifies the maximum number of connections that the `Client` instance can create in a connection pool for a given server. If you attempt an operation while the value of `maxPoolSize` connections are checked out, the operation waits until an in-progress operation finishes and the connection returns to the pool.
minPoolSize	Non-negative integer	`0`	Specifies the minimum number of connections available in a server's connection pool at a given time. If fewer than `minPoolSize` connections are in the pool, the server adds connections in the background up to the value of `minPoolSize`.

For more information on connection pools, see the connection pools guide.

General

Option Name	Accepted Values	Default Value	Description
appName	String	None	Specifies the application name that the `Client` instance sends to the server as part of the handshake. Specifying an `appName` can help you use the server logs to determine which `Client` instance is connected to the server.

API Documentation

For more information about ClientOptions for the Rust driver, see the API documentation for ClientOptions.

Back

Choose a Connection Target

Compress Network Traffic