clickhouse-backup 常用命令

主要命令

clickhouse-backup -help

clickhouse-backup <command> [-t, --tables=<db>.<table>] <backup_name>

英文命令	中文说明
tables	 列出要备份的表（排除 skip_tables 配置中的表）
create	创建本地备份（不自动上传）
create_remote	创建备份并自动上传到远程存储（支持增量）
upload	将已存在的本地备份上传到远程存储
list	列出所有备份（本地和远程）
download	从远程存储下载备份到本地
rebase	将增量备份转换为全量备份（合并所需 parts）
rebalance	在本地备份中按当前磁盘布局重新分配数据 parts
restore	从本地备份恢复数据​
restore_remote	下载远程备份并恢复（一步到位）
delete	删除指定备份
default-config	打印默认配置模板
print-config	打印当前配置（合并环境变量）
clean	清理所有磁盘 shadow 文件夹中的数据
clean_remote_broken	清理所有损坏的远程备份
clean_local_broken	清理所有损坏的本地备份
watch	无限循环创建全量+增量备份序列（自动化）
server	启动 API 服务（高级用法）

create 命令

clickhouse-backup create [-t, --tables=<db>.<table>] [--partitions=<partition_names>] [--diff-from-remote=<backup-name>] [-s, --schema] [--rbac] [--configs] [--named-collections] [--skip-check-parts-columns] [--resume] <backup_name>

作用：在本地创建备份（不自动上传到远程）。

选项	中文说明
-t, --tables	只备份匹配的表名模式（支持 * 和 ? 通配符，多个逗号分隔）
--partitions	只备份指定的分区 ID（格式取决于分区键类型）
--diff-from-remote	基于远程备份创建增量备份（注意：这里是 remote，不是 from）
-s, --schema	只备份表结构（DDL），不备份数据
--rbac	备份 RBAC 对象（用户、角色、权限等）
--configs	备份 ClickHouse 配置文件
--named-collections	备份命名集合（Named Collections）
--skip-check-parts-columns	跳过 parts 列类型一致性检查（用于不一致的表）
--resume	启用断点续传（仅对嵌入式备份有效）

create_remote 命令

clickhouse-backup create_remote [-t, --tables=<db>.<table>] [--partitions=<partition_names>] [--diff-from=<local_backup_name>] [--diff-from-remote=<local_backup_name>] [--schema] [--rbac] [--configs] [--named-collections] [--resumable] [--skip-check-parts-columns] <backup_name>

作用：创建备份并自动上传到远程存储（S3、SFTP、GCS 等）。

选项	中文说明
-t, --tables	同上
--partitions	同上
--diff-from 	基于本地备份名创建增量备份并上传
--diff-from-remote	基于远程备份名创建增量备份并上传
-s, --schema	只备份表结构
--rbac	备份 RBAC
--configs	备份配置文件
--named-collections	备份命名集合
--resume, --resumable	启用断点续传（上传时可恢复）
--delete, --delete-source, --delete-local	上传成功后删除本地备份

restore 命令

clickhouse-backup restore  [-t, --tables=<db>.<table>] [-m, --restore-database-mapping=<originDB>:<targetDB>[,<...>]] [--tm, --restore-table-mapping=<originTable>:<targetTable>[,<...>]] [--partitions=<partitions_names>] [-s, --schema] [-d, --data] [--rm, --drop] [-i, --ignore-dependencies] [--rbac] [--configs] [--named-collections] [--resume] [--skip-empty-tables] <backup_name>

作用：从本地备份中恢复表结构和数据。

选项	中文说明	对你的迁移场景的意义
-t, --tables	只恢复匹配的表名模式（支持 * 和 ? 通配符，多个逗号分隔）	可用于只恢复普通 MergeTree 表，避免重复恢复 Replicated 表
-m, --restore-database-mapping	数据库映射：<源库>:<目标库>，可将备份中的库恢复到不同名称的库	如果你想把旧库 db1 恢复到新库 db2 时使用
--tm, --restore-table-mapping	表映射：<源表>:<目标表>，可将备份中的表恢复到不同名称的表	极少使用，迁移时通常保持原名
--partitions	只恢复指定的分区 ID	可按分区粒度恢复，适合大表分批恢复
-s, --schema	只恢复表结构（DDL），不恢复数据	新集群所有节点都需要执行一次
-d, --data	只恢复数据，不恢复表结构	可与 -s 组合，但通常分开执行
--rm, --drop	恢复前删除已存在的表对象	新集群无数据时加不加都可，但建议加上确保干净
-i, --ignore-dependencies	删除表时忽略依赖关系（如物化视图依赖）	如果有视图依赖，删除表可能报错，加上可跳过
--rbac	恢复 RBAC 对象（用户、角色、权限）	如果你用 SQL 管理的用户，需要加上
--configs	恢复 ClickHouse 配置文件	通常不用，配置已手动同步
--named-collections	恢复命名集合	极少使用
--resume	启用断点续传（仅对对象存储磁盘有效）	本地恢复无需关心
--skip-empty-tables	跳过没有数据的空表（只有 schema）	如果你的备份中有空表，加上可避免无谓的恢复
--restore-schema-as-attach	使用 DETACH/ATTACH 代替 DROP/CREATE 恢复 schema	适用于不想重建 ZK 路径的场景
--replicated-copy-to-detached	对 ReplicatedMergeTree 表只复制 parts 到 detached 目录，但不执行 ATTACH PART	用于特殊调试，正常迁移不要加
--rebind-replica-path-if-exists	当原 ZK 路径仍有残留状态但我们的 replica 条目缺失时，重新绑定 replica 路径	如果你在新集群恢复时遇到 ZK 路径冲突，可尝试加上

restore_remote 命令

clickhouse-backup restore_remote [--schema] [--data] [-t, --tables=<db>.<table>] [-m, --restore-database-mapping=<originDB>:<targetDB>[,<...>]] [--tm, --restore-table-mapping=<originTable>:<targetTable>[,<...>]] [--partitions=<partitions_names>] [--rm, --drop] [-i, --ignore-dependencies] [--rbac] [--configs] [--named-collections] [--resumable] [--skip-empty-tables] <backup_name>

作用：从远程存储（S3、SFTP 等）下载备份并直接恢复，相当于 download + restore 一步完成。

选项  中文说明
-t, --tables  只下载并恢复匹配的表名模式（支持 * 和 ? 通配符）
-m, --restore-database-mapping  数据库映射：<源库>:<目标库>
--tm, --restore-table-mapping 表映射：<源表>:<目标表>
--partitions  只恢复指定的分区 ID
-s, --schema  只下载并恢复表结构（DDL）
-d, --data  只下载并恢复数据
--rm, --drop  恢复前删除已存在的表对象
-i, --ignore-dependencies 删除表时忽略依赖关系
--rbac  下载并恢复 RBAC 对象（用户、角色、权限）
--configs 下载并恢复 ClickHouse 配置文件
--named-collections 下载并恢复命名集合
--rbac-only 只恢复 RBAC，跳过数据和 schema
--configs-only  只恢复配置文件
--named-collections-only  只恢复命名集合
--skip-projections  恢复时跳过投影（projection）文件
--resume, --resumable  启用断点续传（下载中断后可继续）
--hardlink-exists-files  对已存在的文件创建硬链接而非重新下载（节省时间）
--restore-schema-as-attach 使用 DETACH/ATTACH 代替 DROP/CREATE 恢复 schema
--skip-empty-tables  跳过没有数据的空表（只有 schema）
--rebind-replica-path-if-exists  当原 ZK 路径仍有残留状态但 replica 条目缺失时，重新绑定 replica 路径

常用命令

# 创建全量备份（本地）
clickhouse-backup create full_backup

# 备份不同库的表
clickhouse-backup create -t "db1.events,db2.analytics" backup_cross_db

# 创建增量备份1（基于已有全量）
clickhouse-backup create_remote --diff-from-remote=full_backup incr_1
clickhouse-backup create_remote --diff-from=full_backup incr_1

# 创建增量备份2
clickhouse-backup create_remote --diff-from-remote=incr_1 incr_2

# 创建增量备份2
clickhouse-backup create_remote --diff-from-remote=incr_2 incr_3


# 创建备份并自动上传到远程
clickhouse-backup create_remote --diff-from=full_backup incr_backup

# 列出所有备份（本地 + 远程）
clickhouse-backup list

# 恢复表结构（DDL）
clickhouse-backup restore full_backup --schema

# 恢复数据
clickhouse-backup restore full_backup --data --rm

# 只恢复特定表的数据
clickhouse-backup restore full_backup --data --rm -t "db1.t1,db1.t2"

# 删除本地备份
clickhouse-backup delete local full_backup