# yaradb
**Repository Path**: py-service/yaradb
## Basic Information
- **Project Name**: yaradb
- **Description**: https://github.com/illusiOxd/yaradb 是FastAPI与Pydantic“天作之合”的教科书级案例。 https://mp.weixin.qq.com/s/wIFbtd956l8OAvi9vuKY8g
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-11
- **Last Updated**: 2026-01-11
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
---
## 💎 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
---
YaraDB
**Built with passion by** [**illusiOxd**](https://github.com/illusiOxd)
