Todos os produtos
Search

Este produto

    ApsaraDB for ClickHouse:Migrate from self-managed to Cloud ClickHouse

    Central de documentação

    ApsaraDB for ClickHouse:Migrate from self-managed to Cloud ClickHouse

    Última atualização: Oct 10, 2026

    Clusters de ClickHouse auto-gerenciados frequentemente apresentam instabilidade, baixa escalabilidade, dificuldades de atualização e recuperação de desastres ineficiente. Por isso, cada vez mais clientes estão migrando seus clusters de ClickHouse auto-gerenciados para um service PaaS na nuvem. Este tópico descreve como migrar de um cluster de ClickHouse auto-gerenciado para um cluster da edição compatível com a comunidade do ApsaraDB for ClickHouse.

    Pré-requisitos

    • Cluster de destino:

      • O cluster deve ser da edição compatível com a comunidade (Community-Compatible Edition).

      • É necessária uma conta e senha de banco de dados. Para criar uma conta do ClickHouse, consulte {{XREF_0}}.

      • A conta deve ter o nível mais alto de permissões. Para conceder permissões, consulte {{XREF_1}}.

    • Cluster auto-gerenciado:

      • É necessária uma conta e senha de banco de dados.

      • A conta deve ter permissões de leitura em bancos de dados e tabelas, além de permissões para executar comandos SYSTEM.

    • O cluster de destino e o cluster auto-gerenciado devem conseguir se comunicar pela rede.

      Se o cluster auto-gerenciado e o cluster de destino estiverem na mesma VPC, você também deve adicionar os endereços IP de todos os nós no cluster de destino e o bloco CIDR IPv4 do seu vSwitch à lista de permissões do cluster auto-gerenciado.

      • Para configurar uma lista de permissões para um cluster do ApsaraDB for ClickHouse, consulte {{XREF_2}}.

      • Para configurar uma lista de permissões em um cluster auto-gerenciado, consulte a documentação relevante do product.

      • Para visualizar os endereços IP de todos os nós no cluster do ApsaraDB for ClickHouse, execute SELECT * FROM system.clusters;.

      • Para obter o bloco CIDR IPv4 do vSwitch do seu cluster do ApsaraDB for ClickHouse, siga estas etapas:

        1. No console do ApsaraDB for ClickHouse, acesse a página Cluster Information do cluster de destino. Na seção Network Information, obtenha o VSwitch ID.

        2. Na lista de vSwitches, use o Instance ID para encontrar o vSwitch de destino e obtenha seu IPv4 CIDR.

      Se o seu cluster auto-gerenciado e o cluster de destino estiverem em VPCs diferentes, ou se o cluster auto-gerenciado estiver em um data center local ou em outra plataforma de cloud, você deve primeiro estabelecer a conectividade de rede. Para mais informações, consulte {{XREF_3}}.

    Validação da migração

    Antes de iniciar a migração de dados, recomendamos fortemente a criação de um ambiente de teste para validar a compatibilidade do negócio, o desempenho e o plano de migração. Após concluir a validação, você pode realizar a migração de dados no seu ambiente de produção. Essa etapa crucial ajuda a identificar e resolver possíveis problemas com antecedência, garantindo uma migração tranquila e evitando interrupções no seu ambiente de produção.

    1. Crie uma tarefa de migração para migrar os dados. Para obter as etapas detalhadas, consulte este tópico.

    2. Para obter informações sobre compatibilidade de migração para a nuvem, análise de gargalos de desempenho e como garantir o sucesso da migração, consulte {{XREF_4}}.

    Escolha uma solução

    Solução de migração

    Vantagens

    Desvantagens

    Casos de uso

    {{XREF_5}}

    Fornece uma interface visual. Não é necessário migrar os metadados manualmente.

    Suporta apenas migração completa e incremental de todo o cluster. Não é possível migrar bancos de dados, tabelas ou dados históricos específicos.

    Migração de um cluster inteiro.

    {{XREF_6}}

    Permite controlar quais bancos de dados e tabelas migrar.

    Envolve etapas complexas e migração manual de metadados.

    • Migração de bancos de dados e tabelas específicos.

    • Os dados frios excedem 1 TB.

    • Os dados quentes excedem 10 TB.

    • Migração de um cluster inteiro que não atende às condições para migração pelo console.

    Procedimento

    Migração pelo console

    Limites

    O cluster de destino deve estar executando a versão 21.8 ou posterior.

    Observações

    Durante a migração

    • Durante a migração, o processo de merge é pausado no cluster de destino, mas continua no cluster auto-gerenciado.

      Nota

      Se uma tarefa de migração for executada por muito tempo, pode haver acúmulo excessivo de metadados no cluster de destino. Recomendamos que as tarefas de migração não excedam 5 dias de duração. Tarefas que excedem 5 dias são canceladas automaticamente.

    • O cluster de destino deve ser o cluster default. Se o seu cluster auto-gerenciado usar um nome diferente, o service converte automaticamente a definição de cluster nas tabelas distribuídas para default.

    Escopo da migração

    • Objetos suportados

      • Bancos de dados, dicionários de dados e visualizações materializadas (materialized views).

        • Este service suporta a migração de dicionários de dados criados com SQL, mas não suporta aqueles criados com XML.

          Para verificar isso, execute a seguinte instrução: SELECT * FROM system.dictionaries WHERE (database = '') OR isNull(database);. Se a instrução retornar alguma linha, isso indica que você possui dicionários de dados criados usando XML.

        • Quando um dicionário de dados acessa um service externo, certifique-se de que o service externo esteja disponível e de que o cluster esteja adicionado à sua lista de permissões. Se a fonte de dados de um dicionário de dados for uma tabela interna no cluster ClickHouse atual e o parâmetro HOST na definição for um endereço IP, o acesso ao dicionário poderá falhar após a migração devido a uma alteração no endereço IP. Você deve reconfirmar o HOST do cluster ClickHouse atual e criar o dicionário de dados manualmente.

      • Esquemas de tabelas: Todos os esquemas de tabelas, exceto as tabelas com engines Kafka e RabbitMQ.

      • Dados: Migração incremental de dados de tabelas da família MergeTree.

    • Objetos e dados não suportados

      • Tabelas com engines Kafka e RabbitMQ, e seus respectivos dados.

      • Dados de tabelas não-MergeTree, como tabelas externas e tabelas Log.

      Importante

      Você deve migrar manualmente os itens não suportados listados acima.

    • Limites de volume de dados

      • Dados frios: A migração de dados frios é lenta. Para evitar falhas causadas por longos tempos de migração, recomendamos limpar os dados frios do seu cluster auto-gerenciado para garantir que o volume total não exceda 1 TB.

      • Dados quentes: Se o volume de dados quentes exceder 10 TB, é provável que a tarefa de migração falhe.

      Se o seu volume de dados exceder esses limites, considere usar a solução {{XREF_7}}.

    Impacto no cluster

    • Cluster auto-gerenciado:

      • A leitura de dados do cluster auto-gerenciado aumenta o uso de CPU e memória.

      • Operações DDL não são permitidas.

    • Cluster de destino:

      • A gravação de dados no cluster de destino aumenta o uso de CPU e memória.

      • Operações DDL não são permitidas nos bancos de dados e tabelas que estão sendo migrados.

      • Essa restrição não se aplica a outros bancos de dados e tabelas.

      • O processo de merge é interrompido apenas para os bancos de dados e tabelas que estão sendo migrados.

      • O cluster é reiniciado antes do início da tarefa de migração.

      • Após a conclusão da migração, o cluster realiza operações frequentes de merge. Isso aumenta o uso de I/O e pode levar a uma maior latência nas requisições do negócio. Planeje-se para o possível impacto desse aumento de latência. Você deve calcular a duração específica das operações de merge. Para obter instruções, consulte {{XREF_8}}.

    Procedimento

    Etapa 1: Verificar o cluster e ativar as tabelas do sistema

    Antes de migrar os dados, modifique o arquivo config.xml no seu cluster auto-gerenciado para ativar a migração incremental. As modificações necessárias dependem de as tabelas system.part_log e system.query_log estarem ativadas.

    Se as tabelas do sistema não estiverem ativadas

    Se você não ativou as tabelas system.part_log e system.query_log, adicione as seguintes configurações ao arquivo config.xml.

    system.part_log

    EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    system.query_log

    EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    Se as tabelas do sistema estiverem ativadas

    1. Certifique-se de que as configurações de system.part_log e system.query_log no arquivo config.xml correspondam ao seguinte conteúdo. Inconsistências podem fazer com que a migração de dados falhe ou ocorra lentamente.

      system.part_log

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

      system.query_log

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    2. Após modificar a configuração, execute as instruções drop table system.part_log e drop table system.query_log. A inserção de dados em uma tabela de negócio recria automaticamente as tabelas system.part_log e system.query_log.

    Etapa 2: Configurar a compatibilidade do cluster de destino

    Configure o cluster de destino para ser compatível com o cluster auto-gerenciado. Esta etapa minimiza as alterações necessárias na aplicação após a migração.

    1. Obtenha e compare os números de versão do cluster de destino e do cluster auto-gerenciado.

      Faça login no cluster de destino e no cluster auto-gerenciado e execute a seguinte instrução em cada um para obter seus números de versão. Para mais informações sobre como fazer login no ApsaraDB for ClickHouse, consulte {{XREF_9}}.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    2. Se as versões forem diferentes, faça login no cluster de destino e defina o parâmetro de compatibilidade para corresponder à versão do cluster auto-gerenciado. Isso garante que seus recursos sejam o mais consistentes possível. Veja um exemplo abaixo:

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    Etapa 3: (Opcional) Ativar a engine MaterializedMySQL

    Se o seu cluster auto-gerenciado contiver tabelas que usam a engine MaterializedMySQL, execute a seguinte instrução para ativar essa engine.

    EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;
    Nota

    A comunidade ClickHouse não mantém mais a engine MaterializedMySQL. Após migrar para a nuvem, recomendamos usar o Data Transmission Service (DTS) para sincronizar dados do MySQL.

    Como a engine MaterializedMySQL não é mais mantida, o Data Transmission Service (DTS) usa tabelas ReplacingMergeTree em vez de tabelas MaterializedMySQL ao sincronizar dados do MySQL para o ApsaraDB for ClickHouse. Para mais informações, consulte {{XREF_10}}.

    Para mais informações sobre como usar o DTS para migrar dados do MySQL para o ApsaraDB for ClickHouse, consulte os seguintes tópicos:

    • {{XREF_11}}

    • {{XREF_12}}

    Etapa 4: Registrar e limpar tabelas com engines Kafka/RabbitMQ

    Antes de iniciar a migração, registre as definições de todas as tabelas com engines Kafka/RabbitMQ e suas visualizações materializadas (materialized views) subsequentes no cluster auto-gerenciado, trate as tabelas implícitas e, em seguida, exclua essas tabelas para evitar erros de migração.

    1. Faça login no cluster auto-gerenciado e consulte todas as tabelas com engines Kafka e RabbitMQ, juntamente com suas dependências subsequentes.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    2. Visualize a definição da visualização materializada para verificar se sua tabela de destino é uma tabela implícita.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    3. Se a tabela de destino de uma visualização materializada for uma tabela implícita, use RENAME para alterar o nome da tabela de destino para um novo nome, a fim de evitar perda de dados quando a visualização materializada for excluída posteriormente.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    4. Exclua as tabelas com engines Kafka/RabbitMQ e suas visualizações materializadas subsequentes.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;
    Importante

    Certifique-se de salvar todas as instruções DDL registradas. Você precisará delas para recriar essas tabelas tanto no cluster auto-gerenciado quanto no cluster de destino posteriormente. Se você realizou uma operação RENAME, use a cláusula TO apontando para a tabela de destino renomeada ao recriar a visualização materializada. Para mais informações, consulte CREATE MATERIALIZED VIEW.

    Etapa 5: Criar uma tarefa de migração de dados

    1. Faça login no console do ApsaraDB for ClickHouse.

    2. Na página Clusters, selecione Clusters of Community-compatible Edition e clique no ID do cluster de destino.

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

    4. Na página de tarefas de migração, clique em Create Migration Task.

      1. Configure as instâncias de origem e de destino.

        Defina as seguintes configurações e clique em Test Connectivity and Proceed.

        Nota

        Se o teste de conexão for bem-sucedido, prossiga para a próxima etapa. Se o teste de conexão falhar, reconfigure as instâncias de origem e de destino com base nas mensagens exibidas.

        Parâmetros do cluster de origem

        Parâmetro

        Descrição

        Exemplo

        Source Access Method

        Selecione Express Connect, VPN Gateway, Smart Access Gateway, or Self-managed ClickHouse Clusters on an ECS Instance.

        Express Connect, VPN Gateway, Smart Access Gateway, or Self-managed ClickHouse Clusters on an ECS Instance

        Cluster Name

        O nome do cluster de origem.

        O nome pode conter apenas dígitos e letras minúsculas.

        source

        Source Cluster Name

        Execute SELECT * FROM system.clusters; para obter o Source Cluster Name.

        default

        VPC IP Address

        O endereço IP e a PORTA (endereço TCP) de cada shard no cluster, separados por vírgulas.

        Importante

        Você não pode usar o nome de domínio da VPC ou o endereço SLB de um cluster do ApsaraDB for ClickHouse.

        Formato: IP:PORT,IP:PORT,......

        O método para obter o endereço IP e a PORTA do cluster varia dependendo do cenário de migração de dados.

        Migração entre contas ou entre regiões

        Você pode usar a seguinte instrução SQL para obter o endereço IP e a PORTA do cluster auto-gerenciado:

        SELECT shard_num, replica_num, host_address as ip, port FROM system.clusters WHERE cluster = 'default' and replica_num = 1;

        Aqui, replica_num=1 seleciona o primeiro conjunto de réplicas. Você também pode escolher outros conjuntos de réplicas ou selecionar uma réplica de cada shard.

        Migração de ClickHouse fora da Alibaba Cloud

        Se o endereço IP não puder ser mapeado facilmente para a Alibaba Cloud, você pode usar a seguinte instrução SQL para obter o endereço IP e a PORTA do cluster auto-gerenciado:

        SELECT shard_num, replica_num, host_address as ip, port FROM system.clusters WHERE cluster = '<cluster_name>' and replica_num = 1;

        Os parâmetros são descritos da seguinte forma:

        • cluster_name: o nome do cluster de destino.

        • replica_num=1 seleciona o primeiro conjunto de réplicas. Você também pode escolher outros conjuntos de réplicas ou selecionar uma réplica de cada shard.

        Se o endereço IP e a porta forem mapeados para a Alibaba Cloud por meio de tradução de rede, você deve configurar o endereço IP e a porta mapeados correspondentes.

        192.168.0.5:9000,192.168.0.6:9000

        Database Account

        A conta do banco de dados do cluster de origem.

        test

        Database Password

        A senha da conta do banco de dados do cluster de origem.

        test

        Parâmetros do cluster de destino

        Parâmetro

        Descrição

        Exemplo

        Database Account

        A conta do banco de dados do cluster de destino.

        test

        Database Password

        A senha da conta do banco de dados do cluster de destino.

        test

      2. Confirme o conteúdo da migração.

        Revise cuidadosamente as informações sobre os dados a serem migrados na página e, em seguida, clique em Next: Pre-detect and Start Synchronization.

      3. O sistema executa uma pré-verificação no link de migração em segundo plano e inicia a tarefa.

        O sistema executa uma Instance Status Detection, uma Storage Space Detection e uma Local Table and Distributed Table Detection nos clusters de origem e de destino.

        • Se a pré-verificação for bem-sucedida:

          Após o sucesso da pré-verificação, a página mostra que três verificações foram aprovadas: Instance status check, Storage space check e Local table and distributed table check. A parte superior da página mostra que o tempo estimado de migração é de 2 minutos e descreve os impactos durante a migração:

          • A instância de origem permite leitura e gravação, mas operações DDL não podem ser realizadas.

          • A instância de destino permite leitura, mas não é possível gravar nas tabelas migradas.

          • Quando o tempo restante for inferior a 10 minutos, você deve interromper as gravações para acionar o fim da migração.

          • As tabelas não-MergeTree mantêm apenas a estrutura da tabela, sem migração de dados após o dimensionamento.

          1. Revise cuidadosamente como o processo de migração de dados afeta as instâncias.

          2. Clique em Completed.

            Importante

            • Após clicar em Complete, o sistema cria e inicia a tarefa, e seu status muda para Running. Você pode visualizar a tarefa na lista de tarefas.

            • Após criar a tarefa, você deve monitorá-la. Na etapa final da migração, você deve interromper as operações de gravação no cluster auto-gerenciado e migrar os esquemas restantes de bancos de dados e tabelas. Para mais informações, consulte {{XREF_13}}.

        • Se a pré-verificação falhar: Siga as instruções na mensagem de erro e execute a tarefa de migração de dados novamente. A tabela a seguir descreve os itens de pré-verificação e seus requisitos. Para mais informações sobre mensagens de erro de pré-verificação e suas soluções, consulte {{XREF_14}}.

          Item de verificação

          Requisito

          Instance Status Detection

          A tarefa de migração de dados não pode ser iniciada se tarefas de gerenciamento (como scale-out, upgrade ou downgrade) estiverem em execução no cluster de origem ou de destino.

          Storage Space Detection

          O espaço de armazenamento disponível do cluster de destino deve ser de pelo menos 1,2 vez o espaço de armazenamento utilizado pelo cluster auto-gerenciado.

          Local Table and Distributed Table Detection

          Se uma tabela local no cluster auto-gerenciado não tiver uma tabela distribuída correspondente ou tiver mais de uma tabela distribuída, a verificação falhará. Para resolver isso, exclua as tabelas distribuídas redundantes ou crie uma tabela distribuída exclusiva para a tabela local.

    Etapa 6: Avaliar a viabilidade da migração

    Se a velocidade de gravação do cluster de origem for menor que 20 MB/s, você pode pular esta etapa.

    Se a velocidade de gravação do cluster de origem for maior que 20 MB/s, você deve verificar a velocidade real de gravação do cluster de destino para avaliar a viabilidade da migração. Uma migração bem-sucedida exige que a velocidade de gravação do cluster de destino acompanhe a do cluster de origem. Siga estas etapas:

    1. Visualize o TairPDBShardingIOBandwidth do cluster de destino para determinar sua velocidade real de gravação. Para obter informações sobre como visualizar o TairPDBShardingIOBandwidth, consulte {{XREF_15}}.

    2. Compare as velocidades de gravação dos clusters de destino e de origem.

      1. Se a velocidade de gravação do cluster de destino for maior que a do cluster de origem: É provável que a migração seja bem-sucedida. Continue para a Etapa 7.

      2. Se a velocidade de gravação do cluster de destino for menor que a do cluster de origem: É provável que a migração falhe. Recomendamos que você {{XREF_16}} e use {{XREF_17}}.

    Etapa 7: Monitorar a migração e interromper gravações

    1. Faça login no console do ApsaraDB for ClickHouse.

    2. Na lista de instâncias da Community Edition, clique no ID do cluster de destino.

    3. No painel de navegação, clique em Data Migration and Synchronization > Migration from ClickHouse.

    4. Na página da lista de migração de instâncias, você pode:

      • Visualizar o status e o estágio de execução da tarefa de migração.

        Importante

        • Quando o estágio de execução atingir Data Migration (ou seja, a migração do esquema da tabela estiver concluída), prossiga imediatamente para {{XREF_18}} para recriar as tabelas com engines Kafka/RabbitMQ no cluster auto-gerenciado e retomar a ingestão incremental de dados.

        • Monitore de perto as Running Information da tarefa de destino. Com base no tempo restante estimado na coluna Running Information, siga {{XREF_19}} para interromper as gravações no cluster auto-gerenciado e tratar as tabelas com engines Kafka e RabbitMQ.

      • Na coluna Actions, clique em View Details para abrir a página de detalhes da tarefa. A página de detalhes da tarefa contém as seguintes informações:

        Nota

        Se a tarefa de migração estiver concluída (seu status for Completed ou Canceled), o conteúdo na página View Details será limpo. Você pode visualizar a lista de esquemas de tabelas migrados no cluster de destino executando a seguinte instrução SQL:

        EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

        • Todos os esquemas de tabelas migrados e seus respectivos status de migração.

        • Todos os esquemas de bancos de dados migrados e seus respectivos status de migração.

        • Todas as mensagens de erro para migrações de bancos de dados e tabelas que falharam.

      A tabela a seguir descreve os status das tarefas de migração.

      Status da tarefa

      Descrição

      Running

      Preparando o ambiente e os recursos para a migração.

      Initializing

      Inicializando a tarefa de migração.

      Configuration Migration

      Migrando a configuração do cluster.

      Schema Migration

      Migrando todos os bancos de dados, tabelas da família MergeTree e tabelas distribuídas (Distributed).

      Data Migration

      Migrando incrementalmente dados de tabelas da família MergeTree.

      Other Schema Migration

      Migrando os esquemas de visualizações materializadas e tabelas não-MergeTree.

      Data Check

      Verificando se o volume de dados das tabelas concluídas no cluster de destino é consistente com o volume de dados no cluster auto-gerenciado. Se forem inconsistentes, a tarefa poderá falhar. Recomendamos que você reinicie a migração.

      Post-migration Configuration

      Configurando as definições do sistema para o cluster de destino, como limpar recursos de migração e reativar gravações na instância de origem.

      Completed

      A tarefa de migração está concluída.

      Canceled

      A tarefa de migração foi cancelada.

    Etapa 8: Recriar tabelas com engines Kafka/RabbitMQ no cluster auto-gerenciado

    Após a tarefa de migração entrar na fase de data migration (ou seja, a migração do esquema da tabela estiver concluída), use as instruções DDL salvas anteriormente para recriar as tabelas com engines Kafka/RabbitMQ e suas visualizações materializadas subsequentes no cluster auto-gerenciado. 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 uma operação RENAME em tabelas de destino implícitas anteriormente, use a cláusula TO apontando para a tabela de destino renomeada ao recriar a visualização materializada.

    EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;
    EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    Etapa 9: Interromper gravações e realizar o cutover

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

    1. Interrompa as gravações do negócio. No cluster auto-gerenciado, exclua as tabelas com engines Kafka/RabbitMQ recriadas anteriormente e suas visualizações materializadas subsequentes.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    2. Aguarde o progresso da migração atingir 100% e a migração ser totalmente concluída.

    3. Conecte-se ao cluster de destino e use as instruções DDL salvas anteriormente para recriar as tabelas com engines Kafka/RabbitMQ e suas visualizações materializadas subsequentes.

      Importante

      Se você realizou uma operação RENAME em tabelas de destino implícitas anteriormente, use a cláusula TO apontando para a tabela de destino renomeada ao recriar a visualização materializada.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;
      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    4. Verifique se o pipeline de dados no cluster de destino está funcionando corretamente e se os dados estão fluindo normalmente.

    Etapa 10: Concluir a migração

    Após interromper as gravações no cluster auto-gerenciado, você pode Complete the task. Esta etapa migra os dados restantes, realiza uma verificação do volume de dados e migra os esquemas restantes de bancos de dados e tabelas. Você pode visualizar o conteúdo migrado em {{XREF_20}}.

    Importante

    • Se a verificação de dados falhar, a tarefa de migração permanecerá na fase de verificação de volume de dados. Recomendamos cancelar a migração e criar uma nova tarefa de migração. Para mais informações sobre como cancelar uma tarefa de migração, consulte {{XREF_21}}.

    • Uma migração de dados longa pode causar o acúmulo excessivo de metadados no cluster de destino. Recomendamos que as tarefas de migração não excedam 5 dias de duração. Tarefas que excedem 5 dias são canceladas automaticamente.

    1. Faça login no console do ApsaraDB for ClickHouse.

    2. Na página Clusters, selecione Clusters of Community-compatible Edition e clique no ID do cluster de destino.

    3. No painel de navegação à esquerda, clique em Data Migration and Synchronization > Migration from ClickHouse.

    4. Para a tarefa de migração de destino, clique em Complete Migration na coluna Actions.

    5. Na caixa de diálogo Complete Migration, clique em OK.

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

    A tarefa de migração migra apenas o esquema da tabela de tabelas não-MergeTree (como tabelas externas e tabelas Log), criando-as no cluster de destino sem nenhum dado de negócio. Você deve migrar os dados de negócio manualmente. Siga estas etapas:

    1. Faça login no cluster auto-gerenciado e execute a seguinte instrução para identificar as tabelas não-MergeTree que exigem migração de dados.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    2. Faça login no cluster de destino e use a função remote para migrar os dados da tabela. Para obter instruções detalhadas, consulte {{XREF_22}}.

    Outras operações

    Quando uma tarefa de migração é concluída, seu Migration Status muda para Completed. A lista de tarefas não é atualizada imediatamente, portanto, atualize a página periodicamente para visualizar o status mais recente.

    Ações

    Descrição

    Impacto

    Cenário

    Cancel Migration

    Cancela forçadamente a tarefa e pula a verificação de volume de dados, sem migrar os esquemas restantes de bancos de dados e tabelas.

    • A migração é encerrada à força. Os esquemas de bancos de dados e tabelas na instância de destino podem ficar incompletos e inutilizáveis.

    • Antes de reiniciar a migração, você deve limpar os dados migrados do cluster de destino para evitar duplicação de dados.

    Use esta opção quando a migração afetar adversamente o seu cluster auto-gerenciado e você precisar restaurar as operações de gravação imediatamente.

    Stop Migration

    Interrompe a migração de dados imediatamente, mas conclui a migração dos esquemas restantes de bancos de dados e tabelas. A verificação de volume de dados é ignorada.

    A migração de dados ficará incompleta, mas os esquemas de bancos de dados e tabelas na instância de destino estarão completos.

    Use esta opção para testar um conjunto de dados parcialmente migrado sem interromper as gravações no cluster auto-gerenciado.

    Interromper migração

    1. Faça login no console do ApsaraDB for ClickHouse.

    2. Na página Clusters, selecione Clusters of Community-compatible Edition e, em seguida, clique no ID do cluster de destino.

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

    4. Na coluna Actions da tarefa de migração de destino, clique em Stop Migration.

    5. Na caixa de diálogo Stop Migration, clique em OK.

    Cancelar migração

    1. Faça login no console do ApsaraDB for ClickHouse.

    2. Na página Clusters, selecione Clusters of Community-compatible Edition e, em seguida, clique no ID do cluster de destino.

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

    4. Na coluna Actions da tarefa de migração de destino, clique em Cancel Migration.

    5. Na caixa de diálogo Cancel Migration, clique em OK.

    Migração manual

    Método 1: Usar os comandos BACKUP e RESTORE

    Para mais informações, consulte {{XREF_23}}.

    Método 2: Usar a instrução INSERT FROM SELECT

    Etapa 1: Migrar metadados

    A migração de metadados do ClickHouse consiste principalmente em migrar o DDL de criação das tabelas.

    Se você precisar instalar a ferramenta clickhouse-client, certifique-se de que sua versão corresponda à da instância de destino do ApsaraDB for ClickHouse. Você pode encontrar o link para download em clickhouse-client.

    1. Visualize a lista de bancos de dados no cluster auto-gerenciado.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

      Parâmetros:

      Parâmetro

      Descrição

      old host

      O endereço do cluster auto-gerenciado.

      old port

      A porta do cluster auto-gerenciado.

      old user name

      A conta usada para fazer login no cluster auto-gerenciado. A conta deve ter permissões de leitura/gravação DML, permissões de configurações e permissões DDL.

      old password

      A senha da conta.
      Nota

      O banco de dados system é um banco de dados do sistema e não requer migração. Filtre-o.

    2. Visualize a lista de tabelas no cluster auto-gerenciado.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

      Parâmetros:

      Parâmetro

      Descrição

      database_name

      O nome do banco de dados.

      Alternativamente, você pode consultar todos os nomes de bancos de dados e tabelas diretamente nas tabelas do sistema.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;
      Nota

      Se o nome de uma tabela consultada começar com .inner., trata-se de uma representação interna de uma visualização materializada e não requer migração. Filtre-a.

    3. Exporte o DDL de criação de tabelas para todas as tabelas em um banco de dados específico a partir do cluster auto-gerenciado.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    4. Importe o DDL de criação de tabelas para a instância de destino do ApsaraDB for ClickHouse.

      Nota

      Antes de importar o DDL de criação de tabelas, você deve criar o banco de dados correspondente na instância do ApsaraDB for ClickHouse.

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

      Parâmetros:

      Parâmetro

      Descrição

      new host

      O endereço da instância de destino do ApsaraDB for ClickHouse.

      new port

      A porta da instância de destino do ApsaraDB for ClickHouse.

      new user name

      A conta usada para fazer login na instância de destino do ApsaraDB for ClickHouse. A conta deve ter permissões de leitura/gravação DML, permissões de configurações e permissões DDL.

      new password

      A senha da conta.

    Etapa 2: Migrar dados

    Função Remote

    1. (Opcional) Ao migrar dados para uma instância do ApsaraDB for ClickHouse, considere ajustar o parâmetro network_compression_method para reduzir o tráfego de rede.

      • Para modificar temporariamente o network_compression_method na instância de destino do ApsaraDB for ClickHouse, execute o seguinte comando.

        • EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

      • Para visualizar o valor do parâmetro network_compression_method na instância de destino do ApsaraDB for ClickHouse, execute o seguinte comando.

        • EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    2. Use a função Remote para extrair (pull) ou enviar (push) dados.

      • No cluster de destino do ApsaraDB for ClickHouse, use a função Remote para extrair dados da tabela de origem.

        EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;
        Nota

        Para a versão 20.8, use primeiro a função remoteRaw para a migração de dados. Se a migração falhar, você pode solicitar uma atualização de versão secundária (minor version).

        EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

        Parâmetros:

        Importante

        Use o parâmetro _partition_id para filtrar dados. Isso reduz o uso de recursos.

        (Opcional) Para obter o partition_id e o número de partes, consulte-os na tabela system.parts executando a seguinte instrução SQL.

        EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

        Parâmetro

        Descrição

        new_database

        O nome do banco de dados na instância de destino do ApsaraDB for ClickHouse.

        new_table

        O nome da tabela na instância de destino do ApsaraDB for ClickHouse.

        old_endpoint

        O endpoint da instância de origem.

        ClickHouse auto-gerenciado

        Formato do endpoint: Endereço IP de um nó da instância de origem:porta.

        Importante

        A porta deve ser a porta TCP.

        ApsaraDB for ClickHouse

        Use o endpoint interno da VPC da instância de origem, não o endpoint público.

        Importante

        As portas 3306 e 9000 são valores fixos.

        • Instância da Community Edition:

          • Formato do endpoint: Endereço interno da VPC:3306.

          • Exemplo: cc-2zeqhh5v7y6q*.clickhouse.ads.aliyuncs.com:3306

        • Instância Enterprise:

          • Formato do endpoint: Endereço interno da VPC:9000.

          • Exemplo: cc-bp1anv7jo84ta*clickhouse.clickhouseserver.rds.aliyuncs.com:9000

        old_database

        O nome do banco de dados do cluster auto-gerenciado.

        old_table

        O nome da tabela do cluster auto-gerenciado.

        username

        A conta do cluster auto-gerenciado.

        password

        A senha da conta do cluster auto-gerenciado.

        max_execution_time

        O tempo máximo de execução para uma consulta. Defina como 0 para não haver limite de tempo.

        max_bytes_to_read

        O número máximo de bytes que uma consulta pode ler dos dados de origem. Defina como 0 para não haver limite.

        log_query_threads

        Especifica se deve registrar informações de threads durante a execução da consulta. Defina como 0 para desativar o registro.

        max_result_rows

        O número máximo de linhas no resultado da consulta. Defina como 0 para não haver limite.

        min_insert_block_size_rows

        O número mínimo de linhas por parte de dados em uma única gravação. Defina como 4294967296 (máximo) para desativar o limite de linhas. Esta configuração funciona em conjunto com min_insert_block_size_bytes para evitar um excesso de partes pequenas.

        min_insert_block_size_bytes

        O tamanho mínimo em bytes por parte de dados em uma única gravação. Defina como 1073741824 (1 GB) para evitar um excesso de partes pequenas e evitar o erro "Too many partitions for a single INSERT block".

        _partition_id

        O ID da partição de dados.

        allow_experimental_analyzer

        Se deve ativar o novo analisador. Defina como 0 para desativá-lo.

      • No cluster de origem, use a função Remote para enviar dados para o cluster de destino.

        Importante

        Se o cluster de origem executar uma versão anterior à 22.10 e o cluster de destino executar a versão 24.3 ou posterior, use um envio iniciado pela origem. Execute INSERT INTO FUNCTION remote no cluster de origem para enviar dados para o cluster de destino. Isso ocorre porque a versão mais antiga da origem não suporta a configuração allow_experimental_analyzer. A extração a partir do destino mais novo passa essas configurações para a origem e causa erros.

        EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    Exportação e importação de arquivos

    Exporte os dados do banco de dados do cluster auto-gerenciado para um arquivo e, em seguida, importe o arquivo para a instância de destino do ApsaraDB for ClickHouse.

    • Exportação e importação de CSV

      1. Exporte os dados do banco de dados do cluster auto-gerenciado para um arquivo CSV.

        EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

      2. Importe o arquivo CSV para a instância de destino do ApsaraDB for ClickHouse.

        EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    • Stream com um pipe do Linux

      EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

    Erros de verificação de migração e soluções

    Mensagem de erro

    Descrição

    Solução

    Missing unique distributed table or sharding_key not set.

    Uma local table no self-managed cluster não possui uma distributed table exclusiva.

    Crie uma distributed table correspondente para a local table no self-managed cluster.

    The corresponding distributed table is not unique.

    Uma local table no self-managed cluster corresponde a múltiplas distributed tables.

    Exclua as distributed tables redundantes no self-managed cluster e mantenha apenas uma.

    MergeTree table on a multi-replica cluster.

    O self-managed cluster é um multi-replica cluster, mas contém uma non-replicated table. A migração não é suportada porque os dados são inconsistentes entre as replicas.

    {{XREF_24}}

    Data reserved table on destination cluster.

    A tabela a ser migrada já existe e contém dados no destination cluster.

    Exclua a tabela correspondente do destination cluster.

    Columns of distributed table and local table conflict

    As colunas da distributed table e da local table no self-managed cluster são inconsistentes.

    Recrie a distributed table no self-managed cluster para garantir que seu esquema seja consistente com a local table.

    Insufficient storage space.

    O destination cluster possui storage space insuficiente.

    Aumente o storage space em disco do destination cluster. Certifique-se de que o storage space total do destination cluster seja de pelo menos 1,2 vez o espaço utilizado pelo self-managed cluster. Para mais informações, consulte {{XREF_25}}.

    Missing system table.

    Uma system table está ausente no self-managed cluster.

    Modifique o arquivo de configuração config.xml do self-managed cluster para criar as system tables necessárias. Para mais informações, consulte {{XREF_26}}.

    The table is incomplete across different nodes.

    A tabela está ausente em alguns nodes.

    Crie tabelas com o mesmo nome em diferentes shards. Para uma tabela interna de uma materialized view, renomeie a tabela interna e, em seguida, recrie a materialized view para apontar para a tabela renomeada. Para mais informações, consulte {{XREF_27}}.

    Calculando o tempo de merge pós-migração

    Após a migração, o cluster de destino realiza temporariamente operações frequentes de merge. Isso aumenta o uso de I/O e pode causar maior latência para as requisições de service. Se seus services forem sensíveis à latência de leitura e gravação, considere atualizar o tipo de instância e o nível de desempenho do ESSD para encurtar esse período de alto uso de I/O. Para mais informações, consulte {{XREF_28}}.

    Use as seguintes fórmulas para calcular o tempo de merge após a migração:

    Nota

    Essas fórmulas se aplicam tanto a clusters de réplica única quanto a clusters master-replica.

    • Tempo total estimado para operações frequentes de merge = MAX(hot data merge time, cold data merge time)

      • Tempo de merge de dados quentes = amount of hot data on a single node * 2 / MIN(instance type bandwidth, disk bandwidth * n)

      • Tempo de merge de dados frios = (amount of cold data / number of nodes) / MIN(instance type bandwidth, OSS read bandwidth) + (amount of cold data / number of nodes) / MIN(instance type bandwidth, OSS write bandwidth)

    A lista a seguir descreve os parâmetros usados nas fórmulas:

    • Quantidade de dados quentes em um único nó: Você pode visualizar esse valor na linha Disk Usage - Single-Node Statistics. Para mais informações, consulte {{XREF_29}}.

    • Largura de banda do tipo de instância

      Nota

      Esses valores de largura de banda não são absolutos e variam dependendo dos tipos de máquina usados pelo backend do ApsaraDB for ClickHouse. Os valores fornecidos são mínimos e apenas para referência.

      Especificação

      Largura de banda (MB/s)

      Standard 8-core 32 GB

      250

      Standard 16-core 64 GB

      375

      Standard 24-core 96 GB

      500

      Standard 32-core 128 GB

      625

      Standard 64-core 256 GB

      1250

      Standard 80-core 384 GB

      2000

      Standard 104-core 384 GB

      2000

    • Largura de banda do disco: Encontre este valor na linha Maximum throughput per disk (MB/s) da tabela {{XREF_30}}.

    • n: O número de discos em um único nó. Execute o seguinte comando para obter esse valor: SELECT count() FROM system.disks WHERE type = 'local';

    • Quantidade de dados frios: Você pode visualizar esse valor na linha clickhouse_cold_storage_data. Para mais informações, consulte {{XREF_31}}.

    • Número de nós: O número de nós no cluster. Execute o seguinte comando para obter esse valor: SELECT count() FROM system.clusters WHERE cluster = 'default' and replica_num=1;

    • Largura de banda de leitura do OSS: Encontre este valor na coluna Total Intranet and Internet Download Bandwidth da tabela {{XREF_32}}.

    • Largura de banda de gravação do OSS: Encontre este valor na coluna Total Intranet and Internet Upload Bandwidth da tabela {{XREF_33}}.

    Perguntas frequentes

    • P: Como resolvo o erro "Too many partitions for single INSERT block (more than 100)"?

      R: Esse erro ocorre porque uma única operação INSERT excede o limite max_partitions_per_insert_block, que é 100 por padrão. No ClickHouse, cada operação de gravação cria uma parte de dados, e uma partição pode conter uma ou mais partes de dados. Se uma única operação INSERT gravar dados em muitas partições, ela criará um número excessivo de partes de dados. Isso pode degradar significativamente o desempenho de merge e consulta. O ClickHouse impõe esse limite para evitar a degradação do desempenho.

      Para resolver esse problema, você pode ajustar o número de partições ou modificar o parâmetro max_partitions_per_insert_block.

      • Ajuste o esquema da tabela e o método de particionamento, ou evite inserir dados em muitas partições diferentes em uma única operação.

      • Se você precisar inserir dados em muitas partições de uma só vez, poderá aumentar o limite modificando o parâmetro max_partitions_per_insert_block. A sintaxe é a seguinte:

        EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;
        Nota

        A comunidade ClickHouse recomenda o uso do valor padrão de 100. Não defina esse valor muito alto, pois isso pode degradar o desempenho. Após a importação de dados em lote, recomendamos que você redefina o valor para o padrão.

    • P: Por que a conexão da minha instância de destino do ApsaraDB for ClickHouse com o meu banco de dados ClickHouse auto-gerenciado falha?

      R: Esse problema ocorre se o seu banco de dados ClickHouse auto-gerenciado estiver atrás de um firewall ou usar uma lista de permissões. Para resolver isso, adicione o bloco CIDR IPv4 do vSwitch do cluster ApsaraDB for ClickHouse à lista de permissões do seu banco de dados auto-gerenciado. Para obter informações sobre como obter o bloco CIDR IPv4 do vSwitch do cluster ApsaraDB for ClickHouse, consulte {{XREF_34}}.

    • P: Quando dimensiono ou migro uma instância multi-réplica, por que tabelas não replicadas (non-Replicated) não são permitidas? Se elas existirem, como resolvo esse problema?

      R: O motivo dessa restrição e a solução são os seguintes:

      • Motivo: Uma instância multi-réplica requer tabelas Replicated para sincronizar dados entre réplicas. Sem tabelas Replicated, a configuração multi-réplica é ineficaz. A ferramenta de migração seleciona aleatoriamente uma réplica como fonte de dados e migra seus dados para a instância de destino.

        Se existirem tabelas não replicadas, os dados não são sincronizados entre as réplicas, o que significa que cada réplica armazena dados isolados. Como a ferramenta de migração migra de apenas uma réplica, esse processo causa perda de dados. Por exemplo, conforme mostrado na figura a seguir, a tabela MergeTree na réplica 0 (r0) contém os dados 1, 2 e 3. A tabela MergeTree na réplica 1 (r1) contém os dados 4 e 5. Se a ferramenta de migração selecionar r0 como origem, apenas os dados 1, 2 e 3 serão migrados para a instância de destino.

        image

      • Solução: Se você puder excluir as tabelas não replicadas na instância de origem, recomendamos fazê-lo. Caso contrário, você deve substituir as tabelas não replicadas por tabelas Replicated. Siga estas etapas:

        1. Faça login na instância de origem.

        2. Crie uma tabela Replicated. O esquema da tabela deve ser idêntico ao da tabela não replicada que você deseja substituir, exceto pela engine.

        3. Migre manualmente os dados da tabela não replicada para a nova tabela Replicated. A instrução de migração é a seguinte:

          Importante

          Você deve realizar essa migração para cada réplica. Por exemplo, você deve executar a instrução tanto em r0 quanto em r1.

          Você pode obter o endereço IP do nó para a instrução executando SELECT * FROM system.clusters;.

          EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;

        4. Troque os nomes da tabela não replicada e da tabela Replicated.

        EXCHANGE TABLES <source_database>.<non_replicated_table_to_replace> AND <destination_database>.<new_replicated_table> ON CLUSTER default;