Struct ClientOptions

#[non_exhaustive]
pub struct ClientOptions {

    pub hosts: Vec<ServerAddress>,
    pub app_name: Option<String>,
    pub compressors: Option<Vec<Compressor>>,
    pub cmap_event_handler: Option<EventHandler<CmapEvent>>,
    pub command_event_handler: Option<EventHandler<CommandEvent>>,
    pub connect_timeout: Option<Duration>,
    pub credential: Option<Credential>,
    pub direct_connection: Option<bool>,
    pub driver_info: Option<DriverInfo>,
    pub heartbeat_freq: Option<Duration>,
    pub load_balanced: Option<bool>,
    pub local_threshold: Option<Duration>,
    pub max_idle_time: Option<Duration>,
    pub max_pool_size: Option<u32>,
    pub min_pool_size: Option<u32>,
    pub max_connecting: Option<u32>,
    pub read_concern: Option<ReadConcern>,
    pub repl_set_name: Option<String>,
    pub retry_reads: Option<bool>,
    pub retry_writes: Option<bool>,
    pub server_monitoring_mode: Option<ServerMonitoringMode>,
    pub sdam_event_handler: Option<EventHandler<SdamEvent>>,
    pub selection_criteria: Option<SelectionCriteria>,
    pub server_api: Option<ServerApi>,
    pub server_selection_timeout: Option<Duration>,
    pub default_database: Option<String>,
    pub srv_service_name: Option<String>,
    pub tls: Option<Tls>,
    pub tracing_max_document_length_bytes: Option<usize>,
    pub write_concern: Option<WriteConcern>,
    pub srv_max_hosts: Option<u32>,
    /* private fields */
}

Contains the options that can be used to create a new Client.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

hosts: Vec<ServerAddress>

The initial list of seeds that the Client should connect to.

Note that by default, the driver will autodiscover other nodes in the cluster. To connect directly to a single server (rather than autodiscovering the rest of the cluster), set the direct_connection field to true.

app_name: Option<String>

The application name that the Client will send to the server as part of the handshake. This can be used in combination with the server logs to determine which Client is connected to a server.

compressors: Option<Vec<Compressor>>

Available on crate features zstd-compression or zlib-compression or snappy-compression only.

The allowed compressors to use to compress messages sent to and decompress messages received from the server. This list should be specified in priority order, as the compressor used for messages will be the first compressor in this list that is also supported by the server selected for operations.

cmap_event_handler: Option<EventHandler<CmapEvent>>

The handler that should process all Connection Monitoring and Pooling events.

command_event_handler: Option<EventHandler<CommandEvent>>

The handler that should process all command-related events.

Note that monitoring command events may incur a performance penalty.

connect_timeout: Option<Duration>

The connect timeout passed to each underlying TcpStream when attemtping to connect to the server.

The default value is 10 seconds.

credential: Option<Credential>

The credential to use for authenticating connections made by this client.

direct_connection: Option<bool>

Specifies whether the Client should directly connect to a single host rather than autodiscover all servers in the cluster.

The default value is false.

driver_info: Option<DriverInfo>

Extra information to append to the driver version in the metadata of the handshake with the server. This should be used by libraries wrapping the driver, e.g. ODMs.

heartbeat_freq: Option<Duration>

The amount of time each monitoring thread should wait between performing server checks.

The default value is 10 seconds.

load_balanced: Option<bool>

Whether or not the client is connecting to a MongoDB cluster through a load balancer.

local_threshold: Option<Duration>

When running a read operation with a ReadPreference that allows selecting secondaries, local_threshold is used to determine how much longer the average round trip time between the driver and server is allowed compared to the least round trip time of all the suitable servers. For example, if the average round trip times of the suitable servers are 5 ms, 10 ms, and 15 ms, and the local threshold is 8 ms, then the first two servers are within the latency window and could be chosen for the operation, but the last one is not.

A value of zero indicates that there is no latency window, so only the server with the lowest average round trip time is eligible.

The default value is 15 ms.

max_idle_time: Option<Duration>

The amount of time that a connection can remain idle in a connection pool before being closed. A value of zero indicates that connections should not be closed due to being idle.

By default, connections will not be closed due to being idle.

max_pool_size: Option<u32>

The maximum amount of connections that the Client should allow to be created in a connection pool for a given server. If an operation is attempted on a server while max_pool_size connections are checked out, the operation will block until an in-progress operation finishes and its connection is checked back into the pool.

The default value is 10.

min_pool_size: Option<u32>

The minimum number of connections that should be available in a server’s connection pool at a given time. If fewer than min_pool_size connections are in the pool, connections will be added to the pool in the background until min_pool_size is reached.

The default value is 0.

max_connecting: Option<u32>

The maximum number of new connections that can be created concurrently.

If specified, this value must be greater than 0. The default is 2.

read_concern: Option<ReadConcern>

Specifies the default read concern for operations performed on the Client. See the ReadConcern type documentation for more details.

repl_set_name: Option<String>

The name of the replica set that the Client should connect to.

retry_reads: Option<bool>

Whether or not the client should retry a read operation if the operation fails.

The default value is true.

retry_writes: Option<bool>

Whether or not the client should retry a write operation if the operation fails.

The default value is true.

server_monitoring_mode: Option<ServerMonitoringMode>

Configures which server monitoring protocol to use.

The default is Auto.

sdam_event_handler: Option<EventHandler<SdamEvent>>

The handler that should process all Server Discovery and Monitoring events.

selection_criteria: Option<SelectionCriteria>

The default selection criteria for operations performed on the Client. See the SelectionCriteria type documentation for more details.

server_api: Option<ServerApi>

The declared API version for this client. The declared API version is applied to all commands run through the client, including those sent through any handle derived from the client.

Specifying stable API options in the command document passed to run_command AND declaring an API version on the client is not supported and is considered undefined behaviour. To run any command with a different API version or without declaring one, create a separate client that declares the appropriate API version.

For more information, see the Stable API manual page.

server_selection_timeout: Option<Duration>

The amount of time the Client should attempt to select a server for an operation before timing outs

The default value is 30 seconds.

default_database: Option<String>

Default database for this client.

By default, no default database is specified.

srv_service_name: Option<String>

Overrides the default “mongodb” service name for SRV lookup in both discovery and polling

tls: Option<Tls>

The TLS configuration for the Client to use in its connections with the server.

By default, TLS is disabled.

tracing_max_document_length_bytes: Option<usize>

Available on crate feature tracing-unstable only.

The maximum number of bytes that the driver should include in a tracing event or log message’s extended JSON string representation of a BSON document, e.g. a command or reply from the server. If truncation of a document at the exact specified length would occur in the middle of a Unicode codepoint, the document will be truncated at the closest larger length which falls on a boundary between codepoints. Note that in cases where truncation occurs the output will not be valid JSON.

The default value is 1000.

write_concern: Option<WriteConcern>

Specifies the default write concern for operations performed on the Client. See the WriteConcern type documentation for more details.

srv_max_hosts: Option<u32>

Limit on the number of mongos connections that may be created for sharded topologies.

Implementations

impl ClientOptions

pub fn parse<C, E>(conn_str: C) -> ParseConnectionString

where C: TryInto<ConnectionString, Error = E>, E: Into<Error>,

Parses a MongoDB connection string (as either a &str or a ConnectionString) into a ClientOptions struct. If the string is malformed or one of the options has an invalid value, an error will be returned.

In the case that “mongodb+srv” is used, SRV and TXT record lookups will be done as part of this method.

The format of a MongoDB connection string is described here.

Note that default_database will be set from /defaultauthdb in connection string.

The following options are supported in the options query string:

• appName: maps to the app_name field
• authMechanism: maps to the mechanism field of the credential field
• authSource: maps to the source field of the credential field
• authMechanismProperties: maps to the mechanism_properties field of the credential field
• compressors: maps to the compressors field
• connectTimeoutMS: maps to the connect_timeout field
• direct: maps to the direct field
• heartbeatFrequencyMS: maps to the heartbeat_frequency field
• journal: maps to the journal field of the write_concern field
• localThresholdMS: maps to the local_threshold field
• maxIdleTimeMS: maps to the max_idle_time field
• maxStalenessSeconds: maps to the max_staleness field of the selection_criteria field
• maxPoolSize: maps to the max_pool_size field
• minPoolSize: maps to the min_pool_size field
• readConcernLevel: maps to the read_concern field
• readPreferenceField: maps to the ReadPreference enum variant of the selection_criteria field
• readPreferenceTags: maps to the tags field of the selection_criteria field. Note that this option can appear more than once; each instance will be mapped to a separate tag set
• replicaSet: maps to the repl_set_name field
• retryWrites: not yet implemented
• retryReads: maps to the retry_reads field
• serverSelectionTimeoutMS: maps to the server_selection_timeout field
• socketTimeoutMS: unsupported, does not map to any field
• ssl: an alias of the tls option
• tls: maps to the TLS variant of the tls field`.
• tlsInsecure: relaxes the TLS constraints on connections being made; currently is just an alias of tlsAllowInvalidCertificates, but more behavior may be added to this option in the future
• tlsAllowInvalidCertificates: maps to the allow_invalidCertificates field of the tls field
• tlsCAFile: maps to the ca_file_path field of the tls field
• tlsCertificateKeyFile: maps to the cert_key_file_path field of the tls field
• w: maps to the w field of the write_concern field
• waitQueueTimeoutMS: unsupported, does not map to any field
• wTimeoutMS: maps to the w_timeout field of the write_concern field
• zlibCompressionLevel: maps to the level field of the Compressor::Zlib variant (which requires the zlib-compression feature flag) of the Compressor enum

await will return Result<ClientOptions>.

These methods can be chained before .await to set options:

• resolver_config

impl ClientOptions

pub fn builder() -> ClientOptionsBuilder<((), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), ())>

Create a builder for building ClientOptions. On the builder, call .hosts(...)(optional), .app_name(...)(optional), .compressors(...)(optional), .cmap_event_handler(...)(optional), .command_event_handler(...)(optional), .connect_timeout(...)(optional), .credential(...)(optional), .direct_connection(...)(optional), .driver_info(...)(optional), .heartbeat_freq(...)(optional), .local_threshold(...)(optional), .max_idle_time(...)(optional), .max_pool_size(...)(optional), .min_pool_size(...)(optional), .max_connecting(...)(optional), .read_concern(...)(optional), .repl_set_name(...)(optional), .retry_reads(...)(optional), .retry_writes(...)(optional), .server_monitoring_mode(...)(optional), .sdam_event_handler(...)(optional), .selection_criteria(...)(optional), .server_api(...)(optional), .server_selection_timeout(...)(optional), .default_database(...)(optional), .srv_service_name(...)(optional), .tls(...)(optional), .tracing_max_document_length_bytes(...)(optional), .write_concern(...)(optional), .srv_max_hosts(...)(optional) to set the values of the fields. Finally, call .build() to create the instance of ClientOptions.

Trait Implementations

impl Clone for ClientOptions

fn clone(&self) -> ClientOptions

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ClientOptions

fn fmt(&self, __f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ClientOptions

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ClientOptions

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ClientOptions

fn eq(&self, __other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.