ApsaraDB for ClickHouse:One-click major engine version upgrade

Pré-requisitos

O cluster deve estar no estado Running.

Observações de uso

• Não é possível cancelar o processo de atualização da versão principal do mecanismo após o início.

  Nota

  A reversão de versão não é suportada após a atualização da versão principal com um clique. Caso precise garantir a possibilidade de reverter para a versão anterior, realize a atualização por meio da clonagem do cluster. Para mais informações, consulte Upgrade the major engine version by cloning.

• Para garantir uma atualização tranquila, interrompa as operações de escrita da aplicação antes de iniciar o processo. Embora o cluster pare automaticamente as escritas durante a atualização, não interrompê-las previamente na aplicação pode causar longos atrasos ou impedir que a sincronização seja concluída rapidamente, tornando o processo mais lento.

• Para minimizar impactos nos negócios, recomendamos fortemente realizar as seguintes validações antes da atualização:

  • Validação de compatibilidade e desempenho: Verifique diferenças em recursos, sintaxe e desempenho nas operações de escrita e consulta.

  • Validação da duração da atualização: A instância reinicia várias vezes durante o processo. Em alguns casos, uma única reinicialização pode demorar bastante devido ao grande volume de bancos de dados, tabelas ou partições (parts).

    Importante

    Se o cluster utilizar Tiered Storage for Hot and Cold Data e você executar uma validação por clonagem, a atualização com um clique levará mais tempo do que a validação. Isso ocorre porque a operação de clonagem não inclui dados frios, enquanto a atualização real os inclui.

  Para saber como realizar a validação, consulte Validate version compatibility.

Impacto no cluster

Durante a atualização, o cluster reinicia diversas vezes e fica indisponível para leituras e escritas em cada reinicialização. Recomendamos executar a atualização em horários de baixa demanda.

Validar compatibilidade de versão

A atualização da versão principal com um clique não permite reversão. Recomendamos testar a atualização previamente para confirmar a total compatibilidade entre a nova versão e a versão de origem, além de verificar se a duração do processo é aceitável:

1. Acesse a página Cluster Information da instância alvo. No painel de navegação à esquerda, clique em Backup and Restoration. Após concluir o backup da instância, clique em Restore Instance.

2. Selecione Clone from real-time replica e defina a versão do mecanismo alvo como a versão para a qual deseja atualizar.

3. Crie o cluster clonado.

4. Realize a validação de compatibilidade.

   1. Valide a compatibilidade das consultas de negócio com a nova versão. Para mais informações, consulte SQL compatibility validation.

   2. Execute testes de regressão para os recursos de negócio.

Procedimento

1. Faça login no console do ApsaraDB for ClickHouse com sua conta Alibaba Cloud.

2. No canto superior esquerdo da página, selecione a região onde o cluster alvo está localizado.

3. No painel de navegação à esquerda, clique em Clusters of Community-compatible Edition.

4. Localize o cluster alvo e clique no ID do cluster para acessar a página Cluster Information.

5. Na seção Cluster Properties, clique em Major Version Upgrade ao lado de Version.

6. Configure os parâmetros abaixo conforme solicitado e clique em OK.

   Parâmetro	Descrição	Exemplo
   Upgrade cluster kernel version to	Versão alvo do cluster. A reversão de versão não é suportada após a atualização. Atualmente, apenas a versão 23.8 é suportada.	23.8 (versão LTS)
   Version upgrade execution time	Horário para execução da atualização do cluster. Importante Ao optar por atualizar em um horário específico ou dentro de uma janela de manutenção, o status do cluster muda de Running para Upgrading. Antes do horário especificado ou da janela de manutenção, o cluster atende normalmente a requisições de leitura e escrita, mas operações de manutenção como alteração de configuração da instância, dimensionamento ou migração ficam bloqueadas. Specified Time: Selecione um momento futuro para executar a atualização da versão principal. Upgrade Within Maintenance Window: A atualização ocorre durante a janela de manutenção configurada do cluster. Update Now: Inicia a atualização imediatamente.	2024-05-29 14:46
   Perform clone validation	Selecione Clone Validation Performed ou Skip Clone Verification (Not Recommended).	Validação por clonagem realizada

Pré-requisitos

O cluster deve estar no estado Running.

Observações de uso

• A atualização da versão principal com um clique envolve apenas um único cluster e não permite reversão após a conclusão.

  Nota

  A reversão de versão não é suportada após a atualização da versão principal com um clique. Se precisar reverter para a versão anterior, realize a atualização migrando os dados. Para mais informações, consulte Upgrade the major engine version by data migration.

• Ao atualizar um cluster, observe os pontos abaixo sobre bancos de dados e tabelas:

  • Tabelas que utilizam motores da família MergeTree têm seus dados históricos migrados para o novo cluster e redistribuídos automaticamente durante a atualização.

  • Tabelas fora da família MergeTree, como tabelas externas ou tabelas Log, têm apenas seus esquemas migrados. Os dados não são migrados.

  • Em materialized views, apenas o esquema é migrado. Os dados não são transferidos.

  • Tabelas com motores Kafka e RabbitMQ não podem ser migradas diretamente pelo recurso de atualização do console. Registre as instruções DDL dessas tabelas e exclua-as do cluster antes da atualização para evitar interferências na tarefa. Após a conclusão, reconstrua essas tabelas. Consulte o procedimento detalhado abaixo.

  • Os endereços IP internos dos nós mudam após a atualização. Se suas escritas de dados e acessos dependerem desses IPs, obtenha os novos VPC CIDR block do cluster.

• Para reduzir impactos nos negócios, recomendamos fortemente as seguintes validações prévias:

  • Validação de compatibilidade e desempenho: Verifique diferenças em recursos, sintaxe e desempenho nas operações de escrita e consulta.

  • Validação da duração da atualização: A instância reinicia múltiplas vezes durante o processo. Dependendo do volume de bancos de dados, tabelas ou partições (parts), uma única reinicialização pode ser demorada.

  Para detalhes sobre como realizar a validação, consulte Validate version compatibility.

Impacto no cluster

Um cluster Community Edition permanece disponível para leitura e escrita durante todo o processo de atualização, exceto nos últimos 10 minutos de migração, quando torna-se somente leitura. Para verificar o tempo restante de migração, consulte View upgrade progress.

Validar compatibilidade de versão

A atualização da versão principal com um clique não permite reversão. Recomendamos testar previamente para confirmar a compatibilidade total entre a nova versão e a versão de origem, bem como validar se a duração é aceitável:

1. Adquira um novo cluster para realizar a validação de migração. Para mais informações, consulte Upgrade the major engine version by data migration.

2. No novo cluster, execute a validação de compatibilidade SQL. Para mais informações, consulte SQL compatibility validation.

3. Realize testes de regressão para os recursos de negócio.

Etapa 1: Registrar e limpar tabelas com motores Kafka/RabbitMQ

Tabelas com motores Kafka e RabbitMQ não podem ser migradas diretamente pela funcionalidade de atualização do console. Registre as instruções DDL dessas tabelas e exclua-as antes da atualização para evitar falhas na tarefa.

1. Conecte-se ao cluster e execute a instrução abaixo para listar as tabelas que precisam ser tratadas.

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

2. Verifique a definição da materialized view para identificar se a tabela alvo é implícita.

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

3. Se uma materialized view foi criada sem a cláusula TO, o sistema gera automaticamente uma tabela alvo implícita com prefixo .inner ou .inner_id. Essas tabelas implícitas são migradas para os novos nós durante a atualização, mas recriar a materialized view original diretamente pode causar conflitos de nomes devido aos mecanismos internos de nomenclatura. Portanto, renomeie primeiro as tabelas alvo implícitas para nomes de tabelas regulares.

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

4. Exclua as materialized views e as tabelas com motores Kafka/RabbitMQ.

   Importante

   É obrigatório excluir primeiro as materialized views que referenciam as tabelas Kafka/RabbitMQ e só depois excluir as tabelas com esses motores. Caso contrário, a operação de atualização falhará.

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

Etapa 2: Atualizar o cluster

1. Faça login no console do ApsaraDB for ClickHouse com sua conta Alibaba Cloud.

2. No canto superior esquerdo da página, selecione a região onde o cluster alvo está localizado.

3. No painel de navegação à esquerda, clique em Clusters of Community-compatible Edition.

4. Localize o cluster alvo e clique no ID do cluster para acessar a página Cluster Information.

5. Na seção Cluster Properties, clique em Major Version Upgrade ao lado de Version.

6. Configure os parâmetros abaixo conforme solicitado e clique em OK.

   Parâmetro	Descrição	Exemplo
   Upgrade cluster kernel version to	Versão alvo do cluster. A reversão de versão não é suportada após a atualização. Atualmente, apenas a versão 23.8 é suportada.	23.8 (versão LTS)
   Time of Stopping Data Writing	Para garantir a consistência dos dados antes e depois da atualização, o cluster interrompe automaticamente as operações de escrita nos últimos 10 minutos do processo. As regras para definir o horário de suspensão de escrita são: Para assegurar o sucesso da atualização, defina o tempo de suspensão de escrita para pelo menos 30 minutos. A atualização deve ser concluída em até 5 dias. Portanto, a data final para o parâmetro Time of Stopping Data Writing deve ser menor ou igual a data atual + 5 dias. Para minimizar o impacto da suspensão de escrita nos negócios, configure esse período durante horários de baixa demanda.	2025-03-20 10:08 - 2025-03-25 10:08
   Perform instance migration validation	Selecione Verification Performed ou Skip instance migration validation (Not Recommended).	Validação de migração de instância realizada

7. Próximos passos

   • Se o cluster de origem contiver tabelas com motores Kafka ou RabbitMQ, execute as Etapas 3 a 5 nos momentos apropriados durante a atualização. Veja detalhes nas seções abaixo.

   • Para acompanhar o progresso da atualização, consulte View the upgrade progress.

   • Caso o horário de suspensão de escrita tenha passado e o status do cluster ainda seja Upgrading, você deve modify the write suspension time para concluir a migração.

   • Se a atualização estiver afetando seus negócios e você precisar interrompê-la rapidamente, utilize a opção cancel the upgrade.

Etapa 3: Reconstruir tabelas Kafka/RabbitMQ durante a migração de dados

Quando a tarefa de atualização entrar na fase Data Migration (após a conclusão da migração de esquemas de tabelas), utilize as instruções DDL salvas anteriormente para reconstruir as tabelas com motores Kafka/RabbitMQ e suas materialized views dependentes. Após a reconstrução, os dados incrementais voltarão a fluir automaticamente para os novos nós do cluster.

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

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

Etapa 4: Excluir tabelas Kafka/RabbitMQ antes da suspensão de escrita

Pouco antes da janela de suspensão de escrita configurada, exclua as tabelas com motores Kafka/RabbitMQ e suas materialized views dependentes para interromper a escrita de dados incrementais e garantir a consistência durante a sincronização final de dados.

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

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

Etapa 5: Reconstruir tabelas Kafka/RabbitMQ após a atualização

Após a conclusão da atualização, utilize as instruções DDL salvas anteriormente para reconstruir as tabelas com motores Kafka/RabbitMQ e suas materialized views dependentes no cluster atualizado, restaurando assim o pipeline de consumo de dados incrementais.

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

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

Visualizar o progresso da atualização

1. Faça login no console do ApsaraDB for ClickHouse com sua conta Alibaba Cloud.

2. No canto superior esquerdo da página, selecione a região onde o cluster alvo está localizado.

3. No painel de navegação à esquerda, clique em Clusters of Community-compatible Edition.

4. Localize o cluster alvo e clique no ID do cluster para acessar a página Cluster Information.

5. Na seção Cluster Status, clique em View Progress ao lado de Status.

   A caixa de diálogo Modify Data Write-Stop Time Window será exibida, permitindo visualizar o progresso da atualização. É possível acompanhar, por exemplo, o andamento da migração de esquemas MergeTree, a migração de dados, o tempo estimado restante para a migração de dados e o progresso de outras migrações de esquema.

Modificar o horário de suspensão de escrita

Se o horário de suspensão de escrita já passou e o status do cluster continua como Upgrading, a migração de dados ainda não foi concluída. Ajuste o horário de suspensão para garantir que a atualização termine com sucesso.

1. Faça login no console do ApsaraDB for ClickHouse com sua conta Alibaba Cloud.

2. No canto superior esquerdo da página, selecione a região onde o cluster alvo está localizado.

3. No painel de navegação à esquerda, clique em Clusters of Community-compatible Edition.

4. Localize o cluster alvo e clique no ID do cluster para acessar a página Cluster Information.

5. Na seção Cluster Status, clique em View Progress ao lado de Status.

6. Na caixa de diálogo Modify Data Write-Stop Time Window exibida, modifique o parâmetro Time of Stopping Data Writing e clique em Confirm.

   Nota

   As regras para definir o Time of Stopping Data Writing são as mesmas descritas para o parâmetro Time of Stopping Data Writing em Upgrade the cluster.

Cancelar a atualização

Cancele a atualização caso ela esteja impactando seus negócios e você precise interrompê-la rapidamente.

1. Faça login no console do ApsaraDB for ClickHouse com sua conta Alibaba Cloud.

2. No canto superior esquerdo da página, selecione a região onde o cluster alvo está localizado.

3. No painel de navegação à esquerda, clique em Clusters of Community-compatible Edition.

4. Localize o cluster alvo e clique no ID do cluster para acessar a página Cluster Information.

5. Na seção Cluster Status, clique em View Progress ao lado de Status.

6. Na caixa de diálogo Modify Data Write-Stop Time Window exibida, clique em Cancel Upgrade.

   Nota

   Após clicar em Cancel Upgrade, a tarefa de atualização não é interrompida instantaneamente. A parada completa ocorre após aproximadamente 5 minutos.