Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
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...
commit a21fc1c08667dc319601b8195d0a7d3a4b8f2af5 1 parent e2e4de6
@cjerdonek cjerdonek authored aaugustin committed
Showing with 11 additions and 6 deletions.
  1. +11 −6 docs/topics/db/transactions.txt
View
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
-<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

0 comments on commit a21fc1c

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