本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon DocumentDB 主版本就地升级
您可以对 Amazon DocumentDB 集群执行就地主版本升级 (MVU)，同时保持相同的终端节点、存储空间和标签。您的应用程序无需修改即可继续运行。此功能在所有提供 Amazon DocumentDB 的地区均可免费使用。
**重要**
升级期间，您的集群将不可用，并且会经历多次重启。开始升级后，请勿连接到集群、读取集群或写入集群。停机时间因集合、索引、数据库和实例的数量而异。我们建议在维护时段或低利用率时段执行升级。
一旦升级，就无法降级到以前的版本。如果需要，您可以将升级前的快照还原到新集群。
**Topics**
+ [支持的升级途径](#mvu-upgrade-paths)
+ [先决条件](#mvu-prerequisites)
+ [最佳实践](#mvu-best-practices)
+ [从亚马逊 DocumentDB 5.0 升级到 8.0 后发生了什么变化](#mvu-50-to-80-differences)
+ [Post-upgrade 从 3.6 或 4.0 升级的集群的注意事项](#mvu-36-to-50-differences)
+ [执行升级](#perform-an-mvu)
+ [问题排查](#mvu-troubleshooting)
## 支持的升级途径
| 源版本 | 目标版本 |
| --- | --- |
| 亚马逊 DocumentDB 3.6 | Amazon DocumentDB 5.0 |
| Amazon DocumentDB 4.0 | Amazon DocumentDB 5.0 |
| Amazon DocumentDB 5.0 | 亚马逊 DocumentDB 8.0 |
**注意**
In-place 全局群集或弹性集群不支持 MVU。要升级全局群集，请移除辅助群集，将主群集转换为区域群集，执行 MVU，然后通过添加使用相同名称的辅助集群来重新创建全局群集以保留您的终端节点。当升级的主服务器将数据复制到新的辅助服务器时，您将产生 I/O 费用。有关详细步骤，请参阅[从 Amazon DocumentDB 全局集群中删除某集群](global-clusters.manage.md#global-clusters.remove)。
## 先决条件
+ **实例类型** — 亚马逊 DocumentDB 4.0\+ 不支持 db.r4 实例。在升级之前，请将任何`db.r4.*``db.r5.*`实例修改为实例或更新的实例。请参阅[修改 Amazon DocumentDB 实例](db-instance-modify.md)和[不同区域支持的实例类](db-instance-classes.md#db-instance-classes-by-region)。
+ **操作系统补丁**-升级之前，对所有实例应用所有待处理的操作系统维护操作。请参阅[Amazon DocumentDB 操作系统更新](db-instance-maintain.md#os-system-updates)。
**注意**
待处理的集群级引擎补丁可能会隐藏实例操作系统补丁。如果需要，请先应用引擎补丁。请参阅[对集群的引擎版本执行补丁更新](db-cluster-version-upgrade.md)。
+ **突发性能实例（t-family 实例）的索引限制 — 如果突发性能实例**上的索引超过 3,000 个，请在升级之前将主实例扩展到至少 db.r5.large。升级完成后，您可以缩小规模。
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/docdb-mvu.html)
+ **参数组**-我们建议在升级之前为目标版本准备好自定义集群参数组。如果未指定参数组，则将使用目标版本的默认参数组（例如，`default.docdb5.0`或`default.docdb8.0`）。
+ **手动快照**-在升级之前创建手动快照。升级过程会创建名为的自动快照`preupgrade---`，但我们强烈建议您拥有自己的备份。请参阅[创建手动集群快照](backup_restore-create_manual_cluster_snapshot.md)。
**注意**
主版本就地升级已完成后，升级过程创建的自动快照不会自动删除。只要这个快照在保留期范围内，它就不会发生任何费用。一旦您已经确认自己的集群升级成功，您就可以选择删除此快照。
## 最佳实践
### 升级之前 — 使用克隆进行测试
1. [克隆 Amazon DocumentDB 集群卷](db-cluster-cloning.md)用于创建集群的克隆。除非修改克隆上的数据，否则不会产生存储成本。
1. 将克隆的实例计数与目标集群进行匹配，以获得真实的时间估计。
1. 在克隆上执行 MVU 并全面测试功能差异。
1. 运行[https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-clusters.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-clusters.html)并查找，检查是否已安排升级`PendingModifiedValues.EngineVersion`。如果您修改了集群并选择在下一个维护时段内应用该集群，则该计划将不会显示在控制台中，但您可以在以下位置查看 AWS CLI：
```
aws docdb describe-db-clusters \
--region {{us-east-1}} \
--db-cluster-identifier {{mydocdbcluster}}
```
```
"PendingModifiedValues": {
"EngineVersion": "5.0.0"
},
```
1. 如果测试成功，请继续在生产集群上进行升级。
### 升级期间
您可以通过订阅集群维护事件来监控主版本就地升级进度。升级完成后，您将收到 “数据库集群主版本已升级” 事件。升级期间发生的此事件和其他事件显示在 Amazon DocumentDB 控制台集群详情页面的 “**事件和标签**” 部分。然后，集群状态`upgrading`将从变为`available`。
升级期间会生成以下事件：
1. 数据库集群引擎主版本升级已启动。集群保持联机状态。
1. 正在进行升级准备：正在启动在线升级预检查。
1. 正在进行升级准备：已完成在线升级预检查。
1. 在主实例完成该 patch/upgrade 过程的同时使数据库集群脱机。
1. 升级准备进行中：开始离线升级预检。
1. 升级准备进行中：已完成离线升级预检查。
1. 升级正在进行中：正在创建升级前快照 [升级前----]。
1. 升级进行中：正在克隆卷。
1. 升级进行中：正在升级写入器。
1. 升级进行中：正在升级阅读器。
1. 数据库集群引擎主要版本已升级。
事件在控制台的 “**事件**” 页面下方可见：
从中 AWS CLI，您可以运行[https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-events.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-events.html)以监控升级进度。要自动接收通知，请使用订阅事件并将其发送[https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/create-event-subscription.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/create-event-subscription.html)到 Amazon SNS 以获取电子邮件、推送消息或其他传送方式。有关更多信息，请参阅 [订阅 Amazon DocumentDB 事件](event-subscriptions.subscribe.md)。
```
aws docdb describe-events
--source-identifier {{mydocdbcluster}}
--source-type db-cluster
```
该命令返回的输出类似于下方内容：
```
{
"Events": [
{
"SourceIdentifier": "mydocdbcluster",
"SourceType": "db-cluster",
"Message": "Database cluster engine version upgrade started.",
"EventCategories": [
"maintenance"
],
"Date": "2023-07-11T23:20:32.444000+00:00",
"SourceArn": "arn:aws:rds:us-east-1:xxxx:cluster:mycluster"
}
]
}
```
### 升级后
**警告**
就地升级主版本后，您的 Amazon DocumentDB 集群会立即重新填充数据库引擎用于优化查询执行计划的索引元数据。此过程完成后，查询性能将恢复到预期水平。它通常会在几分钟内完成，但最多可能需要两个小时，具体取决于集群上的索引数量。
在此期间，请勿重启、故障转移或扩展 up/down 您的写入器实例，因为这可能会中断索引元数据的重新计算。我们建议您等到观察到预期的查询性能后再进行此类更改。
通过以下集群事件跟踪进度：
Post-upgrade 集群状态：索引元数据刷新过程已启动
Post-upgrade 集群状态：索引元数据刷新过程在 X 秒内完成
如果索引元数据刷新过程未在三小时内完成，或者该过程完成后您仍然遇到性能问题，请联系 AWS 支持人员。
1. **手动拍摄升级后的集群快照**，以备需要恢复到升级后的状态。就地主版本升级完成后，自动快照过程将立即恢复。
1. **标记从 3.6 升级的集群。**添加标签以区分从 3.6 升级的集群。 （见[Post-upgrade 从 3.6 或 4.0 升级的集群的注意事项](#mvu-36-to-50-differences)）。
1. **更新您的驱动程序。**要使用新功能（例如 8.0 中的排序规则、视图或 Zstd 压缩），请升级到相应的 MongoDB API 版本。有关更多信息，请参阅 [Amazon DocumentDB 8.0 的新增](https://docs.aws.amazon.com/documentdb/latest/developerguide/compatibility.html#compatibility-whatsnew-8)功能。
1. **彻底测试。**根据升级后的集群验证您的应用程序。
## 从亚马逊 DocumentDB 5.0 升级到 8.0 后发生了什么变化
在将主要版本从 Amazon DocumentDB 5.0 升级到 8.0 之后，启用或更改了以下功能：
+ **排序规则。**[亚马逊 DocumentDB 8.0 支持排序规则。](https://docs.aws.amazon.com/documentdb/latest/developerguide/collation.html)升级后，默认情况下，新集合及其索引以及现有集合上的新索引将启用排序规则。
+ **文本索引。**新的文本索引是使用文本索引 V2 创建的，该版本使用更新的文本搜索解析器来改进 MongoDB 兼容性。现有文本索引不受影响。
+ **查询计划器版本。**如果您没有自定义参数组，则会为 Amazon DocumentDB 8.0 创建一个新的默认参数组，并自动选择 Planner 版本 3。在查询计划器版本 3 中，还可以使用[视图](https://docs.aws.amazon.com/documentdb/latest/developerguide/views.html)。
+ **压缩。**亚马逊 DocumentDB 8.0 支持使用 Zstd 算法进行基于字典的文档压缩。升级后，将在默认启用 Zstd 压缩的情况下创建新的集合。5.0 版本的现有集合保留其压缩设置。要在现有集合上使用 Zstd 压缩，可以修改其压缩设置。有关更多信息，请参阅[Dictionary-based 压缩](https://docs.aws.amazon.com/documentdb/latest/developerguide/dict-compression.html)。
+ **索引重建。**如果您要从亚马逊 DocumentDB 5.0 升级到亚马逊 DocumentDB 8.0，则无需重建索引。
**注意**
有关功能差异的完整列表，请参阅[Amazon DocumentDB 与 MongoDB 兼容性](compatibility.md)。
## Post-upgrade 从 3.6 或 4.0 升级的集群的注意事项
+ **索引重建。**MVU 会保留原始索引。Amazon DocumentDB 5.0 改进了索引维护和垃圾回收，特别是对于低基数索引。从 3.6 或 4.0 升级后，我们建议重新构建索引以确保最佳查询性能（可选，涉及其他内容 I/O）。请参阅[使用 `reIndex` 进行索引维护](managing-indexes.md#reIndex)。
+ **子文档数值比较（仅限 3.6）。**从 3.6 升级的集群继承了 3.6 行为，即子文档中的数字类型不跨类型进行比较。例如，`{a: {b: 1}}`在 3.6 中`{a: {b: NumberLong(1)}}`不等于，但在 4.0 及更高版本中它们相等。此行为会影响从 3.6 升级的所有集群。
## 执行升级
------
#### [ Using the AWS 管理控制台 ]
1. 登录 [AWS 管理控制台](https://console.aws.amazon.com/docdb/home?region=us-east-1)并 打开 Amazon DocumentDB 控制台。
1. 在**集群**表中，选择源集群，单击**操作**，然后单击**修改**。
1. **在**集群规格**中，从引擎版本下拉列表中选择目标版本（例如 **5.0.0** **或 8.0.0**）。**
1. 在**集群选项**中，为目标引擎版本选择集群参数组。您可以使用默认参数组（例如，default. **docdb5.0 或 default.docdb** **8.0）或您创建的自定义参数组。**
1. 选择**继续**，选择您的计划首选项（立即应用或下一个维护时段），然后选择**修改集群**。
1. 当集群变为**升级**时，监控集群表中的集群状态：
------
#### [ Using the AWS CLI ]
[https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/modify-db-cluster.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/modify-db-cluster.html)与`--allow-major-version-upgrade`旗帜一起使用：
```
aws docdb modify-db-cluster \
‐‐db-cluster-identifier {{mydocdbcluster}} \
‐‐allow-major-version-upgrade \
‐‐engine-version {{8.0.0}} \
‐‐apply-immediately \
‐‐cluster-parameter-group {{mydocdbparametergroup}} \
‐‐region {{us-east-1}}
```
{{placeholder}}用集群的信息替换每个信息。
------
## 问题排查
+ **升级失败并回滚。**如果升级失败，它将自动尝试回滚。成功回滚会生成以下事件：“数据库集群处于无法升级的状态。” 您的集群恢复到升级前的状态，您可以继续使用它。重新尝试之前，请联系 AWS 支持人员进行故障排除。
+ **Post-upgrade 性能。**索引元数据刷新运行时，可能会出现暂时的性能下降和 CPU 使用率过高。如果降级持续超过 3 小时，请联系 AWS 支持人员。
如需其他帮助，请联系 Supp [AWS ort](https://aws.amazon.com/support)。