连接指南

在此页面上

Overview

连接 URI
一个连接 URI 的组成部分
MongoDB 客户端
客户端创建方法
连接示例
连接 MongoDB 的其他方式
连接到本地计算机上的 MongoDB Server
连接到副本集

Overview

在本指南中，您可以了解如何使用 Rust 驱动程序连接到 MongoDB 实例或副本集部署。

本指南包括以下部分：

连接 URI 描述连接 URI 及其组成部分
MongoDB客户端描述了 Client 类型以及从连接string创建客户端的方法
连接示例提供了展示如何使用 Atlas 连接字符串连接 MongoDB 的示例
连接到 MongoDB 的其他方法描述了连接未托管在 Atlas 上的 MongoDB 部署的方法

连接 URI

连接 URI（也称为连接字符串）可告知驱动程序如何连接到 MongoDB，以及连接后如何进行操作。

一个连接 URI 的组成部分

以下的例子解释了示例连接 URI 的各个组成部分：

在本例中，我们使用 mongodb 作为协议指定标准连接字符串格式。如果想要获得更高的部署灵活性，并且能够在不重新配置客户端的情况下更改轮换的服务器，也可以使用 DNS 种子列表连接格式。

如果使用基于密码的身份验证，协议之后的连接字符串部分将包含您的用户名和密码。将 user 的占位符替换为您的用户名，将 pass 的占位符替换为您的密码。如果您使用的是不需要用户名和密码的身份验证机制，请省略连接 URI 中的这一部分。

连接字符串的凭证之后的部分指定 MongoDB 实例的主机名或 IP 地址和端口。在前面的例子中，我们使用 sample.host 作为主机名，27017 作为端口。请将这些值替换为指向您的 MongoDB 实例的值。

连接字符串的最后一部分指定了连接和身份验证选项。在此示例中，设置了两个连接选项：maxPoolSize=20 和 w=majority。

提示

连接选项

要学习；了解有关设置连接选项的更多信息，请参阅连接选项指南。

MongoDB 客户端

要连接到 MongoDB，必须创建一个 Client 实例。客户端可管理您的连接并运行数据库命令。

提示

客户端重用

可以通过在各种会话和操作中重复使用客户端来提高性能。您可以使用同一 Client 实例来执行多项任务，而不是每次都创建一个新实例。 Client 类型可供多个线程或异步任务安全地并发使用。

客户端创建方法

您可以通过将 ClientOptions 对象传递给 with_options() 方法，创建使用连接字符串和其他客户端选项的客户端。

要指定您的连接 URI，请将其传递给 ClientOptions 的 parse() 方法。要设置任何其他选项，请设置 ClientOptions 结构体的相关字段。

如果未指定任何客户端选项，请将连接字符串传递给 Client::with_uri_str() 方法来创建客户端。

要学习；了解有关创建客户端的更多信息，请参阅客户端和 with_options() 的API文档。

提示

Stable API

您可以将 Stable API 版本作为一个选项设置，以避免升级到新的服务器版本时出现破坏性变更 (breaking change)。

如需了解 Stable API 功能相关详情，请参阅《Stable API 指南》。

连接示例

以下代码显示如何创建使用 Atlas 连接字符串和 Stable API 版本的客户端、连接到 MongoDB 并验证连接是否成功。从下面的 Asynchronous API或Synchronous API标签页中选择相应的连接代码示例。

提示

如需了解异步和同步运行时相关详情，请参阅《异步和同步 API 指南》。

use mongodb::{ bson::doc, options::{ ClientOptions, ServerApi, ServerApiVersion }, Client };
#[tokio::main]
async fn main() -> mongodb::error::Result<()> {
    // Replace the placeholder with your Atlas connection string
    let uri = "<connection string>";
    let mut client_options = ClientOptions::parse(uri).await?;
    // Set the server_api field of the client_options object to Stable API version 1
    let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
    client_options.server_api = Some(server_api);
    // Create a new client and connect to the server
    let client = Client::with_options(client_options)?;
    // Send a ping to confirm a successful connection
    client.database("admin").run_command(doc! { "ping": 1 }).await?;
    println!("Pinged your deployment. You successfully connected to MongoDB!");
    Ok(())
}

use mongodb::{ bson::doc, options::{ ClientOptions, ServerApi, ServerApiVersion }, sync::Client };
fn main() -> mongodb::error::Result<()> {
    // Replace the placeholder with your Atlas connection string
    let uri = "<connection string>";
    let mut client_options = ClientOptions::parse(uri)?;
    // Set the server_api field of the client_options object to Stable API version 1
    let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
    client_options.server_api = Some(server_api);
    // Create a new client and connect to the server
    let client = Client::with_options(client_options)?;
    // Send a ping to confirm a successful connection
    client.database("admin").run_command(doc! { "ping": 1 }).run()?;
    println!("Pinged your deployment. You successfully connected to MongoDB!");
    Ok(())
}

提示

按照快速入门指南检索您的 Atlas 连接字符串。

注意

要了解如何连接到 Atlas Serverless，请参阅“无服务器实例限制”页面，以确定所需的最低驱动程序版本。

连接 MongoDB 的其他方式

如果必须连接到未托管在 Atlas 上的单个 MongoDB 服务器实例或副本集，请参阅以下部分了解如何连接。

连接到本地计算机上的 MongoDB Server

如果出于开发目的必须在本地计算机上运行 MongoDB Server，则须完成以下步骤：

按照安装 MongoDB 教程在您的计算机上安装 MongoDB Server。根据您的计算机和操作系统选择相应的安装教程。
安装完毕后，启动该服务器。

重要

务必保护您的服务器免受恶意攻击。请参阅安全检查清单，获取安全建议清单。

成功启动 MongoDB Server 后，执行以下步骤以连接到本地实例：

将前面示例中 uri 变量所存储的连接字符串替换为本地 MongoDB 实例的连接字符串。
如果您的 MongoDB Server 在本地运行，则可使用以下连接字符串连接到 MongoDB：
```
mongodb://localhost:<port>
```
在此连接字符串中，<port> 为您配置的服务器侦听传入连接的端口号。
运行连接代码。如果代码执行成功，您应该会在控制台中看到以下输出：
```
Pinged your deployment. You successfully connected to MongoDB!
```

提示

另请参阅：

要了解有关连接字符串和自定义格式的更多信息，请参阅服务器手册中的连接字符串。

连接到副本集

MongoDB 副本集部署是一组连接的实例或节点，其中节点存储相同数据集。这种实例配置提供了数据冗余和高数据可用性。

要连接到副本集部署，请指定每个实例的主机名和端口号（以逗号分隔），并将副本集名称指定为连接字符串中 replicaSet 参数的值。

在以下示例中，主机名为 host1、host2 和 host3，端口号均为 27017。副本集名称为 myRS。以下代码显示了使用这些规范的副本集的连接 URI：

mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS

连接到副本集时，驱动程序默认执行以下操作：

在给定任一节点的地址时发现所有副本集节点。
向相应成员发送操作，例如针对主节点进行写入的指令。要了解有关副本集主节点的更多信息，请参阅 MongoDB Server手册中的副本集主节点。

提示

您只需要指定一台主机来连接到副本集。但是，为了确保指定主机不可用时保持连接，请提供完整的主机列表。

DirectConnection

要强制在连接 URI 中指定的主机上执行操作，请指定 directConnection 选项。直接连接具有以下行为：

不支持 SRV 字符串。
当指定主机不是主节点时，写入会失败。
当指定主机不是主节点时，要求您指定从节点读取偏好。要了解有关这些副本集节点的更多信息，请参阅服务器手册中的副本集从节点。

后退

连接

来年

连接选项