Docs 菜单
Docs 主页
/
MongoDB Manual
/
参考
/
连接字符串(Connection Strings)

连接字符串选项

在此页面上

  • 副本集选项
  • 连接选项
  • 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：

注意

tls 选项等同于 ssl 选项。

如果 mongosh Shell 在命令行中指定了额外的 tls/ssl 选项，请改用 --tls 命令行选项。

ssl

一个布尔值，用于启用或禁用连接的 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 会在连接时记录警告。请参阅 x.509 证书即将过期触发警告，了解更多信息。

并非所有驱动程序都支持此选项。请参阅驱动程序文档。

此连接字符串选项不可用于 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

隔离级别。可接受以下值之一：

此连接字符串选项不适用于 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。给定事务中的所有操作必须路由至同一节点。

该连接字符串选项不适用于 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。

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

注意

如果 AWS 访问密钥 ID、秘密访问密钥或会话令牌包含以下字符：

$ : / ? # [ ] @

这些字符必须使用百分比编码进行转换。

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

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

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

指定自定义应用名称。应用程序名称出现在：

appName 连接选项可用于：

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)