Docs 菜单

Docs 主页 → 开发应用程序 → MongoDB Manual

连接字符串(Connection Strings)

在此页面上

  • 兼容性
  • 查找连接字符串
  • 查找您的 MongoDB Atlas 连接字符串
  • 查找自托管部署的连接字符串
  • 连接字符串格式
  • SRV 连接格式。
  • 标准连接字符串格式
  • 连接字符串选项
  • 副本集选项
  • 连接选项
  • 连接池选项
  • 写关注选项
  • readConcern 选项
  • 读取偏好选项
  • 身份验证选项
  • 服务器选择和发现选项
  • 其他配置
  • 连接字符串示例
  • MongoDB Atlas 部署连接字符串示例
  • 自托管部署连接字符串示例

➤ 使用右上角的 Select your language（选择语言）下拉菜单，设置以下示例的语言。

您可以使用连接字符串来定义 MongoDB 实例与以下目标之间的连接：

  • 使用 驱动程序连接时的应用程序。

  • MongoDB Compass和MongoDB Shell (mongosh) 等工具。

兼容性

您可以使用连接字符串连接到以下环境中托管的部署：

查找连接字符串

完成如下步骤，找到您的连接字符串。

查找您的 MongoDB Atlas 连接字符串

您的 MongoDB Atlas 连接字符串将类似于以下示例：

查找自托管部署的连接字符串

如果您已连接到自托管的 MongoDB Enterprise 或 MongoDB Community 部署，请运行db.getMongo()方法，以返回连接字符串。

如果您未连接到部署，则可以根据要使用的连接类型确定连接字符串。请参阅 SRV 连接格式以了解 SRV 连接字符串语法，或者参阅标准连接字符串格式以了解标准连接字符串语法。

您的自托管连接字符串将类似于以下示例：

有关连接字符串选项的完整列表，请参阅SRV 连接格式或标准连接字符串格式。有关更多示例，请参阅连接字符串示例。

连接字符串格式

您可以使用下列格式中的一种来指定 MongoDB 连接字符串：

除非连接到 在线存档 ，否则 MongoDB Atlas 数据库部署使用 SRV 连接格式 。

SRV 连接格式。

MongoDB 支持 DNS 构建的种子列表。通过使用 DNS 构建可用服务器列表，可以提高部署的灵活性，并能够轮流更改服务器，而无需重新配置客户端。

SRV URI 连接模式具有以下形式：

mongodb+srv://[username:password@]host[/[defaultauthdb][?options]]

有关更多示例，请参阅连接字符串示例。

连接字符串组件

连接字符串包括以下组件：

组件
说明
mongodb:// 或 mongodb+srv://
标识标准连接格式 (mongodb://) 或 SRV 连接格式 (mongodb+srv://) 字符串的必需前缀。要进一步了解每种格式，请参阅标准连接字符串格式和SRV 连接格式。
username:password@

可选。身份验证凭证。

如果指定，客户端将尝试向authSource验证用户身份。如果未指定authSource ，客户端将尝试向defaultauthdb验证用户身份。如果未指定defaultauthdb ，则写入admin数据库。

注意

如果用户名或密码包含以下字符：

: / ? # [ ] @

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

另请参阅authSource 。

host[:port]

运行 mongod 实例（或分片集群的 mongos 实例）的主机（和可选的端口号）。可以指定主机名、IP 地址或 UNIX 域套接字。根据您的部署拓扑，指定尽可能多的主机：

  • 对于独立实例，请指定独立 mongod 实例的主机名。

  • 对于副本集，副本集配置中列出的 mongod 实例的主机名。

  • 对于分片集群，请指定 mongos 实例的主机名。

如果未指定端口号，则使用默认端口 27017。

注意

如果使用 SRV URI 连接格式，则只能指定一个主机，不能指定端口。否则，驱动程序或mongosh会引发解析错误，并且不会执行 DNS 解析。

/defaultauthdb

可选。如果连接字符串包含username:password@身份验证档案但未指定authSource选项，则要使用的身份验证数据库。

如果authSource和defaultauthdb均未指定，客户端将尝试在admin数据库中验证指定用户的身份。

?<options>

可选。将连接特定选项指定为<name>=<value>对的查询字符串。有关这些选项的完整说明，请参阅连接字符串选项。

如果连接字符串未指定数据库/，则必须在最后一个 host 和选项字符串开头的问号 (?) 之间指定斜杠 (/)。

为了利用 DNS 种子列表，请使用与标准连接字符串相同的语法，前缀为mongodb+srv ，而不是标准mongodb 。 +srv向客户端指示后面的主机名对应于 DNS SRV 记录。然后，驱动程序或mongosh将查询 DNS 的记录，以确定哪些主机正在运行mongod或mongos实例。

注意

使用+srv 连接字符串修饰符会自动将tls （或等效的ssl ）选项设置为true 以进行连接。您可以通过在查询字符串中使用tls sslfalsetls=false（或ssl=false ）将 （或等效的 ）选项显式设置为 来覆盖此行为。

使用 +srv 格式时，必须以 <hostname>.<domain>.<TLD>. 格式指定 hostname、domain 和 top-level domain (TLD)。这个表格显示占位符与示例值的对应关系：

占位符
例子
<hostname>
server
<domain>
example
<TLD>
com
<hostname>.<domain>.<TLD>
server.example.com

此示例显示了正确使用 <hostname>.<domain>.<TLD> 格式的 DNS 种子列表连接字符串。它使用密码D1fficultP%40ssw0rd作为用户myDatabaseUser进行身份验证：

mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@server.example.com/

相应的 DNS 配置类似于：

Record                            TTL   Class    Priority Weight Port  Target
_mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27317 mongodb1.example.com.
_mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27017 mongodb2.example.com.

各个 SRV 记录必须采用 _mongodb._tcp.<hostname>.<domain>.<TLD> 格式。

客户端连接到种子列表的成员时，会检索到它可以连接的副本集节点列表。客户端经常在其种子列表中使用 DNS 别名，这意味着主机可能会返回与原始种子列表不同的服务器列表。如果发生这种情况，客户端将使用副本集提供的主机名而不是种子列表中列出的主机名，以确保可以通过生成的副本集配置中的主机名访问副本集节点。

重要

SRV 记录中返回的主机名必须具有与给定主机名相同的父域（在本例中为 example.com）。如果父域和主机名不匹配，您将无法连接。

此示例显示了缺少 <hostname> 的 DNS 种子列表连接字符串。这是不正确的，会引发错误。

# This connection string is missing the <hostname> and raises a connection error
mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@example.com/

与标准连接字符串一样，DNS 种子列表连接字符串支持将选项指定为查询字符串。使用 DNS 种子列表连接字符串，还可以通过 TXT 记录指定以下选项：

  • replicaSet

  • authSource

每个 mongod 实例只能指定一条 TXT 记录。如果 DNS 中出现多条 TXT 记录和/或 TXT 记录包含 replicaSet 或 authSource 以外的选项，客户端将返回错误。

DNS 条目的 TXT 记录类似于：server.example.com

Record              TTL   Class    Text
server.example.com. 86400 IN TXT   "replicaSet=mySet&authSource=authDB"

将DNS SRV 记录和 TXT 记录中指定的选项结合起来，可解析为以下标准格式的连接字符串：

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb1.example.com:27317,mongodb2.example.com:27017/?replicaSet=mySet&authSource=authDB

可以通过在查询字符串中传递 TXT 记录中指定的选项，以覆盖这些选项。在如下示例中，查询字符串为上面的 DNS 条目的 TXT 记录中配置的 authSource 选项提供了覆盖。

mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@server.example.com/?connectTimeoutMS=300000&authSource=aDifferentAuthDB

考虑到对 authSource 的重写，标准格式的等效连接字符串将是：

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb1.example.com:27317,mongodb2.example.com:27017/?connectTimeoutMS=300000&replicaSet=mySet&authSource=aDifferentAuthDB

注意

mongodb+srv如果没有可用的 DNS 记录与连接字符串中标识的主机名相对应，则 选项将失败。如果使用+srv 连接字符串修饰符，则连接的tls （或等效的ssl ）选项将设置为true 。您可以通过在查询字符串中使用tls sslfalsetls=false（或ssl=false ）将 （或等效的 ）选项显式设置为 来覆盖此行为。

有关使用 DNS 种子列表连接格式将mongosh连接到副本集的示例，请参阅mongosh 连接选项。

标准连接字符串格式

本节介绍了用于连接到自托管 MongoDB 独立部署、副本集或分片集群的 MongoDB 连接 URI 的标准格式。

标准 URI 连接方案的形式如下：

mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]

有关更多示例，请参阅连接字符串示例。

连接字符串组件

连接字符串包括以下组件：

组件
说明
mongodb:// 或 mongodb+srv://
标识标准连接格式 (mongodb://) 或 SRV 连接格式 (mongodb+srv://) 字符串的必需前缀。要进一步了解每种格式，请参阅标准连接字符串格式和SRV 连接格式。
username:password@

可选。身份验证凭证。

如果指定，客户端将尝试向authSource验证用户身份。如果未指定authSource ，客户端将尝试向defaultauthdb验证用户身份。如果未指定defaultauthdb ，则写入admin数据库。

注意

如果用户名或密码包含以下字符：

: / ? # [ ] @

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

另请参阅authSource 。

host[:port]

运行 mongod 实例（或分片集群的 mongos 实例）的主机（和可选的端口号）。可以指定主机名、IP 地址或 UNIX 域套接字。根据您的部署拓扑，指定尽可能多的主机：

  • 对于独立实例，请指定独立 mongod 实例的主机名。

  • 对于副本集，副本集配置中列出的 mongod 实例的主机名。

  • 对于分片集群，请指定 mongos 实例的主机名。

如果未指定端口号，则使用默认端口 27017。

注意

如果使用 SRV URI 连接格式，则只能指定一个主机，不能指定端口。否则，驱动程序或mongosh会引发解析错误，并且不会执行 DNS 解析。

/defaultauthdb

可选。如果连接字符串包含username:password@身份验证档案但未指定authSource选项，则要使用的身份验证数据库。

如果authSource和defaultauthdb均未指定，客户端将尝试在admin数据库中验证指定用户的身份。

?<options>

可选。将连接特定选项指定为<name>=<value>对的查询字符串。有关这些选项的完整说明，请参阅连接字符串选项。

如果连接字符串未指定数据库/，则必须在最后一个 host 和选项字符串开头的问号 (?) 之间指定斜杠 (/)。

连接字符串选项

本节列出了 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] 组件提供副本集节点的种子列表。请参阅驱动程序文档，了解具体详情。

连接选项

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：

注意

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，则mongod / mongos会记录连接警告。 509证书会在mongod/mongos主机系统时间后的30天内过期。请参阅x。 509证书即将过期trigger警告以了解更多信息。

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

此连接字符串选项不可用于 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选项。有关驱动程序的信息，请参阅驱动程序文档。

maxIdleTimeMS

连接在池中可保持空闲状态的最大毫秒数，在此时间过后，连接将被删除或关闭。

并非所有驱动程序都支持此选项。

waitQueueMultiple

驱动程序乘以maxPoolSize值的数字，以提供等待池中连接可用的最大线程数。有关默认值，请参阅驱动程序文档。

并非所有驱动程序都支持此选项。

waitQueueTimeoutMS

线程可以等待连接变为可用状态的最长时间（以毫秒为单位）。有关默认值，请参阅驱动程序文档。

并非所有驱动程序都支持此选项。

写关注选项

写关注描述了从 MongoDB 请求的确认级别。写关注选项由以下提供支持：

您既可以在连接字符串中指定写关注，也可以将其作为 insert 或 update 等方法的参数。如果在两处都指定了写关注，则方法参数会覆盖连接字符串设置。

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

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

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为准。

如果将journal设置为 true，并且mongod未启用日志功能（与storage.journal.enabled一样），则 MongoDB 将出错。

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

readConcern 选项

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

读关注允许客户端为源自副本集的读取操作选择一个隔离级别。

以下副本集连接字符串指定readConcernLevel=majority ：

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readConcernLevel=majority
连接选项
说明
readConcernLevel

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

此连接字符串选项不适用于mongosh 。将读关注指定为特定操作的选项。

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

读取偏好选项

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

注意

要使用驱动程序指定对冲读选项，请参阅驱动程序的读取偏好 API。

例如：

  • 以下副本集连接字符串指定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的情况相同。

重要

要使用 maxStalenessSeconds，您的部署中的所有 MongoDB 实例都必须使用 MongoDB 3.4 或更高版本。如果有任何实例使用了早期版本的 MongoDB，则驱动程序或 mongod / mongos 将引发错误。

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

注意

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

: / ? # [ ] @

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

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

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

有关 MongoDB 中身份验证系统的更多信息，请参阅身份验证。另请考虑使用 x.509 证书对客户端进行身份验证，了解关于 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 和秘密访问密钥。有关使用示例，请参阅 连接到 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 不支持更改心跳检测的频率。

其他配置

连接选项
说明
appName

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

appName连接选项可用于：

retryReads

启用可重试读取。

可能的值为：

  • true。启用连接的可重试读取。

    官方 MongoDB 驱动程序默认为true 。

  • false。禁用连接的可重试读取。

mongosh 不支持可重试读取。

retryWrites

启用可重试写入。

可能的值为：

  • true。启用连接的可重试写入。

    官方 MongoDB 驱动程序默认为true 。

  • false。禁用连接的可重试写入。

    与 MongoDB 4.0 和 3.6 兼容的官方驱动程序默认为 false。

无论 的值如何，MongoDBretryWrites 驱动程序都会重试 事务提交和中止操作 。有关事务可重试性的更多信息，请参阅 事务错误处理。

uuidRepresentation

可能的值为：

standard
标准二进制表示形式。
csharpLegacy
C# 驱动程序的默认表示形式。
javaLegacy
Java 驱动程序的默认表示形式。
pythonLegacy
Python 驱动程序的默认表示形式。

请参阅您的驱动程序文档，了解默认情况。

注意

并非所有驱动程序都支持uuidRepresentation选项。有关驱动程序的信息，请参阅驱动程序文档。

连接字符串示例

以下是常见连接目标的 URI 字符串示例。

MongoDB Atlas 部署连接字符串示例

以下示例连接字符串用于连接到 MongoDB Atlas 部署。

使用用户名和密码进行身份验证的 MongoDB Atlas 集群

使用 AWS IAM 档案进行身份验证的 MongoDB Atlas 集群

以下命令连接到 MongoDB Atlas 集群，该集群已配置为支持通过 AWS IAM 凭证进行身份验证：

以这种方式使用 AWS IAM 凭证连接到 Atlas 会使用MONGODB-AWS authentication mechanism和$external authSource ，如本示例所示。

如果使用 AWS 会话令牌 ，并为其提供AWS_SESSION_TOKENauthMechanismProperties 值，如下所示：

注意

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

: / ? # [ ] @

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

您还可以使用标准 AWS IAM 环境变量 在您的平台上设置这些凭证 mongosh。当您使用 时，MONGODB-AWSauthentication mechanism 会检查以下环境变量：

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

  • AWS_SESSION_TOKEN

如果已设置了这些凭证，就无需在连接字符串中指定。

以下示例会在 bash Shell 中设置这些环境变量：

export AWS_ACCESS_KEY_ID='<aws access key id>'
export AWS_SECRET_ACCESS_KEY='<aws secret access key>'
export AWS_SESSION_TOKEN='<aws session token>'

在其他Shell中设置环境变量的事务语法会有所不同。有关更多信息，请参阅适用于您的平台的文档。

您可以使用以下命令验证这些环境变量是否已设置：

env | grep AWS

一旦制定，以下示例将使用这些环境变量连接到 MongoDB Atlas 集群：

自托管部署连接字符串示例

以下示例连接字符串用于连接到自托管部署。

使用用户名和密码进行身份验证的自托管集群

本地运行的自托管数据库服务器

以下用于连接到在本地默认端口上运行的数据库服务器：

本地运行的自托管 admin 数据库

以下命令以用户 myDatabaseUser 的身份（密码：D1fficultP%40ssw0rd）连接并登录到 admin 数据库：

本地运行的自托管 records 数据库

以下命令以用户 myDatabaseUser 的身份（密码：D1fficultP%40ssw0rd）连接并登录到 records 数据库：

自托管 UNIX 域套接字

连接到 UNIX 域套接字时，请使用 URL 编码的连接字符串。

下面以用户 myDatabaseUser 和密码 D1fficultP%40ssw0rd 连接到文件路径 /tmp/mongodb-27017.sock 的 UNIX 域套接字：

注意

并非所有驱动程序都支持 UNIX 域套接字。有关驱动程序的信息，请参阅驱动程序文档。

在不同计算机上具有成员的自托管副本集

以下示例连接到具有两个成员的副本集，一个在 db1.example.net 上，另一个在 db2.example.net 上，用户为 myDatabaseUser，密码为 D1fficultP%40ssw0rd：

注意

对于副本集，副本集配置中列出的 mongod 实例的主机名。

自托管副本集 localhost

以下命令可以用户 myDatabaseUser 的身份（密码为 D1fficultP%40ssw0rd）连接到一个副本集，该副本集中有三个成员在端口 27017、27018 和 27019 上的 localhost 上运行：

注意

对于副本集，副本集配置中列出的 mongod 实例的主机名。

具有读分发的自托管副本集

以下命令可以用户 myDatabaseUser 的身份（密码：D1fficultP%40ssw0rd）连接到一个含三个成员的副本集，并将读取操作分配给从节点：

注意

对于副本集，副本集配置中列出的 mongod 实例的主机名。

具有高级别写关注的自托管副本集

以下示例将连接到一个副本集，而其写关注被配置为等待大多数承载数据的有投票权成员确认复制成功，且超时时间为两秒。它会使用密码 D1fficultP%40ssw0rd 并以 myDatabaseUser 用户的身份进行身份验证。

注意

对于副本集，副本集配置中列出的 mongod 实例的主机名。

自托管分片集群

以下命令可以用户 myDatabaseUser 的身份（密码：D1fficultP%40ssw0rd）连接到一个含三个 mongos 实例的分片集群：

← 配置文件设置和命令行选项映射
数据库命令 →

在此页面上