ApsaraDB for ClickHouse:Migrer un cluster ClickHouse autogéré vers ApsaraDB for ClickHouse Enterprise Edition

Considérations

Étape 1 : Vérifier le cluster et activer les tables système

Avant de commencer la migration des données, configurez le fichier config.xml sur votre cluster autogéré pour activer la migration incrémentielle. La configuration dépend du fait que les tables système system.part_log et system.query_log soient déjà activées ou non.

<part_log>
    <database>system</database>
    <table>part_log</table>
    <partition_by>event_date</partition_by>
    <order_by>event_time</order_by>
    <ttl>event_date + INTERVAL 15 DAY DELETE</ttl>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
</part_log>

<query_log>
    <database>system</database>
    <table>query_log</table>
    <partition_by>event_date</partition_by>
    <order_by>event_time</order_by>
    <ttl>event_date + INTERVAL 15 DAY DELETE</ttl>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
</query_log>

Étape 2 : Configurer la compatibilité du cluster

Pour garantir que le cluster cible soit aussi compatible que possible avec le cluster autogéré, connectez-vous au cluster cible et modifiez le paramètre compatibility pour qu'il corresponde à la version de votre cluster autogéré.

Par exemple :

SELECT currentProfiles(); // Get the current profile name.
SELECT
    profile_name,
    setting_name,
    value
FROM system.settings_profile_elements
WHERE (setting_name = 'compatibility') AND (profile_name = 'xxxx'); // Check the value of the compatibility setting.
ALTER PROFILE XXXX SETTINGS compatibility = '23.8'; // Set the compatibility value.

Étape 3 : Créer une tâche de migration

1. Connectez-vous à la console ApsaraDB for ClickHouse. Sur la page Clusters, sélectionnez Enterprise Edition Clusters, puis cliquez sur l'ID du cluster cible.

2. Dans le volet de navigation, choisissez Data Migration and Synchronization > Migration from ClickHouse.

3. Cliquez sur Create Migration Task.

4. Sélectionnez les instances source et cible.

   Paramètre	Description	Exemple
   Task Name	Nom unique (non sensible à la casse) de la tâche de migration. Le nom ne peut contenir que des lettres et des chiffres.	MigrationTask1229
   Source Cluster Name	Exécutez SELECT * FROM system.clusters; pour obtenir le nom de votre cluster autogéré.	default
   VPC IP Address	Les adresses IP et les ports de chaque shard du cluster, séparés par des virgules. Format : IP:PORT,IP:PORT,.... Vous pouvez utiliser l'instruction SQL suivante pour obtenir les adresses IP et les ports de votre cluster autogéré : SELECT shard_num, replica_num, host_address as ip, port FROM system.clusters WHERE cluster = '<cluster_name>' and replica_num = 1; Description des paramètres : cluster_name : le nom de votre cluster autogéré. replica_num=1 sélectionne le premier ensemble de réplicas. Vous pouvez également sélectionner un autre ensemble de réplicas ou choisir manuellement un réplica par shard. Important Vous ne pouvez pas utiliser le nom de domaine VPC ni l'adresse SLB du cluster ClickHouse. Si vous utilisez NAT pour mapper les adresses IP et les ports vers Alibaba Cloud, vous devez configurer les adresses IP et les ports mappés en fonction de votre configuration réseau.	192.168.0.5:9000,192.168.0.6:9000
   Database Account	Le compte de base de données pour le cluster autogéré.	test
   Database Password	Le mot de passe du compte de base de données du cluster autogéré.	test
   Source Instance Kernel Version	Cliquez sur Get Version.	22.8.5.29

5. Selon la version de l'instance source, procédez comme suit :

   • Si la version de l'instance source est 22.10 ou ultérieure : cliquez sur Next.

   • Si la version de l'instance source est antérieure à 22.10 : saisissez les informations demandées dans la section Destination Instance Information, puis cliquez sur Next.

   • En cas d'échec de la récupération de la version : cela peut se produire si les informations de l'instance source sont incorrectes ou si le réseau est déconnecté. Suivez les instructions à l'écran pour résoudre le problème, puis cliquez à nouveau sur Get Version.

   Remarque

   En raison d'incompatibilités de paramètres entre les éditions communautaires précédentes et l'édition Enterprise, si la version de l'instance source est antérieure à 22.10, vous devez synchroniser les données en les poussant de la source vers la cible. Dans ce scénario, vous devez mapper l'adresse IP de l'instance cible sur le réseau autogéré. Si le réseau autogéré et l'instance Enterprise Edition se trouvent dans le même VPC, ou s'ils sont connectés via une connexion d'appairage VPC (VPC Peering Connection), vous pouvez utiliser les adresses IP d'origine pour la connexion.

6. Vérifiez la connectivité et les configurations.

   1. Cliquez sur Start Check.

      La vérification porte sur les éléments suivants :

      • Vérification de la connectivité : confirme que le cluster autogéré et l'instance cible disposent d'une connectivité réseau complète et que tous les nœuds peuvent communiquer entre eux.

      • Vérification des autorisations du compte : confirme que le compte source et le mot de passe sont corrects et permettent de se connecter à l'instance source.

      • Vérification des tables système de l'instance source : confirme que l'instance autogérée dispose des tables système system.query_log, system.parts et system.part_log.

      • Vérification de la configuration : confirme que l'instance autogérée et l'instance cible utilisent le même fuseau horaire, et que le paramètre de compatibilité de l'instance cible correspond à la version de l'instance source.

   2. Pendant la vérification, vous pouvez cliquer sur l'icône située dans le coin supérieur droit pour afficher la progression en temps réel.

   3. Une fois la vérification terminée, agissez en fonction des résultats.

      Vous pouvez sélectionner un Result level et un élément de vérification, puis cliquer sur l'icône pour afficher les résultats correspondants. Les niveaux de résultat sont décrits ci-dessous.

      • Success : si toutes les vérifications réussissent, cliquez sur Next pour continuer.

      • Warning : ces éléments ne bloquent pas le processus. Vous devez confirmer manuellement si l'avertissement affecte votre charge de travail ou la tâche de migration. Vous pouvez ignorer l'avertissement ou résoudre le problème, puis cliquer à nouveau sur Start Check.

      • Error : ces éléments bloquent le processus. Vous devez résoudre l'erreur à l'aide des informations fournies, puis cliquer à nouveau sur Start Check.

        Pour plus d'informations sur les messages d'erreur et les solutions, consultez la section FAQ.

7. Vérifiez les structures des bases de données et des tables.

   Une fois la vérification de la connectivité et de la configuration réussie, procédez à la vérification des structures des bases de données et des tables. Cette étape comprend trois sous-étapes : Select databases to migrate, Select tables to migrate et Check database and table structures.

   Important

   Les sous-étapes Select databases to migrate et Select tables to migrate sont facultatives. Si vous souhaitez migrer toutes les bases de données et tables de l'instance source, vous pouvez ignorer ces deux sous-étapes et passer directement à la sous-étape 3 (Check database and table structures).

   Sous-étape 1 : Sélectionner les bases de données à migrer (facultatif)

   1. Cliquez sur Query Source. Le système interroge automatiquement toutes les bases de données de l'instance source.

   2. Pendant l'interrogation, vous pouvez cliquer sur Query Results pour afficher les résultats en temps réel.

   3. Une fois l'interrogation terminée, sélectionnez les bases de données à migrer selon vos besoins métier. Une fois la sélection effectuée, cliquez sur Confirm.

   Sous-étape 2 : Sélectionner les tables à migrer (facultatif)

   1. Après avoir sélectionné les bases de données, l'interface de sélection des tables s'affiche. Cliquez sur Query Source. Le système interroge automatiquement toutes les tables des bases de données sélectionnées.

   2. Pendant l'interrogation, vous pouvez cliquer sur Query Results pour afficher les résultats en temps réel.

   3. Une fois l'interrogation terminée, sélectionnez les tables à migrer selon vos besoins métier. Une fois la sélection effectuée, cliquez sur Confirm.

   Remarque

   Par défaut, toutes les tables sont sélectionnées. Si vous ne devez migrer que certaines tables, décochez la case de sélection globale de la base de données correspondante, développez la liste déroulante et sélectionnez les tables souhaitées.

   Sous-étape 3 : Vérifier les structures des bases de données et des tables

   1. Cliquez sur Start Check. Le système vérifie les structures des bases de données, les structures des tables et les UDF afin d'identifier toute incompatibilité entre les instances source et cible.

   2. Pendant la vérification, vous pouvez filtrer par Result Level et Check Item, et cliquer sur l'icône Refresh pour afficher les résultats en temps réel.

   3. Les résultats de la vérification sont classés en trois niveaux : succès, avertissement et erreur.

      • La vérification réussit : cliquez sur Next pour poursuivre la migration.

      • Des avertissements surviennent pendant la vérification

        Définissez le niveau de résultat sur Warning et recherchez les éléments de vérification correspondants pour consulter les détails de l'avertissement.

        Important

        Les éléments de vérification de niveau Warning ne sont pas bloquants. Vous devez confirmer si l'avertissement affecte votre charge de travail ou la tâche de migration. Après confirmation, vous avez deux options :

        • Ignorer l'avertissement et cliquer sur Next pour continuer la migration.

        • Résoudre l'avertissement en suivant les détails fournis, puis cliquer sur Start Check pour revérifier les structures des bases de données et des tables. Pour plus d'informations sur les messages d'avertissement et les solutions, consultez la section FAQ de cette rubrique.

      • Échec de la vérification

        Définissez le niveau de résultat sur Error et recherchez les éléments de vérification correspondants pour consulter les détails de l'erreur.

        Important

        Les éléments de vérification de niveau Error sont bloquants. Vous devez résoudre les erreurs en suivant les détails fournis, puis cliquer sur Start Check pour revérifier les structures des bases de données et des tables. Pour plus d'informations sur les messages d'erreur et les solutions, consultez la section FAQ de cette rubrique.

8. Migrer les structures des bases de données et des tables.

   1. Cliquez sur Start Migration.

   2. Pendant la migration, vous pouvez cliquer sur l'icône située dans le coin supérieur droit pour afficher la progression en temps réel.

   3. Une fois la migration terminée, agissez en fonction des résultats.

      Pour plus d'informations sur les résultats, consultez l'étape 5.

9. (Facultatif) Vérifier la compatibilité SQL.

   La vérification de la compatibilité SQL rejoue les instructions SQL de votre instance autogérée sur l'instance cible afin de vérifier la compatibilité syntaxique entre les différentes versions du noyau.

   • Pour ignorer cette étape, cliquez sur skip.

   • Pour effectuer cette vérification, sélectionnez une Request replay time et cliquez sur Start Check. Si la vérification réussit, cliquez sur Next. En cas d'échec, consultez l'étape 5 pour connaître les solutions.

     Important

     • Les bases de données et les tables de l'instance ne contiennent aucune donnée ; cette vérification valide uniquement la compatibilité syntaxique. Pour tester avec des données, vous pouvez migrer une partie des données à l'étape suivante.

     • Des différences entre la version du client utilisée pour la relecture SQL et l'instance cible peuvent générer des faux positifs. En cas d'erreurs, exécutez manuellement les instructions SQL pour vérifier les résultats.

10. Enregistrer et nettoyer les tables utilisant les moteurs Kafka/RabbitMQ.

    Avant de démarrer la synchronisation, enregistrez les définitions des tables utilisant les moteurs Kafka/RabbitMQ ainsi que leurs vues matérialisées en aval sur le cluster autogéré, traitez les tables implicites, puis supprimez ces tables pour éviter les exceptions lors de la migration.

    1. Connectez-vous au cluster autogéré et interrogez toutes les tables utilisant les moteurs Kafka et RabbitMQ, ainsi que leurs dépendances en aval.

       /*
       create_table_query: table definition
       dependencies_database: database of the downstream dependent table
       dependencies_table: name of the downstream dependent table
       From dependencies_database and dependencies_table, you can identify the materialized views that depend on the Kafka/RabbitMQ tables.
       */
       SELECT * FROM system.tables WHERE engine IN ('RabbitMQ', 'Kafka');

    2. Consultez les définitions des vues matérialisées et vérifiez si leurs tables cibles sont des tables implicites.

       /*
       View the materialized view definition.
       If the target table of a materialized view is an implicit table, note the following:
       Dropping the materialized view also drops the implicit table, which causes data loss.
       Example: In CREATE MATERIALIZED VIEW [db.]table_name [TO[db.]name], if TO is not specified,
       the system automatically creates an implicit table, which may be in the format '.inner_id.<TABLE_UUID>' or '.inner.<TABLE>'.
       */
       SELECT * FROM system.tables WHERE database='<DATABASE>' AND name = '<MATERIALIZED_VIEW_NAME>';

    3. Si la table cible d'une vue matérialisée est une table implicite, renommez-la pour éviter la perte de données lors de la suppression ultérieure de la vue matérialisée.

       -- Rename the implicit target table to preserve data
       RENAME TABLE <DATABASE>.`.inner_id.<TABLE_UUID>` TO <DATABASE>.<new_target_table_name>;

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

       -- Drop the materialized views first
       DROP TABLE <DATABASE>.<MATERIALIZED_VIEW_NAME>;
       -- Then drop the Kafka/RabbitMQ engine tables
       DROP TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

    Important

    Assurez-vous de sauvegarder toutes les instructions DDL enregistrées. Vous en aurez besoin pour recréer ces tables à la fois sur le cluster autogéré et sur le cluster cible ultérieurement. Si vous avez effectué l'opération RENAME, utilisez la clause TO pour pointer vers la table cible renommée lors de la recréation des vues matérialisées.

11. Démarrer la synchronisation.

    1. Cliquez sur Start Sync.

    2. Pendant la synchronisation, vous pouvez cliquer sur l'icône située dans le coin supérieur droit pour afficher la progression en temps réel.

       Pendant la synchronisation, utilisez les opérations Stop, Restart et Cancel Migration pour contrôler le processus de migration. Cliquez pour afficher les détails de ces opérations.

       Actions	Description	Impact	Cas d'utilisation
       Arrêter	Interrompt immédiatement la migration des données et passe à la migration des structures de base de données et de tables restantes.	Les données peuvent ne pas être entièrement migrées. Avant de redémarrer la migration, vous devez effacer les données migrées du cluster cible pour éviter toute duplication des données.	Arrêt manuel de la tâche de migration une fois toutes les données migrées. Test avec une migration partielle des données sans avoir à interrompre les écritures sur le cluster auto-géré.
       Redémarrer	Si une erreur survient lors d'une étape de vérification ou de migration, cette opération retente l'étape échouée après résolution du problème.	Aucun	Reprendre la tâche à partir du point d'échec après la résolution d'une erreur de migration.
       Annuler la migration	Annule la tâche de force et ignore toutes les étapes suivantes. Important Après l'annulation, la tâche de migration est verrouillée, ce qui empêche toute modification du processus de migration. Vous pouvez utiliser les boutons Previous, Next ou Refresh pour consulter les résultats des étapes terminées.	La tâche de migration est arrêtée de force. Les structures de base de données et de tables ainsi que les configurations de l'instance cible peuvent être incomplètes et inutilisables pour les charges de travail de production. Avant de redémarrer la migration, vous devez effacer les données migrées du cluster cible pour éviter toute duplication des données.	La tâche de migration affecte négativement le cluster auto-géré et vous devez y mettre fin rapidement pour reprendre les écritures.

    3. Sur le cluster auto-géré, utilisez les instructions DDL précédemment enregistrées pour recréer les tables du moteur Kafka/RabbitMQ et leurs vues matérialisées en aval. Après la recréation, les données incrémentales recommencent à circuler et sont automatiquement synchronisées vers le cluster cible.

       Important

       Si vous avez effectué l'opération RENAME sur la table cible implicite plus tôt, utilisez la clause TO pour pointer vers la table cible renommée lors de la recréation des vues matérialisées. Pour plus d'informations, consultez CREATE MATERIALIZED VIEW.

       CREATE MATERIALIZED VIEW [db.]table_name [TO[db.]name]

       .

       -- Recreate the Kafka/RabbitMQ engine table on the self-managed cluster
       CREATE TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME> (...)
       ENGINE = Kafka/RabbitMQ
       SETTINGS ...;
       
       -- Recreate the materialized view (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>;

    4. Lorsque le processus atteint l'étape Migrate data, basculez vers l'onglet Migrate data et cliquez sur l'icône pour afficher la Migration Progress et le Estimated remaining time.

       Évaluer si la migration peut être achevée

       Le succès de la migration dépend de la vitesse de migration par rapport à la vitesse d'écriture du cluster auto-géré.

       • Le tableau suivant fournit des données de test de vitesse de migration :

         Taille moyenne des partitions	Type d'instance source	Type de disque source	Type d'instance cible	Support de stockage cible	Nœuds du cluster	Vitesse par nœud	Vitesse globale de migration
         402,54 Mo	8C32G	PL1	16CCU	OSS	16	47 Mo/s	752,34 Mo/s
         402,54 Mo	80C384G	PL3	48CCU	ESSD_L2	8	197,74 Mo/s	1581,95 Mo/s

       • Comparez les vitesses d'écriture du cluster cible et du cluster auto-géré :

         La vitesse de migration des données dépend de facteurs tels que la taille des partitions (dans nos tests, nous avons observé des vitesses de migration rapides pour une taille moyenne de partition comprise entre 100 Mo et 10 Go), le type d'instance, le type de disque et les caractéristiques de la charge de travail. Par conséquent, les données de test sont fournies à titre indicatif uniquement. Pour déterminer la vitesse d'écriture réelle du cluster cible, vérifiez son débit disque. Pour plus d'informations sur la consultation du débit disque, consultez Afficher les informations de surveillance du cluster.

         • Si la vitesse d'écriture du cluster cible est inférieure à celle du cluster auto-géré : la migration est susceptible d'échouer. Nous vous recommandons d'annuler la tâche et d'effectuer une migration manuelle.

         • Si la vitesse d'écriture du cluster cible est supérieure à celle du cluster auto-géré : pour améliorer le taux de réussite, nous vous recommandons de veiller à ce que le temps de migration, calculé comme Volume de données / (Vitesse de migration - Vitesse d'écriture du cluster auto-géré), ne dépasse pas 5 jours.

       Important

       • Vous devez surveiller attentivement la Migration Progress. En fonction du Estimated remaining time, vous devez proactivement interrompre les écritures sur le cluster auto-géré et gérer les tables utilisant les moteurs Kafka et RabbitMQ.

       • Le processus en arrière-plan annule automatiquement toute tâche s'exécutant pendant plus de 5 jours. Si votre tâche de migration nécessite plus de temps, soumettez un ticket pour demander un ajustement du seuil.

       Estimer quand interrompre les écritures sur le cluster auto-géré et effectuer le basculement

       Lorsque le temps de migration estimé est inférieur à 10 minutes ou que la progression de la migration atteint 99 %, effectuez les opérations suivantes pour finaliser le basculement :

       1. Interrompez les écritures métier. Sur le cluster auto-géré, supprimez les tables du moteur Kafka/RabbitMQ précédemment recréées et leurs vues matérialisées en aval.

          -- Drop the materialized views first
          DROP TABLE <DATABASE>.<MATERIALIZED_VIEW_NAME>;
          -- Then drop the Kafka/RabbitMQ engine tables
          DROP TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

       2. Attendez que la progression de la migration atteigne 100 % et que la migration soit totalement terminée.

       3. Connectez-vous au cluster cible et utilisez les instructions DDL précédemment enregistrées pour recréer les tables du moteur Kafka/RabbitMQ et leurs vues matérialisées en aval.

          Important

          Si vous avez effectué l'opération RENAME sur la table cible implicite plus tôt, utilisez la clause TO pour pointer vers la table cible renommée lors de la recréation des vues matérialisées. Pour plus d'informations, consultez CREATE MATERIALIZED VIEW.

          -- Recreate the Kafka/RabbitMQ engine table on the target cluster
          CREATE TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME> (...)
          ENGINE = Kafka/RabbitMQ
          SETTINGS ...;
          
          -- Recreate the materialized view (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>;

       4. Vérifiez que le pipeline de données sur le cluster cible fonctionne correctement et que les données circulent comme prévu.

    5. Lorsque la Migration Progress atteint 100 % et que vous confirmez l'arrêt des écritures sur l'instance source, cliquez sur Stop pour mettre fin à la migration des données et passer aux étapes suivantes.

       Cliquez sur l'onglet Migrate Data pour afficher les détails de la migration. Cliquez sur l'icône d'actualisation dans le coin supérieur droit pour mettre à jour l'état de la migration.

    6. Une fois la synchronisation terminée, cliquez sur Completed.

       Important

       Une fois l'étape Start Synchronization terminée, la tâche de migration est verrouillée et vous ne pouvez pas modifier le processus de migration. Vous pouvez toujours utiliser les boutons Previous, Next ou Refresh pour consulter les résultats des étapes terminées.

Étape 4 : Migrer les données des tables non-MergeTree

Lors d'une tâche de migration, les tables non-MergeTree ne prennent en charge que la migration de la structure (par exemple, les tables MySQL) ou ne permettent aucune migration (par exemple, les tables Log). Par conséquent, une fois la tâche de migration terminée, le cluster cible peut contenir des tables dont la structure existe mais sans les données métier. Vous devez migrer manuellement les données métier comme suit :

1. Connectez-vous au self-built cluster et identifiez les tables non-MergeTree nécessitant une migration des données.

   SELECT
       `database` AS database_name,
       `name` AS table_name,
       `engine`
   FROM `system`.`tables`
   WHERE (`engine` NOT LIKE '%MergeTree%') AND (`engine` != 'Distributed') AND (`engine` != 'MaterializedView') AND (`engine` NOT IN ('Kafka', 'RabbitMQ')) AND (`database` NOT IN ('system', 'INFORMATION_SCHEMA', 'information_schema')) AND (`database` NOT IN (
       SELECT `name`
       FROM `system`.`databases`
       WHERE `engine` IN ('MySQL', 'MaterializedMySQL', 'MaterializeMySQL', 'Lazy', 'PostgreSQL', 'MaterializedPostgreSQL', 'SQLite')
   ))

2. Connectez-vous au target cluster et utilisez la remote function pour migrer les données.