Chemins de mise à niveau pris en charge Conditions préalables Bonnes pratiques Quels sont les changements après la mise à niveau d'Amazon DocumentDB 5.0 vers la version 8.0 Post-upgrade considérations relatives aux clusters mis à niveau depuis 3.6 ou 4.0 Exécution de la mise à niveau Résolution des problèmes

Mise à niveau de la version majeure d'Amazon DocumentDB sur place

Vous pouvez effectuer une mise à niveau de version majeure (MVU) sur place de votre cluster Amazon DocumentDB tout en conservant les mêmes points de terminaison, le même stockage et les mêmes balises. Vos applications continuent de fonctionner sans modifications. Cette fonctionnalité est disponible sans frais supplémentaires partout Régions AWS où Amazon DocumentDB est disponible.

Important

Votre cluster n'est pas disponible pendant la mise à niveau et redémarre plusieurs fois. Ne vous connectez pas au cluster, ne le lisez pas et n'écrivez pas sur celui-ci après avoir démarré la mise à niveau. Les temps d'arrêt varient en fonction du nombre de collections, d'index, de bases de données et d'instances. Effectuez la mise à niveau pendant votre période de maintenance ou pendant les heures de faible utilisation.

Une fois la mise à niveau effectuée, vous ne pouvez pas revenir à une version précédente. Vous pouvez restaurer votre instantané d'avant la mise à niveau vers un nouveau cluster si nécessaire.

Rubriques

Chemins de mise à niveau pris en charge
Conditions préalables
Bonnes pratiques
Quels sont les changements après la mise à niveau d'Amazon DocumentDB 5.0 vers la version 8.0
Post-upgrade considérations relatives aux clusters mis à niveau depuis 3.6 ou 4.0
Exécution de la mise à niveau
Résolution des problèmes

Chemins de mise à niveau pris en charge

Le tableau suivant répertorie tous les chemins de mise à niveau des versions majeures sur place pris en charge. Vous pouvez sélectionner n'importe quelle version mineure publiée sur la majeure cible comme version du moteur cible.

Version majeure de la source	Version majeure cible	Remarques
Amazon DocumentDB 3.6	Amazon DocumentDB 5.0 (toute version mineure publiée)	Consultez les Post-upgrade considérations relatives aux clusters mis à niveau depuis 3.6 ou 4.0 considérations relatives à la mise à niveau.
Amazon DocumentDB 4.0	Amazon DocumentDB 5.0 (toute version mineure publiée)	Consultez les Post-upgrade considérations relatives aux clusters mis à niveau depuis 3.6 ou 4.0 considérations relatives à la mise à niveau.
Amazon DocumentDB 5.0 (toute version mineure publiée)	Amazon DocumentDB 8.0 (toute version mineure publiée)	Consultez Quels sont les changements après la mise à niveau d'Amazon DocumentDB 5.0 vers la version 8.0 les modifications apportées aux fonctionnalités.

Pour consulter les versions mineures disponibles dans votre AWS région, utilisez la AWS CLI commandeaws docdb describe-db-engine-versions. Pour une liste des versions mineures publiées, voirNotes de mise à jour.

Note

Chaque MVU peut cibler n'importe quelle version mineure publiée sur la majeure de destination. Par exemple, la mise à niveau depuis Amazon DocumentDB 3.6 ou 4.0 peut passer directement à la dernière version mineure 5.0 publiée ; il n'est pas nécessaire de passer d'abord à la version 5.0.0, puis d'appliquer une mise à niveau de version mineure.

Pour passer de 3.6 à 4.0 à 8.0, exécutez deux MVU : d'abord vers une version mineure 5.0 de votre choix, puis vers une version mineure 8.0 de votre choix. Il n'existe pas de chemin MVU direct 3,6→8,0 ou 4,0→8,0.

Note

In-place MVU n'est pas pris en charge pour les clusters globaux ou élastiques. Pour mettre à niveau un cluster global, supprimez les clusters secondaires, convertissez le cluster principal en cluster régional, exécutez le MVU, puis recréez le cluster global en ajoutant des clusters secondaires portant les mêmes noms afin de conserver vos points de terminaison. I/O Des frais vous seront facturés pendant que le serveur principal mis à niveau répliquera les données vers les nouveaux systèmes secondaires. Pour obtenir des instructions complètes, consultez Supprimer un cluster d'un cluster global Amazon DocumentDB.

Conditions préalables

Important

Augmentez la taille des instances explosibles avant la mise à niveau. Si votre cluster utilise des types d'instances évolutifs (par exemple, db.t3.medium oudb.t4g.medium), augmentez la taille de l'instance principale au moins db.r5.large ou db.r6g.large avant de lancer la mise à niveau. Les instances explosibles peuvent ne pas disposer de suffisamment de CPU et de mémoire pour terminer le processus de mise à niveau, ce qui peut entraîner des échecs de mise à niveau et une indisponibilité prolongée du cluster. Vous pouvez réduire la taille une fois la mise à niveau terminée.

Faites évoluer l'instance d'écriture sans serveur avant de procéder à la mise à niveau. Si votre cluster possède une instance d'écriture sans serveur, la DCU maximale ServerlessV2ScalingConfiguration doit être définie sur 3 ou plus avant de lancer la mise à niveau. Les clusters dont la DCU maximale est inférieure à 3 ne peuvent pas être mis à niveau car ils ne disposent pas de suffisamment de processeur ou de mémoire pour terminer la mise à niveau.

Vérifiez vos index partiels avant la mise à niveau (mise à niveau d'Amazon DocumentDB 5.0 vers la version 8.0). Avant de commencer la mise à niveau, vérifiez si vos index partiels utilisent l'$typeopérateur pour correspondre à certains types de BSON : en particulier les alias binDatabool,date, doubledecimal, et de array type, ou un code de type numérique tel que. partialFilterExpression { "$type" : 1 } Ces index partiels entraînent l'échec de la mise à niveau, même si l'index fonctionne normalement pour les lectures et les écritures. db.collection.getIndexes()Utilisez-le pour consulter vos index partiels. partialFilterExpression Supprimez l'index partiel concerné avant de démarrer la mise à niveau et recréez-le une fois la mise à niveau terminée. Si vous ne savez pas si un index est concerné, contactez le AWS support avant de procéder à la mise à niveau.

Type d'instance : Amazon DocumentDB 4.0+ ne prend pas en charge les instances db.r4. Modifiez toutes db.r4.* les instances en db.r5.* instances ou plus récentes avant de procéder à la mise à niveau. Consultez Modification d'une instance Amazon DocumentDB et Classes d'instances prises en charge par région.
Correctifs du système d'exploitation : appliquez toutes les actions de maintenance du système d'exploitation en attente sur toutes les instances avant la mise à niveau. Consultez Mises à jour du système d'exploitation Amazon DocumentDB.

Note
Les correctifs de moteur au niveau du cluster en attente peuvent masquer les correctifs du système d'exploitation de l'instance. Appliquez d'abord les correctifs sur le moteur si nécessaire. Consultez Exécution d'une mise à jour corrective de la version du moteur d'un cluster.
Limites d'index sur les instances éclatables (instances de la famille T) : si vous avez plus de 3 000 index sur les instances éclatables, augmentez la taille de l'index principal à au moins db.r5.large avant de procéder à la mise à niveau. Vous pouvez réduire la taille une fois la mise à niveau terminée.

Instance Indices maximaux pour MVU

db.t4g.medium

3 KM

db.t3.medium

10 000
Groupe de paramètres : préparez un groupe de paramètres de cluster personnalisé pour la version cible avant la mise à niveau. Si aucun n'est spécifié, le groupe de paramètres par défaut pour la version cible sera utilisé (par exemple, default.docdb5.0 oudefault.docdb8.0).
Instantané manuel : créez un instantané manuel avant la mise à niveau. Le processus de mise à niveau crée un instantané automatique nommépreupgrade-<name>-<version>-<timestamp>, mais créez toujours votre propre sauvegarde. Consultez Création d'un instantané de cluster manuel.

Note
L'instantané automatique créé par le processus de mise à niveau ne sera pas automatiquement supprimé une fois la mise à niveau de la version majeure sur place terminée. Cet instantané n'entraînera aucun frais tant qu'il se situe pendant la période de conservation. Vous pouvez choisir de supprimer cet instantané une fois que vous avez vérifié la réussite de la mise à niveau de votre cluster.

Instance	Indices maximaux pour MVU
db.t4g.medium	3 KM
db.t3.medium	10 000

Bonnes pratiques

Avant la mise à niveau : test avec un clone

Clonage d'un volume pour un cluster Amazon DocumentDBUtilisez-le pour créer un clone de votre cluster. Vous n'aurez pas à payer de frais de stockage à moins de modifier les données du clone.
Faites correspondre le nombre d'instances du clone au cluster cible pour obtenir une estimation de temps réaliste.
Effectuez le MVU sur le clone et testez complètement les différences fonctionnelles.
Vérifiez si une mise à niveau est déjà planifiée en exécutant describe-db-clusters et en recherchantPendingModifiedValues.EngineVersion. Si vous avez modifié le cluster et choisi de l'appliquer dans la prochaine fenêtre de maintenance, le calendrier ne sera pas visible dans la console mais vous pouvez le consulter dans le AWS CLI :
```
aws docdb describe-db-clusters \
  --region us-east-1 \
  --db-cluster-identifier mydocdbcluster
```
```
"PendingModifiedValues": {
    "EngineVersion": "5.0.0"
},
```
Si les tests sont réussis, procédez à la mise à niveau sur votre cluster de production.

Pendant la mise à niveau

Vous pouvez suivre la progression de la mise à niveau de votre version majeure sur place en vous inscrivant aux événements de maintenance du cluster. Une fois la mise à niveau terminée, vous recevrez l'événement « La version majeure du cluster de base de données a été mise à niveau ». Cet événement, ainsi que d'autres événements survenant lors de la mise à niveau, apparaissent dans la section Événements et balises de la page détaillée du cluster de la console Amazon DocumentDB. L'état du cluster passe ensuite de upgrading àavailable.

Les événements suivants sont générés lors de la mise à niveau :

La mise à niveau de la version majeure du moteur de cluster de base de données a Le cluster reste en ligne.
Préparation de la mise à niveau en cours : lancement des vérifications préalables à la mise à niveau en ligne.
Préparation de la mise à niveau en cours : vérifications préalables à la mise à niveau en ligne terminées.
Mise hors ligne du cluster de bases de données pendant que l'instance principale termine le patch/upgrade processus.
Préparation de la mise à niveau en cours : lancement des prévérifications de mise à niveau hors ligne.
Préparation de la mise à niveau en cours : vérifications préalables de mise à niveau hors ligne terminées.
<version-to><timestamp>Mise à niveau en cours : création d'un instantané préalable à la mise à niveau [preupgrade- <cluster-name>- <version-from>-to- -].
Mise à niveau en cours : volume de clonage.
Mise à niveau en cours : mise à niveau de Writer.
Mise à niveau en cours : mise à niveau des lecteurs.
La version majeure du moteur de cluster de bases de données a été mise à niveau.

Les événements sont visibles dans la console, sous la page Événements :

Image : la zone de navigation Événements présentant un tableau des événements de mise à niveau.

À partir de AWS CLI, vous pouvez exécuter aws docdb describe-events pour suivre la progression de la mise à niveau. Pour recevoir des notifications automatiquement, abonnez-vous aws docdb create-event-subscription à des événements et redirigez-les vers Amazon SNS pour recevoir des e-mails, des messages push ou d'autres modes de livraison. Pour de plus amples informations, veuillez consulter Abonnement aux événements Amazon DocumentDB.


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

La commande renvoie un résultat semblable à ce qui suit :


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

Après la mise à niveau

Avertissement

Immédiatement après la mise à niveau de la version majeure sur place, votre cluster Amazon DocumentDB reremplit les métadonnées d'index que le moteur de base de données utilise pour optimiser les plans d'exécution des requêtes. Les performances des requêtes retrouvent les niveaux attendus une fois ce processus terminé. Il se termine généralement en quelques minutes, mais peut prendre jusqu'à deux heures en fonction du nombre d'index de votre cluster.

Ne redémarrez pas, ne basculez pas et ne up/down redimensionnez pas votre instance Writer pendant cette période, car cela pourrait perturber le recalcul des métadonnées de l'index. Attendez d'observer les performances de requête attendues avant de procéder à de telles modifications.

Suivez les progrès grâce aux événements du cluster suivants :

Post-upgrade état du cluster : le processus d'actualisation des métadonnées de l'index a commencé
Post-upgrade état du cluster : le processus d'actualisation des métadonnées de l'index s'est terminé en X secondes

Contactez l' AWS assistance si le processus d'actualisation des métadonnées de l'index n'est pas terminé dans les trois heures, ou si vous continuez à rencontrer des problèmes de performances une fois le processus terminé.

Prenez une capture d'écran manuelle du cluster mis à niveau au cas où vous auriez besoin de rétablir l'état après la mise à niveau. Le processus de capture automatique reprendra dès que la mise à niveau de la version majeure sur place sera terminée.
Clusters de balises mis à niveau depuis la version 3.6. Ajoutez une balise pour différencier les clusters mis à niveau depuis la version 3.6. (voirPost-upgrade considérations relatives aux clusters mis à niveau depuis 3.6 ou 4.0).
Mettez à jour votre pilote. Pour utiliser les nouvelles fonctionnalités (par exemple, le classement, les vues ou la compression Zstd dans la version 8.0), passez à la version correspondante de l'API MongoDB. Pour de plus amples informations, veuillez consulter Nouveautés d'Amazon DocumentDB 8.0.
Testez minutieusement. Validez votre application par rapport au cluster mis à niveau.

Quels sont les changements après la mise à niveau d'Amazon DocumentDB 5.0 vers la version 8.0

Après avoir effectué une mise à niveau majeure d'Amazon DocumentDB 5.0 vers la version 8.0, les fonctionnalités suivantes sont activées ou modifiées :

Collation. Amazon DocumentDB 8.0 prend en charge le classement. Après la mise à niveau, le classement est activé par défaut pour les nouvelles collections et leurs index, ainsi que pour les nouveaux index des collections existantes.
Index de texte. Les nouveaux index de texte sont créés à l'aide de Text Index V2, qui utilise un analyseur de recherche de texte mis à jour pour améliorer la compatibilité avec MongoDB. Les index de texte existants ne sont pas affectés.
Version du planificateur de requêtes. Si vous ne disposiez pas d'un groupe de paramètres personnalisé, un nouveau groupe de paramètres par défaut est créé pour Amazon DocumentDB 8.0 avec Planner Version 3 automatiquement sélectionné. Avec la version 3 du planificateur de requêtes, des vues sont également disponibles.
Compression. Amazon DocumentDB 8.0 prend en charge la compression de documents basée sur un dictionnaire à l'aide de l'algorithme Zstd. Après la mise à niveau, de nouvelles collections sont créées avec la compression Zstd activée par défaut. Les collections existantes de la version 5.0 conservent leurs paramètres de compression. Pour tirer parti de la compression Zstd sur les collections existantes, vous pouvez modifier leurs paramètres de compression. Pour de plus amples informations, veuillez consulter Gestion de la compression basée sur un dictionnaire dans Amazon DocumentDB 8.0.
Reconstruction de l'index. Si vous effectuez une mise à niveau d'Amazon DocumentDB 5.0 vers Amazon DocumentDB 8.0, aucune reconstruction d'index n'est nécessaire.

Important

Amazon DocumentDB 8.0 nécessite le protocole TLS 1.2 ou supérieur. Les protocoles TLS 1.0 et TLS 1.1 ne sont plus pris en charge.

Note

Pour une liste complète des différences fonctionnelles, voirCompatibilité d'Amazon DocumentDB avec MongoDB.

Post-upgrade considérations relatives aux clusters mis à niveau depuis 3.6 ou 4.0

Reconstruction de l'index. Un MVU conserve les index d'origine. Amazon DocumentDB 5.0 a amélioré la maintenance des index et la collecte des déchets, en particulier pour les index à faible cardinalité. Après la mise à niveau depuis 3.6 ou 4.0, reconstruisez vos index pour garantir des performances de requête optimales (facultatif, implique des éléments supplémentaires I/O). Consultez Maintenance de l'index à l'aide de ReIndex.
Comparaison numérique des sous-documents (3.6 uniquement). Les clusters mis à niveau à partir de la version 3.6 héritent du comportement de la version 3.6 selon lequel les types numériques des sous-documents ne sont pas comparés entre les types. Par exemple, {a: {b: NumberLong(1)}} n'est pas égal {a: {b: 1}} dans 3.6, mais ils sont égaux dans 4.0 et versions ultérieures. Ce comportement affecte tous les clusters mis à niveau depuis la version 3.6.

Exécution de la mise à niveau

Résolution des problèmes

Pre-upgrade échec de la vérification. Avant le début de la mise à niveau, Amazon DocumentDB effectue des contrôles de validation avant la mise à niveau. Les causes courantes d'échec des contrôles préalables sont les suivantes :
- La mise à niveau n'a pas pu se poursuivre car les collections ont des noms de 58 caractères ou plus. Renommez les collections concernées en leur attribuant des noms plus courts avant de recommencer la mise à niveau.
- La mise à niveau n'a pas pu avoir lieu car le nombre d'index dépasse la limite pour le type d'instance. Passez à un type d'instance plus important avant de recommencer la mise à niveau. Pour les limites d'index par type d'instance, consultezConditions préalables.
Échec de la mise à niveau et restauration. Si la mise à niveau échoue, elle tente automatiquement une restauration. Une restauration réussie génère l'événement suivant : « Le cluster de bases de données est dans un état qui ne peut pas être mis à niveau ». Votre cluster revient à son état d'avant la mise à niveau et vous pouvez continuer à l'utiliser. Contactez le AWS support pour résoudre les problèmes avant de réessayer.
Post-upgrade performance. Une dégradation temporaire des performances et une utilisation élevée du processeur peuvent survenir lors de l'actualisation des métadonnées de l'index. Si la dégradation persiste au-delà de 3 heures, contactez AWS le support.

Pour obtenir de l'aide supplémentaire, contactez AWS Support.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Dates de support des versions du moteur

Mise à niveau d'une version mineure du moteur