Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

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.
  • Loading branch information...
commit 798fd59fad241ca8e48ba2a4526935b92736d30d 1 parent 7dd87aa
@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

With your changed wording, that should be "start" rather than "starts."

@aaugustin Owner

Oops. Sorry. Fixed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+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
Please sign in to comment.
Something went wrong with that request. Please try again.