+
+
+ 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+