xact is a recipe for handling transactions sensibly in Django applications on PostgreSQL.

Note: As of Django 1.6, the functionality of xact will be merged into the Django core as the atomic decorator. Code that uses xact should be able to be migrated to atomic with just a search-and-replace. atomic works on databases other than PostgreSQL, is thread-safe, and has other nice features; switch to it when you can!

The goals are:

• Database operations that do not modify the database aren't wrapped in a transactions at all.
• Database operations that modify the database are wrapped in a transactions.
• We have a lot of fine-grained control over sections that modify the databse vs those that don't.

The bits of the recipe are:

• Use the autocommit option in your database configuration.
• Do not use the transaction middleware.
• Wrap the sections of code which modify the database in the xact() decorator / context manager below, using it like you would the commit_on_success() decorator.
• Profit!

The quick reasons behind each step:

• Turning on autocommit prevents psycopg2 from automatically starting a new transaction on the first database operation on each connection; this means that the transaction only starts when we want it to.
• Similarly, the transaction middleware will set the connection state to "managed," which will defeat the autocommit option above, so we leave it out.
• The xact() decorator will set up the connection so that a transaction is started in the relevant block, which is what we want for database-modifying operations.

This recipe a few other nice features:

• xact() operates like commit_on_success(), in that it will issue a rollback if an exception escapes from the block or function it is wrapping.
• xact() ignores the dirty flag on the Django connection. Since we're deliberately wrapping stuff that modifies the database with it, the chance of it being dirty is near 100%, and a commit on a transaction that did not modify the database is no more expensive in PostgreSQL than a rollback. It also means you can do raw SQL inside an xact() block without the foot-gun of forgetting to call set_dirty.
• Like the built-in Django transaction decorators, it can be used either as a decorator or as a context manager with the with statement.
• xact() can be nested, giving us nested transactions! If it sees that there is already a transaction open when it starts a new block, it will use a savepoint to set up a nested transaction block. (PostgreSQL does not have nested transactions as such, but you can use savepoints to get 99.9% of the way there.)
• By not wrapping operations that do not modify the database, we get better behavior when using pgPool II (more on that in a future post).
• xact() works around an outstanding bug in Django's transaction handling on psycopg2.

xact() also supports the using parameter for multiple databases.

Rollback is a supplied exception class designed for situations in which you want to trigger an exception to cause a rollback, but do not want that exception to propagate beyond the scope of the xact block. xact will perform the rollback, then swallow the exception.

Of course, a few caveats:

• xact() requires the postgresql_psycopg2 backend, and PostgreSQL 8.2 or higher. It's possible it can be hacked to work on other backends that support savepoints.
• xact() works just the way you want if it is nested inside a commit_on_success() block (it will properly create a savepoint insted of a new transaction). However, a commit_on_success() block nested inside of xact() will commit or rollback the entire transaction, somewhat defeating the outer xact(). To the extent possible, use only xact() in code you write.
• Be sure you catch exceptions outside of the xact() block; otherwise, the automatic rollback will be defeated. Allow the exception to escape the xact() block, and then catch it. (Of course, if the intention is to always commit and to defeat the rollback, by all means catch the exception inside the block.)

To use, just drop the source (one class definition, one function) into a file somewhere in your Django project (such as the omni-present utils application every Django project seems to have), and include it.

Examples:

from utils.transaction import xact

@xact
def my_view_function1(request):
   # Everything here will be in a transaction.
   # It'll roll back if an exception escapes, commits otherwise.

def my_view_function2(request):
   # This stuff won't be in a transaction, so don't modify the database here.
   with xact():
      # This stuff will be, and will commit on normal completion, roll back on a exception

def my_view_function3(request):
   with xact():
      # Modify the database here (let's call it "part 1").
      try:
         with xact():
            # Let's call this "part 2."
            # This stuff will be in its own savepoint, and can commit or
            # roll back without losing the whole transaction.
      except:
         # Part 2 will be rolled back, but part 1 will still be available to
         # be committed or rolled back.  Of course, if an exception
         # inside the "part 2" block is not caught, both part 2 and
         # part 1 will be rolled back.