Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Tidy up some of the transaction documentation.

  • Loading branch information...
commit 9666874ee180cfe02229e5f7f6488e367df246a9 1 parent 838f289
Marc Tamlyn authored May 17, 2013

Showing 1 changed file with 22 additions and 18 deletions. Show diff stats Hide diff stats

  1. 40  docs/topics/db/transactions.txt
40  docs/topics/db/transactions.txt
@@ -92,19 +92,15 @@ Django provides a single API to control database transactions.
92 92
 
93 93
 .. function:: atomic(using=None, savepoint=True)
94 94
 
95  
-    This function creates an atomic block for writes to the database.
96  
-    (Atomicity is the defining property of database transactions.)
  95
+    Atomicity is the defining property of database transactions. ``atomic``
  96
+    allows us to create a block of code within which the atomicity on the
  97
+    database is guaranteed. If the block of code is successfully completed, the
  98
+    changes are committed to the database. If there is an exception, the
  99
+    changes are rolled back.
97 100
 
98  
-    When the block completes successfully, the changes are committed to the
99  
-    database. When it raises an exception, the changes are rolled back.
100  
-
101  
-    ``atomic`` can be nested. In this case, when an inner block completes
102  
-    successfully, its effects can still be rolled back if an exception is
103  
-    raised in the outer block at a later point.
104  
-
105  
-    ``atomic`` takes a ``using`` argument which should be the name of a
106  
-    database. If this argument isn't provided, Django uses the ``"default"``
107  
-    database.
  101
+    ``atomic`` blocks can be nested. In this case, when an inner block
  102
+    completes successfully, its effects can still be rolled back if an
  103
+    exception is raised in the outer block at a later point.
108 104
 
109 105
     ``atomic`` is usable both as a `decorator`_::
110 106
 
@@ -137,24 +133,32 @@ Django provides a single API to control database transactions.
137 133
 
138 134
         @transaction.atomic
139 135
         def viewfunc(request):
140  
-            do_stuff()
  136
+            create_parent()
141 137
 
142 138
             try:
143 139
                 with transaction.atomic():
144  
-                    do_stuff_that_could_fail()
  140
+                    generate_relationships()
145 141
             except IntegrityError:
146 142
                 handle_exception()
147 143
 
148  
-            do_more_stuff()
  144
+            add_children()
149 145
 
150  
-    In this example, even if ``do_stuff_that_could_fail()`` causes a database
  146
+    In this example, even if ``generate_relationships()`` causes a database
151 147
     error by breaking an integrity constraint, you can execute queries in
152  
-    ``do_more_stuff()``, and the changes from ``do_stuff()`` are still there.
  148
+    ``add_children()``, and the changes from ``create_parent()`` are still
  149
+    there. Note that any operations attempted in ``generate_relationships()``
  150
+    will already have been rolled back safely when ``handle_exception()`` is
  151
+    called, so the exception handler can also operate on the database if
  152
+    necessary.
153 153
 
154 154
     In order to guarantee atomicity, ``atomic`` disables some APIs. Attempting
155 155
     to commit, roll back, or change the autocommit state of the database
156 156
     connection within an ``atomic`` block will raise an exception.
157 157
 
  158
+    ``atomic`` takes a ``using`` argument which should be the name of a
  159
+    database. If this argument isn't provided, Django uses the ``"default"``
  160
+    database.
  161
+
158 162
     Under the hood, Django's transaction management code:
159 163
 
160 164
     - opens a transaction when entering the outermost ``atomic`` block;
@@ -516,7 +520,7 @@ Transaction states
516 520
 
517 521
 The three functions described above relied on a concept called "transaction
518 522
 states". This mechanisme was deprecated in Django 1.6, but it's still
519  
-available until Django 1.8..
  523
+available until Django 1.8.
520 524
 
521 525
 At any time, each database connection is in one of these two states:
522 526
 

0 notes on commit 9666874

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