Atomic transactions in Django

Atomicity when working with a database is quite an important aspect. Wikipedia defines atomicity as "an indivisible and irreducible series of database operations such that either all occur, or nothing occurs". This means that for the "happy path" when no error occurs it's fine to ignore atomicity. But as soon as your app grows large and complex enough that multiple database interactions must take place to perform an action, then the concept of atomic transactions comes into play.

Even though Django's documentation is more than enough, I will attempt a quick primer into how you can handle atomicity in Django.

The default way: Autocommit

This is how Django works if you don't make any effort to handle atomicity yourself. Every query is committed immediately into the database. If a query fails, the previous commits will not be rolled back.

# Transaction 1
user = CustomUser.objects.create_user([...])

# Transaction 2
profile = CustomUserProfile.objects.create(user=user,[...]).save()

In this example, if for some reason the user profile creation fails, the user will remain in the database.

The manual way: controlling transactions explicitly

With a decorator

Wrapping a function in the @transaction.atomic decorator ensures whatever database operations happen in the function, will be within the same transaction. This means that if an error is thrown, the transaction will be canceled and any database operations will be rolled back.

@transaction.atomic
def create_user_and_profile():
    user = CustomUser.objects.create_user([...])
    profile = CustomUserProfile.objects.create(user=user,[...]).save()

In the example above, if an error is thrown in the user profile creation, the user will not be created either. This means that we will have either a complete user & profile in the database or none of them.

If the entire view method is required to be in a single transaction, you can wrap that in a decorator.

class RegisterView(View):

    @transaction.atomic
    def post(self, request):
        [...]

Ideally, you would avoid doing this for performance reasons. You should aim to wrap the smallest amount of code possible with the decorator. Only the part that has to do with database interaction and not any generic processing. Opening a transaction is an expensive operation and on a bigger scale might have substantial performance penalties if used unwisely.

With a context manager

For more fine-grain control of the transaction, you can use the transaction.atomic() context manager.

def create_user_and_profile():

    with transaction.atomic():
        user = CustomUser.objects.create_user([...])
        profile = CustomUserProfile.objects.create(user=user,[...]).save()

The example above has the same results as the one with the decorator. So why go this way at all? This fine-grained control might be useful when you have to handle an error in a transaction.

@transaction.atomic
def create_user_profile_credits(request):
    user = CustomUser.objects.create_user([...])

    try:
        with transaction.atomic():
            profile = CustomUserProfile.objects.create(
                        user=user,[...]).save()
    except IntegrityError:
        # Print an error message

     credits = CustomUserCredits.objects.create(user=user,[...]).save()

In this example, the user profile is optional, that's why we capture the error for not rolling back the transaction. But the credits object is not optional and it's wrapped in a @transaction.atomic decorator. So we ensure that we either have the user+credits, or user+profile+credit in our database at all times.

The easy (but inefficient way): The atomic requests

Finally, Django offers an easy way for handling transactions which is to bound every view function to a transaction. Just set ATOMIC_REQUESTS to True in the configuration of each database for which you want to enable this behavior.

This is the same as wrapping every function with an @transaction.atomic as we've seen above. This might be convenient since every group of operations we do in a view function will be transactional, but on a bigger scale, this is quite inefficient. On the other hand, if you have a small app, going this way might be just fine.

Hopefully, you got a glimpse of the options Django offers on how to handle atomicity.

As always, happy coding!