# RustSQLite

**Repository Path**: yinglichina/rustsqlite

## Basic Information

- **Project Name**: RustSQLite
- **Description**: Rust 模拟，复刻 SQLite 项目的实现。
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RustSQL

> 用 Rust 语言复刻 SQLite 数据库引擎

[![Rust](https://img.shields.io/badge/rust-1.60%2B-blue.svg)](https://www.rust-lang.org)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-green.svg)](LICENSE)

---

## 项目概述

RustSQL 是一个用 Rust 编写的 SQLite 兼容数据库引擎，旨在提供一个高性能、安全可靠的嵌入式数据库解决方案。

### 核心特性

- **内存安全**：使用 Rust 语言消除 C 语言固有的内存安全问题
- **高性能**：利用 Rust 的零成本抽象和并发能力
- **SQLite 兼容**：兼容 SQLite 的 SQL 语法和数据格式
- **模块化设计**：从 KV 存储到完整 SQL 引擎的渐进式开发

### 项目愿景

```
v0.1 ──────▶ v0.2 ──────▶ v0.3 ──────▶ v1.0 ──────▶ v2.0 ──────▶ v3.0
  │            │            │            │            │            │
 内存KV      持久化       索引查询      SQLite兼容   企业特性      WASM支持
```

---

## 当前状态

> **⚠️ 注意**：项目处于早期开发阶段，v0.1.0 版本有编译错误待修复

| 模块 | 版本目标 | 实现状态 | 说明 |
|------|---------|---------|------|
| 错误处理 | v0.1.0 | ✅ 已实现 | src/error.rs |
| BTree内存 | v0.1.0 | ⚠️ 有bug | src/kv/btree.rs (18个编译错误) |
| BTree节点 | v0.1.0 | ✅ 已实现 | src/kv/node.rs |
| 迭代器 | v0.1.0 | ✅ 已实现 | src/kv/mod.rs |
| 内存存储 | v0.1.0 | ✅ 已实现 | src/kv/mod.rs |
| 分页管理 | v0.2.0 | ❌ 未实现 | |
| 页面缓存 | v0.2.0 | ❌ 未实现 | |
| Journal | v0.2.0 | ❌ 未实现 | |
| 索引管理 | v0.3.0 | ❌ 未实现 | |
| SQL解析 | v1.0 | ❌ 未实现 | |
| SQL执行 | v1.0 | ❌ 未实现 | |
| WAL | v1.5 | ❌ 未实现 | |

---

## 快速开始

### 构建项目

```bash
cargo build
```

### 运行测试

```bash
cargo test
```

### 代码检查

```bash
cargo clippy
cargo fmt --check
```

---

## 文档结构

```
docs/
├── roadmap/                    # 📋 项目规划
│   └── master_roadmap.md       # ✅ 主RoadMap (v1.1)
│
├── srs/                        # 📝 需求规格说明书
│   ├── srs_v0_1.md            # ✅ v0.1 需求规格
│   └── srs_v1_0.md            # ✅ v1.0 需求规格
│
├── hld/                        # 🏗️ 架构设计文档
│   ├── hld_storage.md          # ✅ 存储引擎架构
│   ├── hld_sql.md             # ✅ SQL引擎架构
│   └── hld_optimizer.md        # ✅ 查询优化器架构
│
├── lld/                        # 📐 详细设计文档
│   ├── lld_pager.md           # ✅ Pager详细设计
│   └── lld_sql.md             # ✅ SQL层详细设计
│
├── design/                     # 📚 设计文档 (TRAE + AI)
│   ├── kv_component_design.md  # ✅ B-Tree组件设计 (详细)
│   ├── kv_store_design.md      # ✅ KV存储引擎设计
│   ├── parser_component_design.md # ✅ Parser组件设计
│   ├── parser_module_design.md # ✅ Parser模块设计
│   ├── sql_engine_design.md    # ✅ SQL执行引擎设计
│   ├── optimizer_design.md     # ✅ 查询优化器设计
│   ├── wal_design.md          # ✅ WAL系统设计
│   └── test_plan.md           # ✅ 测试计划
│
├── tests/                      # 🧪 测试用例
│   └── test_cases_v0_1.md     # ✅ v0.1 测试用例
│
├── test/                       # 📊 质量标准
│   └── test_plan_and_quality.md # ✅ 测试计划与质量标准
│
└── api/                        # 📖 API参考
    └── api_kvstore.md         # ✅ KV Store API
```

### 文档状态统计

| 类型 | 数量 | 状态 |
|------|------|------|
| 需求规格 (SRS) | 2 | ✅ 已有 |
| 架构设计 (HLD) | 3 | ✅ 已有 |
| 详细设计 (LLD) | 2 | ✅ 已有 |
| 设计文档 (Design) | 8 | ✅ 已有 |
| 测试用例 | 1 | ✅ 已有 |
| 质量标准 | 1 | ✅ 已有 |
| API参考 | 1 | ✅ 已有 |
| **总计** | **18** | ✅ |

---

## 核心设计文档

### 1. 需求规格 (SRS)

| 文档 | 版本 | 说明 |
|------|------|------|
| [srs_v0_1.md](docs/srs/srs_v0_1.md) | v0.1 | 内存B-Tree KV存储需求 |
| [srs_v1_0.md](docs/srs/srs_v1_0.md) | v1.0 | SQLite兼容数据库需求 |

### 2. 架构设计 (HLD)

| 文档 | 版本 | 说明 |
|------|------|------|
| [hld_storage.md](docs/hld/hld_storage.md) | v0.1-v3.0 | 存储引擎分层架构 |
| [hld_sql.md](docs/hld/hld_sql.md) | v1.0 | SQL解析→执行架构 |
| [hld_optimizer.md](docs/hld/hld_optimizer.md) | v2.0 | 查询优化器架构 |

### 3. 详细设计 (LLD)

| 文档 | 版本 | 说明 |
|------|------|------|
| [lld_pager.md](docs/lld/lld_pager.md) | v0.2 | Pager页面管理详细设计 |
| [lld_sql.md](docs/lld/lld_sql.md) | v1.0 | SQL层详细设计 |

### 4. 组件设计 (Design)

| 文档 | 版本 | 说明 |
|------|------|------|
| [kv_component_design.md](docs/design/kv_component_design.md) | v0.1 | **B-Tree组件详细设计**（含PlantUML图）|
| [kv_store_design.md](docs/design/kv_store_design.md) | v0.1-v0.2 | KV存储引擎设计 |
| [parser_component_design.md](docs/design/parser_component_design.md) | v1.0 | Parser组件设计 |
| [parser_module_design.md](docs/design/parser_module_design.md) | v1.0 | Parser模块设计 |
| [sql_engine_design.md](docs/design/sql_engine_design.md) | v1.0 | SQL执行引擎设计 |
| [optimizer_design.md](docs/design/optimizer_design.md) | v2.0 | 查询优化器设计 |
| [wal_design.md](docs/design/wal_design.md) | v1.5 | WAL系统设计 |
| [test_plan.md](docs/design/test_plan.md) | v0.1-v3.0 | 测试计划 |

---

## 版本里程碑

| 版本 | 阶段 | 核心交付 | 状态 |
|------|------|---------|------|
| **v0.1.0** | 基础夯实 | 内存B-Tree KV Store | ⚠️ 有bug |
| **v0.2.0** | 存储引擎 | 持久化KV + Journal | ❌ 未开始 |
| **v0.3.0** | 索引系统 | 索引支持 + 简单查询 | ❌ 未开始 |
| **v1.0.0** | MVP | SQLite兼容DB | ❌ 未开始 |
| **v1.5.0** | 企业基础 | WAL + 事务 + CLI | ❌ 未开始 |
| **v2.0.0** | 性能优化 | 查询优化 + 并发 | ❌ 未开始 |
| **v2.5.0** | 高级特性 | JSON + FTS | ❌ 未开始 |
| **v3.0.0** | 生态完善 | WASM + 加密 | ❌ 未开始 |

---

## 项目结构

```
src/
├── lib.rs          # 库入口
├── error.rs        # 错误处理
└── kv/
    ├── mod.rs      # KV Store trait
    ├── btree.rs    # B-Tree 实现 (⚠️ 有编译错误)
    └── node.rs     # B-Tree 节点
```

---

## 待完成工作

### P0 (阻塞)

1. **修复 btree.rs 编译错误** - 18个编译错误待修复
2. **实现 Pager 层** - v0.2 持久化存储

### P1 (重要)

3. **实现 Journal/WAL** - 崩溃恢复支持
4. **实现 SQL Parser** - v1.0
5. **实现 SQL Executor** - v1.0

### P2 (增强)

6. **实现查询优化器** - v2.0
7. **性能基准测试** - 添加 criterion 测试
8. **sqllogictest 集成** - SQLite 兼容性测试

---

## 学习资源

| 资源 | 说明 |
|------|------|
| [kv_component_design.md](docs/design/kv_component_design.md) | B-Tree 数据结构详解（含大量 UML 图）|
| [parser_component_design.md](docs/design/parser_component_design.md) | SQL Parser 设计模式 |
| [wal_design.md](docs/design/wal_design.md) | WAL 预写日志原理 |
| [hld_optimizer.md](docs/hld/hld_optimizer.md) | 查询优化器架构 |

---

## 贡献指南

1. 先阅读 `docs/roadmap/master_roadmap.md` 了解项目规划
2. 查看对应版本的 SRS 和 HLD 文档
3. 遵循 `docs/test/test_plan_and_quality.md` 中的测试标准
4. 确保 `cargo clippy` 和 `cargo fmt` 通过

---

## 许可证

MIT OR Apache-2.0

---

*最后更新：2026-04-07*