Documentation

Everything you need to build with CubeDB

Quick Start

Get CubeDB up and running in under 5 minutes.

Prerequisites

Java 21 or later
Maven 3.6+
4GB RAM minimum

Build from Source

# Clone repository
git clone https://github.com/cubecactus/cubecactus.git
cd cubecactus

# Build
mvn clean package -DskipTests

# Run single node
java -jar target/cubecactus-1.0.0.jar \
  --node-id=node-1 \
  --port=8080

✓ Success! CubeCactus is now running on http://localhost:8080

Execute Your First Query

# Create a table
curl -X POST http://localhost:8080/api/v1/sql/execute \
  -H "Content-Type: application/json" \
  -d '{"sql": "CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT, email TEXT)"}'

# Insert data
curl -X POST http://localhost:8080/api/v1/sql/execute \
  -H "Content-Type: application/json" \
  -d '{"sql": "INSERT INTO users VALUES ('\''1'\'', '\''Alice'\'', '\''alice@example.com'\'')"}'

# Query data
curl -X POST http://localhost:8080/api/v1/sql/execute \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users WHERE id = '\''1'\''"}'

Installation

Docker

# Pull image
docker pull cubecactus/cubecactus:latest

# Run
docker run -d \
  --name cubecactus \
  -p 8080:8080 \
  cubecactus/cubecactus:latest

Docker Compose (3-Node Cluster)

# Start cluster
docker-compose up -d

# Check status
docker-compose ps

Kubernetes

# Deploy StatefulSet
kubectl apply -f k8s/statefulset.yaml

# Check pods
kubectl get pods -n cubedb

Architecture

CubeCactus is a distributed column-family database inspired by Apache Cassandra, built with modern cloud-native principles.

Core Components

LSM Storage Engine

Write-optimized storage with MemTable, SSTable, and WAL

Gossip Protocol

SWIM-based membership and failure detection

Query Engine

SQL and CQL parser with query execution

Replication Manager

Configurable RF with hinted handoff

Consistency Levels

CubeDB supports tunable consistency for read and write operations.

Level	Description	Use Case
`ONE`	Fastest, returns after 1 node responds	High throughput, eventual consistency
`QUORUM`	Majority of replicas (RF/2 + 1)	Balanced performance and consistency
`ALL`	All replicas must respond	Strong consistency, critical data

SQL Support

CubeDB supports standard SQL syntax for familiar database operations.

Supported Operations

-- CREATE TABLE
CREATE TABLE users (
    id TEXT PRIMARY KEY,
    name TEXT,
    email TEXT,
    age TEXT
);

-- INSERT
INSERT INTO users (id, name, email, age) 
VALUES ('1', 'Alice', 'alice@example.com', '30');

-- SELECT
SELECT * FROM users WHERE id = '1';
SELECT name, email FROM users WHERE id = '1';

-- UPDATE
UPDATE users SET age = '31' WHERE id = '1';

-- DELETE
DELETE FROM users WHERE id = '1';

Gossip Protocol

CubeCactus uses SWIM (Scalable Weakly-consistent Infection-style Membership) protocol for cluster membership.

How It Works

Heartbeat: Nodes increment heartbeat counters every gossip interval
State Exchange: Nodes randomly select 3 peers and exchange cluster state
Failure Detection: Nodes missing heartbeats are marked SUSPECTED, then DEAD
Convergence: All nodes eventually see consistent cluster state

⚠ Configuration: Tune gossip intervals and timeouts based on your network latency. Default values work for most deployments.

Docker Deployment

Single Node

docker run -d \
  --name cubecactus-node1 \
  -p 8080:8080 \
  -e NODE_ID=node-1 \
  -v cubecactus-data:/var/lib/cube/data \
  cubecactus/cubecactus:latest

3-Node Cluster

# Use docker-compose.yml
services:
  cubecactus-node-1:
    image: cubecactus/cubecactus:latest
    ports:
      - "8080:8080"
    environment:
      - NODE_ID=node-1
      - SEEDS=cubecactus-node-2:7946,cubecactus-node-3:7946
      
  cubecactus-node-2:
    image: cubecactus/cubecactus:latest
    ports:
      - "8081:8080"
    environment:
      - NODE_ID=node-2
      - SEEDS=cubecactus-node-1:7946,cubecactus-node-3:7946
      
  cubecactus-node-3:
    image: cubecactus/cubecactus:latest
    ports:
      - "8082:8080"
    environment:
      - NODE_ID=node-3
      - SEEDS=cubecactus-node-1:7946,cubecactus-node-2:7946

Production Deployment

Best Practices

Replication Factor: Use RF=3 for production
Consistency: Use QUORUM for balanced performance
Monitoring: Enable metrics and health checks
Backups: Regular snapshots of data directories
Resources: Minimum 4 cores, 8GB RAM per node

Scaling

# Add new node to cluster
java -jar cubecactus.jar \
  --node-id=node-4 \
  --port=8083 \
  --seeds=node1:7946,node2:7946,node3:7946

# Verify cluster
curl http://localhost:8080/api/v1/cluster/status