The Dungeon Master's guide to Django's ORM

A Talk presented by Malcolm Tredinnick
log in to bookmark.

Audience level



Django Internals


September 5th, 11:05 a.m. – 11:45 a.m.


If you've ever been curious about Django's ORM implementation, you will have noticed the required learning curve. Some of the code is fairly complicated. Other bits are worse. Here comes a 30 or 40 minute guided tour of the uncharted realms: how the pieces fit together, where to look for things, why the current design is what it is. A portion of this is my fault; I should probably explain myself.


Django's database layer is a necessarily complicated piece of code. It is a very powerful API that works more or less seamlessly across multiple database storage systems, smoothing over many of the inconsistencies and implementation differences that go with the territory. This is great for developers who use Django.

It's a little less awesome for the maintainers of that code; working in that environment is fairly difficult. Still, we all like a challenge. Problem is: where to start? Coming to grips with the ORM code isn't easy. The code is well written and documented, but the entry points are particularly well highlighted and, really, the sheer mass of code is an obstacle to be overcome.

This talk will look at the various layers of the ORM, from the public gateways, to the semi-public doors into the implementation, to the deeper internals and down to the interaction with databases. In effect, following the journey of a couple of adventurous young queries as they traverse the pathways to bring back some data, smelted into just the right format.

The goal is to provide some kind of mental map of the code. Some tips for orienting yourself in the future and how to examine new nooks and corners without losing your mind. We obviously cannot cover everything, but let's go over the common paths and show how the other pieces hang off that backbone.

Along the way, we'll put some of the details into historical perspective. Getting inside the mind of previous adventurers might help understand why things are the way they are.