先决条件和限制主版本就地升级的准备工作执行主版本就地升级主版本就地升级故障排除亚马逊 DocumentDB 3.6/4.0 到 5.0 升级集群与全新 Amazon DocumentDB 5.0 集群之间的区别

Amazon DocumentDB 主版本就地升级

通常在经过广泛的测试后，Amazon DocumentDB 才会推出数据库引擎的新版本。您可以选择如何以及何时升级您的 Amazon DocumentDB 集群至新版本。

目前， Amazon DocumentDB 支持三个主版本： Amazon DocumentDB 3.6、4.0 和 5.0。您可以对您的数据库执行主版本就地升级 (MVU)，同时保留这些集群的端点、存储空间和标签，并且可以在无任何修改下继续使用您的应用程序。此功能在所有提供 Amazon DocumentDB 5.0 的地区免费提供。

重要

在主版本就地升级期间，您的 Amazon DocumentDB 集群将不可用，并且您的集群将经历多次重启。不同集群的升级停机时间可能不定，这具体取决于集合、索引、数据库和实例的数目。我们推荐在您的维护窗口期间或在低利用率时段期间执行升级。一旦您的集群已升级，您无法将该集群降级到先前版本，但可以选择将升级前快照还原到新集群。

主题

先决条件和限制
主版本就地升级的准备工作
执行主版本就地升级
主版本就地升级故障排除
亚马逊 DocumentDB 3.6/4.0 到 5.0 升级集群与全新 Amazon DocumentDB 5.0 集群之间的区别

先决条件和限制

以下是主版本就地升级的先决条件和限制，在执行升级之前，您可能需要了解这些先决条件和限制并据此行动：

实例类型 — Amazon DocumentDB 4.0/5.0 不支持 r4.* 实例。为了继续主版本就地升级，请将 r4.* 实例修改成 r5.* 实例。请参阅修改 Amazon DocumentDB 实例了解更多信息。请参阅不同区域支持的实例类以了解基于 Amazon DocumentDB 引擎版本的受支持实例。
实例 OS 补丁- 主版本就地升级需要最新的操作系统 (OS) 补丁才继续下去。在继续就地升级之前，请对实例应用任何待进行的 OS 维护操作。有关更多信息，请参阅使用操作系统更新。

注意
在某些情况下，如果您有待运行的集群级引擎补丁，则实例 OS 补丁不可见。在继续应用实例 OS 补丁以及随后进行主版本就地升级之前，您可能需要应用集群级引擎补丁。请参阅对集群的引擎版本执行补丁更新。
所有推出 Amazon DocumentDB 5.0 的区域均提供就地主版本升级。
作为目标版本的 Amazon DocumentDB 4.0 不支持主版本就地升级。
Amazon DocumentDB 全球集群和弹性集群上目前不支持主版本就地升级。

注意
要升级您的全球群集，请从全局群集中删除您的辅助群集，将主群集转换为区域群集，对区域（主）群集执行主版本就地升级，然后通过以下方式重新创建全局群集：使用相同的名称添加辅助集群以保留与之前相同的端点。请注意，在您的已升级主群集复制数据到您新添加的辅助集群时，将发生 IO 收费。有关如何在删除前从全局群集移除辅助群集的详细步骤，请参阅从 Amazon DocumentDB 全局集群中删除某集群。

如果您有庞大数目的索引 (>10,000) 并且正在较小实例（例如 t3.medium）上运行，则您必须将主实例扩展到更大的实例（例如，至少 r5.xlarge），以便在实例中预留足够内存执行主版本就地升级。主版本就地升级完成后，您可以选缩减实例大小。有关每种实例类型上就主版本就地升级而言支持的最大索引数，请参阅下表：

对于内存优化型实例 (db.r5.*)：

实例	就地 MVU 所支持的最大索引
db.r5.large	100K
db.r5.xlarge	200K
db.r5.2xlarge	300K
db.r5.4xlarge	400K
db.r5.8xlarge	500K
db.r5.12xlarge	700K
db.r5.16xlarge	800K
db.r5.24xlarge	1M

适用于可突增性能实例（db.t3、db.t4g）

实例	就地 MVU 所支持的最大索引
db.t4g.medium	3K
db.t3.medium	10K

对于内存优化型引力子实例 (db.r6g.*)：

实例	就地 MVU 所支持的最大索引
db.r6g.large	100K
db.r6g.xlarge	200K
db.r6g.2xlarge	300K
db.r6g.4xlarge	400K
db.r6g.8xlarge	500K
db.r6g.12xlarge	700K
db.r6g.16xlarge	800K

注意

如果您的索引超过 100 万，请联系 Amazon 支持人员，不要继续进行就地主版本升级。

主版本就地升级的准备工作

使用克隆过的集群测试主版本就地升级

要测试主版本就地升级，我们建议使用快速克隆功能创建您目标集群的克隆。除非您修改该集群上的任何数据，否则对已克隆的卷测试主版本就地升级不会发生任何存储成本。有关卷克隆的更多信息，请参阅克隆 Amazon DocumentDB 集群卷。
要更真实地估计完成主版本就地升级所花费的时间，请将已克隆集群的实例计数与目标集群匹配。
我们建议全面测试新升级的 Amazon DocumentDB 5.0 集群是否存在任何功能差异，以确保一切按预期运行。

主版本就地升级前之前

准备好一个版本兼容的集群参数组。

对新引擎版本使用 Amazon DocumentDB 默认集群参数组，或为新引擎版本创建自己的自定义集群参数组。

如果您关联 Amazon DocumentDB 集群参数组作为升级请求的一部分，则主版本就地升级将自动重新启动该集群以便应用新的参数组。
确保您已满足如先决条件和限制部分中提到的主版本就地升级先决条件。
创建手动快照。

在升级期间，升级进程创建数据库集群的快照。强烈推荐在升级过程之前创建自己的手动快照。请参阅创建手动集群快照。

注意
主版本就地升级已完成后，升级过程创建的自动快照不会自动删除。只要这个快照在保留期范围内，它就不会发生任何费用。一旦您已经确认自己的集群升级成功，您就可以选择删除此快照。

快照命名为preupgrade-<name>-<version>-<timestamp>。
核查您是否已对您的集群安排主版本就地升级。

如果您已修改集群并选择在下一个维护窗口中应用它，则主版本就地升级计划将在控制台上不可见，但您可以在 CLI 中查看它。你可以运行以下命令核查是否已经安排主版本就地升级：
```
aws docdb describe-db-cluster \
--region $REGION \
--db-cluster-identifier $CLUSTER_NAME
   
"PendingModifiedValues": {
    "EngineVersion": "5.0.0"
},
```
在低级环境中使用卷克隆执行多次试运行，以便对任何执行计划和功能差异测试主版本就地升级后的集群。我们推荐用相同数目和大小的实例进行克隆，以更好估计主版本就地升级的运行时间。有关更多信息，请参阅克隆 Amazon DocumentDB 集群卷。
如果上一步成功，请继续在生产集群上进行主版本就地升级。

主版本就地升级期间

您可以通过订阅集群维护事件来监控主版本就地升级进度。升级完成时，您将收到“数据库集群主版本已升级”事件。该升级期间发生的这个事件和其他事件显示于 Amazon DocumentDB 控制台中集群详情页面的“事件和标签”部分。集群状态随后从“正在升级”变成“可用”。

从 CLI 中，您可以运行aws docdb create-event-subscription 来创建事件并且运行 aws docdb describe-events 以监控进度。您还可以将上述事件的事件通知设置成 Amazon SNS，作为通过电子邮件、推送消息和其他方式待通知的目标。有关更多信息，请参阅订阅 Amazon DocumentDB 活动订阅。

升级期间主版本就地升级生成以下事件：

升级进行中：正在创建升级前快照 [preupgrade-<cluster-name>-<timestamp>]
升级进行中：正在克隆卷。
升级进行中：正在升级写入器。
升级进行中：正在升级阅读器。
数据库集群主要版本已升级。

事件也在控制台上“事件”页面下方可见：

在中 Amazon CLI，您可以使用以下命令来跟踪进度：


aws docdb describe-events --source-identifier $CLUSTER_NAME --source-type db-cluster
{
    "Events": [
        {
            "SourceIdentifier": "mycluster",
            "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 中有什么新内容了解 Amazon DocumentDB 5.0 功能列表。

重要

执行就地主版本升级 (MVU) 后，您的 Amazon DocumentDB 5.0 集群将立即重新填充索引元数据，数据库引擎将基于这些元数据来优化查询执行计划。索引元数据重新计算过程完成后，Amazon DocumentDB 集群的预期查询性能将恢复。通常，此过程会在几分钟内完成，但可能持续长达两个小时，具体取决于集群上的索引数量。

此外，在就地 MVU 之后立即重启、故障转移或向上/缩小写入器实例可能会中断集群上的索引元数据计算过程。就地 MVU 完成后，我们建议您在观察到 Amazon DocumentDB 5.0 集群上的预期查询性能后再进行此类更改。

如果您发现这种临时性能下降在就地 MVU 之后持续超过两个小时，请联系 Amazon 支持人员。

全面测试升级的 Amazon DocumentDB 5.0 集群，确保一切按预期运行。

注意

在启用了更改流的 Amazon DocumentDB 集群上执行就地 MVU 后，之前的更改流事件将被保留，并且可以使用或恢复。resumeToken startAtOperationTime与任何新创建的 Amazon DocumentDB 集群一样，如果日志大小大于 51,200MB，change_stream_log_retention_duration则会删除早于之前的更改流事件日志。

执行主版本就地升级

主版本就地升级故障排除

在失败情况下，主版本就地升级将尝试升级回滚，以采用升级启动前集群的最后一个运行状态。成功的回滚将生成一个事件：“数据库集群处于无法升级状态：DocumentDB 集群处于主版本升级无法成功完成的状态。” 此时，您应该联系 Amazon 支持团队进行故障排除并重新尝试版本升级。您可以继续如前使用您的工作负载。在任何其他罕见的情况下，如果升级时间超过预期，请联系 Amazon 支持团队寻求帮助。

亚马逊 DocumentDB 3.6/4.0 到 5.0 升级集群与全新 Amazon DocumentDB 5.0 集群之间的区别

多种数字数据类型的子文档比较：
- 如果集群迁移自 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 5.0 特有的性能改进（例如垃圾收集）。但是，重新创建索引可能涉及额外的 I/O 和时间。有关更多信息，请参阅管理 Amazon DocumentDB 索引。

注意

有关 Amazon DocumentDB 3.6/4.0 和 Amazon DocumentDB 5.0 之间功能性差异的列表，请参阅。MongoDB 兼容性

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

迁移手册

安全性