YaraDB

🚀 Lightning-fast • 🛡️ Crash-safe • 🎯 Developer-friendly

Quick Start • Documentation • Docker Hub • Python Client

---

💎 What Makes YaraDB Special?

⚡ Blazing Performance # O(1) lookups - Always fast doc = client.get(doc_id) # Sub-millisecond response time ✨ In-memory operations ✨ Hash-based indexing ✨ Zero query overhead	🛡️ Enterprise Reliability # Crash? No problem. # WAL recovery restores everything ✨ Write-Ahead Logging (WAL) ✨ Automatic crash recovery ✨ SHA-256 integrity checks
🎯 Developer Experience # One line to start docker run -p 8000:8000 ashfromsky/yaradb ✨ RESTful API + OpenAPI docs ✨ Zero configuration ✨ Native Python client	🔧 Smart Flexibility # Free mode or strict schemas # Your choice, your rules ✨ Schema-free OR JSON Schema ✨ Optimistic locking (OCC) ✨ Soft deletes built-in

---

🚀 Get Started in 30 Seconds

🐳 Docker Linux / macOS: docker pull ashfromsky/yaradb:latest docker run -d \ --name yaradb_server \ -p 8000:8000 \ -v $(pwd)/data:/data \ ashfromsky/yaradb:latest Windows (PowerShell): docker pull ashfromsky/yaradb:latest docker run -d ` --name yaradb_server ` -p 8000:8000 ` -v ${PWD}/data:/data ` ashfromsky/yaradb:latest Windows (CMD): docker pull ashfromsky/yaradb:latest docker run -d ^ --name yaradb_server ^ -p 8000:8000 ^ -v %cd%/data:/data ^ ashfromsky/yaradb:latest Recommended • Production-ready

📦 Docker Compose services: yaradb: image: ashfromsky/yaradb ports: ["8000:8000"] volumes: ["./data:/data"] Easy • One command deploy

🐍 From Source git clone https://github.com/illusiOxd/yaradb cd yaradb pip install -r requirements.txt python main.py Development • Full control

Verify it's running:

curl http://localhost:8000/ping
# {"status":"alive"} ✅

Explore the API:
👉 http://localhost:8000/docs 👈

---

💻 Usage Examples

🌐 REST API # Create a document curl -X POST http://localhost:8000/document/create \ -H "Content-Type: application/json" \ -d '{ "table_name": "users", "body": { "name": "Alice", "email": "alice@example.com", "role": "admin" } }' # Get by ID curl http://localhost:8000/document/get/{doc_id} # Update with version control curl -X PUT http://localhost:8000/document/update/{doc_id} \ -d '{"version": 1, "body": {"name": "Alice Smith"}}' # Soft delete curl -X PUT http://localhost:8000/document/archive/{doc_id}

🐍 Python Client Install: pip install yaradb-client Use: from yaradb_client import YaraClient client = YaraClient("http://localhost:8000") # Create doc = client.create( table_name="users", body={ "name": "Alice", "email": "alice@example.com", "level": 5 } ) # Read user = client.get(doc["_id"]) # Update (with optimistic locking) updated = client.update( doc_id=doc["_id"], version=doc["version"], body={"name": "Alice", "level": 6} ) # Search results = client.find({"level": 6}) # Archive (soft delete) client.archive(doc["_id"])

---

🏗️ How It Works

╔══════════════════════════════════════════════════════════════╗
║                      🌐 FastAPI REST API                     ║
║                   (OpenAPI • JSON • HTTP/2)                  ║
╚═════════════════════════════╤════════════════════════════════╝
                              │
                              ▼
╔══════════════════════════════════════════════════════════════╗
║                  💾 In-Memory Hash Index                     ║
║              { UUID → Document } - O(1) Lookup               ║
╚═════════════════════════════╤════════════════════════════════╝
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
        ╔═══════════════════╗  ╔═══════════════════╗
        ║   📝 WAL Engine   ║  ║ 🔐 OCC Locking    ║
        ║  Append-Only Log  ║  ║ Version Control   ║
        ╚═════════╤═════════╝  ╚═══════════════════╝
                  │
                  ▼
        ╔═══════════════════╗
        ║ 💿 JSON Storage   ║
        ║ Periodic Snapshot ║
        ╚═══════════════════╝

🎯 Write Path Validate request Append to WAL Update memory Return success ~2ms latency

📖 Read Path Hash lookup Return from RAM Done! <1ms latency

🔄 Crash Recovery Load snapshot Replay WAL Rebuild index Ready! Automatic on startup

💾 Checkpoints Serialize state Write snapshot Truncate WAL Continue Background process

---

🎯 Perfect For

Prototyping Spin up a database in seconds. No complex setup, no configuration files.

Real-Time Apps WebSockets, live dashboards, gaming leaderboards - anywhere speed matters.

Microservices Lightweight data layer for containerized architectures.

Testing Fast, ephemeral test databases. Create, test, destroy.

Edge Computing Low footprint, works anywhere Docker runs.

---

📚 Learn More

📖 Complete Documentation Full guides, tutorials, and best practices

🔌 API Reference REST endpoints, schemas, and examples

🏗️ Architecture Deep Dive WAL internals, OCC, and design decisions

🌟 Alternative Resources

---

🤝 Contributing

We ❤️ contributions from the community!

Whether you're fixing bugs, adding features, improving docs, or sharing ideas — you're welcome here.

🐛 Report Bugs Found an issue? Open an Issue →

💡 Request Features Have an idea? Share It →

📝 Improve Docs Make it clearer Edit on GitHub →

🔧 Submit Code Fork • Code • PR Guidelines →

Read our Code of Conduct • Contributing Guide

---

📜 License & Legal

Server Side Public License (SSPL)
© 2025 Tymofii Shchur Viktorovych

Read Full License →

_{Free for development and internal use • Contact for commercial SaaS deployment}

---

🔗 Connect With Us

Built with passion by illusiOxd

_{⭐ Star us on GitHub if YaraDB powers your project! ⭐}