From 7ea0d10c67b652895442c3a103e0813769309b9c Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 11 Apr 2021 11:30:01 -0400 Subject: [PATCH] Document AsyncSession.refresh() w/ refresh-expire cascade quirk Change-Id: I90e884d12e5843609fa9078aaba4d471e80ba7cd References: #6243 --- doc/build/orm/cascades.rst | 7 +++++++ doc/build/orm/extensions/asyncio.rst | 10 ++++++++++ 2 files changed, 17 insertions(+) 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 -- 2.47.3