ApsaraDB for ClickHouse:Migrar ClickHouse autogerenciado para ApsaraDB for ClickHouse Enterprise Edition

Considerações

Etapa 1: Verificar o cluster e ativar tabelas de sistema

Antes de iniciar a migração de dados, configure o arquivo config.xml no seu cluster autogerenciado para habilitar a migração incremental. A configuração depende se as tabelas de sistema system.part_log e system.query_log já estão ativadas.

<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>

Etapa 2: Configurar a compatibilidade do cluster

Para garantir que o cluster de destino seja o mais compatível possível com o cluster autogerenciado, conecte-se ao cluster de destino e modifique o parâmetro compatibility para corresponder à versão do seu cluster autogerenciado.

Por exemplo:

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.

Etapa 3: Criar uma tarefa de migração

1. Faça login no console do ApsaraDB for ClickHouse. Na página Clusters, selecione Enterprise Edition Clusters e clique em ID do cluster de destino.

2. No painel de navegação, escolha Data Migration and Synchronization > Migration from ClickHouse.

3. Clique em Create Migration Task.

4. Selecione as instâncias de origem e de destino.

   Parâmetro	Descrição	Exemplo
   Task Name	Um nome único e sem distinção entre maiúsculas e minúsculas para a tarefa de migração. O nome pode conter apenas letras e dígitos.	MigrationTask1229
   Source Cluster Name	Execute SELECT * FROM system.clusters; para obter o nome do seu cluster autogerenciado.	default
   VPC IP Address	Os endereços IP e portas para cada shard no cluster, separados por vírgulas. Formato: IP:PORT,IP:PORT,.... Use a seguinte instrução SQL para obter os endereços IP e portas do seu cluster autogerenciado: SELECT shard_num, replica_num, host_address as ip, port FROM system.clusters WHERE cluster = '<cluster_name>' and replica_num = 1; Descrição dos parâmetros: cluster_name: O nome do seu cluster autogerenciado. replica_num=1 seleciona o primeiro conjunto de réplicas. Você também pode selecionar outro conjunto de réplicas ou escolher manualmente uma réplica de cada shard. Importante Não é possível usar o nome de domínio da VPC ou o endereço SLB do cluster ClickHouse. Se você usar NAT para mapear endereços IP e portas para a Alibaba Cloud, configure os endereços IP e portas mapeados de acordo com sua configuração de rede.	192.168.0.5:9000,192.168.0.6:9000
   Database Account	A conta de banco de dados para o cluster autogerenciado.	test
   Database Password	A senha da conta de banco de dados do cluster autogerenciado.	test
   Source Instance Kernel Version	Clique em Get Version.	22.8.5.29

5. Com base na versão da instância de origem, proceda da seguinte forma:

   • Se a versão da instância de origem for 22,10 ou posterior: Clique em Next.

   • Se a versão da instância de origem for anterior a 22,10: Insira as Destination Instance Information conforme solicitado e clique em Next.

   • Se a recuperação da versão falhar: Isso pode ocorrer se as informações da instância de origem estiverem incorretas ou se a rede estiver desconectada. Siga a instrução para resolver o problema e clique em Get Version novamente.

   Nota

   Devido a incompatibilidades de parâmetros entre edições comunitárias anteriores e a Enterprise Edition, se a versão da instância de origem for anterior a 22,10, você deve sincronizar os dados enviando-os da origem para o destino. Neste cenário, é necessário mapear o endereço IP da instância de destino para a rede autogerenciada. Se a rede autogerenciada e a instância Enterprise Edition estiverem na mesma VPC, ou se estiverem conectadas através de uma VPC Peering Connection, use os endereços IP originais para a conexão.

6. Verifique a conectividade e as configurações.

   1. Clique em Start Check.

      A verificação valida os seguintes itens:

      • Verificação de conectividade: Confirma que o cluster autogerenciado e a instância de destino possuem conectividade total de rede e que todos os nós podem acessar uns aos outros.

      • Verificação de permissões da conta: Valida se a conta e senha de origem estão corretas e conseguem conectar-se à instância de origem.

      • Verificação das tabelas de sistema da instância de origem: Confirma que a instância autogerenciada possui as tabelas de sistema system.query_log, system.parts e system.part_log.

      • Verificação de configuração: Valida se a instância autogerenciada e a instância de destino usam o mesmo fuso horário e se o parâmetro de compatibilidade da instância de destino corresponde à versão da instância de origem.

   2. Durante a verificação, clique em ícone no canto superior direito para visualizar o progresso em tempo real.

   3. Após a conclusão da verificação, proceda com base nos resultados.

      Selecione um Result level e um item de verificação, e clique em ícone para visualizar os resultados correspondentes. Os níveis de resultado são descritos abaixo.

      • Sucesso: Se todas as verificações forem aprovadas, clique em Next para continuar.

      • Aviso: São itens não bloqueantes. Confirme manualmente se o aviso afeta sua carga de trabalho ou a tarefa de migração. Ignore o aviso ou resolva o problema e clique em Start Check novamente.

      • Erro: São itens bloqueantes. Resolva o erro usando as informações fornecidas e clique em Start Check novamente.

        Para informações sobre mensagens de erro e soluções, consulte FAQ.

7. Verifique as estruturas de banco de dados e tabelas.

   Após a aprovação da verificação de conectividade e configuração, prossiga para verificar as estruturas de banco de dados e tabelas. Esta etapa consiste em três subetapas: Selecionar bancos de dados para migrar, Selecionar tabelas para migrar e Verificar estruturas de banco de dados e tabelas.

   Importante

   As subetapas Selecionar bancos de dados para migrar e Selecionar tabelas para migrar são opcionais. Se desejar migrar todos os bancos de dados e tabelas da instância de origem, pule essas duas subetapas e vá diretamente para a subetapa 3 (Verificar estruturas de banco de dados e tabelas).

   Subetapa 1: Selecionar bancos de dados para migrar (Opcional)

   1. Clique em Query Source. O sistema consulta automaticamente todos os bancos de dados na instância de origem.

   2. Durante a consulta, clique em Query Results para visualizar os resultados em tempo real.

   3. Após a conclusão da consulta, selecione os bancos de dados a serem migrados conforme suas necessidades de negócio. Após concluir a seleção, clique em Confirm.

   Subetapa 2: Selecionar tabelas para migrar (Opcional)

   1. Após selecionar os bancos de dados, a interface para seleção de tabelas será exibida. Clique em Query Source. O sistema consulta automaticamente todas as tabelas nos bancos de dados selecionados.

   2. Durante a consulta, clique em Query Results para visualizar os resultados em tempo real.

   3. Após a conclusão da consulta, selecione as tabelas a serem migradas conforme suas necessidades de negócio. Após concluir a seleção, clique em Confirm.

   Nota

   Por padrão, todas as tabelas são selecionadas. Se precisar migrar apenas tabelas específicas, desmarque a caixa de seleção geral do banco de dados correspondente, expanda a lista suspensa e selecione as tabelas desejadas.

   Subetapa 3: Verificar estruturas de banco de dados e tabelas

   1. Clique em Start Check. O sistema verifica as estruturas de banco de dados, estruturas de tabelas e UDFs para identificar incompatibilidades entre as instâncias de origem e de destino.

   2. Durante a verificação, filtre por Result Level e Check Item, e clique em ícone Refresh para visualizar resultados em tempo real.

   3. Os resultados da verificação são classificados em três níveis: sucesso, aviso e erro.

      • Verificação bem-sucedida: Clique em Next para prosseguir com a migração.

      • Ocorrência de avisos durante a verificação

        Defina o nível de resultado como Warning e localize os itens de verificação correspondentes para revisar os detalhes do aviso.

        Importante

        Itens de verificação de nível de aviso não são bloqueantes. Confirme se o aviso afeta sua carga de trabalho ou a tarefa de migração. Após a confirmação, você tem duas opções:

        • Ignore o aviso e clique em Next para continuar a migração.

        • Resolva o aviso com base nos detalhes fornecidos e clique em Start Check para reverificar as estruturas de banco de dados e tabelas. Para informações sobre mensagens de aviso e soluções, consulte a seção FAQ deste tópico.

      • Falha na verificação

        Defina o nível de resultado como Error e localize os itens de verificação correspondentes para revisar os detalhes do erro.

        Importante

        Itens de verificação de nível de erro são bloqueantes. Resolva os erros com base nos detalhes fornecidos e clique em Start Check para reverificar as estruturas de banco de dados e tabelas. Para informações sobre mensagens de erro e soluções, consulte a seção FAQ deste tópico.

8. Migre as estruturas de banco de dados e tabelas.

   1. Clique em Start Migration.

   2. Durante a migração, clique em ícone no canto superior direito para visualizar o progresso em tempo real.

   3. Após a conclusão da migração, proceda com base nos resultados.

      Para informações sobre os resultados, consulte a Etapa 5.

9. (Opcional) Verifique a compatibilidade de SQL.

   A verificação de compatibilidade de SQL reproduz instruções SQL da sua instância autogerenciada na instância de destino para validar a compatibilidade de sintaxe entre diferentes versões de kernel.

   • Para pular esta etapa, clique em skip.

   • Para realizar esta verificação, selecione um Request replay time e clique em Start Check. Se a verificação for aprovada, clique em Next. Se a verificação falhar, consulte a Etapa 5 para soluções.

     Importante

     • Os bancos de dados e tabelas da instância não contêm dados, portanto, esta verificação valida apenas a compatibilidade de sintaxe. Para testar com dados, migre alguns dados na próxima etapa.

     • Discrepâncias entre a versão do cliente usada para reprodução de SQL e a instância de destino podem causar falsos positivos. Se ocorrerem erros, execute as instruções SQL manualmente para verificar os resultados.

10. Registre e limpe as tabelas de engine Kafka/RabbitMQ.

    Antes de iniciar a sincronização, registre as definições das tabelas de engine Kafka/RabbitMQ e suas materialized views dependentes no cluster autogerenciado, trate as tabelas implícitas e exclua essas tabelas para evitar exceções de migração.

    1. Faça login no cluster autogerenciado e consulte todas as tabelas de engine Kafka e RabbitMQ juntamente com suas dependências downstream.

       /*
       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. Visualize as definições das materialized views e verifique se suas tabelas de destino são tabelas implícitas.

       /*
       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. Se a tabela de destino de uma materialized view for uma tabela implícita, renomeie-a para evitar perda de dados quando a materialized view for excluída posteriormente.

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

    4. Exclua as tabelas de engine Kafka/RabbitMQ e suas materialized views dependentes.

       -- 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>;

    Importante

    Certifique-se de salvar todas as instruções DDL registradas. Você precisará delas para recriar essas tabelas tanto no cluster autogerenciado quanto no cluster de destino posteriormente. Se realizou a operação RENAME, use a cláusula TO para apontar para a tabela de destino renomeada ao recriar as materialized views.

11. Inicie a sincronização.

    1. Clique em Start Sync.

    2. Durante a sincronização, clique em ícone no canto superior direito para visualizar o progresso em tempo real.

       Durante a sincronização, use as operações Stop, Restart e Cancel Migration para controlar o processo de migração. Clique para ver detalhes sobre essas operações.

       Ações	Descrição	Impacto	Caso de uso
       Stop	Interrompe imediatamente a migração de dados e prossegue para migrar as estruturas restantes de banco de dados e tabelas.	Os dados podem não ser totalmente migrados. Antes de reiniciar a migração, limpe os dados migrados do cluster de destino para evitar duplicação de dados.	Parar manualmente a tarefa de migração após todos os dados terem sido migrados. Testar com uma migração parcial de dados sem precisar interromper as gravações no cluster autogerenciado.
       Restart	Se ocorrer um erro durante uma etapa de verificação ou migração, esta operação tenta repetir a etapa falha após a resolução do problema.	Nenhum	Retomar a tarefa do ponto de falha após resolver um erro de migração.
       Cancel Migration	Cancela forçadamente a tarefa e pula todas as etapas subsequentes. Importante Após o cancelamento, a tarefa de migração fica bloqueada, impedindo a modificação do processo de migração. Use os botões Previous, Next ou Refresh para visualizar os resultados das etapas concluídas.	A tarefa de migração é encerrada forçadamente. As estruturas de banco de dados e tabelas e as configurações da instância de destino podem ficar incompletas e não podem ser usadas para cargas de trabalho de produção. Antes de reiniciar a migração, limpe os dados migrados do cluster de destino para evitar duplicação de dados.	A tarefa de migração está afetando negativamente o cluster autogerenciado e você precisa encerrá-la rapidamente para retomar as gravações.

    3. No cluster autogerenciado, use as instruções DDL salvas anteriormente para recriar as tabelas de engine Kafka/RabbitMQ e suas materialized views dependentes. Após a recriação, os dados incrementais voltam a fluir e são sincronizados automaticamente com o cluster de destino.

       Importante

       Se você realizou a operação RENAME na tabela de destino implícita anteriormente, use a cláusula TO para apontar para a tabela de destino renomeada ao recriar as materialized views. Para mais informações, consulte 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. Quando o processo atingir a etapa Migrate data, mude para a aba Migrate data e clique em ícone para visualizar o Migration Progress e o Estimated remaining time.

       Avalie se a migração pode ser concluída

       O sucesso da migração depende da velocidade de migração em relação à velocidade de gravação do cluster autogerenciado.

       • A tabela a seguir fornece dados de teste de velocidade de migração:

         Tamanho médio da partição	Tipo de instância de origem	Tipo de disco de origem	Tipo de instância de destino	Mídia de armazenamento de destino	Nós do cluster	Velocidade por nó	Velocidade geral de migração
         402,54MB	8C32G	PL1	16CCU	OSS	16	47MB/s	752,34MB/s
         402,54MB	80C384G	PL3	48CCU	ESSD_L2	8	197,74MB/s	1581.95MB/s

       • Compare as velocidades de gravação do cluster de destino e do cluster autogerenciado:

         A velocidade de migração de dados depende de fatores como tamanho da partição (em nossos testes, observamos velocidades rápidas de migração para um tamanho médio de partição entre 100 MB e 10 GB), tipo de instância, tipo de disco e características da carga de trabalho. Portanto, os dados de teste servem apenas como referência. Para determinar a velocidade real de gravação do cluster de destino, verifique seu throughput de disco. Para mais informações sobre como visualizar o throughput de disco, consulte View cluster monitoring information.

         • Se a velocidade de gravação do cluster de destino for mais lenta que a do cluster autogerenciado: É provável que a migração falhe. Recomendamos cancelar a tarefa e realizar uma migração manual.

         • Se a velocidade de gravação do cluster de destino for mais rápida que a do cluster autogerenciado: Para melhorar a taxa de sucesso, recomendamos garantir que o tempo de migração, calculado como Volume de Dados / (Velocidade de Migração - Velocidade de Gravação do Cluster Autogerenciado), seja de no máximo 5 dias.

       Importante

       • Monitore atentamente o Migration Progress. Com base no Estimated remaining time, pare proativamente as gravações no cluster autogerenciado e trate as tabelas que usam os engines Kafka e RabbitMQ.

       • O processo em segundo plano cancela automaticamente qualquer tarefa que dure mais de 5 dias. Se sua tarefa de migração exigir mais tempo, abra um ticket para solicitar um ajuste de limiar.

       Estime quando parar as gravações no cluster autogerenciado e realizar o cutover

       Quando o tempo estimado de migração for inferior a 10 minutos ou o progresso da migração atingir 99%, execute as seguintes operações para concluir o cutover:

       1. Pare as gravações de negócio. No cluster autogerenciado, exclua as tabelas de engine Kafka/RabbitMQ recriadas anteriormente e suas materialized views dependentes.

          -- 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. Aguarde até que o progresso da migração atinja 100% e a migração seja totalmente concluída.

       3. Conecte-se ao cluster de destino e use as instruções DDL salvas anteriormente para recriar as tabelas de engine Kafka/RabbitMQ e suas materialized views dependentes.

          Importante

          Se você realizou a operação RENAME na tabela de destino implícita anteriormente, use a cláusula TO para apontar para a tabela de destino renomeada ao recriar as materialized views. Para mais informações, consulte 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. Verifique se o pipeline de dados no cluster de destino está funcionando corretamente e se os dados estão fluindo conforme o esperado.

    5. Quando o Migration Progress atingir 100% e você confirmar que as gravações na instância de origem foram interrompidas, clique em Stop para encerrar a migração de dados e prosseguir para as próximas etapas.

       Clique em aba Migrate Data para visualizar os detalhes da migração. Clique em ícone de atualização no canto superior direito para atualizar o status da migração.

    6. Após a conclusão da sincronização, clique em Completed.

       Importante

       Após a conclusão da etapa Start Synchronization, a tarefa de migração fica bloqueada e você não pode modificar o processo de migração. Ainda é possível usar os botões Previous, Next ou Refresh para visualizar os resultados das etapas concluídas.

Etapa 4: Migrar dados para tabelas não-MergeTree

Durante uma tarefa de migração, tabelas não-MergeTree suportam apenas a migração da estrutura da tabela (por exemplo, tabelas MySQL) ou não suportam migração alguma (por exemplo, tabelas Log). Portanto, após a conclusão da tarefa de migração, o cluster de destino pode conter tabelas com estrutura, mas sem dados de negócio. Migre manualmente os dados de negócio da seguinte forma:

1. Faça login no cluster autogerenciado e identifique as tabelas não-MergeTree que requerem migração de dados.

   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. Faça login no cluster de destino e use a função remote para migrar os dados.