连接字符串选项

在此页面上

副本集选项

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

此页面列出了 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`：客户端尝试发现副本集中的所有服务器，并向主节点发送操作。这是默认值。

连接选项

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

一个整数：为 network compression 指定 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"。

以下副本集连接字符串使用 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`	对应于写关注 `wtimeout`。`wtimeoutMS` 指定写关注的时间限制（以毫秒为单位）。当 `wtimeoutMS` 为 `0` 时，写操作永远不会超时。请参阅 `wtimeout`，了解更多信息。
`journal`	对应写关注 `j` Option 选项。`journal` 选项请求 MongoDB 确认写入操作已写入日志。有关详细信息，请参阅 `j` 选项。如果将 `journal` 设置为 `true`，并指定小于 1 的 `w` 值，则以 `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`。默认情况下，没有最大过期时限，客户端在选择将读取操作定向到的节点时，也不会考虑从节点的滞后。 `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 集群，该集群已经过配置，可支持通过 AWS IAM 凭证（一个 AWS 访问密钥 ID 和一个秘密访问密钥，以及一个可选的 AWS 会话令牌）进行身份验证。MONGODB-AWS 身份验证机制要求将 authSource 设置为 $external。

使用 MONGODB-AWS 时，请提供 AWS 访问密钥 ID 以作为用户名，并提供秘密访问密钥以作为密码。如果还使用了 AWS 会话令牌，则请为其提供 AWS_SESSION_TOKEN authMechanismProperties 值。

如果AmazonAmazon Web Services IDWeb Services访问权限密钥ID 、秘密访问权限密钥或会话令牌包含以下字符，则必须使用百分比编码来转换这些字符。

$ : / ? # [ ] @

或者，如果 AWS 访问密钥 ID、秘密访问密钥或会话令牌是通过各自的 AWS IAM 环境变量在您的平台上定义的，那么 mongosh 将使用这些环境变量值进行身份验证；您无需在连接字符串中指定它们。

AtlasMONGODB-AWS有关使用连接string 和环境变量方法的身份验证机制的示例用法，请参阅连接到集群。

有关MongoDB中身份验证系统的更多信息，请参阅自管理部署上的身份验证。另请考虑使用 x。 509用于对自管理部署上的客户端进行身份验证的证书，了解有关 x 509身份验证的更多信息。

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>

设置Amazon Web Services 会话令牌，以便在使用 AssumeRole 时使用临时凭证进行身份验证请求，或使用指定此值的Amazon Web Services 资源（例如Lambda ）时。仅在使用MONGODB-AWS身份验证机制时有效。您还必须拥有Amazon Web Services访问权限密钥ID和秘密访问权限密钥。有关使用示例，请参阅连接到Atlas集群。

ENVIRONMENT:<string>

设置 OpenID Connect (OIDC) 环境。对于：

Microsoft Azure，设立 ENVIRONMENT:azure
Google Cloud Platform，设立 ENVIRONMENT:gcp

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

gssapiServiceName

在连接到启用了 Kerberos 的MongoDB 实例时，负责设置 Kerberos 服务名称。该值必须与您要连接的 MongoDB 实例上所设的服务名称相匹配。

对于所有客户端和 MongoDB 实例，gssapiServiceName 默认为 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` 命令和 `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 驱动程序均会重试事务提交与中止操作。有关事务可重试性的更多信息，请参阅事务错误处理。
`uuidRepresentation`	可能的值为： `standard` 标准二进制表示形式。 `csharpLegacy` C# 驱动程序的默认表示形式。 `javaLegacy` Java 驱动程序的默认表示形式。 `pythonLegacy` Python 驱动程序的默认表示形式。请参阅您的驱动程序文档，了解默认情况。并非所有驱动程序都支持 `uuidRepresentation` 选项。有关驱动程序的详细信息，请参阅驱动程序文档。
`loadBalanced`	指定客户端是否连接到负载均衡器。默认情况下，此选项处于 `false` 状态。只有在满足以下要求时，您才能将此选项设置为 `true`：仅指定一个主机名。您连接的不是副本集。 `srvMaxHosts` 选项未设置或值为 `0`。 `directConnection` 选项未设置或值为 `false`。
`srvMaxHosts`	指定可以为分片的拓扑结构创建的 `mongos` 连接数。将此选项设置为非负整数。`0` 是默认值，表示 `mongos` 连接数没有限制。

后退

连接字符串(Connection Strings)

来年

连接字符串示例