Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.6.x] Clarified why one must not catch database errors inside atomic.

Backport of 4db2752 from master.
  • Loading branch information...
commit 0ad178c43d7ac377480cc5fd5e3204f912603a49 1 parent 85ba68c
Aymeric Augustin authored September 20, 2013

Showing 1 changed file with 14 additions and 0 deletions. Show diff stats Hide diff stats

  1. 14  docs/topics/db/transactions.txt
14  docs/topics/db/transactions.txt
@@ -163,6 +163,20 @@ Django provides a single API to control database transactions.
163 163
     called, so the exception handler can also operate on the database if
164 164
     necessary.
165 165
 
  166
+    .. admonition:: Don't catch database exceptions inside ``atomic``!
  167
+
  168
+        If you catch :exc:`~django.db.DatabaseError` or a subclass such as
  169
+        :exc:`~django.db.IntegrityError` inside an ``atomic`` block, you will
  170
+        hide from Django the fact that an error has occurred and that the
  171
+        transaction is broken. At this point, Django's behavior is unspecified
  172
+        and database-dependent. It will usually result in a rollback, which
  173
+        may break your expectations, since you caught the exception.
  174
+
  175
+        The correct way to catch database errors is around an ``atomic`` block
  176
+        as shown above. If necessary, add an extra ``atomic`` block for this
  177
+        purpose -- it's cheap! This pattern is useful to delimit explicitly
  178
+        which operations will be rolled back if an exception occurs.
  179
+
166 180
     In order to guarantee atomicity, ``atomic`` disables some APIs. Attempting
167 181
     to commit, roll back, or change the autocommit state of the database
168 182
     connection within an ``atomic`` block will raise an exception.

0 notes on commit 0ad178c

Please sign in to comment.
Something went wrong with that request. Please try again.