Deprecated TransactionMiddleware and TRANSACTIONS_MANAGED.

Replaced them with per-database options, for proper multi-db support.

Also toned down the recommendation to tie transactions to HTTP requests.
Thanks Jeremy for sharing his experience.

5 files changed, 135 insertions, 40 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 6c13af7ae4..19675801e4 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -329,9 +329,14 @@ these changes.
 1.8
 ---
 
-* The decorators and context managers ``django.db.transaction.autocommit``,
-  ``commit_on_success`` and ``commit_manually`` will be removed. See
-  :ref:`transactions-upgrading-from-1.5`.
+* The following transaction management APIs will be removed:
+
+  - ``TransactionMiddleware``,
+  - the decorators and context managers ``autocommit``, ``commit_on_success``,
+    and ``commit_manually``,
+  - the ``TRANSACTIONS_MANAGED`` setting.
+
+  Upgrade paths are described in :ref:`transactions-upgrading-from-1.5`.
 
 * The :ttag:`cycle` and :ttag:`firstof` template tags will auto-escape their
   arguments. In 1.6 and 1.7, this behavior is provided by the version of these
diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index 1e6e57f720..20bb2fb751 100644
--- a/docs/ref/middleware.txt
+++ b/docs/ref/middleware.txt
@@ -205,6 +205,10 @@ Transaction middleware
 
 .. class:: TransactionMiddleware
 
+.. versionchanged:: 1.6
+    ``TransactionMiddleware`` is deprecated. The documentation of transactions
+    contains :ref:`upgrade instructions <transactions-upgrading-from-1.5>`.
+
 Binds commit and rollback of the default database to the request/response
 phase. If a view function runs successfully, a commit is done. If it fails with
 an exception, a rollback is done.
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 0cd141bcef..2b80527d8b 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -408,6 +408,30 @@ SQLite. This can be configured using the following::
 For other database backends, or more complex SQLite configurations, other options
 will be required. The following inner options are available.
 
+.. setting:: DATABASE-ATOMIC_REQUESTS
+
+ATOMIC_REQUESTS
+~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.6
+
+Default: ``False``
+
+Set this to ``True`` to wrap each HTTP request in a transaction on this
+database. See :ref:`tying-transactions-to-http-requests`.
+
+.. setting:: DATABASE-AUTOCOMMIT
+
+AUTOCOMMIT
+~~~~~~~~~~
+
+.. versionadded:: 1.6
+
+Default: ``True``
+
+Set this to ``False`` if you want to :ref:`disable Django's transaction
+management <deactivate-transaction-management>` and implement your own.
+
 .. setting:: DATABASE-ENGINE
 
 ENGINE
@@ -1807,6 +1831,12 @@ to ensure your processes are running in the correct environment.
 TRANSACTIONS_MANAGED
 --------------------
 
+.. deprecated:: 1.6
+
+    This setting was deprecated because its name is very misleading. Use the
+    :setting:`AUTOCOMMIT <DATABASE-AUTOCOMMIT>` key in :setting:`DATABASES`
+    entries instead.
+
 Default: ``False``
 
 Set this to ``True`` if you want to :ref:`disable Django's transaction
diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt
index cc3bf94ef5..a1fe69229c 100644
--- a/docs/releases/1.6.txt
+++ b/docs/releases/1.6.txt
@@ -262,9 +262,11 @@ Transaction management APIs
 Transaction management was completely overhauled in Django 1.6, and the
 current APIs are deprecated:
 
-- :func:`django.db.transaction.autocommit`
-- :func:`django.db.transaction.commit_on_success`
-- :func:`django.db.transaction.commit_manually`
+- ``django.middleware.transaction.TransactionMiddleware``
+- ``django.db.transaction.autocommit``
+- ``django.db.transaction.commit_on_success``
+- ``django.db.transaction.commit_manually``
+- the ``TRANSACTIONS_MANAGED`` setting
 
 The reasons for this change and the upgrade path are described in the
 :ref:`transactions documentation <transactions-upgrading-from-1.5>`.
diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt
index 91b2cf41b3..37a369a02f 100644
--- a/docs/topics/db/transactions.txt
+++ b/docs/topics/db/transactions.txt
@@ -26,45 +26,61 @@ immediately committed to the database. :ref:`See below for details
     Previous version of Django featured :ref:`a more complicated default
     behavior <transactions-upgrading-from-1.5>`.
 
+.. _tying-transactions-to-http-requests:
+
 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``.
+A common way to handle transactions on the web is to wrap each request in a
+transaction. Set :setting:`ATOMIC_REQUESTS <DATABASE-ATOMIC_REQUESTS>` to
+``True`` in the configuration of each database for which you want to enable
+this behavior.
 
 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.
+response is produced without problems, Django commits the transaction. If the
+view function produces an exception, Django rolls back the transaction.
+Middleware always runs outside of this transaction.
+
+You may perfom partial commits and rollbacks in your view code, typically with
+the :func:`atomic` context manager. However, at the end of the view, either
+all the changes will be committed, or none of them.
+
+To disable this behavior for a specific view, you must set the
+``transactions_per_request`` attribute of the view function itself to
+``False``, like this::
+
+    def my_view(request):
+        do_stuff()
+    my_view.transactions_per_request = False
+
+.. warning::
+
+    While the simplicity of this transaction model is appealing, it also makes it
+    inefficient when traffic increases. Opening a transaction for every view has
+    some overhead. The impact on performance depends on the query patterns of your
+    application and on how well your database handles locking.
 
-To activate this feature, just add the ``TransactionMiddleware`` middleware to
-your :setting:`MIDDLEWARE_CLASSES` setting::
+.. admonition:: Per-request transactions and streaming responses
 
-    MIDDLEWARE_CLASSES = (
-        'django.middleware.cache.UpdateCacheMiddleware',
-        'django.contrib.sessions.middleware.SessionMiddleware',
-        'django.middleware.common.CommonMiddleware',
-        'django.middleware.transaction.TransactionMiddleware',
-        'django.middleware.cache.FetchFromCacheMiddleware',
-    )
+    When a view returns a :class:`~django.http.StreamingHttpResponse`, reading
+    the contents of the response will often execute code to generate the
+    content. Since the view has already returned, such code runs outside of
+    the transaction.
 
-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.
+    Generally speaking, it isn't advisable to write to the database while
+    generating a streaming response, since there's no sensible way to handle
+    errors after starting to send the response.
 
-The various cache middlewares are an exception: ``CacheMiddleware``,
-:class:`~django.middleware.cache.UpdateCacheMiddleware`, and
-:class:`~django.middleware.cache.FetchFromCacheMiddleware` are never affected.
-Even when using database caching, Django's cache backend uses its own database
-connection internally.
+In practice, this feature simply wraps every view function in the :func:`atomic`
+decorator described below.
 
-.. note::
+Note that only the execution of your view in enclosed in the transactions.
+Middleware run outside of the transaction, and so does the rendering of
+template responses.
 
-    The ``TransactionMiddleware`` only affects the database aliased
-    as "default" within your :setting:`DATABASES` setting.  If you are using
-    multiple databases and want transaction control over databases other than
-    "default", you will need to write your own transaction middleware.
+.. versionchanged:: 1.6
+    Django used to provide this feature via ``TransactionMiddleware``, which is
+    now deprecated.
 
 Controlling transactions explicitly
 -----------------------------------
@@ -283,18 +299,20 @@ if autocommit is off. Django will also refuse to turn autocommit off when an
 Deactivating transaction management
 -----------------------------------
 
-Control freaks can totally disable all transaction management by setting
-:setting:`TRANSACTIONS_MANAGED` to ``True`` in the Django settings file. If
-you do this, Django won't enable autocommit. You'll get the regular behavior
-of the underlying database library.
+You can totally disable Django's transaction management for a given database
+by setting :setting:`AUTOCOMMIT <DATABASE-AUTOCOMMIT>` to ``False`` in its
+configuration. If you do this, Django won't enable autocommit, and won't
+perform any commits. You'll get the regular behavior of the underlying
+database library.
 
 This requires you to commit explicitly every transaction, even those started
 by Django or by third-party libraries. 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.
+.. versionchanged:: 1.6
+    This used to be controlled by the ``TRANSACTIONS_MANAGED`` setting.
+
 
 Database-specific notes
 =======================
@@ -459,6 +477,35 @@ atomicity of the outer block.
 API changes
 -----------
 
+Transaction middleware
+~~~~~~~~~~~~~~~~~~~~~~
+
+In Django 1.6, ``TransactionMiddleware`` is deprecated and replaced
+:setting:`ATOMIC_REQUESTS <DATABASE-ATOMIC_REQUESTS>`. While the general
+behavior is the same, there are a few differences.
+
+With the transaction middleware, it was still possible to switch to autocommit
+or to commit explicitly in a view. Since :func:`atomic` guarantees atomicity,
+this isn't allowed any longer.
+
+To avoid wrapping a particular view in a transaction, instead of::
+
+    @transaction.autocommit
+    def my_view(request):
+        do_stuff()
+
+you must now use this pattern::
+
+    def my_view(request):
+        do_stuff()
+    my_view.transactions_per_request = False
+
+The transaction middleware applied not only to view functions, but also to
+middleware modules that come after it. For instance, if you used the session
+middleware after the transaction middleware, session creation was part of the
+transaction. :setting:`ATOMIC_REQUESTS <DATABASE-ATOMIC_REQUESTS>` only
+applies to the view itself.
+
 Managing transactions
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -508,6 +555,13 @@ you should now use::
     finally:
         transaction.set_autocommit(autocommit=False)
 
+Disabling transaction management
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Instead of setting ``TRANSACTIONS_MANAGED = True``, set the ``AUTOCOMMIT`` key
+to ``False`` in the configuration of each database, as explained in :ref
+:`deactivate-transaction-management`.
+
 Backwards incompatibilities
 ---------------------------