Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Tidy up some of the transaction documentation.

  • Loading branch information...
commit 9666874ee180cfe02229e5f7f6488e367df246a9 1 parent 838f289
@mjtamlyn mjtamlyn authored
Showing with 22 additions and 18 deletions.
  1. +22 −18 docs/topics/db/transactions.txt
View
40 docs/topics/db/transactions.txt
@@ -92,19 +92,15 @@ Django provides a single API to control database transactions.
.. function:: atomic(using=None, savepoint=True)
- This function creates an atomic block for writes to the database.
- (Atomicity is the defining property of database transactions.)
+ Atomicity is the defining property of database transactions. ``atomic``
+ allows us to create a block of code within which the atomicity on the
+ database is guaranteed. If the block of code is successfully completed, the
+ changes are committed to the database. If there is an exception, the
+ changes are rolled back.
- When the block completes successfully, the changes are committed to the
- database. When it raises an exception, the changes are rolled back.
-
- ``atomic`` can be nested. In this case, when an inner block completes
- successfully, its effects can still be rolled back if an exception is
- raised in the outer block at a later point.
-
- ``atomic`` takes a ``using`` argument which should be the name of a
- database. If this argument isn't provided, Django uses the ``"default"``
- database.
+ ``atomic`` blocks can be nested. In this case, when an inner block
+ completes successfully, its effects can still be rolled back if an
+ exception is raised in the outer block at a later point.
``atomic`` is usable both as a `decorator`_::
@@ -137,24 +133,32 @@ Django provides a single API to control database transactions.
@transaction.atomic
def viewfunc(request):
- do_stuff()
+ create_parent()
try:
with transaction.atomic():
- do_stuff_that_could_fail()
+ generate_relationships()
except IntegrityError:
handle_exception()
- do_more_stuff()
+ add_children()
- In this example, even if ``do_stuff_that_could_fail()`` causes a database
+ In this example, even if ``generate_relationships()`` causes a database
error by breaking an integrity constraint, you can execute queries in
- ``do_more_stuff()``, and the changes from ``do_stuff()`` are still there.
+ ``add_children()``, and the changes from ``create_parent()`` are still
+ there. Note that any operations attempted in ``generate_relationships()``
+ will already have been rolled back safely when ``handle_exception()`` is
+ called, so the exception handler can also operate on the database if
+ necessary.
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.
+ ``atomic`` takes a ``using`` argument which should be the name of a
+ database. If this argument isn't provided, Django uses the ``"default"``
+ database.
+
Under the hood, Django's transaction management code:
- opens a transaction when entering the outermost ``atomic`` block;
@@ -516,7 +520,7 @@ Transaction states
The three functions described above relied on a concept called "transaction
states". This mechanisme was deprecated in Django 1.6, but it's still
-available until Django 1.8..
+available until Django 1.8.
At any time, each database connection is in one of these two states:
Please sign in to comment.
Something went wrong with that request. Please try again.