连接指南

一个连接 URI 的组成部分

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

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

连接字符串的下一部分包含您的数据库用户名，如果使用基于密码的身份验证，则还包含您的密码。将 user 的值替换为您的数据库用户名，将 pass 替换为您的密码。如果您使用的是不需要用户名和密码的身份验证机制，请省略连接 URI 中的这一部分。

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

连接字符串的最后一部分指定了连接和身份验证选项。在此示例中，设置了两个连接选项：maxPoolSize=20 和 w=majority。要了解有关连接选项的更多信息，请阅读本指南的连接选项部分。

连接示例

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

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

要指定您的连接 URI，请将其传递给 ApplyURI() 方法，该方法会返回一个新的 ClientOptions 实例。要设置任何其他选项，请从 options 包中调用相关辅助方法。

要了解有关连接选项的更多信息，请参阅“连接选项”部分。要了解有关创建客户端的更多信息，请参阅 API 文档中的客户端和 Connect()。

您可以将 Stable API 版本作为一个选项设置，以避免升级到新的服务器版本时出现破坏性变更 (breaking change)。要了解有关 Stable API 功能的更多信息，请参阅 Stable API 页面。

以下代码展示了如何创建使用 Atlas 连接字符串和 Stable API 版本的客户端、如何连接到 MongoDB 以及如何验证连接是否成功：

// Connects to MongoDB and sets a Stable API version
package main
import (
	"context"
	"fmt"
	"go.mongodb.org/mongo-driver/bson"
	"go.mongodb.org/mongo-driver/mongo"
	"go.mongodb.org/mongo-driver/mongo/options"
)
// Replace the placeholder with your Atlas connection string
const uri = "<connection string>"
func main() {
	// Use the SetServerAPIOptions() method to set the Stable API version to 1
	serverAPI := options.ServerAPI(options.ServerAPIVersion1)
	opts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPI)
	// Create a new client and connect to the server
	client, err := mongo.Connect(context.TODO(), opts)
	if err != nil {
		panic(err)
	}
	defer func() {
		if err = client.Disconnect(context.TODO()); err != nil {
			panic(err)
		}
	}()
	// Send a ping to confirm a successful connection
	var result bson.M
	if err := client.Database("admin").RunCommand(context.TODO(), bson.D{{"ping", 1}}).Decode(&result); err != nil {
		panic(err)
	}
	fmt.Println("Pinged your deployment. You successfully connected to MongoDB!")
}

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

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

1. 下载 MongoDB Server Community 或 Enterprise 版本。

2. 安装并配置 MongoDB Server。

3. 启动该服务器。

在成功启动 MongoDB 服务器后，在驱动程序连接代码中指定连接字符串。

如果 MongoDB Server 在本地运行，您可以使用连接字符串 "mongodb://localhost:<port>"，其中 <port> 是您配置服务器以侦听传入连接的端口号。

如果想要指定其他主机名或 IP 地址，请参阅服务器手册中关于连接字符串的条目。

要测试能否连接到服务器，请在前面的代码示例中将连接字符串替换为 localhost 连接字符串。

连接到副本集

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

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

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

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

• 在给定任一节点的地址时发现所有副本集节点。

• 将操作分派给相应节点，例如，对主节点进行写入的指令。

单一超时设置

您可以通过 SetTimeout() 方法或在连接 URI 字符串中指定 timeoutMS 选项，在 Client 上设置一个单独的 Timeout 选项，以控制执行单个操作所需的时间。如果您没有为针对同一实体的操作设置上下文，则代码中其他位置的 Database、Collection、Session、ChangeStream 和 Bucket 实例将继承 Client 中的 Timeout 选项。

如果您在操作中传递了一个具有截止时间的上下文，驱动程序将使用该上下文的截止时间执行操作。如果上下文没有截止时间，则驱动程序会使用 Client 上设置的 Timeout 选项基于给定上下文派生出新的上下文。

以下代码展示了如何使用 SetTimeout 选项在 Client 上设置 Timeout 选项：

opts := options.Client().SetTimeout(5 * time.Second)

以下示例展示了如何使用 URI 选项设置单个超时并执行继承此设置的操作：

uri := "mongodb://user:pass@sample.host:27017/?timeoutMS=5000"
client := mongo.Connect(context.TODO(), uri)
coll := client.Database("<db>").Collection("<collection>")
...
coll.InsertOne(context.Background(), doc)