MongoDB 5.0 中的兼容性更改

以下 5.0 变更可能会影响与旧版本 MongoDB 的兼容性。

某些命令只接受可被识别的参数

从 MongoDB 5.0 开始，如果传递的参数未被命令显式接受，则某些数据库命令会抛出错误。在 MongoDB 4.4 及更早版本中，无法被识别的参数会被默默忽略。

受影响的命令：

已删除的命令

从 MongoDB 5.0 开始，已删除以下数据库命令和 mongo Shell 助手方法：

已删除的命令	替代方案
`db.collection.copyTo()`	`$out`
`db.collection.ensureIndex()`	`db.collection.createIndex()`
`db.collection.save()`	`db.collection.insertOne()` `db.collection.insertMany()`
`db.resetError()`	不可用
`geoSearch`	地理空间查询运算符之一
`Mongo.getSecondaryOk()`	Mongo.getReadPrefMode()
`Mongo.isCausalConsistency`	不可用
`Mongo.setSecondaryOk()`	Mongo.setReadPref()
`rs.secondaryOk()`	Mongo.setReadPref()
`resetError`	不可用
`shardConnPoolStats`	`connPoolStats`
`unsetSharding`	不可用

删除的参数

MongoDB 5.0 删除了以下服务器参数：

删除的参数	说明
`cachePressureThreshold`	MongoDB 5.0 删除了 `cachePressureThreshold` 服务器参数。由于 WiredTiger 计算快照窗口大小的方式发生了变化，该参数已不再适用。
`shouldMultiDocTxnCreateCollectionAndIndexes`	MongoDB 5.0 删除了 `shouldMultiDocTxnCreateCollectionAndIndexes` 服务器参数。在 5.0+ 版本中，事务内部的集合和索引创建将始终被允许。您不能再使用该服务器参数来禁用此行为。
`connPoolMaxShardedConnsPerHost`	MongoDB 5.0 删除了 `connPoolMaxShardedConnsPerHost` 服务器参数。
`connPoolMaxShardedInUseConnsPerHost`	MongoDB 5.0 删除了 `connPoolMaxShardedInUseConnsPerHost` 服务器参数。
`shardedConnPoolIdleTimeoutMinutes`	MongoDB 5.0 删除了 `shardedConnPoolIdleTimeoutMinutes` 服务器参数。

已删除的索引类型

MongoDB 5.0删除了已弃用的geoHaystack索引。请改用2 d 索引。

将 MongoDB 实例升级到 5.0 并将 FeatureCompatibilityVersion 设置为 5.0 会删除所有先前存在的 geoHaystack 索引。

已删除的指标

从 MongoDB 5.0 开始，serverStatus 命令不会输出 opReadConcernCounters，其中包含查询操作指定的读关注（read concern）级别。新的 readConcernCounters 取代了 opReadConcernCounters，并包含其他信息。

从 MongoDB 5.0 开始，serverStatus 命令不会输出 wiredTiger.snapshot-window-settings 下的 cache pressure percentage threshold 和 current cache pressure percentage。

`currentOp` 输出变化

从 MongoDB 5.0 开始，$currentOp.remainingOperationTimeEstimated 指标仅在执行重新分片操作时会出现在接收分片上。

删除了对 Raspberry Pi 的支持

MongoDB 5.0 移除了对 Raspberry Pi 的支持。要在 Raspberry Pi 上运行 MongoDB，请安装版本 4.4。

设置为 `NaN` 时的 TTL `expireAfterSeconds` 行为

从 MongoDB 5.0 开始，将 expireAfterSeconds 设置为 NaN 的 TTL 索引与早期版本相比发生了行为更改。

此行为更改会影响：

直接升级
早期版本的初始同步
mongorestore 早期版本的

执行任意上述操作均会导致 NaN 的 expireAfterSeconds 值被视为 0 的 expireAfterSeconds。这可能会导致文档立即过期。

从 MongoDB 5.0.14（和 6.0.2）开始，服务器将不再使用将 expireAfterSeconds 设置为 NaN 的 TTL 索引。

Shell 变更

mongo Shell 在 MongoDB v5.0 中已被弃用。替换 Shell 为 mongosh。

MongoDB v5.0 中的 Shell 打包方式也有变更。更多详情，请参阅安装说明。

副本集

`enableMajorityReadConcern` 不可配置

从 MongoDB 5.0 开始，由于改进了存储引擎，enableMajorityReadConcern 和 --enableMajorityReadConcern 不可更改，并始终设置为 true。

在 MongoDB 的早期版本中，enableMajorityReadConcern 和 --enableMajorityReadConcern 均可配置，可以设置为 false，以防止由三个节点组成的主-从-仲裁 (PSA) 架构的部署因存储缓存压力而停止运行。

如使用主节点-从节点-仲裁节点 (PSA) 三成员架构，请考虑以下因素：

如果从节点不可用或滞后，写关注 "majority" 可能会导致性能问题。有关如何缓解这些问题的建议，请参阅缓解自管理 PSA 副本集的性能问题。
如果使用的全局默认值 "majority"，并且写关注小于大多数的大小，则您的查询可能会返回过时（未完全复制）的数据。

`secondaryDelaySecs` 配置设置

从 MongoDB 5.0 开始，secondaryDelaySecs 将取代 slaveDelay。此变更不向后兼容。

水平分割 DNS 所需的主机名

要为水平分割 DNS 配置集群节点，请使用主机名称，而非 IP 地址。

从 MongoDB v5.0 开始，replSetInitiate 和 replSetReconfig 拒绝使用 IP 地址而不是主机名的配置。

使用 disableSplitHorizonIPCheck 修改无法更新为使用主机名的节点。该参数仅适用于配置命令。

mongod 和 mongos 在启动时不依赖 disableSplitHorizonIPCheck 进行验证。使用 IP 地址而不是主机名的旧版 mongod 和 mongos 实例可以在升级后启动。

配置 IP 地址的实例会记录警告，要求使用主机名称而非 IP 地址。

非事务性读取 `config.transactions`

从 MongoDB 5.0 开始，不允许对具有以下读关注（read concern）和选项的 config.transactions 集合进行非事务性读取：

"snapshot"
"majority"，且设置了 afterClusterTime 选项
在一个因果一致的会话中使用 MongoDB 驱动程序和 "majority" 时

手动 Oplog 写入

从 MongoDB 5.0 开始，不再支持在作为副本集运行的集群上对 oplog 执行手动写入操作。作为独立实例运行时对 oplog 执行写入操作只能在 MongoDB 支持团队的指导下完成。

对副本集中新的投票节点的自动重新配置

从 MongoDB 5.0 开始，新添加的从节点在未达到 SECONDARY 状态之前将不被计为投票节点，并且无法被选为主节点。

当一个新的投票节点被添加到副本集时，replSetReconfig 将从内部向该节点的配置中添加一个 newlyAdded 字段。带有 newlyAdded 字段的节点不会被计入当前的投票节点数。当初始同步完成且节点达到 SECONDARY 状态后，newlyAdded 字段将被自动删除。

注意

即使使用 { force: true } 运行，尝试添加名为 newlyAdded 的字段的配置也会出错。
如果现有节点有一个 newlyAdded 字段，使用 rs.reconfig() 更改配置将不会删除 newlyAdded 字段。newlyAdded 字段将被附加到用户提供的配置中。
replSetGetConfig 将删除输出中的所有 newlyAdded 字段。如果您想查看任何 newlyAdded 字段，可以直接查询 local.system.replset 集合。

删除了 getLastErrorDefaults 的自定义值

从 MongoDB 5.0 开始，除了默认值 { w: 1, wtimeout: 0 } 之外，您不能使用settings.getLastErrorDefaults 来指定默认写关注（write concern）。相反，请使用 setDefaultRWConcern 命令为副本集或分片集群设置默认的读关注（read concern）或写关注（write concern）配置。

副本集写入确认

从 MongoDB 5.0 开始，处于 STARTUP2 状态的副本集节点不参与对写入操作的多数节点确认。

提示

另请参阅：

副本集的写关注

隐式默认写关注

从 MongoDB 5.0 开始，隐式默认写关注为 w: majority。但是，对于包含仲裁节点的部署，需要特别考虑以下事项：

副本集的投票多数是 1 加投票成员数量的一半，四舍五入。如果数据承载投票成员的数量不超过投票多数，则默认写关注为 { w: 1 }。
在所有其他场景中，默认写关注为 { w: "majority" }。

具体来说，MongoDB 使用以下公式来确定默认写关注：

if [ (#arbiters > 0) AND (#non-arbiters <= majority(#voting-nodes)) ]
    defaultWriteConcern = { w: 1 }
else
    defaultWriteConcern = { w: "majority" }

例如，考虑以下部署以及各自的默认写关注：

Non-Arbiters	仲裁节点	投票节点	多数投票节点	隐式默认写关注
2	1	3	2	`{ w: 1 }`
4	1	5	3	`{ w: "majority" }`

在第一个示例中：
- 有 2 个非仲裁节点和 1 个仲裁节点，共有 3 个投票节点。
- 多数投票节点（1 加 3 的一半，四舍五入）为 2。
- 非仲裁节点的数量 (2) 等于多数投票节点 (2)，导致隐式写关注为 { w: 1 }。
在第二个示例中：
- 共有 5 个投票节点，其中有 4 个非仲裁节点和 1 个仲裁节点。
- 多数投票节点（1 加 5 的一半，四舍五入）为 3。
- 非仲裁节点的数量 (4) 大于多数投票节点 (3)，导致隐式写关注为 { w: "majority" }。

如果发生选举或副本集成员不可用，{ w: "majority" } 默认写关注可提供更强的持久性保证。

针对固定大小集合的读关注 `snapshot`

从 MongoDB 5.0 开始，从固定大小集合进行读取时无法使用读关注（read concern） "snapshot"。

`local` 为默认读关注（read concern）

从 MongoDB 5.0 开始，"local" 是针对主节点和从节点的读取操作的默认读关注（read concern）级别。

对于使用过滤器的计数查询以及覆盖查询来说，这可能会导致显著的延迟增长。

您可以通过使用 setDefaultRWConcern 设置集群范围的读关注（read concern）来更改此默认行为。

新增 `cursor.map()` 返回类型

cursor.map() 在旧版 mongo shell 中返回 Array。返回类型为 mongosh 中的 Cursor。您可以使用 .toArray() 来转换结果。

更新操作符变更

从 MongoDB 5.0 开始，使用以下带空操作数表达式 ({ }) 的更新操作符时，mongod 不会再抛出错误。

空更新不会导致任何变化，也不会创建 oplog 条目（意味着该操作为“无操作”）。

更新操作符处理顺序

从 MongoDB 5.0 开始，更新操作符按字典顺序处理具有基于字符串的名称的文档字段。具有数字名称的字段按数字顺序处理。详情请参阅更新操作符行为。

`$setWindowFields` 具有事务和快照读取关注的阶段

在 5.3 之前的 MongoDB 版本中，$setWindowFields 聚合管道阶段不能与事务或 "snapshot" 读关注一起使用。

聚合管道操作符参数限制

以下聚合管道操作符现在有 64 位整数值的最大限制。

如果传递的值超过此限制，管道将返回无效参数错误。

`listDatabases` 输出变更

从 MongoDB 5.0 开始，针对 mongod 运行的 listDatabases 命令与针对 mongos 运行的 listDatabases 有更加一致的输出。

下表显示了 MongoDB 5.0 和早期版本之间 listDatabases 输出字段的数据类型差异。下表仅列出了在 5.0 版本和早期版本之间存在差异的字段。

字段	MongoDB 5.0 中的类型	MongoDB 4.4 及更早版本中的类型 (`mongod`)	MongoDB 4.4 及更早版本中的类型 (`mongos`)
`sizeOnDisk`	整型	double	整型
`totalSize`	整型	double	整型
`totalSizeMb`	整型	未提供（见下文）	整型

现在，在对 mongos 或 mongod 运行时，listDatabases 的输出包含了 totalSizeMb 字段。在 MongoDB 4.4 及更早版本中，totalSizeMb 仅在对 mongos 运行时出现。totalSizeMb 是 sizeOnDisk 字段的总和，以兆字节为单位。

在对 mongos 运行时，listDatabases 输出中的 shards 字段包含特定分片上每个集合的字段-值对。shards 字段中的大小值将以整数表示。

安全性

TLS 连接 X509 证书启动警告

从 MongoDB 5.0 开始，mongod 和 mongos 现在会在其证书不包含主题备用名称属性时，在启动阶段发出警告。

以下平台不支持通用名称验证：

iOS 13 及更高版本
MacOS 10.15 及更高版本
Go 1.15 及更高版本

使用这些平台的客户端不会向使用 x.509 证书（其主机名由 CommonName 属性指定）的 MongoDB 服务器进行身份验证。

Map-Reduce

从 5.0 版开始，MongoDB 弃用了 map-reduce 操作。

有关 map-reduce 操作的聚合管道版替代方案的示例，请参阅 Map-Reduce 到聚合管道和 Map-Reduce 示例

审核

MongoDB 5.0 新增了可以在运行时配置的审核功能。

如果将 auditLog.runtimeConfiguration 设置为 true， mongod 和 mongos 配置文件将无法再设置 setParameter.auditAuthorizationSuccess 或配置审核过滤器。如果服务器配置文件包含这些设置，服务器将无法启动并记录错误。

如果将 auditLog.runtimeConfiguration 设置为 false 并且存在审核过滤器配置文档，则服务器会发出启动警告，但不会中止。

降低分片事务中数据块过期的风险

从 MongoDB 5.0 开始，如果您更改了 transactionLifetimeLimitSeconds 参数，您还必须在所有配置服务器副本集节点上将 transactionLifetimeLimitSeconds 更改为相同的值。保持该值一致将会：

确保路由表历史记录的保留时间至少达到分片副本集成员的事务生命周期限制。
降低事务重试频率，从而提高性能。

一般性变更

从 MongoDB 5.0 开始：

如果将 featureCompatibilityVersion 设置为 "5.0" 或更高版本，用户将无法再直接向 <database>.system.views 集合写入数据。
reIndex 命令和 db.collection.reIndex() Shell 方法只能在独立运行的实例上运行。
单个管道中允许的聚合管道阶段最大数量为 1000 个。
当启用了 directoryPerDB 或 --directoryperdb 时，删除数据库中的最后一个集合（或删除数据库本身）将删除该数据库新的空子目录。
如有必要，$subtract 聚合操作符将转换结果的数据类型，以便准确表示结果值。有关具体的转换，请参阅 $subtract。
MongoDB 删除 --serviceExecutor 命令行选项和相应的 net.serviceExecutor 配置选项。
如果设置了 --apiStrict 选项，就不能在同一客户端会话中同时以多个用户身份进行身份验证。如果设置了 --apiStrict 选项，则当前现有用户身份登录后，如果尝试以新用户身份进行身份验证，将在每次身份验证尝试时生成一条错误消息。如果不使用 --apiStrict选项，则当前以现有用户身份登录后，如果以新用户身份进行身份验证，将在每次身份验证尝试时向日志写入一次警告。
只有 $text 索引才允许使用权重选项。
在尝试使用会改变隐式默认写关注（write concern）的配置重新配置一个非分片的副本集之前，您必须显式设置全局默认写关注。要设置全局默认写关注，请使用 setDefaultRWConcern 命令。
要在 mongosh 中设置 replSetOplog 大小，请使用 Double() 构造函数和 replSetResizeOplog 命令。

弃用

已弃用	说明
`mongo`	MongoDB v5.0 已弃用旧版 `mongo` Shell。其替代品为 `mongosh`。
`db.printSlaveReplicationInfo()`	自版本 4.4.1 起已弃用：改用 `db.printSecondaryReplicationInfo()`。
`rs.printSlaveReplicationInfo()`	自版本 4.4.1 起已弃用：改用 `rs.printSecondaryReplicationInfo()`。
`security.clusterIpSourceWhitelist`	在版本 5.0 中已被弃用：使用 `security.clusterIpSourceAllowlist` 代替。
`--clusterIpSourceWhitelist`	在版本 5.0 中已被弃用：使用 `--clusterIpSourceAllowlist` 代替。
`logout`	在版本 5.0 中已被弃用：改为从服务器断开连接以结束会话。
`db.logout()`	在版本 5.0 中已被弃用：改为从服务器断开连接以结束会话。
本地审核消息字段	在版本 5.0 中已被弃用：改用 clientMetadata 审核消息中的 `localEndpoint` 字段。

已弃用的传输协议操作码

MongoDB 5.0 弃用了以下传输协议操作码：

OP_REPLY
OP_UPDATE
OP_INSERT
OP_QUERY
OP_GET_MORE
OP_DELETE
OP_KILL_CURSORS

较新的驱动程序版本使用 OP_MSG 代替这些已弃用的操作码。

相关命令和方法在 MongoDB 5.0 中也被弃用：

getLastError
db.getLastError()
db.getLastErrorObj()

为了确保您的驱动程序使用的是最新传输协议，请将驱动程序升级到 5.0 兼容版本。

凡显式使用 getLastError、db.getLastError() 或 db.getLastErrorObj() 的代码都应改用 CRUD API 来执行具有所需写关注（write concern）的写入操作。有关写入操作是成功还是失败的信息将作为一个值由驱动程序直接返回。

5.0 功能兼容性

中的某些功能不仅需要5.0 5.05.0二进制文件，还需要将 featureCompatibilityVersion (FCV)设立为。这些功能包括：

创建时间序列集合需要将FCV设立为5.0 +。
配置运行时审核筛选器管理需要将FCV设立为5.0 +。
在字段名称中使用 . 和 $ 需要将FCV设立为 5.0+。
对集合重新分片需要将FCV设立为5.0 +。

后退

5.0

来年

将4.4升级到5.0