Fixed #9964 -- Ensure that all database operations make transactions dirty, not just write operations. Many thanks to Shai Berger for his work and persistence on this issue.

This is BACKWARDS INCOMPATIBLE for anyone relying on the current behavior that allows manually managed read-only transactions to be left dangling without a manual commit or rollback.

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

3 files changed, 74 insertions, 39 deletions

diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt
index ad93f09185..aca227f896 100644
--- a/docs/releases/1.3.txt
+++ b/docs/releases/1.3.txt
@@ -604,6 +604,42 @@ domain):
 
 .. _corresponding deprecated features section: loading_of_translations_from_the_project_directory_
 
+Transaction management
+~~~~~~~~~~~~~~~~~~~~~~
+
+When using managed transactions -- that is, anything but the default
+autocommit mode -- it is important when a transaction is marked as
+"dirty". Dirty transactions are committed by the
+:func:`~django.db.transaction.commit_on_success` decorator or the
+:class:`~django.middleware.transaction.TransactionMiddleware`, and
+:func:`~django.db.transaction.commit_manually` forces them to be
+closed explicitly; clean transactions "get a pass", which means they
+are usually rolled back at the end of a request when the connection is
+closed.
+
+Until Django 1.3, transactions were only marked dirty when Django was
+aware of a modifying operation performed in them; that is, either some
+model was saved, some bulk update or delete was performed, or the user
+explicitly called ``transaction.set_dirty()``. In Django 1.3, a
+transaction is marked dirty when *any* database operation is
+performed.
+
+As a result of this change, you no longer need to set a transaction
+dirty explicitly when you execute raw SQL or use a data-modifying
+``SELECT``. However, you *do* need to explicitly close any read-only
+transactions that are being managed using
+:func:`~django.db.transaction.commit_manually`. For example::
+
+      @transaction.commit_manually
+      def my_view(request, name):
+      	  obj = get_object_or_404(MyObject, name__iexact=name)
+	  return render_to_response('template', {'object':obj})
+
+Prior to Django 1.3, this would work without error. However, under
+Django 1.3, this will raise a :class:`TransactionManagementError` because
+the read operation that retrieves the ``MyObject`` instance leaves the
+transaction in a dirty state.
+
 .. _deprecated-features-1.3:
 
 Features deprecated in 1.3
diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt
index 2698bb0f04..6be59c5d5a 100644
--- a/docs/topics/db/sql.txt
+++ b/docs/topics/db/sql.txt
@@ -233,37 +233,17 @@ alias::
 
 Transactions and raw SQL
 ------------------------
-If you are using transaction decorators (such as ``commit_on_success``) to
-wrap your views and provide transaction control, you don't have to make a
-manual call to ``transaction.commit_unless_managed()`` -- you can manually
-commit if you want to, but you aren't required to, since the decorator will
-commit for you. However, if you don't manually commit your changes, you will
-need to manually mark the transaction as dirty, using
-``transaction.set_dirty()``::
 
-    @commit_on_success
-    def my_custom_sql_view(request, value):
-        from django.db import connection, transaction
-        cursor = connection.cursor()
-
-        # Data modifying operation
-        cursor.execute("UPDATE bar SET foo = 1 WHERE baz = %s", [value])
-
-        # Since we modified data, mark the transaction as dirty
-        transaction.set_dirty()
-
-        # Data retrieval operation. This doesn't dirty the transaction,
-        # so no call to set_dirty() is required.
-        cursor.execute("SELECT foo FROM bar WHERE baz = %s", [value])
-        row = cursor.fetchone()
+When you make a raw SQL call, Django will automatically mark the
+current transaction as dirty. You must then ensure that the
+transaction containing those calls is closed correctly. See :ref:`the
+notes on the requirements of Django's transaction handling
+<topics-db-transactions-requirements>` for more details.
 
-        return render_to_response('template.html', {'row': row})
+.. versionchanged:: 1.3
 
-The call to ``set_dirty()`` is made automatically when you use the Django ORM
-to make data modifying database calls. However, when you use raw SQL, Django
-has no way of knowing if your SQL modifies data or not. The manual call to
-``set_dirty()`` ensures that Django knows that there are modifications that
-must be committed.
+Prior to Django 1.3, it was necessary to manually mark a transaction
+as dirty using ``transaction.set_dirty()`` when using raw SQL calls.
 
 Connections and cursors
 -----------------------
diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt
index 80971613e0..6e7288ec1d 100644
--- a/docs/topics/db/transactions.txt
+++ b/docs/topics/db/transactions.txt
@@ -70,35 +70,35 @@ per-function or per-code-block basis.
 These functions, described in detail below, can be used in two different ways:
 
     * As a decorator_ on a particular function. For example::
-    
+
             from django.db import transaction
-            
+
             @transaction.commit_on_success()
             def viewfunc(request):
                 # ...
                 # this code executes inside a transaction
                 # ...
-                
+
       This technique works with all supported version of Python (that is, with
       Python 2.4 and greater).
-      
+
     * As a `context manager`_ around a particular block of code::
-    
+
             from django.db import transaction
-            
+
             def viewfunc(request):
                 # ...
                 # this code executes using default transaction management
-                # ... 
-                
+                # ...
+
                 with transaction.commit_on_success():
                     # ...
                     # this code executes inside a transaction
                     # ...
-                    
+
       The ``with`` statement is new in Python 2.5, and so this syntax can only
       be used with Python 2.5 and above.
-      
+
 .. _decorator: http://docs.python.org/glossary.html#term-decorator
 .. _context manager: http://docs.python.org/glossary.html#term-context-manager
 
@@ -106,7 +106,7 @@ For maximum compatibility, all of the examples below show transactions using the
 decorator syntax, but all of the follow functions may be used as context
 managers, too.
 
-.. note:: 
+.. note::
 
     Although the examples below use view functions as examples, these
     decorators and context managers can be used anywhere in your code
@@ -187,6 +187,25 @@ managers, too.
         def viewfunc2(request):
             ....
 
+.. _topics-db-transactions-requirements:
+
+Requirements for transaction handling
+=====================================
+
+.. versionadded:: 1.3
+
+Django requires that every transaction that is opened is closed before
+the completion of a request. If you are using :func:`autocommit` (the
+default commit mode) or :func:`commit_on_success`, this will be done
+for you automatically. However, if you are manually managing
+transactions (using the :func:`commit_manually` decorator), you must
+ensure that the transaction is either committed or rolled back before
+a request is completed.
+
+This applies to all database operations, not just write operations. Even
+if your transaction only reads from the database, the transaction must
+be committed or rolled back before you complete a request.
+
 How to globally deactivate transaction management
 =================================================