srdb/examples

SRDB Examples

本目录包含 SRDB 数据库的示例程序和工具。

目录结构

examples/
├── complex/            # 复杂类型系统示例（21 种类型全覆盖）
│   ├── main.go         # 主程序
│   ├── README.md       # 详细文档
│   └── .gitignore      # 忽略数据目录
└── webui/              # Web UI 和命令行工具集
    ├── main.go         # 主入口点
    ├── commands/       # 命令实现
    │   ├── webui.go            # Web UI 服务器
    │   ├── check_data.go       # 数据检查工具
    │   ├── check_seq.go        # 序列号检查工具
    │   ├── dump_manifest.go    # Manifest 导出工具
    │   ├── inspect_all_sst.go  # SST 文件批量检查
    │   ├── inspect_sst.go      # SST 文件检查工具
    │   ├── test_fix.go         # 修复测试工具
    │   └── test_keys.go        # 键存在性测试工具
    └── README.md       # WebUI 详细文档

---

Complex - 完整类型系统演示

一个展示 SRDB 所有 21 种数据类型的完整示例，包括结构体 Schema 生成、边界值测试、索引查询和分页等核心功能。

🎯 涵盖的类型

分类	数量	包含类型
字符串	1 种	String
有符号整数	5 种	Int, Int8, Int16, Int32, Int64
无符号整数	5 种	Uint, Uint8, Uint16, Uint32, Uint64
浮点数	2 种	Float32, Float64
布尔	1 种	Bool
特殊类型	5 种	Byte, Rune, Decimal, Time, Duration
复杂类型	2 种	Object, Array

快速开始

cd examples/complex

# 运行示例
go run main.go

# 清理并重新生成
go run main.go --clean

# 指定数据目录
go run main.go --dir ./mydata --clean

示例输出

╔═══════════════ 设备记录 #1 (seq=1) ═══════════════╗
║ ID: IOT-2025-0001                                   ║
║ 名称: 智能环境监测站                                 ║
╟─────────────────── 整数类型 ────────────────────────╢
║ Signal(int):    -55                                 ║
║ ErrorCode(i8):  0                                   ║
║ DeltaTemp(i16): 150                                 ║
║ RecordNum(i32): 12345                               ║
║ TotalBytes(i64):1073741824                          ║
...

功能演示

✅ 结构体自动生成 Schema

fields, _ := srdb.StructToFields(DeviceRecord{})

✅ 边界值测试

• int8 最大值 (127)
• int16 最小值 (-32768)
• uint64 最大值 (18446744073709551615)

✅ 索引查询优化

table.Query().Eq("device_id", "IOT-2025-0001").Rows()

✅ 分页查询（返回总数）

rows, total, err := table.Query().Paginate(1, 10)

✅ 复杂类型序列化

• Object: map[string]any → JSON
• Array: []string → JSON

详细文档：complex/README.md

---

WebUI - 数据库管理工具

一个集成了 Web 界面和命令行工具的 SRDB 数据库管理工具。

功能特性

🌐 Web UI

• 表列表展示 - 可视化查看所有表及其 Schema
• 数据分页浏览 - 表格形式展示数据，支持分页和列选择
• Manifest 查看 - 查看 LSM-Tree 结构和 Compaction 状态
• 响应式设计 - 基于 HTMX 的现代化界面
• 大数据优化 - 自动截断显示，点击查看完整内容

🛠️ 命令行工具

• 数据检查 - 检查表和数据完整性
• 序列号验证 - 验证特定序列号的数据
• Manifest 导出 - 导出 LSM-Tree 层级信息
• SST 文件检查 - 检查和诊断 SST 文件问题

快速开始

1. 启动 Web UI

cd examples/webui

# 使用默认配置（数据库：./data，端口：8080）
go run main.go serve

# 或指定自定义配置
go run main.go serve -db ./mydb -addr :3000

然后打开浏览器访问 http://localhost:8080

2. 查看帮助

go run main.go help

输出：

SRDB WebUI - Database management tool

Usage:
  webui <command> [flags]

Commands:
  webui, serve       Start WebUI server (default: :8080)
  check-data         Check database tables and row counts
  check-seq          Check specific sequence numbers
  dump-manifest      Dump manifest information
  inspect-all-sst    Inspect all SST files
  inspect-sst        Inspect a specific SST file
  test-fix           Test fix for data retrieval
  test-keys          Test key existence
  help               Show this help message

Examples:
  webui serve -db ./mydb -addr :3000
  webui check-data -db ./mydb
  webui inspect-sst -file ./data/logs/sst/000046.sst

---

命令详解

serve / webui - 启动 Web 服务器

启动 Web UI 服务器，提供数据可视化界面。

# 基本用法
go run main.go serve

# 指定数据库路径和端口
go run main.go webui -db ./mydb -addr :3000

参数：

• -db - 数据库目录路径（默认：./data）
• -addr - 服务器地址（默认：:8080）

功能：

• 自动创建示例表（users, products, logs）
• 后台自动插入测试数据（每秒一条）
• 提供 Web UI 和 HTTP API

---

check-data - 检查数据

检查数据库中所有表的记录数。

go run main.go check-data -db ./data

输出示例：

Found 3 tables: [users products logs]
Table 'users': 5 rows
Table 'products': 6 rows
Table 'logs': 1234 rows

---

check-seq - 检查序列号

验证特定序列号的数据是否存在。

go run main.go check-seq -db ./data

功能：

• 检查 seq=1, 100, 729 等特定序列号
• 显示总记录数
• 验证数据完整性

---

dump-manifest - 导出 Manifest

导出数据库的 Manifest 信息，检查文件重复。

go run main.go dump-manifest -db ./data

输出示例：

Level 0: 5 files
Level 1: 3 files
Level 2: 1 files

---

inspect-all-sst - 批量检查 SST 文件

检查所有 SST 文件的完整性。

go run main.go inspect-all-sst -dir ./data/logs/sst

输出示例：

Found 10 SST files

File #1 (000001.sst):
  Header: MinKey=1 MaxKey=100 RowCount=100
  Actual: 100 keys [1 ... 100]

File #2 (000002.sst):
  Header: MinKey=101 MaxKey=200 RowCount=100
  Actual: 100 keys [101 ... 200]
  *** MISMATCH: Header says 101-200 but file has 105-200 ***

---

inspect-sst - 检查单个 SST 文件

详细检查特定 SST 文件。

go run main.go inspect-sst -file ./data/logs/sst/000046.sst

输出示例：

File: ./data/logs/sst/000046.sst
Size: 524288 bytes

Header:
  RowCount: 100
  MinKey: 332
  MaxKey: 354
  DataSize: 512000 bytes

Actual keys in file: 100 keys
  First key: 332
  Last key: 354
  All keys: [332 333 334 ... 354]

Trying to get key 332:
  FOUND: seq=332, time=1234567890

---

test-fix - 测试修复

测试数据检索的修复功能。

go run main.go test-fix -db ./data

功能：

• 测试首部、中部、尾部记录
• 验证 Get() 操作的正确性
• 显示修复状态

---

test-keys - 测试键存在性

测试特定键是否存在。

go run main.go test-keys -db ./data

功能：

• 测试预定义的键列表
• 统计找到的键数量
• 显示首尾记录

---

编译安装

编译二进制

cd examples/webui
go build -o webui main.go

全局安装

go install ./examples/webui@latest

然后可以在任何地方使用：

webui serve -db ./mydb
webui check-data -db ./mydb

---

Web UI 使用

界面布局

访问 http://localhost:8080 后，你会看到：

左侧边栏：

• 表列表，显示每个表的字段数
• 点击展开查看 Schema 详情
• 点击表名切换到该表

右侧主区域：

• Data 视图：数据表格，支持分页和列选择
• Manifest 视图：LSM-Tree 结构和 Compaction 状态

HTTP API 端点

获取表列表

GET /api/tables-html

获取表数据

GET /api/tables-view/{table_name}?page=1&pageSize=20

获取 Manifest

GET /api/tables-view/{table_name}/manifest

获取 Schema

GET /api/tables/{table_name}/schema

获取单条数据

GET /api/tables/{table_name}/data/{seq}

详细 API 文档请参考：webui/README.md

---

在你的应用中集成

方式 1：使用 WebUI 包

package main

import (
    "net/http"
    "code.tczkiot.com/wlw/srdb"
    "code.tczkiot.com/wlw/srdb/webui"
)

func main() {
    db, _ := srdb.Open("./mydb")
    defer db.Close()

    // 创建 WebUI handler
    handler := webui.NewWebUI(db)

    // 启动服务器
    http.ListenAndServe(":8080", handler)
}

方式 2：挂载到现有应用

mux := http.NewServeMux()

// 你的其他路由
mux.HandleFunc("/api/myapp", myHandler)

// 挂载 SRDB Web UI 到 /admin/db 路径
mux.Handle("/admin/db/", http.StripPrefix("/admin/db", webui.NewWebUI(db)))

http.ListenAndServe(":8080", mux)

方式 3：使用命令工具

将 webui 工具的命令集成到你的应用：

import "code.tczkiot.com/wlw/srdb/examples/webui/commands"

// 检查数据
commands.CheckData("./mydb")

// 导出 manifest
commands.DumpManifest("./mydb")

// 启动服务器
commands.StartWebUI("./mydb", ":8080")

---

开发和调试

开发模式

在开发时，使用 go run 可以快速测试：

# 启动服务器
go run main.go serve

# 在另一个终端检查数据
go run main.go check-data

# 检查 SST 文件
go run main.go inspect-all-sst

清理数据

# 删除数据目录
rm -rf ./data

# 重新运行
go run main.go serve

---

注意事项

1. 数据目录：默认在当前目录创建 ./data 目录
2. 端口占用：确保端口未被占用
3. 并发访问：Web UI 支持多用户并发访问
4. 只读模式：Web UI 仅用于查看，不提供数据修改功能
5. 生产环境：建议添加身份验证和访问控制
6. 性能考虑：大表分页查询性能取决于数据分布

---

技术栈

• 后端：Go 标准库（net/http）
• 前端：HTMX + 原生 JavaScript + CSS
• 渲染：服务端 HTML 渲染（Go）
• 数据库：SRDB (LSM-Tree)
• 部署：所有静态资源通过 embed 嵌入，无需单独部署

---

故障排除

常见问题

1. 启动失败 - 端口被占用

Error: listen tcp :8080: bind: address already in use

解决：使用 -addr 指定其他端口

go run main.go serve -addr :3000

2. 数据库打开失败

Error: failed to open database: invalid header

解决：删除损坏的数据目录

rm -rf ./data

3. SST 文件损坏 使用 inspect-sst 或 inspect-all-sst 命令诊断：

go run main.go inspect-all-sst -dir ./data/logs/sst

---

更多信息

• WebUI 详细文档：webui/README.md
• SRDB 主文档：../README.md
• Compaction 说明：../COMPACTION.md
• 压力测试报告：../STRESS_TEST_RESULTS.md

---

贡献

欢迎贡献新的示例和工具！请遵循以下规范：

1. 在 examples/ 下创建新的子目录
2. 提供清晰的 README 文档
3. 添加示例代码和使用说明
4. 更新本文件

---

许可证

与 SRDB 项目相同的许可证。