- alter the yield_per eager restriction such that joined many-to-one loads

are still OK, since these should be fine.

2 files changed, 22 insertions, 7 deletions

diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst
index 016be974b..5f12cc969 100644
--- a/doc/build/changelog/changelog_10.rst
+++ b/doc/build/changelog/changelog_10.rst
@@ -25,11 +25,12 @@
         :tags: feature, orm
 
         The :class:`.Query` will raise an exception when :meth:`.Query.yield_per`
-        is used with mappings or options where eager loading, either
-        joined or subquery, would take place.  These loading strategies are
+        is used with mappings or options where either
+        subquery eager loading, or joined eager loading with collections,
+        would take place.  These loading strategies are
         not currently compatible with yield_per, so by raising this error,
-        the method is safer to use - combine with sending False to
-        :meth:`.Query.enable_eagerloads` to disable the eager loaders.
+        the method is safer to use.  Eager loads can be disabled with
+        the ``lazyload('*')`` option or :meth:`.Query.enable_eagerloads`.
 
         .. seealso::
 
diff --git a/doc/build/changelog/migration_10.rst b/doc/build/changelog/migration_10.rst
index 1aa0129c3..533682ebc 100644
--- a/doc/build/changelog/migration_10.rst
+++ b/doc/build/changelog/migration_10.rst
@@ -110,11 +110,25 @@ Joined/Subquery eager loading explicitly disallowed with yield_per
 ------------------------------------------------------------------
 
 In order to make the :meth:`.Query.yield_per` method easier to use,
-an exception is raised if any joined or subquery eager loaders are
+an exception is raised if any subquery eager loaders, or joined
+eager loaders that would use collections, are
 to take effect when yield_per is used, as these are currently not compatible
 with yield-per (subquery loading could be in theory, however).
-When this error is raised, the :meth:`.Query.enable_eagerloads` method
-should be called with a value of False to disable these eager loaders.
+When this error is raised, the :func:`.lazyload` option can be sent with
+an asterisk::
+
+	q = sess.query(Object).options(lazyload('*')).yield_per(100)
+
+or use :meth:`.Query.enable_eagerloads`::
+
+	q = sess.query(Object).enable_eagerloads(False).yield_per(100)
+
+The :func:`.lazyload` option has the advantage that additional many-to-one
+joined loader options can still be used::
+
+	q = sess.query(Object).options(
+		lazyload('*'), joinedload("some_manytoone")).yield_per(100)
+
 
 .. _migration_migration_deprecated_orm_events: