changelog

diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst
index c71f3be0cb8f296c73ee65abfc949591ffea558e..8c34dab09ff4c4e62df4d4b9eb48c055fa498d9a 100644 (file)
--- a/doc/build/changelog/changelog_08.rst
+++ b/doc/build/changelog/changelog_08.rst
@@ -8,14 +8,30 @@
 
     .. note::
 
-      Be sure to *re-read* :doc:`migration_08` for this release.
       There are some new behavioral changes as of 0.8.0
-      not present in 0.8.0b2, including:
+      not present in 0.8.0b2.  They are present in the
+      migration document as follows:
 
       * :ref:`legacy_is_orphan_addition`
 
       * :ref:`metadata_create_drop_tables`
 
+      * :ref:`correlation_context_specific`
+
+    .. change::
+        :tags: bug, sql
+        :tickets: 2668
+
+      The behavior of SELECT correlation has been improved such that
+      the :meth:`.Select.correlate` and :meth:`.Select.correlate_except`
+      methods, as well as their ORM analogues, will still retain
+      "auto-correlation" behavior in that the FROM clause is modified
+      only if the output would be legal SQL; that is, the FROM clause
+      is left intact if the correlated SELECT is not used in the context
+      of an enclosing SELECT inside of the WHERE, columns, or HAVING clause.
+      The two methods now only specify conditions to the default
+      "auto correlation", rather than absolute FROM lists.
+
     .. change::
         :tags: feature, mysql
         :pullreq: 42

diff --git a/doc/build/changelog/migration_08.rst b/doc/build/changelog/migration_08.rst
index bb6d85e58f69565f5e440fafbf6b6989b4737d05..971dd2f5183fb817b9c3860ecb0755f5f1765a58 100644 (file)
--- a/doc/build/changelog/migration_08.rst
+++ b/doc/build/changelog/migration_08.rst
@@ -7,9 +7,10 @@ What's New in SQLAlchemy 0.8?
     This document describes changes between SQLAlchemy version 0.7,
     undergoing maintenance releases as of October, 2012,
     and SQLAlchemy version 0.8, which is expected for release
-    in late 2012.
+    in early 2013.
 
     Document date: October 25, 2012
+    Updated: March 9, 2013
 
 Introduction
 ============
@@ -1145,6 +1146,59 @@ entity, ``query.correlate(someentity)``.
 
 :ticket:`2179`
 
+.. _correlation_context_specific:
+
+Correlation is now always context-specific
+------------------------------------------
+
+To allow a wider variety of correlation scenarios, the behavior of
+:meth:`.Select.correlate` and :meth:`.Query.correlate` has changed slightly
+such that the SELECT statement will omit the "correlated" target from the
+FROM clause only if the statement is actually used in that context.  Additionally,
+it's no longer possible for a SELECT statement that's placed as a FROM
+in an enclosing SELECT statement to "correlate" (i.e. omit) a FROM clause.
+
+This change only makes things better as far as rendering SQL, in that it's no
+longer possible to render illegal SQL where there are insufficient FROM
+objects relative to what's being selected::
+
+    from sqlalchemy.sql import table, column, select
+
+    t1 = table('t1', column('x'))
+    t2 = table('t2', column('y'))
+    s = select([t1, t2]).correlate(t1)
+
+    print(s)
+
+Prior to this change, the above would return::
+
+    SELECT t1.x, t2.y FROM t2
+
+which is invalid SQL as "t1" is not referred to in any FROM clause.
+
+Now, in the absense of an enclosing SELECT, it returns::
+
+    SELECT t1.x, t2.y FROM t1, t2
+
+Within a SELECT, the correlation takes effect as expected::
+
+    s2 = select([t1, t2]).where(t1.c.x == t2.c.y).where(t1.c.x == s)
+
+    print (s2)
+
+    SELECT t1.x, t2.y FROM t1, t2
+    WHERE t1.x = t2.y AND t1.x =
+        (SELECT t1.x, t2.y FROM t2)
+
+This change is not expected to impact any existing applications, as
+the correlation behavior remains identical for properly constructed
+expressions.  Only an application that relies, most likely within a
+testing scenario, on the invalid string output of a correlated
+SELECT used in a non-correlating context would see any change.
+
+:ticket:`2668`
+
+
 .. _metadata_create_drop_tables:
 
 create_all() and drop_all() will now honor an empty list as such