pipelinedb/examples/README.md

# Pipeline Database V4 示例

本目录包含了 Pipeline Database V4 的各种使用示例，展示了不同场景下的应用方法。

## 示例列表

### 1. 基础使用 (`basic-usage/`)
演示 Pipeline Database 的基本功能：
- 数据库初始化和配置
- 数据插入和查询
- 基本统计信息获取
- **Handler**: `LoggingHandler` (简单日志处理)

### 2. 组管理 (`group-management/`)
展示分组管理功能：
- 多组数据管理
- 按组查询和统计
- 跨组数据分析
- **Handler**: `ExampleHandler` (完整示例处理器)

### 3. 外部处理器 (`external-handler/`)
演示自定义外部处理器：
- 实现 Handler 接口
- 热数据预热处理
- 温数据冷却处理
- 组完成回调
- **Handler**: 自定义 `EmailHandler`

### 4. 数据分析 (`data-analytics/`)
展示数据分析和报告功能：
- 用户行为分析
- 统计报告生成
- 数据可视化
- **Handler**: `ExampleHandler` (数据分析处理器)

### 5. 并发处理 (`concurrent-processing/`)
演示并发数据处理：
- 多生产者并发写入
- 实时统计监控
- 并发查询测试
- **Handler**: `ExampleHandler` (并发处理器)

### 6. 高并发压力测试 (`high-concurrency/`)
演示极限并发性能：
- 50个写入goroutine + 20个读取goroutine
- 目标1000写入QPS + 500读取QPS
- 30秒压力测试
- 性能评估和报告
- **Handler**: `LoggingHandler` (轻量级处理)

## Handler 配置说明

所有示例现在都配置了适当的 Handler，避免了空指针异常：

### LoggingHandler
- **用途**: 简单的日志输出，适合基础示例
- **特点**: 轻量级，不做复杂处理
- **使用场景**: 基础使用、高并发测试

### ExampleHandler
- **用途**: 完整的示例处理器，包含详细日志
- **特点**: 展示完整的处理流程
- **使用场景**: 组管理、数据分析、并发处理

### 自定义Handler
- **用途**: 特定业务逻辑处理
- **特点**: 根据具体需求实现
- **使用场景**: 外部处理器示例

## 运行示例

每个示例都是独立的，可以直接运行：

```bash
# 基础使用示例
```

2. **运行任意示例**:
```bash
cd basic-usage
go run main.go
```

3. **查看输出**: 每个示例都会产生详细的输出，展示各个步骤的执行过程

## 📚 示例特点

### 🎯 实用性
- 每个示例都模拟真实的业务场景
- 包含完整的错误处理
- 提供详细的日志输出

### 🔧 可定制性
- 易于修改和扩展
- 清晰的代码结构
- 丰富的注释说明

### 📊 教育性
- 渐进式学习路径
- 从基础到高级功能
- 最佳实践演示

## 💡 使用建议

### 学习路径
1. **新手**: 从 `basic-usage` 开始
2. **进阶**: 学习 `external-handler` 和 `group-management`
3. **高级**: 研究 `concurrent-processing` 和 `data-analytics`

### 生产环境适配
- 修改数据库文件路径
- 调整缓存大小配置
- 实现自定义的外部处理器
- 添加适当的监控和日志

### 性能优化
- 根据数据量调整 `CacheSize`
- 合理设计组结构
- 优化查询分页大小
- 监控系统资源使用

## 🔧 配置说明

### 数据库配置
```go
config := &pipelinedb.Config{
    CacheSize: 100, // 缓存页面数量
}
```

### 打开选项
```go
pdb, err := pipelinedb.Open(pipelinedb.Options{
    Filename: "database.db",    // 数据库文件路径
    Config:   config,           // 配置选项
    Handler:  yourHandler,      // 外部处理器（可选）
    Logger:   yourLogger,       // 日志器（可选）
})
```

## 🐛 故障排除

### 常见问题

1. **文件权限错误**
   - 确保对数据库文件目录有写权限
   - 检查临时文件创建权限

2. **内存不足**
   - 减少 `CacheSize` 配置
   - 优化数据处理逻辑

3. **并发冲突**
   - 检查并发访问模式
   - 确保正确的错误处理

### 调试技巧
- 启用详细日志输出
- 使用分步调试
- 监控系统资源使用
- 检查数据库统计信息

## 📞 获取帮助

如果你在使用示例时遇到问题：

1. 查看示例代码中的注释
2. 检查错误信息和日志输出
3. 参考 Pipeline Database V4 的文档
4. 在项目仓库提交 Issue

## 🎉 贡献

欢迎贡献新的示例！请确保：
- 代码清晰易懂
- 包含详细注释
- 模拟真实场景
- 添加到此 README

---

**Pipeline Database V4** - 高性能的管道式数据库系统