remdb - 嵌入式内存数据库
English Version
remdb是一个轻量级的嵌入式内存数据库，专为资源受限的嵌入式系统设计，支持no_std环境，具有可预测的内存使用和高性能。
主要功能
- 内存表存储：高效的内存表实现，支持插入、删除、查询和遍历操作
- 索引机制：
- 基于哈希的主键索引，提供O(1)的查询性能
- 多种辅助索引类型：Hash、SortedArray、BTree（默认）、TTree
- SortedArray、BTree和TTree索引支持范围查询
- 事务支持：完整的ACID事务支持，包括原子性、一致性、隔离性和持久性
- 内存管理：支持静态内存分配和动态内存分配，固定大小块内存池
- 平台抽象层：支持POSIX和裸机环境
- 编译时配置：使用宏实现表和数据库的编译时配置，优化性能
- 低功耗模式：优化内存使用，减少事务日志写入频率
- 增量快照：只保存版本号变化的记录，减少快照大小和保存时间
- SQL查询支持：支持标准SQL SELECT语句查询内存数据库的数据
- 基于UDP的高可靠数据订阅与发布：支持单播、广播和组播模式，提供基于NACK的重传机制
- 高可用支持：主从复制机制，自动故障检测和切换
- 时序数据库支持：专用的时序表实现，优化时间序列数据存储和查询
技术特点
- 零外部依赖：不依赖任何外部库，支持no_std环境
- 静态内存分配：可预测的内存使用，适合资源受限的嵌入式系统
- 编译时优化：通过宏实现编译时配置，减少运行时开销
- 多平台支持：支持POSIX和裸机环境
- 类型安全：使用Rust的类型系统确保数据安全
- 高效的同步机制：实现了自旋锁同步机制，适合多线程环境
快速开始
安装
将remdb添加到你的Cargo.toml文件中：
[dependencies]
remdb = { path = "./remdb", default-features = false }
Rust语言的三种使用方式
remdb提供了三种主要的Rust语言使用方式，以满足不同场景的需求：
1. 直接定义表数据结构
使用remdb::table!宏直接定义表结构，这是最基础的使用方式，适合简单场景：
#![no_std]
#![feature(alloc_error_handler)]
extern crate alloc;
use core::alloc::Layout;
use remdb::*;
static mut DB_MEMORY: [u8; 65536] = [0u8; 65536];
remdb::table!(
users,
100, primary_key: id,
secondary_index: name,
fields: {
id: i32,
name: str(32), age: i8,
active: bool,
created_at: u64
}
);
remdb::database!(
tables: [users]
);
#[alloc_error_handler]
fn alloc_error_handler(layout: Layout) -> ! {
panic!("Allocation error: {:?}", layout);
}
fn main() {
unsafe {
memory::allocator::init_global_allocator(
DB_MEMORY.as_mut_ptr(),
DB_MEMORY.len()
);
platform::init_platform(platform::posix::get_posix_platform());
let db = init_global_db(
database!(tables: [users]),
&mut [None; 1],
&mut [None; 1],
&mut [None; 1]
).unwrap();
}
}
2. 宏定义MemTable
使用#[derive(MemdbTable)]宏定义表，支持内联DDL和外部DDL文件，提供更灵活的表定义方式：
内联DDL模式
use remdb_macros::MemdbTable;
#[derive(MemdbTable)]
#[memdb_schema(ddl = "CREATE TABLE user (id INTEGER PRIMARY KEY, name TEXT NOT NULL, age INTEGER, active BOOLEAN);
CREATE INDEX idx_user_name ON user USING btree (name);
CREATE INDEX idx_user_age ON user USING hash (age);")]
struct UserTable;
fn main() {
let user = User {
id: 1,
name: "Alice".to_string(),
age: Some(30),
active: Some(true),
};
println!("生成的User结构体: {:?}", user);
println!("用户名: {}", user.name);
println!("年龄: {:?}", user.age);
}
文件模式
use remdb_macros::MemdbTable;
#[derive(MemdbTable)]
#[memdb_schema(file = "./schema.ddl")]
struct MyDatabase;
3. 使用DdlExecutor通过动态DDL创建
使用DdlExecutor trait在运行时动态创建表和索引，适合需要在运行时灵活配置表结构的场景：
use remdb::{RemDb, DdlExecutor, types::{DataType, IndexType}};
use remdb::config::{DbConfig, MemoryAllocator};
use core::ptr::NonNull;
struct SimpleAllocator {
base_ptr: NonNull<u8>,
size: usize,
used: usize,
}
impl SimpleAllocator {
pub const fn new(base_ptr: NonNull<u8>, size: usize) -> Self {
Self {
base_ptr,
size,
used: 0,
}
}
}
impl MemoryAllocator for SimpleAllocator {
fn allocate(&self, size: usize) -> Option<NonNull<u8>> {
let new_used = self.used + size;
if new_used <= self.size {
let ptr = NonNull::new((self.base_ptr.as_ptr() as usize + self.used) as *mut u8)?;
Some(ptr)
} else {
None
}
}
fn deallocate(&self, _ptr: NonNull<u8>, _size: usize) {
}
}
fn main() {
let mut buffer = [0u8; 1024 * 1024]; let base_ptr = NonNull::new(buffer.as_mut_ptr()).unwrap();
let allocator = SimpleAllocator::new(base_ptr, buffer.len());
let config = DbConfig {
tables: &[],
total_memory: buffer.len(),
low_power_mode_supported: false,
low_power_max_records: None,
memory_allocator: &allocator,
};
let mut tables = [None; 8];
let mut primary_indices = [None; 8];
let mut secondary_indices = [None; 8];
let mut db = RemDb::new(
&config,
&mut tables,
&mut primary_indices,
&mut secondary_indices
);
let result = db.create_table(
"users",
&[
("id", DataType::UInt32),
("name", DataType::String),
("age", DataType::UInt8),
("active", DataType::Bool),
],
Some(0) );
let result = db.sql_query(
"CREATE TABLE products (id UINT32 PRIMARY KEY, name STRING, price FLOAT32, in_stock BOOL);"
);
let result = db.create_index(
"users",
"name",
IndexType::BTree
);
}
其他访问方式
C语言接口访问
remdb提供了C语言接口，方便C/C++应用程序使用：
#include "remdb_c.h"
int main() {
remdb_t *db = remdb_init();
remdb_create_table(db, "users", ...);
remdb_insert(db, "users", ...);
remdb_result_t *result = remdb_query(db, "SELECT * FROM users");
remdb_free_result(result);
remdb_close(db);
return 0;
}
JDBC访问
remdb提供了JDBC驱动，允许Java应用程序通过JDBC API访问remdb数据库：
import java.sql.*;
public class RemdbExample {
public static void main(String[] args) {
try {
Class.forName("com.remdb.jdbc.Driver");
String url = "jdbc:remdb://localhost:8080/dbname";
Connection conn = DriverManager.getConnection(url);
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM users");
while (rs.next()) {
System.out.println(rs.getInt("id") + ": " + rs.getString("name"));
}
rs.close();
stmt.close();
conn.close();
} catch (Exception e) {
e.printStackTrace();
}
}
}
基于UDP的高可靠数据订阅与发布
remdb提供了基于UDP的高可靠数据订阅与发布机制，支持单播、广播和组播模式，适合分布式系统中的数据同步：
use std::time::Duration;
use remdb::pubsub::{PubSub, PubSubConfig, UdpMode};
let config = PubSubConfig {
udp_mode: UdpMode::Broadcast,
multicast_addr: None,
port: 5555,
max_topics: 32,
max_subscribers_per_topic: 16,
buffer_size: 4096,
enable_nack: true,
retransmit_timeout: Duration::from_millis(100),
max_retransmits: 3,
heartbeat_interval: Duration::from_secs(10),
frame_pool_size: 128,
};
let mut pubsub = PubSub::new(config).expect("Failed to create PubSub instance");
pubsub.init().expect("Failed to initialize PubSub");
let callback = |topic_id: u16, data: &[u8]| -> bool {
println!("Received data on topic {}: {:?}", topic_id, String::from_utf8_lossy(data));
true
};
let subscription_id = pubsub.subscribe(0, callback).expect("Failed to subscribe");
let msg = "Hello, PubSub!";
pubsub.publish(0, msg.as_bytes()).expect("Failed to publish");
pubsub.unsubscribe(subscription_id).expect("Failed to unsubscribe");
SQL查询示例
remdb支持标准SQL SELECT语句查询内存数据库的数据：
let result = db.sql_query("SELECT * FROM users").unwrap();
println!("{}", result.to_string());
let result = db.sql_query("SELECT name, age FROM users WHERE age > 25 ORDER BY name ASC LIMIT 10").unwrap();
for row in result {
println!("{}: {}", row.get(0), row.get(1));
}
let result = db.sql_query("SELECT * FROM users WHERE active = true ORDER BY created_at DESC").unwrap();
for row in result {
println!("ID: {}, Name: {}, Age: {}, Active: {}",
row.get(0), row.get(1), row.get(2), row.get(3));
}
时序数据库
remdb提供了强大的时序数据库功能，专为时间序列数据的高效存储和查询而设计：
基本使用
use remdb::*;
use remdb::time_series::*;
use std::time::{Duration, SystemTime};
remdb::table!(
sensor_data,
5000, primary_key: id,
secondary_index: timestamp,
fields: {
id: i32,
sensor_id: str(32), sensor_type: str(32), value: f64, timestamp: u64, location: str(64) }
);
remdb::database!(
DB_CONFIG,
tables: [sensor_data]
);
fn main() {
unsafe {
let memory_size = 128 * 1024 * 1024; static mut DB_MEMORY: [u8; 128 * 1024 * 1024] = [0u8; 128 * 1024 * 1024];
memory::allocator::init_global_allocator(
DB_MEMORY.as_mut_ptr(),
DB_MEMORY.len()
).expect("Failed to initialize memory allocator");
platform::init_platform(platform::posix::get_posix_platform());
let db = init_global_db(&DB_CONFIG).unwrap();
let table_mut = db.get_table_mut(0).unwrap();
let start_time = base_time;
let end_time = base_time + 30 * 60000;
let mut result_buffer = [0u8; 160 * 50]; let found_count = table_mut.get_records_in_time_window(
4, start_time,
end_time,
result_buffer.as_mut_ptr(),
50
).unwrap();
match table_mut.aggregate_count(4, start_time, end_time) {
Ok(count) => {
println!("时间范围内记录数: {}", count);
},
Err(e) => println!("统计记录数失败: {:?}", e)
}
}
}
平台支持
POSIX平台
启用POSIX平台支持：
features = ["posix"]
裸机平台
启用裸机平台支持：
features = ["baremetal"]
测试
运行单元测试
cargo test
检查编译
在no_std环境下检查编译：
cargo check --tests --no-default-features
在baremetal环境下检查编译：
cargo check --no-default-features --features=baremetal
在baremetal环境下运行测试
由于测试框架依赖std库，直接运行cargo test在baremetal环境下会失败。但你可以通过以下步骤验证代码在baremetal环境下的正确性：
-
确保代码可以成功编译：
cargo check --no-default-features --features=baremetal
-
对于实际的baremetal硬件测试，你可能需要：
- 使用交叉编译工具链
- 编写针对目标硬件的测试代码
- 配置适当的链接脚本
- 使用烧录工具将可执行文件写入硬件
-
示例交叉编译命令（以ARM Cortex-M为例）：
cargo build --target thumbv7m-none-eabi --no-default-features --features=baremetal
示例
查看examples目录下的示例代码：
basic_usage.rs：基本使用示例，展示表定义、插入、查询和事务操作low_power_mode.rs：低功耗模式示例，展示如何配置和使用低功耗模式incremental_snapshot.rs：增量快照示例，展示如何保存和恢复增量快照sql_query.rs：SQL查询示例，展示如何使用SQL查询内存数据库ddl_example.rs：DDL示例，展示如何使用DDL宏定义表和索引ddl_runtime_example.rs：运行时DDL配置示例，展示如何使用运行时DDL APIpubsub_example.rs：发布/订阅示例，展示如何使用基于UDP的高可靠数据订阅与发布功能time_series.rs：时间序列示例，展示如何处理时间序列数据
项目结构
remdb/
├── src/
│ ├── lib.rs # 主库入口
│ ├── types.rs # 基本数据类型定义
│ ├── config.rs # 编译时配置宏
│ ├── table.rs # 内存表实现
│ ├── index.rs # 索引实现
│ ├── transaction.rs # 事务管理
│ ├── sql/
│ │ ├── mod.rs # SQL查询模块
│ │ ├── query_parser.rs # SQL查询解析器
│ │ ├── query_executor.rs # SQL查询执行器
│ │ └── result_set.rs # 结果集处理
│ ├── memory/
│ │ ├── allocator.rs # 静态内存分配器
│ │ ├── pool.rs # 内存池
│ │ └── mod.rs
│ ├── platform/
│ │ ├── mod.rs # 平台抽象层定义
│ │ ├── posix.rs # POSIX平台实现
│ │ └── baremetal.rs # 裸机平台实现
│ ├── ha/
│ │ ├── mod.rs # 高可用模块入口
│ │ ├── manager.rs # HA管理器实现
│ │ ├── replication.rs # 复制功能实现
│ │ ├── heartbeat.rs # 心跳检测实现
│ │ └── role.rs # 角色管理实现
│ └── pubsub/
│ ├── mod.rs # 发布/订阅模块入口
│ ├── protocol.rs # 协议帧定义与解析
│ ├── udp.rs # 跨平台UDP套接字封装
│ ├── subscriber.rs # 订阅者管理
│ ├── publisher.rs # 发布者管理
│ └── crc32.rs # CRC32校验实现
├── examples/ # 示例代码
├── tests/ # 测试代码
├── Cargo.toml # 项目配置
└── README.md # 项目说明文档
许可证
MIT许可证
贡献
欢迎提交问题和拉取请求！
注意事项
- remdb专为嵌入式系统设计，不适合大规模数据存储
- 在no_std环境下使用时，需要提供适当的内存分配器实现
- 请确保在使用前正确初始化内存分配器和平台抽象层
未来计划
- 支持更多的数据类型
- 优化内存使用
- 提供更多的索引类型
- 增加更多的示例和文档
- 实现更复杂的内存优化算法
- 完善运行时DDL配置API，支持完整的表和索引创建功能
- 支持DROP TABLE和ALTER TABLE语句
- 优化运行时DDL操作的性能
- 支持更复杂的索引配置选项
