From: Mike Bayer Date: Sun, 11 Apr 2021 15:30:01 +0000 (-0400) Subject: Document AsyncSession.refresh() w/ refresh-expire cascade quirk X-Git-Tag: rel_1_4_8~17 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=7ea0d10c67b652895442c3a103e0813769309b9c;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git 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 23fec99eb7..51aba5b9c8 100644 --- 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 f56068fcc2..2d3002c6dd 100644 --- 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