RustMinidb

轻量级嵌入式关系型数据库 · 原生 REST API · 单文件存储 · 多数据库支持

RustMinidb 是一个使用 Rust 编写的轻量级嵌入式关系型数据库，基于 redb 存储引擎（ACID、MVCC、单文件）。原生内置 HTTP REST API 服务器，支持多数据库同时打开、文件监听自动重载，适合物联网、边缘计算和嵌入式场景。

特性

⚡ 核心能力

🆕 v0.2.0 新特性

🌐 REST API 服务器

公开端点（免认证）：

需认证端点（Bearer Token）：

🛠️ 实用工具

• 交互式 Shell — 类似 sqlite3 的命令行控制台，支持多数据库切换
• SQL 导出迁移 — 支持 Standard / MySQL / PostgreSQL / SQLite 四种方言
• 监控仪表盘 — 运行时 QPS、延迟、连接数等指标
• 彩色 Banner — 增强型启动欢迎画面（ANSI 彩色 "R" Logo）
• 请求追踪 — UUID 级请求链路追踪
• 🔒 API 认证 — Bearer Token 保护全部数据接口

使用场景

快速开始

安装

方式一：下载预编译二进制

从 Releases 下载对应平台的二进制文件。

方式二：从源码编译

# 确保已安装 Rust 工具链（https://rustup.rs）

cargo install rustminidb

方式三：作为依赖库（Cargo）

[dependencies]

rustminidb = "0.2"

基本使用

🔹 命令行模式

# 初始化数据库

rustminidb init --db mydata.db


# 执行单条 SQL

rustminidb exec --db mydata.db "CREATE TABLE sensors (id INT PRIMARY KEY, value FLOAT)"

rustminidb exec --db mydata.db "INSERT INTO sensors VALUES (1, 25.6)"

rustminidb exec --db mydata.db "SELECT * FROM sensors"


# 启动交互式 Shell

rustminidb shell --db mydata.db


# 启动 HTTP 服务器（无认证，仅限开发环境）

rustminidb serve --host 0.0.0.0 --port 8080 --db mydata.db


# 启动 HTTP 服务器（推荐：开启 Bearer Token 认证）

rustminidb serve --host 0.0.0.0 --port 8080 --db mydata.db --api-token "your-secret-token"


# 也可通过环境变量设置 Token（避免命令行泄露）

set RUSTMINIDB_API_TOKEN=your-secret-token

rustminidb serve --host 0.0.0.0 --port 8080 --db mydata.db


# ── v0.2.0 新特性 ──────────────────────────────────


# 多数据库同时打开（支持任意数量）

rustminidb serve --db data1.db --db data2.db --db data3.db


# 多数据库 Shell

rustminidb shell --db orders.db --db inventory.db


# 文件监听自动重载（数据库文件变化时自动刷新）

rustminidb serve --db mydata.db --watch


# 多数据库 + 文件监听组合

rustminidb serve --db data1.db --db data2.db --db data3.db --watch


# ──────────────────────────────────────────────────


# 导出数据库为 SQL

rustminidb export --db mydata.db --output backup.sql


# 查看版本

rustminidb version

🔹 交互式 Shell 命令

在 shell 模式下可使用以下内置命令：

🔹 REST API 使用

# 启动服务器（推荐开启认证）

rustminidb serve --host 0.0.0.0 --port 8080 --db mydata.db --api-token "my-secret-token"


# 执行 SQL（需在请求头中携带 Token）

curl -X POST http://localhost:8080/v1/query \

  -H "Content-Type: application/json" \

  -H "Authorization: Bearer my-secret-token" \

  -d '{"sql": "SELECT * FROM sensors"}'


# 健康检查（公开端点，无需 Token）

curl http://localhost:8080/v1/health


# 查看监控指标（需 Token）

curl -H "Authorization: Bearer my-secret-token" http://localhost:8080/v1/metrics


# 导出数据库（需 Token）

curl -H "Authorization: Bearer my-secret-token" http://localhost:8080/v1/export


# 列出所有数据库（需 Token）

curl -H "Authorization: Bearer my-secret-token" http://localhost:8080/v1/databases


# 切换数据库（需 Token）

curl -X POST http://localhost:8080/v1/databases/switch \

  -H "Content-Type: application/json" \

  -H "Authorization: Bearer my-secret-token" \

  -d '{"name": "data2.db"}'

🔹 嵌入式 Rust 库

use rustminidb::Database;

// 打开数据库
let db = Database::open("mydata.db").unwrap();

// 建表
db.execute("CREATE TABLE sensors (id INT PRIMARY KEY, value FLOAT)").unwrap();

// 插入数据
db.execute("INSERT INTO sensors VALUES (1, 25.6)").unwrap();

// 查询数据
let rows = db.query("SELECT * FROM sensors").unwrap();
for row in rows {
    println!("{:?}", row);
}

🔒 安全

API 访问认证

RustMinidb 内置 Bearer Token 认证 保护所有数据接口，防止未授权访问。

# 方式一：命令行参数（推荐）

rustminidb serve --api-token "your-secret-token"


# 方式二：环境变量（避免 Token 出现在进程列表）

export RUSTMINIDB_API_TOKEN="your-secret-token"

rustminidb serve

认证规则：

公开端点（免认证）：

安全建议：

• 生产环境必须设置 --api-token
• 通过环境变量 RUSTMINIDB_API_TOKEN 传入 Token，避免命令行历史泄露
• 使用反向代理（nginx / caddy）终止 TLS/SSL，确保传输加密
• 定期更换 Token

配置

RustMinidb 支持 TOML 配置文件，默认值如下：

[server]

host = "0.0.0.0"

port = 8080

maxConnections = 100

queryTimeoutMs = 5000



[storage]

dbPath = "data.db"

cacheSizeMb = 64



[logging]

level = "info"

format = "text"

可通过命令行参数覆盖：

rustminidb serve --host 127.0.0.1 --port 9090 --db mydb.db

SQL 支持

RustMinidb 支持以下 SQL 语法（MVP 阶段）：

支持的数据类型：INTEGER、FLOAT、TEXT、BLOB、BOOLEAN、TIMESTAMP

支持的比较运算符：=、!=、<、>、<=、>=、AND、OR

数据迁移与导出

支持四种 SQL 方言导出：

# 标准格式导出

rustminidb export --db mydata.db --output export.sql


# 导出兼容 MySQL

# （可通过 Rust API 配置 dialect: SqlDialect::MySQL）


# 导出兼容 PostgreSQL

# （可通过 Rust API 配置 dialect: SqlDialect::PostgreSQL）

导出特性：

• ✅ CREATE TABLE IF NOT EXISTS
• ✅ 批量 INSERT（可配置每批行数）
• ✅ DROP TABLE IF EXISTS 前缀
• ✅ 事务包裹（BEGIN / COMMIT）
• ✅ 表注释导出
• ✅ 多方言类型映射
• ✅ 进度回调

构建

# 克隆仓库

git clone https://github.com/rustminidb/rustminidb.git

cd rustminidb


# 构建（默认启用 server 特性）

cargo build --release


# 仅构建 library（无 HTTP 服务器）

cargo build --release --no-default-features


# 运行测试

cargo test --lib


# 查看帮助

./target/release/rustminidb --help

技术栈

许可证

本项目基于 BSL-1.1 许可证（Boost Software License 1.0）发布。

Boost Software License - Version 1.0

Permission is hereby granted, free of charge, to any person or organization
obtaining a copy of the software and accompanying documentation...

相关链接

• 仓库: https://github.com/rustminidb/rustminidb
• 文档: https://docs.rs/rustminidb
• 主页: https://rustminidb.dev