Add migration note about Query.statement

This accessor returns a 2.0 style Select() object now
which won't have the same state as it did in 1.3.  This
can impact things that assume this state.

Fixes: #6231
Change-Id: Ib5cf8e6c67214d864d4ff7f6177c79f15f834cd2

diff --git a/doc/build/changelog/migration_14.rst b/doc/build/changelog/migration_14.rst
index 0a153ceb8d22edf68ebddd983d5fa417c1f16888..7cf1cc5942ce92fecd081942426a1c49454f2e75 100644 (file)
--- a/doc/build/changelog/migration_14.rst
+++ b/doc/build/changelog/migration_14.rst
@@ -470,6 +470,20 @@ Error conditions which fall under this category include:
   will be evaluated at statement compilation time rather than when the method
   is first called.
 
+Other things that may change involve the :class:`_orm.Query` object directly:
+
+* Behaviors may be slightly different when calling upon the
+  :attr:`_orm.Query.statement` accessor. The :class:`_sql.Select` object
+  returned is now a direct copy of the same state that was present in the
+  :class:`_orm.Query`, without any ORM-specific compilation being performed
+  (which means it's dramatically faster). However, the :class:`_sql.Select`
+  will not have the same internal state as it had in 1.3, including things like
+  the FROM clauses being explicitly spelled out if they were not explicitly
+  stated in the :class:`_orm.Query`. This means code that relies upon
+  manipulating this :class:`_sql.Select` statement such as calling methods like
+  :meth:`_sql.Select.with_only_columns` may need to accommodate for the FROM
+  clause.
+
 .. seealso::
 
     :ref:`change_4639`