Fixed #2705: added a `select_for_update()` clause to querysets.

A number of people worked on this patch over the years -- Hawkeye, Colin Grady,
KBS, sakyamuni, anih, jdemoor, and Issak Kelly. Thanks to them all, and
apologies if I missed anyone.

Special thanks to Dan Fairs for picking it up again at the end and seeing this
through to commit.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16058 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 53 insertions, 0 deletions

diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 1715afda6b..fb97c9f045 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -359,6 +359,13 @@ store a timezone-aware ``time`` or ``datetime`` to a
 :class:`~django.db.models.TimeField` or :class:`~django.db.models.DateTimeField`
 respectively, a ``ValueError`` is raised rather than truncating data.
 
+Row locking with ``QuerySet.select_for_update()``
+-------------------------------------------------
+
+MySQL does not support the ``NOWAIT`` option to the ``SELECT ... FOR UPDATE``
+statement. If ``select_for_update()`` is used with ``nowait=True`` then a
+``DatabaseError`` will be raised.
+
 .. _sqlite-notes:
 
 SQLite notes
@@ -493,6 +500,12 @@ If you're getting this error, you can solve it by:
       This will simply make SQLite wait a bit longer before throwing "database
       is locked" errors; it won't really do anything to solve them.
 
+``QuerySet.select_for_update()`` not supported
+----------------------------------------------
+
+SQLite does not support the ``SELECT ... FOR UPDATE`` syntax. Calling it will
+have no effect.
+
 .. _oracle-notes:
 
 Oracle notes
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index badcf38f53..f05368bc0c 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -966,6 +966,46 @@ For example::
     # queries the database with the 'backup' alias
     >>> Entry.objects.using('backup')
 
+select_for_update
+~~~~~~~~~~~~~~~~~
+
+.. method:: select_for_update(nowait=False)
+
+.. versionadded:: 1.4
+
+Returns a queryset that will lock rows until the end of the transaction,
+generating a ``SELECT ... FOR UPDATE`` SQL statement on supported databases.
+
+For example::
+
+    entries = Entry.objects.select_for_update().filter(author=request.user)
+
+All matched entries will be locked until the end of the transaction block,
+meaning that other transactions will be prevented from changing or acquiring
+locks on them.
+
+Usually, if another transaction has already acquired a lock on one of the
+selected rows, the query will block until the lock is released. If this is
+not the behaviour you want, call ``select_for_update(nowait=True)``. This will
+make the call non-blocking. If a conflicting lock is already acquired by
+another transaction, ``django.db.utils.DatabaseError`` will be raised when
+the queryset is evaluated.
+
+Note that using ``select_for_update`` will cause the current transaction to be
+set dirty, if under transaction management. This is to ensure that Django issues
+a ``COMMIT`` or ``ROLLBACK``, releasing any locks held by the ``SELECT FOR
+UPDATE``.
+
+Currently, the ``postgresql_psycopg2``, ``oracle``, and ``mysql``
+database backends support ``select_for_update()``. However, MySQL has no
+support for the ``nowait`` argument.
+
+Passing ``nowait=True`` to ``select_for_update`` using database backends that
+do not support ``nowait``, such as MySQL, will cause a ``DatabaseError`` to be
+raised. This is in order to prevent code unexpectedly blocking.
+
+Using ``select_for_update`` on backends which do not support
+``SELECT ... FOR UPDATE`` (such as SQLite) will have no effect.
 
 Methods that do not return QuerySets
 ------------------------------------