References: #5831

Add a note to docs regarding future session under asyncio

Change-Id: Ib152be833dcb8ea46217e761a715f639859133c6

diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst
index c5fc356d1205beda1c7162a3a0385559633944ce..98f16932c80b990e2a848f95a85d3a436d30384b 100644 (file)
--- a/doc/build/orm/extensions/asyncio.rst
+++ b/doc/build/orm/extensions/asyncio.rst
@@ -226,6 +226,16 @@ then used in a Python asynchronous context manager (i.e. ``async with:``
 statement) so that it is automatically closed at the end of the block; this is
 equivalent to calling the :meth:`_asyncio.AsyncSession.close` method.
 
+.. note:: :class:`_asyncio.AsyncSession` uses SQLAlchemy's future mode, which
+   has several potentially breaking changes.  One such change is the new
+   default behavior of ``cascade_backrefs`` is ``False``, which may affect
+   how related objects are saved to the database.
+
+   .. seealso::
+
+     :ref:`change_5150`
+
+
 .. _asyncio_orm_avoid_lazyloads:
 
 Preventing Implicit IO when Using AsyncSession