melange_db 0.2.2

# Melange DB 🪐

> sledアーキテクチャに基づく次世代高性能組み込みデータベース

[![Crates.io](https://img.shields.io/crates/v/melange_db.svg)](https://crates.io/crates/melange_db)
[![Documentation](https://docs.rs/melange_db/badge.svg)](https://docs.rs/melange_db)
[![License](https://img.shields.io/badge/license-LGPLv3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0.en.html)

## 🌍 言語バージョン
- [中文版](README.md) | [English](README_en.md) | [日本語版](README_ja.md)

## プロジェクト紹介

Melange DBは、sledアーキテクチャをベースに深いパフォーマンス最適化を行った組み込みデータベースです。RocksDBのパフォーマンスを超越することを目指し、SIMD命令最適化、スマートキャッシュシステム、ブルームフィルターなどの技術により、究極の読み書きパフォーマンスを実現します。

### 🎭 創作インスピレーション

プロジェクト名と設計哲学は、フランク・ハーバートの古典SF小説「デューン」に深くインスパイアされています：

- **メランジュ（スパイス）**: デューン宇宙で最も貴重な物質、宇宙航行の鍵であり、データの価値を象徴
- **恐怖は思考殺し**: 「恐怖は心の殺し屋だ」という古典的なセリフのように、パフォーマンスへの恐怖を排除し、究極の最適化を追求
- **スパイスルート**: デューンのスパイス輸送ルートのように、Melange DBは効率的なデータフローとストレージパスを構築
- **フリーメンの精神**: 砂漠のサバイバル専門家、リソース制約環境での究極のパフォーマンス最適化を表現

このインスピレーションは、私たちの中核哲学を反映しています：**限られたリソースから無限の価値を創造する**。

## コア機能

### 🚀 究極のパフォーマンス最適化
- **SIMD最適化Key比較**: ARM64 NEON命令セットに基づく高性能比較
- **多段ブロックキャッシュシステム**: ホット/ウォーム/コールド3階層キャッシュ、LRU削除戦略
- **スマートブルームフィルター**: 1%の偽陽性率、存在しないクエリの高速フィルタリング
- **プリフェッチメカニズム**: インテリジェントなプリフェッチアルゴリズムがシーケンシャルアクセスパフォーマンスを向上

### 🔒 並行安全性
- **ロックフリーデータ構造**: concurrent-mapに基づく高並行性設計
- **スレッド安全性**: 完全なSend + Syncトレイト実装
- **原子性保証**: ACID互換トランザクションサポート

### 🔥 原子操作統一アーキテクチャ（重大なパフォーマンスアップグレード）

> **バージョン v0.2.0**: 全新しい原子操作統一アーキテクチャを導入し、高並行シナリオにおけるEBR競合を完全に解決しました。

#### 🚀 破壊的アップグレード通知

**これは破壊的パフォーマンスアップグレード**で、以下の重大な改良を含みます：

✅ **解決された問題**:
- **EBR RefCell競合**: マルチスレッド高並行操作時の`RefCell already borrowed`パニックを完全に排除
- **データ競合**: 原子操作とデータベース操作間の競合状態を排除
- **パフォーマンスボトルネック**: ワーカー間通信により並行パフォーマンスを大幅向上

⚠️ **API変更**:
- `atomic_operations_manager::AtomicOperationsManager` - 全新しい統一ルーター設計
- `atomic_worker::AtomicWorker` - 完全に独立した原子操作コンポーネントに再構築
- `database_worker::DatabaseWorker` - 新しい専用データベース操作ワーカー

#### 🏗️ 新アーキテクチャ設計

**SegQueue統一アーキテクチャ**:
```
AtomicOperationsManager (純粋ルーター)
    ├── SegQueue A ↔ AtomicWorker (DashMap + AtomicU64)
    │   └── 自動永続化命令送信 → DatabaseWorkerキュー
    └── SegQueue B ↔ DatabaseWorker (すべてのデータベース操作)
```

#### ✅ コアアドバンテージ

1. **完全分離**:
   - AtomicOperationsManagerはルーティングのみを担当し、データ構造を操作しない
   - AtomicWorkerは原子操作を専門に処理し、データベースに直接アクセスしない
   - DatabaseWorkerはすべてのデータベース操作を専門に処理

2. **ワーカー間通信**:
   - AtomicWorkerは操作完了後に自動的にDatabaseWorkerに永続化命令を送信
   - 同一スレッドでのEBR競合を完全に回避

3. **統一SegQueue使用**:
   - すべてのワーカーが同じ並行キュー機構を使用
   - 既存アーキテクチャとの一貫性を維持

#### 📊 パフォーマンス検証

**12スレッド高圧力テスト結果**:
- ✅ **285回の原子操作**: 160 + 50 + 40 + 35回のページアクセス
- ✅ **570件のデータベースレコード**: 300 + 150 + 120件
- ✅ **ゼロEBR競合**: 12スレッド同時実行完全に安全
- ✅ **100%データ一貫性**: すべてのカウンターとレコードデータ完全に正確

#### 🚀 使用例

```rust
use melange_db::{Db, Config, atomic_operations_manager::AtomicOperationsManager};
use std::sync::Arc;

fn main() -> anyhow::Result<()> {
    // データベースを作成
    let config = Config::new().path("my_db");
    let db: Db<1024> = config.open()?;

    // 統一ルーターを作成
    let manager = Arc::new(AtomicOperationsManager::new(Arc::new(db)));

    // 原子操作（自動永続化）
    let user_id = manager.increment("user_counter".to_string(), 1)?;
    println!("新しいユーザーID: {}", user_id);

    // データベース操作
    manager.insert(b"user:profile", format!("user{}", user_id).as_bytes())?;

    // カウンターを取得
    let counter = manager.get("user_counter".to_string())?;
    println!("ユーザー総数: {:?}", counter);

    Ok(())
}
```

#### 🧪 テストケース

```bash
# 基本統一アーキテクチャテスト
cargo run --example segqueue_unified_test

# 高圧力並行テスト（12スレッド）
cargo run --example high_pressure_segqueue_test

# 原子操作ワーカーテスト
cargo run --example atomic_worker_test
```

#### 🔄 移行ガイド

**旧バージョン（v0.1.4以下）**:
```rust
// ❌ 非推奨 - EBR競合を引き起こす
let db = Arc::new(config.open()?);
// データベースへの直接的マルチスレッド操作はRefCell競合を引き起こす
```

**新バージョン（v0.2.0+）**:
```rust
// ✅ 推奨 - EBR競合なし
let manager = Arc::new(AtomicOperationsManager::new(Arc::new(config.open()?)));
// 統一ルーターを介した操作、完全にスレッドセーフ
```

📖 **詳細な移行ガイド**: 完全なアップグレード手順とトラブルシューティングガイドについては [docs/migration_guide_v0.2.0_ja.md](docs/migration_guide_v0.2.0_ja.md) を参照してください。

#### ⚡ パフォーマンス向上

- **並行安全性**: 無制限の並行スレッドをサポート
- **ゼロ競合**: EBR RefCell借用問題を完全に排除
- **自動永続化**: 原子操作完了後に自動的に永続化
- **データ一貫性**: 高並行下でのデータ完全性を保証

### 📦 効率的なメモリ管理
- **インクリメンタルシリアライゼーション**: I/Oオーバーヘッドを削減するシリアライゼーション戦略
- **スマートキャッシュ戦略**: 適応的キャッシュ置換アルゴリズム
- **メモリマッピング最適化**: 効率的なファイルマッピングメカニズム

## クイックスタート

### 基本的な使用方法

```rust
use melange_db::{Db, Config};

fn main() -> anyhow::Result<()> {
    // データベースを設定
    let config = Config::new()
        .path("/path/to/database")
        .cache_capacity_bytes(512 * 1024 * 1024); // 512MBキャッシュ

    // データベースを開く
    let db: Db<1024> = config.open()?;

    // データを書き込む
    let tree = db.open_tree("my_tree")?;
    tree.insert(b"key", b"value")?;

    // データを読み込む
    if let Some(value) = tree.get(b"key")? {
        println!("Found value: {:?}", value);
    }

    // 範囲クエリ
    for kv in tree.range(b"start"..b"end") {
        let (key, value) = kv?;
        println!("{}: {:?}", String::from_utf8_lossy(&key), value);
    }

    Ok(())
}
```

### 圧縮設定

Melange DBはコンパイル時機能による圧縮アルゴリズムの選択をサポートしています：

#### 無圧縮（デフォルト、最高パフォーマンス）
```rust
use melange_db::{Db, Config, CompressionAlgorithm};

let config = Config::new()
    .path("/path/to/database")
    .compression_algorithm(CompressionAlgorithm::None);
```

#### LZ4圧縮（パフォーマンスと圧縮率のバランス）
```rust
use melange_db::{Db, Config, CompressionAlgorithm};

let config = Config::new()
    .path("/path/to/database")
    .compression_algorithm(CompressionAlgorithm::Lz4);
```

#### Zstd圧縮（高圧縮率）
```rust
use melange_db::{Db, Config, CompressionAlgorithm};

let config = Config::new()
    .path("/path/to/database")
    .compression_algorithm(CompressionAlgorithm::Zstd);
```

### ビルドコマンド

```bash
# 無圧縮（デフォルト）
cargo build --release

# LZ4圧縮
cargo build --release --features compression-lz4

# Zstd圧縮
cargo build --release --features compression-zstd
```

## パフォーマンスハイライト

### Apple M1パフォーマンス
- **無圧縮**: 1.07 µs/書き込み、0.36 µs/読み取り
- **LZ4圧縮**: 0.97 µs/書き込み、0.36 µs/読み取り
- **Zstd圧縮**: 1.23 µs/書き込み、0.40 µs/読み取り

### プラットフォーム最適化
- **ARM64 NEON最適化**: Apple Silicon M1 NEON命令セットの完全活用
- **x86_64 SSE2/AVX2**: ローエンドからハイエンドまでフルカバー
- **適応的最適化**: ハードウェア特性に基づくスマート設定

## インストール

`Cargo.toml`に追加：

```toml
[dependencies]
melange_db = "0.2.0"
```

## サンプル

詳細な使用例については`examples/`ディレクトリを参照してください：

### 🔥 原子操作統一アーキテクチャ（v0.2.0+）
- **SegQueue統一アーキテクチャテスト**: `cargo run --example segqueue_unified_test`
  - 新しい原子操作統一アーキテクチャを実演
  - ワーカー間通信と自動永続化を検証
  - 基本ルーティング機能テストを含む

- **高圧力並行テスト**: `cargo run --example high_pressure_segqueue_test`
  - 12スレッド高並行混合操作テスト
  - 高負荷下でのシステム安定性を検証
  - ユーザーシステム、注文システムなどの実世界シナリオを含む

- **原子操作ワーカーテスト**: `cargo run --example atomic_worker_test`
  - 純粋原子操作ワーカーパフォーマンステスト
  - 原子インクリメント、取得、リセット機能を検証
  - 基本並行テストを含む

### ⚠️ 非推奨サンプル（v0.1.4以下）
- `simple_atomic_sequence` - 新統一アーキテクチャに移行済み
- `atomic_operations_test` - EBR競合問題あり、非推奨
- `atomic_mixed_operations` - 並行性制限あり、非推奨

### 🔄 移行提案

**旧バージョンのサンプルを使用している場合**：

❌ **使用しないでください**（EBR競合あり）：
```bash
cargo run --example atomic_mixed_operations  # クラッシュします
cargo run --example simple_atomic_test       # 問題あり
```

✅ **推奨使用**（新統一アーキテクチャ）：
```bash
cargo run --example segqueue_unified_test
cargo run --example high_pressure_segqueue_test
cargo run --example atomic_worker_test
```

### 📊 パフォーマンステストサンプル
- **`performance_demo.rs`** - 基本的なパフォーマンスデモとスマートフラッシュ戦略のショーケース
- **`accurate_timing_demo.rs`** - P50/P95/P99統計を含む正確なタイミング分析

### 🎯 圧縮サンプル
- **`macbook_air_m1_compression_none.rs`** - 無圧縮究極パフォーマンス
- **`macbook_air_m1_compression_lz4.rs`** - NEONアクセラレーションLZ4圧縮
- **`macbook_air_m1_compression_zstd.rs`** - 高圧縮率Zstd

### 🎯 ベストプラクティスサンプル
- **`best_practices.rs`** - 完全な本番環境使用例

### サンプルの実行

```bash
# 原子操作統一アーキテクチャテストを実行
cargo run --example segqueue_unified_test
cargo run --example high_pressure_segqueue_test
cargo run --example atomic_worker_test

# 基本的なパフォーマンスデモを実行
cargo run --example performance_demo

# 正確なタイミング分析を実行
cargo run --example accurate_timing_demo

# 圧縮アルゴリズムパフォーマンス比較を実行
cargo run --example macbook_air_m1_compression_none --features compression-none --release
cargo run --example macbook_air_m1_compression_lz4 --features compression-lz4 --release
cargo run --example macbook_air_m1_compression_zstd --features compression-zstd --release
```

## ライセンス

このプロジェクトはLGPL-3.0ライセンスの下で提供されています - 詳細は[LICENSE](LICENSE)ファイルを参照してください。

## コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを提出してください。

## 謝辞

- 優れた[sled](https://github.com/spacejam/sled)データベースアーキテクチャに基づいています
- フランク・ハーバートの「デューン」宇宙にインスパイアされています
- フィードバックと提案を提供してくれたすべてのコントリビューターとユーザーに感謝します