/ /

连接字符串选项

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

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

使用驱动程序时，选项 name 不区分大小写。
name使用mongosh 时，选项不区分大小写。
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` 连接选项，以确保跨驱动程序的行为的一致性。连接到副本集时，请在 `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` 实例。如果显示的 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。请改用命令行选项。警告：禁用证书验证会产生漏洞。

超时选项

连接选项	说明
`timeoutMS`	超时之前尝试执行操作的时间（以毫秒为单位）。超时适用于操作中的所有步骤，包括服务器选择、连接签出和服务器端执行。 `timeoutMS` 没有默认值。如果未指定值，驾驶员将应用单个超时选项，例如`socketTimeoutMS` 。如果在连接字符串中设置 `timeoutMS`，驱动程序将忽略其他超时选项，并且超时将应用到客户端中的每个操作。您可以在更具体的级别覆盖 `timeoutMS`，但无法取消设置该值。要了解有关超时继承的更多信息，请参阅限制服务器执行时间。重要提示： `timeoutMS` 尚未得到所有官方驱动程序的支持。有关可用性，请参阅驾驶员文档。
`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`	线程可以等待连接变为可用状态的最长时间（以毫秒为单位）。有关默认值，请参阅驱动程序文档。并非所有驱动程序都支持此选项。

写关注选项

写关注（write concern）描述了从MongoDB请求的确认级别。这些选项由以下设备支持：

您可以在连接字符串中指定写关注（write concern），也可以将其指定为 insert 或 update 等方法的参数。如果在两个位置都指定了，则方法参数将覆盖连接字符串。

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

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

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` `timeoutMSwtimeoutMS`。覆盖。对应于写关注（write concern）。指定写关注（write`wtimeout` `wtimeoutMS`concern）的时间限制（以毫秒为单位）。当 `wtimeoutMS` 为 `0` 时，写入操作永不超时。有关更多信息，请参阅`wtimeout`。
`journal`	对应于写关注（write concern）`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` 。将读关注（read concern）为特定操作的选项。

有关详细信息，请参阅读关注。

读取偏好选项

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

例如：

以下副本集连接字符串指定读取偏好（readsecondary preference）模式和maxStalenessSeconds 120秒的值：
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readPreference=secondary&maxStalenessSeconds=120
以下分片集群的连接字符串指定了读取偏好（readsecondary preference）模式和maxStalenessSeconds 120秒的值：
mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongos1.example.com,mongos2.example.com/?readPreference=secondary&maxStalenessSeconds=120
以下分片集群的连接字符串指定读取偏好（readsecondary preference）模式和三个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` 包含读取操作的事务必须使用读取偏好（read preference）`primary`。给定ACID 事务中的所有操作必须路由到同一成员。该连接字符串选项不适用于 `mongo` shell。请参见 `cursor.readPref()` 和 `Mongo.setReadPref()`。
`maxStalenessSeconds`	指定客户端在停止对从节点进行读取操作之前，从节点的陈旧程度（以秒为单位）。有关详情，请参阅读取偏好 `maxStalenessSeconds`。默认下，没有最大过时时间，客户端在选择读取操作的定向位置时不考虑从节点(secondary node from replica set)的延迟。 `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

与用户凭证关联的数据库名称。如果指定，则默认为 defaultauthdb，否则默认为 admin。

、和PLAINGSSAPI MONGODB-AWSauthSource机制要求将设立为$external ，因为它们会将档案存储委托给外部服务。

如果连接字符串中或通过未提供用户名，authSource MongoDB会忽略--username 。

authMechanism

默认值：SCRAM-SHA-256

连接的身份验证机制。如果没有显式 authMechanism， MongoDB会尝试SCRAM-SHA-256；如果失败，则回退到SCRAM-SHA-1。

SCRAM-SHA-1
SCRAM-SHA-256
MONGODB-X509
MONGODB-AWS
GSSAPI (Kerberos)
PLAIN (LDAP SASL)

只有 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_TOKENauthMechanismProperties 值。

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

$ : / ? # [ ] @

或者，如果 AWS访问权限密钥ID、秘密访问权限密钥或会话令牌是使用各自的 AWS IAM 环境变量在您的平台上定义的，则 mongosh会使用这些环境变量值自动进行身份验证。您不需要在连接字符串中指定它们。根据您的部署环境和安全要求，还有其他方法可以提供 AWS凭证。

有关 MONGODB-AWS 身份验证机制的示例用法，请参阅连接字符串。

有关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>

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

gssapiServiceName

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

gssapiServiceName 默认值为 mongodb（对于所有客户端和 MongoDB 实例）。如果更改了 MongoDB 实例的 saslServiceName 设置，则必须设置 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 MongoDB Compass从Compass 1开始。28 。4
`retryReads`	启用可重试读取。可能的值为： `true`。启用连接的可重试读取。官方 MongoDB 驱动程序默认为 `true`。 `false`。禁用连接的可重试读取。 `mongosh` 不支持可重试读取。
`retryWrites`	启用可重试写入。可能的值为： `true`。启用连接的可重试写入。官方 MongoDB 驱动程序默认为 `true`。 `false`。禁用连接的可重试写入。无论 `retryWrites`的值如何， MongoDB驱动程序都会重试ACID 事务提交和中止操作。有关ACID 事务可重试性的更多信息，请参阅事务错误处理。
`uuidRepresentation`	可能的值为： `standard` 标准二进制表示形式。 `csharpLegacy` .NET/C# 驱动程序的默认表示形式。 `javaLegacy` Java 驱动程序的默认表示形式。 `pythonLegacy` Python 驱动程序的默认表示形式。请参阅您的驱动程序文档，了解默认情况。并非所有驱动程序支持`uuidRepresentation` 选项。有关驾驶员的信息，请参阅驱动程序文档。
`loadBalanced`	指定客户端是否连接到负载均衡器。默认情况下，此选项处于 `false` 状态。只有在满足以下要求时，您才能将此选项设置为 `true`：仅指定一个主机名。您连接的不是副本集。 `srvMaxHosts`选项未设置或值为`0` 。 `directConnection`选项未设置或值为`false` 。
`srvMaxHosts`	指定可以为分片的拓扑结构创建的 `mongos` 连接数。将此选项设置为非负整数。`0` 是默认值，表示 `mongos` 连接数没有限制。

后退

连接字符串(Connection Strings)

来年

Formats