指定连接选项

Overview

本页介绍了Scala驾驶员中可用的MongoDB连接和身份验证选项，并解释了如何为MongoDB连接指定这些选项。

在连接 URI 中设置选项

如果将连接 URI 传递给 MongoClient() 构造函数，则可以将连接选项作为 <name>=<value> 对包含在字符串中。在以下示例中，连接 URI 包含值为 60000 的 connectTimeoutMS 选项和值为 true 的 tls 选项：

val uri = "mongodb://localhost:27017/?connectTimeoutMS=60000&tls=true"
val mongoClient = MongoClient(uri)

在 MongoClientSettings 中设置选项

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

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

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

val settings = MongoClientSettings.builder()
    .applyToClusterSettings(builder =>
        builder.hosts(List(new ServerAddress("localhost", 27017)).asJava))
    .applyToSocketSettings(builder =>
        builder.connectTimeout(60000, TimeUnit.MILLISECONDS))
    .applyToSslSettings(builder => builder.enabled(true))
    .build()
val mongoClient = MongoClient(settings)

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

val uri = "mongodb://localhost:27017/"
val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString(uri))
    .applyToSocketSettings(builder =>
        builder.connectTimeout(60000, TimeUnit.MILLISECONDS))
    .applyToSslSettings(builder => builder.enabled(true))
    .build()
val mongoClient = MongoClient(settings)

网络压缩

compressors

首选压缩类型（按顺序），用于发送到服务器或从服务器接收的传输协议消息。您可以将“snappy”、“zlib”和“zstd”作为可选的构建时依赖项启用。驱动程序使用服务器支持的第一种压缩类型。

数据类型：逗号分隔的string

默认值： null

示例：

val uri = "mongodb://localhost:27017/?compressors=snappy,zstd,zlib"
val mongoClient = MongoClient(uri)

zlibCompressionLevel

zlib要使用的压缩级别。此选项接受 -1 和 9 之间的整数值：

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

数据类型： integer

默认值： -1

示例：

val uri = "mongodb://localhost:27017/?compressors=zlib&zlibCompressionLevel=3"
val mongoClient = MongoClient(uri)

compressors

数据类型： List[MongoCompressor]

默认值：空列表

示例：

val settings = MongoClientSettings.builder()
    .compressorList(List(
        MongoCompressor.createSnappyCompressor(),
        MongoCompressor.createZstdCompressor(),
        MongoCompressor.createZlibCompressor()
    ).asJava)
    .build()
val mongoClient = MongoClient(settings)

zlibCompressionLevel

zlib要使用的压缩级别。此选项接受 -1 和 9 之间的整数值：

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

数据类型： integer

默认值： -1

示例：

val settings = MongoClientSettings.builder()
    .compressorList(List(
        MongoCompressor.createZlibCompressor()
            .withProperty(MongoCompressor.LEVEL, 3)
    ).asJava)
    .build()
val mongoClient = MongoClient(settings)

超时

connectTimeoutMS

驱动程序在超时前尝试与服务器建立单个 TCP 套接字连接的时间长度。

数据类型： integer

默认值： 10000

示例：

val uri = "mongodb://localhost:27017/?connectTimeoutMS=10000"
val mongoClient = MongoClient(uri)

socketTimeoutMS（已弃用）

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

驱动程序在超时之前尝试在套接字上发送或接收的时间长度。默认值由操作系统设立。

数据类型： integer

默认值：无超时

示例：

val uri = "mongodb://localhost:27017/?socketTimeoutMS=5000"
val mongoClient = MongoClient(uri)

connectTimeoutMS

驱动程序在超时前尝试与服务器建立单个 TCP 套接字连接的时间长度。

数据类型： integer

默认值： 10000

示例：

val settings = MongoClientSettings.builder()
    .applyToSocketSettings(builder =>
        builder.connectTimeout(10, TimeUnit.SECONDS))
    .build()
val mongoClient = MongoClient(settings)

socketTimeoutMS（已弃用）

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

驱动程序在超时之前尝试在套接字上发送或接收的时间长度。默认值由操作系统设立。

数据类型： integer

默认值：无超时

示例：

val settings = MongoClientSettings.builder()
    .applyToSocketSettings(builder =>
        builder.readTimeout(5, TimeUnit.SECONDS))
    .build()
val mongoClient = MongoClient(settings)

服务器选择

serverSelectionTimeoutMS

驱动程序在超时之前尝试选择服务器的时间长度。

数据类型： integer

默认值： 30000

示例：

val uri = "mongodb://localhost:27017/?serverSelectionTimeoutMS=30000"
val mongoClient = MongoClient(uri)

serverSelectionTimeoutMS

驱动程序在超时之前尝试选择服务器的时间长度。

数据类型： integer

默认值： 30000

示例：

val settings = MongoClientSettings.builder()
    .applyToClusterSettings(builder =>
        builder.serverSelectionTimeout(30, TimeUnit.SECONDS))
    .build()
val mongoClient = MongoClient(settings)

身份验证

提示

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

authMechanism

驱动程序用于向 MongoDB Server 进行身份验证的机制。如果您未指定身份验证机制，驱动程序将使用 SCRAM-SHA-1 或 SCRAM-SHA-256，具体取决于服务器版本。

数据类型： string

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

示例：

val uri = "mongodb://<username>:<password>@localhost:27017/?authMechanism=SCRAM-SHA-256"
val mongoClient = MongoClient(uri)

authMechanismProperties

特定于身份验证机制的选项。并非所有身份验证机制都需要。

数据类型： string

示例：

val uri = "mongodb://localhost:27017/?authMechanismProperties=AWS_SESSION_TOKEN:12435"
val mongoClient = MongoClient(uri)

authSource

要进行身份验证的数据库。

数据类型： string

默认值： "admin"

示例：

val uri = "mongodb://<username>:<password>@localhost:27017/?authSource=admin"
val mongoClient = MongoClient(uri)

用户名

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

数据类型： string

示例：

val uri = "mongodb://myUser:<password>@localhost:27017/"
val mongoClient = MongoClient(uri)

密码

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

数据类型： string

示例：

val uri = "mongodb://<username>:myPassword@localhost:27017/"
val mongoClient = MongoClient(uri)

authMechanism

驱动程序用于向 MongoDB Server 进行身份验证的机制。如果您未指定身份验证机制，驱动程序将使用 SCRAM-SHA-1 或 SCRAM-SHA-256，具体取决于服务器版本。

数据类型： string

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

示例：

val settings = MongoClientSettings.builder()
    .credential(MongoCredential.createScramSha256Credential(
        "<username>", "<authSource>", "<password>".toCharArray))
    .build()
val mongoClient = MongoClient(settings)

注意

要在中配置用户名、密码、身份验证源和特定于机制的属性，请使用相应的MongoClientSettings MongoCredential工厂方法。要学习；了解更多信息，请参阅身份验证机制指南。

读取和写入操作

replicaSet

要连接的副本集的名称。

数据类型： string

示例：

val uri = "mongodb://localhost:27017/?replicaSet=myRS"
val mongoClient = MongoClient(uri)

directConnection

指定是否强制将所有操作分派到托管。如果指定此选项，驱动程序将不接受 SRV 连接格式。必须使用标准连接 URI 格式。要了解有关 SRV 连接和标准连接格式的更多信息，请参阅 MongoDB Server 手册中的连接字符串指南。

如果指定多个托管名，则必须将此属性设立为 false。

数据类型： boolean

默认值： false

示例：

val uri = "mongodb://localhost:27017/?directConnection=true"
val mongoClient = MongoClient(uri)

readPreference

客户端的默认读取偏好（read preference）设置。有关详细信息，请参阅 MongoDB Server 手册中的读取偏好（read preference）。

数据类型： string

默认值： primary

示例：

val uri = "mongodb://localhost:27017/?readPreference=primary"
val mongoClient = MongoClient(uri)

事务外的

客户端的读关注（read concern）。有关更多信息，请参阅MongoDB Server手册中的读关注。

数据类型： string

示例：

val uri = "mongodb://localhost:27017/?readConcern=majority"
val mongoClient = MongoClient(uri)

writeConcern

客户端的写关注（write concern）。有关更多信息，请参阅MongoDB Server手册中的写关注。

数据类型： string

示例：

val uri = "mongodb://localhost:27017/?writeConcern=majority"
val mongoClient = MongoClient(uri)

localThresholdMS

服务器资格的延迟窗口。如果服务器的往返时间长于最快服务器的往返时间加上此值，则该服务器没有资格被选中。

数据类型： integer

默认值： 15

示例：

val uri = "mongodb://localhost:27017/?localThresholdMS=35"
val mongoClient = MongoClient(uri)

replicaSet

要连接的副本集的名称。

数据类型： string

示例：

val settings = MongoClientSettings.builder()
    .applyToClusterSettings(builder =>
        builder.requiredReplicaSetName("myRS"))
    .build()
val mongoClient = MongoClient(settings)

directConnection

如果指定多个托管名，则必须将此属性设立为 false。

数据类型： boolean

默认值： false

示例：

val settings = MongoClientSettings.builder()
    .applyToClusterSettings(builder =>
        builder.mode(ClusterConnectionMode.SINGLE))
    .build()
val mongoClient = MongoClient(settings)

readPreference

客户端的默认读取偏好（read preference）设置。有关详细信息，请参阅 MongoDB Server 手册中的读取偏好（read preference）。

数据类型： string

默认值： primary

示例：

val settings = MongoClientSettings.builder()
    .readPreference(ReadPreference.primary())
    .build()
val mongoClient = MongoClient(settings)

事务外的

客户端的读关注（read concern）。有关更多信息，请参阅MongoDB Server手册中的读关注。

数据类型： string

示例：

val settings = MongoClientSettings.builder()
    .readConcern(ReadConcern.MAJORITY)
    .build()
val mongoClient = MongoClient(settings)

writeConcern

客户端的写关注（write concern）。有关更多信息，请参阅MongoDB Server手册中的写关注。

数据类型： string

示例：

val settings = MongoClientSettings.builder()
    .writeConcern(WriteConcern.MAJORITY)
    .build()
val mongoClient = MongoClient(settings)

localThresholdMS

服务器资格的延迟窗口。如果服务器的往返时间长于最快服务器的往返时间加上此值，则该服务器没有资格被选中。

数据类型： integer

默认值： 15

示例：

val settings = MongoClientSettings.builder()
    .applyToClusterSettings(builder =>
        builder.localThreshold(35, TimeUnit.MILLISECONDS))
    .build()
val mongoClient = MongoClient(settings)

指定连接选项

Overview

在连接 URI 中设置选项

在 MongoClientSettings 中设置选项

网络压缩

compressors

zlibCompressionLevel

compressors

zlibCompressionLevel

超时

connectTimeoutMS

socketTimeoutMS（已弃用）

connectTimeoutMS

socketTimeoutMS（已弃用）

服务器选择

serverSelectionTimeoutMS

serverSelectionTimeoutMS

身份验证

提示

authMechanism

authMechanismProperties

authSource

用户名

密码

authMechanism

注意

读取和写入操作

replicaSet

directConnection

readPreference

事务外的

writeConcern

localThresholdMS

replicaSet

directConnection

readPreference

事务外的

writeConcern

localThresholdMS

更多信息

API 文档