连接字符串 URI 格式
在本页面
本文档介绍了用于定义使用 MongoDB drivers和 MongoDB 实例的应用程序之间的连接的 URI 格式。
连接字符串格式
您可以使用以下任一方式指定 MongoDB 连接字符串：
the DNS 种子列表连接格式.
标准连接字符串格式
本部分描述用于连接到 MongoDB 部署的 MongoDB 连接 URI 的标准格式：独立，副本集或分片群集。
标准 URI 连接方案具有以下形式：
mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[database][?options]]
Examples
Standalone
Replica Set
Sharded Cluster
- For a standalone:
mongodb://mongodb0.example.com:27017/admin
- For a standalone that enforces access control:
mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017/admin
If the username or password includes the at sign @ , colon : , slash / , or the percent sign % character, use percent encoding.
Note
For a replica set, specify the hostname of the mongod instance as listed in the replica set configuration.
For a replica set, include the replicaSet option.
- For a replica set:
mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/admin?replicaSet=myRepl
- For a replica set that enforces access control, include user credentials:
mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/admin?replicaSet=myRepl
If the username or password includes the at sign @ , colon : , slash / , or the percent sign % character, use percent encoding.
Note
For a connection string to a sharded cluster, specify mongos hosts in the connection string.
- For a sharded cluster:
mongodb://mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017/admin
- For a sharded cluster that enforces access control, include user credentials:
mongodb://myDBReader:D1fficultP%40ssw0rd@mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017/admin
If the username or password includes the at sign @ , colon : , slash / , or the percent sign % character, use percent encoding.
有关更多示例，请参见Examples。
Components
标准 URI 连接字符串包括以下组件：
mongodb:// |
标识这是标准连接格式的字符串的必需前缀。 |
username:password@ |
可选的。身份验证凭据。如果指定，Client 端将在连接后尝试使用这些凭据登录到特定数据库。 |
如果用户名或密码包含符号@，冒号:，斜杠/或百分号%字符，请使用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.
Note
SRVLogging 返回的主机名必须与给定的主机名共享相同的父域(在此示例中为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
Note
如果没有可用的 DNS 记录与连接字符串中标识的主机名相对应，则mongodb+srv选项将失败。此外，使用+srv连接字符串修饰符会自动将ssl选项设置为true进行连接。可以通过在查询字符串中将ssl选项显式设置为false和ssl=false来覆盖此设置。
连接字符串选项
本节列出了标准连接字符串格式中使用的所有连接选项。
连接选项是成对的，格式如下：name=value。 value始终区分大小写。用＆字符(即&)分隔选项。在以下示例中，连接使用replicaSet和connectTimeoutMS选项：
mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000
Semi-colon separator for connection string arguments
为了提供向后兼容性，驱动程序当前接受分号(即;)作为选项分隔符。
副本集选项
以下连接字符串连接到名为myRepl的副本集，且成员在指定主机上运行：
mongodb://db0.example.com:27017,db1.example.com:27017,db2.example.com:27017/admin?replicaSet=myRepl
| Connection Option | Description |
|---|---|
replicaSet |
如果mongod是副本集的成员，则指定replica set的名称。 |
连接到副本集时，请将副本集成员的种子列表提供给 uri 的host[:port]组件。有关特定的详细信息，请参阅您的driver文档。
Connection Options
以下到副本集的连接字符串包括ssl=true选项：
mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&ssl=true
| Connection Option | Description |
|---|---|
ssl |
用于为连接启用或禁用 TLS/SSL 的布尔值： |
true：使用 TLS/SSL 启动连接。默认为DNS 种子列表连接格式。false：在没有 TLS/SSL 的情况下启动连接。缺省为标准连接字符串格式。 |
|
connectTimeoutMS |
超时之前尝试连接的时间(以毫秒为单位)。默认值是永不超时，尽管不同的驱动程序可能有所不同。请参阅driver文档。 |
socketTimeoutMS |
尝试超时之前在套接字上尝试发送或接收的时间(以毫秒为单位)。默认值是永不超时，尽管不同的驱动程序可能有所不同。请参阅driver文档。 |
compressors |
以逗号分隔的压缩字符串，以启用网络压缩以用于此 Client 端与mongod/mongos实例之间的通信。 您可以指定以下压缩器： snappy zlib(在 MongoDB 3.6 或更高版本中可用) 如果指定多个压缩器，则列出压缩器的 Sequences 以及通信启动器都很重要。例如，如果 Client 端指定以下网络压缩器 "zlib,snappy"，而mongod指定"snappy,zlib"，则 Client 端和mongod之间的消息将使用zlib。 |
Important
当双方都启用网络压缩时，消息将被压缩。否则，双方之间的消息将不被压缩。
如果各方不共享至少一个公共压缩器，则各方之间的消息将不被压缩。
从 MongoDB 3.6.10 开始，mongo shell 支持 uri 连接字符串选项compressors。|。
| zlibCompressionLevel |一个整数，如果对network compression使用zlib，则指定压缩级别。
您可以指定一个介于-1到9之间的整数值：
|价值|注意事项
| -1 |默认压缩级别，通常为6压缩。 |
| 0 |无压缩
| 1-9 |增加压缩级别但以速度为代价，具有：1提供最佳速度，但压缩最少，并且9提供最佳压缩效果，但速度最慢。 |
mongo shell 不支持。
连接池选项
大多数驱动程序实现某种连接池处理。某些驱动程序不支持连接池。有关连接池实现的更多信息，请参见driver文档。这些选项允许应用程序在连接到 MongoDB 部署时配置连接池。
| Connection Option | Description |
|---|---|
maxPoolSize |
连接池中的最大连接数。默认值为100。 |
minPoolSize |
连接池中的最小连接数。默认值为0。 |
Note
并非所有驱动程序都支持minPoolSize选项。有关驱动程序的信息，请参见drivers文档。
|
| maxIdleTimeMS |连接可以在池中保持空闲(直到被删除和关闭)的最大毫秒数。
> 并非所有驱动程序都支持此选项。
| waitQueueMultiple |驱动程序将maxPoolSize值乘以的数字，以提供允许 await 池中的连接可用的最大线程数。有关默认值，请参见/drivers文档。
> 并非所有驱动程序都支持此选项。
| waitQueueTimeoutMS |线程可以 await 连接可用的最长时间(以毫秒为单位)。有关默认值，请参见/drivers文档。
> 并非所有驱动程序都支持此选项。
写关注选项
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
| Connection Option | Description |
|---|---|
readConcernLevel |
隔离级别。可以接受以下值之一： |
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。
| Connection Option | Description |
|---|---|
readPreference |
指定此连接的replica set读取首选项。 |
读取的首选项值如下：
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一样。
Important
要使用maxStalenessSeconds，部署中的所有 MongoDB 实例必须使用 MongoDB 3.4 或更高版本。如果任何实例在 MongoDB 的早期版本上，则驱动程序或mongos将引发错误。
|
| readPreferenceTags |将tags document指定为以冒号分隔的键/值对的列表。例如，
> 要指定标签文档{ "dc": "ny", "rack": "r1" }，请在连接字符串中使用readPreferenceTags=dc:ny,rack:r1。
> 要指定空标签文档{ }，请使用readPreferenceTags=而不设置值。
> 要指定标签文档的列表，请使用多个readPreferenceTags。例如readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=。
> 使用多个readPreferenceTags时，Sequences 很重要。依次尝试readPreferenceTags直到找到匹配项。有关详细信息，请参见标签匹配 Sequences。
> 此连接字符串选项不适用于mongo shell。请参见cursor.readPref()和Mongo.setReadPref()。
有关更多信息，请参见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。
| Connection Option | Description |
|---|---|
authSource |
指定与用户凭据关联的数据库名称。 authSource默认为连接字符串中指定的数据库。 |
对于将凭据存储委派给其他服务的身份验证机制，与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 领域。这对于支持跨域身份验证可能是必需的，在该身份验证中，用户位于一个领域中，而服务位于另一个领域中。
Note
仅当authMechanism为GSSAPI时才支持authMechanismProperties选项。
|
| gssapiServiceName |设置连接到 Kerberized MongoDB 实例时的 Kerberos 服务名称。该值必须与您要连接的 MongoDB 实例上设置的服务名称匹配。
> 所有 Client 端和 MongoDB 实例的gssapiServiceName默认为mongodb。如果您在 MongoDB 实例上更改saslServiceName设置，则必须将gssapiServiceName设置为与该设置匹配。
> gssapiServiceName是authMechanismProperties=SERVICE_NAME:mongodb的不赞成使用的别名。有关驱动程序支持哪些选项以及彼此之间相对优先级的更多信息，请参考您首选驱动程序版本的文档。
服务器选择和发现选项
MongoDB 提供以下选项，以配置 MongoDB 驱动程序和mongos实例如何选择要将读取或写入操作定向到的服务器。
| Connection Option | Description |
|---|---|
localThresholdMS |
在多个合适的 MongoDB 实例中进行选择的 await 时间窗口的大小(以毫秒为单位)。 默认：15 毫秒。 |
所有驱动程序都使用localThresholdMS。将 await 时间窗口大小指定为mongos时，请使用localThreshold别名。
| serverSelectionTimeoutMS |指定在引发异常之前阻塞服务器选择的时间(以毫秒为单位)。 默认值：30,000 毫秒。
| serverSelectionTryOnce | 仅单线程驱动程序 。当true时，指示驱动程序在服务器选择失败后立即扫描 MongoDB 部署一次，然后选择服务器或引发错误。当false时，驱动程序将阻止并搜索最多serverSelectionTimeoutMS值的服务器。 默认：true。
多线程驱动程序和mongos不支持serverSelectionTryOnce。
| heartbeatFrequencyMS | heartbeatFrequencyMS控制驱动程序何时检查 MongoDB 部署的状态。指定两次检查之间的间隔(以毫秒为单位)，从上一次检查的结束到下一次检查的开始计算。
Default :
单线程驱动程序：60 秒。
多线程驱动程序：10 秒。
mongos不支持更改心跳检查的频率。|
Miscellaneous Configuration
| Connection Option | Description |
|---|---|
retryWrites |
Enable retryable writes. |
可能的值为：truefalse。 3.6 驱动程序的默认值为false。
3.6 版中的新功能。
| uuidRepresentation |可能的值为：standard
标准二进制表示形式。csharpLegacy
C#驱动程序的默认表示。javaLegacy
Java 驱动程序的默认表示。pythonLegacy
Python 驱动程序的默认表示形式。
有关默认设置，请参见驱动程序的drivers文档。
Note
并非所有驱动程序都支持uuidRepresentation选项。有关驱动程序的信息，请参见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
Note
并非所有驱动程序都支持 UNIX 域套接字。有关驱动程序的信息，请参见drivers文档。
副本集与不同计算机上的成员
以下连接到具有两个成员的replica set，一个在db1.example.net上，另一个在db2.example.net上：
Note
对于副本集，请指定副本集配置中列出的mongod实例的主机名。
mongodb://db1.example.net,db2.example.com/?replicaSet=test
副本集与 localhost 上的成员
以下连接到一个副本集，其中三个成员在端口27017，27018和27019的localhost上运行：
Note
对于副本集，请指定副本集配置中列出的mongod实例的主机名。
mongodb://localhost,localhost:27018,localhost:27019/?replicaSet=test
具有读取分布的副本集
以下内容连接到具有三个成员的副本集，并将读取结果分发到secondaries：
Note
对于副本集，请指定副本集配置中列出的mongod实例的主机名。
mongodb://example1.com,example2.com,example3.com/?replicaSet=test&readPreference=secondary
副本集具有较高的写入问题
以下内容连接到具有写关注点的副本集，该副本集被配置为 await 跨大多数数据承载投票成员的复制成功，并具有两秒钟的超时时间。
Note
对于副本集，请指定副本集配置中列出的mongod实例的主机名。
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/