ormdantic 2.0.1

A Rust-backed async ORM for Python applications that use Pydantic models.

Ormdantic lets you declare database tables with Pydantic v2 models and run async CRUD, relationship loading, migrations, reflection, and native SQL execution through a Rust-backed runtime.

The project is designed for applications that want Python model ergonomics without giving up SQL database features. Python owns the model and API surface; Rust owns SQL compilation, type conversion, and driver execution.

What you get

Benchmarks

The reproducible benchmark report in benchmark/ compares Ormdantic, SQLAlchemy, and SQLModel on local SQLite file databases. It includes read and write cases, and the optional huge profile uses million-row datasets.

Million-row profile:

Install

uv add ormdantic

First example

from pydantic import BaseModel, Field

from ormdantic import Ormdantic

db = Ormdantic("sqlite:///app.sqlite3")


@db.table(pk="id", indexed=["name"])
class Flavor(BaseModel):
    id: str
    name: str = Field(min_length=2, max_length=63)
    rating: int = 0


async def main() -> None:
    await db.init()

    await db[Flavor].insert(Flavor(id="vanilla", name="Vanilla", rating=5))

    result = await db[Flavor].find_many(
        {"rating": {"gte": 4}},
        order_by=["name"],
    )

    for flavor in result.data:
        print(flavor.name)

Learn the project

Start with the documentation when you are new:

• docs/learning-path.md tells new and advanced readers where to start.
• docs/quickstart.md walks through the first model, first table, first query, first session, and first migration preview.
• docs/concepts/ explains tables, fields, relationships, querying, loading, sessions, migrations, events, and the native engine.
• docs/drivers/ explains SQLite, PostgreSQL, MySQL, MariaDB, SQL Server, and Oracle behavior.
• docs/examples/ contains task-focused how-to guides.
• docs/api/ documents the Python API with generated references and usage notes.

Migration CLI

Migration commands can read the database URL from --url, an exported DATABASE_URL, or a local .env file:

export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
uv run ormdantic migrations init
uv run ormdantic migrations apply-dir migrations
uv run ormdantic migrations current

The CLI prints redacted connection details and summaries such as Applied 2 migrations from migrations. instead of only raw revision IDs.

Development

Common commands:

bash scripts/lint.sh
bash scripts/test.sh
bash scripts/docs_build.sh

The docs use Zensical:

uv run --group docs zensical build
uv run --group docs zensical serve

Rust crates live under rust/crates/ and are managed from the repository root Cargo.toml.

Status

Ormdantic is evolving quickly. Prefer explicit migrations, review generated SQL before applying it in production, and check the driver-specific pages for dialect behavior.