django/docs/transactions.txt

==============================
Managing database transactions
==============================

Django gives you a few ways to control how database transactions are managed.

Django's default transaction behavior
=====================================

The default behavior of Django is to commit on special model functions. If you
call ``model.save()`` or ``model.delete()``, that change will be committed immediately.

This is much like the auto-commit setting for most databases: as soon as you
perform an action that needs to write to the database, Django produces the
insert/update/delete statements and then does the commit. There is no implicit
rollback in Django.

Tying transactions to HTTP requests
===================================

A useful way to handle transactions is to tie them to the request and response
phases.

When a request starts, you start a transaction. If the response is produced
without problems, any transactions are committed. If the view function produces
and exception, a rollback happens. This is one of the more intuitive ways to
handle transactions. To activate this feature, just add the
``TransactionMiddleware`` middleware to your stack::

    MIDDLEWARE_CLASSES = (
        "django.middleware.common.CommonMiddleware",
        "django.middleware.sessions.SessionMiddleware",
        "django.middleware.cache.CacheMiddleware",
        "django.middleware.transaction.TransactionMiddleware",
    )

The order is quite important: the transaction middleware will be relevant not
only for the view functions called, but for all middleware modules that come
after it. So if you use the session middleware after the transaction middleware,
session creation will be part of the transaction.

The cache middleware isn't affected, as it uses its own database cursor (which
is mapped to its own database connection internally), and only the
database-based cache is affected.

Controlling transaction management in views
===========================================

For many people, implicit request-based transactions will work wonderfully.
However, if you need to control the way that transactions are managed,
you can use decorators that you can apply to a function to change the way
transactions are handled.

.. note::

    Although the examples below use view functions as examples, these
    decorators can be applied to non-view functions as well.

``autocommit``
--------------

You can use the ``autocommit`` decorator to switch a view function to the
default commit behavior of Django, regardless of the global setting. Just use
the decorator like this::

    from django.db.transaction import autocommit

    @transaction.autocommit
    def viewfunc(request):
        ....

Within ``viewfunc`` transactions will be committed as soon as you call
``model.save()``, ``model.delete()``, or any other function that writes to the
database.

``commit_on_success``
---------------------

You can use the ``commit_on_success`` decorator to use a single transaction for
all the work done in a function::

    from django.db import transaction

    @transaction.commit_on_success
    def viewfunc(request):
        ....

If the function returns successfully, then all work done will be committed. If an
exception is raised beyond the function, however, the transaction will be rolled
back.

``commit_manually``
-------------------

Sometimes you need full control over your transactions. In that case, you can use the
``commit_manually`` decorator, which tells Django you'll be managing the transaction
on your own.

If you don't commit or rollback and did change data (so that the current
transaction is marked as dirty), you'll get a ``TransactionManagementError``
exception.

Manual transaction management looks like::

    from django.db import transaction

    @transaction.commit_manually
    def viewfunc(request):
        ...
        # You can commit/rollback however and whenever you want
        transaction.commit()
        ...

        # But you've got to remember to do it yourself!
        try:
            ...
        except:
            transaction.rollback()
        else:
            transaction.commit()

..admonition:: An important note to users of earlier Django releases:

    The database ``connection.commit`` and ``connection.rollback`` functions
    (also called ``db.commit`` and ``db.rollback`` in 0.91 and earlier), no
    longer exist and have been replaced by the ``transaction.commit`` and
    ``transaction.rollback`` commands.

How to globally deactivate transaction management
=================================================

Control freaks can totally disable all transaction management by setting
``DISABLE_TRANSACTION_MANAGEMENT`` to ``True`` in the Django settings file.

If you do this, there will be no management whatsoever. The middleware will no
longer implicitly commit transactions, and you'll need to roll management
yourself. This even will require you to commit changes done by middleware
somewhere else.

Thus, this is best used in situations where you want to run your own transaction
controlling middleware or do something really strange. In almost all situations,
you'll be better off using the default behavior or the transaction middleware
and only modify selected functions as needed.