Commit a21fc1c0 authored by Chris Jerdonek's avatar Chris Jerdonek Committed by Aymeric Augustin
Browse files

[1.6.x] 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.

Backport of 798fd59f from master.
parent e2e4de65

docs/topics/db/transactions.txt

+11 −6
Original line number Diff line number Diff line
@@ -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

<autocommit-details>`.

immediately committed to the database, unless a transaction is active.

:ref:`See below for details <autocommit-details>`.



Django uses transactions or savepoints automatically to guarantee the

integrity of ORM operations that require multiple queries, especially

:ref:`delete() <topics-db-queries-delete>` and :ref:`update()

<topics-db-queries-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