本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon DocumentDB 主版本就地升级
通常在经过广泛的测试后，Amazon DocumentDB 才会推出数据库引擎的新版本。您可以选择如何以及何时升级您的 Amazon DocumentDB 集群至新版本。
目前，亚马逊 DocumentDB 支持四个主要版本：亚马逊 DocumentDB 3.6、4.0、5.0 和 8.0。您可以对您的数据库执行主版本就地升级 (MVU)，同时保留这些集群的端点、存储空间和标签，并且可以在无任何修改下继续使用您的应用程序。此功能在可获得 Amazon DocumentDB 5.0 的所有地区免费提供。注意：亚马逊 DocumentDB 8.0 目前不支持 MVU。
**重要**
在主版本就地升级期间，您的 Amazon DocumentDB 集群将不可用，并且您的集群将经历多次重启。开始升级后，请避免连接、读取或写入集群。不同集群的升级停机时间可能不定，这具体取决于集合、索引、数据库和实例的数目。我们推荐在您的维护窗口期间或在低利用率时段期间执行升级。一旦您的集群已升级，您无法将该集群降级到先前版本，但可以选择将升级前快照还原到新集群。
**Topics**
+ [MVU 先决条件和限制](#mvu-prerequisites)
+ [主版本就地升级的准备工作](#mvu-best-practices)
+ [执行主版本就地升级](#perform-an-mvu)
+ [Amazon DocumentDB 3.6/4.0 到 5.0 已升级集群与新 Amazon DocumentDB 5.0 集群之间的差异](#mvu-36-to-50-differences)
+ [主版本就地升级故障排除](#mvu-troubleshooting)
## MVU 先决条件和限制
以下是主版本就地升级的先决条件和限制，在执行升级之前，您可能需要了解这些先决条件和限制并据此行动：
**重要**
亚马逊 DocumentDB 8.0 目前不支持 MVU。要使用引擎版本 8.0，请创建一个新的 8.0 集群并迁移您的数据。计划在 future 版本中提供对 8.0 的 MVU 支持。
+ **实例类型**：Amazon DocumentDB 4.0/5.0 不支持 r4.\$1 实例。为了继续主版本就地升级，请将 r4.\$1 实例修改成 r5.\$1 实例。请参阅[修改 Amazon DocumentDB 实例](db-instance-modify.md)了解更多信息。请参阅 [不同区域支持的实例类](db-instance-classes.md#db-instance-classes-by-region) 以了解基于 Amazon DocumentDB 引擎版本的受支持实例。
+ **实例 OS 补丁**- 主版本就地升级需要最新的操作系统 (OS) 补丁才继续下去。在继续就地升级之前，请对实例应用任何待进行的 OS 维护操作。有关更多信息，请参阅 [Amazon DocumentDB 操作系统更新](db-instance-maintain.md#os-system-updates)。
**注意**
在某些情况下，如果您有待运行的集群级引擎补丁，则实例 OS 补丁不可见。在继续应用实例 OS 补丁以及随后进行主版本就地升级之前，您可能需要应用集群级引擎补丁。请参阅[对集群的引擎版本执行补丁更新](db-cluster-version-upgrade.md)。
+ 在可获得 Amazon DocumentDB 5.0 的区域均可提供主版本就地升级。
+ 作为目标版本的 Amazon DocumentDB 4.0 不支持主版本就地升级。
+ Amazon DocumentDB 全球集群和弹性集群上目前不支持主版本就地升级。
**注意**
要升级您的全球群集，请从全局群集中删除您的辅助群集，将主群集转换为区域群集，对区域（主）群集执行主版本就地升级，然后通过以下方式重新创建全局群集：使用相同的名称添加辅助集群以保留与之前相同的端点。请注意，在您的已升级主群集复制数据到您新添加的辅助集群时，将发生 IO 收费。有关如何在删除前从全局群集移除辅助群集的详细步骤，请参阅 [从 Amazon DocumentDB 全局集群中删除某集群](global-clusters.manage.md#global-clusters.remove)。
+ 如果您有庞大数目的索引 (>3,000) 并且正在可突增性能实例（例如 t3.medium 或 t4g.medium）上运行，则您必须将主实例扩展到更大的实例（例如，至少 r5.large），以便在实例中预留足够内存执行主版本就地升级。主版本就地升级完成后，您可以选缩减实例大小。有关 db.t3 和 db.t4g 实例类型上就主版本就地升级而言支持的最大索引数，请参阅下表：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/docdb-mvu.html)
## 主版本就地升级的准备工作
**Topics**
+ [使用克隆过的集群测试主版本就地升级](#test-in-place-mvu)
+ [主版本就地升级前之前](#before-in-place-mvu)
+ [主版本就地升级期间](#during-in-place-mvu)
+ [主版本就地升级后](#after-in-place-mvu)
### 使用克隆过的集群测试主版本就地升级
1. 要测试主版本就地升级，我们建议使用快速克隆功能创建您目标集群的克隆。除非您修改该集群上的任何数据，否则对已克隆的卷测试主版本就地升级不会发生任何存储成本。有关卷克隆的更多信息，请参阅 [克隆 Amazon DocumentDB 集群卷](db-cluster-cloning.md)。
1. 要更真实地估计完成主版本就地升级所花费的时间，请将已克隆集群的实例计数与目标集群匹配。
1. 我们建议全面测试新升级的 Amazon DocumentDB 5.0 集群是否存在任何功能差异，以确保一切按预期运行。
### 主版本就地升级前之前
1. 准备好一个版本兼容的集群参数组。
对新引擎版本使用 Amazon DocumentDB 默认集群参数组，或为新引擎版本创建自己的自定义集群参数组。
如果您关联 Amazon DocumentDB 集群参数组作为升级请求的一部分，则主版本就地升级将自动重新启动该集群以便应用新的参数组。
1. 确保您已满足如先决条件和限制部分中提到的主版本就地升级先决条件。
1. 创建手动快照。
在升级期间，升级进程创建数据库集群的快照。强烈推荐在升级过程之前创建自己的手动快照。请参阅[创建手动集群快照](backup_restore-create_manual_cluster_snapshot.md)。
**注意**
主版本就地升级已完成后，升级过程创建的自动快照不会自动删除。只要这个快照在保留期范围内，它就不会发生任何费用。一旦您已经确认自己的集群升级成功，您就可以选择删除此快照。
快照命名为`preupgrade---`。
![\[图片：快照导航框中显示之前创建的快照表。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/mvu-snapshot-2.png)
1. 核查您是否已对您的集群安排主版本就地升级。
如果您已修改集群并选择在下一个维护窗口中应用它，则主版本就地升级计划将在控制台上不可见，但您可以在 CLI 中查看它。您可以运行 [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) 命令，以检查是否已经安排就地主要版本升级：
```
aws docdb describe-db-cluster \
--region us-east-1 \
--db-cluster-identifier mydocdbcluster
```
在上面的示例中，将每个*user input placeholder*替换为集群的信息。
该命令将返回以下输出：
```
"PendingModifiedValues": {
"EngineVersion": "5.0.0"
},
```
1. 在低级环境中使用卷克隆执行多次试运行，以便对任何执行计划和功能差异测试主版本就地升级后的集群。我们推荐用相同数目和大小的实例进行克隆，以更好估计主版本就地升级的运行时间。有关更多信息，请参阅 [克隆 Amazon DocumentDB 集群卷](db-cluster-cloning.md)。
1. 如果上一步成功，请继续在生产集群上进行主版本就地升级。
### 主版本就地升级期间
您可以通过订阅集群维护事件来监控主版本就地升级进度。升级完成时，您将收到“数据库集群主版本已升级”事件。该升级期间发生的这个事件和其他事件显示于 Amazon DocumentDB 控制台中集群详情页面的“事件和标签”部分。集群状态随后从“正在升级”变成“可用”。
从 CLI 中，您可以运行`aws docdb create-event-subscription` 来创建事件并且运行 `aws docdb describe-events` 以监控进度。您还可以将上述事件的事件通知设置成 Amazon SNS，作为通过电子邮件、推送消息和其他方式待通知的目标。有关更多信息，请参阅 [订阅 Amazon DocumentDB 事件](event-subscriptions.subscribe.md)。
升级期间主版本就地升级生成以下事件：
+ 升级进行中：正在创建升级前快照 [preupgrade--]
+ 升级进行中：正在克隆卷。
+ 升级进行中：正在升级写入器。
+ 升级进行中：正在升级阅读器。
+ 数据库集群主要版本已升级。
事件也在控制台上“**事件**”页面下方可见：
![\[图片：事件导航框中显示升级事件表。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/mvu-events-2.png)
在中 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)命令来跟踪进度：
```
aws docdb describe-events
--source-identifier mydocdbcluster
--source-type db-cluster
```
在上面的示例中，将每个*user input placeholder*替换为集群的信息。
该命令将返回以下输出：
```
{
"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 3.6，向集群添加标签，以区分集群已从 Amazon DocumentDB 3.6 升级到 Amazon DocumentDB 5.0，而不是新创建的 Amazon DocumentDB 5.0 集群。请参阅有关已升级 Amazon DocumentDB 5.0 集群与新 Amazon DocumentDB 5.0 集群之间差异的部分。
在就地主要版本升级完成后拍摄手动快照，以防您需要恢复到升级后状态。一旦主版本就地升级完成，自动快照进程就将恢复。只要手动快照在保留期范围内，它就不会发生任何费用。
要使用与 Amazon DocumentDB 5.0 相关的新功能，例如客户端字段级加密，我们推荐您的驱动程序版本升级到 MongoDB 5.0 API 版本。有关更多信息，请参阅 [Amazon DocumentDB 5.0 中有什么新内容](compatibility.md#compatibility-whatsnew-5) 了解 Amazon DocumentDB 5.0 功能列表。
**重要**
执行就地主版本升级 (MVU) 后，Amazon DocumentDB 5.0 集群将立即重新填充索引元数据，数据库引擎据此数据优化查询执行计划。Amazon DocumentDB 集群上的预期查询性能将在索引元数据重新计算过程完成后恢复。通常，这一过程将在几分钟内完成，但可能会持续长达两个小时之久，具体取决于集群上的索引数量。在就地 MVU 之后立即重启、故障转移或扩展 up/down 写入器实例，可能会中断集群上的索引元数据计算过程。就地主版本升级完成后，我们建议在 Amazon DocumentDB 5.0 集群上观察到预期的查询性能后再进行此类更改。
您可以通过以下集群事件跟踪此重新计算过程的开始和结束：
升级后集群状态：索引元数据刷新过程已启动
升级后集群状态：索引元数据刷新过程在 X 秒内完成
如果索引元数据刷新过程未在三小时内完成，或者该过程完成后您仍然遇到性能问题，请联系 AWS 支持人员。
全面测试升级的 Amazon DocumentDB 5.0 集群，确保一切按预期运行。
## 执行主版本就地升级
------
#### [ Using the AWS 管理控制台 ]
要使用 AWS 管理控制台执行主版本就地升级：
1. 登录 [AWS 管理控制台](https://console.aws.amazon.com/docdb/home?region=us-east-1)并 打开 Amazon DocumentDB 控制台。
1. 在**集群**表中，选择源集群，单击**操作**，然后单击**修改**。
![\[图片：集群导航框中显示一列现有集群链接及其对应的实例链接。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/mvu-cluster-table-2.png)
1. 在**集群规范**部分中的**修改集群**对话框中，从**引擎版本**下拉菜单中选择目标数据库版本（**5.0.0**）。
![\[图片：“修改集群”对话框的“集群规范”部分显示“集群标识符”和“引擎版本”字段。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/mvu-modify-cluster-2.png)
1. 在**集群选项**部分，选择适宜的群集参数组 (**default.docdb5.0**) 或创建的自定义参数组。
![\[图片：“修改集群”对话框的“集群选项”部分显示“集群参数组”字段。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/mvu-param-group-2.png)
1. 一旦完成，就向下滚动并选择**继续**。
1. 在**安排修改**”部分，选择您的首选安排计划：立即应用或在下一个维护窗口中应用。
然后选择 **Modify cluster (修改集群)**。
![\[图片：“修改集群”对话框显示了选定集群的修改摘要和计划。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/mvu-mod-schedule-2.png)
1. 在集群表中，记下您的集群正在升级时的状态：
![\[图片：集群导航框突出显示正在升级的集群的“状态”列。\]](http://docs.aws.amazon.com/zh_cn/documentdb/latest/developerguide/images/mvu-cluster-upgrading-2.png)
------
#### [ Using the AWS CLI ]
使用带有所需引擎版本选项和 `allow-major-version-upgrade` 标志集的 [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) 命令：
```
aws docdb modify-db-cluster \
‐‐db-cluster-identifier mydocdbcluster \
‐‐allow-major-version-upgrade \
‐‐engine-version 5.0.0 \
‐‐apply-immediately \
‐‐cluster-parameter-group mydocdbparametergroup \
‐‐region us-east-1
```
在上面的示例中，将每个*user input placeholder*替换为集群的信息。
------
## Amazon DocumentDB 3.6/4.0 到 5.0 已升级集群与新 Amazon DocumentDB 5.0 集群之间的差异
+ 主版本就地升级保留已升级集群上的原始索引。借助 Amazon DocumentDB 5.0，我们提高了索引维护和垃圾回收过程的整体效率，特别是针对低基数索引而言。作为一般最佳实践，我们建议在主要版本升级成功完成后使用 reindex 命令重新创建索引。重新创建索引不是必需操作，这将涉及额外的 I/O。有关更多信息，请参阅 [使用 `reIndex` 进行索引维护](managing-indexes.md#reIndex)。
+ 多种数字数据类型的子文档比较：
+ 如果集群迁移自 Amazon DocumentDB 3.6，则它将继承 Amazon DocumentDB 3.6 子文档比较行为。功能性差异仅限于子文档中的数字类型（例如 Long、Double、Decimal128）。例如，在 Amazon DocumentDB 3.6 中 `{a: {b: {NumberLong(1)}}` 不等于 `{a: {b: 1}}` ，而在 Amazon DocumentDB 4.0 及更高版本中，则将它们作为相等进行比较。
+ 这种子文档比较行为仅存在于 Amazon DocumentDB 3.6 和使用主版本就地升级从 3.6 版本升级而来的 Amazon DocumentDB 5.0 集群中。这不适用于新创建的 Amazon DocumentDB 5.0 集群。
**注意**
有关 Amazon DocumentDB 3.6/4.0 和 Amazon DocumentDB 5.0 之间功能性差异的列表，请参阅。[Amazon DocumentDB 与 MongoDB 兼容性](compatibility.md)
## 主版本就地升级故障排除
+ 在失败情况下，主版本就地升级将尝试升级回滚，以采用升级启动前集群的最后一个运行状态。成功的回滚将生成一个事件：“数据库集群处于无法升级状态：DocumentDB 集群处于主版本升级无法成功完成的状态。” 此时，您应该联系 AWS 支持团队进行故障排除并重新尝试版本升级。您可以继续如前使用您的工作负载。在任何其他罕见的情况下，如果升级时间超过预期，请联系 AWS 支持团队寻求帮助。
+ 成功完成就地主版本升级后，在索引元数据刷新过程运行期间，升级后的集群可能会在短时间内出现临时性能下降和 CPU 使用率过高的问题。如果您持续出现性能下降超过 2 小时，请联系 AWS 支持人员。