https://github.com/ashfromsky/yaradb
In-memory-first document DB (Python/FastAPI) with JSON persistence and a "smart" data model.
https://github.com/ashfromsky/yaradb
database db json nosql nosql-database python
Last synced: about 1 month ago
JSON representation
In-memory-first document DB (Python/FastAPI) with JSON persistence and a "smart" data model.
- Host: GitHub
- URL: https://github.com/ashfromsky/yaradb
- Owner: ashfromsky
- License: other
- Created: 2025-10-29T12:27:19.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-11-28T10:35:06.000Z (7 months ago)
- Last Synced: 2026-03-12T07:34:25.446Z (3 months ago)
- Topics: database, db, json, nosql, nosql-database, python
- Language: Python
- Homepage:
- Size: 159 KB
- Stars: 33
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
YaraDB
🚀 Lightning-fast • 🛡️ Crash-safe • 🎯 Developer-friendly
---
## 💎 What Makes YaraDB Special?
### ⚡ **Blazing Performance**
```python
# 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**
```python
# Crash? No problem.
# WAL recovery restores everything
```
✨ **Write-Ahead Logging (WAL)**
✨ **Automatic crash recovery**
✨ **SHA-256 integrity checks**
### 🎯 **Developer Experience**
```python
# One line to start
docker run -p 8000:8000 ashfromsky/yaradb
```
✨ **RESTful API + OpenAPI docs**
✨ **Zero configuration**
✨ **Native Python client**
### 🔧 **Smart Flexibility**
```python
# 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:**
```bash
docker pull ashfromsky/yaradb:latest
docker run -d \
--name yaradb_server \
-p 8000:8000 \
-v $(pwd)/data:/data \
ashfromsky/yaradb:latest
```
**Windows (PowerShell):**
```powershell
docker pull ashfromsky/yaradb:latest
docker run -d `
--name yaradb_server `
-p 8000:8000 `
-v ${PWD}/data:/data `
ashfromsky/yaradb:latest
```
**Windows (CMD):**
```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
```yaml
services:
yaradb:
image: ashfromsky/yaradb
ports: ["8000:8000"]
volumes: ["./data:/data"]
```
**Easy** • One command deploy
### 🐍 From Source
```bash
git clone https://github.com/illusiOxd/yaradb
cd yaradb
pip install -r requirements.txt
python main.py
```
**Development** • Full control
**Verify it's running:**
```bash
curl http://localhost:8000/ping
# {"status":"alive"} ✅
```
**Explore the API:**
👉 **http://localhost:8000/docs** 👈
---
## 💻 Usage Examples
### 🌐 REST API
```bash
# 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"
}
}'
```
```bash
# Get by ID
curl http://localhost:8000/document/get/{doc_id}
```
```bash
# Update with version control
curl -X PUT http://localhost:8000/document/update/{doc_id} \
-d '{"version": 1, "body": {"name": "Alice Smith"}}'
```
```bash
# Soft delete
curl -X PUT http://localhost:8000/document/archive/{doc_id}
```
### 🐍 Python Client
**Install:**
```bash
pip install yaradb-client
```
**Use:**
```python
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**
1. Validate request
2. Append to WAL
3. Update memory
4. Return success
~2ms latency
### 📖 **Read Path**
1. Hash lookup
2. Return from RAM
3. Done!
<1ms latency
### 🔄 **Crash Recovery**
1. Load snapshot
2. Replay WAL
3. Rebuild index
4. Ready!
Automatic on startup
### 💾 **Checkpoints**
1. Serialize state
2. Write snapshot
3. Truncate WAL
4. 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](https://github.com/illusiOxd/yaradb/wiki)
Full guides, tutorials, and best practices
### 🔌 [API Reference](https://github.com/illusiOxd/yaradb/wiki/API-Reference)
REST endpoints, schemas, and examples
### 🏗️ [Architecture Deep Dive](https://github.com/illusiOxd/yaradb/wiki/Architecture)
WAL internals, OCC, and design decisions
### 🌟 Alternative Resources
[](https://www.notion.so/YaraDB-Complete-Documentation-29ed5746db8c80fca39defa67e9d8ef4)
[](https://github.com/illusiOxd/yaradb-client-py)
[](https://github.com/illusiOxd/yaradb/discussions)
---
## 🤝 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 →](https://github.com/illusiOxd/yaradb/issues/new?template=bug_report.md)
### 💡 Request Features
Have an idea?
[Share It →](https://github.com/illusiOxd/yaradb/issues/new?template=feature_request.md)
### 📝 Improve Docs
Make it clearer
[Edit on GitHub →](https://github.com/illusiOxd/yaradb/wiki)
### 🔧 Submit Code
Fork • Code • PR
[Guidelines →](.github/CONTRIBUTING.md)
**Read our** [Code of Conduct](.github/CODE_OF_CONDUCT.md) • [Contributing Guide](.github/CONTRIBUTING.md)
---
## 📜 License & Legal
**Server Side Public License (SSPL)**
© 2025 Tymofii Shchur Viktorovych
[Read Full License →](LICENSE)
Free for development and internal use • Contact for commercial SaaS deployment
---
## 🔗 Connect With Us
**Built with passion by** [**illusiOxd**](https://github.com/illusiOxd)
⭐ **Star us on GitHub if YaraDB powers your project!** ⭐
