MongoDB Go驱动

MongoDB 支持的 Go 驱动程序：

要求

如果使用驱动程序作为依赖，请使用1.10或更高版本。如果自己构建驱动程序，则需要Go 1.17或更高版本。我们的目标是支持Go的最新版本。
MongoDB 2.6及以上版本。

安装

开始使用 MongoDB Go 驱动程序的推荐方法是使用 Go 模块在你的项目中安装该依赖项。这可以通过从go.mongodb.org/mongo-driver 导入软件包并让构建步骤安装该依赖关系来实现，或者通过明确运行：

go get go.mongodb.org/mongo-driver/mongo

当使用不支持模块的Go版本时，可以通过运行dep 来安装驱动：

dep ensure -add "go.mongodb.org/mongo-driver/mongo"

使用方法

要开始使用该驱动，请导入mongo 包并使用Connect 函数创建一个mongo.Client ：

import (
    "context"
    "time"

    "go.mongodb.org/mongo-driver/mongo"
    "go.mongodb.org/mongo-driver/mongo/options"
    "go.mongodb.org/mongo-driver/mongo/readpref"
)

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
client, err := mongo.Connect(ctx, options.Client().ApplyURI("mongodb://localhost:27017"))

确保在实例化你的客户端后推迟对Disconnect 的调用：

defer func() {
    if err = client.Disconnect(ctx); err != nil {
        panic(err)
    }
}()

关于更高级的配置和认证，请参见mongo.Connect的文档。

调用Connect 不会阻止服务器的发现。如果你想知道MongoDB服务器是否已经被发现并连接到，请使用Ping 方法。

ctx, cancel = context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
err = client.Ping(ctx, readpref.Primary())

Client要在一个集合中插入一个文档，首先检索一个Database ，然后从Collection 实例。

collection := client.Database("testing").Collection("numbers")

然后可以使用Collection 实例来插入文档。

ctx, cancel = context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
res, err := collection.InsertOne(ctx, bson.D{{"name", "pi"}, {"value", 3.14159}})
id := res.InsertedID

要使用bson.D ，你需要在你的导入中添加"go.mongodb.org/mongo-driver/bson" 。

你的导入语句现在应该看起来像这样：

import (
    "context"
    "log"
    "time"

    "go.mongodb.org/mongo-driver/bson"
    "go.mongodb.org/mongo-driver/mongo"
    "go.mongodb.org/mongo-driver/mongo/options"
    "go.mongodb.org/mongo-driver/mongo/readpref"
)

有几个查询方法返回一个游标，可以像这样使用：

ctx, cancel = context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
cur, err := collection.Find(ctx, bson.D{})
if err != nil { log.Fatal(err) }
defer cur.Close(ctx)
for cur.Next(ctx) {
    var result bson.D
    err := cur.Decode(&result)
    if err != nil { log.Fatal(err) }
    // do something with result....
}
if err := cur.Err(); err != nil {
    log.Fatal(err)
}

对于返回单个项目的方法，会返回一个SingleResult 实例：

var result struct {
    Value float64
}
filter := bson.D{{"name", "pi"}}
ctx, cancel = context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
err = collection.FindOne(ctx, filter).Decode(&result)
if err == mongo.ErrNoDocuments {
    // Do something when no record was found
    fmt.Println("record does not exist")
} else if err != nil {
    log.Fatal(err)
}
// Do something with result...

更多的例子和文档可以在例子目录下和MongoDB文档网站上找到。

反馈信息

关于驱动程序的帮助，请在MongoDB社区论坛上发表。

新功能和错误可以在jira上报告：https://jira.mongodb.org/browse/GODRIVER

测试/开发

驱动程序的测试可以针对几种数据库配置运行。最简单的配置是一个独立的mongod，没有auth，没有ssl，也没有压缩。要运行这些基本的驱动测试，确保一个独立的MongoDB服务器实例在localhost:27017处运行。为了运行这些测试，你可以运行make （在Windows下，运行nmake ）。这将运行覆盖率，运行go-lint，运行go-vet，并构建示例。

测试不同的拓扑结构

要测试一个副本集或分片集群，可以在make 命令中设置MONGODB_URI="<connection-string>" 。例如，一个名为rs1 的本地副本集由三个节点组成，端口为 27017、27018 和 27019。

MONGODB_URI="mongodb://localhost:27017,localhost:27018,localhost:27019/?replicaSet=rs1" make

测试认证和TLS

要测试认证和TLS，首先要建立一个配置了auth和TLS的MongoDB集群。测试认证需要一个在admin 数据库上具有root 角色的用户。下面是一个命令的例子，它将运行一个正确配置了TLS的mongod进行测试。设置或替换PATH_TO_SERVER_KEY_FILE和PATH_TO_CA_FILE为各自文件的路径。

mongod \
--auth \
--tlsMode requireTLS \
--tlsCertificateKeyFile $PATH_TO_SERVER_KEY_FILE \
--tlsCAFile $PATH_TO_CA_FILE \
--tlsAllowInvalidCertificates

要用make 来运行测试，请设置：

MONGO_GO_DRIVER_CA_FILE 到数据库使用的CA文件的位置
MONGO_GO_DRIVER_KEY_FILE 客户端密钥文件的位置
MONGO_GO_DRIVER_PKCS8_ENCRYPTED_KEY_FILE 到用密码字符串加密的 pkcs8 客户端密钥文件的位置。password
MONGO_GO_DRIVER_PKCS8_UNENCRYPTED_KEY_FILE 到未加密的pkcs8密钥文件的位置
MONGODB_URI 到服务器的连接字符串
AUTH=auth
SSL=ssl

比如说

AUTH=auth SSL=ssl \
MONGO_GO_DRIVER_CA_FILE=$PATH_TO_CA_FILE \
MONGO_GO_DRIVER_KEY_FILE=$PATH_TO_CLIENT_KEY_FILE \
MONGO_GO_DRIVER_PKCS8_ENCRYPTED_KEY_FILE=$PATH_TO_ENCRYPTED_KEY_FILE \
MONGO_GO_DRIVER_PKCS8_UNENCRYPTED_KEY_FILE=$PATH_TO_UNENCRYPTED_KEY_FILE \
MONGODB_URI="mongodb://user:password@localhost:27017/?authSource=admin" \
make

注释：

--tlsAllowInvalidCertificates 标志在服务器上是必需的，这样测试套件才能正常工作。
测试套件要求在 auth 数据库中设置?authSource=admin ，而不是/admin 。

测试压缩

MongoDB Go驱动支持使用Snappy、zLib或zstd进行有线协议压缩。要运行有线协议压缩的测试，将MONGO_GO_DRIVER_COMPRESSOR 设置为snappy,zlib, 或zstd 。比如说。

MONGO_GO_DRIVER_COMPRESSOR=snappy make

如果测试zLib压缩，确保mongod或mongos上的--networkMessageCompressors 标志包括zlib 。

贡献

查看项目页面，了解需要完成的任务。详情见我们的贡献指南。

持续集成

提交到主站的内容会在常青树上自动运行。

感谢和致谢

@ashleymcnamara- Mongo Gopher 艺术作品

许可证

MongoDB Go驱动采用Apache许可协议授权。

MongoDB Go驱动的详细指南