Browse files

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

Backport of 4db2752 from master.
  • Loading branch information...
1 parent 85ba68c commit 0ad178c43d7ac377480cc5fd5e3204f912603a49 @aaugustin aaugustin committed Sep 20, 2013
Showing with 14 additions and 0 deletions.
  1. +14 −0 docs/topics/db/transactions.txt
@@ -163,6 +163,20 @@ Django provides a single API to control database transactions.
called, so the exception handler can also operate on the database if
+ .. admonition:: Don't catch database exceptions inside ``atomic``!
+ If you catch :exc:`~django.db.DatabaseError` or a subclass such as
+ :exc:`~django.db.IntegrityError` inside an ``atomic`` block, you will
+ hide from Django the fact that an error has occurred and that the
+ transaction is broken. At this point, Django's behavior is unspecified
+ and database-dependent. It will usually result in a rollback, which
+ may break your expectations, since you caught the exception.
+ The correct way to catch database errors is around an ``atomic`` block
+ as shown above. If necessary, add an extra ``atomic`` block for this
+ purpose -- it's cheap! This pattern is useful to delimit explicitly
+ which operations will be rolled back if an exception occurs.
In order to guarantee atomicity, ``atomic`` disables some APIs. Attempting
to commit, roll back, or change the autocommit state of the database
connection within an ``atomic`` block will raise an exception.

0 comments on commit 0ad178c

Please sign in to comment.