Fixes: #4100

Add a warning, in two places, stating `with_for_update` will lock joinedload
tables, because at least one person did not expect the obvious to happen.

Also warn that eager loading techniques may not work with `with_for_update`
and combining the two is not officially supported or recommended.

Change-Id: Iedd609b56b3144d90a90fc2eea3cf5335a2d178a

diff --git a/doc/build/orm/loading_relationships.rst b/doc/build/orm/loading_relationships.rst
index 2734e68707edff732780533e5448921be70f0ecd..5a1d5151d4211528c9457fe5e5e3febb6c8209a9 100644 (file)
--- a/doc/build/orm/loading_relationships.rst
+++ b/doc/build/orm/loading_relationships.rst
@@ -444,6 +444,16 @@ On older versions of SQLite, the above nested right JOIN may be re-rendered
 as a nested subquery.  Older versions of SQLAlchemy would convert right-nested
 joins into subqueries in all cases.
 
+    .. warning::
+
+        Using ``with_for_update`` in the context of eager loading
+        relationships is not officially supported or recommended by
+        SQLAlchemy and may not work with certain queries on various
+        database backends.  When ``with_for_update`` is successfully used
+        with a query that involves :func:`_orm.joinedload`, SQLAlchemy will
+        attempt to emit SQL that locks all involved tables.
+
+
 Joined eager loading and result set batching
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index fcb9dae57ad0227bf47eedcba731745062a02c2c..48f4b9464846ea5f537c1d11b13072e71d9fb527 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1602,6 +1602,15 @@ class Query(
 
             SELECT users.id AS users_id FROM users FOR UPDATE OF users NOWAIT
 
+        .. warning::
+
+            Using ``with_for_update`` in the context of eager loading
+            relationships is not officially supported or recommended by
+            SQLAlchemy and may not work with certain queries on various
+            database backends.  When ``with_for_update`` is successfully used
+            with a query that involves :func:`_orm.joinedload`, SQLAlchemy will
+            attempt to emit SQL that locks all involved tables.
+
         .. note::  It is generally a good idea to combine the use of the
            :meth:`_orm.Query.populate_existing` method when using the
            :meth:`_orm.Query.with_for_update` method.   The purpose of