RocksDB dump 文件格式全解析ROCKDUMP 二进制布局、dump/undump 工具与实战【免费下载链接】rocksdbA library that provides an embeddable, persistent key-value store for fast storage.项目地址: https://gitcode.com/gh_mirrors/ro/rocksdb本篇技术指南以仓库根目录下的 DUMP_FORMAT.md 为核心系统讲解 RocksDB 逻辑备份文件dump 文件的 v1 二进制格式从 8 字节魔数ROCKDUMP、大端版本号到 4 字节小端长度前缀的 chunk 结构、首块 JSON 元信息以及后续成对出现的 key/value 记录。结合 tools/dump/db_dump_tool.cc 的读写实现与 include/rocksdb/db_dump_tool.h 的公共接口读者将掌握 dump 文件的字节级布局、rocksdb_dump/rocksdb_undump命令行工具的使用方法以及如何自行解析或生成该格式。一、dump 格式的定位逻辑备份而非物理备份RocksDB 的正常数据文件SST、WAL、MANIFEST 等内部布局复杂且与具体版本实现强相关直接拷贝数据库目录进行备份通常要求版本兼容。而 dump 格式则是一种与数据库文件格式解耦的逻辑备份它通过迭代器把数据库中的 key/value 对按顺序导出为一个顺序读写的流式文件同时将数据库路径、主机名、创建时间等元信息以 JSON 形式保存在文件头部使得任何平台、任何版本都能按同一套字节布局读出数据。从 tools/dump/db_dump_tool.cc 的实现看导出的数据源自DB::OpenForReadOnly打开数据库后创建的Iterator以SeekToFirst()开始顺序遍历全部键值对而恢复方向则由 DbUndumpTool::Run 逐条db-Put写入新库。因此 dump 文件本质上是一条键值对 元信息的自描述字节流这正是 DUMP_FORMAT.md 所描述的 v1 格式。二、v1 dump 文件字节级布局根据 DUMP_FORMAT.md 的定义v1 格式整体结构如下--------------------------------------------------------------------------------------------------------------------------------------- | 魔数 ROCKDUMP (8 字节) | 版本号 (8 字节, 大端) | 信息块长度 (4 字节, 小端) | 信息块 JSON (长度不定) | key/value 记录序列 | ---------------------------------------------------------------------------------------------------------------------------------------各组成部分详细说明魔数Magic文件以 8 字节 ASCII 标识符ROCKDUMP开头用于快速识别文件是否为 RocksDB dump 文件。在 tools/dump/db_dump_tool.cc 中定义为static const char* magicstr ROCKDUMP;实际写入时构造Slice(magicstr, 8)精确追加 8 字节。版本号Version魔数之后是 8 字节**大端序big-endian**的格式版本号v1 固定为0x00000001。对应源码中的static const char versionstr[8] {0, 0, 0, 0, 0, 0, 0, 1};tools/dump/db_dump_tool.cc。大端序意味着多字节整数的最高有效字节在前读取端只需按字节比对即可校验版本。Chunk 化长度前缀从第三部分开始文件由若干长度前缀 数据的 chunk 组成。每个 chunk 先写入4 字节小端序little-endian的长度值uint32_t随后紧跟该长度的原始字节。这一小端长度 数据的模式贯穿信息块与所有键值对。写入端使用 util/coding.h 中的EncodeFixed32将uint32_t编码为固定 4 字节小端读取端用DecodeFixed32还原。首个 chunk 为 JSON 信息块第一个 chunk 的数据是描述 dump 创建信息的 JSON 字符串具体键如下键名含义database-path被 dump 数据库的路径写入时会通过Env::GetAbsolutePath转换为绝对路径hostname创建 dump 时所在机器的主机名来自Env::GetHostNamecreation-time创建 dump 的 Unix 秒级时间戳来自Env::GetCurrentTime对应实现见 tools/dump/db_dump_tool.cc生成出的 JSON 形如{ database-path: /data/db, hostname: build-server-1, creation-time: 1720000000 }键值对序列信息块之后文件包含任意数量的键值对记录每条记录是两个连续 chunk先写入 4 字节小端 key 长度 key 原始字节再写入 4 字节小端 value 长度 value 原始字节。写入端按it-key()/it-value()的Slice大小动态生成长度前缀tools/dump/db_dump_tool.cc。文件到达末尾即自然结束没有显式的结束标记。一个完整文件的十六进制示意以 key 为hello、value 为world的极简库为例dump 文件字节流大致为52 4F 43 4B 44 55 4D 50 # ROCKDUMP 魔数 00 00 00 00 00 00 00 01 # 大端版本号 1 XX XX XX XX # 信息块长度小端4 字节 { database-path: ... } # JSON 信息块 05 00 00 00 # key 长度 5小端 68 65 6C 6C 6F # hello 05 00 00 00 # value 长度 5小端 77 6F 72 6C 64 # world注意观察两种整数序并存的设计版本号使用大端而所有 chunk 长度前缀使用小端。解析器必须区分对待混用任一端的字节序都会导致数据错位。三、写入与读取的源码实现印证3.1 写入端DbDumpTool::Run导出流程位于 tools/dump/db_dump_tool.cc关键步骤为以只读方式打开源库DB::OpenForReadOnly(options, dump_options.db_path, db)并强制create_if_missing false防止误建新库通过Env::Default()的NewWritableFile创建 dump 输出文件依次追加魔数、版本号、长度前缀 JSON 信息块创建Iterator顺序遍历对每个有效键值对分别追加 key 长度、key、value 长度、value遍历结束后检查it-status()确认迭代过程无错误。值得注意的细节是anonymous选项当DumpOptions::anonymous为真时见 include/rocksdb/db_dump_tool.hJSON 信息块被替换为{}从而隐去数据库路径、主机名与创建时间适用于需要脱敏导出的场景。3.2 读取端DbUndumpTool::Run导入流程位于 tools/dump/db_dump_tool.cc关键校验与步骤使用NewSequentialFile打开 dump 文件先读取 8 字节与magicstr比对不匹配则报is not a recognizable dump file再读取 8 字节与versionstr比对不匹配则报version not recognized读取 4 字节信息块长度Skip(infosize)跳过整个 JSON 信息块读取端不解析 JSON 内容仅跳过以create_if_missing true打开目标库随后循环读取[key 长度][key][value 长度][value]逐条db-Put写入当读到文件末尾Read返回不足 4 字节时正常结束循环视作文件结束。读取端还包含一个实用的内存优化last_keysize/last_valsize从初始值64 字节 key、1 MB value开始遇更大记录时按 2 倍扩容重新分配缓冲区tools/dump/db_dump_tool.cc避免对大 key/value 频繁 realloc。3.3 公共接口工具类的公共接口定义在 include/rocksdb/db_dump_tool.hDumpOptionsdb_path源库路径、dump_locationdump 输出文件路径、anonymous是否隐藏头部元信息DbDumpTool::Run(DumpOptions, Options)执行导出UndumpOptionsdb_path目标库路径、dump_locationdump 文件路径、compact_db导入完成后是否执行CompactRange压缩全库DbUndumpTool::Run(UndumpOptions, Options)执行导入。其中compact_db在 tools/dump/db_dump_tool.cc 中通过db-CompactRange(CompactRangeOptions(), nullptr, nullptr)实现可在加载后立即整理 LSM 结构优化后续读性能。四、命令行工具使用实战仓库提供两个基于 gflags 的命令行可执行文件tools/dump/rocksdb_dump.cc导出工具参数为--db_path、--dump_location、--anonymous、--db_optionstools/dump/rocksdb_undump.cc导入工具参数为--dump_location、--db_path、--compact、--db_options。两者均要求 gflags 支持util/gflags_compat.h未安装 gflags 时程序会提示Please install gflags to run rocksdb tools。若--db_path或--dump_location为空工具会直接报错退出。4.1 导出数据库为 dump 文件./rocksdb_dump --db_path/path/to/source/db --dump_location/tmp/backup.dmp导出过程以只读方式打开源库不影响线上读写。若希望脱敏不记录路径、主机名与时间./rocksdb_dump --anonymous --db_path/path/to/source/db --dump_location/tmp/backup.dmp如需以特定选项打开源库可追加--db_options例如./rocksdb_dump --db_path/path/to/source/db \ --dump_location/tmp/backup.dmp \ --db_optionsmax_open_files5000;write_buffer_size67108864--db_options使用GetOptionsFromString解析见 tools/dump/rocksdb_dump.cc格式为key1value1;key2value2适用于打开需要特殊配置如不同压缩、不同块缓存的数据库。4.2 从 dump 文件恢复数据库./rocksdb_undump --dump_location/tmp/backup.dmp --db_path/path/to/new/db导入时会自动创建目标库create_if_missing true。恢复后立即执行全库压缩./rocksdb_undump --dump_location/tmp/backup.dmp \ --db_path/path/to/new/db --compact同样支持--db_options指定目标库的打开选项。4.3 编译与测试验证两个工具在构建系统中分别注册于 src.mk 与 tools/CMakeLists.txt。Makefile 提供了对应目标make rocksdb_dump rocksdb_undump仓库自带回归测试脚本 tools/rocksdb_dump_test.sh其验证思路与格式完全对应./rocksdb_undump --dump_locationtools/sample-dump.dmp --db_path$TESTDIR/db ./rocksdb_dump --anonymous --db_path$TESTDIR/db --dump_location$TESTDIR/dump cmp tools/sample-dump.dmp $TESTDIR/dump流程为先用仓库内的样例 dump 文件tools/sample-dump.dmp还原出一个库再以--anonymous重新导出最后cmp逐字节比对验证还原→再导出后内容完全一致由于 anonymous 模式信息块固定为{}两次文件字节完全相同。执行入口为make rocksdb_dump_test见 Makefile。五、格式要点总结与兼容性注意事项整数字节序不对称版本号为 8 字节大端所有 chunk 长度前缀信息块长度、key 长度、value 长度均为 4 字节小端长度前缀上限长度字段为uint32_t单个 key 或 value 不得超过 4 GiB实际使用中远小于此无结束标记文件以键值对序列自然收尾解析器依据读不到完整 4 字节长度判定 EOF信息块为纯元数据读取端只按长度跳过 JSON 而不解析即使 JSON 内容为空anonymous模式也不影响数据加载迭代序即存储序导出顺序为数据库迭代器的顺序按键有序因此 dump 天然保序但该顺序对恢复结果无影响恢复是逐条 Put版本演进魔数与版本号双校验机制为未来格式演进留有余地新版本可更新versionstr并保持向后兼容读取。六、自行实现解析器的核对清单若需要脱离 RocksDB 工具自行读取 dump 文件如导入其他存储系统按以下步骤校验即可读取前 8 字节必须等于 ASCIIROCKDUMP读取后 8 字节当前仅接受大端值0x00000001读取 4 字节小端n1随后跳过n1字节的 JSON 元信息循环读取 4 字节小端kl读取kl字节 key再读取 4 字节小端vl读取vl字节 value任一读取不足预期字节数即视为文件结束或损坏。遵循上述布局即可完整还原 dump 内容而生成 dump 时只需按魔数 版本号 信息块 键值对序列的顺序写出即可被rocksdb_undump与DbUndumpTool正常识别和加载实现跨工具的数据互通。【免费下载链接】rocksdbA library that provides an embeddable, persistent key-value store for fast storage.项目地址: https://gitcode.com/gh_mirrors/ro/rocksdb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考