Cube Database - Phase 1 Complete ✅

A Cassandra-like distributed database with 100% pure Java LSM storage engine - no native dependencies!

Features

✅ Pure Java LSM Storage Engine - No RocksDB, no C++
✅ Write-Ahead Log (WAL) - Crash recovery and durability
✅ In-Memory MemTable - Fast writes with ConcurrentSkipListMap
✅ On-Disk SSTables - Sorted string tables for persistence
✅ Background Compaction - Automatic space reclamation
✅ Prefix Scanning - Efficient range queries
✅ REST API - HTTP interface with JSON
✅ Thread-Safe - Concurrent reads and writes

Quick Start

1. Build the Project

cd cube-db
mvn clean package

2. Run the Server

java -jar target/cube-db-1.0.0.jar

Or with Maven:

mvn spring-boot:run

The server starts on http://localhost:8080

3. Test the API

# Health check
curl http://localhost:8080/api/v1/health

# Put a value
curl -X POST http://localhost:8080/api/v1/put \
  -H "Content-Type: application/json" \
  -d '{"key": "user:1", "value": "Alice"}'

# Get a value
curl http://localhost:8080/api/v1/get/user:1

# Scan with prefix
curl "http://localhost:8080/api/v1/scan?prefix=user:"

# Get statistics
curl http://localhost:8080/api/v1/stats

API Reference

PUT - Store a value

POST /api/v1/put
Body: {"key": "mykey", "value": "myvalue"}

Response:
{
  "success": true,
  "message": "Value stored successfully",
  "key": "mykey"
}

GET - Retrieve a value

GET /api/v1/get/{key}

Response:
{
  "success": true,
  "found": true,
  "key": "mykey",
  "value": "myvalue"
}

DELETE - Remove a value

DELETE /api/v1/delete/{key}

Response:
{
  "success": true,
  "message": "Key deleted",
  "key": "mykey"
}

SCAN - Prefix search

GET /api/v1/scan?prefix=user:

Response:
{
  "success": true,
  "prefix": "user:",
  "count": 2,
  "results": {
    "user:1": "Alice",
    "user:2": "Bob"
  }
}

STATS - Storage statistics

GET /api/v1/stats

Response:
{
  "success": true,
  "stats": {
    "totalKeys": 100,
    "totalSize": 52432,
    "memtableSize": 2048,
    "sstableCount": 1
  }
}

FLUSH - Force memtable flush

POST /api/v1/flush

Response:
{
  "success": true,
  "message": "Flush completed"
}

COMPACT - Trigger compaction

POST /api/v1/compact

Response:
{
  "success": true,
  "message": "Compaction completed"
}

Programmatic Usage

Basic Operations

import com.cube.storage.LSMStorageEngine;

// Create storage engine
LSMStorageEngine storage = new LSMStorageEngine("/tmp/my-data");

// Write
storage.put("user:1", "Alice".getBytes());
storage.put("user:2", "Bob".getBytes());

// Read
byte[] value = storage.get("user:1");
System.out.println(new String(value)); // "Alice"

// Update
storage.put("user:1", "Alice Johnson".getBytes());

// Delete
storage.delete("user:2");

// Close
storage.close();

Prefix Scanning

// Store hierarchical data
storage.put("user:1:name", "Alice".getBytes());
storage.put("user:1:email", "alice@example.com".getBytes());
storage.put("user:2:name", "Bob".getBytes());

// Scan for prefix
Iterator<Map.Entry<String, byte[]>> entries = storage.scanEntries("user:1:");

while (entries.hasNext()) {
    Map.Entry<String, byte[]> entry = entries.next();
    System.out.println(entry.getKey() + " = " + new String(entry.getValue()));
}

// Output:
// user:1:email = alice@example.com
// user:1:name = Alice

Batch Operations

// Insert 1000 records
for (int i = 0; i < 1000; i++) {
    storage.put("item:" + i, ("value:" + i).getBytes());
}

// Flush to disk
storage.flush();

// Get statistics
StorageEngine.StorageStats stats = storage.getStats();
System.out.println("Keys: " + stats.getTotalKeys());
System.out.println("SSTables: " + stats.getSstableCount());

Running Examples

# Compile and run examples
mvn compile
mvn exec:java -Dexec.mainClass="com.cube.examples.CubeExamples"

Running Tests

# Run all tests
mvn test

# Run specific test
mvn test -Dtest=CubeStorageEngineTest

# Run with verbose output
mvn test -X

Configuration

System Properties

# Data directory
-Dcube.datadir=/path/to/data

# Server port
-Dserver.port=8080

Application Properties

Edit src/main/resources/application.properties:

server.port=8080
cube.datadir=/tmp/cube-data
logging.level.com.cube=INFO

Architecture

┌─────────────────────────────────────┐
│         Cube Database               │
├─────────────────────────────────────┤
│                                     │
│  ┌──────────┐    ┌──────────────┐  │
│  │ MemTable │◄───┤ Write-Ahead  │  │
│  │          │    │ Log (WAL)    │  │
│  └────┬─────┘    └──────────────┘  │
│       │ Flush                       │
│       ▼                             │
│  ┌──────────────────────┐          │
│  │  Immutable MemTables │          │
│  └──────┬───────────────┘          │
│         │ Background Flush         │
│         ▼                           │
│  ┌──────────────────────┐          │
│  │ SSTables (on disk)   │          │
│  │  ┌────┐ ┌────┐       │          │
│  │  │SST1│ │SST2│ ...   │          │
│  │  └────┘ └────┘       │          │
│  └──────┬───────────────┘          │
│         │ Compaction               │
│         ▼                           │
│  ┌──────────────────────┐          │
│  │ Compacted SSTable    │          │
│  └──────────────────────┘          │
│                                     │
└─────────────────────────────────────┘

Performance

Benchmarks (i7-12700, 32GB RAM, NVMe SSD)

File Structure

cube-db/
├── pom.xml
├── README.md
├── src/
│   ├── main/
│   │   ├── java/com/cube/
│   │   │   ├── CubeApplication.java
│   │   │   ├── api/
│   │   │   │   └── CubeController.java
│   │   │   ├── storage/
│   │   │   │   ├── StorageEngine.java
│   │   │   │   ├── LSMStorageEngine.java
│   │   │   │   ├── MemTable.java
│   │   │   │   ├── SSTable.java
│   │   │   │   └── WriteAheadLog.java
│   │   │   └── examples/
│   │   │       └── CubeExamples.java
│   │   └── resources/
│   │       └── application.properties
│   └── test/
│       └── java/com/cube/storage/
│           └── CubeStorageEngineTest.java
└── target/
    └── cube-db-1.0.0.jar

Troubleshooting

Port already in use

# Use different port
java -Dserver.port=9090 -jar target/cube-db-1.0.0.jar

Out of memory

# Increase heap size
java -Xmx2G -jar target/cube-db-1.0.0.jar

Data directory permission denied

# Use different directory
java -Dcube.datadir=/home/user/cube-data -jar target/cube-db-1.0.0.jar

Next Steps

• Phase 2: Consistency & Replication
• Phase 3: Bloom Filters & Compression
• Phase 4: Secondary Indexes
• Phase 5: CQL Query Language

License

Apache License 2.0

Built with ❤️ in 100% Pure Java
No native dependencies. Runs anywhere! 🎉