Direktes Upgrade der Hauptversion von Amazon DocumentDB

Sie können ein direktes Hauptversions-Upgrade (MVU) Ihres Amazon DocumentDB-Clusters durchführen und dabei dieselben Endpunkte, Speicher und Tags beibehalten. Ihre Anwendungen funktionieren weiterhin ohne Änderungen. Diese Funktion ist überall dort, AWS-Regionen wo Amazon DocumentDB verfügbar ist, ohne zusätzliche Kosten verfügbar.

Wichtig

Ihr Cluster ist während des Upgrades nicht verfügbar und wird mehrmals neu gestartet. Stellen Sie nach dem Start des Upgrades keine Verbindung zum Cluster her, lesen Sie nicht aus dem Cluster und schreiben Sie nicht in den Cluster. Die Ausfallzeit variiert je nach Anzahl der Sammlungen, Indizes, Datenbanken und Instanzen. Führen Sie das Upgrade während des Wartungsfensters oder zu Zeiten mit geringer Auslastung durch.

Nach dem Upgrade können Sie kein Downgrade auf eine frühere Version durchführen. Sie können Ihren Snapshot vor dem Upgrade bei Bedarf in einem neuen Cluster wiederherstellen.

Unterstützte Upgrade-Pfade

In der folgenden Tabelle sind alle unterstützten direkten Upgrade-Pfade für Hauptversionen aufgeführt. Sie können jede veröffentlichte Nebenversion der Ziel-Hauptversion als Ziel-Engine-Version auswählen.

Quell-Hauptversion	Ziel-Hauptversion	Hinweise
Amazon DocumentDB 3.6	Amazon DocumentDB 5.0 (jede veröffentlichte Nebenversion)	Informationen zu Überlegungen Post-upgrade Überlegungen zu Clustern, die von 3.6 oder 4.0 aktualisiert wurden nach dem Upgrade finden Sie unter.
Amazon DocumentDB 4.0	Amazon DocumentDB 5.0 (jede veröffentlichte Nebenversion)	Informationen zu Überlegungen Post-upgrade Überlegungen zu Clustern, die von 3.6 oder 4.0 aktualisiert wurden nach dem Upgrade finden Sie unter.
Amazon DocumentDB 5.0 (jede veröffentlichte Nebenversion)	Amazon DocumentDB 8.0 (jede veröffentlichte Nebenversion)	Informationen zu Funktionsänderungen finden Sie unterWas ändert sich nach dem Upgrade von Amazon DocumentDB 5.0 auf 8.0.

Verwenden Sie den AWS CLI Befehl, um die in Ihrer AWS Region verfügbaren Nebenversionen anzuzeigenaws docdb describe-db-engine-versions. Eine Liste der veröffentlichten Nebenversionen finden Sie unterVersionshinweise.

Anmerkung

Jede MVU kann auf jede veröffentlichte Nebenversion der Ziel-Hauptversion abzielen. Beispielsweise kann ein Upgrade von Amazon DocumentDB 3.6 oder 4.0 direkt auf die neueste veröffentlichte 5.0-Nebenversion durchgeführt werden. Es ist nicht erforderlich, zuerst auf 5.0.0 zu aktualisieren und dann ein Nebenversions-Upgrade durchzuführen.

Um 8.0 von 3.6 oder 4.0 zu erreichen, führen Sie zwei MVUs durch: zuerst auf eine 5.0-Nebenversion Ihrer Wahl, dann auf eine 8.0-Nebenversion Ihrer Wahl. Es gibt keinen direkten 3,6→8,0- oder 4,0→8,0-MVU-Pfad.

Anmerkung

In-place MVU wird für globale Cluster oder elastische Cluster nicht unterstützt. Um einen globalen Cluster zu aktualisieren, entfernen Sie die sekundären Cluster, konvertieren Sie den primären Cluster in einen regionalen Cluster, führen Sie die MVU durch und erstellen Sie dann den globalen Cluster neu, indem Sie sekundäre Cluster mit denselben Namen hinzufügen, um Ihre Endpunkte beizubehalten. Während der aktualisierte primäre Server Daten auf die neuen sekundären Replikationen repliziert, fallen I/O Gebühren an. Die detaillierten Schritte finden Sie unter Einen Cluster aus einem globalen Amazon DocumentDB-Cluster entfernen.

Voraussetzungen

Wichtig

Skalieren Sie Burstable-Instances vor dem Upgrade hoch. Wenn Ihr Cluster Burstable-Instance-Typen verwendet (z. B. db.t3.medium oderdb.t4g.medium), skalieren Sie die primäre Instance auf mindestens db.r5.large oder db.r6g.large bevor Sie das Upgrade initiieren. Burstable-Instances verfügen möglicherweise nicht über genügend CPU und Arbeitsspeicher, um den Upgrade-Vorgang abzuschließen. Dies kann zu Upgrade-Fehlern und einer längeren Nichtverfügbarkeit des Clusters führen. Sie können das System nach Abschluss des Upgrades wieder herunterskalieren.

Skalieren Sie die serverlose Writer-Instanz vor dem Upgrade hoch. Wenn Ihr Cluster über eine serverlose Writer-Instance verfügt, ServerlessV2ScalingConfiguration muss die maximale DCU in der auf 3 oder höher gesetzt werden, bevor das Upgrade initiiert wird. Cluster mit einer maximalen DCU unter 3 können nicht aktualisiert werden, da sie nicht über genügend CPU oder Arbeitsspeicher verfügen, um das Upgrade abzuschließen.

Überprüfen Sie Ihre Teilindizes vor dem Upgrade (Upgrade von Amazon DocumentDB 5.0 auf 8.0). Bevor Sie mit dem Upgrade beginnen, überprüfen Sie Ihre Teilindizes auf einenpartialFilterExpression, der den $type Operator verwendet, um bestimmte BSON-Typen abzugleichen: insbesondere die Aliase binData bool datedouble,decimal,, und den array Typ oder einen numerischen Typcode wie. { "$type" : 1 } Solche Teilindizes führen dazu, dass das Upgrade fehlschlägt, obwohl der Index für Lese- und Schreibvorgänge normal funktioniert. Verwenden Sie diese db.collection.getIndexes() Option, um Ihre partialFilterExpression Teilindizes zu überprüfen. Löschen Sie den betroffenen Teilindex, bevor Sie das Upgrade starten, und erstellen Sie ihn nach Abschluss des Upgrades erneut. Wenn Sie sich nicht sicher sind, ob ein Index betroffen ist, wenden Sie sich vor dem Upgrade an den AWS Support.

• Instanztyp — Amazon DocumentDB 4.0+ unterstützt keine db.r4-Instances. Ändern Sie vor dem Upgrade alle db.r4.* Instances in Instances oder neuere db.r5.* Versionen. Siehe Ändern einer Amazon DocumentDB DocumentDB-Instance und Unterstützte Instance-Klassen nach Region.

• Betriebssystem-Patches — Wenden Sie vor dem Upgrade alle ausstehenden Wartungsmaßnahmen für das Betriebssystem auf alle Instanzen an. Siehe Aktualisierungen des Amazon DocumentDB-Betriebssystems.

  Anmerkung

  Ausstehende Engine-Patches auf Clusterebene können Instanz-Betriebssystem-Patches verbergen. Wenden Sie bei Bedarf zuerst Engine-Patches an. Siehe Durchführung eines Patch-Updates für die Engine-Version eines Clusters.

• Indexgrenzwerte für Burstable-Instances (Instances der T-Familie) — Wenn Sie über mehr als 3.000 Indizes für Burstable-Instances verfügen, skalieren Sie vor dem Upgrade die primäre Instanz auf mindestens db.r5.large. Sie können nach Abschluss des Upgrades wieder herunterskalieren.

  Instance	Maximale Indizes für MVU
  db.t4g.medium	3K
  db.t3.medium	10 K

• Parametergruppe — Halten Sie vor dem Upgrade eine benutzerdefinierte Cluster-Parametergruppe für die Zielversion bereit. Wenn keine Parametergruppe angegeben ist, wird die Standardparametergruppe für die Zielversion verwendet (z. B. default.docdb5.0 oderdefault.docdb8.0).

• Manueller Snapshot — Erstellen Sie vor dem Upgrade einen manuellen Snapshot. Beim Upgrade-Vorgang wird ein automatischer Snapshot mit dem Namen preupgrade-<name>-<version>-<timestamp> erstellt. Erstellen Sie jedoch immer Ihr eigenes Backup. Siehe Einen manuellen Cluster-Snapshot erstellen.

  Anmerkung

  Der durch den Upgrade-Vorgang erstellte automatische Snapshot wird nicht automatisch gelöscht, nachdem das direkte Upgrade der Hauptversion abgeschlossen ist. Für diesen Snapshot fallen keine Gebühren an, solange er innerhalb der Aufbewahrungsfrist liegt. Sie können diesen Snapshot löschen, sobald Sie ein erfolgreiches Upgrade Ihres Clusters überprüft haben.

  

Bewährte Methoden

Vor dem Upgrade — Testen mit einem Klon

1. Wird verwendetKlonen eines Volumes für einen Amazon DocumentDB-Cluster, um einen Klon Ihres Clusters zu erstellen. Es fallen keine Speicherkosten an, es sei denn, Sie ändern die Daten auf dem Clone.

2. Ordnen Sie die Anzahl der Instanzen des Clones dem Ziel-Cluster zu, um eine realistische Zeitschätzung zu erhalten.

3. Führen Sie die MVU auf dem Clone durch und testen Sie sie vollständig auf funktionale Unterschiede.

4. Prüfen Sie, ob ein Upgrade bereits geplant ist, indem Sie es ausführen describe-db-clusters und danach suchenPendingModifiedValues.EngineVersion. Wenn Sie den Cluster geändert und ausgewählt haben, dass er im nächsten Wartungsfenster angewendet werden soll, ist der Zeitplan in der Konsole nicht sichtbar. Sie können ihn jedoch im folgenden Ordner einsehen AWS CLI:

   aws docdb describe-db-clusters \
     --region us-east-1 \
     --db-cluster-identifier mydocdbcluster

   "PendingModifiedValues": {
       "EngineVersion": "5.0.0"
   },

5. Wenn der Test erfolgreich ist, fahren Sie mit dem Upgrade auf Ihrem Produktionscluster fort.

Während des Upgrades

Sie können den Fortschritt Ihres direkten Hauptversions-Upgrades überwachen, indem Sie Cluster-Wartungsveranstaltungen abonnieren. Wenn das Upgrade abgeschlossen ist, erhalten Sie das Ereignis „Die Hauptversion des Datenbank-Clusters wurde aktualisiert“. Dieses und andere Ereignisse, die während des Upgrades auftreten, werden im Abschnitt Ereignisse und Tags der Cluster-Detailseite in der Amazon DocumentDB-Konsole angezeigt. Der Cluster-Status ändert sich dann von upgrading zuavailable.

Die folgenden Ereignisse werden während des Upgrades generiert:

1. Das Upgrade der Hauptversion der Datenbankcluster-Engine wurde gestartet. Der Cluster bleibt online.

2. Upgrade-Vorbereitung im Gange: Die Online-Upgrade-Vorabprüfungen werden gestartet.

3. Upgrade-Vorbereitung im Gange: Die Online-Upgrade-Vorabprüfungen wurden abgeschlossen.

4. Der Datenbankcluster wird offline geschaltet, während die primäre Instanz den patch/upgrade Vorgang abschließt.

5. Upgrade-Vorbereitung läuft: Offline-Upgrade-Vorabprüfungen werden gestartet.

6. Upgrade-Vorbereitung läuft: Offline-Upgrade-Vorabprüfungen wurden abgeschlossen.

7. <version-to><timestamp>Upgrade wird ausgeführt: Vor dem Upgrade wird ein Snapshot erstellt [preupgrade- <cluster-name>- <version-from>-to- -].

8. Upgrade wird ausgeführt: Volume wird geklont.

9. Aktualisierung im Gange: Writer wird aktualisiert.

10. Aktualisierung im Gange: Reader werden aktualisiert.

11. Die Hauptversion der Datenbank-Cluster-Engine wurde aktualisiert.

Ereignisse sind in der Konsole auf der Seite „Ereignisse“ sichtbar:

Von dort aus können Sie das Programm ausführen AWS CLI, aws docdb describe-events um den Upgrade-Fortschritt zu überwachen. Um Benachrichtigungen automatisch zu erhalten, abonnieren Sie Ereignisse und leiten Sie sie für E-Mail, Push-Nachrichten oder andere Übermittlungsmethoden an Amazon SNS weiter. aws docdb create-event-subscription Weitere Informationen finden Sie unter Amazon DocumentDB DocumentDB-Veranstaltungen abonnieren.

aws docdb describe-events 
  --source-identifier mydocdbcluster 
  --source-type db-cluster

Daraufhin erhalten Sie ein Ergebnis, das dem hier dargestellten entspricht:

{
    "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"
        }
    ]
}

Nach dem Upgrade

Warnung

Unmittelbar nach dem direkten Upgrade der Hauptversion füllt Ihr Amazon DocumentDB-Cluster die Index-Metadaten erneut auf, die die Datenbank-Engine zur Optimierung der Abfrageausführungspläne verwendet. Sobald dieser Vorgang abgeschlossen ist, kehrt die Abfrageleistung auf das erwartete Niveau zurück. In der Regel ist er in wenigen Minuten abgeschlossen, kann aber je nach Anzahl der Indizes in Ihrem Cluster bis zu zwei Stunden dauern.

Starten Sie up/down Ihre Writer-Instance während dieser Zeit nicht neu, führen Sie kein Failover durch oder skalieren Sie sie nicht, da dies die Neuberechnung der Index-Metadaten stören kann. Warten Sie, bis Sie die erwartete Abfrageleistung beobachten, bevor Sie solche Änderungen vornehmen.

Verfolgen Sie den Fortschritt anhand der folgenden Cluster-Ereignisse:

• Post-upgrade Cluster-Status: Die Aktualisierung der Index-Metadaten wurde gestartet

• Post-upgrade Clusterstatus: Die Aktualisierung der Indexmetadaten wurde in X Sekunden abgeschlossen

Wenden Sie sich an den AWS Support, wenn die Aktualisierung der Index-Metadaten nicht innerhalb von drei Stunden abgeschlossen ist oder wenn nach Abschluss des Vorgangs weiterhin Leistungsprobleme auftreten.

1. Erstellen Sie einen manuellen Snapshot des aktualisierten Clusters für den Fall, dass Sie den Zustand nach dem Upgrade wiederherstellen müssen. Der automatische Snapshot-Vorgang wird fortgesetzt, sobald das direkte Upgrade der Hauptversion abgeschlossen ist.

2. Tag-Cluster wurden von Version 3.6 aktualisiert. Fügen Sie ein Tag hinzu, um Cluster zu unterscheiden, für die ein Upgrade von 3.6 durchgeführt wurde. (siehePost-upgrade Überlegungen zu Clustern, die von 3.6 oder 4.0 aktualisiert wurden).

3. Aktualisieren Sie Ihren Treiber. Um neue Funktionen zu verwenden (z. B. Sortierung, Ansichten oder Zstd-Komprimierung in 8.0), führen Sie ein Upgrade auf die entsprechende MongoDB-API-Version durch. Weitere Informationen finden Sie unter Was ist neu in Amazon DocumentDB 8.0.

4. Gründlich testen. Validieren Sie Ihre Anwendung anhand des aktualisierten Clusters.

Was ändert sich nach dem Upgrade von Amazon DocumentDB 5.0 auf 8.0

Nach einem Upgrade der Hauptversion von Amazon DocumentDB 5.0 auf 8.0 werden die folgenden Funktionen aktiviert oder geändert:

• Sortierung. Amazon DocumentDB 8.0 unterstützt die Sortierung. Nach dem Upgrade ist die Sortierung für neue Sammlungen und ihre Indizes sowie für neue Indizes vorhandener Sammlungen standardmäßig aktiviert.

• Textindex. Neue Textindizes werden mit Text Index V2 erstellt, der einen aktualisierten Textsuchparser für eine verbesserte MongoDB-Kompatibilität verwendet. Bestehende Textindizes sind nicht betroffen.

• Version des Abfrageplaners. Wenn Sie keine benutzerdefinierte Parametergruppe hatten, wird eine neue Standardparametergruppe für Amazon DocumentDB 8.0 erstellt, wobei Planner Version 3 automatisch ausgewählt wird. In der Version 3 des Abfrageplaners sind auch Ansichten verfügbar.

• Komprimierung. Amazon DocumentDB 8.0 unterstützt die wörterbuchbasierte Dokumentenkomprimierung mithilfe des Zstd-Algorithmus. Nach dem Upgrade werden neue Sammlungen mit standardmäßig aktivierter Zstd-Komprimierung erstellt. Bestehende Sammlungen aus 5.0 behalten ihre Komprimierungseinstellungen bei. Um die Vorteile der Zstd-Komprimierung für bestehende Sammlungen zu nutzen, können Sie deren Komprimierungseinstellungen ändern. Weitere Informationen finden Sie unter Verwaltung der wörterbuchbasierten Komprimierung in Amazon DocumentDB 8.0.

• Neuerstellung des Indexes Wenn Sie ein Upgrade von Amazon DocumentDB 5.0 auf Amazon DocumentDB 8.0 durchführen, ist keine Indexneuerstellung erforderlich.

Wichtig

Amazon DocumentDB 8.0 erfordert TLS 1.2 oder höher. TLS 1.0 und TLS 1.1 werden nicht mehr unterstützt.

Anmerkung

Eine vollständige Liste der funktionalen Unterschiede finden Sie unterAmazon DocumentDB-Kompatibilität mit MongoDB.

Post-upgrade Überlegungen zu Clustern, die von 3.6 oder 4.0 aktualisiert wurden

• Neuerstellung des Indexes Eine MVU behält die ursprünglichen Indizes bei. Amazon DocumentDB 5.0 hat die Indexverwaltung und die Speicherbereinigung verbessert, insbesondere für Indizes mit niedriger Kardinalität. Erstellen Sie nach dem Upgrade von 3.6 oder 4.0 Ihre Indizes neu, um eine optimale Abfrageleistung sicherzustellen (optional, erfordert zusätzliche). I/O Siehe Indexverwaltung mithilfe von Reindex.

• Numerischer Vergleich von Unterdokumenten (nur 3.6). Cluster, die von 3.6 aktualisiert wurden, erben das 3.6-Verhalten, bei dem numerische Typen in Unterdokumenten nicht typübergreifend verglichen werden. {a: {b: NumberLong(1)}}Entspricht beispielsweise {a: {b: 1}} in 3.6 nicht, aber sie sind in 4.0 und höher gleich. Dieses Verhalten wirkt sich auf alle Cluster aus, die von 3.6 aktualisiert wurden.

Durchführung des Upgrades

Using the AWS-Managementkonsole

1. Melden Sie sich bei der Amazon DocumentDB-Konsole an AWS-Managementkonsole und öffnen Sie sie.

2. Wählen Sie in der Cluster-Tabelle den Quell-Cluster aus, wählen Sie Actions und anschließend Modify aus.

   

3. Wählen Sie in den Cluster-Spezifikationen die Zielversion (z. B. 5.0.0 oder 8.0.0) aus dem Drop-down-Menü Engine-Version aus.

   

4. Wählen Sie in den Cluster-Optionen Ihre Cluster-Parametergruppe für die Ziel-Engine-Version aus. Sie können die Standardparametergruppe (z. B. default.docdb5.0 oder default.docdb8.0) oder eine benutzerdefinierte Parametergruppe verwenden, die Sie erstellt haben.

   

5. Wählen Sie „Fortfahren“, wählen Sie Ihre bevorzugte Terminplanung aus (sofort anwenden oder nächstes Wartungsfenster) und wählen Sie dann „Cluster ändern“.

   

6. Überwachen Sie den Clusterstatus in der Cluster-Tabelle, wenn er sich beim Upgrade ändert:

   

Using the AWS CLI

modify-db-clusterMit der --allow-major-version-upgrade Flagge verwenden:

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

Ersetzen Sie jedes placeholder durch die Informationen Ihres Clusters.

Fehlerbehebung

• Pre-upgrade Überprüfen Sie den Fehler. Bevor das Upgrade beginnt, führt Amazon DocumentDB Validierungsprüfungen vor dem Upgrade durch. Die folgenden Ursachen sind häufig für Fehlschläge bei der Vorabprüfung aufgeführt:

  • Das Upgrade konnte nicht fortgesetzt werden, da die Sammlung (en) Namen mit 58 oder mehr Zeichen haben. Benennen Sie die betroffenen Sammlungen in kürzere Namen um, bevor Sie das Upgrade erneut versuchen.

  • Das Upgrade konnte nicht fortgesetzt werden, da die Indexanzahl den Grenzwert für den Instanztyp überschreitet. Führen Sie ein Upgrade auf einen größeren Instanztyp durch, bevor Sie das Upgrade erneut versuchen. Informationen zu Indexlimits nach Instanztyp finden Sie unterVoraussetzungen.

• Upgrade-Fehler und Rollback. Schlägt das Upgrade fehl, wird automatisch ein Rollback versucht. Ein erfolgreiches Rollback generiert das folgende Ereignis: „Der Datenbankcluster befindet sich in einem Zustand, der nicht aktualisiert werden kann.“ Ihr Cluster kehrt in den Zustand vor dem Upgrade zurück und Sie können ihn weiter verwenden. Wenden Sie sich zur Problembehebung an den AWS Support, bevor Sie es erneut versuchen.

• Post-upgrade Leistung. Während der Aktualisierung der Indexmetadaten können vorübergehende Leistungseinbußen und eine hohe CPU-Auslastung auftreten. Wenn die Leistungseinbußen länger als 3 Stunden andauern, wenden Sie sich an den AWS Support.

Für weitere Unterstützung wenden Sie sich bitte an AWS Support.