flashdb-rs

这是一个为 FlashDB 编写的安全、高性能的 Rust 绑定库。FlashDB 是一款专注于嵌入式产品的超轻量级数据库。

本库旨在为 Rust 开发者提供一个安全且符合人体工程学的接口，以便在 Rust 项目中（包括 no_std 环境）无缝使用 FlashDB 强大的键值（KV）和时序（TSDB）存储功能，而无需直接编写 unsafe 的 C 代码。

原始库介绍

FlashDB 是一款超轻量级的嵌入式数据库，专注于提供嵌入式产品的数据存储方案。FlashDB 不仅支持传统的基于文件系统的数据库模式，而且结合了 Flash 的特性，具有较强的性能及可靠性，并在保证极低的资源占用前提下，尽可能延长 Flash 使用寿命。

它提供两种数据库模式：

键值数据库 (KVDB)：将数据存储为键值对集合，操作简洁，可扩展性强。
时序数据库 (TSDB)：将数据按照时间顺序存储，适用于日志记录、传感器数据等场景，具有高性能的插入和查询能力。

`flashdb-rs` 的特性

内存安全保证：通过 Rust 的所有权和生命周期管理，将底层的 C 库接口封装在安全的 API 之后。
符合人体工程学的 API：提供 Result 进行错误处理，并为数据访问提供了流式读取器（Reader）和迭代器（Iterator）。
灵活的存储后端：通过 embedded_storage::nor_flash::NorFlash trait 将存储层完全抽象。您可以为任何 Flash 硬件（内部 Flash、QSPI、SPI Nor/NAND 等）实现自己的存储后端。
内置文件系统支持：在 std 环境下，提供开箱即用的文件存储后端（StdStorage），方便在桌面环境进行开发和测试。
no_std 兼容：专为嵌入式和裸机环境设计，只需实现 NorFlash trait 即可在不同平台上运行。
特性控制（Feature Gates）：您可以根据需要仅启用 kvdb 或 tsdb 功能，最大限度地减少固件体积。

快速上手

1. 添加依赖

将以下内容添加到您的 Cargo.toml 中：

[dependencies]
flashdb-rs = { version = "0.2.1", features = ["kvdb", "tsdb", "std", "time64"] }

# 用于桌面测试
anyhow = "1.0"
tempfile = "3.4.0"

2. KVDB (键值数据库) 示例

use flashdb_rs::KVDB;
use std::ffi::CStr;
use tempfile::tempdir;

fn main() -> anyhow::Result<()> {
    // 1. 创建一个临时目录用于存储数据库文件
    let temp_dir = tempdir()?;
    let db_path = temp_dir.path().to_str().unwrap();

    // 2. 使用 `new_file` 创建数据库实例。
    // 它返回一个 `Box` 以确保其内存地址稳定，防止悬空指针。
    let mut db = KVDB::new_file(
        "kv_db",
        db_path,
        4096,       // sec_size
        128 * 1024, // max_size
        None,       // default_kvs
    )?;

    // 3. 设置键值对
    let key = "boot_count"; // 直接使用 &str，更简洁
    let value = b"10";
    db.set(key, value)?;
    println!("Set '{}' = '{}'", key, std::str::from_utf8(value)?);

    // 4. 获取键值对
    if let Some(retrieved_value) = db.get(key)? {
        let value_str = std::str::from_utf8(&retrieved_value)?;
        println!("Get '{}' = '{}'", key, value_str);
        assert_eq!(value_str.as_bytes(), value);
    }

    // 5. 迭代所有键值对
    println!("\nIterating all KVs:");
    for entry in db.iter() {
        // entry 是一个 KVEntry
        if let Some(name) = entry.name() {
             println!("- Found key: '{}', value_len: {}", name, entry.value_len());
        }
    }

    Ok(())
}

3. TSDB (时序数据库) 示例

use flashdb_rs::tsdb::TSDB;
use tempfile::tempdir;

fn main() -> anyhow::Result<()> {
    // 1. 创建临时目录
    let temp_dir = tempdir()?;
    let db_path = temp_dir.path().to_str().unwrap();

    // 2. 使用 `new_file` 创建 TSDB 实例
    let mut tsdb = TSDB::new_file(
        "ts_db",
        db_path,
        4096,       // sec_size
        128 * 1024, // max_size
        1024,       // 单条日志最大长度
    )?;

    // 3. 追加带时间戳的日志
    let timestamp1 = 1686451200; // Unix aarch
    let data1 = b"log entry 1: system started";
    tsdb.append_with_timestamp(timestamp1, data1)?;
    println!("Appended log at timestamp {}", timestamp1);

    let timestamp2 = 1686451260;
    let data2 = b"log entry 2: sensor reading OK";
    tsdb.append_with_timestamp(timestamp2, data2)?;
    println!("Appended log at timestamp {}", timestamp2);

    // 4. 按时间范围迭代日志 (通过回调)
    println!("\nIterating logs from {} to {}:", timestamp1, timestamp2);
    tsdb.tsdb_iter_by_time(timestamp1, timestamp2, |db, tsl| {
        if let Ok(Some(value)) = db.get_value(tsl) {
            println!(
                "  - Time: {}, Data: '{}'",
                tsl.time(), // 使用 .time() 方法
                std::str::from_utf8(&value).unwrap()
            );
        }
        true // 返回 true 继续迭代
    });

    Ok(())
}

在嵌入式 (`no_std`) 环境中使用

修改 Cargo.toml：禁用默认的 std 特性，并根据需要启用 kvdb 或 tsdb。

[dependencies]
flashdb-rs = { version = "0.2.1", default-features = false, features = ["kvdb", "time64"] }

实现 NorFlash Trait：您需要为您目标平台的 Flash 存储器（例如 STM32 的内部 Flash 或 ESP32 的 SPI Flash）实现 embedded_storage::nor_flash::NorFlash trait。

// 伪代码示例
# use embedded_storage::nor_flash::{ErrorType, NorFlash, ReadNorFlash};
# use flashdb_rs::error::Error;
# struct MyHardwareFlash;
# impl ErrorType for MyHardwareFlash { type Error = Error; }
# impl ReadNorFlash for MyHardwareFlash {
#     const READ_SIZE: usize = 1;
#     fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Self::Error> { Ok(()) }
#     fn capacity(&self) -> usize { 64 * 1024 }
# }
# impl NorFlash for MyHardwareFlash {
#     const WRITE_SIZE: usize = 1;
#     const ERASE_SIZE: usize = 4096;
#     fn erase(&mut self, from: u32, to: u32) -> Result<(), Self::Error> { Ok(()) }
#     fn write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Self::Error> { Ok(()) }
# }

// 您需要为您的硬件实现这些 Trait

初始化数据库：在 no_std 环境下，您需要手动创建存储实例，然后创建 KVDB 或 TSDB 实例，最后调用 .init() 方法。

use flashdb_rs::KVDB;
use core::ffi::CStr;
# use embedded_storage::nor_flash::{ErrorType, NorFlash, ReadNorFlash};
# use flashdb_rs::error::Error;
# struct MyHardwareFlash;
# impl ErrorType for MyHardwareFlash { type Error = Error; }
# impl ReadNorFlash for MyHardwareFlash {
#     const READ_SIZE: usize = 1;
#     fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Self::Error> { Ok(()) }
#     fn capacity(&self) -> usize { 64 * 1024 }
# }
# impl NorFlash for MyHardwareFlash {
#     const WRITE_SIZE: usize = 1;
#     const ERASE_SIZE: usize = 4096;
#     fn erase(&mut self, from: u32, to: u32) -> Result<(), Self::Error> { Ok(()) }
#     fn write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Self::Error> { Ok(()) }
# }


fn my_embedded_main() {
    let my_flash_storage = MyHardwareFlash; // 1. 创建您的存储实例

    // 2. 创建数据库实例
    let mut db = KVDB::new(my_flash_storage);

    // 3. 在使用前必须调用 init()
    db.set_name("config").unwrap(); // (可选, 用于日志)
    db.init(None).expect("Failed to initialize db");
    
    // 4. 现在可以正常使用 db
    let key = CStr::from_bytes_with_nul(b"wifi_ssid\0").unwrap();
    db.set(key, b"MyNetwork").unwrap();
}

许可证

本项目采用 Apache-2.0 开源协议。

致谢

感谢 armink 开发了如此出色的 FlashDB C 库。
本项目依赖于原始的 FlashDB 仓库。

flashdb-rs 0.2.1