全部產品
Search

搜尋本產品

    ApsaraDB for ClickHouse：使用BACKUP和RESTORE命令實現資料備份恢複

    文件中心

    ApsaraDB for ClickHouse：使用BACKUP和RESTORE命令實現資料備份恢複

    更新時間：Dec 18, 2025

    如果您需要將ClickHouse中的資料備份至OSS實現低成本的長期歸檔，或者計劃將自建ClickHouse遷移至雲資料庫ClickHouse中，可以使用BACKUP和RESTORE命令。該命令是ClickHouse內建的SQL命令，用於對資料庫、表等對象進行備份和恢複。本文介紹BACKUP和RESTORE命令的文法與使用樣本。

    注意事項

    • 由於庫表引擎不相容，不支援在社區相容版和企業版之間進行資料備份與恢複。

    • 備份恢複執行期間，叢集的CPU使用率會有所升高，可通過調整相關參數（如backup_threads、restore_threads）限制資源消耗；記憶體使用量率基本無影響。

    前提條件

    文法

     BACKUP|RESTORE
  TABLE [db.]table_name [AS [db.]table_name_in_backup]
    [PARTITION[S] partition_expr [,...]] |
  DICTIONARY [db.]dictionary_name [AS [db.]name_in_backup] |
  DATABASE database_name [AS database_name_in_backup]
    [EXCEPT TABLES ...] |
  TEMPORARY TABLE table_name [AS table_name_in_backup] |
  VIEW view_name [AS view_name_in_backup] |
  ALL [EXCEPT {TABLES|DATABASES}...] } [,...]
  [ON CLUSTER 'cluster_name']
  TO|FROM File('<path>/<filename>') | Disk('<disk_name>', '<path>/') | S3('<S3 endpoint>/<path>', '<Access key ID>', '<Access key Secret>')
  [SETTINGS base_backup = File('<path>/<filename>') | Disk(...) | S3('<S3 endpoint>/<path>', '<Access key ID>', '<Access key Secret>')]

    社區相容版

    BACKUP和RESTORE命令支援執行個體、資料庫、表層級的資料備份恢複。本節以表為例，介紹資料上傳的使用方法。

    備份資料至OSS

    直接上傳至OSS

    BACKUP TABLE default.data ON CLUSTER default TO S3('https://<yourBucketName>.<yourEndpoint>/data/', 'yourAccessKeyID', 'yourAccessKeySecret')

    備份到本地再上傳至OSS

    重要

    雲資料庫ClickHouse不支援備份到本地。

    1. 配置備份。

      添加檔案/etc/clickhouse-server/config.d/backup_disk.xml，並指定備份目標。

      樣本如下，在<storage_configuration>標籤內，自訂磁碟名稱為backups，並指定了磁碟對應的實體路徑為/backups/；在<backups>標籤內，表示只能使用名為 backups 的磁碟，並且最終檔案路徑必須在 /backups/ 目錄內。

      <clickhouse>
    <storage_configuration>
        <disks>
            <backups>
                <type>local</type>
                <path>/backups/</path>
            </backups>
        </disks>
    </storage_configuration>
    <backups>
        <allowed_disk>backups</allowed_disk>
        <allowed_path>/backups/</allowed_path>
    </backups>
</clickhouse>

    2. 備份資料到本地。

      BACKUP TABLE test.table TO Disk('backups', 'data_1.zip')

    3. 使用ossutil上傳至OSS。

      ossutil cp data_1.zip oss://<yourBucketName>/data/data_1.zip -i <yourAccessKeyID> -k <yourAccessKeySecret> -e <yourEndpoint>

    從OSS恢複資料

    -- 從zip檔案恢複到單個節點
RESTORE TABLE default.data FROM S3('https://<yourBucketName>.<yourEndpoint>/data/data_1.zip', 'yourAccessKeyID', 'yourAccessKeySecret')
-- 從目錄恢複到所有節點
RESTORE TABLE default.data ON CLUSTER default FROM S3('https://<yourBucketName>.<yourEndpoint>/data/', 'yourAccessKeyID', 'yourAccessKeySecret')

    企業版

    備份資料至OSS

    BACKUP TABLE default.data TO S3('https://<yourBucketName>.<yourEndpoint>/data/data_1.zip', 'yourAccessKeyID', 'yourAccessKeySecret')

    從OSS恢複資料

    RESTORE TABLE default.data FROM S3('https://<yourBucketName>.<yourEndpoint>/data/data_1.zip', 'yourAccessKeyID', 'yourAccessKeySecret')

    效能調優參數

    查看方式

    -- 使用者級參數
SELECT * FROM system.settings WHERE name LIKE '%backup%' OR name LIKE '%restore%';
-- server級參數
SELECT * FROM system.server_settings WHERE name LIKE '%backup%' OR name LIKE '%restore%';

    參數說明

    • backup

      參數類型

      參數名

      說明

      server級參數

      backup_threads

      需重啟，限制backup的線程數量。預設最大線程數16。

      max_backup_bandwidth_for_server

      需重啟，限制單個server內所有backup的頻寬。

      max_backups_io_thread_pool_size

      需重啟，限制backup的IO操作線程數量。

      max_backups_io_thread_pool_free_size

      需重啟，限制backup的IO操作線程池內Idle線程數量。

      user級參數

      max_backup_bandwidth

      限制單個backup任務的頻寬。

    • restore

      參數類型

      參數名

      說明

      server級參數

      restore_threads

      需重啟，限制restore的線程數量。預設最大線程數16。

    常見問題

    如何解決報錯“Not found backup engine S3”？

    低版本執行個體不支援備份資料到OSS，會出現類似“Not found backup engine S3”的異常資訊。建議升級執行個體版本到23.8及以上。如果是自建ClickHouse，也可以通過備份至本地再上傳OSS。

    如何解決報錯“Using archives with backups on clusters is disabled”？

    多節點執行個體的叢集備份不支援ZIP歸檔格式。S3路徑可以使用目錄，樣本如下。

    BACKUP TABLE default.data ON CLUSTER default TO S3('https://<yourBucketName>.<yourEndpoint>/data/', 'yourAccessKeyID', 'yourAccessKeySecret')

    執行BACKUP命令後，客戶clickhouse-client和clickhouse中斷連線怎麼辦？

    備份任務後台運行，串連斷開並不影響正常備份。可以通過select * from system.backups;查看進度。

    如果想要非同步執行，可以在BACKUP執行後加ASYNC。

    BACKUP TABLE default.data ON CLUSTER default TO S3('https://<yourBucketName>.<yourEndpoint>/data/data_1.zip', 'yourAccessKeyID', 'yourAccessKeySecret') ASYNC;

    BACKUP和RESTORE命令速度能達到多少？

    整條鏈路包括CPU、磁碟吞吐、網路吞吐、OSS頻寬，速度取決於整條鏈路的其中一個鏈路的瓶頸。

    • 雲資料庫ClickHouse：您可以通過垂直升配叢集規格的方式提升CPU、磁碟吞吐和網路吞吐。

    • OSS側：請參見使用限制及效能指標。

    雲資料庫ClickHouse如何?逐個節點備份恢複？

    1. 查詢節點IP。

      SELECT * FROM system.clusters;

    2. 通過clickhouse-client直連執行個體節點，設定不強制ON CLUSTER default。

      說明

      以下參數設定僅適用於阿里雲雲資料庫ClickHouse，自建ClickHouse無需設定。

      set enforce_on_cluster_default_for_ddl = 0;

    3. 執行BACKUP命令。

      BACKUP TABLE default.data TO S3('https://<yourBucketName>.<yourEndpoint>/data/data_1.zip', 'yourAccessKeyID', 'yourAccessKeySecret')

    4. 執行RESTORE命令。

      RESTORE TABLE default.data FROM S3('https://<yourBucketName>.<yourEndpoint>/data/data_1.zip', 'yourAccessKeyID', 'yourAccessKeySecret')