容灾和备份

容灾

KaiwuDB 通过 WAL（Write-Ahead Logging，预写式日志）技术，在 VGroup（虚拟组）级别记录时序表的模式变更和数据变更，实现时序数据灾难恢复，确保时序数据的一致性与原子性。

WAL 工作机制

WAL 通过以下三个核心步骤保障数据安全：

预写日志：所有时序数据修改操作在执行前必须先写入 WAL 日志，确保即使系统异常退出也能完整恢复数据
定期检查点（Checkpoint）：系统后台定期将内存中的数据写入磁盘以确保数据安全。默认执行间隔为 1 分钟，可通过 ts.wal.checkpoint_interval 参数调整
故障恢复：系统重启时自动检查上次关闭状态，重放未完成的 WAL 操作并回滚异常事务，保证数据完整性

WAL 文件管理

KaiwuDB 采用双文件轮转策略实现高效的 WAL 文件管理：

current_file：当前活跃的 WAL 写入文件，文件大小根据系统负载和配置参数动态调整
checkpoint_file：执行检查点时由 current_file 转换的临时文件，数据同步完成后自动删除

具体轮转流程如下：

正常运行时，所有 WAL 操作记录在 current_file 中
触发检查点时，当前 current_file 转换为 checkpoint_file
系统立即创建新的 current_file 继续接收 WAL 写入
数据同步完成后，checkpoint_file 被安全删除

WAL 配置

用户可通过以下参数调整 WAL 行为：

参数名称	描述	默认值
`ts.wal.wal_level`	WAL 写入级别，控制数据持久化策略： - `0` (`off`)：关闭 WAL，重启时通过时序存储引擎接口恢复数据状态 - `1` (`sync`)：日志实时写入磁盘并强制持久化，提供最高安全性，性能相对较低 - `2` (`flush`)：日志写入文件系统缓冲区，在性能和安全性间取得平衡 - `3` (`byrl`)：基于 Raft Log 保证数据一致性，WAL 仅负责元数据一致性	`2`
`ts.wal.checkpoint_interval`	检查点执行间隔，控制时序数据从内存持久化到磁盘的频率	`1m`

说明

支持从 2 (flush) 或 1 (sync) 动态切换到 0 (off) / 3 (byrl)，切换过程会产生短暂阻塞，阻塞时长取决于当前检查点的执行时间
实例级别的 DDL 操作不受 ts.wal.wal_level 影响，始终启用 WAL 并实时持久化

示例：

-- 设置 WAL 为同步模式，确保最高数据安全性
SET cluster setting ts.wal.wal_level = 1;

-- 调整检查点间隔为 5 分钟
SET cluster setting ts.wal.checkpoint_interval = '5m';

备份还原

备份

功能概述

备份是指将数据库中的用户数据和元数据复制到指定位置的过程，用于在数据丢失、损坏或系统故障时恢复数据。

KaiwuDB 的备份功能主要用于应对以下场景：

灾难恢复：硬件故障、软件崩溃、自然灾害等意外情况时，根据备份文件快速恢复系统可用性
版本回退：数据库升级、应用升级出错时，根据备份文件回退至稳定版本
数据保护：防止人为误操作导致的数据丢失
系统迁移：将数据从一个环境迁移到另一个环境

备份类型

KaiwuDB 支持对时序数据和关系数据进行不同粒度的备份，具体包括：

引擎级备份：备份整个时序引擎或关系引擎下的所有数据库
数据库级备份：备份指定数据库下的所有表
表级备份：备份指定的单个表

KaiwuDB 支持全量备份和增量备份两种备份策略：

全量备份：备份指定对象的完整数据，适用于首次备份或需要完整数据副本的场景
增量备份：仅备份自上次备份后新增或修改的数据，有效减少备份时间和存储空间占用。

备份文件结构

KaiwuDB 备份文件采用层级目录结构组织，根据备份引擎类型和粒度生成相应的目录结构。

时序数据

时序数据备份采用 引擎 → 数据库 → 表 的三级层级结构。引擎层级包含 BACKUP_TS_PATH 标识文件和 metadata 元数据文件，表目录下存储 storage_metrics_tag 标签和指标数据文件。

全量备份结构：

# 引擎级全量备份
backup_ts/
├── BACKUP_TS_PATH              # 时序备份路径标识文件
└── tsengine/
    ├── metadata                # 引擎元数据
    ├── tsdb1/                  # 数据库1
    │   ├── t1/                 # 表1
    │   │   └── storage_metrics_tag
    │   └── t2/                 # 表2
    │       └── storage_metrics_tag
    └── tsdb2/                  # 数据库2
        └── t3/                 # 表3
            └── storage_metrics_tag

# 数据库级全量备份
backup_tsdb/
├── BACKUP_TS_PATH              # 时序备份路径标识文件
└── tsdb/
    ├── metadata                # 数据库元数据
    ├── t1/
    │   └── storage_metrics_tag
    └── t2/
        └── storage_metrics_tag

# 表级全量备份
backup_t1/
├── BACKUP_TS_PATH              # 时序备份路径标识文件
└── t1/
    ├── metadata                # 表元数据
    └── storage_metrics_tag

增量备份结构（形成备份链，每个文件夹内部结构与全量备份相同）：

# 引擎级增量备份
backup_ts_inc/
├── backup_engine/              # 全量备份
│   ├── BACKUP_TS_PATH
│   └── tsengine/
│       ├── metadata
│       ├── test/
│       │   ├── tb1/
│       │   │   └── storage_metrics_tag
│       │   └── tb2/
│       │       └── storage_metrics_tag
│       └── test2/
│           ├── tb1/
│           │   └── storage_metrics_tag
│           └── tb2/
│               └── storage_metrics_tag
├── backup_engine_inc/          # 第一次增量备份
│   ├── BACKUP_TS_PATH
│   └── tsengine/...
└── backup_engine_inc2/         # 第二次增量备份
    ├── BACKUP_TS_PATH
    └── tsengine/...

# 数据库级增量备份
backup_tsdb_inc/
├── backup_tsdb/                # 全量备份
│   ├── BACKUP_TS_PATH
│   └── tsdb/
│       ├── metadata
│       ├── t1/...
│       └── t2/...
├── backup_tsdb_inc1/           # 第一次增量备份
│   ├── BACKUP_TS_PATH
│   └── tsdb/...
└── backup_tsdb_inc2/           # 第二次增量备份
    ├── BACKUP_TS_PATH
    └── tsdb/...

# 表级增量备份
backup_t1_inc/
├── backup_t1/                  # 全量备份
│   ├── BACKUP_TS_PATH
│   └── t1/
│       ├── metadata
│       └── storage_metrics_tag
├── backup_t1_inc1/             # 第一次增量备份
│   ├── BACKUP_TS_PATH
│   └── t1/...
└── backup_t1_inc2/             # 第二次增量备份
    ├── BACKUP_TS_PATH
    └── t1/...

关系引擎备份文件结构：

关系备份采用扁平结构，包含 BACKUP 元数据文件、路径标识文件和 .sst 数据文件。

全量备份结构：

# 引擎级全量备份
backup_r/
├── BACKUP                      # 元数据文件
├── BACKUP_RELATIONAL_PATH      # 关系备份路径标识文件
├── RELATIONAL_ENGINE           # 引擎标识文件
├── *.sst                       # 数据文件
├── *.sst
└── ...

# 数据库级全量备份
backup_rdb/
├── BACKUP                      # 元数据文件
├── BACKUP_RELATIONAL_PATH      # 关系备份路径标识文件
├── RELATIONAL_DATABASE         # 数据库标识文件
├── *.sst                       # 数据文件
└── ...

# 表级全量备份
backup_tb1/
├── BACKUP                      # 元数据文件
├── BACKUP_RELATIONAL_PATH      # 关系备份路径标识文件
├── RELATIONAL_TABLE            # 表标识文件
└── *.sst                       # 数据文件

增量备份结构（形成备份链，每个文件夹内部结构与全量备份相同）：

# 引擎级增量备份
backup_engine_inc/
├── backup_engine1/            # 全量备份
│   ├── BACKUP
│   ├── BACKUP_RELATIONAL_PATH
│   ├── RELATIONAL_ENGINE
│   └── *.sst
├── backup_engine_inc1/        # 第一次增量备份
│   ├── BACKUP
│   ├── BACKUP_RELATIONAL_PATH
│   ├── RELATIONAL_ENGINE
│   └── *.sst
└── backup_engine_inc2/        # 第二次增量备份
    ├── BACKUP
    ├── BACKUP_RELATIONAL_PATH
    ├── RELATIONAL_ENGINE
    └── *.sst

# 数据库级增量备份
backup_db_inc/
├── backup_db1/                # 全量备份
│   ├── BACKUP
│   ├── BACKUP_RELATIONAL_PATH
│   ├── RELATIONAL_DATABASE
│   └── *.sst
├── backup_db_inc1/            # 第一次增量备份
│   ├── BACKUP
│   ├── BACKUP_RELATIONAL_PATH
│   ├── RELATIONAL_DATABASE
│   └── *.sst
└── backup_db_inc2/            # 第二次增量备份
    ├── BACKUP
    ├── BACKUP_RELATIONAL_PATH
    ├── RELATIONAL_DATABASE
    └── *.sst

# 表级增量备份
backup_tb_inc/
├── backup_tb1/                # 全量备份
│   ├── BACKUP
│   ├── BACKUP_RELATIONAL_PATH
│   ├── RELATIONAL_TABLE
│   └── *.sst
├── backup_tb_inc1/            # 第一次增量备份
│   ├── BACKUP
│   ├── BACKUP_RELATIONAL_PATH
│   ├── RELATIONAL_TABLE
│   └── *.sst
└── backup_tb_inc2/            # 第二次增量备份
    ├── BACKUP
    ├── BACKUP_RELATIONAL_PATH
    ├── RELATIONAL_TABLE
    └── *.sst

备份操作

备份操作通过 BACKUP SQL 语句执行，支持通过作业管理查看、暂停、恢复和取消备份任务。有关 BACKUP SQL 语句的详细信息，参见备份管理。有关作业管理的详细信息，参见作业管理。

功能限制

时序数据备份限制：

历史数据处理：首次备份后写入的历史数据（时间戳早于备份时间）不会被后续增量备份捕获，历史数据的删除操作也无法被增量备份记录
备份时间窗口：备份任务开始后，时间戳晚于备份开始时间的新写入数据不会包含在本次备份中

通用限制：

任务中断处理：暂停全量备份任务后，如需恢复执行，必须先手动清理目标文件夹中已生成的临时文件，否则恢复操作将失败
版本兼容性：备份文件不支持跨大版本还原（如 3.0.x ↔ 3.1），同一大版本内的小版本支持互相还原
备份范围：目前暂不支持权限、系统表、序列等对象

增量备份路径要求：执行增量备份时，必须在命令中按时间顺序指定所有相关的备份路径（包括全量备份和之前的所有增量备份），以确保备份链的完整性。例如：

-- 第一次全量备份
BACKUP TABLE t1 TO "nodelocal://1/t1";

-- 第一次增量备份（需指定全量备份路径）
BACKUP TABLE t1 TO "nodelocal://1/t1_inc1" INCREMENTAL FROM "nodelocal://1/t1";

-- 第二次增量备份（需指定全量备份和第一次增量备份路径）
BACKUP TABLE t1 TO "nodelocal://1/t1_inc2" INCREMENTAL FROM "nodelocal://1/t1", "nodelocal://1/t1_inc1";

还原

功能概述

还原是指将备份文件中的数据和元数据恢复到数据库系统中的过程，使目标对象恢复到备份时的状态。还原功能是数据库灾难恢复和数据保护策略的核心组成部分。

KaiwuDB 的还原功能主要用于以下场景：

灾难恢复：在系统故障、数据损坏或丢失时，通过还原备份数据快速恢复业务连续性
数据迁移：将数据从一个环境迁移到另一个环境，如从测试环境迁移到生产环境
版本回退：当系统升级或变更出现问题时，回退到之前的稳定状态
测试环境搭建：使用生产数据备份快速搭建测试环境
数据分析：为数据分析和报表生成创建独立的数据副本

还原类型

KaiwuDB 支持对时序数据和关系数据进行不同粒度的还原，具体包括：

引擎级还原：还原整个时序引擎或关系引擎下的所有数据库
数据库级还原：还原指定数据库下的所有表
表级还原：还原指定的单个表

KaiwuDB 支持全量还原和增量还原两种还原策略：

全量还原：从单个全量备份文件夹完全恢复目标对象到该备份时间点的状态
增量还原：按时间顺序依次应用多个备份文件夹（全量备份 + 增量备份），恢复到最后一个增量备份的时间点状态

还原操作

还原操作通过 RESTORE SQL 语句执行，支持通过作业管理查看、暂停、恢复和取消还原任务。有关 RESTORE SQL 语句的详细信息，参见还原管理。有关作业管理的详细信息，参见作业管理。

功能限制

通用限制：

任务中断处理：暂停全量还原任务后，如需恢复执行，必须先手动清理目标文件夹中已生成的临时文件，否则恢复操作将失败
版本兼容性：备份文件不支持跨大版本还原（如 3.0.x ↔ 3.1），同一大版本内的小版本支持互相还原
备份链完整性要求：增量还原依赖完整的备份链，缺少任何一个备份文件都会导致还原失败
还原范围：目前不支持权限、系统表、序列等对象

关系引擎还原限制： 执行增量还原时，需要先删除目标对象，然后按备份顺序列举所有备份文件路径。例如：

-- 错误示例： 直接对已存在的表进行增量还原会失败
RESTORE TABLE t1 FROM "nodelocal://1/tb1", "nodelocal://1/tb1_inc";

-- 正确示例： 先删除表，再按备份顺序还原（全量备份 + 增量备份）
DROP TABLE t1;
RESTORE TABLE t1 FROM "nodelocal://1/tb1", "nodelocal://1/tb1_inc";

-- 如果有多个增量备份，需按顺序列出所有备份路径
DROP TABLE t1;
RESTORE TABLE t1 FROM "nodelocal://1/tb1", "nodelocal://1/tb1_inc1", "nodelocal://1/tb1_inc2";

# 容灾和备份

# 容灾

# WAL 工作机制

# WAL 文件管理

# WAL 配置

# 备份还原

# 备份

# 功能概述

# 备份类型

# 备份文件结构

# 备份操作

# 功能限制

# 还原

# 功能概述

# 还原类型

# 还原操作

# 功能限制

容灾和备份

容灾

WAL 工作机制

WAL 文件管理

WAL 配置

备份还原

备份

功能概述

备份类型

备份文件结构

备份操作

功能限制

还原

功能概述

还原类型

还原操作

功能限制