# spyMonk-DB Enterprise

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

## 🚀 Quick Start

```bash
# 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](docs/ARCHITECTURE.md)** - System design and components
- **[Implementation](docs/IMPLEMENTATION_SUMMARY.md)** - Technical details
- **[Enterprise Features](docs/README_ENTERPRISE.md)** - Advanced features
- **[Benchmarks](docs/README_BENCHMARK.md)** - 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)

```python
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)

```python
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](scripts/build_package.sh) for building wheel packages.

See [scripts/private-pypi/](scripts/private-pypi/) for private PyPI setup.

## 🧪 Testing

```bash
# 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](LICENSE) file

---

**For full deployment guide, see the parent project README**
