本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Amazon DocumentDB 就地主要版本升級
您可以執行 Amazon DocumentDB 叢集的就地主要版本升級 (MVU)，同時保留相同的端點、儲存體和標籤。您的應用程式會繼續運作，無需修改。此功能可在提供 Amazon DocumentDB 的所有區域中免費使用。
**重要**
您的叢集在升級期間將無法使用，並會經歷多次重新啟動。開始升級後，請勿連接、讀取或寫入叢集。停機時間取決於集合、索引、資料庫和執行個體的數量。我們建議您在維護時段或低使用率時段執行升級。
升級之後，您就無法降級至先前的版本。如有需要，您可以將預先升級快照還原至新的叢集。
**Topics**
+ [支援的升級路徑](#mvu-upgrade-paths)
+ [先決條件](#mvu-prerequisites)
+ [最佳實務](#mvu-best-practices)
+ [從 Amazon DocumentDB 5.0 升級至 8.0 後有何變更](#mvu-50-to-80-differences)
+ [從 3.6 或 4.0 升級之叢集的升級後考量事項](#mvu-36-to-50-differences)
+ [執行升級](#perform-an-mvu)
+ [疑難排解](#mvu-troubleshooting)
## 支援的升級路徑
| 來源版本 | 目標版本 |
| --- | --- |
| Amazon DocumentDB 3.6 | Amazon DocumentDB 5.0 |
| Amazon DocumentDB 4.0 | Amazon DocumentDB 5.0 |
| Amazon DocumentDB 5.0 | Amazon DocumentDB 8.0 |
**注意**
全域叢集或彈性叢集不支援就地 MVU。若要升級全域叢集，請移除次要叢集、將主要叢集轉換為區域叢集、執行 MVU，然後使用相同名稱新增次要叢集來保留端點，以重新建立全域叢集。升級的主要 將資料複寫到新的次要檔案時，會產生 I/O 費用。如需詳細步驟，請參閱[從 Amazon DocumentDB 全域叢集移除叢集](global-clusters.manage.md#global-clusters.remove)。
## 先決條件
+ **執行個體類型** — 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-family 執行個體） 的索引限制** — 如果您在高載執行個體上有超過 3，000 個索引，請在升級之前將主要執行個體擴展到至少 db.r5.large。您可以在升級完成後縮減規模。
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/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. 在主要執行個體完成修補/升級程序時，使資料庫叢集離線。
1. 升級準備進行中：開始離線升級預先檢查。
1. 升級準備進行中：已完成離線升級預先檢查。
1. 升級進行中：建立升級前快照 【preupgrade---to--】。
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 叢集會立即重新填入索引中繼資料，讓資料庫引擎用來最佳化查詢執行計畫。一旦此程序完成，查詢效能就會返回預期的層級。它通常在幾分鐘內完成，但最多可能需要兩個小時，具體取決於叢集上的索引數量。
在此期間，請勿重新啟動、容錯移轉或擴展/縮減您的寫入器執行個體，因為這可能會中斷索引中繼資料的重新計算。我們建議您等到觀察到預期的查詢效能，再進行此類變更。
透過下列叢集事件追蹤進度：
升級後叢集狀態：索引中繼資料重新整理程序已啟動
升級後叢集狀態：在 X 秒內完成索引中繼資料重新整理程序
如果索引中繼資料重新整理程序未在三小時內完成，或在程序完成後持續遇到效能問題，請聯絡 AWS 支援。
1. 如果您需要還原至升級後狀態，請**手動擷取升級叢集的快照**。一旦就地主要版本升級完成，自動快照程序就會繼續。
1. **從 3.6 升級的標籤叢集。**新增標籤以區分從 3.6 升級的叢集 （請參閱 [從 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. **徹底測試。**針對升級的叢集驗證您的應用程式。
## 從 Amazon DocumentDB 5.0 升級至 8.0 後有何變更
執行從 Amazon DocumentDB 5.0 到 8.0 的主要版本升級之後，會啟用或停用下列功能：
+ **定序。**Amazon DocumentDB 8.0 支援[定序](https://docs.aws.amazon.com/documentdb/latest/developerguide/collation.html)。升級之後，新的集合及其索引，以及現有集合上的新索引，預設會啟用定序。
+ **文字索引。**使用文字索引 V2 建立新的文字索引，該索引使用更新的文字搜尋剖析器來改善 MongoDB 相容性。現有的文字索引不受影響。
+ **查詢規劃器版本。**如果您沒有自訂參數群組，則會為 Amazon DocumentDB 8.0 建立新的預設參數群組，並自動選取規劃器第 3 版。透過查詢規劃器第 3 版，也可以使用[檢視](https://docs.aws.amazon.com/documentdb/latest/developerguide/views.html)。
+ **壓縮。**Amazon DocumentDB 8.0 支援使用 Zstd 演算法的字典型文件壓縮。升級之後，系統會根據預設啟用 Zstd 壓縮來建立新的集合。來自 5.0 的現有集合會保留其壓縮設定。若要在現有集合上利用 Zstd 壓縮，您可以修改其壓縮設定。如需詳細資訊，請參閱[字典型壓縮](https://docs.aws.amazon.com/documentdb/latest/developerguide/dict-compression.html)。
+ **索引重建。**如果您要從 Amazon DocumentDB 5.0 升級到 Amazon DocumentDB 8.0，則不需要重建索引。
**注意**
如需功能差異的完整清單，請參閱 [Amazon DocumentDB 與 MongoDB 的相容性](compatibility.md)。
## 從 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 行為，其中子文件中的數值類型不會跨類型進行比較。例如， 在 3.6 `{a: {b: 1}}`中`{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.docdb8.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}}
```
將每個{{預留位置}}取代為您叢集的資訊。
------
## 疑難排解
+ **升級失敗和復原。**如果升級失敗，會自動嘗試回復。成功轉返會產生事件：「資料庫叢集處於無法升級的狀態」。您的叢集會返回其升級前狀態，您可以繼續使用它。在重新嘗試之前，請聯絡 AWS 支援部門進行故障診斷。
+ **升級後效能。**當索引中繼資料重新整理執行時，可能會發生暫時性效能降低和高 CPU 使用率。如果降級持續超過 3 小時，請聯絡 AWS 支援。
如需其他協助，請聯絡 [AWS Support](https://aws.amazon.com/support)。