MERGED MAGIC-REMOVAL BRANCH TO TRUNK. This change is highly backwards-incompatible. Please read http://code.djangoproject.com/wiki/RemovingTheMagic for upgrade instructions.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@2809 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 146 insertions, 0 deletions

diff --git a/docs/transactions.txt b/docs/transactions.txt
new file mode 100644
index 0000000000..6b2e6fda8f
--- /dev/null
+++ b/docs/transactions.txt
@@ -0,0 +1,146 @@
+==============================
+Managing database transactions
+==============================
+
+Django gives you a few ways to control how database transactions are managed.
+
+Django's default transaction behavior
+=====================================
+
+Django's default behavior is to commit automatically when any built-in,
+data-altering model function is called. For example, if you call
+``model.save()`` or ``model.delete()``, the 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's no implicit ``ROLLBACK``.
+
+Tying transactions to HTTP requests
+===================================
+
+The recommended way to handle transactions in Web requests is to tie them to
+the request and response phases via Django's ``TransactionMiddleware``.
+
+It works like this: When a request starts, Django starts a transaction. If the
+response is produced without problems, Django commits any pending transactions.
+If the view function produces an exception, Django rolls back any pending
+transactions.
+
+To activate this feature, just add the ``TransactionMiddleware`` middleware to
+your ``MIDDLEWARE_CLASSES`` setting::
+
+    MIDDLEWARE_CLASSES = (
+        "django.contrib.sessions.middleware.SessionMiddleware",
+        "django.middleware.common.CommonMiddleware",
+        "django.middleware.cache.CacheMiddleware",
+        "django.middleware.transaction.TransactionMiddleware",
+    )
+
+The order is quite important. The transaction middleware applies not only to
+view functions, but also 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.
+
+An exception is ``CacheMiddleware``, which is never affected. The cache
+middleware uses its own database cursor (which is mapped to its own database
+connection internally).
+
+Controlling transaction management in views
+===========================================
+
+For most people, implicit request-based transactions work wonderfully. However,
+if you need more fine-grained control over how transactions are managed, you
+can use Python decorators to change the way transactions are handled by a
+particular view function.
+
+.. note::
+
+    Although the examples below use view functions as examples, these
+    decorators can be applied to non-view functions as well.
+
+``django.db.transaction.autocommit``
+------------------------------------
+
+Use the ``autocommit`` decorator to switch a view function to Django's default
+commit behavior, regardless of the global transaction setting.
+
+Example::
+
+    from django.db import transaction
+
+    @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.
+
+``django.db.transaction.commit_on_success``
+-------------------------------------------
+
+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 Django will commit all work done
+within the function at that point. If the function raises an exception, though,
+Django will roll back the transaction.
+
+``django.db.transaction.commit_manually``
+-----------------------------------------
+
+Use the ``commit_manually`` decorator if you need full control over
+transactions. It tells Django you'll be managing the transaction on your own.
+
+If your view changes data and doesn't ``commit()`` or ``rollback()``, Django
+will raise a ``TransactionManagementError`` exception.
+
+Manual transaction management looks like this::
+
+    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()`` methods
+    (called ``db.commit()`` and ``db.rollback()`` in 0.91 and earlier) no longer
+    exist. They've been replaced by ``transaction.commit()`` and
+    ``transaction.rollback()``.
+
+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, Django won't provide any automatic transaction management
+whatsoever. Middleware will no longer implicitly commit transactions, and
+you'll need to roll management yourself. This even requires 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.