ApsaraDB for ClickHouse:One-click major engine version upgrade

Requisitos previos

El clúster se encuentra en estado Running.

Notas de uso

• No es posible cancelar el proceso de actualización de versión principal del motor con un clic una vez que ha comenzado.

  Nota

  No se admite la reversión de versión después de una actualización de versión principal del motor con un clic. Si necesita poder revertir a la versión anterior después de la actualización, puede realizarla mediante la clonación del clúster. Para obtener más información, consulte Upgrade the major engine version by cloning.

• Para garantizar una actualización sin problemas, se recomienda detener las operaciones de escritura desde su aplicación antes de iniciarla. Aunque el clúster detiene automáticamente las operaciones de escritura durante el proceso, no detenerlas previamente en la aplicación puede causar retrasos prolongados o impedir que la sincronización se complete a tiempo, lo cual ralentiza la actualización.

• Para minimizar el impacto en su negocio, se recomienda encarecidamente realizar las siguientes validaciones antes de actualizar:

  • Validación de compatibilidad y rendimiento: Compruebe cualquier diferencia en funciones, sintaxis y rendimiento para operaciones de escritura y consulta.

  • Validación de duración de la actualización: La instancia se reinicia varias veces durante la actualización de versión. En algunas instancias, un solo reinicio puede tardar mucho tiempo debido a una gran cantidad de bases de datos, tablas o particiones (partes).

    Importante

    Si el clúster utiliza Tiered Storage for Hot and Cold Data y realiza una validación por clonación, la actualización con un clic tardará más que la validación. Esto se debe a que la operación de clonación no incluye datos fríos, mientras que la actualización real sí los incluye.

  Para obtener información sobre cómo realizar la validación, consulte Validate version compatibility.

Impacto en el clúster

El clúster se reinicia varias veces durante la actualización y no está disponible para operaciones de lectura y escritura durante cada reinicio. Se recomienda realizar la actualización en horas de baja demanda.

Validar la compatibilidad de versiones

Una actualización de versión principal del motor con un clic no se puede revertir. Se recomienda encarecidamente probar primero la actualización para confirmar que la nueva versión es totalmente compatible con la versión de origen y que la duración de la actualización es aceptable:

1. Vaya a la página Cluster Information de la instancia de destino. En el panel de navegación izquierdo, haga clic en Backup and Restoration. Una vez realizada la copia de seguridad de la instancia, haga clic en Restore Instance.

2. Seleccione Clone from real-time replica y establezca la versión de motor de destino en la versión a la que desea actualizar.

3. Cree el clúster clonado.

4. Realice la validación de compatibilidad.

   1. Valide la compatibilidad de sus consultas de negocio con la nueva versión. Para obtener más información, consulte SQL compatibility validation.

   2. Realice pruebas de regresión para las funciones de su negocio.

Procedimiento

1. Inicie sesión en la consola de ApsaraDB for ClickHouse con su cuenta de Alibaba Cloud.

2. En la esquina superior izquierda de la página, seleccione la región donde se encuentra el clúster de destino.

3. En el panel de navegación izquierdo, haga clic en Clusters of Community-compatible Edition.

4. Busque el clúster de destino y haga clic en su ID para ir a la página Cluster Information.

5. In the Cluster Properties section, click Major Version Upgrade next to Version.

6. Configure the following parameters as prompted and click OK.

   Parámetro	Descripción	Ejemplo
   Upgrade cluster kernel version to	La versión de destino del clúster. No se admite la reversión de versión después de la actualización. Actualmente, solo se admite la versión 23.8.	23.8 (versión LTS)
   Version upgrade execution time	El momento para realizar la actualización del clúster. Importante Si selecciona actualizar en un momento específico o dentro de una ventana de mantenimiento, el estado del clúster cambia de Running a Upgrading. Antes de que llegue el momento especificado o la ventana de mantenimiento, el clúster puede atender solicitudes de lectura y escritura con normalidad, pero no es posible realizar operaciones de mantenimiento como cambios de configuración de instancia, escalado o migración. Specified Time: Seleccione un momento futuro para realizar la actualización de versión principal. Upgrade Within Maintenance Window: La actualización se realiza durante la ventana de mantenimiento configurada del clúster. Update Now: Inicia la actualización inmediatamente.	2024-05-29 14:46
   Perform clone validation	Seleccione Clone Validation Performed o Skip Clone Verification (Not Recommended).	Validación de clonación realizada

Requisitos previos

El clúster se encuentra en estado Running.

Notas de uso

• Una actualización de versión principal del motor con un clic involucra únicamente un solo clúster, y no es posible revertir la versión una vez completada la actualización.

  Nota

  No se admite la reversión de versión después de una actualización de versión principal del motor con un clic. Si necesita poder revertir a la versión anterior después de la actualización, puede realizarla mediante la migración de datos. Para obtener más información, consulte Upgrade the major engine version by data migration.

• Al actualizar un clúster, tenga en cuenta los siguientes puntos sobre sus bases de datos y tablas:

  • Para tablas que utilizan un motor de la familia MergeTree, los datos históricos se migran al nuevo clúster y se redistribuyen automáticamente durante la actualización.

  • Para tablas que no utilizan un motor de la familia MergeTree, como tablas externas o tablas Log, solo se migran los esquemas de tabla. Los datos no se migran.

  • Para una vista materializada, solo se migra el esquema. Los datos no se migran.

  • Las tablas con motores Kafka y RabbitMQ no se pueden migrar directamente mediante la función de actualización de la consola. Debe registrar las sentencias DDL de estas tablas y eliminarlas del clúster antes de actualizar para evitar interferencias con la tarea de actualización. Una vez completada la actualización, debe reconstruir estas tablas. Para conocer los pasos detallados, consulte el procedimiento a continuación.

  • Las direcciones IP internas de los nodos cambian después de la actualización. Si sus escrituras de datos y accesos dependen de las direcciones IP de los nodos, debe obtener las nuevas VPC CIDR block del clúster.

• Para minimizar el impacto en su negocio, se recomienda encarecidamente realizar las siguientes validaciones antes de actualizar:

  • Validación de compatibilidad y rendimiento: Compruebe cualquier diferencia en funciones, sintaxis y rendimiento para operaciones de escritura y consulta.

  • Validación de duración de la actualización: La instancia se reinicia varias veces durante la actualización de versión. En algunas instancias, un solo reinicio puede tardar mucho tiempo debido a una gran cantidad de bases de datos, tablas o particiones (partes).

  Para obtener información sobre cómo realizar la validación, consulte Validate version compatibility.

Impacto en el clúster

Un clúster de Community Edition permite lectura y escritura durante todo el proceso de actualización, excepto en los últimos 10 minutos de migración, cuando el clúster pasa a ser de solo lectura. Para consultar el tiempo restante de migración, véase View upgrade progress.

Validar la compatibilidad de versiones

Una actualización de versión principal del motor con un clic no se puede revertir. Se recomienda encarecidamente probar primero la actualización para confirmar que la nueva versión es totalmente compatible con la versión de origen y que la duración de la actualización es aceptable:

1. Adquiera un nuevo clúster para realizar la validación de migración. Para obtener más información, consulte Upgrade the major engine version by data migration.

2. En el nuevo clúster, realice la validación de compatibilidad SQL. Para obtener más información, consulte SQL compatibility validation.

3. Realice pruebas de regresión para las funciones de su negocio.

Paso 1: Registrar y limpiar tablas con motores Kafka/RabbitMQ

Las tablas con motores Kafka y RabbitMQ no se pueden migrar directamente mediante la función de actualización de la consola. Registre las sentencias DDL de estas tablas y elimínelas antes de actualizar para evitar interferencias con la tarea de actualización.

1. Inicie sesión en el clúster y ejecute la siguiente sentencia para consultar las tablas que deben manejarse.

   /*
   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. Consulte la definición de la vista materializada para comprobar si su tabla de destino es una tabla 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. Si se creó una vista materializada sin la cláusula TO, el sistema genera automáticamente una tabla de destino implícita con el prefijo .inner o .inner_id. Estas tablas implícitas se migran a los nuevos nodos del clúster durante la actualización, pero debido a mecanismos internos de nomenclatura, recrear directamente la vista materializada original puede causar conflictos de nombres. Por lo tanto, primero debe cambiar el nombre de las tablas de destino implícitas a nombres de tabla 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. Elimine las vistas materializadas y las tablas con motores Kafka/RabbitMQ.

   Importante

   Debe eliminar primero las vistas materializadas que hacen referencia a las tablas Kafka/RabbitMQ y luego eliminar las tablas con motores Kafka/RabbitMQ. De lo contrario, la operación de actualización fallará.

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

Paso 2: Actualizar el clúster

1. Inicie sesión en la consola de ApsaraDB for ClickHouse con su cuenta de Alibaba Cloud.

2. En la esquina superior izquierda de la página, seleccione la región donde se encuentra el clúster de destino.

3. En el panel de navegación izquierdo, haga clic en Clusters of Community-compatible Edition.

4. Busque el clúster de destino y haga clic en su ID para ir a la página Cluster Information.

5. In the Cluster Properties section, click Major Version Upgrade next to Version.

6. Configure the following parameters as prompted and click OK.

   Parámetro	Descripción	Ejemplo
   Upgrade cluster kernel version to	La versión de destino del clúster. No se admite la reversión de versión después de la actualización. Actualmente, solo se admite la versión 23.8.	23.8 (versión LTS)
   Time of Stopping Data Writing	Para garantizar la consistencia de los datos antes y después de la actualización, el clúster detiene automáticamente las operaciones de escritura durante los últimos 10 minutos de la actualización. Las siguientes reglas aplican para establecer el tiempo de suspensión de escritura: Para garantizar una actualización exitosa, se recomienda establecer el tiempo de suspensión de escritura en al menos 30 minutos. La actualización debe finalizar dentro de 5 días. Por lo tanto, la fecha de finalización para Time of Stopping Data Writing debe ser menor o igual a fecha actual + 5 días. Para minimizar el impacto de la suspensión de escritura en su negocio, se recomienda establecer el tiempo de suspensión de escritura en un periodo dentro de sus horas de baja demanda.	2025-03-20 10:08 - 2025-03-25 10:08
   Perform instance migration validation	Seleccione Verification Performed o Skip instance migration validation (Not Recommended).	Validación de migración de instancia realizada

7. Siguientes pasos

   • Si el clúster de origen contiene tablas con motores Kafka o RabbitMQ, realice los pasos 3 a 5 en los momentos adecuados durante la actualización. Para más detalles, consulte las secciones a continuación.

   • Para ver el progreso de la actualización, consulte View the upgrade progress.

   • Si el tiempo de suspensión de escritura especificado ya pasó pero el estado del clúster sigue siendo Upgrading, debe modify the write suspension time para completar la migración.

   • Si la actualización afecta su negocio y desea detenerla rápidamente, puede cancel the upgrade.

Paso 3: Reconstruir tablas con motores Kafka/RabbitMQ durante la migración de datos

Cuando la tarea de actualización entra en la fase Data Migration (después de completar la migración del esquema de tablas), utilice las sentencias DDL guardadas previamente para reconstruir las tablas con motores Kafka/RabbitMQ y sus vistas materializadas dependientes. Una vez reconstruidas, los datos incrementales reanudan automáticamente su flujo hacia los nuevos nodos del clúster.

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

Paso 4: Eliminar tablas con motores Kafka/RabbitMQ antes de la suspensión de escritura

Poco antes de la ventana de suspensión de escritura configurada, elimine las tablas con motores Kafka/RabbitMQ y sus vistas materializadas dependientes para detener las escrituras de datos incrementales y garantizar la consistencia durante la sincronización final de datos.

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

Paso 5: Reconstruir tablas con motores Kafka/RabbitMQ después de la actualización

Una vez completada la actualización, utilice las sentencias DDL guardadas previamente para reconstruir las tablas con motores Kafka/RabbitMQ y sus vistas materializadas dependientes en el clúster actualizado, con el fin de restaurar la canalización de consumo de datos incrementales.

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

Ver el progreso de la actualización

1. Inicie sesión en la consola de ApsaraDB for ClickHouse con su cuenta de Alibaba Cloud.

2. En la esquina superior izquierda de la página, seleccione la región donde se encuentra el clúster de destino.

3. En el panel de navegación izquierdo, haga clic en Clusters of Community-compatible Edition.

4. Busque el clúster de destino y haga clic en su ID para ir a la página Cluster Information.

5. In the Cluster Status section, click View Progress next to Status.

   Aparece el cuadro de diálogo Modify Data Write-Stop Time Window, donde puede ver el progreso de la actualización. Por ejemplo, puede consultar el progreso de la migración del esquema MergeTree, la migración de datos, el tiempo restante estimado para la migración de datos y el progreso de otras migraciones de esquema.

Modificar el tiempo de suspensión de escritura

Si el tiempo de suspensión de escritura ya pasó pero el estado del clúster sigue siendo Upgrading, la migración de datos aún no ha terminado. Ajuste el tiempo de suspensión de escritura para garantizar que la actualización finalice correctamente.

1. Inicie sesión en la consola de ApsaraDB for ClickHouse con su cuenta de Alibaba Cloud.

2. En la esquina superior izquierda de la página, seleccione la región donde se encuentra el clúster de destino.

3. En el panel de navegación izquierdo, haga clic en Clusters of Community-compatible Edition.

4. Busque el clúster de destino y haga clic en su ID para ir a la página Cluster Information.

5. In the Cluster Status section, click View Progress next to Status.

6. In the Modify Data Write-Stop Time Window dialog box that appears, modify the Time of Stopping Data Writing and click Confirm.

   Nota

   Las reglas para establecer Time of Stopping Data Writing son las mismas que las del parámetro Time of Stopping Data Writing descrito en Upgrade the cluster.

Cancelar la actualización

Puede cancelar la actualización si esta afecta su negocio y necesita detenerla rápidamente.

1. Inicie sesión en la consola de ApsaraDB for ClickHouse con su cuenta de Alibaba Cloud.

2. En la esquina superior izquierda de la página, seleccione la región donde se encuentra el clúster de destino.

3. En el panel de navegación izquierdo, haga clic en Clusters of Community-compatible Edition.

4. Busque el clúster de destino y haga clic en su ID para ir a la página Cluster Information.

5. In the Cluster Status section, click View Progress next to Status.

6. In the Modify Data Write-Stop Time Window dialog box that appears, click Cancel Upgrade.

   Nota

   Después de hacer clic en Cancel Upgrade, la tarea de actualización no se detiene inmediatamente. La tarea se detiene por completo después de aproximadamente 5 minutos.