A distributed NoSQL database inspired by Apache Cassandra, implementing a Log-Structured Merge-tree (LSM) architecture in Java. DisDB provides high write throughput, horizontal scalability, and fault tolerance for modern distributed applications.
DisDB is a learning-oriented implementation of a Cassandra-like distributed database system. It demonstrates core concepts of distributed databases including:
- LSM Tree Storage Engine: Optimized for write-heavy workloads
- Distributed Architecture: Horizontal scalability across multiple nodes
- Eventual Consistency: CAP theorem trade-offs favoring availability and partition tolerance
- Decentralized Design: Peer-to-peer architecture with no single point of failure
- ✅ LSM Tree Storage: Efficient write operations with background compaction
- ✅ Memtable & SSTable: In-memory buffer with persistent disk storage
- ✅ Write-Ahead Log (WAL): Durability guarantees for write operations
- ✅ Bloom Filters: Fast negative lookups to reduce disk I/O
- ✅ Compaction Strategies: Background merging of SSTables to optimize storage
- 🌐 Consistent Hashing: Even data distribution across cluster nodes
- 🔄 Replication: Configurable replication factor for data redundancy
- 💾 Partition Key-based Sharding: Automatic data partitioning
- 🔍 Gossip Protocol: Node discovery and cluster state management
- ⚡ Tunable Consistency: Configurable read/write consistency levels
- Secondary indexes
- Range queries
- Materialized views
- Multi-datacenter replication
- Compression support
┌─────────────────────────────────────────────────┐
│ Write Path │
├─────────────────────────────────────────────────┤
│ Client Write → WAL → Memtable │
│ ↓ │
│ (When threshold reached) │
│ ↓ │
│ Flush to SSTable │
└─────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────┐
│ Read Path │
├─────────────────────────────────────────────────┤
│ Client Read → Memtable → Bloom Filter │
│ ↓ │
│ SSTable (L0) │
│ ↓ │
│ SSTable (L1) │
│ ↓ │
│ SSTable (Ln) │
└─────────────────────────────────────────────────┘
┌──────────────┐
│ Client │
└──────┬───────┘
│
┌───────┴───────┐
│ Coordinator │
│ Node │
└───────┬───────┘
│
┌────────────┼────────────┐
│ │ │
┌───▼────┐ ┌───▼────┐ ┌───▼────┐
│ Node 1 │ │ Node 2 │ │ Node 3 │
│ (RF=3) │ │ (RF=3) │ │ (RF=3) │
└────────┘ └────────┘ └────────┘
│ │ │
└────────────┴────────────┘
Gossip Protocol
- Java 11 or higher
- Maven 3.6+
- At least 2GB RAM (recommended)
# Clone the repository
git clone https://github.com/suvaidkhan/DisDB.git
cd DisDB
# Build the project
mvn clean package
# Run a single node
java -jar target/disdb-1.0-SNAPSHOT.jarTerminal 1 (Seed Node):
java -jar target/disdb-1.0-SNAPSHOT.jar \
--node-id node1 \
--port 7000 \
--data-dir /tmp/disdb/node1Terminal 2 (Node 2):
java -jar target/disdb-1.0-SNAPSHOT.jar \
--node-id node2 \
--port 7001 \
--data-dir /tmp/disdb/node2 \
--seed-nodes localhost:7000Terminal 3 (Node 3):
java -jar target/disdb-1.0-SNAPSHOT.jar \
--node-id node3 \
--port 7002 \
--data-dir /tmp/disdb/node3 \
--seed-nodes localhost:7000DisDBClient client = new DisDBClient("localhost:7000");// Simple put operation
client.put("users:1001", "name", "Alice");
client.put("users:1001", "email", "alice@example.com");
client.put("users:1001", "age", "28");
// With consistency level
client.put("users:1002", "name", "Bob", ConsistencyLevel.QUORUM);// Simple get operation
String name = client.get("users:1001", "name");
// With consistency level
String email = client.get("users:1001", "email", ConsistencyLevel.ONE);client.delete("users:1001", "age");# Connect to node
disdb-cli --host localhost --port 7000
# Execute commands
DisDB> PUT users:1001 name Alice
OK
DisDB> GET users:1001 name
Alice
DisDB> DELETE users:1001 name
OKcluster:
name: "DisDB Cluster"
replication_factor: 3
storage:
data_directory: /var/lib/disdb/data
commit_log_directory: /var/lib/disdb/commitlog
memtable_size_mb: 64
sstable_compression: none
network:
listen_address: localhost
rpc_port: 9042
storage_port: 7000
compaction:
strategy: size_tiered
max_threshold: 32
min_threshold: 4
consistency:
default_read: ONE
default_write: QUORUM- Write-Ahead Log: Every write is first appended to the commit log for durability
- Memtable: Data is written to an in-memory sorted structure (Memtable)
- Flush: When Memtable reaches threshold, it's flushed to disk as an SSTable
- Compaction: Background process merges SSTables to optimize storage and reads
- Memtable Check: First checks the in-memory Memtable
- Bloom Filter: Uses Bloom filters to quickly eliminate SSTables that don't contain the key
- SSTable Search: Searches SSTables from newest to oldest
- Merge Results: Combines results using timestamp-based conflict resolution
DisDB uses consistent hashing with virtual nodes to distribute data evenly across the cluster:
- Each physical node is assigned multiple virtual nodes (tokens)
- Keys are hashed and assigned to nodes based on the token ring
- Data is replicated to N successive nodes (where N = replication factor)
Data is automatically replicated across multiple nodes:
Replication Factor = 3
Key: "users:1001" (Hash: 12345)
↓
Token Ring:
Node1 (Token: 0-10000)
Node2 (Token: 10001-20000) ← Primary
Node3 (Token: 20001-30000) ← Replica 1
Node1 (Token: 30001-40000) ← Replica 2
DisDB supports tunable consistency:
- ANY: Write succeeds after being written to at least one node
- ONE: Write succeeds after being written to commit log and memtable of one replica
- QUORUM: Write succeeds after being written to (replication_factor / 2 + 1) replicas
- ALL: Write succeeds after being written to all replicas
- ONE: Returns data from the nearest replica
- QUORUM: Returns data after (replication_factor / 2 + 1) replicas respond
- ALL: Returns data after all replicas respond
- Write Latency: O(log n) for Memtable insert
- Read Latency: O(log n) for Memtable + O(k) for SSTable scans where k = number of SSTables
- Space Amplification: ~2-3x due to LSM compaction overhead
- Write Throughput: ~50,000 writes/sec per node (hardware dependent)
- Read Throughput: ~20,000 reads/sec per node (hardware dependent)
# Run unit tests
mvn test
# Run integration tests
mvn verify
# Run performance benchmarks
mvn test -PbenchmarkDisDB/
├── src/main/java/com/disdb/
│ ├── core/
│ │ ├── lsm/
│ │ │ ├── Memtable.java
│ │ │ ├── SSTable.java
│ │ │ ├── WAL.java
│ │ │ └── Compaction.java
│ │ ├── storage/
│ │ │ ├── BloomFilter.java
│ │ │ └── StorageEngine.java
│ │ └── index/
│ │ └── Index.java
│ ├── cluster/
│ │ ├── Node.java
│ │ ├── GossipProtocol.java
│ │ ├── ConsistentHash.java
│ │ └── Replication.java
│ ├── protocol/
│ │ ├── Server.java
│ │ └── Client.java
│ └── util/
│ ├── Hash.java
│ └── Config.java
├── pom.xml
└── README.md
Contributions are welcome! This project is designed for learning, so feel free to:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow Java coding conventions
- Add unit tests for new features
- Update documentation for significant changes
- Keep commits atomic and well-described
- LSM tree implementation
- Basic read/write operations
- Write-ahead logging
- Memtable and SSTable
- Distributed cluster support
- Consistent hashing
- Gossip protocol
- Replication
- Compaction strategies (size-tiered, leveled)
- Bloom filters optimization
- Query language (CQL-like)
- Client drivers
- Advanced features (secondary indexes, materialized views)
- Multi-datacenter replication
- Performance optimizations
- Production hardening
- Cassandra Architecture
- LSM Trees Explained
- Designing Data-Intensive Applications by Martin Kleppmann
- Amazon DynamoDB Paper
This project is licensed under the MIT License - see the LICENSE file for details.
- Inspired by Apache Cassandra's architecture and design principles
- LSM tree concepts from Google's Bigtable and LevelDB
- Distributed systems patterns from Amazon's Dynamo paper
Suvaid Khan - GitHub
Project Link: https://github.com/suvaidkhan/DisDB