本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon DocumentDB 主版本就地升级
您可以对 Amazon DocumentDB 集群执行就地主要版本升级 (MVU)，同时保持相同的终端节点、存储空间和标签。您的应用程序无需修改即可继续运行。此功能在所有可用 Amazon DocumentDB AWS 区域 的地方均不收取额外费用。
**重要**
您的集群在升级期间不可用，并且会多次重启。开始升级后，请勿连接、读取或写入集群。停机时间因集合、索引、数据库和实例的数量而异。在维护时段或低利用率时段执行升级。
升级后，您无法降级到以前的版本。如果需要，您可以将升级前的快照恢复到新集群。
**Topics**
+ [支持的升级途径](#mvu-upgrade-paths)
+ [先决条件](#mvu-prerequisites)
+ [最佳实践](#mvu-best-practices)
+ [从 Amazon 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)
## 支持的升级途径
下表列出了所有支持的就地主要版本升级路径。您可以选择目标主要版本上的任何已发布次要版本作为目标引擎版本。
| 源代码主要版本 | 目标主要版本 | 注意 |
| --- | --- | --- |
| 亚马逊文档数据库 3.6 | 亚马逊 DocumentDB 5.0（任何已发布的次要版本） | 有关升级后的注意事项[Post-upgrade 从 3.6 或 4.0 升级的集群的注意事项](#mvu-36-to-50-differences)，请参见。 |
| Amazon DocumentDB 4.0 | 亚马逊 DocumentDB 5.0（任何已发布的次要版本） | 有关升级后的注意事项[Post-upgrade 从 3.6 或 4.0 升级的集群的注意事项](#mvu-36-to-50-differences)，请参见。 |
| 亚马逊 DocumentDB 5.0（任何已发布的次要版本） | 亚马逊 DocumentDB 8.0（任何已发布的次要版本） | [从 Amazon DocumentDB 5.0 升级到 8.0 后发生了什么变化](#mvu-50-to-80-differences)有关功能变更的信息，请参见。 |
要查看您所在 AWS 地区可用的次要版本，请使用 AWS CLI 命令`aws docdb describe-db-engine-versions`。有关已发布的次要版本的列表，请参阅[发布说明](release-notes.md)。
**注意**
每个 MVU 可以将目标主版本上的任何已发布次要版本作为目标。例如，从 Amazon DocumentDB 3.6 或 4.0 升级可以直接升级到最新发布的 5.0 次要版本；无需先升级到 5.0.0 然后应用次要版本升级。
要从 3.6 或 4.0 升至 8.0，请执行两个 MVU：首先是您选择的 5.0 次要版本，然后是您选择的 8.0 次要版本。没有直接的 3.6→8.0 或 4.0→8.0 MVU 路径。
**注意**
In-place 全局集群或弹性集群不支持 MVU。要升级全局集群，请移除辅助群集，将主群集转换为区域群集，执行 MVU，然后通过添加使用相同名称的辅助群集来重新创建全局群集以保留您的终端节点。升级后的主服务器将数据复制到新的辅助服务器时，您将产生 I/O 费用。有关详细步骤，请参阅[从 Amazon DocumentDB 全局集群中删除某集群](global-clusters.manage.md#global-clusters.remove)。
## 先决条件
**重要**
**在升级之前向上扩展突发实例。**如果您的集群使用突发性实例类型（例如，`db.t3.medium`或`db.t4g.medium`），请至少将主实例扩展到`db.r5.large`或在启动升级`db.r6g.large`之前。突发性实例可能没有足够的 CPU 和内存来完成升级过程，这可能导致升级失败和集群长期不可用。升级完成后，您可以缩减规模。
**在升级之前扩展无服务器写入器实例。**如果您的集群有无服务器写入器实例，则在启动升级之前，`ServerlessV2ScalingConfiguration`必须将中的最大 DCU 设置为 3 或更高。最大 DCU 低于 3 的群集无法升级，因为它们没有足够的 CPU 或内存来完成升级。
**升级（从 Amazon DocumentDB 5.0 升级到 8.0）之前，请检查您的部分索引。**在开始升级之前，请检查使用`$type`运算符匹配特定 BSON 类型的部分索引：特别是`binData`、、`bool`、`date`、`double`、`decimal`、和`array`类型别名或数字类型代码，例如。`partialFilterExpression` `{ "$type" : 1 }`尽管索引正常用于读取和写入，但此类部分索引会导致升级失败。`db.collection.getIndexes()`用于查看您的`partialFilterExpression`部分索引。在开始升级之前删除受影响的部分索引，并在升级完成后重新创建。如果您不确定索引是否受到影响，请在升级之前联系 AWS 支持人员。
+ **实例类型 ** — Amazon 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 系列实例）的索引限制 ** — 如果突发实例上的索引超过 3,000 个，请在升级之前将主实例的索引扩展到至少 db.r5.large。升级完成后，您可以缩减规模。
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/documentdb/latest/devguide/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. 通过运行[`describe-db-clusters`](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，您可以运行[`aws docdb describe-events`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-events.html)以监控升级进度。要自动接收通知，请使用[`aws docdb create-event-subscription`](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 版本。有关更多信息，请参阅 [亚马逊 DocumentDB 8.0 的新增功能](compatibility.md#compatibility-whatsnew-8)。
1. **彻底测试。**针对升级后的集群验证您的应用程序。
## 从 Amazon DocumentDB 5.0 升级到 8.0 后发生了什么变化
将主要版本从 Amazon DocumentDB 5.0 升级到 8.0 后，启用或更改了以下功能：
+ **排序规则。**亚马逊 DocumentDB 8.0 支持排序规则[。](collation.md)升级后，新集合及其索引以及现有集合的新索引默认启用排序规则。
+ **文本索引。**新的文本索引是使用文本索引 V2 创建的，它使用更新的文本搜索解析器来提高 MongoDB 兼容性。现有文本索引不受影响。
+ **查询计划器版本。**如果您没有自定义参数组，则会为 Amazon DocumentDB 8.0 创建一个新的默认参数组，并自动选择规划器版本 3。在查询计划器版本 3 中，[还提供](views.md)视图。
+ **压缩。**Amazon DocumentDB 8.0 支持使用 Zstd 算法进行基于字典的文档压缩。升级后，将在默认启用 Zstd 压缩的情况下创建新集合。5.0 版本的现有集合保留其压缩设置。要在现有集合上利用 Zstd 压缩，可以修改其压缩设置。有关更多信息，请参阅 [在 Amazon DocumentDB 8.0 中管理基于字典的压缩](dict-compression.md)。
+ **索引重建。**如果您要从 Amazon DocumentDB 5.0 升级到 Amazon DocumentDB 8.0，则无需重建索引。
**重要**
亚马逊 DocumentDB 8.0 需要 TLS 1.2 或更高版本。不再支持 TLS 1.0 和 TLS 1.1。
**注意**
有关功能差异的完整列表，请参阅[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.docd ** b8.0）或您创建**的自定义参数组。
1. 选择**继续**，选择您的日程安排首选项（立即应用或下一个维护窗口），然后选择**修改集群**。
1. 当集群更改为**升级时，在集群表中监控其状态**：
------
#### [ Using the AWS CLI ]
与`--allow-major-version-upgrade`旗帜[`modify-db-cluster`](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 {{8.0.0}} \
‐‐apply-immediately \
‐‐cluster-parameter-group {{mydocdbparametergroup}} \
‐‐region {{us-east-1}}
```
将每个{{placeholder}}替换为您的集群信息。
------
## 问题排查
+ **Pre-upgrade 检查失败。**在升级开始之前，Amazon DocumentDB 会运行升级前的验证检查。以下是预检查失败的常见原因：
+ **无法继续升级，因为集合的名称包含 58 个或更多字符 ** — 在重试升级之前，将受影响的集合重命名为较短的名称。
+ **无法继续升级，因为索引数量超过了实例类型的限制 ** — 在重试升级之前升级到更大的实例类型。有关按实例类型划分的索引限制，请参阅[先决条件](#mvu-prerequisites)。
+ **升级失败和回滚。**如果升级失败，它将自动尝试回滚。成功回滚会生成以下事件：“数据库集群处于无法升级的状态。” 您的集群恢复到升级前状态，您可以继续使用它。在重试之前，请联系 AWS 支持人员进行故障排除。
+ **Post-upgrade 性能。**在索引元数据刷新运行时，可能会出现暂时的性能下降和 CPU 使用率过高。如果降解持续时间超过 3 小时，请联系 AWS 支持人员。
如需其他帮助，请联系 [AWS Support](https://aws.amazon.com/support)。