From f3e0bef712da7a40ead247994413b36e5e3dd97b Mon Sep 17 00:00:00 2001 From: jonathan vanasco Date: Fri, 24 Sep 2021 14:55:59 -0400 Subject: [PATCH] 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 --- doc/build/orm/loading_relationships.rst | 10 ++++++++++ lib/sqlalchemy/orm/query.py | 9 +++++++++ 2 files changed, 19 insertions(+) diff --git a/doc/build/orm/loading_relationships.rst b/doc/build/orm/loading_relationships.rst index 2734e68707..5a1d5151d4 100644 --- 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 fcb9dae57a..48f4b94648 100644 --- 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 -- 2.47.3