Skip to content

Delete Your Repository Layer

Part 4 of six in Relation-Oriented Programming. Series index

Here's a question about a blog schema of four tables: author, post, comment, and comment_type, whose DDL is in the series index. Who are the reviewers of a given post? A reviewer is an author who left a comment of type review on it.

In any ORM codebase written in the last fifteen years, the answer lives in a service or a repository, and it looks like this:

class PostService:
    def get_reviewers(self, post_id):
        return (session.query(Author)
            .join(Comment, Comment.author_id == Author.id)
            .join(CommentType, Comment.comment_type == CommentType.name)
            .filter(Comment.post_id == post_id,
                    CommentType.name == 'review').all())

One method, three tables, every join condition spelled out, and one class that has to know the internal structure of all three relations at once.

Now the same question in halfORM:

class CommentType(db.get_relation_class('blog.comment_type')):
    Fkeys = {'rfk_comments': ...}

    def reviews(self):
        return CommentType(name='review').rfk_comments()

class Comment(db.get_relation_class('blog.comment')):
    Fkeys = {'fk_comment_type': ..., 'fk_author': ...}

    def reviewers(self):
        return self.fk_comment_type().reviews().fk_author()

class Post(db.get_relation_class('blog.post')):
    Fkeys = {'rfk_comments': ...}

    def reviewers(self):
        return self.rfk_comments().reviewers()

Three one-line methods, each on the class of the relation it describes, each delegating to its neighbour. No join condition appears anywhere. The query assembles itself as the delegation chain unwinds, and Post(id=42).reviewers() produces a single SQL query with three joins.

I call this predicate locality: every business predicate belongs on the Relation subclass of the entity it describes. It is, as far as I can tell, the most consequential thing about relation-oriented programming that isn't about queries at all.

Three properties fall out

It's set-general. Post.reviewers() works on any Post predicate. One post, all published posts, every post by a given author, with no modification:

Post(id=42).reviewers()                       # reviewers of one post
Post(published=True).reviewers()              # reviewers of all published posts
Author(name='Alice').rfk_posts().reviewers()  # reviewers of Alice's posts

The service version takes a post_id. To ask the second question you either call it in a loop (and now you have an N+1 problem in your service layer) or you rewrite it to accept a collection and rewrite the filter to match. The halfORM version never knew how many posts there were, because the argument was never a post id. It was a set.

Knowledge stays where it belongs. Post.reviewers() has no idea what a review is. It knows it has comments, and it knows comments know about reviewers. The definition of "review" (the string 'review', the fact that it's a row in comment_type at all) lives in CommentType, which is the only class that should know. Rename the type, add a second reviewing type, change the semantics: you touch CommentType.reviews() and nothing else.

That's Parnas's information-hiding criterion, applied with an unusually clean decomposition rule. Parnas's hard question is always what should each module hide? Here the answer is given to you: each class hides its own slice of the schema. And the delegation chain is the Law of Demeter applied to relational navigation: no class knows anything beyond its immediate neighbours in the FK graph. Cognitive load at each node is bounded by that node's degree.

Every level is independently testable. Because each method is anchored to one relation, you can test it against that relation alone:

from half_orm.testing import (assertConstraintsMatch,
                              assertTablePath, assertSamePredicate)

REVIEW_CONSTRAINT = dict(table='blog.comment_type', field='name', value='review')

class TestCommentType(TestCase):
    def test_reviews(self):
        reviews = CommentType().reviews()
        self.assertIsInstance(reviews, Comment)
        assertConstraintsMatch(reviews, **REVIEW_CONSTRAINT)

class TestComment(TestCase):
    def test_reviewers(self):
        reviewers = Comment().reviewers()
        self.assertIsInstance(reviewers, Author)
        assertConstraintsMatch(reviewers, **REVIEW_CONSTRAINT)
        assertTablePath(reviewers,
            'blog.comment', 'blog.comment_type', 'blog.comment', 'blog.author')

    def test_reviewers_delegates_to_comment_type(self):
        comment = Comment()
        assertSamePredicate(
            comment.reviewers(),
            comment.fk_comment_type().reviews().fk_author())

class TestPost(TestCase):
    def test_reviewers(self):
        reviewers = Post(id=42).reviewers()
        self.assertIsInstance(reviewers, Author)
        assertConstraintsMatch(reviewers, table='blog.post', field='id', value=42)
        assertConstraintsMatch(reviewers, **REVIEW_CONSTRAINT)

No SQL is executed. No fixture data is required. These assertions operate on the structure of the predicate: which tables it involves, which constraints it carries, whether one method really delegates to another.

And look at REVIEW_CONSTRAINT. The same constant is asserted at all three levels. That's not repetition; it's the evidence. Post.reviewers() is correct only because the comment_type.name = 'review' constraint introduced three delegations down survives the whole chain intact. Seeing the identical constant pass at every level is a direct, readable proof that it does.

The test suite ends up isomorphic to the code, which is isomorphic to the schema. One class per relation, one test class per relation, each testing only what its class knows.

Why the Repository pattern exists at all

Now the uncomfortable bit. Putting query logic on the entity class isn't just unusual in ORM codebases; it's actively discouraged. Fowler's Repository pattern and most Domain-Driven Design practice say the opposite: domain objects model behaviour, repositories own queries, and the boundary between them is load-bearing architecture.

I think that boundary is, in substantial part, a workaround.

Consider what an ORM entity actually is. It's a proxy tied to a session, carrying implicit state, with attributes that may or may not be loaded and that may issue queries when touched. Putting query logic on an object like that is dangerous: your method's behaviour depends on whether self is attached, detached, or expired; on whether the session is open; on what's already in the identity map. So the community developed the correct response to that constraint: move the queries somewhere the constraint doesn't apply. That's the Repository.

Remove the constraint and the workaround loses its reason to exist.

A halfORM Relation subclass is a stateless predicate. There's no session attachment, no identity, no lazy attribute, no loaded-or-not ambiguity. Calling a method on it composes a new predicate and returns it. There is no state to be wrong about, so there is nothing a query method on the class can break.

And the relational model imposes the decomposition criterion, rather than an architectural convention layered on top of the code: one class per relation, one predicate per business concept, anchored to the relation that holds it. The schema is the decomposition. You don't choose a module boundary and defend it in review; the foreign-key graph already drew it.

Which is not nothing, incidentally. "Where should this go?" is one of the most expensive recurring questions in a codebase, and most architectural patterns are attempts to answer it in advance. Here the answer is mechanical: which relation does this predicate constrain? That class.

It generalises

The blog example is the minimal non-trivial case. The pattern holds for any acyclic FK graph. For a path R₁ →ᶠ¹ R₂ →ᶠ² ⋯ →ᶠⁿ Rₙ, a predicate defined on R₁ composes predicates on R₂ … Rₙ through n−1 delegating methods, each O(1) in code written. Depth doesn't hurt you: a five-hop query is five one-line methods, and each one is readable in isolation because none of them can see past its neighbours.

Compare that to the service-layer version at five hops, which is a single method containing five join conditions and knowledge of five tables' internals, and which has to be rewritten every time any of those five schemas changes.

The adoption problem

The main thing that goes wrong when experienced developers pick up halfORM is that they keep the repository.

It's a trained habit. Years of separating mapping artefacts from business objects teaches you to treat a generated class as infrastructure (plumbing you shouldn't put domain logic into), and so people generate their model, then build a service layer on top of it and write the same joins they always wrote. It works. It just throws away most of the benefit, because now the query logic is centralised again, it isn't set-general again, and no class owns its own predicates again.

FK aliases, @singleton guards, and domain operations belong inside the Relation subclass. half-orm-dev makes this explicit in the generated files themselves, with a developer zone that the code generator is guaranteed never to touch, which is the subject of a later post in this series. But the shift is mental before it's technical, and it's the prerequisite for the rest.

If you take one thing from this essay: the Repository pattern was a correct response to session-bound entity proxies. If you don't have session-bound entity proxies, check whether you still need the response.


The testing helpers used here are documented in Testing.