# mitedb **Repository Path**: liukeying011/mitedb ## Basic Information - **Project Name**: mitedb - **Description**: # MiteDB —— 嵌入式时序数据库 MiteDB ( libmite )是一个用 C99 编写的嵌入式时序数据库,以进程内链接库的形式运行(形态类似 SQLite),专为嵌入式 Linux 设备(网关、采集器、边缘计算盒子)设计。 核心特点: - 零依赖 :仅依赖 libc + pthread,无服务进程、无网络端口,静态链接后体积小巧 - 时序优先 :持续追加写入、按时间范围查询、聚合 - **Primary Language**: C - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 0 - **Created**: 2026-08-11 - **Last Updated**: 2026-11-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MiteDB > 面向嵌入式 Linux 的进程内时序数据库(In-Process Time-Series Database) MiteDB(`libmite`,mite 意为"极小的生物")是一个以 C 语言实现、进程内链接的时序数据库,形态类似 SQLite——应用直接调用 C API,无独立服务进程、无网络端口。面向嵌入式设备(网关、采集器、边缘计算盒子)设计:持续追加写入、按时间范围查询、聚合降采样、按保留期自动淘汰旧数据。 - **零依赖**:仅依赖 libc + pthread - **崩溃安全**:`SYNC/FULL` 模式下掉电不丢已确认写入,故障注入验证 - **内存有界**:写入、查询路径不做无界动态分配,所有内存可配置上限 - **平台**:嵌入式 Linux(arm / arm64 / x86 / x86_64),32 位平台原生支持 >2GB 大文件 ## 特性 | 领域 | 能力 | |---|---| | 写入 | 批量 Inserter、Group Commit(合并 fsync)、多语句事务、乱序窗口 | | 存储 | LSM 风格:WAL + 不可变列式 chunk;delta / Gorilla 列编码;LRU 解码缓存 | | 查询 | 流式游标、SQL 子集、超级表(STable)+ 标签谓词下推、物化排序 | | 聚合 | count/sum/min/max/avg/first/last、分桶降采样、GROUP BY、窗口函数 | | 时序分析 | 重采样与插值(prev/next/linear/const)、滑动窗口聚合 | | 运维 | 保留期自动清理、增量数据同步(断点续传)、WAL 归档、运行时统计 | | 崩溃恢复 | WAL 重放 + 撕裂截断,断电/杀进程自动恢复(已通过 LD_PRELOAD 故障注入) | ## 架构速览 ``` 应用进程 ├─ mite_* C API(线程安全:单写者多读者,写者优先 rwlock) ├─ 写入路径:Inserter/Txn → memtable → WAL → flush → 不可变 chunk(列式编码) └─ 查询路径:SQL/游标/聚合 → 索引剪枝 + 列块读取 + 解码 LRU 缓存 ``` - 存储格式自包含:MANIFEST(schema/元数据)+ 列式 chunk + WAL,全部固定小端、跨架构可迁移 - 数据文件一经 fsync 不可变,配合解码列 LRU 与 fd 缓存,热区间反复查询零冗余 IO - 支持从几 MB 到数 GB 的规模,通过 `mite_opts_t` 适配 ## 平台支持 | 平台 | 状态 | |---|---| | Linux armv7l(32 位,如 RK3506) | ✅ 实测(含 >2GB 大文件) | | Linux arm64 / x86 / x86_64 | ✅ 支持 | | 字节序 | 固定小端编解码,大端 CPU 亦可正确读写同一文件格式 | | 32 位大文件 | `O_LARGEFILE` + 显式 64 位文件 API(pread64/ftruncate64 等),无需 `_FILE_OFFSET_BITS` 宏 | | 其他 OS | 目前仅 Linux;macOS/Windows 需补充移植层(`src/os_linux.c` 为唯一 OS 接口) | ## 快速开始 > **数据库目录扩展名**:MiteDB 数据库为目录存储,`mite_open` 会自动为目录名 > 补全统一后缀 `.mite`(`/tmp/db1` → 实际 `/tmp/db1.mite`;已带后缀或尾部 > 斜杠均正确处理),便于识别与脚本化。设置环境变量 `MITE_NO_DIR_SUFFIX=1` > 可禁用自动补全(测试与特殊部署用逃生舱)。 ### 构建 ```bash cmake -S . -B build -DCMAKE_BUILD_TYPE=Release cmake --build build -j$(nproc) ctest --test-dir build # 运行全部测试 ``` 无 cmake 的嵌入式环境可直接用 gcc 手动构建: ```bash gcc -O3 -DNDEBUG -std=gnu99 -fPIC -Wall -Isrc -Iinclude -c src/*.c ar rcs libmitedb.a *.o ``` ### 最小示例 ```c #include #include static int print_row(void *ud, int ncols, const char **names, const mite_value_t *v) { for (int i = 0; i < ncols; i++) printf("%s=%lld ", names[i], (long long)v[i].u.i64); printf("\n"); return 0; } int main(void) { mite_t *db = mite_open("/tmp/db1", NULL); /* NULL = 默认配置;实际目录为 /tmp/db1.mite */ mite_sql(db, "CREATE TABLE sensor (v INT64)", NULL, NULL); mite_inserter_t *it = mite_inserter(db, "sensor"); mite_inserter_add(it, 1000, (mite_value_t[]){ mite_v_i64(42) }); mite_inserter_add(it, 2000, (mite_value_t[]){ mite_v_i64(43) }); mite_inserter_commit(it); /* 落 WAL */ mite_inserter_free(it); mite_sync(db); /* flush + fsync */ mite_sql(db, "SELECT v FROM sensor WHERE ts > 0", print_row, NULL); mite_close(db); return 0; } ``` 编译:`cc demo.c -Iinclude -Lbuild -lmitedb -lpthread -o demo` ### 示例程序 ```bash cmake --build build --target mitedb_cli 2>/dev/null # 或直接编译: cc example/01_basic.c -Iinclude -Lbuild -lmitedb -lpthread -o 01_basic && ./01_basic ``` - [example/01_basic.c](example/01_basic.c) —— 基础读写流程(建表 / 批量写 / 范围查询 / 删除 / 持久化) - [example/02_stable.c](example/02_stable.c) —— 超级表 / 子表(点位建模)与标签查询下推 - [example/03_txn_sql.c](example/03_txn_sql.c) —— 多语句事务与 SQL 执行 - [example/04_stmt.c](example/04_stmt.c) —— 预处理语句(`?` 参数绑定、结果集游标) ## 核心 API 概览 | 类别 | 函数 | |---|---| | 打开/关闭 | `mite_open` / `mite_close` / `mite_sync` / `mite_errmsg` | | Schema | `mite_create_table` / `mite_drop_table` / `mite_create_stable` / `mite_create_subtable` | | 写入 | `mite_inserter` + `add/commit/free`;`mite_txn_begin/add/commit/rollback` | | 查询 | `mite_query` + 流式游标;`mite_sql`(回调);`mite_stmt_prepare/step/column`(绑定参数) | | 聚合 | `mite_agg_query` / `mite_agg_query_stable(_multi/_groups)` | | 时序分析 | `mite_resample_stable` / `mite_fill_stable` / `mite_roll_stable` / `mite_stable_query_window` | | 删除/保留 | `mite_delete_range` / `mite_set_retention` / `mite_get_retention` | | 同步 | `mite_sync_export_begin/next/ack` / `mite_sync_import` / `mite_sync_checkpoint_*` | | 运维 | `mite_db_stats` / `mite_cache_stats` / `mite_archive_list/remove/cleanup` | **线程安全**:同一句柄可多线程并发使用(单写者多读者);回调/游标迭代期间持读锁,回调内禁止再调用库 API;Inserter 与游标为线程私有。 ## 关键配置(`mite_opts_t`,均为 0 取默认) | 字段 | 默认 | 说明 | |---|---|---| | `memtable_cap` | 16MB | 容量触发 flush | | `chunk_duration` | 1h | 时间跨度触发 flush | | `flush_interval` | 60s | 时间触发 flush | | `cache_cap` | 16MB | 解码列 LRU 总字节上限 | | `max_out_of_order` | ±1h | 乱序写入窗口 | | `retention` | 关闭 | 保留期自动清理 | | `fsync_mode` | SYNC | OFF=高性能(可丢最近写入)/ SYNC / FULL=最严格 | | `group_commit` | 开启 | 合并提交 fsync | | `threads` | 0 | 0=同步模式,>0 启动后台维护线程 | ## 实测表现(RK3506,armv7l 32 位,500MB 内存) - **I/O 优化**:列块读取合并后 `pread64` 调用减少 **19.4%**(2904 → 2340,多次一致复现) - **稳定性**:30 轮循环查询 VmRSS 稳定在 18–20MB,无内存泄漏;数据完整性逐轮校验 - **崩溃恢复**:模拟断电(abort)后重开,写入数据完整恢复、零丢失 - **大文件**:>2GB 稀疏文件创建 / 深处读写 / 截断全部正确(32 位平台原生支持) ## 测试 - 27 个单元/集成测试(`ctest`):写入、查询、聚合、超级表、事务、并发、同步、归档、SQL、窗口等 - 故障注入([tests/powerloss](tests/powerloss)):LD_PRELOAD 影子层模拟"未 fsync 掉电"与"fsync 中途撕裂",20+ 轮随机掉电点全部精确恢复 - 详细设计见 [docs/DESIGN.md](docs/DESIGN.md),性能/稳定性报告见 [docs/](docs/) ## 目录结构 ``` ├── include/mite.h # 公共 API(含详细语义注释) ├── src/ # 核心引擎(WAL / memtable / chunk / 编码 / SQL / 聚合 / 同步…) ├── example/ # 4 个示例程序 ├── tests/ # 单元与集成测试 + 断电故障注入 ├── tools/ # CLI 与写入压测工具 └── docs/ # 设计文档与测试报告 ``` ## 许可证 [MIT](LICENSE)