Ticket #9206: extra_v4.diff

docs/topics/db/transactions.txt

@@ -150 +150 @@
 all situations, you'll be better off using the default behavior, or the
 transaction middleware, and only modify selected functions as needed.
 
+Savepoints
+==========
+
+A savepoint is a marker within an open transaction that enables partial
+rollback to the point when it was created.
+
+Under the default ``autocommit`` decorator this is not very useful, since
+the open transaction is regularly committed in its entirety. However under
+the ``commit_on_success`` or ``commit_manually`` the open transaction will
+build up multiple database operations, so savepoints can provide more
+fine-grained rollback than a full ``transaction.rollback()``. Example::
+
+    from django.db import transaction
+
+    @transaction.commit_manually
+    def viewfunc(request):
+
+      a.save()
+      # open transaction now contains a.save()
+      sid = transaction.savepoint()
+
+      b.save()
+      # open transaction now contains a.save() and b.save()
+
+      if want_to_keep_b:
+        transaction.savepoint_commit(sid)
+        # open transaction still contains a.save() and b.save()
+
+      else:
+        transaction.savepoint_rollback(sid)
+        # open transaction now contains only a.save()
+
+      transaction.commit()
+
+Savepoints are implemented in the PostgreSQL 8 and Oracle backends.
+
 Transactions in MySQL
 =====================
 
@@ -166 +202 @@
 
 .. _information on MySQL transactions: http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html
 
-Transactions and savepoints in PostgreSQL 8
-===========================================
+Database exceptions within PostgreSQL transactions
+==================================================
 
-When a call to a PostgreSQL 8 cursor raises an exception, all subsequent SQL
-in the same transaction fails with the error "current transaction is aborted,
-queries ignored until end of transaction block". Whilst simple use of save()
-is unlikely to raise an exception in PostgreSQL, there are many more advanced
-usage patterns which might: for example, saving objects with unique fields,
-saving using the force_insert/force_update flag, or invoking custom SQL.
+When a call to a PostgreSQL cursor raises an exception (typically
+``IntegrityError``), all subsequent SQL in the same transaction fails with
+the error "current transaction is aborted, queries ignored until end of
+transaction block".  Whilst simple use of ``save()`` is unlikely to raise an
+exception in PostgreSQL, there are many more advanced usage patterns which
+might: for example, saving objects with unique fields, saving using the
+force_insert/force_update flag, or invoking custom SQL.  Example::
 
-In any of these cases, you can wrap the command which may throw
-IntegrityError inside savepoints, which will then allow subsequent commands
-to proceed. Example::
+    a.save() # succeeds
+    try:
+      b.save() # throws exception due to unique field
+    except:
+      pass
+    c.save() # fails under PostgreSQL as current transaction is aborted
+             # succeeds under all other database backends
 
+There are three possible solutions to this issue, of which Django recommends
+savepoint rollback:
+
+Transaction rollback
+--------------------
+
+With any version of PostgreSQL, you can rollback to the start of the
+transaction if you experience an exception. Example::
+
+    a.save() # succeeds, but may be undone by transaction rollback
     try:
+      b.save() # throws exception due to unique field
+    except:
+      transaction.rollback()
+    c.save() # succeeds, but a.save() may have been undone
+
+Note that under the ``commit_on_success`` or ``commit_manually``
+decorators the transaction rollback will also undo ``a.save()``.
+
+Savepoint rollback
+------------------
+
+With PostgreSQL 8 or later, you can wrap just the command which may raise an
+exception inside savepoints, isolating the rollback. Example::
+
+    a.save() # succeeds, and never undone by savepoint rollback
+    try:
       sid = transaction.savepoint()
-      x.save()
+      b.save() # throws exception due to unique field
       transaction.savepoint_commit(sid)
-    except IntegrityError:
+    except:
       transaction.savepoint_rollback(sid)
-      raise
+    c.save() # succeeds, and a.save() is never undone
 
-Savepoints are not implemented in PostgreSQL 7. If you experience an
-IntegrityError when using PostgreSQL 7, you will need to rollback to the
-start of the transaction.
+Note that ``a.save()`` is never undone.
+
+Database-level autocommit
+-------------------------
+
+.. versionadded:: 1.1
+
+With PostgreSQL 8.2 or later, there is an advanced option to run PostgreSQL
+with :ref:`database-level autocommit <ref-databases>`. With this option
+there is no constantly open transaction, so it is always possible to continue
+after catching an exception. Please see the documentation for that feature,
+which behaves differently from the standard ``autocommit`` decorator. 
+Example::
+
+    a.save() # succeeds
+    try:
+      b.save() # throws exception due to unique field
+    except:
+      pass
+    c.save() # succeeds