DEV Community: Seva D

Your ORM is fast. But is it right? Three silent data bugs in async Python stacks

Seva D — Fri, 10 Jul 2026 21:51:31 +0000

Your ORM is fast. But is it right? Three silent data bugs in async Python stacks

My last post was about making an ORM faster with a Rust engine, so let me open with an uncomfortable admission: for most services, the ORM is not your bottleneck. Your database is doing the real work, the network round-trip dwarfs your hydration loop, and if your p99 is bad it's almost certainly an index or an N+1, not the ORM.

What the ORM can be is quietly wrong. Not "throws an exception" wrong — that kind is easy. Wrong as in: your data is corrupted, no error was raised, and you find out three months later. I hit all three of the bugs below while building yara-orm, and every one of them exists right now in production apps that pass their test suites.

Trap 1: Your SQLite foreign keys are probably decorative

SQLite has supported foreign key constraints since 2009. It also ignores them by default. Enforcement is opt-in, per connection:

import sqlite3

db = sqlite3.connect(":memory:")
db.execute("CREATE TABLE author (id INTEGER PRIMARY KEY, name TEXT)")
db.execute("""CREATE TABLE book (
    id INTEGER PRIMARY KEY,
    author_id INTEGER REFERENCES author(id)
)""")

db.execute("INSERT INTO book (author_id) VALUES (42)")  # author 42 doesn't exist
# ...no error. You now have an orphaned row.

print(db.execute("PRAGMA foreign_keys").fetchone())  # (0,) — enforcement is OFF

The constraint is in the schema. The database just doesn't check it unless every single connection runs PRAGMA foreign_keys = ON first.

Why this bites ORM users specifically: your ORM happily generates the REFERENCES clause, so the schema looks protected, and ON DELETE CASCADE looks configured. Whether any of it does anything depends on whether your ORM (or you) sets the pragma on every pooled connection. SQLAlchemy, for example, is upfront that it doesn't do this for you — the docs tell you to hook connection creation and issue the pragma yourself. Django does it for you. Everything in between: go check. Seriously, run PRAGMA foreign_keys through your app's actual connection and look at the answer.

And "it's just SQLite, that's only for tests" is exactly the problem — your tests pass while enforcing nothing, then CI green-lights code that violates constraints your Postgres production DB will enforce.

In yara-orm the Rust engine enables enforcement on every SQLite connection it opens, because a foreign key you declared and didn't get is worse than no foreign key at all — it's documentation that lies.

Trap 2: The decimal that came back different

SQLite has no decimal type. So when your model says "this is money":

price = fields.DecimalField(max_digits=10, decimal_places=2)

…the ORM has to pick a physical representation, and the honest options are TEXT (exact, but you lose SUM() in plain SQL) or REAL (a float — fast, sortable, and wrong for money). Binary floats cannot represent most decimal fractions:

>>> 0.1 + 0.2
0.30000000000000004

Store prices through a REAL column and each individual value usually survives (rounding on the way out hides the error), but aggregate a few thousand of them — or compare for equality — and the drift is real and unexplainable to your accountant.

Again, the good ORMs don't hide this; SQLAlchemy literally emits a warning when you push Decimal values through SQLite. But a warning in a log nobody reads is a weak safety net for a correctness property. The test you want in your suite today:

from decimal import Decimal

await Order.create(id=1, total=Decimal("19.99"))
row = await Order.get(id=1)
assert row.total == Decimal("19.99")
assert isinstance(row.total, Decimal)   # not float!

yara-orm's contract is that a Decimal round-trips exactly, on every backend — the engine picks a lossless representation per database and refuses to route decimals through binary floats. That's not a performance feature. It's the feature the performance work is pointless without.

Trap 3: The migration that renamed your column by deleting it

You rename a field:

# before
name = fields.CharField(max_length=100)
# after
full_name = fields.CharField(max_length=100)

To you, that's a rename. To a schema-diffing migration tool, it's indistinguishable from "dropped name, added full_name" — unless the tool explicitly tries to detect renames. The naive autogenerated migration is:

ALTER TABLE author DROP COLUMN name;      -- your data leaves the building here
ALTER TABLE author ADD COLUMN full_name VARCHAR(100);

Runs clean in dev (three rows, who cares). Runs clean in staging. Runs clean in prod, too — DROP COLUMN doesn't raise just because the column held ten million customer names.

Migration tools across the Python ecosystem handle this with everything from silent drop-and-add to interactive "did you rename this?" prompts, and the behavior changes between versions. Which means the rule is: read the SQL of every autogenerated migration before it touches data you can't regenerate. Alembic's docs say it, Aerich's issue tracker testifies to it, and anyone who's been paged for it will say it louder.

yara-orm's migration engine does rename detection out of the box (same-type column disappearing and appearing in one diff is flagged as a rename, not a drop), and generates partial indexes without hand-written SQL. But I'll say it about my own tool too: read the generated SQL anyway. A migration is a git push --force for your data.

The theme

None of these are exotic. They share one shape: the declaration and the behavior are two different things. The schema declares a foreign key that isn't checked. The model declares a decimal that's stored as a float. The code declares a rename that executes as a drop. Every one is invisible in a green test suite unless you test the property, not the API.

If you take nothing else away, steal these three checks:

PRAGMA foreign_keys through your app's real connection — expect 1.
Round-trip Decimal("19.99") and assert type and value.
cat the SQL of every autogenerated migration before it ships.

Where yara-orm fits (and honest caveats)

I built yara-orm as a Tortoise-style async ORM — Django-ish models, chainable querysets — with the per-query hot path in Rust, across PostgreSQL, MySQL, MariaDB, SQLite, Oracle, and SQL Server. It's genuinely fast (2–9× vs. popular pure-Python ORMs on common ops in our PostgreSQL benchmarks — methodology here, scrutiny welcome). But speed is the headline, not the reason: the three guarantees above — enforced SQLite FKs, exact decimal round-trips, rename-aware migrations — are the parts I'd actually miss.

Caveats, because every tool has them: it's younger and smaller than SQLAlchemy's ecosystem, the async model differs from sync ORMs in ways that matter for session/transaction habits, and if your workload is single-row point queries you're near the network round-trip floor where no ORM's speed matters.

pip install yara-orm

Docs: https://vsdudakov.github.io/yara-orm/

What's the silent data bug that bit you — the one where nothing errored and everything was wrong? I collect these now.

Add a Django-style admin to your FastAPI app in ~10 minutes

Seva D — Tue, 07 Jul 2026 11:25:24 +0000

If you've moved to FastAPI from Django, there's one thing you probably miss on
day one: django-admin. You define a model, register it, and you get a real
CRUD back-office for free — list views, filters, search, edit forms, the works.

FastAPI is deliberately unopinionated, so it ships nothing like that. For a lot
of internal tools, that back-office is exactly what you need and don't want to
hand-build.

This walkthrough adds a Django-admin-style dashboard to a FastAPI + SQLAlchemy
app in about ten minutes, using FastAdmin.
Full disclosure up front: I maintain FastAdmin. I'll point out where other
tools fit better at the end so this isn't a one-sided pitch.

What we're building

A /admin dashboard for a tiny blog: User and Post models, superuser
sign-in, list views with filters and search, and edit forms — without writing a
line of frontend code. The React UI ships bundled in the package, so there's no
Node.js step at install time.

1. Install

pip install "fastadmin[fastapi,sqlalchemy]"

The extras pull in the FastAPI glue and the async SQLAlchemy backend. (Swap in
tortoise, django, or pony if that's your ORM — FastAdmin has a first-class
admin class for each.)

2. Define your models

Nothing FastAdmin-specific here — these are plain async SQLAlchemy models.

# models.py
from sqlalchemy import Boolean, ForeignKey, Integer, String, Text
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship

engine = create_async_engine("sqlite+aiosqlite:///db.sqlite3")
session_maker = async_sessionmaker(engine, expire_on_commit=False)


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user"

    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    username: Mapped[str] = mapped_column(String(255), nullable=False)
    hash_password: Mapped[str] = mapped_column(String(255), nullable=False)
    is_superuser: Mapped[bool] = mapped_column(Boolean, default=False)
    is_active: Mapped[bool] = mapped_column(Boolean, default=True)

    def __str__(self) -> str:
        return self.username


class Post(Base):
    __tablename__ = "post"

    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    title: Mapped[str] = mapped_column(String(255), nullable=False)
    body: Mapped[str] = mapped_column(Text, default="")
    is_published: Mapped[bool] = mapped_column(Boolean, default=False)
    author_id: Mapped[int] = mapped_column(ForeignKey("user.id"))
    author: Mapped["User"] = relationship()

    def __str__(self) -> str:
        return self.title

3. Register your admins

This is the part that looks like Django. You subclass a base admin
(SqlAlchemyModelAdmin here) and describe how each model shows up. The one
required piece is an authenticate method on the user model's admin — it's how
sign-in works, against your user table, however you hash passwords.

# admin.py
import os

# Must be set before importing fastadmin
os.environ["ADMIN_USER_MODEL"] = "User"
os.environ["ADMIN_USER_MODEL_USERNAME_FIELD"] = "username"
os.environ["ADMIN_SECRET_KEY"] = "change-me-in-production"

import bcrypt
from sqlalchemy import select

from fastadmin import SqlAlchemyModelAdmin, register
from models import Post, User, session_maker


@register(User, sqlalchemy_sessionmaker=session_maker)
class UserAdmin(SqlAlchemyModelAdmin):
    exclude = ("hash_password",)
    list_display = ("id", "username", "is_superuser", "is_active")
    list_display_links = ("id", "username")
    list_filter = ("is_superuser", "is_active")
    search_fields = ("username",)

    async def authenticate(self, username: str, password: str) -> int | None:
        sessionmaker = self.get_sessionmaker()
        async with sessionmaker() as session:
            result = await session.scalars(
                select(User).filter_by(username=username, is_superuser=True)
            )
            user = result.first()
        if not user or not bcrypt.checkpw(password.encode(), user.hash_password.encode()):
            return None
        return user.id


@register(Post, sqlalchemy_sessionmaker=session_maker)
class PostAdmin(SqlAlchemyModelAdmin):
    list_display = ("id", "title", "author", "is_published")
    list_display_links = ("id", "title")
    list_filter = ("is_published",)
    search_fields = ("title", "body")

If you've written a django-admin ModelAdmin, list_display / list_filter
/ search_fields need no explanation. That's the whole point.

4. Mount it on FastAPI

The admin is just an ASGI sub-app you mount wherever you like:

# main.py
from contextlib import asynccontextmanager

import bcrypt
from fastapi import FastAPI

from fastadmin import fastapi_app as admin_app
from models import Base, User, engine, session_maker
import admin  # noqa: F401 — importing registers the admin classes


@asynccontextmanager
async def lifespan(app: FastAPI):
    # Create tables and a superuser to sign in with (demo only)
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    async with session_maker() as session:
        session.add(
            User(
                username="admin",
                hash_password=bcrypt.hashpw(b"admin", bcrypt.gensalt()).decode(),
                is_superuser=True,
            )
        )
        await session.commit()
    yield


app = FastAPI(lifespan=lifespan)
app.mount("/admin", admin_app)

Run it:

uvicorn main:app --reload

Open http://localhost:8000/admin, sign in with admin / admin, and you've
got a working dashboard over your models.

What you actually get

Out of that ~60 lines: paginated list views, column sorting, the filters and
search you declared, add/edit forms with the right widget per field type, and
delete — all in a polished antd React UI. Here's the demo from the repo:

Going further

The same ModelAdmin style scales past CRUD when you need it:

Bulk actions — decorate a method with @action and it shows up in the actions dropdown on the list page (e.g. "publish selected posts").
Inlines — edit related rows (a tournament's events, a post's comments) on the parent's page via inlines.
Form widgets — 20+ antd widgets (rich text, JSON editor, async select, slug, date/time pickers) via formfield_overrides.
File & image uploads — a storage-agnostic upload_file hook (local, S3, presigned URLs).
Dashboard charts — declarative line/area/column/bar/pie widgets for a metrics view.

When not to reach for this

Being honest about fit:

You're on Django. Just use the built-in admin — it's right there and it's excellent. FastAdmin's story is strongest off Django (FastAPI/Flask).
You're SQLAlchemy-only and want the smallest possible dependency. sqladmin is SQLAlchemy-focused and great at that. starlette-admin is another strong, flexible option (SQLAlchemy, MongoEngine, ODMantic).

Where FastAdmin earns its place is the combination: multiple frameworks
(FastAPI, Flask, Django) and multiple ORMs (SQLAlchemy, Tortoise, Django, Pony,
Yara) behind one Django-admin-style API, with the React UI bundled so there's
no separate frontend build.

If that matches your stack, the repo and docs are here:

Repo: https://github.com/vsdudakov/fastadmin
Docs: https://vsdudakov.github.io/fastadmin/

Happy to answer questions in the comments — and if you hit a rough edge, issues
and PRs are welcome.

I built a Python ORM with a Rust engine — here's how the GIL, PyO3, and asyncio actually cooperate

Seva D — Mon, 29 Jun 2026 22:16:56 +0000

I like Tortoise ORM. Django-style models, async-first, clean. But I wanted more speed on read-heavy paths without reaching for SQLAlchemy, so I built yara-orm: a Tortoise-style async ORM where the model and query layer is Python, but the engine — connection pooling, parameter binding, and row decoding — is written in Rust (PyO3 over tokio-postgres and rusqlite).

The API is exactly what you'd expect:

from yara_orm import Model, YaraOrm, fields, in_transaction

class Author(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=100)

class Book(Model):
    id = fields.IntField(pk=True)
    title = fields.CharField(max_length=200)
    author = fields.ForeignKeyField("Author", related_name="books")

await YaraOrm.init("postgres://localhost/app")   # or sqlite://./app.db
await YaraOrm.generate_schemas()

ada = await Author.create(name="Ada")
hot = await Book.filter(author__name="Ada").order_by("-id").limit(10)

async with in_transaction():
    await Book.create(title="Atomic", author=ada)

But the API isn't the interesting part — Tortoise already nailed that. The interesting part is underneath: a Rust database engine and Python's asyncio loop have to share one interpreter, and if you get it wrong the GIL collapses the whole thing back into a single-threaded program. Here's exactly how that works.

Two runtimes in one process

There are two schedulers running at once:

CPython's asyncio event loop — single-threaded, on your main thread, where your async def code runs.
Tokio's multi-threaded runtime — background worker threads that actually open sockets, send queries, and parse wire protocols.

The job is to let them cooperate so that the event loop never blocks on I/O, and the database I/O never blocks on the GIL. The GIL is the thing that makes that non-trivial.

How the GIL shows up in Rust

In PyO3 you can't touch a Python object without proof that you hold the GIL. That proof is a token — Python<'py> — threaded through the API: every function that reads or creates Python objects takes one, and the 'py lifetime ties every borrowed Bound<'py, PyAny> to it. It's a compile-time guarantee. No token, no access to the interpreter.

So the GIL boundary is explicit in the code, and only two places actually need it:

Binding parameters (Python → Rust): pulling a Python int / str / datetime / UUID out and converting it to a Rust value reads Python objects, so it holds the GIL.
Decoding rows (Rust → Python): constructing the int / str / datetime you get back creates Python objects, so it holds the GIL.

Everything between those two — acquiring a pooled connection, sending the query, waiting on the socket, parsing the wire protocol — touches no Python objects at all. So it runs with the GIL released. That's the entire point: while Postgres is doing work and bytes are in flight, the GIL is free and other Python tasks run.

To make that safe, the data crossing into the async world has to be owned and Send. yara-orm converts each parameter into a small Rust Value enum under the GIL, then hands an owned Vec<Value> to the database layer:

#[derive(Clone)]
enum Value { Null, Int(i64), Text(String), Uuid(Uuid), /* ... */ }

By the time real I/O starts there isn't a single Py<...> or Bound<...> in scope — nothing borrowed from the interpreter, nothing that needs the GIL — so Tokio is free to move the future across worker threads. This is also why you can't just hold a PyObject across an .await: a GIL-bound handle isn't Send, and the borrow checker stops you. The architecture is partly forced by PyO3's types, which is a feature, not a limitation.

How a Rust future becomes a Python `await`

The model layer calls await engine.fetch_rows(sql, params). On the Rust side fetch_rows doesn't block — it returns a Python awaitable, built with pyo3-async-runtimes:

fn fetch_rows<'p>(&self, py: Python<'p>, sql: String, params: Vec<Value>)
    -> PyResult<Bound<'p, PyAny>>
{
    let backend = self.backend.clone();
    future_into_py(py, async move {
        // runs on a Tokio worker thread, GIL released
        backend.fetch_all_values(&sql, &params).await.map_err(to_pyerr)
    })
}

future_into_py does three things:

Creates a Python asyncio.Future bound to the currently running event loop — which is why this has to be called from inside a running loop.
Spawns the Rust async move { ... } onto the Tokio runtime, which lives on its own background threads, completely separate from the asyncio loop thread.
When the Rust future finishes — on a Tokio worker thread — it schedules the result back onto the asyncio loop with loop.call_soon_threadsafe(...), the only thread-safe way to poke the loop from another thread.

From Python it's an ordinary await: the coroutine suspends, the event loop keeps serving other tasks, and when the Tokio side resolves the future the loop wakes the coroutine with the rows. The decode step (Rust Value → Python objects) re-acquires the GIL for the few microseconds it takes to build the result, then releases it again.

So the two runtimes never block each other: the asyncio thread is never blocked on I/O, and the database I/O never holds the GIL. The GIL is held only during the cheap conversion at each end.

That last sentence is the whole performance story, and it tells you exactly where to optimize. The query builder runs once per query; the decoder runs once per row. A SELECT returning 5,000 rows runs your row-hydration code 5,000 times — that loop is where the time goes, on every ORM. So that's where the effort went:

uuid.UUID and decimal.Decimal type objects are imported once per interpreter, not re-resolved per cell (UUID primary keys show up on basically every query).
Postgres decoding dispatches on the column's type OID via a jump table, instead of walking a 16-deep chain of type comparisons per cell.
SQLite upper-cases each column's declared type once per result set instead of per cell, and binds parameters by move rather than copying them twice.

None of these are glamorous. All of them compound across rows — and crucially, all of them are inside the short GIL-held window, where every microsecond is one the event loop can't use.

A note on blocking drivers

rusqlite is synchronous — a blocking C library. Call it directly on a Tokio worker and you stall an async executor thread. So SQLite work runs on a dedicated blocking thread pool (the connection pool's interact / spawn_blocking): same decoupling principle, one layer down. Blocking work stays off both the asyncio loop and Tokio's async workers.

The honest tradeoff

There's another way to build this: serialize the query to bytes (MessagePack or similar) in Python, hand the bytes to Rust, get bytes back, and never touch a Python object in Rust at all — so the GIL is never involved. yara-orm goes the direct-PyO3 route instead.

Holding the GIL during conversion is a real cost, and free-threaded Python (3.13+ --disable-gil) changes the calculus: if your workload is many OS threads decoding result sets in parallel, the GIL-free, bytes-on-the-wire design can pull ahead. For the typical single-event-loop async service, paying the GIL for a few microseconds of conversion and skipping a serialize/deserialize round trip is the better trade.

There's no free lunch — just a choice, and most "we rewrote it in Rust" posts don't tell you which one they made.

Try it

pip install yara-orm

Repo: https://github.com/vsdudakov/yara-orm
Docs: https://vsdudakov.github.io/yara-orm/

If you've built a PyO3 bridge yourself: did you go IR-over-MessagePack or direct conversion — and would you make the same call again? Genuinely curious how others have drawn the GIL boundary.

DEV Community: Seva D

Your ORM is fast. But is it right? Three silent data bugs in async Python stacks

Your ORM is fast. But is it right? Three silent data bugs in async Python stacks

Trap 1: Your SQLite foreign keys are probably decorative

Trap 2: The decimal that came back different

Trap 3: The migration that renamed your column by deleting it

The theme

Where yara-orm fits (and honest caveats)

Add a Django-style admin to your FastAPI app in ~10 minutes

What we're building

1. Install

2. Define your models

3. Register your admins

4. Mount it on FastAPI

What you actually get

Going further

When not to reach for this

I built a Python ORM with a Rust engine — here's how the GIL, PyO3, and asyncio actually cooperate

Two runtimes in one process

How the GIL shows up in Rust

How a Rust future becomes a Python await

A note on blocking drivers

The honest tradeoff

Try it

How a Rust future becomes a Python `await`