连接字符串选项

此页面列出了使用 SRV 连接字符串和标准连接字符串连接到数据库的所有连接选项。

连接选项是以下形式的对： name=value 。

使用驱动程序时，选项 name 不区分大小写。
使用 mongosh时，选项name不区分大小写。
value 始终区分大小写。

用 & 符号 (&) 字符 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

如果mongod 是副本集的成员，则指定副本集的名称。设置replicaSet连接选项，确保跨驱动程序行为的一致。

连接到副本集时，向 uri 的 host[:port] 组件提供副本集节点的种子列表。请参阅驱动程序文档，了解具体详情。

directConnection

指定客户端是否直接连接到连接 URI 中的 host[:port]：

true：客户端仅向指定主机发送操作。它不会尝试发现副本集的任何其他节点。
false：客户端尝试发现副本集中的所有服务器，并向主节点发送操作。这是默认值。

重要提示：当副本集在Docker中运行时，它可能只公开一个MongoDB端点。在这种情况下，副本集不可发现，并且指定 directConnection=false 可能会阻止应用程序连接到该副本集。

在测试或开发环境中，您可以通过在连接 URI 中指定directConnection=true 来连接副本集。在生产环境中，我们建议配置集群，以便每个 MongoDB 实例都可以在 Docker 虚拟网络之外访问。

连接选项

TLS 选项

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

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 启动连接。标准连接string格式的默认值。 `tls`选项等同于`ssl` 选项。如果 `mongosh` Shell 在命令行中指定了额外的 tls/ssl 选项，请改用 `--tls` 命令行选项。
`ssl`	一个布尔值，用于启用或禁用连接的 TLS/SSL： `true`：使用 TLS/SSL 启动连接。 SRV 连接格式的默认值。 `false`：不使用 TLS/SSL 启动连接。标准连接string格式的默认值。 `ssl`选项等同于`tls` 选项。如果 `mongosh` Shell 在命令行中指定了额外的 tls/ssl 选项，请改用 `--ssl` 命令行选项。
`tlsCertificateKeyFile`	指定包含客户端的 TLS/SSL X.509 证书或客户端的 TLS/SSL 证书和密钥的本地 `.pem` 文件的位置。客户端将此文件提供给 `mongod` / `mongos` 实例。如果显示的 x.509 证书在 `mongod/mongos` 主机系统时间后的 `30` 天内过期，则 `mongod` / `mongos` 会在连接时记录警告。并非所有驱动程序都支持此选项。请参阅驱动程序文档。此连接字符串选项不可用于 `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用于 network compression）。

您可以指定范围从 -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"。

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

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

连接选项	说明
`w`	对应于写关注 `w` 选项。`w` 选项请求确认写入操作已传播到指定数量的 `mongod` 实例或带有指定标签的 `mongod` 实例。您可以指定 `number`、字符串 `majority` 或 `tag set`。有关详细信息，请参阅 `w` 选项。
`wtimeoutMS`	重要提示：`wtimeoutMS` 选项已弃用。改为设置 `timeoutMS`。`timeoutMS` 覆盖 `wtimeoutMS`。对应于写关注（write concern）`wtimeout` 。`wtimeoutMS`指定写关注（write concern）的时间限制（以毫秒为单位）。当 `wtimeoutMS` 为 `0` 时，写入操作永不超时。有关更多信息，请参阅`wtimeout`。
`journal`	对应于写关注（write concern）`j` Option 选项。`journal`选项请求MongoDB确认写入操作已写入日志。有关详细信息，请参阅`j` 选项。如果将`journal` 设立为`true` ，并指定小于的`w` 值，则1 `journal`优先。

如需了解更多信息，请参阅写关注。

readConcern 选项

对于 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 读取偏好模式和 maxStalenessSeconds 值为 120 秒：
```
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`。默认下，没有最大过时时间，客户端在选择读取操作的定向位置时不考虑从节点(secondary node from replica set)的延迟。 `maxStalenessSeconds` 的最小值为 90 秒。指定介于 0 和 90 秒之间的值会产生错误。MongoDB驱动程序将 `-1` 的 `maxStalenessSeconds` 值视为“无最大陈旧度”，与省略 `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()`。

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

身份验证选项

以下指向副本集的连接字符串为 admin 数据库指定 authSource。换言之，根据 admin 数据库对用户凭证进行身份验证。

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

如果用户名或密码包含以下字符，则必须使用百分号编码：对这些字符进行转换。

$ : / ? # [ ] @

连接选项	说明
`authSource`	指定与用户凭证关联的数据库名称。 `authSource`如果未指定，则`authSource` `defaultauthdb`默认为连接字符串中指定的。`defaultauthdb`如果未指定，则`authSource` 默认为`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`，您必须：设置`authMechanismPropertiesENVIRONMENT` 变量。为客户端构造函数提供 OIDC回调。只有 MongoDB Enterprise Edition 的`mongod` 和 `mongos` 实例提供 `GSSAPI` (Kerberos) 和 `PLAIN` (LDAP) 机制。要使用 `MONGODB-X509`，必须启用 TLS/SSL。要使用 `MONGODB-AWS`，您必须连接到MongoDB Atlas 群集，该集群已配置为支持通过Amazon Web Services IAM凭证（Amazon Web Services访问权限密钥ID和秘密访问权限密钥，以及可选的Amazon Web Services会话令牌）进行身份验证验证）。`MONGODB-AWS`身份验证机制要求将`authSource`设立为 `$external`。如果 AWS访问权限密钥ID、秘密访问权限密钥或会话令牌是使用各自的 AWS IAM 环境变量在您的平台上定义的，则 `mongosh` 将使用这些环境变量值自动进行身份验证。您不需要在连接字符串中指定它们。根据您的部署环境和安全要求，还有其他方法可以提供 AWS凭证。 For example usage of the `MONGODB-AWS` authentication mechanism, see Connection Strings. 有关MongoDB中身份验证系统的更多信息，请参阅自管理部署上的身份验证。另请考虑使用 X.509 对自管理 MongoDB 上的客户端进行身份验证，了解有关 x509 身份验证的更多信息。
`authMechanismProperties`	将指定`authMechanism` 的属性指定为以逗号分隔的冒号分隔键值对列表。可能的键值对有： `SERVICE_NAME:<string>` 在连接到 Kerberized MongoDB 实例时设置 Kerberos 服务名称。该值必须与您要连接的 MongoDB 实例上设置的服务名称匹配。仅在使用 GSSAPI 身份验证机制时有效。 `SERVICE_NAME` 对于所有客户端和 MongoDB 实例，默认为 `mongodb`。如果更改 MongoDB 实例上的 `saslServiceName` 设置，则必须设置 `SERVICE_NAME` 以匹配该设置。仅在使用 GSSAPI 身份验证机制时有效。 `CANONICALIZE_HOST_NAME:true\|false` 连接到 Kerberos 服务器时规范化客户端托管计算机的主机名。当主机报告的主机名与 Kerberos 数据库中的主机名不同时，这可能是必需的。默认值为 `false`。仅在使用 GSSAPI 身份验证机制时有效。 `SERVICE_REALM:<string>` 为 MongoDB 服务设置 Kerberos Realm。这对于支持跨 Realm 的身份验证（在此情况下，用户存在于一个 Realm，而服务则存在于另一 Realm 中）可能是必需的。仅在使用 GSSAPI 身份验证机制时有效。 `AWS_SESSION_TOKEN:<security_token>` Set the AWS session token for authentication with temporary credentials when using an AssumeRole request, or when working with AWS resources that specify this value such as Lambda. Only valid when using the `MONGODB-AWS` authentication mechanism. You must have an AWS access key ID and a secret access key as well. For example usage, see Connection Strings. `ENVIRONMENT:<string>` 设置 OpenID Connect (OIDC) 环境。对于： Microsoft Azure，设立 `ENVIRONMENT:azure` Google Cloud Platform，设立 `ENVIRONMENT:gcp` 您还必须将`authMechanism` 设立为`MONGODB-OIDC` 。
`gssapiServiceName`	在连接到启用了 Kerberos 的MongoDB 实例时，负责设置 Kerberos 服务名称。该值必须与您要连接的 MongoDB 实例上所设的服务名称相匹配。对于所有客户端和MongoDB实例，`gssapiServiceName` 默认为。`mongodbsaslServiceName`如果更改MongoDB实例上的设置，则必须设立`gssapiServiceName` 以匹配该设置。 `gssapiServiceName` 是 `authMechanismProperties=SERVICE_NAME:mongodb` 的已弃用别名。有关您的驱动程序支持哪些选项以及它们之间的相对优先级的更多信息，请参阅您的首选驱动程序版本的文档。

服务器选择和发现选项

MongoDB 提供以下选项来配置 MongoDB 驱动程序和 mongos 实例如何选择要直接读取或写入操作的服务器。

连接选项	说明
`localThresholdMS`	用于在多个合适的 MongoDB 实例中选择的延迟窗口的大小（以毫秒为单位）。默认：15 毫秒。所有驱动程序都使用`localThresholdMS` 。`localThreshold`将延迟窗口大小指定为`mongos` 时，请使用别名。
`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` 命令和 `db.currentOp()` 方法输出中的 `currentOp.appName` 字段数据库分析器输出中的 `system.profile.appName` 字段 `appName`连接选项可用于： MongoDB 驱动程序 `mongosh` 从 `mongosh` 1.1.9 开始从 Compass 1.28.4 开始的 MongoDB Compass
`retryReads`	启用可重试读取。可能的值为： `true`。启用连接的可重试读取。官方 MongoDB 驱动程序默认为 `true`。 `false`。禁用连接的可重试读取。 `mongosh` 不支持可重试读取。
`retryWrites`	启用可重试写入。可能的值为： `true`。启用连接的可重试写入。官方 MongoDB 驱动程序默认为 `true`。 `false`。禁用连接的可重试写入。无论的值如何， `retryWrites`MongoDB驱动程序都会重试ACID 事务提交和中止操作。有关ACID 事务可重试性的更多信息，请参阅事务错误处理。
`uuidRepresentation`	可能的值为： `standard` 标准二进制表示形式。 `csharpLegacy` C# 驱动程序的默认表示形式。 `javaLegacy` Java 驱动程序的默认表示形式。 `pythonLegacy` Python 驱动程序的默认表示形式。请参阅您的驱动程序文档，了解默认情况。并非所有驱动程序都支持 `uuidRepresentation` 选项。有关驱动程序的详细信息，请参阅驱动程序文档。
`loadBalanced`	指定客户端是否连接到负载均衡器。默认情况下，此选项处于 `false` 状态。只有在满足以下要求时，您才能将此选项设置为 `true`：仅指定一个主机名。您连接的不是副本集。 `srvMaxHosts`选项未设置或值为`0` 。 `directConnection`选项未设置或值为`false` 。
`srvMaxHosts`	指定可以为分片的拓扑结构创建的 `mongos` 连接数。将此选项设置为非负整数。`0` 是默认值，表示 `mongos` 连接数没有限制。

后退

连接字符串(Connection Strings)

来年

Formats