连接字符串选项

本页内容

副本集选项
连接选项
TLS选项
超时选项
压缩选项
连接池选项
写关注选项
读关注选项
读取偏好选项
身份验证选项
服务器选择和发现选项
杂项配置

本页列出了所有SRV连接字符串和标准连接字符串的连接选项。

以下形式的选项是成对出现的名称=值.

在驱动程序中使用时，选项名称不区分大小写。
在mongosh中使用时，选项名称不区分大小写。mongosh.
值始终区分大小写。

使用连字符（&）字符分隔选项，形式为name1=value1&name2=value2。在以下示例中，连接包含replicaSet和connectTimeoutMS选项

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db1.example.net:27017,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000

注意

连接字符串参数的分号分隔符

为了提供向后兼容性，当前驱动程序接受分号（;）作为选项分隔符。

副本集选项

以下连接字符串连接到名为myRepl的副本集，成员运行在指定的主机上。它使用用户名myDatabaseUser和密码D1fficultP%40ssw0rd进行身份验证。

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com:27017,db1.example.com:27017,db2.example.com:27017/?replicaSet=myRepl

连接选项	描述
`replicaSet`	指定replica set的名称，如果`mongod`是副本集的成员。设置`replicaSet`连接选项以确保驱动程序之间的一致性。连接到副本集时，向uri的`host[:port]`组件提供副本集成员的种子列表。具体细节请参阅您的驱动程序文档。
`directConnection`	指定客户端是否直接连接到连接URI中的`host[:port]` `true`：客户端仅向指定的主机发送操作。它不会尝试发现副本集的任何其他成员。 `false`：客户端尝试发现副本集中的所有服务器，并向主成员发送操作。这是默认值。

连接选项

TLS选项

以下连接字符串到副本集包含 tls=true 选项。使用用户 myDatabaseUser 和密码 D1fficultP%40ssw0rd 进行身份验证。

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&tls=true

或者，您也可以使用等效的 ssl=true 选项

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&ssl=true

连接选项	描述
`tls`	启用或禁用连接的TLS/SSL `true`：使用TLS/SSL初始化连接。SRV连接格式的默认值。 `false`：不使用TLS/SSL启动连接。这是标准连接字符串格式的默认值。 `tls`选项等同于`ssl`选项。如果`mongosh` shell从命令行指定了额外的tls/ssl选项，请使用`--tls`命令行选项。
`ssl`	一个布尔值，用于启用或禁用连接的TLS/SSL。 `true`：使用TLS/SSL初始化连接。SRV连接格式的默认值。 `false`：不使用TLS/SSL启动连接。这是标准连接字符串格式的默认值。 `ssl`选项等同于`tls`选项。如果`mongosh` shell从命令行指定了额外的tls/ssl选项，请使用`--ssl`命令行选项。
`tlsCertificateKeyFile`	指定包含客户端TLS/SSL X.509证书或客户端TLS/SSL证书和密钥的本地`.pem`文件的位置。客户端将此文件呈现给`mongod` / `mongos`实例。 `mongod` / `mongos`在连接时如果呈现的X.509证书在`mongod/mongos`主机系统时间的30天内过期，则记录警告。此选项不是所有驱动程序都支持。请参阅驱动程序文档。此连接字符串选项在mongo shell中不可用。请使用命令行选项。
`tlsCertificateKeyFilePassword`	指定解密`tlsCertificateKeyFile`.的密码。此选项不是所有驱动程序都支持。请参阅驱动程序文档。此连接字符串选项在mongo shell中不可用。请使用命令行选项。
`tlsCAFile`	指定包含证书颁发机构根证书链的本地`.pem`文件的位置。该文件用于验证`mongod` / `mongos`实例提供的证书。此选项不是所有驱动程序都支持。请参阅驱动程序文档。此连接字符串选项在mongo shell中不可用。请使用命令行选项。
`tlsAllowInvalidCertificates`	绕过由 `mongod` / `mongos` 实例提供的证书验证。设置为 `true`，即使服务器提供的证书无效，也可以连接到 MongoDB 实例。此选项不是所有驱动程序都支持。请参阅驱动程序文档。此连接字符串选项在mongo shell中不可用。请使用命令行选项。警告：禁用证书验证会创建漏洞。
`tlsAllowInvalidHostnames`	禁用由 `mongod` / `mongos` 实例提供的证书的域名验证。设置为 `true`，即使服务器证书中的域名与服务器主机不匹配，也可以连接到 MongoDB 实例。此选项不是所有驱动程序都支持。请参阅驱动程序文档。此连接字符串选项在mongo shell中不可用。请使用命令行选项。警告：禁用证书验证会创建漏洞。
`tlsInsecure`	禁用各种证书验证。设置为 `true` 以禁用证书验证。具体禁用的验证方式因驱动程序而异。请参阅驱动程序文档。此连接字符串选项在mongo shell中不可用。请使用命令行选项。警告：禁用证书验证会创建漏洞。

超时选项

连接选项	描述
`connectTimeoutMS`	在超时之前尝试连接的时间（以毫秒为单位）。默认值为 10,000 毫秒，但特定驱动程序可能有所不同。有关详细信息，请参阅驱动程序文档。
`socketTimeoutMS`	在套接字尝试发送或接收之前超时的时间（以毫秒为单位）。默认情况下，永远不会超时，但不同的驱动程序可能会有所不同。请参阅驱动程序文档。

压缩选项

连接选项

描述

compressors

以逗号分隔的压缩程序字符串，用于启用此客户端与mongod / mongos实例之间的网络压缩。

可以指定以下压缩程序

如果指定了多个压缩程序，则压缩程序列表的顺序以及通信发起者也很重要。例如，如果客户端指定以下网络压缩程序 "zlib,snappy"，而mongod指定 "snappy,zlib"，则客户端和mongod之间的消息使用 zlib。

当双方都启用网络压缩时，消息会被压缩。否则，双方之间的消息将不会被压缩。

如果双方没有共享至少一个共同的压缩程序，则双方之间的消息将不会被压缩。

mongosh支持uri连接字符串选项compressors。

zlibCompressionLevel

一个整数，用于指定使用 zlib 进行 网络压缩 时的压缩级别。

可以指定从 -1 到 9 的整数值

值	注释
`-1`	默认压缩级别，通常是 `6` 级压缩。
`0`	无压缩
`1` - `9`	增加压缩级别，但会以速度为代价，其中 `1` 提供最佳速度但压缩最少，而 `9` 提供最佳压缩但速度最慢。

由 mongosh 支持。

连接池选项

大多数驱动程序实现了一些连接池处理。一些驱动程序不支持连接池。有关连接池实现的更多信息，请参阅您的驱动程序文档。这些选项允许应用程序在连接到 MongoDB 部署时配置连接池。

连接选项	描述
`maxPoolSize`	连接池中的最大连接数。默认值是 `100`。
`minPoolSize`	连接池中的最小连接数。默认值是 `0`。 `minPoolSize` 选项并非所有驱动程序都支持。有关您驱动程序的详细信息，请参阅驱动程序文档。
`maxConnecting`	连接池可能同时建立的最大连接数。默认值是 `2`。 `maxConnecting` 被所有驱动程序支持，除了Rust 驱动程序。增加 `maxConnecting` 的值可以使客户端更快地连接到服务器，但会增加连接风暴的机会。如果 `maxConnecting` 的值太低，您的连接池可能会遇到严重的节流和客户端获取连接时的尾部延迟增加。
`maxIdleTimeMS`	连接在池中保持空闲状态的最大毫秒数，在此之后将被移除并关闭。并非所有驱动程序都支持此选项。
`waitQueueMultiple`	驱动程序将此数值乘以 `maxPoolSize` 的值，以提供最大线程数，允许线程等待连接从池中可用。有关默认值，请参阅驱动程序文档。并非所有驱动程序都支持此选项。
`waitQueueTimeoutMS`	线程等待连接变为可用的最大时间（以毫秒为单位）。有关默认值，请参阅驱动程序文档。并非所有驱动程序都支持此选项。

写入关注选项

写入关注描述了从MongoDB请求的确认级别。写入关注选项由以下驱动程序支持：

您可以在连接字符串和insert或update等方法的参数中指定写入关注。如果两个地方都指定了写入关注，则方法参数将覆盖连接字符串设置。

MongoDB Atlas 部署的连接字符串默认使用"majority"。如果您没有为 MongoDB Atlas 部署指定写入关注，MongoDB Atlas 将强制使用"majority"。

以下连接字符串指定了副本集的"majority"写入关注和5秒超时，使用wtimeoutMS写入关注参数：

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&w=majority&wtimeoutMS=5000

连接选项	描述
`w`	对应于写入关注`w`选项。该`w`选项请求确认写入操作已传播到指定数量的`mongod`实例或带有指定标签的`mongod`实例。您可以使用一个`数字`，字符串`majority`或`标签集`。有关详细信息，请参阅`w`选项。
`wtimeoutMS`	对应于写入关注度 `wtimeout`。 `wtimeoutMS` 指定了写入关注度的超时时间，单位为毫秒。当 `wtimeoutMS` 为 `0` 时，写入操作将不会超时。有关更多信息，请参阅 `wtimeout`。
`journal`	对应于写入关注度 `j` 选项。选项 `journal` 要求 MongoDB 确认写入操作已写入日志。有关详细信息，请参阅 `j` 选项。如果将 `journal` 设置为 `true`，并指定小于 1 的 `w` 值，则 `journal` 优先。

有关更多信息，请参阅写入关注度。

读取关注选项

对于WiredTiger存储引擎，MongoDB为副本集和副本集分片引入了readConcern选项。

读取关注允许客户端从副本集选择一个隔离级别进行读取。

以下连接到副本集的连接字符串指定了readConcernLevel=majority:

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readConcernLevel=majority

连接选项	描述
`readConcernLevel`	隔离级别。可以接受以下值之一 `local` `majority` `linearizable` `available` 此连接字符串选项在`mongosh`中不可用。指定读取关注作为特定操作的选项。

有关更多信息，请参阅读取关注。

读取优先级选项

读取偏好描述了读取操作相对于副本集的行为。这些参数允许您在连接字符串中按连接指定读取偏好。

例如

以下副本集的连接字符串指定了secondary读取偏好模式以及120秒的maxStalenessSeconds值。
```
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readPreference=secondary&maxStalenessSeconds=120
```
以下分片集群的连接字符串指定了secondary读取偏好模式以及120秒的maxStalenessSeconds值。
```
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongos1.example.com,mongos2.example.com/?readPreference=secondary&maxStalenessSeconds=120
```
以下分片集群的连接字符串指定了secondary读取偏好模式以及三个readPreferenceTags:
```
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongos1.example.com,mongos2.example.com/?readPreference=secondary&readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=dc:ny&readPreferenceTags=
```

当使用多个readPreferenceTags时，顺序很重要。尝试按顺序使用readPreferenceTags，直到找到匹配项。找到后，使用该指定来查找所有合格的匹配成员，并且忽略任何剩余的readPreferenceTags。有关详细信息，请参阅标签匹配顺序。

连接选项	描述
`readPreference`	指定此连接的读取偏好。可能的值包括 `primary`（默认值） `primaryPreferred` `secondary` `secondaryPreferred` `nearest` 包含读取操作的分布式事务必须使用读取偏好`primary`。给定事务中的所有操作都必须路由到同一成员。此连接字符串选项对`mongo` shell不可用。请参阅`cursor.readPref()`和`Mongo.setReadPref()`。
`maxStalenessSeconds`	指定在客户端停止使用副本进行读操作之前，副本可以有多少秒的过时性。有关详细信息，请参阅读优先级 `maxStalenessSeconds`。默认情况下，没有最大过时性，客户端在选择将读操作定向到何处时不会考虑副本的延迟。最小 `maxStalenessSeconds` 值为 90 秒。指定介于 0 和 90 秒之间的值将产生错误。MongoDB 驱动程序将 `maxStalenessSeconds` 的值 `-1` 视为“没有最大过时性”，与省略 `maxStalenessSeconds` 相同。
`readPreferenceTags`	指定标签文档作为逗号分隔的冒号分隔键值对列表。例如，要指定标签文档 `{ "dc": "ny", "rack": "r1" }`，在连接字符串中使用 `readPreferenceTags=dc:ny,rack:r1`。要指定空标签文档 `{ }`，使用 `readPreferenceTags=` 而不设置值。要指定列表的标签文档，使用多个 `readPreferenceTags`。例如，`readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=`。在多个 `readPreferenceTags` 使用时，顺序很重要。会按照顺序尝试 `readPreferenceTags`，直到找到匹配项。有关详细信息，请参阅标签匹配顺序。此连接字符串选项对`mongo` shell不可用。请参阅`cursor.readPref()`和`Mongo.setReadPref()`。

更多信息请参阅读取偏好。

身份验证选项

以下连接字符串到副本集指定了 authSource 到 admin 数据库。也就是说，用户凭据是在 admin 数据库上验证的。

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?replicaSet=myRepl&authSource=admin

如果用户名或密码包含以下字符，则必须使用百分编码：

$ : / ? # [ ] @

连接选项

描述

authSource

指定与用户凭证关联的数据库名称。如果未指定 authSource，则默认为连接字符串中指定的 defaultauthdb。如果未指定 defaultauthdb，则默认为 admin。

PLAIN (LDAP)、GSSAPI (Kerberos) 和 MONGODB-AWS (IAM) 身份验证机制需要将 authSource 设置为 $external，因为这些机制将凭证存储委托给外部服务。

如果没有提供用户名，无论是通过连接字符串还是通过 --username 参数，MongoDB 将忽略 authSource 的值。

authMechanism

默认：SCRAM-SHA-256

指定 MongoDB 用于连接身份验证的认证机制。如果您不指定 authMechanism 但提供了用户凭证，MongoDB 将尝试使用 SCRAM-SHA-256。如果失败，则回退到 SCRAM-SHA-1。

SCRAM-SHA-1
SCRAM-SHA-256
MONGODB-X509
MONGODB-AWS
GSSAPI (Kerberos)
PLAIN (LDAP SASL)
MONGODB-OIDC (OpenID Connect OIDC)。要使用 MONGODB-OIDC，您必须
- 设置 authMechanismProperties ENVIRONMENT 环境变量。
- 将 OIDC 回调提供给客户端构造函数。

只有 MongoDB 企业版 mongod 和 mongos 实例提供 GSSAPI（Kerberos）和 PLAIN（LDAP）机制。

要使用 MONGODB-X509，您必须启用 TLS/SSL。

要使用 MONGODB-AWS，您必须连接到已配置为通过 MongoDB Atlas 集群，该集群支持通过 AWS IAM 凭据进行身份验证（一个 AWS 访问密钥 ID 和一个秘密访问密钥，以及可选的 AWS 会话令牌）。MONGODB-AWS 身份验证机制要求将 authSource 设置为 $external。

在使用 MONGODB-AWS 时，请将 AWS 访问密钥 ID 作为用户名，将秘密访问密钥作为密码。如果使用 AWS 会话令牌，也请提供相应的 AWS_SESSION_TOKEN，并将其添加到 authMechanismProperties 值中。

如果 AWS 访问密钥 ID、秘密访问密钥或会话令牌包含以下字符，则必须使用百分编码

$ : / ? # [ ] @

或者，如果 AWS 访问密钥 ID、秘密访问密钥或会话令牌已在您的平台使用相应的 AWS IAM 环境变量定义，mongosh 将使用这些环境变量值进行身份验证；您不需要在连接字符串中指定它们。

请参阅连接到 Atlas 集群以了解使用连接字符串和环境变量方法使用 MONGODB-AWS 身份验证机制的示例。

请参阅自管理部署中的身份验证以获取有关MongoDB中身份验证系统的更多信息。还请考虑在自管理部署中使用x.509证书进行客户端身份验证以获取有关x509身份验证的更多信息。

authMechanismProperties

指定authMechanism的属性，以冒号分隔的键值对列表形式。

可能的键值对有

SERVICE_NAME:

设置连接到Kerberos MongoDB实例时的Kerberos服务名称。此值必须与您连接的MongoDB实例上设置的服务名称匹配。仅当使用GSSAPI身份验证机制时有效。

SERVICE_NAME对所有客户端和MongoDB实例默认为mongodb。如果您更改MongoDB实例上的saslServiceName设置，则必须设置SERVICE_NAME以匹配该设置。仅当使用GSSAPI身份验证机制时有效。

CANONICALIZE_HOST_NAME:true|false

连接到Kerberos服务器时，规范客户端主机机的主机名。当主机报告的主机名与Kerberos数据库中的不同时，可能需要此操作。默认为false。仅当使用GSSAPI身份验证机制时有效。

SERVICE_REALM:

设置MongoDB服务的Kerberos领域。这可能对于支持跨领域身份验证是必要的，其中用户存在于一个领域中，而服务存在于另一个领域中。仅当使用GSSAPI身份验证机制时有效。

AWS_SESSION_TOKEN:

在执行AssumeRole 请求时，或者当与Lambda等指定此值的AWS资源一起工作时，设置AWS会话令牌以使用临时凭证进行身份验证。仅在使用 MONGODB-AWS 身份验证机制时有效。您还必须拥有AWS访问密钥ID和密钥。例如，请参阅连接到Atlas集群。

环境：<string>

设置OpenID Connect (OIDC) 环境。

对于Microsoft Azure，设置 ENVIRONMENT:azure
对于Google Cloud Platform，设置 ENVIRONMENT:gcp

您还必须将 authMechanism 设置为 MONGODB-OIDC。

gssapiServiceName

设置连接到Kerberized MongoDB实例时的Kerberos服务名称。此值必须与您连接的MongoDB实例上设置的服务名称匹配。

gssapiServiceName 默认对所有客户端和MongoDB实例为 mongodb。如果您更改MongoDB实例上的 saslServiceName 设置，您必须将 gssapiServiceName 设置为与之匹配。

gssapiServiceName 是 authMechanismProperties=SERVICE_NAME:mongodb 的过时别名。有关您驱动程序支持哪些选项及其相对优先级的更多信息，请参考您首选驱动程序版本的文档。

服务器选择和发现选项

MongoDB提供了以下选项来配置MongoDB驱动程序和mongos实例如何选择要将其读或写操作定向到的服务器。

连接选项	描述
`localThresholdMS`	选择多个合适的MongoDB实例时的延迟窗口大小（以毫秒为单位）。默认值：15毫秒。所有驱动程序都使用`localThresholdMS`。当指定`mongos`的延迟窗口大小时，请使用`localThreshold`别名。
`serverSelectionTimeoutMS`	指定在抛出异常之前阻塞服务器选择的时间（以毫秒为单位）。默认值：30,000毫秒。
`serverSelectionTryOnce`	仅适用于单线程驱动程序。当设置为 `true` 时，指示驱动程序在服务器选择失败后仅扫描 MongoDB 部署一次，然后选择服务器或引发错误。当设置为 `false` 时，驱动程序将阻塞并搜索服务器，直到达到 `serverSelectionTimeoutMS` 值。默认值：`true`。多线程驱动程序和 `mongos` 不支持 `serverSelectionTryOnce`。
`heartbeatFrequencyMS`	`heartbeatFrequencyMS` 控制驱动程序检查 MongoDB 部署状态的时间。指定两次检查之间的间隔（以毫秒为单位），从上一次检查结束到下一次检查开始。默认值: 单线程驱动程序：60 秒。多线程驱动程序：10 秒。 `mongos` 不支持更改心跳检查的频率。
`socketCheckIntervalMS`	仅单线程客户端。控制客户端检查MongoDB部署的TCP连接状态的频率。指定较低的值，客户端可以更快地检测到网络问题，但会消耗更多CPU资源。默认：5秒。此选项不是所有驱动程序都支持。请参阅驱动程序文档。

其他配置

连接选项	描述
`appName`	指定自定义应用名称。应用名称会在 `mongod` 和 `mongos` 日志的 `currentOp.appName` 字段中显示，在 `currentOp` 命令和 `db.currentOp()` 方法输出中的 `system.profile.appName` 字段中显示，在数据库分析器输出中从MongoDB驱动程序中可用 `appName` 连接选项。 MongoDB驱动程序 `mongosh` 从mongosh 1.1.9版本开始 MongoDB Compass 从Compass 1.28.4版本开始
`retryReads`	启用可重试的读取。可能的值是 `true`。为连接启用可重试的读取。官方MongoDB驱动程序默认设置为`true`。 `false`。为连接禁用可重试的读取。 `mongosh` 不支持可重试的读取。
`retryWrites`	启用可重试的写入。可能的值是 `true`。为连接启用可重试的写入。官方MongoDB驱动程序默认设置为`true`。 `false`。为连接禁用可重试的写入。 MongoDB驱动程序会重试事务提交和取消操作，无论`retryWrites`的值如何。有关事务重试性的更多信息，请参阅事务错误处理。
`uuidRepresentation`	可能的值是 `标准` 标准二进制表示。 `csharpLegacy` C#驱动程序的默认表示。 `javaLegacy` Java驱动程序的默认表示。 `pythonLegacy` Python驱动程序的默认表示。有关默认值，请参阅您驱动程序的驱动程序文档。并非所有驱动程序都支持`uuidRepresentation`选项。有关您驱动程序的信息，请参阅驱动程序文档。
`loadBalanced`	指定客户端是否连接到负载均衡器。此选项默认为`false`。只有满足以下要求，您才能将此选项设置为`true` 您指定了仅一个主机名。您没有连接到副本集。 `srvMaxHosts`选项未设置或其值为`0`。 `directConnection`选项未设置或其值为`false`。
`srvMaxHosts`	指定可以创建用于分片拓扑的 `mongos` 连接的数量。将此选项设置为非负整数。默认值为 `0`，表示没有对 `mongos` 连接数量的限制。

连接字符串

连接字符串示例