spymonk-db 0.1.0

Spanner-inspired distributed database with external consistency

spyMonk-DB Enterprise

A Google Spanner-inspired distributed SQL database with external consistency and horizontal scalability.

🚀 Quick Start

# Install from PyPI
pip3 install spymonk-db

# Start the database server
spymonk-server --port 50051

# Or install from source
git clone https://gitlab.com/shubhajeet.pradhan/spymonk-db2.0.git
cd spymonk-db2.0
pip3 install -e .

📚 Documentation

• Architecture - System design and components
• Implementation - Technical details
• Enterprise Features - Advanced features
• Benchmarks - Performance metrics

🎯 Features

• ✅ External Consistency - Linearizable transactions across distributed nodes
• ✅ Distributed Transactions - ACID guarantees with 2-Phase Commit
• ✅ MVCC - Multi-Version Concurrency Control for lock-free reads
• ✅ Paxos Consensus - Leader-based replication with automatic failover
• ✅ LSM-Tree Storage - Write-optimized storage with WAL
• ✅ SQL Support - Standard SQL query interface

💻 Usage

Embedded Mode (Single Node)

from spymonk_enterprise.client import SpyMonkClient

client = SpyMonkClient("/tmp/spymonk_data")
client.start()

# Simple operations
client.put(b"key", b"value")
value = client.get(b"key")

client.stop()

Distributed Mode (Cluster)

from spymonk_enterprise.client import DistributedClient

client = DistributedClient([
    "node1.example.com:5000",
    "node2.example.com:5001",
    "node3.example.com:5002"
])

# Use same API as embedded mode
client.put(b"key", b"value")

📦 Package Distribution

See scripts/build_package.sh for building wheel packages.

See scripts/private-pypi/ for private PyPI setup.

🧪 Testing

# Run unit tests
pytest tests/

# Run benchmarks
python benchmarks/throughput.py

🏗️ Project Structure

spyMonk-DB/
├── spymonk_enterprise/     # Core implementation
│   ├── client/             # Client SDK
│   ├── storage/            # LSM-Tree & MVCC
│   ├── transaction/        # Transaction manager
│   ├── replication/        # Paxos consensus
│   ├── time/               # Hybrid Logical Clock
│   ├── sql/                # SQL parser & executor
│   └── schema/             # Directory & schemas
├── docs/                   # Documentation
├── scripts/                # Build & deployment scripts
├── tests/                  # Test suite
├── benchmarks/             # Performance benchmarks
└── examples/               # Usage examples

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📄 License

MIT License - See LICENSE file

---

For full deployment guide, see the parent project README