surreal-orm-lite 0.4.0

Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.

Surreal ORM Lite

Surreal ORM Lite is a lightweight, Django-style ORM for SurrealDB that uses the official SurrealDB Python SDK. It provides a simple and intuitive interface for database operations with full async support and Pydantic validation.

Why This Project?

This ORM is designed to:

• Use the official SurrealDB SDK (surrealdb>=1.0.8) for maximum compatibility
• Stay lightweight with minimal dependencies
• Keep up-to-date with SurrealDB and SDK releases
• Provide Django-style query syntax that developers love

---

Requirements

Dependency	Version
Python	3.11+
SurrealDB	2.6.0+
Official SDK	surrealdb>=1.0.8
Pydantic	>=2.12.5

---

Installation

pip install surreal-orm-lite

Or with uv:

uv add surreal-orm-lite

---

Quick Start

1. Configure the Connection

from surreal_orm_lite import SurrealDBConnectionManager

SurrealDBConnectionManager.set_connection(
    url="http://localhost:8000",
    user="root",
    password="root",
    namespace="my_namespace",
    database="my_database",
)

2. Define a Model

from surreal_orm_lite import BaseSurrealModel
from pydantic import Field

class User(BaseSurrealModel):
    id: str | None = None
    name: str = Field(..., max_length=100)
    email: str
    age: int = Field(..., ge=0)

3. CRUD Operations

# Create
user = User(name="Alice", email="[e-mail]", age=30)
await user.save()

# Read
user = await User.objects().get("alice_id")
users = await User.objects().filter(age__gte=18).exec()

# Update
user.age = 31
await user.update()

# Or partial update
await user.merge(age=31)

# Delete
await user.delete()

4. QuerySet Methods

# Filter with Django-style lookups
users = await User.objects().filter(
    age__gte=18,
    name__startswith="A"
).exec()

# Ordering
users = await User.objects().order_by("name").exec()
users = await User.objects().order_by("age", OrderBy.DESC).exec()

# Pagination
users = await User.objects().limit(10).offset(20).exec()

# Select specific fields
results = await User.objects().select("name", "email").exec()

# Get first result
user = await User.objects().filter(name="Alice").first()

# Get all records
all_users = await User.objects().all()

# Custom query
results = await User.objects().query(
    "SELECT * FROM User WHERE age > $min_age",
    {"min_age": 21}
)

---

Features

Feature	Status
Async/await support	✅
Pydantic validation	✅
CRUD operations	✅
QuerySet with filters	✅
Django-style lookups	✅
Custom primary keys	✅
HTTP connections	✅
WebSocket connections	✅
Aggregations	✅
GROUP BY	✅
Model Signals	✅

Supported Filter Lookups

• exact (default)
• gt, gte, lt, lte
• in
• contains, icontains
• startswith, istartswith
• endswith, iendswith

5. Aggregations

from surreal_orm_lite import Count, Sum, Avg, Min, Max

# Simple aggregations
count = await User.objects().count()
total = await Order.objects().sum("amount")
avg_age = await User.objects().avg("age")
max_price = await Product.objects().max("price")
min_price = await Product.objects().min("price")

# Check existence
has_admins = await User.objects().filter(role="admin").exists()

# GROUP BY with annotations
results = await User.objects().values("status").annotate(count=Count()).exec()
# [{"status": "active", "count": 42}, {"status": "inactive", "count": 8}]

# Raw SurrealQL queries
results = await User.raw_query(
    "SELECT * FROM User WHERE age > $min_age",
    variables={"min_age": 18}
)

6. Model Signals

from surreal_orm_lite import pre_save, post_save, pre_delete, post_delete

@post_save.connect(User)
async def on_user_saved(sender, instance, created, **kwargs):
    """Called after every User save."""
    if created:
        await send_welcome_email(instance.email)
    await invalidate_cache(f"user:{instance.id}")

@pre_delete.connect(User)
async def on_user_deleting(sender, instance, **kwargs):
    """Called before User deletion."""
    await archive_user_data(instance.id)

Available signals:

Signal	When	Extra kwargs
pre_save	Before save()
post_save	After save()	created
pre_update	Before update()/merge()	update_fields
post_update	After update()/merge()	update_fields
pre_delete	Before delete()
post_delete	After delete()
around_save	Wraps save()
around_update	Wraps update()/merge()	update_fields
around_delete	Wraps delete()

Around signals use async generators to wrap operations:

from surreal_orm_lite import around_save

@around_save.connect(User)
async def time_user_save(sender, instance, **kwargs):
    import time
    start = time.time()
    yield  # save() executes here
    duration = time.time() - start
    print(f"Save took {duration:.3f}s")

---

Configuration Options

Custom Primary Key

from surreal_orm_lite import BaseSurrealModel, SurrealConfigDict

class Product(BaseSurrealModel):
    model_config = SurrealConfigDict(primary_key="sku")

    sku: str
    name: str
    price: float

Context Manager

async with SurrealDBConnectionManager():
    users = await User.objects().all()
# Connection automatically closed

---

Compatibility

This ORM is tested and compatible with:

SurrealDB Version	SDK Version	Status
2.6.0	1.0.8	✅ Tested
2.5.x	1.0.8	✅ Compatible

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m "Add amazing feature")
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Advanced Features?

This project prioritizes stability and compatibility with the official SurrealDB Python SDK. Due to current SDK limitations, some advanced features cannot be implemented here.

For a feature-rich ORM with relations, transactions, and more, see:

• GitHub: SurrealDB-ORM
• PyPI: surrealdb-orm

When the official SDK supports additional features, they will be incorporated into this lite version.

---

License

MIT License - see LICENSE for details.

---

Author

Yannick Croteau GitHub: @EulogySnowfall

---

Related Projects

• SurrealDB - The database
• surrealdb.py - Official Python SDK