/ /

指定连接选项

Overview

本节介绍Rust驱动程序中可用的MongoDB连接和身份验证选项。您可以使用连接 URI（也称为连接字符串）或在创建 Client 时在 ClientOptions实例上设置字段来配置连接。

使用连接 URI

如果将连接 URI 传递给 Client::with_uri_str 方法，则可以将连接选项作为 <name>=<value> 对包含在 string 中。以下示例显示了一个连接 URI，其中包含值为 60000 的 connectTimeoutMS 选项和值为 true 的 tls 选项：

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

使用 ClientOptions

您可以在 ClientOptions实例上设立连接选项，而不是将它们包含在连接 URI 中。使用 ClientOptions实例配置连接时，您可以更轻松地在运行时更改设置并在编译期间捕获错误。以下示例展示了如何使用 ClientOptions设立连接选项：

  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)?;

连接选项

以下部分介绍了Rust驱动程序中可用的连接选项。要查看连接选项的完整列表，请访问服务器手册指南中有关连接字符串的连接字符串选项部分。

网络压缩

选项名称	接受的值	默认值	说明
compressors	以逗号分隔的字符串列表	无	指定`Client` 实例按指定顺序使用的压缩程序。要学习；了解有关网络压缩的更多信息，请参阅压缩网络流量指南。
zlibCompressionLevel	介于 `0` 和 `9` 之间的整数	`6`	`zlib`如果使用压缩器，请指定该压缩器的压缩级别字段。级别值越高，压缩程度越高，速度越慢。将值设置为 `0`指定不压缩，将值设置为`9` 指定最大压缩。要学习；了解有关网络压缩的更多信息，请参阅压缩网络流量指南。

超时

选项名称	接受的值	默认值	说明
connectTimeoutMS	Non-negative integer	`10000` （10 秒）	指定尝试连接到服务器时传递给每个底层 TCP 流的连接超时时间（以毫秒为单位）。

服务器选择

选项名称	接受的值	默认值	说明
heartbeatFrequencyMS	大于或等于 500 的整数。	`10000` （10 秒）	指定每个监控线程在执行服务器检查之间等待的时间（以毫秒为单位）。
maxStalenessSeconds	`-1`，或任何大于或等于的整数 `90`	`-1`	指定从主节点开始的最大延迟时间（以秒为单位），在此时间内，可以将从节点(secondary node from replica set)视为可用于给定操作。此选项的值必须至少为 `90`，否则操作会报错。`-1` 表示没有最大延迟。
serverSelectionTimeoutMS	Non-negative integer	`30000` （30 秒）	指定`Client`实例在尝试为操作选择服务器时在超时之前等待的时间（以毫秒为单位）。

身份验证

选项名称	接受的值	默认值	说明
authMechanism	字符串	无	指定要使用的身份验证机制。如果不指定此选项，驱动程序将使用默认的身份验证机制。要了解有关 Rust 驱动程序中身份验证的更多信息，请参阅身份验证机制指南。
authMechanismProperties	字符串	无	为`authMechanism`选项中设置的身份验证机制指定更多属性。
authSource	字符串	查看说明	指定用于身份验证的数据库。对于基于 SCRAM 的身份验证机制，此选项默认为 `admin`；对于 `MONGODB-X509` 机制，此选项默认为 `$external`；对于 `PLAIN` 机制，此选项默认为数据库名称或 `$external`。
TLS	布尔	`false`	指定 `Client` 实例在与服务器连接时使用的 TLS 配置。默认情况下，TLS 处于关闭状态。
tlsAllowInvalidCertificates	布尔	`false`	指定如果服务器提供的证书无效，`Client` 实例是否返回错误。我们建议您仅在测试环境中将此选项设置为 `true`，以避免在应用程序中创建漏洞。
tlsCAFile	字符串	查看说明	指定 `Client` 实例用于 TLS 的证书授权机构 (CA) 文件的路径。如果您未指定此选项，则驱动程序会使用 `webpki-roots` crate 中的 Mozilla 根证书。
tlsCertificateKeyFile	字符串	无	指定 `Client` 实例向服务器呈现的证书文件的路径，以验证其身份。如果您未设置此选项，则 `Client` 实例不会尝试向服务器验证其身份。
tlsCertificateKeyFilePassword	字符串	无	如果密钥已加密，请指定用于解密证书文件中的私钥的密码。
tlsInsecure	布尔	`false`	指定如果服务器提供的证书无效，`Client` 实例是否返回错误。我们建议您仅在测试环境中将此选项设置为 `true`，以避免在应用程序中创建漏洞。

读取和写入操作

选项名称	接受的值	默认值	说明
directConnection	布尔	`false`	指定`Client`实例是否直接连接到单个主机，而不是发现并连接到集群中的所有服务器。
enableOverloadRetargeting	布尔	`false`	指定驱动程序是否降低返回过载错误的服务器的优先级，从而降低在同一台过载服务器上重试的可能性。
journal	布尔	`false`	请求确认操作已传播到磁盘上日志。
localThresholdMS	Non-negative integer	`15`	指定驱动程序与服务器之间的平均往返时间相对于所有合适服务器中最短往返时间所允许持续的毫秒数。 `0` 的值表示没有延迟窗口，因此只有平均往返时间最短的服务器符合条件。
maxAdaptiveRetries	Non-negative integer	`2`	指定驱动程序遇到过载错误时的最大重试次数。
readConcernLevel	字符串	无	指定在 `Client` 实例上执行的操作的默认读关注（read concern）。要了解更多信息，请参阅服务器手册中的读关注（read concern）。
readPreference	字符串	`primary`	指定驱动程序如何将读取操作路由到副本集的节点。要了解更多信息，请参阅服务器手册中的读取偏好（read preference）。
readPreferenceTags	以逗号分隔的键值对列表	无	指定可以考虑进行操作的副本集成员。此密钥的每个实例都是一个独立的标签集。驱动程序会检查每个标签集，直到找到一个或多个包含集中每个标签的服务器。
replicaSet	字符串	无	指定`Client`实例连接到的副本集的名称。
retryReads	布尔	`true`	指定在操作失败时客户端是否重试读取操作。
w	非负整数或字符串	无	请求确认操作已传播到特定数量或类型的服务器。如需了解更多信息，请参阅服务器手册中的写关注（write concern）。
wtimeoutMS	Non-negative integer	无超时	指定写关注（write concern）的时间限制（以毫秒为单位）。如果操作未在时限内传播到请求的级别，驱动程序将引发错误。

连接池

选项名称	接受的值	默认值	说明
maxIdleTimeMS	Non-negative integer	`0`	指定连接在连接池中可以保持空闲状态的时间量（以毫秒为单位），直到服务器关闭该连接。 `0` 值表示客户端不关闭空闲连接。
maxPoolSize	Non-negative integer	`10`	指定 `Client` 实例可以在给定服务器的连接池中创建的最大连接数。如果在值为 `maxPoolSize` 的连接已经检出时尝试操作，则操作会等待进行中的操作完成并且连接返回到连接池。
minPoolSize	Non-negative integer	`0`	指定服务器连接池在给定时间内可用的最小连接数。如果连接池中的连接数少于 `minPoolSize`，则服务器在背景中添加连接，直到连接数达到 `minPoolSize`。

有关连接池的更多信息，请参阅连接池指南。

常规

选项名称	接受的值	默认值	说明
appName	字符串	无	指定 `Client` 实例作为握手的一部分发送到服务器的应用程序名称。指定 `appName` 可帮助您使用服务器日志来确定哪个 `Client` 实例连接到服务器。

API 文档

有关 Rust 驱动程序的 ClientOptions 的更多信息，请参阅 ClientOptions 的 API 文档。