django-subatomic: Django Subatomic: The library that makes transactions less magical

Django’s `atomic()` is convenient for the same reason it is dangerous: it can quietly do the wrong kind of thing for the moment you are in. `django-subatomic` answers that problem by removing the blur. It splits one broad helper into smaller, stricter tools that force you to say whether you are starting a transaction, requiring one, or only creating a local savepoint.

That sounds fussy until you look at the failure mode. The bug class here is not obvious corruption. It is code that passes in tests, looks fine in review, and then behaves differently when nested inside another transaction or wrapped by Django’s test harness.

The useful kind of friction

The library’s philosophy is not to make transaction work easier. It is to make wrong assumptions harder. The docs describe it as splitting Django’s `atomic` into more specific utilities, which is exactly the right framing: explicitness is the product, convenience is the trade-off.

Why `atomic()` was not enough

Django’s built-in `atomic()` is flexible in a way that hides intent. If you call it inside an existing transaction, it can create a savepoint. If you use it in tests, the surrounding `TestCase` machinery can make code feel safely transactional even when the production path is not equivalent.

That split matters because a transaction is not just a code pattern. It is a promise about who owns failure, who can roll back, and what should happen after commit. Subatomic wants those promises to be visible in the call site, not inferred from framework behavior.

The API is a set of decisions

from django_subatomic.db import transaction, transaction_required, savepoint, transaction_if_not_already

# Start a real transaction. If one already exists, this should not quietly nest.
with transaction():
    do_write()
    with savepoint():
        maybe_partial_failure()

# Require an existing transaction.
@transaction_required
def enqueue_after_commit_work():
    register_work()

# Clunky on purpose. Use only when ownership is unclear.
with transaction_if_not_already():
    legacy_work()

The naming is doing real work. `transaction_if_not_already()` is intentionally clunky because a smooth name would make a compromise look like a norm. The library keeps reminding you that ambiguity is usually a code smell.

The constraint engine behind the API

The deepest trick is not in the public helpers. It is in the internal context-manager machinery that refuses to behave like a decorator when that would blur scope. That is a small implementation choice with a big effect: it keeps transaction boundaries attached to the block where they are visible.

The point is locality. If a savepoint can only be used as a context manager, then rollback behavior stays where the human reader can see it. The library does not just guard the database. It guards the shape of the code around the database.

Kraken’s engineering blog gives the scale context for why this matters. As the blog says, "Here at Kraken we have a lot of code written in Python and the Django web framework. Including tests our main monorepo is well over 10 million lines!" That is exactly the kind of environment where small transaction ambiguities become expensive.

Testing without lying to yourself

The testing story is where Subatomic becomes more than a style preference. Django’s `TestCase` wraps each test in a transaction-like shell, which is useful for cleanup but dangerous for signaling. Code that requires a real transaction can appear satisfied when it is only living inside the test harness.

from django_subatomic.test import part_of_a_transaction
from django_subatomic.db import transaction_required

@transaction_required
def must_be_inside_real_transaction():
    return "ok"


def test_transaction_required_code():
    with part_of_a_transaction():
        assert must_be_inside_real_transaction() == "ok"

The helper exists so you can exercise transaction-sensitive code without depending on accidental test-state. That is a valuable discipline. Tests should verify durable behavior, not the illusion of it.

What this says about modern Django

Subatomic is a small library, but it argues for a larger shift in framework thinking. In mature systems, flexibility often becomes a liability because it makes the boundary between safe and unsafe behavior too easy to blur. The answer is not more magic. It is better boundaries.

That is why the project feels less like a helper library and more like an opinionated boundary system. It does not replace Django’s transaction model. It narrows it until the behavior is hard to misread.