{"canonical_url":"https://engineer.company/glossary/orm/","content_markdown":"# ORM\n\n## What it is\n\nAn ORM, short for object-relational mapper, is a library that maps the tables of\na relational database to classes in application code, and their rows to objects.\nCode asks for an author and gets an `Author` object back, changes one of its\nattributes and saves it, and the ORM writes the `SELECT`, `INSERT` and `UPDATE`\nstatements that do the work. Django's models and SQLAlchemy's ORM, both written\nin Python, are two well-known examples, and they are the two this article draws\non.\n\nThe mapping is needed because the two sides organise data differently. Martin\nFowler puts it plainly in his description of the Data Mapper pattern: objects\nand relational databases have different ways of structuring data, and parts of\nan object model, such as collections and inheritance, have no counterpart in a\nrelational database. Moving data between the two becomes a problem of its own,\nand an ORM is a ready-made answer to it.\n\nThe parts of that answer were named in Fowler's book Patterns of Enterprise\nApplication Architecture, published in 2003, whose pattern catalogue is online.\nTwo patterns describe the overall shape. Active Record is an object that wraps\none row of a table, handles its own database access and carries the domain logic\nfor that data; Django's design philosophies say its models follow that pattern.\nData Mapper is a separate layer that moves data between objects and the database\nwhile keeping each independent of the other, so the objects need not know that a\ndatabase exists. Smaller patterns sit around them. Identity Map makes sure each\nobject is loaded only once. Unit of Work keeps a list of the objects a piece of\nwork has changed and writes the changes out together. Lazy Load is an object\nthat holds only part of the data code needs but knows how to fetch the rest.\nSQLAlchemy's documentation names two of these directly: its `Session` keeps\nloaded objects in an identity map, with only one object for any primary key, and\nits way of collecting changes and flushing them to the database is the unit of\nwork pattern.\n\n## Why it matters\n\nThe first reason is the amount of code it saves. In his 2012 essay ORM Hate,\nFowler calls the object-relational mapping problem hard: it means keeping two\nquite different representations of the same data in step, and a change on either\nside has to be carried over to the other. His estimate is that an ORM handles\nabout 80 to 90% of the mapping problems, and he argues that a framework which\nspares a team 80% of that work is worth having even if it stops there. Every\ntable a team does not map by hand is one less place for a column to be read into\nthe wrong attribute.\n\nThe second reason is consistency inside a running program. With an identity map,\ntwo queries that find the same row return the same object, so a change made\nthrough one reference is visible through the other; SQLAlchemy's documentation\ndemonstrates it by loading the same primary key twice and getting the identical\nobject back. With a unit of work, the ORM collects pending inserts, updates and\ndeletes and, in the words of SQLAlchemy's feature list, flushes them all in one\nbatch, so application code does not have to remember which objects it touched.\nDjango makes the opposite choice on purpose: its design philosophies require an\nexplicit `save()` rather than saving behind the scenes, so that the framework\nsends as few SQL statements as possible.\n\nThe third reason is where the boundary sits. Fowler describes a good ORM as one\nthat takes care of the routine work and \"provides manholes so you can get down\nwith the SQL\" when it has to, and he is blunt that anyone building an\napplication on a relational database should know how one works. Django's design\nphilosophies say the same from the framework side: the database API should know\nit is a shortcut rather than the whole answer, and should make custom SQL easy\nto write, whether a whole statement or a single `WHERE` clause. An ORM earns its\nplace on the routine majority of the data access; the rest is where a team\nspends its SQL skill.\n\n## What it looks like in practice\n\nThe cost an ORM hides most often is the number of queries it sends. In\nSQLAlchemy 2.1, relationships load lazily by default: the related objects are\nfetched the first time code touches the attribute. The documentation spells out\nthe consequence: for N objects loaded, touching their lazily loaded attributes\nmeans N+1 `SELECT` statements. The example below assumes `Author` and `Book`\nclasses already mapped, with a one-to-many `Author.books` relationship, and\nwalks the authors three ways.\n\n```python\nfrom sqlalchemy import select\nfrom sqlalchemy.orm import raiseload, selectinload\n\n# The default: one SELECT for the authors, then one more for each\n# author whose books the loop touches, N+1 statements in all.\nauthors = session.scalars(select(Author)).all()\nfor author in authors:\n    print(author.name, len(author.books))\n\n# select IN loading: a second SELECT fetches the books of every\n# author at once, with the authors' primary keys in an IN clause.\nstmt = select(Author).options(selectinload(Author.books))\nfor author in session.scalars(stmt).all():\n    print(author.name, len(author.books))\n\n# raise loading: touching author.books now raises an error\n# instead of quietly sending another query.\nstmt = select(Author).options(raiseload(Author.books))\n```\n\nFor one-to-many and many-to-many collections, the documentation calls\n`selectinload()` generally the best strategy to use. `joinedload()`, which it\ncalls the most general-purpose strategy, adds a `JOIN` to the original\nstatement, a `LEFT OUTER JOIN` by default, so the related rows arrive in the\nsame result set. `raiseload()` exists to guard against unwanted loads, and its\nwildcard form, `raiseload(\"*\")`, extends the guard to the other relationships\ntoo, including those of the objects the statement does load.\n\nDjango 6.1 gives the same choice a name of its own: fetch modes. When code\ntouches a field that the original query did not load, such as a foreign key, a\none-to-one relation or a field left out with `defer()` or `only()`, the default\nmode, `FETCH_ONE`, fetches it for that one instance, and the documentation\nitself names the result the N+1 queries problem. `FETCH_PEERS`, new in 6.1,\nfetches the missing field for the instance and for every other instance from the\nsame `QuerySet`, on the reasoning that code which needs a field for one row\nusually needs it for all of them. `FETCH_RAISE` raises `FieldFetchBlocked`\ninstead. A mode is set per `QuerySet`, as in\n`Book.objects.fetch_mode(models.FETCH_PEERS)`, or as a model's default through a\ncustom manager, and Django copies it to the related objects it fetches. Where\n`FETCH_PEERS` is not appropriate or efficient enough, the optimisation guide\npoints to `select_related()` and `prefetch_related()`.\n\nThe company's own pages draw the boundary further towards the database than\nmost. Its [tech stack](/tech-stack/) treats SQL as a first-class language rather\nthan something an ORM generates, because most of the performance work it is\ncalled in for lives there. In work under NextMariner, the founder took that approach to its logical\nconclusion with\n[a function-first PostgreSQL data layer](/portfolio/designed-a-function-first-postgresql-data-layer/):\nevery operation the app can do is one of 1,275 stored functions spread across 34\nschemas, and there is no direct table access from Go at all. The role the API\nlogs in as holds `EXECUTE` on those functions and `USAGE` on their schemas and\nnothing else, so it cannot touch a table directly. The page is open about the\nprice: a new field means changing a table as well as a function, not adding a\nline to a query.\n\n## Where it goes wrong\n\n**A loop sends one query per row.** The N+1 pattern above looks harmless on a\nsmall development database and slows a page down in step with the number of\nrows. Decide the loading for every path that matters, with `selectinload()` or\n`joinedload()` in SQLAlchemy and `FETCH_PEERS`, `select_related()` or\n`prefetch_related()` in Django. Then make the unplanned case fail loudly:\n`raiseload()` in SQLAlchemy, or `FETCH_RAISE`, which Django's documentation\ndescribes as a way to prevent unintentional queries in performance-critical\ncode.\n\n**Nobody reads the SQL the ORM writes.** An ORM writes SQL that nobody on the\nteam chose, and that SQL stays invisible until a page turns slow. Django's\noptimisation guide starts here: find out which queries a page runs and what they\ncost, use `QuerySet.explain()` to see how the database executes a given\n`QuerySet`, and read `django.db.connection.queries` to see what Django is\nwriting on the code's behalf. Make reading that SQL part of reviewing any page\nor job that matters, and run the slow statements through the database's own\nquery plan.\n\n**Work that belongs in the database runs in Python.** Loading rows only to\nfilter them, compare two of their fields or add them up moves every row across\nthe connection to do in application code what the database could do where the\ndata already is. Django's guide lists the alternatives: `filter()` and\n`exclude()` to filter in the database, `F()` expressions to compare fields\nwithin the same model, and `annotate()` to aggregate in the database. Writes\nfollow the same rule, with `bulk_create()` and `bulk_update()` in place of one\n`save()` per object, after checking the caveats the documentation lists for\nboth. For a very large result set, a `QuerySet` holds on to everything it has\nread and can use a lot of memory, and `iterator()` may help.\n\n**The last part is forced through the ORM.** Fowler's own estimate leaves 10 to\n20% of the mapping problems, and that last part, in his words, always needs\ncareful work. Bending the ORM until it produces a particular statement hides\nthat work inside generated SQL that nobody chose. Write those statements in SQL\nand review them like any other code. Django's guide names the steps down: the\n`RawSQL` expression adds explicit SQL to a query, less portable but more\npowerful, and beyond that a team can write its own SQL to retrieve data or\npopulate models. Keep the ORM for the routine records, where it saves the most\nand costs the least.\n\n## Further reading\n\n- [Catalog of Patterns of Enterprise Application Architecture](https://martinfowler.com/eaaCatalog/)\n  — Martin Fowler's summaries of Active Record, Data Mapper, Unit of Work,\n  Identity Map and Lazy Load.\n- [ORM Hate](https://martinfowler.com/bliki/OrmHate.html)\n  — why the object-relational mapping problem is hard, and how much of it a\n  framework can take on.\n- [Relationship Loading Techniques](https://docs.sqlalchemy.org/en/21/orm/queryguide/relationships.html)\n  — lazy, select IN, joined and raise loading in SQLAlchemy 2.1, and which one\n  to choose.\n- [Fetch modes](https://docs.djangoproject.com/en/stable/topics/db/fetch-modes/)\n  — `FETCH_ONE`, `FETCH_PEERS` and `FETCH_RAISE`, new in Django 6.1.\n- [Database access optimization](https://docs.djangoproject.com/en/stable/topics/db/optimization/)\n  — profiling, `QuerySet` evaluation, work done in the database, bulk methods\n  and raw SQL.\n\n\u003chttps://engineer.company/glossary/orm/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"What an ORM does between objects and tables, which of Fowler's patterns it is made of, what loading related rows costs, and four ways it goes wrong.","formats":{"gemtext":"https://engineer.company/glossary/orm/index.gmi","gopher":"https://engineer.company/glossary/orm/gophermap","html":"https://engineer.company/glossary/orm/","json":"https://engineer.company/glossary/orm/index.json","markdown":"https://engineer.company/glossary/orm/index.md","pdf":"https://engineer.company/glossary/orm/index.pdf"},"kind":"page","language":"en","title":"What is an ORM?","url":"https://engineer.company/glossary/orm/","version":1}