From 9666874ee180cfe02229e5f7f6488e367df246a9 Mon Sep 17 00:00:00 2001 From: Marc Tamlyn Date: Fri, 17 May 2013 16:12:49 +0200 Subject: [PATCH] Tidy up some of the transaction documentation. --- docs/topics/db/transactions.txt | 40 ++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt index 255584c68b4..78786996cd0 100644 --- a/docs/topics/db/transactions.txt +++ b/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: