# Cube Database - Quick Start Guide

## 5-Minute Setup

### Step 1: Prerequisites

Ensure you have Java 21 installed:

```bash
java -version
# Should show Java 21 or later
```

### Step 2: Build

```bash
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:
```bash
./start.sh
```

Option B - Direct Java command:
```bash
java -jar target/cube-db-1.0.0.jar
```

Option C - Using Maven:
```bash
mvn spring-boot:run
```

Wait for:
```
Started CubeApplication in 3.456 seconds
```

### Step 4: Test the API

Open another terminal and run:

```bash
# 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:
```bash
./test-api.sh
```

## Common Operations

### Store a Key-Value Pair

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

### Get a Value

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

### Scan by Prefix

```bash
# 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

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

### View Statistics

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

## Running Examples

```bash
# Compile
mvn compile

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

## Running Tests

```bash
# All tests
mvn test

# Specific test
mvn test -Dtest=CubeStorageEngineTest

# With details
mvn test -X
```

## Configuration

### Change Port

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

### Change Data Directory

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

### Increase Memory

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

### Combined

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

## Programmatic Usage

### Java Example

```java
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"
```bash
# 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"
```bash
# Rebuild
mvn clean package
```

### "Permission denied" on data directory
```bash
# Use directory with write permission
java -Dcube.datadir=$HOME/cube-data -jar target/cube-db-1.0.0.jar
```

### Tests failing
```bash
# 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!**