Ticket #9206: extra_v3.diff

docs/topics/db/transactions.txt

@@ -166 +166 @@
 
 .. _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:
-      sid = transaction.savepoint()
-      x.save()
-      transaction.savepoint_commit(sid)
-    except IntegrityError:
-      transaction.savepoint_rollback(sid)
-      raise
+      b.save() # throws exception due to unique field
+    except:
+      pass
+    c.save() # fails as current transaction is aborted
 
-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.
+There are three possible solutions to this issue:
+
+    * 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 rollback
+          try:
+            b.save() # throws exception due to unique field
+          except:
+            transaction.rollback()
+          c.save() # succeeds
+
+      Note that under the ``commit_on_success`` or ``commit_manually``
+      decorators the rollback will also undo ``a.save()``.
+
+    * 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()
+            b.save() # throws exception due to unique field
+            transaction.savepoint_commit(sid)
+          except:
+            transaction.savepoint_rollback(sid)
+          c.save() # succeeds
+
+    * 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
+      savepoints are not required 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