Skip to content
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 798fd59 from master.
  • Loading branch information...
1 parent e2e4de6 commit a21fc1c08667dc319601b8195d0a7d3a4b8f2af5 @cjerdonek cjerdonek committed with aaugustin
Showing with 11 additions and 6 deletions.
  1. +11 −6 docs/topics/db/transactions.txt
17 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 <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
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
+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

0 comments on commit a21fc1c

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