SRDB - Simple Row Database

一个用 Go 编写的高性能 Append-Only 时序数据库引擎，专为高并发写入和快速查询设计。

🎯 核心特性

• Append-Only 架构 - WAL + MemTable + mmap B+Tree SST，简化并发控制
• 强类型 Schema - 21 种数据类型，包括 Object（map）和 Array（slice）
• 高性能写入 - 200K+ 写/秒（多线程），<1ms 延迟（p99）
• 快速查询 - <0.1ms（内存），1-5ms（磁盘），支持二级索引
• 智能 Scan - 自动扫描到结构体，完整支持复杂类型
• 链式查询 API - 18 种操作符，支持复合条件
• 自动 Compaction - 后台异步合并，优化存储空间
• 零拷贝读取 - mmap 访问 SST 文件，内存占用 <150MB
• Web 管理界面 - 现代化的数据浏览和监控工具

📋 目录

• 快速开始
• 核心概念
• 文档
• 开发

---

🚀 快速开始

安装

go get code.tczkiot.com/wlw/srdb

要求：Go 1.21+

基本示例

package main

import (
    "fmt"
    "log"
    "code.tczkiot.com/wlw/srdb"
)

func main() {
    // 1. 打开数据库
    db, err := srdb.Open("./data")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // 2. 定义 Schema（强类型，21 种类型）
    schema, err := srdb.NewSchema("users", []srdb.Field{
        {Name: "id", Type: srdb.Uint32, Indexed: true, Comment: "用户ID"},
        {Name: "name", Type: srdb.String, Comment: "用户名"},
        {Name: "email", Type: srdb.String, Indexed: true, Comment: "邮箱"},
        {Name: "age", Type: srdb.Int32, Comment: "年龄"},
        {Name: "tags", Type: srdb.Array, Comment: "标签"},          // Array 类型
        {Name: "settings", Type: srdb.Object, Comment: "设置"},     // Object 类型
    })
    if err != nil {
        log.Fatal(err)
    }

    // 3. 创建表
    table, err := db.CreateTable("users", schema)
    if err != nil {
        log.Fatal(err)
    }

    // 4. 插入数据
    err = table.Insert(map[string]any{
        "id":    uint32(1),
        "name":  "Alice",
        "email": "alice@example.com",
        "age":   int32(25),
        "tags":  []any{"golang", "database"},
        "settings": map[string]any{
            "theme": "dark",
            "lang":  "zh-CN",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // 5. 查询并扫描到结构体
    type User struct {
        ID       uint32            `json:"id"`
        Name     string            `json:"name"`
        Email    string            `json:"email"`
        Age      int32             `json:"age"`
        Tags     []string          `json:"tags"`
        Settings map[string]string `json:"settings"`
    }

    var users []User
    err = table.Query().
        Eq("name", "Alice").
        Gte("age", 18).
        Scan(&users)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d users\n", len(users))
    fmt.Printf("Tags: %v\n", users[0].Tags)
    fmt.Printf("Settings: %v\n", users[0].Settings)
}

---

💡 核心概念

架构

SRDB 使用 Append-Only 架构，分为两层：

1. 内存层 - WAL（Write-Ahead Log）+ MemTable（Active + Immutable）
2. 磁盘层 - SST 文件（带 B+Tree 索引），分层存储（L0-L3）

写入流程：
数据 → WAL（持久化）→ MemTable → Flush → SST L0 → Compaction → SST L1-L3

读取流程：
查询 → MemTable（O(1)）→ Immutable MemTables → SST Files（B+Tree）

数据文件

database_dir/
├── database.meta        # 数据库元数据
└── table_name/          # 每表一个目录
    ├── schema.json      # 表 Schema 定义
    ├── MANIFEST-000001  # 表级版本控制
    ├── CURRENT          # 当前 MANIFEST 指针
    ├── wal/             # WAL 子目录
    │   ├── 000001.wal   # WAL 文件
    │   └── CURRENT      # 当前 WAL 指针
    ├── sst/             # SST 子目录（L0-L3 层级文件）
    │   └── 000001.sst   # SST 文件（B+Tree + 数据）
    └── idx/             # 索引子目录
        └── idx_email.sst # 二级索引文件

设计特点

• Append-Only - 无原地更新，简化并发控制
• MemTable - map[int64][]byte + sorted slice，O(1) 读写
• SST 文件 - 4KB 节点的 B+Tree，mmap 零拷贝访问
• 二进制编码 - ROW1 格式，无压缩，优先查询性能
• Compaction - 后台异步合并，按层级管理文件大小

---

📚 文档

核心文档

• DOCS.md - 完整 API 文档和使用指南
• DESIGN.md - 数据库设计文档

示例教程

• WebUI 工具 - Web 管理界面

---

🛠️ 开发

运行测试

# 所有测试
go test -v ./...

# 单个测试
go test -v -run TestTable

# 性能测试
go test -bench=. -benchmem

构建 WebUI

cd examples/webui
go build -o webui main.go
./webui serve --db ./data

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发流程

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 提交 Pull Request

代码规范

• 遵循 Go 官方代码风格
• 添加必要的注释和文档
• 编写单元测试
• 确保所有测试通过

---

📝 许可证

MIT License - 详见 LICENSE 文件

---

🙏 致谢

• LevelDB - 架构设计参考
• RocksDB - Compaction 策略参考

---

📧 联系

• 项目主页：https://code.tczkiot.com/wlw/srdb
• Issue 跟踪：https://code.tczkiot.com/wlw/srdb/issues

---

SRDB - 简单、高效、可靠的嵌入式数据库 🚀