对于 AI 代理：可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。
Docs 菜单
Docs 主页
/ /
连接
Docs 主页
/ /
Kotlin Sync 驱动程序
/
连接
Docs 主页
/
客户端库
/
Kotlin
/
Kotlin Sync 驱动程序
/
连接

指定连接选项

Overview

本节介绍Kotlin同步驱动程序中可用的MongoDB连接和身份验证选项。您可以通过在连接 URI 中或 MongoClientSettings实例中设置选项来配置连接。

在连接 URI 中设置选项

如果将连接 URI 传递给 MongoClient.create() 方法，则可以将连接选项作为 <name>=<value> 对包含在string中。 在以下示例中，连接 URIconnectTimeoutMS 包含值为 的60000 选项和值为tls 的true 选项：

val uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"
val mongoClient = MongoClient.create(uri)

在 MongoClientSettings 中设置选项

您可以使用MongoClientSettings.Builder类中的方法在MongoClientSettings实例中设立连接选项，然后将设置对象传递给MongoClient.create()方法。

以这种方式配置连接可以更轻松地在运行时更改设置，并帮助您在编译时捕获错误。

以下示例展示了如何在创建MongoClientSettings实例时指定连接目标并设立其他选项：

val settings = MongoClientSettings.builder()
    .applyToClusterSettings { builder -> builder.hosts(listOf(ServerAddress("localhost", 27017))) }
    .applyToSocketSettings { builder -> builder.connectTimeout(60000, TimeUnit.MILLISECONDS) }
    .applyToSslSettings { builder -> builder.enabled(true) }
    .build()
 val mongoClient = MongoClient.create(settings)

如果更愿意提供连接string而不是指定主机名和端口，则可以使用 applyConnectionString() 方法，然后使用构建器方法设立其他选项，如以下代码所示：

val uri = "<connection string>"
val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString(uri))
    .applyToSocketSettings { builder -> builder.connectTimeout(60000, TimeUnit.MILLISECONDS) }
    .applyToSslSettings { builder -> builder.enabled(true) }
    .build()
val mongoClient = MongoClient.create(settings)

连接选项

以下部分介绍了Kotlin同步驱动程序中可用的连接选项。每个选项都显示您可以在连接 URI 中使用的选项值对，以及在 MongoClientSettings实例中设立该选项的驱动程序方法（如果可用）。

网络压缩

连接选项
说明

compressors

首选压缩类型（按顺序），用于发送至服务器或从服务器接收的传输协议消息。驱动程序使用服务器支持的第一个压缩类型。

数据类型：逗号分隔的 string
MongoClientSettings：compressorList(listOf(<MongoCompressor>))
连接 URL：compressors=snappy,zstd,zlib

zlibCompressionLevel

要使用的 zlib 压缩级别。此选项接受 -1 到 9 之间的整数值，对应以下设置：

- -1：（默认）。zlib 使用其默认压缩级别（通常为 6 ）。
- 0：无压缩。
- 1：速度最快，但压缩率最低。
- 9：压缩最佳，但速度最慢。

数据类型：整数
默认：-1
MongoClientSettings：compressorList(listOf(zlib.withProperty(MongoCompressor.LEVEL, 3)))
连接 URI：zlibCompressionLevel=3

超时

连接选项
说明

connectTimeoutMS

超时之前尝试连接的时间（以毫秒为单位）。

数据类型：整数
默认：10000
MongoClientSettings：

applyToSocketSettings{ builder ->
    builder.connectTimeout(10, TimeUnit.SECONDS)
}

连接 URI：timeoutMs=10000

socketTimeoutMS （已弃用）

此选项已弃用。您可以通过设置
客户端级别超时
来配置此超时。


在尝试超时之前，在连接上尝试发送或接收的时间（以毫秒为单位）。

数据类型：整数
默认值：无超时
MongoClientSettings：

applyToSocketSettings{ builder ->
    builder.readTimeout(5, TimeUnit.SECONDS)
}

连接 URI：socketTimeoutMS=5000

服务器选择

连接选项
说明

serverSelectionTimeoutMS

驱动程序在抛出异常之前等待服务器选择成功的最长时间（以毫秒为单位）。

数据类型：整数
默认：30000
MongoClientSettings：

applyToClusterSettings{ builder ->
    builder.serverSelectionTimeout(30, TimeUnit.SECONDS)
}

连接 URI：serverSelectionTimeoutMS=30000

身份验证

提示

要学习；了解有关身份验证选项的更多信息，请参阅身份验证机制部分。

连接选项
说明

authMechanism

Kotlin 同步驱动程序用于验证应用程序的机制。

数据类型：string
默认值：连接到 MongoDB v4.0 或更高版本时为 "SCRAM-SHA-256"
MongoClientSettings：

credential(
    MongoCredential.createScramSha256Credential(...)
)

连接 URI：authMechanism=SCRAM-SHA-256

authMechanismProperties

针对身份验证机制的选项。此选项并非所有身份验证机制都需要。

数据类型：string
连接 URI：authMechanismProperties=AWS_SESSION_TOKEN:12435

authSource

要认证的数据库。

数据类型：string
默认："admin"
连接 URI：authSource=admin

用户名

用于身份验证的用户名。当此选项包含在连接 URI 中时，必须对其进行百分比编码。

数据类型：string
连接 URI：username=my+user

密码

用于身份验证的密码。当此选项包含在连接 URI 中时，必须对其进行百分比编码。

数据类型：string
连接 URI：password=strong+password

读取和写入操作

要学习；了解有关连接到不同类型MongoDB部署的更多信息，请参阅选择连接目标指南。

连接选项
说明

replicaSet

指定要连接到的副本集的名称。

数据类型：string
连接 URI：replicaSet=myRS

directConnection

是否仅连接到副本集的主节点。

数据类型：布尔值
默认值：false
MongoClientSettings：

applyToClusterSettings{ builder ->
    builder.mode(ClusterConnectionMode.SINGLE)
}

连接 URI：directConnection=true

readPreference

指定客户端的读取偏好。有关读取偏好的更多信息，请参阅服务器手册中的读取偏好（read preference）。

数据类型：string
默认：primary
MongoClientSettings：readPreference(ReadPreference.primary())
连接 URI：readPreference=primary

事务外的

指定客户端的读关注（read concern）。有关读关注（read concern）的更多信息，请参阅服务器手册中的读关注（read concern）。

数据类型：string
MongoClientSettings：readConcern(ReadConcern.MAJORITY)
连接 URI：readConcern=majority

writeConcern

指定客户端的写关注（write concern）。有关写关注（write concern）的更多信息，请参阅服务器手册中的写关注。

数据类型：string
MongoClientSettings：writeConcern(WriteConcern.MAJORITY)
连接 URI：writeConcern=majority

localThresholdMS

副本集节点资格的延迟窗口。如果节点的往返网络探测（ping）时间超过最快服务器的往返网络探测（ping）时间加上此值，则该服务器没有资格被选中。

数据类型：整数
默认：15
MongoClientSettings：

applyToClusterSettings{ builder ->
    builder.localThreshold(35, TimeUnit.MILLISECONDS)
}

连接 URI：localThresholdMS=35

更多信息

要查看连接选项的完整列表，请参阅服务器手册中的连接字符串。

API 文档

要学习；了解有关本指南中提到的类和方法的更多信息，请参阅以下API文档：

后退

选择连接目标

来年

网络压缩