Repository, ou le métier qui ignore sa baseRepository, or the domain that ignores its database

Une règle métier noyée dans du SQL. Qu'est-ce qui devrait varier ?A business rule drowned in SQL. What should be allowed to vary?

On ouvre le volume des données par sa pièce de base. ship() porte une vraie règle — on n'expédie qu'une commande payée — mais elle est entrelacée avec un SELECT, une colonne, un driver. Deux choses de natures opposées vivent dans la même fonction : la règle, stable et propre au métier ; le stockage, volatil et purement technique. Ce qui varie, ce n'est pas la règle : c'est où et comment les données sont rangées. Le réflexe : le métier devrait demander ses commandes comme à une collection en mémoire, sans jamais savoir qu'il y a une base derrière.We open the data volume with its foundational piece. ship() carries a real rule — you only ship a paid order — but it's interwoven with a SELECT, a column, a driver. Two things of opposite natures live in the same function: the rule, stable and domain-owned; the storage, volatile and purely technical. What varies isn't the rule: it's where and how the data is stored. The reflex: the domain should ask for its orders as if from an in-memory collection, never knowing there's a database behind.

class OrderService:
    def ship(order_id):
        row = db.query("SELECT * FROM orders WHERE id = %s", order_id)  # SQL ici
        if row["status"] != "paid":          # ← LA règle métier, noyée
            raise CannotShip("commande non payée")
        db.query("UPDATE orders SET status='shipped' WHERE id=%s", order_id)
        # la règle « on n'expédie qu'une commande payée » est vraie…
        # mais elle est soudée à la table, au driver, au SQL. Intestable sans base.

Le schéma remonte partout, et la règle ne se teste qu'avec une base.The schema leaks everywhere, and the rule can only be tested with a database.

Mettre le SQL dans le métier a trois coûts qui se renforcent. Le schéma devient une dépendance publique : renommer une colonne casse des fonctions métier, parfois dans d'autres modules. La règle devient intestable sans infrastructure : pour vérifier « on n'expédie qu'une commande payée », il faut une vraie base, des fixtures, une connexion. Et la même requête se duplique : chaque service réécrit son SELECT, et le jour où la logique d'accès change, on la cherche partout.Putting SQL in the domain has three costs that reinforce each other. The schema becomes a public dependency: renaming a column breaks business functions, sometimes in other modules. The rule becomes untestable without infrastructure: to check 'you only ship a paid order', you need a real database, fixtures, a connection. And the same query duplicates: each service rewrites its SELECT, and the day the access logic changes, you hunt for it everywhere.

def test_refuse_ship_if_unpaid():
    db = spin_up_postgres()                 # 💥 une base entière…
    db.execute("INSERT INTO orders ...")     # … des fixtures SQL…
    with pytest.raises(CannotShip):          # … pour vérifier UN if.
        OrderService(db).ship(order_id)

On glisse une frontière : le métier parle à une collection, pas à une base.Slide in a boundary: the domain talks to a collection, not a database.

Le Repository fait croire au métier qu'il manipule une simple collection en mémoire — find, add, save — alors qu'un seul endroit, derrière, traduit ces gestes en SQL. L'animation installe cette frontière, puis inverse la flèche de dépendance comme au Vol 1 : ce n'est plus le métier qui dépend de la base, c'est la base qui réalise une interface possédée par le métier. Dernier temps : on débranche le SQL, on branche une collection en mémoire, et la règle se teste sans rien.The Repository makes the domain believe it's handling a plain in-memory collection — find, add, save — while one place, behind it, translates those gestures into SQL. The animation installs that boundary, then flips the dependency arrow as in Vol 1: it's no longer the domain depending on the database, it's the database realizing an interface owned by the domain. Final beat: unplug the SQL, plug an in-memory collection, and the rule tests with nothing.

# le métier — possède l'interface, parle sa langue, ignore le SQL
interface OrderRepository: find(id) -> Order; save(order)
class ShipOrder(repo: OrderRepository):
    def run(order_id):
        order = repo.find(order_id)
        order.ship()            # la règle « payé ? » vit DANS l'entité, testable seule
        repo.save(order)

# l'infra — la seule à connaître la base
class SqlOrderRepository implements OrderRepository:
    def find(id): row = db.query("SELECT ..."); return to_order(row)

Un objet nommé Repository ne suffit pas. Le faux qui laisse fuir la base.An object named Repository isn't enough. The fake that lets the database leak.

Le piège n'est pas d'oublier le Repository — c'est d'en écrire un qui ne cache rien. On crée une classe OrderRepository, on se sent en règle, mais ses méthodes rendent un query builder de l'ORM, ou prennent une chaîne SQL, ou exposent des noms de colonnes. Le métier, au-dessus, écrit toujours des filtres sur des tables : le couplage est intact, juste déguisé en abstraction. La frontière n'existe que si rien du stockage ne la traverse. Bascule le toggle : cherche le mot de persistance au-dessus de la ligne.The trap isn't forgetting the Repository — it's writing one that hides nothing. You create an OrderRepository class, you feel compliant, but its methods return an ORM query builder, or take a SQL string, or expose column names. The domain, above, still writes filters on tables: the coupling is intact, just disguised as an abstraction. The boundary only exists if nothing from storage crosses it. Flip the toggle: hunt the persistence word above the line.

# le Repository parle la langue du métier — il rend des entités, pas des lignes
class SqlOrderRepository(OrderRepository):
    def find(self, order_id) -> Order:          # ← rend une ENTITÉ métier
        row = self._db.query("SELECT ... WHERE id=%s", order_id)
        return Order(id=row["id"], status=row["status"], lines=...)   # SQL → domaine
    def save(self, order: Order):
        self._db.query("UPDATE orders SET status=%s ...", order.status)

# au-dessus de la frontière : aucun mot de persistance
class ShipOrder(repo: OrderRepository):
    def run(order_id):
        order = repo.find(order_id)   # pas de table, pas de colonne, pas de SELECT
        order.ship()                  # la règle vit dans l'entité, testable seule
        repo.save(order)

Le métier qui écrit du SQL, ou le métier qui ignore sa base.The domain that writes SQL, or the domain that ignores its database.

Quand ne pas extraire un RepositoryWhen not to extract a Repository

Le Repository a un loyer : une interface, un mapping entité↔table à écrire et tenir, une couche de plus à traverser pour lire. On reste en accès direct — et c'est correct — quand :The Repository has rent: an interface, an entity↔table mapping to write and maintain, one more layer to cross when reading. Stay with direct access — and that's fine — when:

• il n'y a pas de règle métier à protéger : un script d'export, un rapport, un job d'admin qui lit et recrache des lignes n'a aucune logique à isoler. Y glisser un Repository, c'est de la cérémonie (YAGNI, Vol 0 #3) — le SQL direct est plus honnête et plus court.there's no business rule to protect: an export script, a report, an admin job that reads and spits out rows has no logic to isolate. Sliding a Repository in there is ceremony (YAGNI, Vol 0 #3) — direct SQL is more honest and shorter.
• l'entité EST le stockage, et tu l'assumes : pour un CRUD simple sans invariants, Active Record (order.save()) couple sciemment objet et table — moins de code, un couplage accepté les yeux ouverts. C'est un choix légitime tant que la règle métier ne dépasse pas la validation de champs.the entity IS the storage, and you own it: for simple CRUD with no invariants, Active Record (order.save()) knowingly couples object and table — less code, a coupling accepted with eyes open. A legitimate choice as long as the business rule doesn't exceed field validation.
• le besoin de lecture est trop riche pour des entités : un tableau de bord qui agrège, joint et pagine n'a que faire d'objets Order reconstitués un par un. Là, une requête de lecture dédiée bat le Repository — et c'est exactement la fissure que le prochain numéro va creuser.the read need is too rich for entities: a dashboard that aggregates, joins and paginates has no use for Order objects rebuilt one by one. There, a dedicated read query beats the Repository — and that's exactly the crack the next issue will widen.

Le réflexe n'est donc pas « mets toujours un Repository » : c'est « y a-t-il une règle métier qui mérite d'ignorer sa base ? Si oui, glisse la frontière. Sinon, l'accès direct est plus court et plus franc. »So the reflex isn't 'always add a Repository': it's 'is there a business rule that deserves to ignore its database? If yes, slide the boundary in. If not, direct access is shorter and franker.'

Mot de l'éditeurFrom the editor

On ouvre le volume des données par la pièce la plus rassurante, parce qu'elle n'est pas neuve : le Repository, ce n'est que l'inversion de dépendance du Vol 1 pointée sur la persistance. Le métier possède le contrat, l'infrastructure l'implémente, la flèche va de la base vers le domaine. Si ce numéro ne laisse qu'une chose, que ce soit celle-là : « Repository » n'est pas un type d'objet à instancier, c'est une frontière que rien du stockage ne doit traverser. Le jour où un nom de colonne remonte dans une règle, la frontière a fui — quel que soit le nom de la classe.We open the data volume with its most reassuring piece, because it isn't new: the Repository is just Vol 1's dependency inversion aimed at persistence. The domain owns the contract, infrastructure implements it, the arrow runs from the database toward the domain. If this issue leaves only one thing, let it be this: 'Repository' isn't a kind of object to instantiate, it's a boundary nothing from storage may cross. The day a column name surfaces in a rule, the boundary leaked — whatever the class is called.

Mais le Repository fait une hypothèse tranquille qu'on n'a pas encore questionnée : qu'on lit et qu'on écrit le même modèle — la même entité Order pour décider d'expédier et pour afficher un tableau de bord. Le réflexe du volume était précisément « est-ce que je lis et j'écris le même modèle, et est-ce que ça me coûte ? ». Le #1 a répondu « range les deux derrière une frontière ». Le #2 va demander : et si lire et écrire avaient des besoins si différents qu'il vaille mieux deux modèles ? C'est la porte de CQRS.But the Repository makes a quiet assumption we haven't questioned yet: that you read and write the same model — the same Order entity to decide on shipping and to render a dashboard. The volume's reflex was precisely 'do I read and write the same model, and does it cost me?'. #1 answered 'put both behind a boundary'. #2 will ask: what if reading and writing had needs so different that two models were better? That's the door to CQRS.

Les voisins que ce numéro débloqueThe neighbors this issue unlocks

• Unit of Work — le compagnon du Repository : il regroupe plusieurs save dans une seule transaction et suit ce qui a changé, pour qu'on commit ou rollback en bloc. Le Repository dit « où » ; l'Unit of Work dit « quand tout part ensemble ».the Repository's companion: it groups several saves into one transaction and tracks what changed, so you commit or rollback as a block. The Repository says 'where'; the Unit of Work says 'when it all goes together'.
• Data Mapper — la mécanique sous le Repository : traduire entre l'entité et la table sans que l'une connaisse l'autre. C'est ce qui permet à Order de n'avoir aucune annotation de persistance — le mapping vit ailleurs, dans une couche qui ne fait que ça.the machinery under the Repository: translating between entity and table without either knowing the other. It's what lets Order carry no persistence annotation — the mapping lives elsewhere, in a layer that does only that.
• Active Record — le contraire assumé : l'entité connaît sa table et se sauve elle-même (order.save()). Couplage volontaire, moins de cérémonie — excellent pour un CRUD sans invariants, dangereux dès que la règle métier grandit. Le nommer, c'est se rappeler que le Repository est un choix, pas un dogme.the owned opposite: the entity knows its table and saves itself (order.save()). Deliberate coupling, less ceremony — excellent for invariant-free CRUD, dangerous as soon as the business rule grows. Naming it is a reminder that the Repository is a choice, not a dogma.

Le kata — écris-le, ne le relis pasThe kata — write it, don't reread it

# test_order_repository.py — la spec EST le harnais : fais-le passer au vert.
# le métier ne connaît qu'une collection ; une impl en mémoire suffit à tout tester.
# sans base, sans ORM, sans fixture SQL.

def test_add_puis_find():
    repo = InMemoryOrderRepository()
    repo.add(Order(id=1, status="paid"))
    assert repo.find(1).status == "paid"       # une collection : on range, on retrouve

def test_find_absent_rend_none():
    repo = InMemoryOrderRepository()
    assert repo.find(999) is None              # rien trouvé → None, pas d'exception

def test_la_regle_vit_dans_l_entite():
    o = Order(id=1, status="paid")
    o.ship()                                   # « on n'expédie que payé » : dans Order
    assert o.status == "shipped"

def test_regle_refuse_si_pas_paye():
    o = Order(id=1, status="pending")
    with raises(CannotShip): o.ship()          # invariant tenu sans toucher la base

def test_le_metier_ignore_le_stockage():
    repo = InMemoryOrderRepository()
    repo.add(Order(id=1, status="paid"))
    ShipOrder(repo).run(1)                      # le use case ne parle qu'au contrat…
    assert repo.find(1).status == "shipped"    # … et marche sur un dict en mémoire

def test_sans_save_rien_n_est_persiste():
    repo = InMemoryOrderRepository()
    repo.add(Order(id=1, status="paid"))
    o = repo.find(1)
    o.ship()                                   # on mute l'entité en mémoire…
    assert repo.find(1).status == "paid"       # …mais SANS repo.save(o), un find neuf ne
    # voit RIEN : la collection feinte doit COPIER comme un SELECT, sinon elle masque un
    # save oublié — un bug qui dort en test et casse en production.