Skip to content

Features

Intentional transaction management

Django Subatomic grants precise control over:

Unambiguous transactions

Subatomic's transaction unambiguously starts a new database transaction, unlike Django's atomic which sometimes creates a savepoint.

The exact behaviour of atomic can be tricky to reason about, and can lead to subtle bugs. By using Subatomic to explicitly express desired behaviour, developers are empowered to avoid these bugs.

Require atomicity separately from transaction management

Subatomic's transaction_required decorator allows developers to decouple code which must be run in a transaction from code which is responsible for the management of that transaction.

Using this instead of an atomic decorator also prevents the accidental creation of unnecessary savepoints when a transaction is already open. Subatomic provides the savepoint context manager for when savepoints are necessary.

Require durability without creating a transaction

Subatomic provides the durable decorator to ensure that a function is called durably without starting a database transaction at the same time.

No immediate "after-commit" callbacks

Subatomic's run_after_commit will ensure that after-commit callbacks are only registered when a transaction is open. If no transaction is open, an error will be raised. This can expose that a transaction is missing or open on a different database, and prevents code from reading as though a callback will be deferred when it won't be.

This is in contrast to the default behaviour of Django's on_commit function, where after-commit callbacks outside of transactions are run immediately.

More realistic tests

Usually, Django tests are each wrapped in a transaction which is rolled back when the test completes, meaning after-commit callbacks are not run.

To simulate realistic production behaviour, Subatomic runs after-commit callbacks when exiting the outermost transaction (or transaction_if_not_already) context. This emulates how the application will behave when deployed and means that tests reproduce realistic application behaviour without resorting to other more costly or error-prone testing strategies.

Progressive integration support

The larger your project is, the more likely you are to benefit from the guardrails offered by Django Subatomic's strict features. Paradoxically, the larger your project is, the more difficult it may be to enable them all.

Integrating Django Subatomic all at once could be a daunting task for larger projects, so we provide some settings to ease the process. These allow you to progressively roll out strict behaviour on a per-test or per-feature basis.