本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Amazon DocumentDB 就地主要版本升級
Amazon DocumentDB 提供新版本的資料庫引擎，通常僅在廣泛測試後可用。您可以選擇將 Amazon DocumentDB 叢集升級至新版本的方式和時間。
目前，Amazon DocumentDB 支援四個主要版本：Amazon DocumentDB 3.6、4.0、5.0 和 8.0。您可以執行資料庫的就地主要版本升級 (MVU)，同時保留叢集的相同端點、儲存體和標籤，並且可以繼續使用您的應用程式，而無需進行任何修改。此功能可在提供 Amazon DocumentDB 5.0 的所有區域中免費使用。注意：Amazon 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 先決條件和限制
以下是就地主要版本升級的先決條件和限制，在執行升級之前您可能需要了解這些升級並採取動作：
**重要**
Amazon DocumentDB 8.0 目前不支援 MVU。若要使用引擎 8.0 版，請建立新的 8.0 叢集並遷移您的資料。未來版本預計支援 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) 修補程式才能繼續。請在執行個體上套用任何待定的作業系統維護動作，然後再繼續就地升級。如需詳細資訊，請參閱[Amazon DocumentDB 作業系統更新](db-instance-maintain.md#os-system-updates)。
**注意**
在某些情況下，如果您有待定的叢集層級引擎修補程式，則不會顯示執行個體作業系統修補程式。您可能需要套用叢集層級引擎修補程式，才能繼續套用執行個體作業系統修補程式，以及後續的就地主要版本升級。請參閱 [對叢集的引擎版本執行修補程式更新](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_tw/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_tw/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
```
在上述範例中，將每個*使用者輸入預留位置*取代為您叢集的資訊。
命令會傳回下列輸出：
```
"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_tw/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
```
在上述範例中，將每個*使用者輸入預留位置*取代為您叢集的資訊。
命令會傳回下列輸出：
```
{
"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 叢集之間的差異。
在就地 MVU 完成後手動拍攝快照，以防您需要還原至升級後狀態。一旦就地主要版本升級完成，自動快照程序就會繼續。只要手動快照在保留期間內，就不會產生任何費用。
若要使用與 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 之後，立即重新啟動、容錯移轉或擴展/縮減寫入器執行個體，可能會中斷叢集上的索引中繼資料計算程序。就地 MVU 完成後，建議您在 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_tw/documentdb/latest/developerguide/images/mvu-cluster-table-2.png)
1. 在叢集**規格**區段的**修改**叢集對話方塊中，從**引擎版本下拉式選單中選擇目標資料庫版本 ****(5.0.0**)。
![\[影像：修改叢集對話方塊的叢集規格區段，顯示叢集識別符和引擎版本欄位。\]](http://docs.aws.amazon.com/zh_tw/documentdb/latest/developerguide/images/mvu-modify-cluster-2.png)
1. 在**叢集選項**區段中，選擇適當的叢集參數群組 (**default.docdb5.0**) 或自訂建立的參數群組。
![\[影像：修改叢集對話方塊的叢集選項區段，顯示叢集參數群組欄位。\]](http://docs.aws.amazon.com/zh_tw/documentdb/latest/developerguide/images/mvu-param-group-2.png)
1. 完成後，向下捲動並選擇**繼續**。
1. 在**修改排程**區段中，選擇您偏好的排程計劃：立即套用或在下一個維護時段套用。
然後選擇 **Modify cluster (修改叢集)**。
![\[影像：修改叢集對話方塊，顯示所選叢集的修改摘要和排程。\]](http://docs.aws.amazon.com/zh_tw/documentdb/latest/developerguide/images/mvu-mod-schedule-2.png)
1. 在叢集資料表中，記下正在升級的叢集狀態：
![\[影像：叢集導覽方塊反白顯示要升級之叢集的狀態欄。\]](http://docs.aws.amazon.com/zh_tw/documentdb/latest/developerguide/images/mvu-cluster-upgrading-2.png)
------
#### [ 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 5.0.0 \
‐‐apply-immediately \
‐‐cluster-parameter-group mydocdbparametergroup \
‐‐region us-east-1
```
在上述範例中，將每個*使用者輸入預留位置*取代為您叢集的資訊。
------
## Amazon DocumentDB 3.6/4.0 到 5.0 升級的叢集和新的 Amazon DocumentDB 5.0 叢集之間的差異
+ 就地主要版本升級會在升級的叢集上保留原始索引。使用 Amazon DocumentDB 5.0，我們提高了索引維護和垃圾收集程序的整體效率，尤其是低基數索引。一般而言，我們建議在 MVU 成功完成後，使用 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: 1}}`中`{a: {b: {NumberLong(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 支援團隊尋求協助。
+ 就地 MVU 成功完成後，升級的叢集可能會在執行索引中繼資料重新整理程序時，遇到暫時效能降低和 CPU 使用率過高的一小段時間。如果您持續發生效能降低超過 2 小時，請聯絡 AWS 支援。