连接字符串 URI 格式

在本页面

• 连接字符串格式

• 连接字符串选项

• Examples

本文档介绍了用于定义使用 MongoDB drivers和 MongoDB 实例的应用程序之间的连接的 URI 格式。

连接字符串格式

您可以使用以下任一方式指定 MongoDB 连接字符串：

• 标准连接字符串格式或

• the DNS 种子列表连接格式.

标准连接字符串格式

本部分描述用于连接到 MongoDB 部署的 MongoDB 连接 URI 的标准格式：独立，副本集或分片群集。

标准 URI 连接方案具有以下形式：

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

Examples

mongodb://mongodb0.example.com:27017/admin

mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017/admin

mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/admin?replicaSet=myRepl

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

mongodb://mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017/admin

mongodb://myDBReader:D1fficultP%40ssw0rd@mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017/admin

有关更多示例，请参见Examples。

Components

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

如果用户名或密码包含符号@，冒号:，斜杠/或百分号%字符，请使用percent encoding。
另请参见authSource。
| host[:port] |正在运行mongod实例(或分片群集的mongos实例)的主机(和可选端口号)。您可以指定主机名，IP 地址或 UNIX 域套接字。根据您的部署拓扑指定尽可能多的主机：
对于独立服务器，请指定独立mongod实例的主机名。
对于副本集，请指定副本集配置中列出的mongod实例的主机名。
对于分片群集，请指定mongos实例的主机名。
如果未指定端口号，则使用默认端口27017。
| /database |可选。如果连接字符串包含username:password@形式的认证凭据，则要认证的数据库的名称。如果未指定/database且连接字符串包含凭据，则驱动程序将向admin数据库进行身份验证。另请参见authSource。
| ?options |可选。一个查询字符串，将特定于连接的选项指定为<name>=<value>对。有关这些选项的完整说明，请参见连接字符串选项。
如果连接字符串未指定数据库/，则必须在最后一个host和以选项字符串开头的问号(?)之间指定斜杠(/)。

DNS 种子列表连接格式

3.6 版的新功能。

除标准连接格式外，MongoDB 还支持 DNS 构造的种子列表。使用 DNS 构造可用的服务器列表，可以提供更大的部署灵 Active，并可以轮流更改服务器而无需重新配置 Client 端。

为了利用 DNS 种子列表，请使用连接字符串前缀mongodb+srv:代替上面的mongodb:字符串。

+srv向 mongoClient 端指示后面的主机名对应于 DNS SRV 记录。然后，Client 端驱动程序将查询 DNS 以获取记录，以确定正在运行 mongod 实例的主机。

例如，要连接到列出 DNS 的主机名：

mongodb+srv://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.

DNS 种子列表连接字符串还可以提供选项作为查询字符串，并带有尾随的“ /？”。就像上面的标准连接字符串一样。但是，附加到标准连接字符串的+srv表示驱动程序要向 DNS 查询选项以作为已配置的 TXT 记录。

通过 TXT 记录只能配置两个选项replicaSet和authSource，每个服务器只允许一个 TXT 记录。如果 DNS 中出现多个 TXT 记录和/或 TXT 记录包含replicaSet或authSource以外的选项，则驱动程序将引发错误。

正确配置的 TXT 记录的示例：

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

在这种情况下，同时考虑 DNS SRV 记录和从 TXT 记录检索的选项，解析后的字符串将如下所示：

mongodb://mongodb1.example.com:27317,mongodb2.example.com:27017/?replicaSet=mySet&authSource=authDB

通过传递带有 URI 的查询字符串，可以覆盖 TXTLogging 设置的选项。在下面的示例中，查询字符串提供了对上面 DNS 条目的 TXTLogging 配置的authSource选项的替代。

mongodb+srv://server.example.com/?connectTimeoutMS=300000&authSource=aDifferentAuthDB

选项字符串的其余部分将保留，我们可以预期结果 URI 看起来像这样(解析后)。

mongodb://mongodb1.example.com:27317,mongodb2.example.com:27017/?connectTimeoutMS=300000&replicaSet=mySet&authSource=aDifferentAuthDB

连接字符串选项

本节列出了标准连接字符串格式中使用的所有连接选项。

连接选项是成对的，格式如下：name=value。 value始终区分大小写。用＆字符(即&)分隔选项。在以下示例中，连接使用replicaSet和connectTimeoutMS选项：

mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000

副本集选项

以下连接字符串连接到名为myRepl的副本集，且成员在指定主机上运行：

mongodb://db0.example.com:27017,db1.example.com:27017,db2.example.com:27017/admin?replicaSet=myRepl

连接到副本集时，请将副本集成员的种子列表提供给 uri 的host[:port]组件。有关特定的详细信息，请参阅您的driver文档。

Connection Options

以下到副本集的连接字符串包括ssl=true选项：

mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&ssl=true

连接池选项

大多数驱动程序实现某种连接池处理。某些驱动程序不支持连接池。有关连接池实现的更多信息，请参见driver文档。这些选项允许应用程序在连接到 MongoDB 部署时配置连接池。

写关注选项

Write concern描述了从 MongoDB 请求的确认级别。有关一般写关注和写操作的完整说明，请参见Write Concern。

您既可以在连接字符串中也可以在insert或update之类的方法中指定写关注点。如果在两个地方都指定了写关注点，则 method 参数将覆盖连接字符串设置。

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

mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&w=majority&wtimeoutMS=5000

您可以指定number，字符串majority或tag set。
有关详细信息，请参见w Option。
| wtimeoutMS |对应于写关注wtimeout。 wtimeoutMS指定以毫秒为单位的写关注时间限制。
当wtimeoutMS为0时，写操作将永远不会超时。有关更多信息，请参见wtimeout。
| journal |对应于写入关注j Option选项。 journal选项请求 MongoDB 确认写入操作已写入journal。有关详细信息，请参见j Option。
如果将journal设置为true，并且将w的值指定为小于 1，则以journal为准。
在 2.6 版中进行了更改：如果将journal设置为 true，并且mongod没有像storage.journal.enabled那样启用日记功能，则 MongoDB 将出错。在以前的版本中，MongoDB 将提供基本的收据确认(即w:1)，忽略journal，并在其返回文档中包含jnote字段。

有关更多信息，请参见Write Concern。

readConcern Options

3.2 版中的新功能：对于 WiredTiger 存储引擎，MongoDB 3.2 引入了副本集和副本集分片的 readConcern 选项。

Read Concern允许 Client 端选择其读取副本集的隔离级别。

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

mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readConcernLevel=majority

local
majority
linearizable
available
此连接字符串选项不适用于mongo shell。将读取的关注点指定为特定操作的选项。

有关更多信息，请参见Read Concern。

读取首选项

Read preferences描述关于replica sets的读取操作的行为。这些参数允许您在连接字符串中基于每个连接指定读取首选项。

For example:

• 以下到副本集的连接字符串指定secondary读取首选项模式和maxStalenessSeconds值为 120 秒：

mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readPreference=secondary&maxStalenessSeconds=120

• 以下到分片群集的连接字符串指定secondary读取首选项模式和maxStalenessSeconds值为 120 秒：

mongodb://mongos1.example.com,mongos2.example.com/?readPreference=secondary&maxStalenessSeconds=120

• 以下到分片群集的连接字符串指定secondary读取首选项模式以及三个readPreferenceTags：

mongodb://mongos1.example.com,mongos2.example.com/?readPreference=secondary&readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=dc:ny&readPreferenceTags=

使用多个readPreferenceTags时，Sequences 很重要。依次尝试readPreferenceTags直到找到匹配项。一旦找到，该规范将用于查找所有符合条件的匹配成员，并且忽略任何剩余的readPreferenceTags。有关详细信息，请参见标签匹配 Sequences。

读取的首选项值如下：
primary(默认)
primaryPreferred
secondary
secondaryPreferred
nearest
此连接字符串选项不适用于mongo shell。请参见cursor.readPref()和Mongo.setReadPref()。
| maxStalenessSeconds |版本 3.4 中的新功能。
指定以秒为单位的秒数，表示 Client 机在停止将其用于读取操作之前会过时。有关详细信息，请参阅：maxStalenessSeconds。
默认情况下，没有最大的陈旧性，并且在选择将读取操作定向到何处时，Client 端不会考虑辅助节点的延迟。
maxStalenessSeconds的最小值是 90 秒。指定 0 到 90 秒之间的值将产生错误。 MongoDB 驱动程序将-1的maxStalenessSeconds值视为“没有最大陈旧性”，与省略maxStalenessSeconds一样。

有关更多信息，请参见Read preferences。

Authentication Options

以下到副本集的连接字符串指定authSource到admin数据库。也就是说，用户凭据已通过admin数据库认证。

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

如果用户名或密码包含符号@，冒号:，斜杠/或百分号%字符，请使用percent encoding。

对于将凭据存储委派给其他服务的身份验证机制，与PLAIN(LDAP)和GSSAPI(Kerberos)身份验证机制一样，authSource值应为$external。
如果连接字符串未指定用户名，MongoDB 将忽略authSource个值。
| authMechanism |在 2.6 版中进行了更改：添加了对PLAIN和MONGODB-X509认证机制的支持。
在版本 3.0 中进行了更改：添加了对SCRAM-SHA-1身份验证机制的支持。
指定 MongoDB 将用于认证连接的认证机制。可能的值包括：
SCRAM-SHA-1
MONGODB-CR(* MongoDB 3.6 中已弃用*)
MONGODB-X509
GSSAPI (Kerberos)
PLAIN(LDAP SASL)
仅 MongoDB Enterprise mongod和mongos实例提供GSSAPI(Kerberos)和PLAIN(LDAP)机制。要使用MONGODB-X509，您必须启用 TLS/SSL。
有关 MongoDB 中身份验证系统的更多信息，请参见Authentication。另请考虑使用 x.509 证书对 Client 端进行身份验证以获取有关 x509 身份验证的更多信息。
| authMechanismProperties |将指定的authMechanism的属性指定为以逗号分隔的冒号分隔的键/值对列表。
可能的值为：
SERVICE_NAME:<string>
连接到 Kerberized MongoDB 实例时，设置 Kerberos 服务名称。该值必须与您要连接的 MongoDB 实例上设置的服务名称匹配。
所有 Client 端和 MongoDB 实例的SERVICE_NAME默认为mongodb。如果您在 MongoDB 实例上更改saslServiceName设置，则必须将SERVICE_NAME设置为与该设置匹配。
CANONICALIZE_HOST_NAME:true|false
连接到 Kerberos 服务器时，规范化 Client 端主机的主机名。当主机报告的主机名与 Kerberos 数据库中的主机名不同时，可能需要这样做。默认为false。
SERVICE_REALM:<string>
为 MongoDB 服务设置 Kerberos 领域。这对于支持跨域身份验证可能是必需的，在该身份验证中，用户位于一个领域中，而服务位于另一个领域中。

服务器选择和发现选项

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

所有驱动程序都使用localThresholdMS。将 await 时间窗口大小指定为mongos时，请使用localThreshold别名。
| serverSelectionTimeoutMS |指定在引发异常之前阻塞服务器选择的时间(以毫秒为单位)。 默认值：30,000 毫秒。
| serverSelectionTryOnce | 仅单线程驱动程序 。当true时，指示驱动程序在服务器选择失败后立即扫描 MongoDB 部署一次，然后选择服务器或引发错误。当false时，驱动程序将阻止并搜索最多serverSelectionTimeoutMS值的服务器。 默认：true。
多线程驱动程序和mongos不支持serverSelectionTryOnce。
| heartbeatFrequencyMS | heartbeatFrequencyMS控制驱动程序何时检查 MongoDB 部署的状态。指定两次检查之间的间隔(以毫秒为单位)，从上一次检查的结束到下一次检查的开始计算。
Default :
单线程驱动程序：60 秒。
多线程驱动程序：10 秒。
mongos不支持更改心跳检查的频率。|

Miscellaneous Configuration

可能的值为：
true
false。 3.6 驱动程序的默认值为false。
3.6 版中的新功能。
| uuidRepresentation |可能的值为：
standard
标准二进制表示形式。
csharpLegacy
C#驱动程序的默认表示。
javaLegacy
Java 驱动程序的默认表示。
pythonLegacy
Python 驱动程序的默认表示形式。
有关默认设置，请参见驱动程序的drivers文档。

Examples

以下提供了公共连接目标的示例 URI 字符串。

在本地运行的数据库服务器

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

mongodb://localhost

admin Database

以下内容以用户sysop的身份连接并使用密码moon登录到admin数据库：

mongodb://sysop:moon@localhost

records Database

以下内容以用户sysop的身份连接并使用密码moon登录到records数据库：

mongodb://sysop:moon@localhost/records

UNIX 域套接字

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

以下连接到文件路径为/tmp/mongodb-27017.sock的 UNIX 域套接字：

mongodb://%2Ftmp%2Fmongodb-27017.sock

副本集与不同计算机上的成员

以下连接到具有两个成员的replica set，一个在db1.example.net上，另一个在db2.example.net上：

mongodb://db1.example.net,db2.example.com/?replicaSet=test

副本集与 localhost 上的成员

以下连接到一个副本集，其中三个成员在端口27017，27018和27019的localhost上运行：

mongodb://localhost,localhost:27018,localhost:27019/?replicaSet=test

具有读取分布的副本集

以下内容连接到具有三个成员的副本集，并将读取结果分发到secondaries：

mongodb://example1.com,example2.com,example3.com/?replicaSet=test&readPreference=secondary

副本集具有较高的写入问题

以下内容连接到具有写关注点的副本集，该副本集被配置为 await 跨大多数数据承载投票成员的复制成功，并具有两秒钟的超时时间。

mongodb://example1.com,example2.com,example3.com/?replicaSet=test&w=majority&wtimeoutMS=2000

Sharded Cluster

以下连接到具有三个mongos实例的分片群集：

mongodb://router1.example.com:27017,router2.example2.com:27017,router3.example3.com:27017/