文档数据库 MongoDB 版支持在实例的连接地址中通过指定参数实现读写分离。本文介绍如何设置相关参数实现读写分离。

背景信息

文档数据库 MongoDB 版为副本集实例和分片集群实例的 Mongos 组件默认提供了高可用地址，该地址包含副本集实例所有节点或分片集群中所有 Mongos 节点的地址，发生主从切换后，写请求将会被路由到新的主节点或其他 Mongos 节点上，不会出现无法执行写操作的情况。更多关于 MongoDB 实例连接地址的说明，请参见查看连接地址。

读写分离参数介绍

文档数据库 MongoDB 版支持在高可用地址中使用 readPreference 和 readPreferenceTags 参数实现读写分离。

参数	说明	支持使用对应参数的连接地址类型
readPreference	用于实现高可用地址的读写分离和负载均衡。该参数可以将写请求发送到主节点，读请求随机发送到从节点和只读节点，可选取值如下： readPreference=primary：读请求仅发送到主节点。 readPreference=primaryPreferred：优先读主节点。如果主节点故障，将读请求发送到从节点和只读节点。 readPreference=secondary：仅读从节点和只读节点。如果从节点和只读节点都出现故障，读请求失败，不会发送到主节点。 readPreference=secondaryPreferred：优先读从节点和只读节点。如果从节点和只读节点都出现故障，该参数将读请求发送到主节点。说明关于 readPreference 参数的更多详情，请参见 Read Preference。	副本集实例连接地址。分片集群实例中 Mongos、Shard、 ConfigServer 组件连接地址。说明分片集群实例中的 Shard 或 ConfigServer 组件连接地址主要用于测试或其他特殊场景，在实际生产环境中，不推荐直连 Shard 或 ConfigServer 组件地址进行读写，推荐使用分片集群的 Mongos 地址，并通过 Mongos 连接地址实现负载均衡路和读写分离。文档数据库 MongoDB 版默认仅提供了 Mongos 私网连接地址，如需使用 Shard 或 ConfigServer 组件连接地址需单独申请。具体操作步骤，请参见申请私网地址和申请公网地址。
readPreferenceTags	该参数可以将读请求发送到标签对应的节点。可选取值如下： readPreferenceTags=role:electable：读请求发送到从节点。 readPreferenceTags=role:readonly：读请求发送到只读节点。说明创建时间在 2025 年 11 月 27 日之前的实例如需设置 readPreferenceTags=role:electable，需先在实例的连接管理页签下，打开读写分离的分离增强功能开关。分离增强功能开关打开后不支持关闭。创建时间在 2025 年 11 月 27 日及之后的 MongoDB 实例默认支持设置readPreferenceTags=role:electable，在连接地址中直接设置该参数即可。该参数通常与参数 readPreference 一起使用实现读写分离功能，但与 primary 模式不兼容。仅当实例中存在只读节点时， readPreferenceTags=role:readonly 设置才会生效。只读节点使用方法，请参见添加或删除只读节点。关于 readPreferenceTags 参数的更多详情，请参见 readPreferenceTags。	副本集实例连接地址。分片集群实例中 Mongos、Shard 组件连接地址。

设置读写分离连接地址

您可以根据业务需求，在 MongoDB 实例的高可用地址中通过设置 readPreference 和 readPreferenceTags 参数，来满足不同场景下的读写分离需求。

读从或只读节点失败时，读请求发送到主节点

读从或只读节点失败时，读请求不发送到主节点

读请求发送策略及读写分离参数设置建议

读请求发送策略	参数设置建议
优先读主节点。	readPreference=primaryPreferred
优先读从节点和只读节点。	readPreference=secondaryPreferred
优先读从节点。如果从节点故障，读请求将发送到主节点，不会发送到只读节点。	readPreference=secondaryPreferred&readPreferenceTags=role:electable
优先读只读节点。如果只读节点故障，读请求将发送到主节点，不会发送到从节点。	readPreference=secondaryPreferred&readPreferenceTags=role:readonly

读写分离连接地址示例

如下示例以 MongoDB 副本集实例的连接地址为例，为实例设置优先读只读节点，如果只读节点故障，读请求发送到主节点。

mongodb://root:Pwd_123456@mongoreplicab338d0d1****0.mongodb.ivolces.com:3717,mongoreplicab338d0d1****1.mongodb.ivolces.com:3717,mongoreplicab338d0d1****100.mongodb.ivolces.com:3717/?authSource=admin&replicaSet=rs-mongo-replica-b338d0d1a007&readPreference=secondaryPreferred&readPreferenceTags=role:readonly&retryWrites=true

常见问题

如何查看 MongoDB 实例的连接使用情况？

如何查看连接 MongoDB 实例的客户端来源？

如何限制访问 MongoDB 实例的客户端连接数？

为副本集实例新增节点或为分片集群新增 Mongos 节点后，需要修改应用程序的连接地址代码才能连上新增节点吗？

文档数据库 MongoDB 版是否支持 SRV 的连接方式？

如何查看 MongoDB 连接地址对应的 IP 地址?

是否支持修改 MongoDB 连接地址的域名？

文档数据库 MongoDB 版是否支持读写分离功能？

读请求发送策略	参数设置建议
仅读从节点和只读节点。	readPreference=secondary
仅读从节点，如果从节点故障，读取操作失败。	readPreference=secondary&readPreferenceTags=role:electable
仅读只读节点，如果只读节点故障，读取操作失败。	readPreference=secondary&readPreferenceTags=role:readonly