From 798fd59fad241ca8e48ba2a4526935b92736d30d Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Tue, 14 Jan 2014 04:41:52 -0800 Subject: [PATCH] Fixed #21836 -- Improved transaction docs about autocommit mode Clarified that queries in autocommit mode are committed immediately only if a transaction has not already been started. Added to the main transaction docs that Django's TestCase class implicitly wraps its tests in transactions. --- docs/topics/db/transactions.txt | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt index c7adb9e191..2bf545d12f 100644 --- a/docs/topics/db/transactions.txt +++ b/docs/topics/db/transactions.txt @@ -13,14 +13,17 @@ Django's default transaction behavior ------------------------------------- Django's default behavior is to run in autocommit mode. Each query is -immediately committed to the database. :ref:`See below for details -`. +immediately committed to the database, unless a transaction is active. +:ref:`See below for details `. Django uses transactions or savepoints automatically to guarantee the integrity of ORM operations that require multiple queries, especially :ref:`delete() ` and :ref:`update() ` queries. +Django's :class:`~django.test.TestCase` class also wraps each test in a +transaction for performance reasons. + .. versionchanged:: 1.6 Previous version of Django featured :ref:`a more complicated default @@ -231,13 +234,15 @@ Why Django uses autocommit -------------------------- In the SQL standards, each SQL query starts a transaction, unless one is -already in progress. Such transactions must then be committed or rolled back. +already active. Such transactions must then be explicitly committed or rolled +back. This isn't always convenient for application developers. To alleviate this problem, most databases provide an autocommit mode. When autocommit is turned -on, each SQL query is wrapped in its own transaction. In other words, the -transaction is not only automatically started, but also automatically -committed. +on and no transaction is active, each SQL query gets wrapped in its own +transaction. In other words, not only does each such query starts a +transaction, but the transaction also gets automatically committed or rolled +back, depending on whether the query succeeded. :pep:`249`, the Python Database API Specification v2.0, requires autocommit to be initially turned off. Django overrides this default and turns autocommit