Added an option to disable the creation of savepoints in atomic.

1 files changed, 9 insertions, 1 deletions

diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt
index 8cbe0dccd0..d5c22e17f5 100644
--- a/docs/topics/db/transactions.txt
+++ b/docs/topics/db/transactions.txt
@@ -89,7 +89,7 @@ Controlling transactions explicitly
 
 Django provides a single API to control database transactions.
 
-.. function:: atomic(using=None)
+.. 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.)
@@ -164,6 +164,14 @@ Django provides a single API to control database transactions.
     - releases or rolls back to the savepoint when exiting an inner block;
     - commits or rolls back the transaction when exiting the outermost block.
 
+    You can disable the creation of savepoints for inner blocks by setting the
+    ``savepoint`` argument to ``False``. If an exception occurs, Django will
+    perform the rollback when exiting the first parent block with a savepoint
+    if there is one, and the outermost block otherwise. Atomicity is still
+    guaranteed by the outer transaction. This option should only be used if
+    the overhead of savepoints is noticeable. It has the drawback of breaking
+    the error handling described above.
+
 .. admonition:: Performance considerations
 
     Open transactions have a performance cost for your database server. To