ApsaraDB for ClickHouse:One-click major engine version upgrade

Prérequis

Le cluster doit être dans l'état Running.

Notes d'utilisation

• Il est impossible d'annuler le processus de mise à niveau majeure du moteur en un clic une fois celui-ci démarré.

  Remarque

  Un retour à la version précédente n'est pas pris en charge après une mise à niveau majeure du moteur en un clic. Si vous souhaitez pouvoir revenir à la version antérieure après la mise à niveau, effectuez celle-ci en clonant le cluster. Pour plus d'informations, consultez la rubrique Mettre à niveau la version majeure du moteur par clonage.

• Pour garantir le bon déroulement de la mise à niveau, nous vous recommandons d'interrompre les opérations d'écriture depuis votre application avant de démarrer le processus. Bien que le cluster arrête automatiquement les écritures pendant l'opération, l'absence d'interruption préalable au niveau de l'application risque de provoquer des délais importants ou d'empêcher la synchronisation de se terminer rapidement, ce qui ralentirait la mise à niveau.

• Afin de minimiser l'impact sur votre activité, nous vous recommandons vivement d'effectuer les validations suivantes avant la mise à niveau :

  • Validation de la compatibilité et des performances : vérifiez les éventuelles différences en matière de fonctionnalités, de syntaxe et de performances pour les opérations d'écriture et de requête.

  • Validation de la durée de mise à niveau : l'instance redémarre plusieurs fois lors de la mise à niveau de version. Pour certaines instances, un seul redémarrage peut prendre beaucoup de temps en raison du grand nombre de bases de données, de tables ou de partitions (parts).

    Important

    Si le cluster utilise le stockage hiérarchisé pour les données chaudes et froides et que vous effectuez une validation par clonage, la mise à niveau en un clic prendra plus de temps que la validation. En effet, l'opération de clonage n'inclut pas les données froides, contrairement à la mise à niveau réelle.

  Pour savoir comment effectuer cette validation, consultez la section Valider la compatibilité des versions.

Impact sur le cluster

Le cluster redémarre plusieurs fois pendant la mise à niveau et n'est pas disponible pour les opérations de lecture et d'écriture lors de chaque redémarrage. Nous vous recommandons d'effectuer la mise à niveau pendant les heures creuses.

Valider la compatibilité des versions

Une mise à niveau majeure du moteur en un clic ne peut pas faire l'objet d'un retour arrière. Nous vous recommandons vivement de tester la mise à niveau au préalable pour confirmer que la nouvelle version est entièrement compatible avec la version source et que la durée de mise à niveau est acceptable :

1. Accédez à la page Cluster Information de l'instance cible. Dans le volet de navigation de gauche, cliquez sur Backup and Restoration. Une fois l'instance sauvegardée, cliquez sur Restore Instance.

2. Sélectionnez Clone from real-time replica et définissez la version cible du moteur sur la version vers laquelle vous souhaitez effectuer la mise à niveau.

3. Créez le cluster cloné.

4. Effectuez la validation de compatibilité.

   1. Validez la compatibilité de vos requêtes métier avec la nouvelle version. Pour plus d'informations, consultez la rubrique Validation de la compatibilité SQL.

   2. Effectuez des tests de régression pour vos fonctionnalités métier.

Procédure

1. Connectez-vous à la console ApsaraDB for ClickHouse avec votre compte Alibaba Cloud.

2. Dans le coin supérieur gauche de la page, sélectionnez la région où se trouve le cluster cible.

3. Dans le volet de navigation de gauche, cliquez sur Clusters of Community-compatible Edition.

4. Localisez le cluster cible et cliquez sur son ID pour accéder à la page Cluster Information.

5. Dans la section Cluster Properties, cliquez sur Major Version Upgrade à côté de Version.

6. Configurez les paramètres suivants comme indiqué, puis cliquez sur OK.

   Paramètre	Description	Exemple
   Upgrade cluster kernel version to	Version cible du cluster. Un retour à la version précédente n'est pas pris en charge après la mise à niveau. Actuellement, seule la version 23.8 est prise en charge.	23.8 (version LTS)
   Version upgrade execution time	Moment auquel effectuer la mise à niveau du cluster. Important Si vous choisissez d'effectuer la mise à niveau à une heure précise ou durant une fenêtre de maintenance, l'état du cluster passe de Running à Upgrading. Avant l'heure spécifiée ou l'ouverture de la fenêtre de maintenance, le cluster peut traiter normalement les requêtes de lecture et d'écriture, mais vous ne pouvez pas effectuer d'opérations de maintenance telles que la modification de la configuration de l'instance, la mise à l'échelle ou la migration. Specified Time : sélectionnez un moment futur pour effectuer la mise à niveau majeure de version. Upgrade Within Maintenance Window : la mise à niveau est effectuée durant la fenêtre de maintenance configurée pour le cluster. Update Now : démarre la mise à niveau immédiatement.	2024-05-29 14:46
   Perform clone validation	Sélectionnez Clone Validation Performed ou Skip Clone Verification (Not Recommended).	Clone validation performed

Prérequis

Le cluster doit être dans l'état Running.

Notes d'utilisation

• Une mise à niveau majeure du moteur en un clic concerne un seul cluster et il est impossible de revenir à la version précédente une fois la mise à niveau terminée.

  Remarque

  Un retour à la version précédente n'est pas pris en charge après une mise à niveau majeure du moteur en un clic. Si vous souhaitez pouvoir revenir à la version antérieure après la mise à niveau, effectuez celle-ci en migrant les données. Pour plus d'informations, consultez la rubrique Mettre à niveau la version majeure du moteur par migration de données.

• Lors de la mise à niveau d'un cluster, tenez compte des points suivants concernant ses bases de données et ses tables :

  • Pour les tables utilisant un moteur de la famille MergeTree, les données historiques sont migrées vers le nouveau cluster et redistribuées automatiquement pendant la mise à niveau.

  • Pour les tables n'utilisant pas un moteur de la famille MergeTree, telles que les tables externes ou les tables Log, seuls les schémas de table sont migrés. Les données ne sont pas migrées.

  • Pour une vue matérialisée, seul le schéma est migré. Les données ne sont pas migrées.

  • Les tables utilisant les moteurs Kafka et RabbitMQ ne peuvent pas être migrées directement via la fonctionnalité de mise à niveau de la console. Vous devez enregistrer les instructions DDL de ces tables et les supprimer du cluster avant la mise à niveau afin d'éviter toute interférence avec la tâche de mise à niveau. Une fois la mise à niveau terminée, vous devez recréer ces tables. Consultez la procédure ci-dessous pour connaître les étapes détaillées.

  • Les adresses IP internes des nœuds changent après la mise à niveau. Si vos écritures de données et vos accès dépendent des adresses IP des nœuds, vous devez obtenir le nouveau plage d'adresses VPC du cluster.

• Afin de minimiser l'impact sur votre activité, nous vous recommandons vivement d'effectuer les validations suivantes avant la mise à niveau :

  • Validation de la compatibilité et des performances : vérifiez les éventuelles différences en matière de fonctionnalités, de syntaxe et de performances pour les opérations d'écriture et de requête.

  • Validation de la durée de mise à niveau : l'instance redémarre plusieurs fois lors de la mise à niveau de version. Pour certaines instances, un seul redémarrage peut prendre beaucoup de temps en raison du grand nombre de bases de données, de tables ou de partitions (parts).

  Pour savoir comment effectuer cette validation, consultez la section Valider la compatibilité des versions.

Impact sur le cluster

Un cluster Community Edition reste accessible en lecture et en écriture tout au long du processus de mise à niveau, sauf durant les 10 dernières minutes de la migration où le cluster passe en lecture seule. Pour vérifier le temps restant avant la fin de la migration, consultez la section Afficher la progression de la mise à niveau.

Valider la compatibilité des versions

Une mise à niveau majeure du moteur en un clic ne peut pas faire l'objet d'un retour arrière. Nous vous recommandons vivement de tester la mise à niveau au préalable pour confirmer que la nouvelle version est entièrement compatible avec la version source et que la durée de mise à niveau est acceptable :

1. Achetez un nouveau cluster pour effectuer la validation de la migration. Pour plus d'informations, consultez la rubrique Mettre à niveau la version majeure du moteur par migration de données.

2. Dans le nouveau cluster, effectuez la validation de la compatibilité SQL. Pour plus d'informations, consultez la rubrique Validation de la compatibilité SQL.

3. Effectuez des tests de régression pour vos fonctionnalités métier.

Étape 1 : enregistrer et nettoyer les tables utilisant les moteurs Kafka/RabbitMQ

Les tables utilisant les moteurs Kafka et RabbitMQ ne peuvent pas être migrées directement via la fonctionnalité de mise à niveau de la console. Enregistrez les instructions DDL de ces tables et supprimez-les avant la mise à niveau afin d'éviter toute interférence avec la tâche de mise à niveau.

1. Connectez-vous au cluster et exécutez l'instruction suivante pour rechercher les tables à traiter.

   /*
   create_table_query: table definition statement
   dependencies_database: database that depends on this table
   dependencies_table: table name that depends on this table
   Use dependencies_database and dependencies_table to identify materialized views that depend on Kafka/RabbitMQ tables
   */
   SELECT * FROM system.tables WHERE engine IN ('RabbitMQ', 'Kafka');

2. Consultez la définition de la vue matérialisée pour vérifier si sa table cible est une table implicite.

   /*
   View the materialized view definition.
   If the target table of the materialized view is an implicit table, note the following:
   Deleting the materialized view will also delete the implicit table, resulting in data loss.
   Example: If CREATE MATERIALIZED VIEW [db.]table_name [TO[db.]name] does not specify the TO clause,
   the system automatically creates an implicit table in the format '.inner_id.<TABLE_UUID>' or '.inner.<TABLE>'
   */
   SELECT * FROM system.tables WHERE database='<DATABASE>' AND name = '<MATERIALIZED_VIEW_NAME>';

3. Si une vue matérialisée a été créée sans la clause TO, le système génère automatiquement une table cible implicite préfixée par .inner ou .inner_id. Ces tables implicites sont migrées vers les nœuds du nouveau cluster lors de la mise à niveau, mais en raison des mécanismes de nommage internes, la recréation directe de la vue matérialisée d'origine peut provoquer des conflits de nommage. Par conséquent, vous devez d'abord renommer les tables cibles implicites avec des noms de table standards.

   -- Rename implicit target tables to regular table names (execute on all nodes)
   RENAME TABLE <database>.`.inner_id.<uuid>` TO <database>.<new_target_table_name> ON CLUSTER default;

4. Supprimez les vues matérialisées et les tables utilisant les moteurs Kafka/RabbitMQ.

   Important

   Vous devez d'abord supprimer les vues matérialisées qui référencent les tables Kafka/RabbitMQ, puis supprimer les tables utilisant les moteurs Kafka/RabbitMQ. Sinon, l'opération de mise à niveau échouera.

   -- Delete materialized views first
   DROP TABLE <database>.<materialized_view_name> ON CLUSTER default;
   
   -- Then delete Kafka/RabbitMQ engine tables
   DROP TABLE <database>.<kafka_or_rabbitmq_table_name> ON CLUSTER default;

Étape 2 : mettre à niveau le cluster

1. Connectez-vous à la console ApsaraDB for ClickHouse avec votre compte Alibaba Cloud.

2. Dans le coin supérieur gauche de la page, sélectionnez la région où se trouve le cluster cible.

3. Dans le volet de navigation de gauche, cliquez sur Clusters of Community-compatible Edition.

4. Localisez le cluster cible et cliquez sur son ID pour accéder à la page Cluster Information.

5. Dans la section Cluster Properties, cliquez sur Major Version Upgrade à côté de Version.

6. Configurez les paramètres suivants comme indiqué, puis cliquez sur OK.

   Paramètre	Description	Exemple
   Upgrade cluster kernel version to	Version cible du cluster. Un retour à la version précédente n'est pas pris en charge après la mise à niveau. Actuellement, seule la version 23.8 est prise en charge.	23.8 (version LTS)
   Time of Stopping Data Writing	Pour garantir la cohérence des données avant et après la mise à niveau, le cluster arrête automatiquement les opérations d'écriture durant les 10 dernières minutes de la mise à niveau. Les règles suivantes s'appliquent à la définition de la période de suspension des écritures : Pour assurer le succès de la mise à niveau, nous vous recommandons de définir la période de suspension des écritures à au moins 30 minutes. La mise à niveau doit se terminer dans un délai de 5 jours. Par conséquent, la date de fin pour le paramètre Time of Stopping Data Writing doit être inférieure ou égale à date actuelle + 5 jours. Pour minimiser l'impact de la suspension des écritures sur votre activité, nous vous recommandons de définir la période de suspension des écritures durant vos heures creuses.	2025-03-20 10:08 - 2025-03-25 10:08
   Perform instance migration validation	Sélectionnez Verification Performed ou Skip instance migration validation (Not Recommended).	Instance migration validation performed

7. Étapes suivantes

   • Si le cluster source contient des tables utilisant les moteurs Kafka ou RabbitMQ, effectuez les étapes 3 à 5 aux moments appropriés durant la mise à niveau. Pour plus de détails, consultez les sections ci-dessous.

   • Pour afficher la progression de la mise à niveau, consultez la section Afficher la progression de la mise à niveau.

   • Si la période de suspension des écritures spécifiée est écoulée mais que l'état du cluster est toujours Upgrading, vous devez modifier la période de suspension des écritures pour terminer la migration.

   • Si la mise à niveau affecte votre activité et que vous souhaitez l'arrêter rapidement, vous pouvez annuler la mise à niveau.

Étape 3 : reconstruire les tables utilisant les moteurs Kafka/RabbitMQ durant la migration des données

Lorsque la tâche de mise à niveau entre dans la phase Data Migration (après la migration des schémas de table), utilisez les instructions DDL précédemment enregistrées pour reconstruire les tables utilisant les moteurs Kafka/RabbitMQ et leurs vues matérialisées en aval. Une fois reconstruites, les données incrémentielles reprennent automatiquement leur flux vers les nœuds du nouveau cluster.

-- Rebuild Kafka/RabbitMQ engine tables
CREATE TABLE <database>.<kafka_or_rabbitmq_table_name> (...)
ENGINE = Kafka/RabbitMQ
SETTINGS ...;

-- Rebuild materialized view (using TO clause pointing to the renamed target table)
CREATE MATERIALIZED VIEW <database>.<materialized_view_name> TO <database>.<new_target_table_name>
AS SELECT ... FROM <database>.<kafka_or_rabbitmq_table_name>;

Étape 4 : supprimer les tables utilisant les moteurs Kafka/RabbitMQ avant la suspension des écritures

Peu avant la fenêtre de suspension des écritures configurée, supprimez les tables utilisant les moteurs Kafka/RabbitMQ et leurs vues matérialisées en aval afin d'arrêter les écritures de données incrémentielles et de garantir la cohérence lors de la synchronisation finale des données.

-- Delete materialized views first
DROP TABLE <database>.<materialized_view_name> ON CLUSTER default;

-- Then delete Kafka/RabbitMQ engine tables
DROP TABLE <database>.<kafka_or_rabbitmq_table_name> ON CLUSTER default;

Étape 5 : reconstruire les tables utilisant les moteurs Kafka/RabbitMQ après la mise à niveau

Une fois la mise à niveau terminée, utilisez les instructions DDL précédemment enregistrées pour reconstruire les tables utilisant les moteurs Kafka/RabbitMQ et leurs vues matérialisées en aval sur le cluster mis à niveau afin de restaurer le pipeline de consommation des données incrémentielles.

-- Rebuild Kafka/RabbitMQ engine tables
CREATE TABLE <database>.<kafka_or_rabbitmq_table_name> (...)
ENGINE = Kafka/RabbitMQ
SETTINGS ...;

-- Rebuild materialized view (using TO clause pointing to the renamed target table)
CREATE MATERIALIZED VIEW <database>.<materialized_view_name> TO <database>.<new_target_table_name>
AS SELECT ... FROM <database>.<kafka_or_rabbitmq_table_name>;

Afficher la progression de la mise à niveau

1. Connectez-vous à la console ApsaraDB for ClickHouse avec votre compte Alibaba Cloud.

2. Dans le coin supérieur gauche de la page, sélectionnez la région où se trouve le cluster cible.

3. Dans le volet de navigation de gauche, cliquez sur Clusters of Community-compatible Edition.

4. Localisez le cluster cible et cliquez sur son ID pour accéder à la page Cluster Information.

5. Dans la section Cluster Status, cliquez sur View Progress à côté de Status.

   La boîte de dialogue Modify Data Write-Stop Time Window s'affiche, permettant de consulter la progression de la mise à niveau. Vous pouvez par exemple voir la progression de la migration des schémas MergeTree, la migration des données, le temps restant estimé pour la migration des données et la progression des autres migrations de schémas.

Modifier la période de suspension des écritures

Si la période de suspension des écritures est écoulée mais que l'état du cluster est toujours Upgrading, la migration des données n'est pas encore terminée. Ajustez la période de suspension des écritures pour garantir la réussite de la mise à niveau.

1. Connectez-vous à la console ApsaraDB for ClickHouse avec votre compte Alibaba Cloud.

2. Dans le coin supérieur gauche de la page, sélectionnez la région où se trouve le cluster cible.

3. Dans le volet de navigation de gauche, cliquez sur Clusters of Community-compatible Edition.

4. Localisez le cluster cible et cliquez sur son ID pour accéder à la page Cluster Information.

5. Dans la section Cluster Status, cliquez sur View Progress à côté de Status.

6. Dans la boîte de dialogue Modify Data Write-Stop Time Window qui s'affiche, modifiez le paramètre Time of Stopping Data Writing et cliquez sur Confirm.

   Remarque

   Les règles de définition du paramètre Time of Stopping Data Writing sont identiques à celles décrites pour le paramètre Time of Stopping Data Writing dans la section Mettre à niveau le cluster.

Annuler la mise à niveau

Vous pouvez annuler la mise à niveau si elle affecte votre activité et que vous devez l'arrêter rapidement.

1. Connectez-vous à la console ApsaraDB for ClickHouse avec votre compte Alibaba Cloud.

2. Dans le coin supérieur gauche de la page, sélectionnez la région où se trouve le cluster cible.

3. Dans le volet de navigation de gauche, cliquez sur Clusters of Community-compatible Edition.

4. Localisez le cluster cible et cliquez sur son ID pour accéder à la page Cluster Information.

5. Dans la section Cluster Status, cliquez sur View Progress à côté de Status.

6. Dans la boîte de dialogue Modify Data Write-Stop Time Window qui s'affiche, cliquez sur Cancel Upgrade.

   Remarque

   Après avoir cliqué sur Cancel Upgrade, la tâche de mise à niveau ne s'arrête pas immédiatement. L'arrêt complet de la tâche intervient après environ 5 minutes.