Why django-graphex?¶

Every library carries the fingerprints of the person who built it. This page is the honest story of where django-graphex comes from — and the benchmark that tells you, in numbers, what those years of thinking bought you.

The story¶

I come from a Django REST Framework background, and that DNA runs through every line of this project. If you have ever written a DRF ViewSet, attached a permission_classes, reached for a pagination_class, or leaned on a serializer to validate an incoming payload, then django-graphex is going to feel like home. That was deliberate. I did not want GraphQL in Django to feel like a foreign framework bolted onto your models — I wanted it to feel like the Django you already know, with the ergonomics you already trust.

Years ago I built graphene-django-extras as a hobby. It came together over a single weekend, born out of necessity: a production project I was working on kept running into the real limitations of graphene-django at the time, and I needed a way out. So I wrote one. It solved concrete pain for concrete people, and to my surprise it found an audience. But I'll be honest with you — I never gave it all the love it deserved. Life moved on, the weekend project stayed a weekend project, and it quietly kept working for people while I looked elsewhere.

Meanwhile, the ground it stood on shifted. Over the following years, the pace of maintenance on graphene and graphene-django slowed considerably — releases stretched further apart, issues sat longer without answers. I want to be very clear about this: that is not a criticism of the people who built those projects. Graphene taught an entire generation of Django developers what GraphQL even was. It walked so the rest of us could run. I have nothing but gratitude for the work — and for the maintainers who carried it as far as they did, on their own time, for free.

django-graphex is me coming back to settle a pending debt. It is the same initial idea behind graphene-django-extras — GraphQL for Django with DRF-style ergonomics — but rebuilt the way it always deserved to be built. Modern foundations: graphql-core and Pydantic underneath, with zero graphene in the stack. The best performance I could squeeze out of it, profiled and benchmarked rather than assumed. Documentation treated as a first-class deliverable instead of an afterthought. And test coverage pushed as high as I could take it — the suite currently sits at 3,200+ tests with a hard ≥95% coverage floor enforced in CI.

How it compares¶

Talk is cheap, so here are the numbers. I built a fairness-first benchmark that puts django-graphex head-to-head with the three other actively-used Django GraphQL libraries, on the same database, the same models, and the same operations. The full harness lives in the repository — you can run it yourself.

The conditions¶

Credibility is in the conditions, so let me state all of them up front.

• Identical runtime. Same pinned Python 3.12.11 and Django 6.0.6 across all four virtual environments. Latest PyPI versions of every library: graphene-django 3.2.3 (+ graphene 3.4.3, django-filter 25.2), strawberry-graphql-django 0.86.4 (+ strawberry-graphql 0.320.1), ariadne 1.1.0 (+ ariadne-django 0.3.0), and django-graphex 2.0.0.
• Identical data. The same Django models and the same seeded dataset for everyone: 2,000 authors, 20,000 posts, 60,000 comments, 60,000 tag relations, generated from a deterministic seed.
• Five semantically-equivalent operations, each written in the idiomatic syntax of the library under test: a flat list (50 rows), a nested query (20 authors → 10 posts → 5 comments — the N+1 stressor), a single object, a filtered list (icontains), and a create mutation.
• Each library in its recommended production setup. strawberry runs with its DjangoOptimizerExtension enabled; graphene-django runs stock (its optimizer is a separate, unmaintained package); ariadne uses hand-written idiomatic resolvers; graphex runs on defaults.
• A strict harness. Django test client, 15 warmup + 100 measured iterations per operation, sequential single-session run, response-shape validation before timing (a benchmark that returns the wrong data is invalid), and SQL counts captured via CaptureQueriesContext. macOS arm64, 16 cores, SQLite.

The results¶

Per-request p50 latency (ms) and SQL queries for each operation. Lower is better on both.

What the numbers actually mean¶

The nested row is the one that matters at scale. For the same response, graphene-django fires 442 SQL queries where graphex fires 3 — a textbook N+1 explosion that graphex avoids by prefetching the relation tree. And here's the part that's easy to miss: this ran on local SQLite, which understates the gap. In production, against Postgres over a network, every one of those 442 round-trips pays real latency. The 15 ms vs 61 ms you see here becomes a far wider chasm the moment there's a wire between your app and your database.

The scaling story is just as telling. When I doubled the dataset (from 1,000 to 2,000 authors), graphex's filtered operation stayed flat at ~1.2 ms — it's O(page): no unconditional COUNT, and a LIKE + LIMIT early exit. Over the same doubling, graphene-django's filtered operation climbed from 3.55 ms to 6.71 ms — it's O(table), because its count scans the whole thing. The lead doesn't just hold as your data grows; it widens.

Reproduce it yourself¶

I don't want you to take my word for any of this. The complete harness lives in the repo under benchmarks/. The README there documents the full operation contract and the fairness rules; ./setup_envs.sh && ./run_all.sh regenerates everything from scratch — venvs, database, seed, and the raw per-library result JSONs under benchmarks/results/.