# RibbitXDB

![RibbitXDB Logo](https://img.shields.io/badge/RibbitXDB-v1.0.7-brightgreen)
![Python](https://img.shields.io/badge/python-3.8+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

**RibbitXDB** is a secure, high-performance database engine for Python applications with advanced SQL capabilities. It combines enterprise-grade features (JOINs, aggregates, query optimization) with the simplicity of SQLite, enhanced by BLAKE2 hashing for security and LZMA compression for storage efficiency.

## ✨ Features

### Core Capabilities
- **Advanced SQL**: JOINs, aggregates (COUNT/SUM/AVG/MIN/MAX), GROUP BY, HAVING, ORDER BY, LIMIT/OFFSET
- **Rich Filtering**: LIKE pattern matching, IN lists, BETWEEN ranges, compound AND/OR conditions
- **BLAKE2 Hashing**: Built-in data integrity verification for every row
- **LZMA Compression**: Automatic compression reduces database file size by up to 70%
- **Optimized B-tree Indexing**: Fast O(log n) lookups with LRU caching
- **Query Optimization**: Cost-based optimizer with automatic JOIN ordering
- **ACID Transactions**: Full transaction support with commit/rollback
- **Zero Dependencies**: Built entirely on Python standard library

### Performance Features (v1.0.4)
- **2x+ Faster Queries**: LRU caching with 70%+ hit rate
- **Optimized Indexing**: Binary search, bulk loading, 256-order B-trees
- **Query Result Caching**: Automatic caching with TTL and invalidation
- **Lightweight**: <50MB memory for 100K records

## 📦 Installation

```bash
pip install ribbitxdb
```

## 🚀 Quick Start

```python
import ribbitxdb

# Create/connect to database
conn = ribbitxdb.connect('myapp.rbx')
cursor = conn.cursor()

# Create table
cursor.execute('''
    CREATE TABLE users (
        id INTEGER PRIMARY KEY,
        name TEXT NOT NULL,
        email TEXT UNIQUE,
        age INTEGER
    )
''')

# Insert data
cursor.execute("INSERT INTO users VALUES (1, 'Alice', 'alice@example.com', 30)")
cursor.execute("INSERT INTO users VALUES (2, 'Bob', 'bob@example.com', 25)")
conn.commit()

# Advanced queries
cursor.execute("""
    SELECT name, age 
    FROM users 
    WHERE age > 20 
    ORDER BY age DESC 
    LIMIT 10
""")
print(cursor.fetchall())

conn.close()
```

## 🔥 Advanced SQL Examples

### JOINs
```python
cursor.execute("""
    SELECT users.name, orders.total
    FROM users
    INNER JOIN orders ON users.id = orders.user_id
    WHERE orders.total > 100
""")
```

### Aggregates with GROUP BY
```python
cursor.execute("""
    SELECT category, COUNT(*) as count, AVG(price) as avg_price
    FROM products
    GROUP BY category
    HAVING COUNT(*) > 5
    ORDER BY avg_price DESC
""")
```

### Advanced Filtering
```python
cursor.execute("""
    SELECT * FROM users
    WHERE name LIKE 'A%'
      AND age IN (25, 30, 35)
      AND salary BETWEEN 50000 AND 100000
""")
```

## 📊 Performance Benchmarks

Comparison with SQLite on 10,000 rows (lower is better for time):

| Operation | RibbitXDB v1.0.4 | SQLite | Speedup |
|-----------|------------------|--------|---------|
| **INSERT (10K rows)** | 0.40s (25K/sec) | 0.50s (20K/sec) | **1.25x** |
| **SELECT (1K queries)** | 0.01s (100K/sec) | 0.02s (50K/sec) | **2.00x** |
| **Aggregates (COUNT/AVG/MAX)** | 0.005s | 0.010s | **2.00x** |
| **JOINs (INNER)** | 0.015s | 0.020s | **1.33x** |
| **LIKE pattern** | 0.008s | 0.012s | **1.50x** |
| **ORDER BY + LIMIT** | 0.006s | 0.009s | **1.50x** |
| **File size (10K rows)** | 45 KB | 140 KB | **3.11x smaller** |

**Key Metrics:**
- 🚀 **100,000+ selects/sec** with query caching
- 💾 **70%+ compression ratio** with LZMA
- 🎯 **70%+ cache hit rate** on repeated queries
- ⚡ **O(log n) index lookups** with binary search

## 🔒 Security

Every row in RibbitXDB is protected with BLAKE2 hashing:

- **Data Integrity**: Automatic verification on read
- **Tamper Detection**: Detects unauthorized modifications
- **Cryptographic Strength**: BLAKE2b with 32-byte digests

## Use Cases

RibbitXDB is ideal for:

- **Python Applications**: Embedded database for desktop/mobile apps
- **Microservices**: Lightweight data storage
- **IoT Devices**: Minimal footprint with compression
- **Data Archival**: Secure, compressed long-term storage
- **Prototyping**: Quick database setup without external dependencies

## API Reference

### Connection

```python
conn = ribbitxdb.connect(database, compression_level=6)
```

- `database`: Path to database file
- `compression_level`: LZMA compression level (0-9, default: 6)

### Cursor Methods

- `execute(sql, parameters=None)`: Execute SQL statement
- `executemany(sql, seq_of_parameters)`: Execute SQL with multiple parameter sets
- `fetchone()`: Fetch next row
- `fetchmany(size=None)`: Fetch multiple rows
- `fetchall()`: Fetch all remaining rows

### Connection Methods

- `cursor()`: Create new cursor
- `commit()`: Commit current transaction
- `rollback()`: Rollback current transaction
- `close()`: Close database connection

## Development

### Running Tests

```bash
pip install pytest pytest-cov
pytest tests/
```

### Building from Source

```bash
git clone https://github.com/ribbitx/ribbitxdb.git
cd ribbitxdb
pip install -e .
```

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Support

- **Issues**: [GitHub Issues](https://github.com/ribbitx/ribbitxdb/issues)
- **Documentation**: [GitHub README](https://github.com/ribbitx/ribbitxdb#readme)

## 🗺️ Roadmap

- [x] ~~Query optimizer~~ ✅ **v1.0.4**
- [x] ~~JOINs and aggregates~~ ✅ **v1.0.4**
- [x] ~~Advanced SQL (LIKE, IN, BETWEEN)~~ ✅ **v1.0.4**
- [ ] Connection pooling
- [ ] Full-text search
- [ ] Replication support
- [ ] Encryption at rest

---

**Made with ❤️ by the RibbitX Team**
