mongodb 跨版本升级指南

描述

日常工作中，经常需要升级数据库版本，常常还面临跨版本的升级，每个版本升级前都会有一些需要注意的点，今天就把主要的流程和需要注意的点写下来，给需要升级数据库的你。

服务器分布

这是我假设的升级目标，从3.0升级到4.0。

10.204.11.102 3.2.11

10.204.11.133 3.0.6

10.204.11.159 3.0.6

3.0.6–>3.2.11(17)–>3.6.23–>4.0.10-5

官方原生版本变迁时间线

https://www.mongodb.com/docs/legacy/?site=docs

版本	首版发布时间	最新版本发布时间(截止20220812)
3.2	Jan 12, 2016	Dec 28, 2018
3.4	Dec 20, 2016	Jan 27, 2020
3.6	Dec 26, 2017	Mar 19, 2021
4.0	Aug 6, 2018	January 31, 2022
4.2	Oct 18, 2019	Jun 21, 2022
4.4	Sep 9, 2020	Jun 21, 2022
5.0	Aug 4, 2021	July 29, 2022

MongoDB 3.0 升级 3.2

兼容性变化

https://www.mongodb.com/docs/v3.2/release-notes/3.2-compatibility/

默认引擎从MMAPv1改为WiredTiger，配置文件需要指定

1 2	storage: engine: mmapv1

索引改变

2.1 不允许创建 version 0 indexes (i.e. {v: 0})，如果存在需要删除重建
1
2
use test
db.legacyOrders.dropIndex( "x_1" )
2.2 2dsphere index (version 3) 和 Text index (version 3) 和之前版本不兼容，如果库中存在此类索引，实例将不能启动。
MongoDB 3.2 changes the JavaScript engine from V8 to SpiderMonkey.
initial sync 阶段如果存在 renameCollection 操作，将导致数据冲突。

Operations that rename collections include:
- renameCollection command and db.collection.renameCollection() method.
- Aggregation (db.collection.aggregate() method or aggregate command) with the $out stage.
- Map-reduce (db.collection.mapReduce() method or mapReduce command) with the out option.
- convertToCapped command.
关于副本集配置文件的校验

5.1 非投票节点的priority必须设置为0
1
2
3
4
cfg = rs.conf()
cfg.members[n].votes = 0
cfg.members[n].priority = 0
rs.reconfig(cfg)
5.2 priority> 0 的节点不能成为非投票节点
A driver upgrade is necessary to support the find and getMore commands.
mongooplog is deprecated starting in MongoDB 3.2.

升级(副本集)

https://www.mongodb.com/docs/v3.2/release-notes/3.2-upgrade/

在开始升级之前，请查看MongoDB 3.2文档中的兼容性更改，以确保应用程序和部署与MongoDB 3.2兼容。开始升级之前，请解决部署中的不兼容问题。

升级之前需保证每个节点版本都是3.0.x，否则需要先统一节点版本。

1. 升级 secondary 节点

关闭节点，用新安装包替换旧安装包

重启节点，等待节点状态重新变为SECONDARY

2. 升级 primary 节点

执行 rs.stepDown()使主节点退位，强制重新选举，当确认新primary节点选举成功之后关闭当前节点，用新安装包替换旧安装包，重启节点。

MongoDB 3.2 升级 3.4

兼容性变化

https://www.mongodb.com/docs/v3.4/release-notes/3.4-compatibility/

initial sync 阶段如果存在 renameCollection 操作将导致数据冲突。

Operations that rename collections include:

renameCollection command and db.collection.renameCollection() method.
Aggregation (db.collection.aggregate() method or aggregate command) with the $out stage.
Map-reduce (db.collection.mapReduce() method or mapReduce command) with the out option.
convertToCapped command.

Deprecated Operations

group command and db.collection.group(). Use db.collection.aggregate() or db.collection.mapReduce() instead.
更严格的索引规范验证

3.1 当用db.collection.createIndex() 创建索引的时候需要确保 key: value 是合法的。规则如下：

Value Description

A number greater than 0 For ascending index

A number less than 0 For descending index

String “text”, “2dsphere”, “2d”, or “hashed” For special index types

如下在当前版本视为非法：
1
2
3
4
db.collection.createIndex( { x: 0 } );
db.collection.createIndex( { y: "text2d" } );
db.collection.createIndex( { z: NaN } );
db.collection.createIndex( { x: 1, unique: true } )
同时需要确保 index options 有效，之前版本的处理方式是如果无效就忽略。如下的规则将不再合法：
1
2
db.collection.createIndex( { y: 1 }, { uniques2: true} ); # 应该是 unique:true
db.collection.createIndex( { z: 1 }, { expireAfterSec: 350 } ) #应该是 expireAfterSeconds:350
库名不能包含 $ 符号
mongosniff 取代了 mongoreplay, 提供了更多功能特性

Value	Description
A number greater than 0	For ascending index
A number less than 0	For descending index
String “text”, “2dsphere”, “2d”, or “hashed”	For special index types

升级(副本集)

https://www.mongodb.com/docs/v3.4/release-notes/3.4-upgrade-replica-set/

在开始升级之前，请查看MongoDB 3.4文档中的兼容性更改，以确保应用程序和部署与MongoDB 3.4兼容。开始升级之前，请解决部署中的不兼容问题。

升级之前需保证每个节点版本都是3.2.x，否则需要先统一节点版本。

1. 升级 secondary 节点

关闭节点，用新安装包替换旧安装包

重启节点，等待节点状态重新变为SECONDARY

2. 升级 primary 节点

执行 rs.stepDown()使主节点退位，强制重新选举，当确认新primary节点选举成功之后关闭当前节点，用新安装包替换旧安装包，重启节点。

3. 启用向后不兼容的新版本特性

到第二步为止，版本特性还没有出现和上一个版本不兼容的情况，此步是为了启动新版本特性，并且此特性和上一个版本不兼容，开启之前需确保业务适应性，开启之后如要降级会变得复杂很多。

#此操作为幂等操作，如执行失败可重试
#只在primary节点执行 && 确保没有 initial sync  正在执行
use admin 
db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } )

#命令说明
db.adminCommand( { setFeatureCompatibilityVersion: <version> } )
<version>:
	"3.4" 启用新版本向后的不兼容特性
	"3.2" 关闭新版本特性

MongoDB 3.4 升级 3.6

兼容性变化

https://www.mongodb.com/docs/v3.6/release-notes/3.6-compatibility/

移除HTTP接口和REST API

#相关配置项
net.http.enabled
net.http.JSONPEnabled
net.http.port
net.http.RESTInterfaceEnabled

从3.6开始，不推荐使用MONGODB-CR身份验证机制。如尚未将MONGODB-CR身份验证模式升级到SCRAM，请参见 Upgrade to SCRAM
从3.6开始 Arbiter 节点的 Priority 应该设置为0。
主从模式已经被标记为即将弃用状态。
移除了过时的 diagLogging 命令和 mongod --diaglog 选项，使用 mongoreplay 替换。
向后的不兼容的特性
- UUID for collections
- $jsonSchema document validation
- Change Streams
- Chunk aware secondaries
- View definitions, document validators, and partial index filters that use 3.6 query features
- Sessions and retryable writes
- Users and roles with authenticationRestrictions

升级(副本集)

https://www.mongodb.com/docs/v3.6/release-notes/3.6-upgrade-replica-set/

在开始升级之前，请查看MongoDB 3.6文档中的兼容性更改，以确保应用程序和部署与MongoDB 3.6兼容。开始升级之前，请解决部署中的不兼容问题。

升级之前需保证每个节点版本都是3.4.x，否则需要先统一节点版本。

1. FCV(Feature Compatibility Version)特性兼容性版本确认

升级到3.6之前必须确保所有节点的FCV=3.4

#FCV查询
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )

#FCV设置(只需在primary节点设置)
db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } )

2. 节点状态确认

确保所有节点都不处于 ROLLBACK 或 RECOVERING 状态

3. 升级 secondary 节点

关闭节点，用新安装包替换旧安装包

重启节点，等待节点状态重新变为SECONDARY

4. 升级 primary 节点

执行rs.stepDown()使主节点退位，强制重新选举，当确认新primary节点选举成功之后关闭当前节点，用新安装包替换旧安装包，重启节点。

5. 启用向后不兼容的新版本特性

到第四步为止，版本特性还没有出现和上一个版本不兼容的情况，此步是为了启动新版本特性，并且此特性和上一个版本不兼容，开启之前需确保业务适应性，开启之后如要降级会变得复杂很多。

#此操作为幂等操作，如执行失败可重试
#只在primary节点执行 && 确保没有 initial sync  正在执行
use admin 
db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } )

#命令说明
db.adminCommand( { setFeatureCompatibilityVersion: <version> } )
<version>:
	"3.6" 启用新版本向后的不兼容特性
	"3.4" 关闭新版本特性

MongoDB 3.6 升级 4.0

兼容性变化

移除 MONGODB-CR，更多参见 Upgrade to SCRAM.

#查看认证方式
>use admin
> db.system.version.findOne()
{ "_id" : "authSchema", "currentVersion" : 5 }
其中 3:MONGODB-CR, 5:SCRAM

#升级
db.adminCommand({authSchemaUpgrade: 1})

MMAPv1 标记为弃用状态，更多参见 Change Replica Set to WiredTiger
Remove pv0 for Replica Sets

4.0之前副本集支持 pv0 和 pv1 ，从4.0开始只支持 pv1。升级方法：
1
2
3
4
#在 primary 节点执行
cfg = rs.conf();
cfg.protocolVersion=1;
rs.reconfig(cfg);
移除主从模式
移除 mongoperf

升级(副本集)

https://www.mongodb.com/docs/v4.0/release-notes/4.0-upgrade-replica-set/

在开始升级之前，请查看MongoDB 4.0文档中的兼容性更改，以确保应用程序和部署与MongoDB 4.0兼容。开始升级之前，请解决部署中的不兼容问题。

升级之前需保证每个节点版本都是3.6.x，否则需要先统一节点版本。

1. 检查驱动兼容性

在升级MongoDB之前，请检查使用的是MongoDB 4.0兼容的驱动程序，更多相关 driver documentation 。

2. Initial Syncs

开始升级之前，请确保没有正在进行的初始化同步。

3. 认证方式确认

确保所有节点没有使用 MONGODB-CR 认证方式。关于认证方式转换Upgrade to SCRAM.

4. Remove `pv0` for Replica Sets

mongodb 4.0 移除了对副本集协议版本 pv0 的支持，需要且必须升级到 pv1.

# 在primary节点执行
cfg = rs.conf();
cfg.protocolVersion=1;
rs.reconfig(cfg);

5. FCV(Feature Compatibility Version)特性兼容性版本确认

升级到4.0之前必须确保所有节点的FCV=3.6

#FCV查询
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )

#FCV设置(只需在primary节点设置)
db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } )

6. 节点状态确认

确保所有节点都不处于 ROLLBACK 或 RECOVERING 状态

7. 升级 secondary 节点

关闭节点，用新安装包替换旧安装包

重启节点，等待节点状态重新变为SECONDARY

8. 升级 primary 节点

执行rs.stepDown()使主节点退位，强制重新选举，当确认新primary节点选举成功之后关闭当前节点，用新安装包替换旧安装包，重启节点。

9. 启用向后不兼容的新版本特性

#此操作为幂等操作，如执行失败可重试
#只在primary节点执行 && 确保没有 initial sync  正在执行
use admin 
db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } )

#命令说明
db.adminCommand( { setFeatureCompatibilityVersion: <version> } )
<version>:
	"4.0" 启用新版本向后的不兼容特性
	"3.6" 关闭新版本特性

附录

MongoDB Drivers

Java

https://www.mongodb.com/docs/drivers/java/sync/current/

下面的兼容性表格指定了MongoDB Java驱动程序的推荐版本，用于特定版本的MongoDB。

Java Driver Version	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2	MongoDB 4.0	MongoDB 3.6	MongoDB 3.4	MongoDB 3.2	MongoDB 3.0	MongoDB 2.6
4.7	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
4.6		✓	✓	✓	✓	✓	✓	✓	✓	✓
4.5		✓	✓	✓	✓	✓	✓	✓	✓	✓
4.4		✓	✓	✓	✓	✓	✓	✓	✓	✓
4.3		✓	✓	✓	✓	✓	✓	✓	✓	✓
4.2			✓	✓	✓	✓	✓	✓	✓	✓
4.1			✓	✓	✓	✓	✓	✓	✓	✓
4.0				✓	✓	✓	✓	✓	✓	✓
3.12				✓	✓	✓	✓	✓	✓	✓
3.11				✓	✓	✓	✓	✓	✓	✓
3.10					✓	✓	✓	✓	✓	✓
3.9					✓	✓	✓	✓	✓	✓
3.8					✓	✓	✓	✓	✓	✓
3.7						✓	✓	✓	✓	✓
3.6						✓	✓	✓	✓	✓
3.5							✓	✓	✓	✓
3.4							✓	✓	✓	✓
3.3								✓	✓	✓
3.2								✓	✓	✓
3.1									✓	✓
3.0									✓	✓

下面的兼容性表格指定了MongoDB Java驱动程序的推荐版本，用于特定版本的Java。

Java Driver Version	Java 17	Java 11	Java 8	Java 7	Java 6
4.7	✓	✓	✓
4.6	✓	✓	✓
4.5	✓	✓	✓
4.4	✓	✓	✓
4.3		✓	✓
4.2		✓	✓
4.1		✓	✓
4.0		✓	✓
3.12		✓	✓	✓	✓
3.11		✓	✓	✓	✓
3.10		✓	✓	✓	✓
3.9		✓	✓	✓	✓
3.8		✓	✓	✓	✓
3.4		✓	✓	✓	✓
3.3		✓	✓	✓	✓
3.2		✓	✓	✓	✓
3.1		✓	✓	✓	✓
3.0		✓	✓	✓	✓

PHP

https://www.mongodb.com/docs/drivers/php/

MongoDB PHP驱动程序包含两个组件:

The extension, which provides a low-level API and mainly serves to integrate libmongoc and libbson with PHP.
The library, which provides a high-level API for working with MongoDB databases consistent with other MongoDB language drivers.

安装说明:

下面的兼容性表格指定了与特定版本的MongoDB一起使用的PHP驱动程序的推荐版本。

PHP Driver Versions	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2	MongoDB 4.0	MongoDB 3.6	MongoDB 3.4	MongoDB 3.2	MongoDB 3.0	MongoDB 2.6
ext 1.14 + lib 1.13	✓	✓	✓	✓	✓	✓
ext 1.13 + lib 1.12	⊛	✓	✓	✓	✓	✓
ext 1.12 + lib 1.11	⊛	✓	✓	✓	✓	✓	✓	✓	✓
ext 1.11 + lib 1.10	⊛	✓	✓	✓	✓	✓	✓	✓	✓
ext 1.10 + lib 1.9	⊛	✓ [1]	✓	✓	✓	✓	✓	✓	✓
ext 1.9 + lib 1.8	⊛	⊛	✓	✓	✓	✓	✓	✓	✓
ext 1.8 + lib 1.7	⊛	⊛	✓	✓	✓	✓	✓	✓	✓
ext 1.7 + lib 1.6	⊛	⊛	⊛	✓	✓	✓	✓	✓	✓
ext 1.6 + lib 1.5	⊛	⊛	⊛	✓	✓	✓	✓	✓	✓
ext 1.5 + lib 1.4	⊛	⊛	⊛	⊛	✓	✓	✓	✓	✓
ext 1.4 + lib 1.3						✓	✓	✓	✓	✓
ext 1.3 + lib 1.2							✓	✓	✓	✓
ext 1.2 + lib 1.1							✓	✓	✓	✓
ext 1.1 + lib 1.0								✓	✓	✓
ext 1.0									✓	✓

✓	All features are supported.
⊛	The Driver version will work with the MongoDB version, but not all new MongoDB features are supported.

[1] The extension 1.10 + library 1.9 driver does not support snapshot reads on secondaries

下面的兼容性表指定了用于特定PHP版本的PHP驱动程序的推荐版本。

PHP Driver Versions	PHP 8.1	PHP 8.0	PHP 7.4	PHP 7.3	PHP 7.2	PHP 7.1	PHP 7.0	PHP 5.6	PHP 5.5
ext 1.14 + lib 1.13	✓	✓	✓	✓	✓
ext 1.13 + lib 1.12	✓	✓	✓	✓	✓
ext 1.12 + lib 1.11	✓	✓	✓	✓	✓
ext 1.11 + lib 1.10		✓	✓	✓	✓	✓
ext 1.10 + lib 1.9		✓	✓	✓	✓	✓
ext 1.9 + lib 1.8		✓	✓	✓	✓	✓	✓
ext 1.8 + lib 1.7			✓	✓	✓	✓	✓
ext 1.7 + lib 1.6			✓	✓	✓	✓	✓	✓
ext 1.6 + lib 1.5			✓	✓	✓	✓	✓	✓
ext 1.5 + lib 1.4				✓	✓	✓	✓	✓	✓
ext 1.4 + lib 1.3					✓	✓	✓	✓	✓
ext 1.3 + lib 1.2					✓	✓	✓	✓	✓

Python

下面的兼容性表指定了MongoDB Python驱动程序的推荐版本，用于特定版本的MongoDB。

PyMongo Driver Version	MongoDB 6.0	MongoDB 5.0	MongoDB 4.4	MongoDB 4.2	MongoDB 4.0	MongoDB 3.6	MongoDB 3.4	MongoDB 3.2	MongoDB 3.0	MongoDB 2.6
4.2	✓	✓	✓	✓	✓	✓
4.1	⊛	✓	✓	✓	✓	✓
4.0	⊛	✓	✓	✓	✓	✓
3.12	⊛	✓	✓	✓	✓	✓	✓	✓	✓	✓
3.11	⊛	⊛	✓	✓	✓	✓	✓	✓	✓	✓
3.10	⊛	⊛	⊛	✓	✓	✓	✓	✓	✓	✓
3.9	⊛	⊛	⊛	✓	✓	✓	✓	✓	✓	✓
3.8	⊛	⊛	⊛	⊛	✓	✓	✓	✓	✓	✓
3.7	⊛	⊛	⊛	⊛	✓	✓	✓	✓	✓	✓
3.6						✓	✓	✓	✓	✓
3.5							✓	✓	✓	✓
3.4							✓	✓	✓	✓
3.3								✓	✓	✓
3.2								✓	✓	✓
3.1									✓	✓
3.0									✓	✓
2.9									✓	✓
2.8									✓	✓
2.7										✓

下面的兼容性表指定了MongoDB Python驱动程序的推荐版本，用于特定版本的Python。

Python 3 Compatibility

PyMongo Driver Version	Python 3.10 [2]	Python 3.9	Python 3.8	Python 3.7	Python 3.6	Python 3.5	Python 3.4	Python 3.3	PyPy3	Python 3.2	Python 3.1
4.2	✓	✓	✓	✓
4.1	✓	✓	✓	✓	✓ [3]
4.0	✓	✓	✓	✓	✓
3.12	✓	✓	✓	✓	✓	✓	✓		✓
3.11		✓	✓	✓	✓	✓	✓		✓
3.10			✓	✓	✓	✓	✓		✓
3.9				✓	✓	✓	✓		✓
3.8				✓	✓	✓	✓		✓
3.7				✓	✓	✓	✓		✓
3.6					✓	✓	✓		✓
3.5					✓	✓	✓	✓	✓
3.4						✓	✓	✓	✓
3.3						✓	✓	✓	✓
3.2						✓	✓	✓	✓	✓
3.1						✓	✓	✓	✓	✓
3.0							✓	✓	✓	✓
2.9					✓	✓	✓	✓	✓	✓	✓
2.8							✓	✓	✓	✓	✓
2.7							✓	✓	✓	✓	✓

Python 2 Compatibility

PyMongo Driver Version	Python 2.7, PyPy	Python 2.6	Python 2.5, Jython 2.5	Python 2.4
4.1 [1]
4.0 [1]
3.12	✓
3.11	✓
3.10	✓
3.9	✓
3.8	✓
3.7	✓	✓
3.6	✓	✓
3.5	✓	✓
3.4	✓	✓
3.3	✓	✓
3.2	✓	✓
3.1	✓	✓
3.0	✓	✓
2.9	✓	✓	✓	✓
2.8	✓	✓	✓	✓
2.7	✓	✓	✓	✓

[1]	(1, 2) Versions of PyMongo 4.0 and later are not compatible with Python 2
[2]	Versions of Python 3.10 and later are not compatible with TLS/SSL for versions of MongoDB 4.0 and earlier. See the PyMongo documentation for more information.
[3]	Pymongo 4.1 requires Python 3.6.2 or later.

pymongo Changelog: https://pymongo.readthedocs.io/en/stable/changelog.html

描述

服务器分布

官方原生版本变迁时间线

MongoDB 3.0 升级 3.2

兼容性变化

升级(副本集)

1. 升级 secondary 节点

2. 升级 primary 节点

MongoDB 3.2 升级 3.4

兼容性变化

升级(副本集)

1. 升级 secondary 节点

2. 升级 primary 节点

3. 启用向后不兼容的新版本特性

MongoDB 3.4 升级 3.6

兼容性变化

升级(副本集)

1. FCV(Feature Compatibility Version)特性兼容性版本确认

2. 节点状态确认

3. 升级 secondary 节点

4. 升级 primary 节点

5. 启用向后不兼容的新版本特性

MongoDB 3.6 升级 4.0

兼容性变化

升级(副本集)

1. 检查驱动兼容性

2. Initial Syncs

3. 认证方式确认

4. Remove pv0 for Replica Sets

5. FCV(Feature Compatibility Version)特性兼容性版本确认

6. 节点状态确认

7. 升级 secondary 节点

8. 升级 primary 节点

9. 启用向后不兼容的新版本特性

附录

MongoDB Drivers

Java

PHP

Python

4. Remove `pv0` for Replica Sets