ApsaraDB for ClickHouse：將自建ClickHouse遷移至雲資料庫 ClickHouse 企業版

注意事項

步驟一：檢查自建叢集並開啟使用系統資料表system

在資料移轉之前，需要根據自建叢集是否已啟用system.part_log和system.query_log，對config.xml檔案進行修改配置，以實現增量遷移。

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

步驟二：配置目的地組群相容自建叢集版本

為確保目的地組群與自建叢集的行為儘可能相容，需串連目的地組群，修改compatibility參數，使目的地組群與自建叢集的版本號碼一致。

樣本如下：

SELECT currentProfiles(); //擷取使用者使用的profile
SELECT
    profile_name,
    setting_name,
    value
FROM system.settings_profile_elements
WHERE (setting_name = 'compatibility') AND (profile_name = 'xxxx'); // 查詢compatibility配置值
ALTER PROFILE XXXX SETTINGS compatibility = '23.8'; // 修改profile

步驟三：建立遷移任務

1. 登入雲資料庫ClickHouse控制台，在集群清單頁面，選擇企业版实例列表，並單擊目的地組群ID。

2. 在左側導覽列，單擊数据迁移及同步 > 實例遷移。

3. 單擊創建遷移任務。

4. 選擇源及目標執行個體。

   配置項	說明	樣本
   任務名稱	遷移任務名稱，只能由大小寫英文字母和數字組成，且不允許重複，大小寫不敏感。	MigrationTask1229
   源实例cluster名称	通過SELECT * FROM system.clusters; 擷取自建執行個體cluster名稱。	default
   VPC IP地址	叢集每個shard的IP和PORT地址，使用英文逗號隔開。格式：IP:PORT,IP:PORT,.... 您可以使用以下SQL擷取自建叢集的IP和PORT： SELECT shard_num, replica_num, host_address as ip, port FROM system.clusters WHERE cluster = '<cluster_name>' and replica_num = 1; 參數說明： cluster_name：目的地組群的名字。 replica_num=1表示選擇第一個複本集，也可以選擇其他複本集或者自行挑選每個shard的一個副本組成。 重要 不能使用ClickHouse的VPC網域名稱地址或者SLB地址。 如果IP和連接埠發生轉換後映射到阿里雲，則需要根據網路打通情況配置對應的IP和PORT。	192.168.0.5:9000,192.168.0.6:9000
   數據庫賬號	自建叢集資料庫帳號。	test
   數據庫密碼	自建叢集資料庫帳號密碼。	test******
   源实例内核版本	單擊获取版本。	22.8.5.29

5. 根據擷取到的源執行個體版本資訊，執行對應操作：

   • 源執行個體版本大於等於22.10：單擊下一步。

   • 源執行個體版本小於22.10：根據提示填寫目標實例信息，單擊下一步。

   • 擷取版本失敗：源執行個體資訊填寫錯誤、網路未打通等情況會導致擷取版本失敗，請根據提示資訊處理後，重新單擊获取版本。

   說明

   由於低版本社區版與企業版之間存在參數不相容的問題，當源執行個體版本低於22.10時，需要通過源端向目的端推送資料的方式進行同步。在這種情況下，需要將目的端的IP映射至自建網路。如果自建網路與企業版執行個體處於同一 VPC，或雙方網路已通過VPC對等串連連通，則可直接使用原有IP地址進行串連。

6. 檢查連通性和配置。

   1. 單擊開始検査。

      點擊查看檢查項。

      • 連通性驗證：自建執行個體和目標執行個體之間的網路完全打通，兩端各個節點之間能夠互相訪問。

      • 賬戶許可權驗證：源端賬戶、密碼輸入正確，能夠串連到源端執行個體。

      • 檢查源執行個體系統資料表：自建執行個體必須有system.query_log、system.parts、system.part_log三個系統資料表。

      • 檢查配置：自建執行個體和目標執行個體時區相同、目標執行個體的compatibility配置項與源端版本相同。

   2. 檢查過程中可以單擊右上方的即時查看檢查進度。

   3. 檢查完成後，請根據檢查結果，完成後續操作。

      您可以選擇结果级别與檢查項，然後單擊按鈕，查看對應的檢查結果，檢查結果說明如下。

      • 成功：若所有檢查項均通過，單擊下一步繼續操作。

      • 警告：非強制卡點項，需自行確認該警告項是否會對業務和遷移任務造成影響。您可選擇忽略警示，或根據警示內容處理對應的警示項後，再次單擊開始検査，重新檢查連通性與配置。

      • 錯誤：強制卡點項，需根據錯誤內容處理對應的錯誤項後，再次單擊開始検査，重新檢查連通性與配置。

        檢測報錯資訊以及解決方案，請參見常見問題。

7. 檢查庫表結構。

   檢查連通性和配置成功後，進入檢查庫表結構步驟。此步驟分為選擇需要遷移的庫、選擇需要遷移的表和檢查庫表結構三個子步驟。

   重要

   其中選擇需要遷移的庫和選擇需要遷移的表兩個步驟可以跳過。若您確認需要遷移源端的所有庫表，則不需要進行這兩個子步驟，可以直接跳到子步驟3（檢查庫表結構）。

   子步驟1：選擇需要遷移的庫（可跳過）

   1. 單擊查詢源端，後台會自動查詢源端的庫。

   2. 查詢過程中，您可以點擊查询结果，來查看即時查詢結果。

   3. 當源端庫查詢完畢後，您可以根據業務需求選擇需要遷移的庫，選擇完畢後，點擊確認提交即可。

   子步驟2：選擇需要遷移的表（可跳過）

   1. 選擇完需要遷移的庫後，會進入選擇需要遷移的表的介面，單擊查詢源端，後台會自動查詢您選擇的庫中的所有表。

   2. 查詢過程中，您可以點擊查询结果，來查看即時查詢結果。

   3. 當源端表查詢完畢後，您可以根據業務需求選擇需要遷移的表，選擇完畢後，點擊確認提交即可。

   重要

   選擇需要遷移的表時，系統預設全選，若您只需要遷移部分表，可以取消對應庫的全選框，開啟下拉框後即可選擇您需要的表。

   子步驟3：檢查庫表結構

   1. 單擊開始検査，後台會進行庫結構檢查、表結構檢查、UDF檢查，此步驟主要檢查源端執行個體的庫、表、UDF是否存在與目的端不相容的情況。

   2. 檢測過程中，您可以選擇通過結果層級、檢查項，並點擊重新整理按鈕，來查看即時檢查結果。

   3. 檢測結果分為成功、警告、失敗三類。

      • 檢測成功：可直接單擊下一步，進行後續遷移流程。

      • 檢測過程出現警示

        您可以將結果層級設定為警告，並找到對應檢查項查看對應的警告原因。

        重要

        結果層級為警告的檢查項非強制卡點項，需要您自行確認該警告項是否會對您的業務和遷移任務造成影響，在您自行確認後，有以下兩種選擇：

        • 忽略警示，直接單擊下一步，進行後續的遷移流程。

        • 根據警示內容處理對應的警示項後，單擊開始検査，重新檢查庫表結構。檢測警示資訊以及解決方案，請參見本文檢查庫表結構中的報錯資訊及解決方案。

      • 檢測失敗

        您可以將結果層級設定為錯誤，並找到對應檢查項查看對應的錯誤原因。

        重要

        結果層級為錯誤的檢查項為強制卡點項，您需要根據錯誤內容處理對應的錯誤項後，單擊開始検査，重新檢查庫表結構。檢測報錯資訊以及解決方案，請參見本文檢查庫表結構中的報錯資訊及解決方案。

8. 庫表結構遷移。

   1. 單擊开始迁移。

   2. 遷移過程中可以單擊右上方的即時查看遷移進度。

   3. 檢查完成後，請根據檢查結果，完成後續操作。

      檢查結果說明請參見步驟5。

9. （可選）檢查SQL相容性。

   SQL相容性檢查通過在目標執行個體上對自建執行個體的SQL語句進行回放，來驗證不同核心版本的文法相容性，請您根據自身需求，決定是否需要執行此步驟。

   • 無需執行，則單擊跳过兼容性验证。

   • 若需要執行，需選擇请求重放时间後，再單擊開始検査。檢查通過後單擊下一步，檢查不通過時的處理方法請參見步驟5。

     重要

     • 執行個體庫表無資料，僅提供驗證文法相容性的能力。如果需要有資料，可先執行下一步驟遷移部分資料。

     • 由於回放SQL的用戶端版本和目標執行個體不匹配，可能存在誤判。針對異常情況，您可以自行執行SQL驗證。

10. 記錄並清理 Kafka/RabbitMQ 引擎表。

    啟動同步前，需要在自建叢集中記錄 Kafka/RabbitMQ 引擎表及其下遊物化視圖的定義，處理隱式表後刪除這些表，以避免遷移異常。

    1. 登入自建叢集，查詢所有 Kafka 和 RabbitMQ 引擎表及其下遊依賴關係。

       /*
       create_table_query：表定義
       dependencies_database：依賴此表的庫
       dependencies_table：依賴此表的表
       從 dependencies_database 和 dependencies_table 可以拿到依賴 Kafka/RabbitMQ 表的物化視圖表
       */
       SELECT * FROM system.tables WHERE engine IN ('RabbitMQ', 'Kafka');

    2. 查看物化視圖定義，確認其目標表是否為隱式表。

       /*
       查看物化視圖定義
       如果物化視圖的目標表是隱式表，則特別注意：刪除物化視圖表會同步刪除隱式表，導致資料丟失
       舉例：CREATE MATERIALIZED VIEW [db.]table_name [TO[db.]name] 中沒有指定 TO，
       則系統會自動建立出來一個隱式表，可能格式為 '.inner_id.<TABLE_UUID>' 或 '.inner.<TABLE>'
       */
       SELECT * FROM system.tables WHERE database='<DATABASE>' AND name = '<MATERIALIZED_VIEW_NAME>';

    3. 如果物化視圖目標表是隱式表，則 RENAME 物化視圖目標表到一個新名字，避免後續刪除物化視圖時同步刪除目標表導致資料丟失。

       -- 將隱含顯示目標表 rename 到新名字，保護資料
       RENAME TABLE <DATABASE>.`.inner_id.<TABLE_UUID>` TO <DATABASE>.<new_target_table_name>;

    4. 刪除 Kafka/RabbitMQ 引擎表及其下遊物化視圖。

       -- 先刪除物化視圖
       DROP TABLE <DATABASE>.<MATERIALIZED_VIEW_NAME>;
       -- 再刪除 Kafka/RabbitMQ 引擎表
       DROP TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

    重要

    請務必儲存好所有記錄的建表語句（DDL）。後續需要在自建叢集和目的地組群上重建這些表。如果執行了 RENAME 操作，重建物化視圖時需要指向已被 RENAME 的目標表。

11. 啟動同步。

    1. 單擊開始同步。

    2. 同步過程中可以單擊右上方的即時查看同步進度。

       同步過程中，支援執行停止、重启與取消迁移操作控制遷移流程，點擊查看操作含義及影響等資訊。

       操作	功能含義	影響	使用情境
       停止	立刻停止遷移資料，遷移剩餘的庫表結構。	資料可能未完全遷移。 在您重新發起遷移之前，必須先清理目的地組群中已遷移的資料，避免出現資料重複的情況。	全部資料移轉完成後，主動停止遷移任務。 期望遷移一部分資料後測試，但是不想停寫自建叢集。
       重啟	在檢查並清理其他庫表、遷移資料、遷移剩餘庫表結構過程中出現異常，客戶根據錯誤資訊處理之後，將重試當前步驟，並正常執行後續步驟。	無	遷移過程出現異常，客戶根據提示資訊解決之後想要斷點重試
       取消遷移	強製取消任務，跳過後續步驟。 重要 取消遷移後，該遷移任務將被鎖定，即不允許修改遷移流程，您可通過上一步、下一步或重繪按鈕查看遷移步驟執行結果。	遷移任務強制終止，目標執行個體庫表結構和配置可能不完整，不可作為業務正常使用。 在您重新發起遷移之前，必須先清理目的地組群中已遷移的資料，避免出現資料重複的情況。	遷移任務影響了自建叢集，希望儘快結束遷移，開啟寫入。

    3. 在自建叢集上，使用之前儲存的 DDL 語句重建 Kafka/RabbitMQ 引擎表及其下遊物化視圖。重建後增量資料將恢複流入並自動同步到目的地組群。

       重要

       如果之前對隱含顯示目標表執行了 RENAME 操作，重建物化視圖時需要使用 TO 子句指向已被 RENAME 的目標表，具體請參見CREATE MATERIALIZED VIEW。

       -- 在自建叢集重建 Kafka/RabbitMQ 引擎表
       CREATE TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME> (...)
       ENGINE = Kafka/RabbitMQ
       SETTINGS ...;
       
       -- 重建物化視圖（指向已 RENAME 的目標表）
       CREATE MATERIALIZED VIEW <DATABASE>.<MATERIALIZED_VIEW_NAME> TO <DATABASE>.<new_target_table_name>
       AS SELECT ... FROM <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

    4. 當執行到迁移数据時，切換到迁移数据頁簽，單擊按鈕查看遷移進度及预估剩余时间。

       點擊查看如何評估遷移是否可以完成。

       遷移是否可以完成取決於遷移速度與自建叢集寫入速度的關係。

       • 遷移速度的測試實驗資料如下：

         資料表的Part平均大小	源端執行個體規格	源端磁碟規格	目標端執行個體規格	目標端儲存介質	叢集節點數	單節點遷移速度	整體遷移速度
         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

       • 判斷目的地組群與自建叢集的寫入速度的關係：

         資料移轉的速度與part大小（在測試實驗中，平均part大小在100MB~10GB的範圍內，能夠保持較快的遷移速度）、執行個體規格、磁碟規格、業務資料特性等要素相關，因此測試實驗資料僅供參考。目的地組群的真實寫入速度需要您通過查看目的地組群的磁碟吞吐來判斷，如何查看磁碟吞吐，請參見查看叢集監控資訊。

         • 目的地組群寫入速度小於自建叢集的寫入速度：遷移失敗率較高，建議您取消遷移任務，使用手動遷移進行資料移轉。

         • 目的地組群寫入速度大於自建叢集的寫入速度：可繼續後續步驟，為提高遷移成功率，建議資料量 /（遷移速度-自建執行個體寫入速度）所得的遷移所需時間小於等於 5天 。

       重要

       • 您需重點監控目標任務的遷移進度，根據预估剩余时间，主動停寫自建叢集並處理Kafka和RabbitMQ引擎表。

       • 目前遷移最長時間閾值統一設定為5天，當持續遷移時間滿5天時，後台將自動取消遷移任務，若您的遷移任務需要更長的遷移時間，請提交工單聯絡支援人員調整閾值。

       評估何時停寫自建叢集並執行切流

       當遷移預估時間少於 10 分鐘或者遷移進度達到 99% 時，執行以下操作完成切流：

       1. 停止業務寫入。在自建叢集上，刪除之前重建的 Kafka/RabbitMQ 引擎表及其下遊物化視圖。

          -- 先刪除物化視圖
          DROP TABLE <DATABASE>.<MATERIALIZED_VIEW_NAME>;
          -- 再刪除 Kafka/RabbitMQ 引擎表
          DROP TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

       2. 等待遷移進度達到 100%，遷移完全結束。

       3. 串連目的地組群，使用之前儲存的 DDL 語句重建 Kafka/RabbitMQ 引擎表及其下遊物化視圖。

          重要

          如果之前對隱含顯示目標表執行了 RENAME 操作，重建物化視圖時需要使用 TO 子句指向已被 RENAME 的目標表。參考 CREATE MATERIALIZED VIEW。

          -- 在目的地組群重建 Kafka/RabbitMQ 引擎表
          CREATE TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME> (...)
          ENGINE = Kafka/RabbitMQ
          SETTINGS ...;
          
          -- 重建物化視圖（指向已 RENAME 的目標表）
          CREATE MATERIALIZED VIEW <DATABASE>.<MATERIALIZED_VIEW_NAME> TO <DATABASE>.<new_target_table_name>
          AS SELECT ... FROM <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

       4. 驗證目的地組群資料管道正常工作，確認資料正常流入。

    5. 當遷移進度為100%，且確認源端執行個體已經進入停寫狀態後，需要您單擊停止按鈕結束遷移流程，執行後續流程。

       單擊迁移数据 Tab 可查看遷移詳情，單擊右上方重新整理表徵圖可更新遷移狀態。

    6. 同步完成後單擊完成。

       重要

       當“啟動同步”步驟完成後，該遷移任務將被鎖定，即不允許修改遷移流程，您可通過上一步、下一步或重繪按鈕查看遷移步驟執行結果。

步驟四：遷移非MergeTree類型表的業務資料

遷移任務中，非MergeTree類型的表僅支援遷移表結構（例如MySQL表）或者不支援遷移（例如Log表）。因此，遷移任務完成後，目的地組群可能存在只有表結構，沒有具體的業務資料的表，您需自主完成業務資料移轉，具體操作如下：

1. 登入自建叢集，查看需要遷移資料的非MergeTree類型的表。

   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. 登入目的地組群，通過remote函數執行資料移轉。