datavoxel 0.2.0

Type-Safe Modern ORM - Data in 3D

██████╗  █████╗ ████████╗ █████╗ ██╗   ██╗ ██████╗ ██╗  ██╗███████╗██╗     
██╔══██╗██╔══██╗╚══██╔══╝██╔══██╗██║   ██║██╔═══██╗╚██╗██╔╝██╔════╝██║     
██║  ██║███████║   ██║   ███████║██║   ██║██║   ██║ ╚███╔╝ █████╗  ██║     
██║  ██║██╔══██║   ██║   ██╔══██║╚██╗ ██╔╝██║   ██║ ██╔██╗ ██╔══╝  ██║     
██████╔╝██║  ██║   ██║   ██║  ██║ ╚████╔╝ ╚██████╔╝██╔╝ ██╗███████╗███████╗
╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝  ╚═══╝   ╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝

🗄️ Type-Safe Modern ORM 🗄️

Data in 3D - Where Database Queries Feel Like Magic

Quick Start • Features • Examples • Documentation

🌟 What is DATAVOXEL?

DATAVOXEL is a revolutionary ORM that thinks in 3 dimensions: Type Safety, Developer Experience, and Performance. Built on SQLAlchemy but with a modern twist, it makes database operations feel natural and intuitive.

from datavoxel import Model, Query

class User(Model):
    __table__ = "users"
    
    id: int
    name: str
    email: str
    created_at: datetime

# Type-safe queries with IDE autocomplete!
users = Query(User).where(User.age > 18).order_by(User.name).limit(10).all()
# 🎯 Your IDE knows exactly what type 'users' is!

---

✨ Key Features

🎯 Type Safety ✅ Full Type Hints - IDE autocomplete everywhere 🔍 Mypy Compatible - Catch errors before runtime 📝 IntelliSense - See available fields instantly 🛡️ Compile-Time Checks - No more typos	⚡ Performance 🚀 Async First - Built for async/await 🔄 Connection Pooling - Reuse connections 💾 Query Caching - Automatic optimization 📊 Lazy Loading - Load data when needed
🎨 Developer Experience 💡 Intuitive API - Reads like English 🔗 Method Chaining - Build queries naturally 🏗️ Auto Migrations - Schema changes made easy 📚 Rich Documentation - Examples for everything	🏗️ Production Ready ✅ Battle Tested - Built on SQLAlchemy 🔒 SQL Injection Safe - Parameterized queries 🌍 Multi-DB Support - Postgres, MySQL, SQLite 📈 Scalable - From MVP to millions of rows

---

📦 Installation

# Basic installation (SQLite support)
pip install datavoxel

# With PostgreSQL support
pip install datavoxel[postgres]

# With MySQL support  
pip install datavoxel[mysql]

# With all database drivers
pip install datavoxel[all]

---

🎯 Quick Start

Define Your Models

from datavoxel import Model
from datetime import datetime
from typing import Optional

class User(Model):
    __table__ = "users"
    __database__ = "myapp"
    
    id: int
    username: str
    email: str
    is_active: bool = True
    created_at: datetime = datetime.now()
    bio: Optional[str] = None

Simple CRUD Operations

# Create
user = User(username="john_doe", email="[e-mail]")
await user.save()

# Read
user = await User.get(id=1)
users = await User.filter(is_active=True).all()

# Update
user.email = "[e-mail]"
await user.save()

# Delete
await user.delete()

Advanced Queries

from datavoxel import Query, Q

# Complex WHERE clauses
active_users = await Query(User).where(
    (User.is_active == True) & 
    (User.created_at > datetime(2024, 1, 1))
).all()

# Joins
class Post(Model):
    __table__ = "posts"
    user_id: int
    title: str
    content: str

posts_with_users = await Query(Post).join(
    User, Post.user_id == User.id
).select(Post.title, User.username).all()

# Aggregations
from datavoxel import Count, Avg

user_count = await Query(User).aggregate(Count(User.id))
avg_age = await Query(User).aggregate(Avg(User.age))

---

🏗️ Architecture

graph TB
    A[Your Application] --> B[DATAVOXEL ORM]
    
    B --> C{Query Builder}
    B --> D{Model Manager}
    B --> E{Migration Engine}
    
    C --> F[Type Checker]
    C --> G[SQL Generator]
    
    D --> H[CRUD Operations]
    D --> I[Relationships]
    
    E --> J[Schema Diff]
    E --> K[Auto Migrate]
    
    F --> L[SQLAlchemy Core]
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L
    
    L --> M{Database Driver}
    M --> N[PostgreSQL]
    M --> O[MySQL]
    M --> P[SQLite]
    
    style B fill:#2196F3
    style L fill:#4CAF50

---

🔥 Advanced Features

Relationships

class Author(Model):
    __table__ = "authors"
    id: int
    name: str

class Book(Model):
    __table__ = "books"
    id: int
    title: str
    author_id: int
    
    # Define relationship
    author = Relation(Author, foreign_key="author_id")

# Use relationships
book = await Book.get(id=1)
author = await book.author  # Automatically fetches author
print(f"{book.title} by {author.name}")

Transactions

from datavoxel import transaction

async with transaction():
    user = User(username="alice")
    await user.save()
    
    post = Post(title="First Post", user_id=user.id)
    await post.save()
    
    # Both saved or both rolled back together!

Query Optimization

# Eager loading (N+1 query prevention)
books = await Query(Book).prefetch(Book.author).all()
# Only 2 queries instead of N+1!

# Select only needed fields
users = await Query(User).only(User.id, User.username).all()
# Smaller result set = faster queries

# Bulk operations
await User.bulk_create([
    User(username="user1", email="[e-mail]"),
    User(username="user2", email="[e-mail]"),
])

Custom Queries

# Raw SQL when needed
results = await Query.raw("""
    SELECT users.name, COUNT(posts.id) as post_count
    FROM users
    LEFT JOIN posts ON users.id = posts.user_id
    GROUP BY users.id
    HAVING post_count > 10
""")

---

📊 Comparison with Other ORMs

Feature	DATAVOXEL	SQLAlchemy	Django ORM	Peewee	Tortoise
Type Safety	✅ Full	⚠️ Partial	❌ No	❌ No	⚠️ Partial
Async Support	✅ Native	✅ Yes	⚠️ Limited	❌ No	✅ Yes
Learning Curve	🟢 Easy	🔴 Hard	🟢 Easy	🟢 Easy	🟡 Medium
Auto Migrations	✅ Built-in	⚠️ Alembic	✅ Yes	❌ No	✅ Yes
IDE Support	⚡⚡⚡⚡⚡	⚡⚡	⚡⚡	⚡⚡	⚡⚡⚡
Performance	⚡⚡⚡⚡	⚡⚡⚡⚡⚡	⚡⚡⚡	⚡⚡⚡⚡	⚡⚡⚡⚡

---

🎨 Real-World Examples

FastAPI Integration

from fastapi import FastAPI, Depends
from datavoxel import Model, Query

app = FastAPI()

class User(Model):
    __table__ = "users"
    id: int
    username: str
    email: str

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    user = await User.get(id=user_id)
    return user.dict()  # Automatic serialization!

@app.get("/users")
async def list_users(skip: int = 0, limit: int = 10):
    users = await Query(User).offset(skip).limit(limit).all()
    return [user.dict() for user in users]

Data Pipeline

from datavoxel import Model, transaction
import asyncio

class RawData(Model):
    __table__ = "raw_data"
    id: int
    data: str

class ProcessedData(Model):
    __table__ = "processed_data"
    id: int
    result: str

async def process_data():
    raw_items = await Query(RawData).filter(processed=False).all()
    
    async with transaction():
        for item in raw_items:
            # Process data
            result = transform(item.data)
            
            # Save result
            processed = ProcessedData(result=result)
            await processed.save()
            
            # Mark as processed
            item.processed = True
            await item.save()

Multi-Tenant App

from datavoxel import Model, set_schema

class Tenant(Model):
    __table__ = "tenants"
    id: int
    schema_name: str

class User(Model):
    __table__ = "users"
    __schema_bound__ = True  # Uses current schema
    id: int
    name: str

async def get_tenant_users(tenant_id: int):
    tenant = await Tenant.get(id=tenant_id)
    
    # Switch to tenant schema
    set_schema(tenant.schema_name)
    
    # Query tenant-specific data
    users = await Query(User).all()
    return users

---

📚 Documentation

• 📖 Full API Reference
• 🚀 Quick Start Guide
• 🎓 Tutorial
• 🏗️ Migrations Guide
• 🎯 Best Practices

---

🗺️ Roadmap

✅ Version 0.1.0 (Current)

• Type-safe models
• Basic CRUD operations
• Query builder
• Async support

🚧 Version 0.2.0 (Coming Soon)

• Auto migrations
• Relationship support
• Connection pooling
• Query caching

🔮 Version 0.3.0 (Planned)

• Advanced relationships (M2M, polymorphic)
• Full-text search
• Database sharding
• Performance monitoring
• GraphQL integration

---

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

---

📜 License

MIT License - see LICENSE file for details.

---

👤 Author

Juste Elysée MALANDILA

"Making databases feel like magic." 🗄️

---

Made with ❤️ by Juste Elysée MALANDILA

DATAVOXEL - Data in 3D 🗄️