Cube Database - Quick Start Guide

5-Minute Setup

Step 1: Prerequisites

Ensure you have Java 21 installed:

java -version
# Should show Java 21 or later

Step 2: Build

cd cube-db
mvn clean package

Expected output:

[INFO] BUILD SUCCESS
[INFO] Total time: 15.432 s

Step 3: Start Server

Option A - Using the startup script:

./start.sh

Option B - Direct Java command:

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

Option C - Using Maven:

mvn spring-boot:run

Wait for:

Started CubeApplication in 3.456 seconds

Step 4: Test the API

Open another terminal and run:

# Test health
curl http://localhost:8080/api/v1/health

# Store data
curl -X POST http://localhost:8080/api/v1/put \
  -H "Content-Type: application/json" \
  -d '{"key":"hello","value":"world"}'

# Retrieve data
curl http://localhost:8080/api/v1/get/hello

Or run the automated test script:

./test-api.sh

Common Operations

Store a Key-Value Pair

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

Get a Value

curl http://localhost:8080/api/v1/get/user:123

Scan by Prefix

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

curl -X POST http://localhost:8080/api/v1/put \
  -H "Content-Type: application/json" \
  -d '{"key":"user:1:email","value":"alice@example.com"}'

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

Delete a Key

curl -X DELETE http://localhost:8080/api/v1/delete/user:123

View Statistics

curl http://localhost:8080/api/v1/stats

Running Examples

# Compile
mvn compile

# Run examples
mvn exec:java -Dexec.mainClass="com.cube.examples.CubeExamples"

Running Tests

# All tests
mvn test

# Specific test
mvn test -Dtest=CubeStorageEngineTest

# With details
mvn test -X

Configuration

Change Port

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

Change Data Directory

java -Dcube.datadir=/path/to/data -jar target/cube-db-1.0.0.jar

Increase Memory

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

Combined

java -Xmx2G \
     -Dserver.port=9090 \
     -Dcube.datadir=/var/lib/cube \
     -jar target/cube-db-1.0.0.jar

Programmatic Usage

Java Example

import com.cube.storage.LSMStorageEngine;

public class MyApp {
    public static void main(String[] args) throws Exception {
        // Create storage
        LSMStorageEngine storage = new LSMStorageEngine("/tmp/mydata");
        
        // Write
        storage.put("key1", "value1".getBytes());
        
        // Read
        byte[] value = storage.get("key1");
        System.out.println(new String(value));
        
        // Close
        storage.close();
    }
}

Troubleshooting

"Port 8080 already in use"

# Find and kill process
lsof -ti:8080 | xargs kill -9

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

"Cannot find or load main class"

# Rebuild
mvn clean package

"Permission denied" on data directory

# Use directory with write permission
java -Dcube.datadir=$HOME/cube-data -jar target/cube-db-1.0.0.jar

Tests failing

# Clean and rebuild
mvn clean test

What's Next?

1. ✅ Phase 1 Complete - Pure Java storage engine
2. ⏭️ Phase 2 - Consistency & replication
3. ⏭️ Phase 3 - Bloom filters & compression
4. ⏭️ Phase 4 - CQL query language

Need Help?

• Check README.md for detailed documentation
• Run examples: mvn exec:java -Dexec.mainClass="com.cube.examples.CubeExamples"
• Check logs in console output

🎉 Congratulations! You're running Cube Database!