对于 AI 代理：可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。
Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
MongoDB Branding Shape
Click here >
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



按顺序排列的首选压缩类型，适用于发送到服务器接收的线协议消息。驾驶员使用服务器支持的第一种压缩类型。数据类型：逗号分隔的字符串
MongoClientSettings: compressorList(listOf(<MongoCompressor>))
连接 URI:compressors=snappy,zstd,zlib

zlibCompressionLevel

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

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


-1
compressorList(listOf(zlib.withProperty(MongoCompressor.LEVEL, 3)))
默认值： MongoClientSettings: 连接 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 Sync驾驶员用于对应用程序进行身份验证的机制。数据类型：字符串


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

credential(
    MongoCredential.createScramSha256Credential(...)
)

连接 URI：authMechanism=SCRAM-SHA-256

authMechanismProperties

特定于身份验证机制的选项。并非所有身份验证机制都需要此选项。数据类型：字符串连接


URI：authMechanismProperties=AWS_SESSION_TOKEN:12435

authSource



要进行身份验证的数据库。数据类型：字符串
默认值："admin"
连接 URI：authSource=admin

用户名

用于身份验证的用户名。当此选项包含在连接 URI 中时，您必须对其进行百分比编码。数据类型：字符串


连接 URI：username=my+user

密码

用于身份验证的密码。当此选项包含在连接 URI 中时，您必须对其进行百分比编码。数据类型：字符串


连接 URI：password=strong+password

读取和写入操作

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

连接选项
说明

replicaSet

指定要连接到的副本集的名称。数据类型：字符串


连接 URI：replicaSet=myRS

directConnection

是否仅连接到副本集的主节点 (primary node in the replica set)节点。数据类型：布尔值


默认值：false
MongoClientSettings:

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

连接 URI：directConnection=true

readPreference

指定客户端的读取偏好（read preference）。有关更多信息，请参阅服务器手册中的读取偏好。数据类型：字符串


primary
readPreference(ReadPreference.primary())
默认值： MongoClientSettings: 连接 URI:readPreference=primary

事务外的

指定客户端的读关注（read concern）。有关更多信息，请参阅服务器手册中的读关注。数据类型：字符串


MongoClientSettings： readConcern(ReadConcern.MAJORITY)
连接 URI：readConcern=majority

writeConcern

指定客户端的写关注（write concern）。有关详细信息，请参阅服务器手册中的“写关注”。数据类型：字符串


MongoClientSettings： writeConcern(WriteConcern.MAJORITY)
连接 URI：writeConcern=majority

localThresholdMS

副本集成员资格的延迟窗口。如果成员的往返网络探测（ping）时间比最快服务器的往返网络探测（ping）时间加上此值还要长，则该服务器没有资格参与选择。数据类型：整数


默认值：15
MongoClientSettings:

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

连接 URI：localThresholdMS=35

更多信息

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

API 文档

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

后退

选择连接目标

来年

网络压缩