Document AsyncSession.refresh() w/ refresh-expire cascade quirk

Change-Id: I90e884d12e5843609fa9078aaba4d471e80ba7cd
References: #6243

diff --git a/doc/build/orm/cascades.rst b/doc/build/orm/cascades.rst
index 23fec99eb79332d19cdf3a31c3c200e2652c414f..51aba5b9c8d66be172ab2bcd5b8cf0b1bfc1e5a6 100644 (file)
--- a/doc/build/orm/cascades.rst
+++ b/doc/build/orm/cascades.rst
@@ -57,6 +57,13 @@ and using it in conjunction with ``delete-orphan`` indicates that the child
 object should follow along with its parent in all cases, and be deleted once
 it is no longer associated with that parent.
 
+.. warning:: The ``all`` cascade option implies the
+   :ref:`cascade_refresh_expire`
+   cascade setting which may not be desirable when using the
+   :ref:`asyncio_toplevel` extension, as it will expire related objects
+   more aggressively than is typically appropriate in an explicit IO context.
+   See the notes at :ref:`asyncio_orm_avoid_lazyloads` for further background.
+
 The list of available values which can be specified for
 the :paramref:`_orm.relationship.cascade` parameter are described in the following subsections.
 

diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst
index f56068fcc25d8266259329520bd32e75ea423d5b..2d3002c6dda8de87e84bc6bc045f755012d4763f 100644 (file)
--- a/doc/build/orm/extensions/asyncio.rst
+++ b/doc/build/orm/extensions/asyncio.rst
@@ -265,6 +265,16 @@ Other guidelines include:
 * Methods like :meth:`_asyncio.AsyncSession.expire` should be avoided in favor of
   :meth:`_asyncio.AsyncSession.refresh`
 
+* Avoid using the ``all`` cascade option documented at :ref:`unitofwork_cascades`
+  in favor of listing out the desired cascade features explicitly.   The
+  ``all`` cascade option implies among others the :ref:`cascade_refresh_expire`
+  setting, which means that the :meth:`.AsyncSession.refresh` method will
+  expire the attributes on related objects, but not necessarily refresh those
+  related objects assuming eager loading is not configured within the
+  :func:`_orm.relationship`, leaving them in an expired state.   A future
+  release may introduce the ability to indicate eager loader options when
+  invoking :meth:`.Session.refresh` and/or :meth:`.AsyncSession.refresh`.
+
 * Appropriate loader options should be employed for :func:`_orm.deferred`
   columns, if used at all, in addition to that of :func:`_orm.relationship`
   constructs as noted above.  See :ref:`deferred` for background on