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.

• Official SDK only: built on surrealdb[pydantic], no custom protocol, few dependencies.
• Two server lines: the same code runs on SurrealDB 2.x and 3.x, and on the SDK's in-process engine (mem://, surrealkv://) for tests and notebooks.
• Django-style queries: filter(age__gte=18), Q objects, order_by("-age"), aggregations, subqueries.
• SurrealDB-native: graph relations and typed edges, live queries, change feeds, time travel, full-text, vector and hybrid search, events, views and schema DDL.
• Tooling: migrations, a surreal-orm-lite command line, schema introspection, test factories and a pytest plugin.

Documentation: user guide · changelog · roadmap · examples

Installation

pip install surreal-orm-lite
# or
uv add surreal-orm-lite

Quick start

import asyncio

from pydantic import Field

from surreal_orm_lite import BaseSurrealModel, Q, SurrealDBConnectionManager


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


async def main() -> None:
    # A server URL (ws://localhost:8000/rpc, http://localhost:8000) or an in-process engine (mem://).
    SurrealDBConnectionManager.set_connection(
        url="http://localhost:8000", user="root", password="root", namespace="app", database="app"
    )

    alice = await User(id="alice", name="Alice", email="alice@example.com", age=30).save()
    await User(id="bob", name="Bob", email="bob@example.com", age=17).save()

    adults = await User.objects().filter(age__gte=18).order_by("-age").exec()
    a_or_minor = await User.objects().filter(Q(name__startswith="A") | Q(age__lt=18)).exec()
    average = await User.objects().avg("age")

    await alice.merge(age=31)  # partial update
    await alice.delete()
    print(adults, a_or_minor, average)


asyncio.run(main())

The getting started guide walks through it, and the querying guide lists every QuerySet method and filter lookup.

Documentation

The documentation index lists every section of the guides.

Using with AI assistants

The guide for AI coding assistants gives an assistant such as Claude Code the idioms, the 2.x/3.x differences and the common mistakes in one page, each example checked by the test suite. Download it into your project, then add the line @docs/surreal-orm-lite.md to your CLAUDE.md to import it:

curl -fsSL -o docs/surreal-orm-lite.md https://raw.githubusercontent.com/EulogySnowfall/SurrealDB-ORM-lite/main/docs/ai/CLAUDE.md

Tools that read the llms.txt convention find every guide listed there.

Features

Supported versions

Surreal ORM Lite runs on both SurrealDB release lines, 2.x (2.6 / 2.7) and 3.x (3.2 / 3.3), and on the official SDK's in-process engine. It is tested against SurrealDB v2.7.0 and v3.3.5; SurrealDB 3.1.5 is run as a backward-compatibility check. A few capabilities rely on server features introduced in SurrealDB 3.x: on 2.x the ORM degrades gracefully or says so before sending anything. The compatibility guide lists every tested version and every difference between the two lines and the embedded engine.

SurrealDB-ORM-lite vs SurrealDB-ORM

This project prioritizes stability and compatibility with the official SurrealDB Python SDK. The full SurrealDB-ORM uses a custom SDK for advanced features.

Both projects target the same feature set; the difference is how (official SDK vs custom SDK) and server support. Everything below is on the lite roadmap via the official SDK 2.0 — only the custom-SDK internals stay exclusive to the full ORM; the official SDK's in-process engine (section 26) is lite-only.

Choose ORM-lite if you want the official SDK, minimal dependencies, support for SurrealDB 2.x (2.6 / 2.7) and 3.x (3.2 / 3.3), and a full feature roadmap built entirely on the official SDK.

Choose ORM if you need the custom-SDK internals (CBOR protocol, native connection pool) or those features available today rather than on the roadmap.

• SurrealDB-ORM GitHub: github.com/EulogySnowfall/SurrealDB-ORM
• SurrealDB-ORM PyPI: surrealdb-orm

Project status

Surreal ORM Lite is in alpha (0.x): every Tier 1 to Tier 3 feature of the roadmap has shipped, and the next release, v0.41.0, opens the beta phase (API freeze and hardening) on the way to GA as v2.0.0, numbered after the official SDK 2.0. The release overview lists every release, and docs/ROADMAP.md details each one.

Contributing

Contributions are welcome: see the contributing guide. Report a vulnerability as the security policy describes, not in a public issue.

License

MIT License - see LICENSE for details.

Author

Yannick Croteau GitHub: @EulogySnowfall

Related Projects

• SurrealDB - The database
• surrealdb.py - Official Python SDK
• SurrealDB-ORM - Full-featured ORM with custom SDK