Warn that before_compile for lazyload needs bake_queries=False

The longer term future plan for ORM queries is that there
will be a new hook that receives queries before invocation
rather than "compilation", which will make use of a new
caching system.

Fixes: #4947
Change-Id: I256c16155a0cc9b7133e86e22d27040cb64eb1a9
(cherry picked from commit 172d99a8a1282b534aeadafebdd2af0162758931)

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index b243e783b32fefbf1abde45873c4e4ed2b48ea68..8b560804f9e7837a9e867e97261a7b793ddaf337 100644 (file)
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -2391,6 +2391,13 @@ class QueryEvents(event.Events):
         The event should normally be listened with the ``retval=True``
         parameter set, so that the modified query may be returned.
 
+        .. warning::  If the :meth:`.QueryEvents.before_compile` event is to
+           be applied to :class:`.Query` objects that are used for lazy loading
+           of :func:`.relationships` (as described at :ref:`lazy_loading`),
+           it may be necessary to set :paramref:`.relationship.bake_queries`
+           to ``False``, else the :meth:`.QueryEvents.before_compile` event
+           will not be invoked for each lazy load operation.
+
         .. seealso::
 
             :meth:`.QueryEvents.before_compile_update`