# FlexiDB

**Repository Path**: kingecg/flexi-db

## Basic Information

- **Project Name**: FlexiDB
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-02-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FlexiDB - Embedded Hybrid Database

[![GitHub Actions CI](https://github.com/kingecg/flexi-db/workflows/CI/badge.svg)](https://github.com/kingecg/flexi-db/actions) [![Gitee CI](https://gitee.com/kingecg/flexi-db/badge.svg?branch=main)](https://gitee.com/kingecg/flexi-db)

FlexiDB is an embedded database that simultaneously supports both relational SQL operations and MongoDB-style document operations, written in Rust.

## Features

- **Dual Data Models**: Support for both relational tables and document collections
- **ACID Transactions**: Full transaction support with commit/rollback, isolation levels, and durability
- **Aggregation Pipeline**: MongoDB-style aggregation framework with $match, $project, $group, $sort, and more
- **High Performance**: Optimized for low latency and memory footprint
- **Embedded**: No separate server process required
- **Rust Native API**: Idiomatic Rust interface with async/await support
- **FFI Interface**: C-compatible API for embedding in other languages
- **Pluggable Storage**: B+Tree and LSM-tree storage engines
- **Cross-Model Queries**: Join relational tables with document collections

## Architecture

FlexiDB follows a modular architecture with 9 independent crates:

```
flexidb/ (workspace root)
├── flexidb-core/         # Core abstractions and types
├── flexidb-storage/      # Storage abstraction layer
├── flexidb-engine-btree/ # B+Tree storage engine
├── flexidb-engine-lsm/   # LSM-tree storage engine (optional)
├── flexidb-sql/          # SQL parsing and execution
├── flexidb-document/     # Document model and query
├── flexidb-hybrid/       # Cross-model query coordination
├── flexidb-api/          # User-friendly public API
└── flexidb-cli/          # Command-line interface
```

## Quick Start

### Prerequisites

- Rust 1.70+ with Cargo
- For development: `cargo`, `rustfmt`, `clippy`

### Building

```bash
# Clone the repository
git clone https://github.com/flexidb/flexidb.git
cd flexidb

# Build all crates
cargo build --workspace

# Run tests
cargo test --workspace

# Run CLI
cargo run --package flexidb-cli -- --help
```

### Example Usage

```rust
use flexidb::{Database, Document};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open a database
    let db = Database::open("test.db").await?;
    
    // SQL operations
    db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, data JSONB)").await?;
    db.execute("INSERT INTO users VALUES (1, '{\"name\": \"Alice\", \"age\": 30}')").await?;
    
    // Document operations
    let coll = db.collection("profiles").await?;
    coll.insert_one(Document::from_json(r#"{ "name": "Bob", "age": 25 }"#)).await?;
    
    // Hybrid query
    let results = db.execute(
        "SELECT u.id, p.* FROM users u JOIN profiles p ON u.data->>'name' = p.name"
    ).await?;
    
    Ok(())
}
```

## Development Roadmap

### Phase 1: Foundation (1-2 months)
- [x] Project scaffolding and workspace setup
- [x] Core type system and error handling
- [x] Storage abstraction layer (page management, cache, WAL)
- [x] B+Tree engine basic functionality
- [x] Documentation framework

### Phase 2: SQL Engine (2-3 months)
- [x] SQL parser and query optimizer
- [x] Query execution engine
- [x] Index support (primary and secondary)
- [x] Transaction support with ACID properties

### Phase 3: Document Engine (2 months)
- [x] Document type system and BSON support
- [x] Collection management
- [x] Document query language (basic)
- [x] Aggregation pipeline

### Phase 4: Hybrid Engine (1-2 months)
- [x] Query coordinator for cross-model queries (basic)
- [x] Unified query interface (basic)
- [ ] Performance optimizations

### Phase 5: Advanced Features (1-2 months)
- [x] User-friendly API layer
- [x] CLI tool
- [ ] Backup/recovery, monitoring
- [ ] Extension functions, triggers, change streams

### Recent Updates (2026-02-06)
- Implemented comprehensive transaction support with ACID properties
- Added transaction coordinator for managing multi-operation transactions
- Implemented isolation levels (Read Uncommitted, Read Committed, Repeatable Read, Serializable)
- Added operation tracking for rollback capability
- Implemented transaction state management and resource cleanup
- Enhanced production readiness with improved error handling throughout codebase
- Removed critical crash points using unsafe `.unwrap()` calls
- Added proper mutex lock error handling in storage and cache layers
- Implemented defensive programming practices for system stability
- Implemented aggregation pipeline with MongoDB-style operations
- Added support for $match, $project, $group, $sort, $limit, $skip, $unwind, $lookup, $addFields, and $count stages
- Implemented accumulator functions ($sum, $avg, $min, $max, $first, $last, $push, $addToSet)
- Implemented expression evaluation system for complex computations
- Integrated aggregation with hybrid query engine
- Implemented secondary index support with `CREATE INDEX` syntax
- Added multi-column index support with leftmost prefix matching
- Implemented unique index constraint enforcement
- Added index range scan for efficient querying
- Integrated index maintenance during INSERT/UPDATE/DELETE operations

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

FlexiDB is dual-licensed under either:
- MIT License ([LICENSE-MIT](LICENSE-MIT))
- Apache License 2.0 ([LICENSE-APACHE](LICENSE-APACHE))

at your option.

## Acknowledgments

FlexiDB draws inspiration from:
- SQLite for embedded simplicity
- PostgreSQL for robust SQL support
- MongoDB for flexible document model
- RocksDB/Sled for storage engine design