- The ``str()`` call for :class:`.Query` will now take into account

the :class:`.Engine` to which the :class:`.Session` is bound, when
generating the string form of the SQL, so that the actual SQL
that would be emitted to the database is shown, if possible.  Previously,
only the engine associated with the :class:`.MetaData` to which the
mappings are associated would be used, if present.  If
no bind can be located either on the :class:`.Session` or on
the :class:`.MetaData` to which the mappings are associated, then
the "default" dialect is used to render the SQL, as was the case
previously.  fixes #3081

2 files changed, 40 insertions, 1 deletions

diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst
index 81637a0b4..3d29c9eb4 100644
--- a/doc/build/changelog/changelog_11.rst
+++ b/doc/build/changelog/changelog_11.rst
@@ -22,6 +22,25 @@
     :version: 1.1.0b1
 
     .. change::
+        :tags: feature, orm
+        :tickets: 3081
+
+        The ``str()`` call for :class:`.Query` will now take into account
+        the :class:`.Engine` to which the :class:`.Session` is bound, when
+        generating the string form of the SQL, so that the actual SQL
+        that would be emitted to the database is shown, if possible.  Previously,
+        only the engine associated with the :class:`.MetaData` to which the
+        mappings are associated would be used, if present.  If
+        no bind can be located either on the :class:`.Session` or on
+        the :class:`.MetaData` to which the mappings are associated, then
+        the "default" dialect is used to render the SQL, as was the case
+        previously.
+
+        .. seealso::
+
+            :ref:`change_3081`
+
+    .. change::
         :tags: feature, sql
         :tickets: 3501
 
diff --git a/doc/build/changelog/migration_11.rst b/doc/build/changelog/migration_11.rst
index ecab73fec..c317b734a 100644
--- a/doc/build/changelog/migration_11.rst
+++ b/doc/build/changelog/migration_11.rst
@@ -16,7 +16,7 @@ What's New in SQLAlchemy 1.1?
     some issues may be moved to later milestones in order to allow
     for a timely release.
 
-    Document last updated: January 14, 2016
+    Document last updated: January 19, 2016
 
 Introduction
 ============
@@ -344,6 +344,26 @@ would have to be compared during the merge.
 
 :ticket:`3601`
 
+.. _change_3081:
+
+Stringify of Query will consult the Session for the correct dialect
+-------------------------------------------------------------------
+
+Calling ``str()`` on a :class:`.Query` object will consult the :class:`.Session`
+for the correct "bind" to use, in order to render the SQL that would be
+passed to the database.  In particular this allows a :class:`.Query` that
+refers to dialect-specific SQL constructs to be renderable, assuming the
+:class:`.Query` is associated with an appropriate :class:`.Session`.
+Previously, this behavior would only take effect if the :class:`.MetaData`
+to which the mappings were associated were itself bound to the target
+:class:`.Engine`.
+
+If neither the underlying :class:`.MetaData` nor the :class:`.Session` are
+associated with any bound :class:`.Engine`, then the fallback to the
+"default" dialect is used to generate the SQL string.
+
+:ticket:`3081`
+
 New Features and Improvements - Core
 ====================================