Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.7.x] Fixed #22491 -- documented how select_for_update() should be …

…tested.

Thanks Andreas Pelme for the report.

Backport of 668d432 from master
  • Loading branch information...
commit acbe3fac7c1210aacf2a931d9c5dde4f8fecd6c4 1 parent 2077bbe
@mmardini mmardini authored timgraham committed
Showing with 21 additions and 7 deletions.
  1. +17 −6 docs/ref/models/querysets.txt
  2. +4 −1 docs/topics/testing/tools.txt
View
23 docs/ref/models/querysets.txt
@@ -1421,17 +1421,18 @@ backends support ``select_for_update()``. However, MySQL has no support for the
``nowait`` argument. Obviously, users of external third-party backends should
check with their backend's documentation for specifics in those cases.
-Passing ``nowait=True`` to ``select_for_update`` using database backends that
+Passing ``nowait=True`` to ``select_for_update()`` using database backends that
do not support ``nowait``, such as MySQL, will cause a
:exc:`~django.db.DatabaseError` to be raised. This is in order to prevent code
unexpectedly blocking.
-Evaluating a queryset with ``select_for_update`` in autocommit mode is
-an error because the rows are then not locked. If allowed, this would
-facilitate data corruption, and could easily be caused by calling,
-outside of any transaction, code that expects to be run in one.
+Evaluating a queryset with ``select_for_update()`` in autocommit mode is
+a :exc:`~django.db.transaction.TransactionManagementError` error because the
+rows are not locked in that case. If allowed, this would facilitate data
+corruption and could easily be caused by calling code that expects to be run in
+a transaction outside of one.
-Using ``select_for_update`` on backends which do not support
+Using ``select_for_update()`` on backends which do not support
``SELECT ... FOR UPDATE`` (such as SQLite) will have no effect.
.. versionchanged:: 1.6.3
@@ -1439,6 +1440,16 @@ Using ``select_for_update`` on backends which do not support
It is now an error to execute a query with ``select_for_update()`` in
autocommit mode. With earlier releases in the 1.6 series it was a no-op.
+.. warning::
+
+ Although ``select_for_update()`` normally fails in autocommit mode, since
+ :class:`~django.test.TestCase` automatically wraps each test in a
+ transaction, calling ``select_for_update()`` in a ``TestCase`` even outside
+ an :func:`~django.db.transaction.atomic()` block will (perhaps unexpectedly)
+ pass without raising a ``TransactionManagementError``. To properly test
+ ``select_for_update()`` you should use
+ :class:`~django.test.TransactionTestCase`.
+
raw
~~~
View
5 docs/topics/testing/tools.txt
@@ -622,7 +622,10 @@ to test the effects of commit and rollback:
While ``commit`` and ``rollback`` operations still *appear* to work when
used in ``TestCase``, no actual commit or rollback will be performed by the
database. This can cause your tests to pass or fail unexpectedly. Always
- use ``TransactionTestCase`` when testing transactional behavior.
+ use ``TransactionTestCase`` when testing transactional behavior or any code
+ that can't normally be excuted in autocommit mode
+ (:meth:`~django.db.models.query.QuerySet.select_for_update()` is an
+ example).
``TransactionTestCase`` inherits from :class:`~django.test.SimpleTestCase`.
Please sign in to comment.
Something went wrong with that request. Please try again.