File: migration_07.html

package info (click to toggle)
sqlalchemy 0.9.8%2Bdfsg-0.1
links: PTS, VCS
area: main
in suites: jessie, jessie-kfreebsd
size: 23,952 kB
ctags: 24,534
sloc: python: 152,282; ansic: 1,346; makefile: 257; xml: 17
file content (1339 lines) | stat: -rw-r--r-- 115,548 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        
        <title>
            
    
                What&#8217;s New in SQLAlchemy 0.7?
             &mdash;
    SQLAlchemy 0.9 Documentation

        </title>

        
            <!-- begin iterate through SQLA + sphinx environment css_files -->
                <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
                <link rel="stylesheet" href="../_static/docs.css" type="text/css" />
                <link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" />
                <link rel="stylesheet" href="../_static/changelog.css" type="text/css" />
            <!-- end iterate through SQLA + sphinx environment css_files -->
        

        

    

    <!-- begin layout.mako headers -->

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '../',
          VERSION:     '0.9.8',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: '.html'
      };
    </script>

    <!-- begin iterate through sphinx environment script_files -->
        <script type="text/javascript" src="../_static/jquery.js"></script>
        <script type="text/javascript" src="../_static/underscore.js"></script>
        <script type="text/javascript" src="../_static/doctools.js"></script>
    <!-- end iterate through sphinx environment script_files -->

    <script type="text/javascript" src="../_static/detectmobile.js"></script>
    <script type="text/javascript" src="../_static/init.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
        <link rel="copyright" title="Copyright" href="../copyright.html" />
    <link rel="top" title="SQLAlchemy 0.9 Documentation" href="../index.html" />
        <link rel="up" title="Changes and Migration" href="index.html" />
        <link rel="next" title="What&#8217;s New in SQLAlchemy 0.6?" href="migration_06.html" />
        <link rel="prev" title="What&#8217;s New in SQLAlchemy 0.8?" href="migration_08.html" />
    <!-- end layout.mako headers -->


    </head>
    <body>
        















<div id="docs-container">





<div id="docs-top-navigation-container" class="body-background">
<div id="docs-header">
    <div id="docs-version-header">
        Release: <span class="version-num">0.9.8</span> | Release Date: October 13, 2014
    </div>

    <h1>SQLAlchemy 0.9 Documentation</h1>

</div>
</div>

<div id="docs-body-container">

    <div id="fixed-sidebar" class="withsidebar">


        <div id="docs-sidebar-popout">
            <h3><a href="../index.html">SQLAlchemy 0.9 Documentation</a></h3>

            <p id="sidebar-paginate">
                    <a href="index.html" title="Changes and Migration">Up</a> |

                    <a href="migration_08.html" title="What&#8217;s New in SQLAlchemy 0.8?">Prev</a> |
                    <a href="migration_06.html" title="What&#8217;s New in SQLAlchemy 0.6?">Next</a>
            </p>

            <p id="sidebar-topnav">
                <a href="../index.html">Contents</a> |
                <a href="../genindex.html">Index</a>
            </p>

            <div id="sidebar-search">
                <form class="search" action="../search.html" method="get">
                  <input type="text" name="q" size="12" /> <input type="submit" value="Search" />
                  <input type="hidden" name="check_keywords" value="yes" />
                  <input type="hidden" name="area" value="default" />
                </form>
            </div>

        </div>

        <div id="docs-sidebar">

        <h3><a href="#">            
                What&#8217;s New in SQLAlchemy 0.7?
            
        </a></h3>
        <ul>
<li><a class="reference internal" href="#">What&#8217;s New in SQLAlchemy 0.7?</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a></li>
<li><a class="reference internal" href="#new-features">New Features</a><ul>
<li><a class="reference internal" href="#new-event-system">New Event System</a></li>
<li><a class="reference internal" href="#hybrid-attributes-implements-supersedes-synonym-comparable-property">Hybrid Attributes, implements/supersedes synonym(), comparable_property()</a></li>
<li><a class="reference internal" href="#speed-enhancements">Speed Enhancements</a></li>
<li><a class="reference internal" href="#composites-rewritten">Composites Rewritten</a></li>
<li><a class="reference internal" href="#more-succinct-form-of-query-join-target-onclause">More succinct form of query.join(target, onclause)</a></li>
<li><a class="reference internal" href="#mutation-event-extension-supersedes-mutable-true">Mutation event extension, supersedes &#8220;mutable=True&#8221;</a></li>
<li><a class="reference internal" href="#nulls-first-nulls-last-operators">NULLS FIRST / NULLS LAST operators</a></li>
<li><a class="reference internal" href="#select-distinct-query-distinct-accepts-args-for-postgresql-distinct-on">select.distinct(), query.distinct() accepts *args for Postgresql DISTINCT ON</a></li>
<li><a class="reference internal" href="#index-can-be-placed-inline-inside-of-table-table-args"><tt class="docutils literal"><span class="pre">Index()</span></tt> can be placed inline inside of <tt class="docutils literal"><span class="pre">Table</span></tt>, <tt class="docutils literal"><span class="pre">__table_args__</span></tt></a></li>
<li><a class="reference internal" href="#window-function-sql-construct">Window Function SQL Construct</a></li>
<li><a class="reference internal" href="#execution-options-on-connection-accepts-isolation-level-argument">execution_options() on Connection accepts &#8220;isolation_level&#8221; argument</a></li>
<li><a class="reference internal" href="#typedecorator-works-with-integer-primary-key-columns"><tt class="docutils literal"><span class="pre">TypeDecorator</span></tt> works with integer primary key columns</a></li>
<li><a class="reference internal" href="#typedecorator-is-present-in-the-sqlalchemy-import-space"><tt class="docutils literal"><span class="pre">TypeDecorator</span></tt> is present in the &#8220;sqlalchemy&#8221; import space</a></li>
<li><a class="reference internal" href="#new-dialects">New Dialects</a></li>
</ul>
</li>
<li><a class="reference internal" href="#behavioral-changes-backwards-compatible">Behavioral Changes (Backwards Compatible)</a><ul>
<li><a class="reference internal" href="#c-extensions-build-by-default">C Extensions Build by Default</a></li>
<li><a class="reference internal" href="#query-count-simplified-should-work-virtually-always">Query.count() simplified, should work virtually always</a><ul>
<li><a class="reference internal" href="#to-emit-a-non-subquery-form-of-count">To emit a non-subquery form of count()</a></li>
</ul>
</li>
<li><a class="reference internal" href="#limit-offset-clauses-now-use-bind-parameters">LIMIT/OFFSET clauses now use bind parameters</a></li>
<li><a class="reference internal" href="#logging-enhancements">Logging enhancements</a></li>
<li><a class="reference internal" href="#simplified-polymorphic-on-assignment">Simplified polymorphic_on assignment</a></li>
<li><a class="reference internal" href="#contains-eager-chains-across-multiple-paths-i-e-all">contains_eager() chains across multiple paths (i.e. &#8220;all()&#8221;)</a></li>
<li><a class="reference internal" href="#flushing-of-orphans-that-have-no-parent-is-allowed">Flushing of orphans that have no parent is allowed</a></li>
<li><a class="reference internal" href="#warnings-generated-when-collection-members-scalar-referents-not-part-of-the-flush">Warnings generated when collection members, scalar referents not part of the flush</a></li>
<li><a class="reference internal" href="#setup-no-longer-installs-a-nose-plugin">Setup no longer installs a Nose plugin</a></li>
<li><a class="reference internal" href="#non-table-derived-constructs-can-be-mapped">Non-<tt class="docutils literal"><span class="pre">Table</span></tt>-derived constructs can be mapped</a></li>
<li><a class="reference internal" href="#aliased-accepts-fromclause-elements">aliased() accepts <tt class="docutils literal"><span class="pre">FromClause</span></tt> elements</a></li>
<li><a class="reference internal" href="#session-connection-session-execute-accept-bind">Session.connection(), Session.execute() accept &#8216;bind&#8217;</a></li>
<li><a class="reference internal" href="#standalone-bind-parameters-in-columns-clause-auto-labeled">Standalone bind parameters in columns clause auto-labeled.</a></li>
<li><a class="reference internal" href="#sqlite-relative-file-paths-are-normalized-through-os-path-abspath">SQLite - relative file paths are normalized through os.path.abspath()</a></li>
<li><a class="reference internal" href="#ms-sql-string-unicode-varchar-nvarchar-varbinary-emit-max-for-no-length">MS-SQL - <tt class="docutils literal"><span class="pre">String</span></tt>/<tt class="docutils literal"><span class="pre">Unicode</span></tt>/<tt class="docutils literal"><span class="pre">VARCHAR</span></tt>/<tt class="docutils literal"><span class="pre">NVARCHAR</span></tt>/<tt class="docutils literal"><span class="pre">VARBINARY</span></tt> emit &#8220;max&#8221; for no length</a></li>
</ul>
</li>
<li><a class="reference internal" href="#behavioral-changes-backwards-incompatible">Behavioral Changes (Backwards Incompatible)</a><ul>
<li><a class="reference internal" href="#pickletype-and-array-mutability-turned-off-by-default"><tt class="docutils literal"><span class="pre">PickleType</span></tt> and ARRAY mutability turned off by default</a></li>
<li><a class="reference internal" href="#mutability-detection-of-composite-requires-the-mutation-tracking-extension">Mutability detection of <tt class="docutils literal"><span class="pre">composite()</span></tt> requires the Mutation Tracking Extension</a></li>
<li><a class="reference internal" href="#sqlite-the-sqlite-dialect-now-uses-nullpool-for-file-based-databases">SQLite - the SQLite dialect now uses <tt class="docutils literal"><span class="pre">NullPool</span></tt> for file-based databases</a></li>
<li><a class="reference internal" href="#session-merge-checks-version-ids-for-versioned-mappers"><tt class="docutils literal"><span class="pre">Session.merge()</span></tt> checks version ids for versioned mappers</a></li>
<li><a class="reference internal" href="#tuple-label-names-in-query-improved">Tuple label names in Query Improved</a></li>
<li><a class="reference internal" href="#mapped-column-attributes-reference-the-most-specific-column-first">Mapped column attributes reference the most specific column first</a></li>
<li><a class="reference internal" href="#mapping-to-joins-with-two-or-more-same-named-columns-requires-explicit-declaration">Mapping to joins with two or more same-named columns requires explicit declaration</a></li>
<li><a class="reference internal" href="#mapper-requires-that-polymorphic-on-column-be-present-in-the-mapped-selectable">Mapper requires that polymorphic_on column be present in the mapped selectable</a></li>
<li><a class="reference internal" href="#ddl-constructs-now-escape-percent-signs"><tt class="docutils literal"><span class="pre">DDL()</span></tt> constructs now escape percent signs</a></li>
<li><a class="reference internal" href="#table-c-metadata-tables-refined-a-bit-don-t-allow-direct-mutation"><tt class="docutils literal"><span class="pre">Table.c</span></tt> / <tt class="docutils literal"><span class="pre">MetaData.tables</span></tt> refined a bit, don&#8217;t allow direct mutation</a></li>
<li><a class="reference internal" href="#server-default-consistently-returns-none-for-all-inserted-primary-key-values">server_default consistently returns None for all inserted_primary_key values</a></li>
<li><a class="reference internal" href="#the-sqlalchemy-exceptions-alias-in-sys-modules-is-removed">The <tt class="docutils literal"><span class="pre">sqlalchemy.exceptions</span></tt> alias in sys.modules is removed</a></li>
<li><a class="reference internal" href="#query-timing-recipe-changes">Query Timing Recipe Changes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#deprecated-api">Deprecated API</a><ul>
<li><a class="reference internal" href="#default-constructor-on-types-will-not-accept-arguments">Default constructor on types will not accept arguments</a></li>
<li><a class="reference internal" href="#compile-mappers-renamed-configure-mappers-simplified-configuration-internals">compile_mappers() renamed configure_mappers(), simplified configuration internals</a></li>
<li><a class="reference internal" href="#core-listener-proxy-superseded-by-event-listeners">Core listener/proxy superseded by event listeners</a></li>
<li><a class="reference internal" href="#orm-extensions-superseded-by-event-listeners">ORM extensions superseded by event listeners</a></li>
<li><a class="reference internal" href="#sending-a-string-to-distinct-in-select-for-mysql-should-be-done-via-prefixes">Sending a string to &#8216;distinct&#8217; in select() for MySQL should be done via prefixes</a></li>
<li><a class="reference internal" href="#useexisting-superseded-by-extend-existing-and-keep-existing"><tt class="docutils literal"><span class="pre">useexisting</span></tt> superseded by <tt class="docutils literal"><span class="pre">extend_existing</span></tt> and <tt class="docutils literal"><span class="pre">keep_existing</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#backwards-incompatible-api-changes">Backwards Incompatible API Changes</a><ul>
<li><a class="reference internal" href="#callables-passed-to-bindparam-don-t-get-evaluated-affects-the-beaker-example">Callables passed to <tt class="docutils literal"><span class="pre">bindparam()</span></tt> don&#8217;t get evaluated - affects the Beaker example</a></li>
<li><a class="reference internal" href="#types-type-map-is-now-private-types-type-map">types.type_map is now private, types._type_map</a></li>
<li><a class="reference internal" href="#renamed-the-alias-keyword-arg-of-standalone-alias-function-to-name">Renamed the <tt class="docutils literal"><span class="pre">alias</span></tt> keyword arg of standalone <tt class="docutils literal"><span class="pre">alias()</span></tt> function to <tt class="docutils literal"><span class="pre">name</span></tt></a></li>
<li><a class="reference internal" href="#non-public-pool-methods-underscored">Non-public <tt class="docutils literal"><span class="pre">Pool</span></tt> methods underscored</a></li>
</ul>
</li>
<li><a class="reference internal" href="#previously-deprecated-now-removed">Previously Deprecated, Now Removed</a><ul>
<li><a class="reference internal" href="#query-join-query-outerjoin-eagerload-eagerload-all-others-no-longer-allow-lists-of-attributes-as-arguments">Query.join(), Query.outerjoin(), eagerload(), eagerload_all(), others no longer allow lists of attributes as arguments</a></li>
<li><a class="reference internal" href="#scopedsession-mapper-is-removed"><tt class="docutils literal"><span class="pre">ScopedSession.mapper</span></tt> is removed</a></li>
</ul>
</li>
</ul>
</li>
</ul>




        </div>

    </div>

    

    <div id="docs-body" class="withsidebar" >
        
<div class="section" id="what-s-new-in-sqlalchemy-0-7">
<h1>What&#8217;s New in SQLAlchemy 0.7?<a class="headerlink" href="#what-s-new-in-sqlalchemy-0-7" title="Permalink to this headline">¶</a></h1>
<div class="admonition-about-this-document admonition">
<p class="first admonition-title">About this Document</p>
<p>This document describes changes between SQLAlchemy version 0.6,
last released May 5, 2012, and SQLAlchemy version 0.7,
undergoing maintenance releases as of October, 2012.</p>
<p class="last">Document date: July 27, 2011</p>
</div>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>This guide introduces what&#8217;s new in SQLAlchemy version 0.7,
and also documents changes which affect users migrating
their applications from the 0.6 series of SQLAlchemy to 0.7.</p>
<p>To as great a degree as possible, changes are made in such a
way as to not break compatibility with applications built
for 0.6.   The changes that are necessarily not backwards
compatible are very few, and all but one, the change to
mutable attribute defaults, should affect an exceedingly
small portion of applications - many of the changes regard
non-public APIs and undocumented hacks some users may have
been attempting to use.</p>
<p>A second, even smaller class of non-backwards-compatible
changes is also documented. This class of change regards
those features and behaviors that have been deprecated at
least since version 0.5 and have been raising warnings since
their deprecation. These changes would only affect
applications that are still using 0.4- or early 0.5-style
APIs. As the project matures, we have fewer and fewer of
these kinds of changes with 0.x level releases, which is a
product of our API having ever fewer features that are less
than ideal for the use cases they were meant to solve.</p>
<p>An array of existing functionalities have been superseded in
SQLAlchemy 0.7.  There&#8217;s not much difference between the
terms &#8220;superseded&#8221; and &#8220;deprecated&#8221;, except that the former
has a much weaker suggestion of the old feature would ever
be removed. In 0.7, features like <tt class="docutils literal"><span class="pre">synonym</span></tt> and
<tt class="docutils literal"><span class="pre">comparable_property</span></tt>, as well as all the <tt class="docutils literal"><span class="pre">Extension</span></tt>
and other event classes, have been superseded.  But these
&#8220;superseded&#8221; features have been re-implemented such that
their implementations live mostly outside of core ORM code,
so their continued &#8220;hanging around&#8221; doesn&#8217;t impact
SQLAlchemy&#8217;s ability to further streamline and refine its
internals, and we expect them to remain within the API for
the foreseeable future.</p>
</div>
<div class="section" id="new-features">
<h2>New Features<a class="headerlink" href="#new-features" title="Permalink to this headline">¶</a></h2>
<div class="section" id="new-event-system">
<h3>New Event System<a class="headerlink" href="#new-event-system" title="Permalink to this headline">¶</a></h3>
<p>SQLAlchemy started early with the <tt class="docutils literal"><span class="pre">MapperExtension</span></tt> class,
which provided hooks into the persistence cycle of mappers.
As SQLAlchemy quickly became more componentized, pushing
mappers into a more focused configurational role, many more
&#8220;extension&#8221;, &#8220;listener&#8221;, and &#8220;proxy&#8221; classes popped up to
solve various activity-interception use cases in an ad-hoc
fashion.   Part of this was driven by the divergence of
activities; <tt class="docutils literal"><span class="pre">ConnectionProxy</span></tt> objects wanted to provide a
system of rewriting statements and parameters;
<tt class="docutils literal"><span class="pre">AttributeExtension</span></tt> provided a system of replacing
incoming values, and <tt class="docutils literal"><span class="pre">DDL</span></tt> objects had events that could
be switched off of dialect-sensitive callables.</p>
<p>0.7 re-implements virtually all of these plugin points with
a new, unified approach, which retains all the
functionalities of the different systems, provides more
flexibility and less boilerplate, performs better, and
eliminates the need to learn radically different APIs for
each event subsystem.  The pre-existing classes
<tt class="docutils literal"><span class="pre">MapperExtension</span></tt>, <tt class="docutils literal"><span class="pre">SessionExtension</span></tt>,
<tt class="docutils literal"><span class="pre">AttributeExtension</span></tt>, <tt class="docutils literal"><span class="pre">ConnectionProxy</span></tt>,
<tt class="docutils literal"><span class="pre">PoolListener</span></tt> as well as the <tt class="docutils literal"><span class="pre">DDLElement.execute_at</span></tt>
method are deprecated and now implemented in terms of the
new system - these APIs remain fully functional and are
expected to remain in place for the foreseeable future.</p>
<p>The new approach uses named events and user-defined
callables to associate activities with events. The API&#8217;s
look and feel was driven by such diverse sources as JQuery,
Blinker, and Hibernate, and was also modified further on
several occasions during conferences with dozens of users on
Twitter, which appears to have a much higher response rate
than the mailing list for such questions.</p>
<p>It also features an open-ended system of target
specification that allows events to be associated with API
classes, such as for all <tt class="docutils literal"><span class="pre">Session</span></tt> or <tt class="docutils literal"><span class="pre">Engine</span></tt> objects,
with specific instances of API classes, such as for a
specific <tt class="docutils literal"><span class="pre">Pool</span></tt> or <tt class="docutils literal"><span class="pre">Mapper</span></tt>, as well as for related
objects like a user- defined class that&#8217;s mapped, or
something as specific as a certain attribute on instances of
a particular subclass of a mapped parent class. Individual
listener subsystems can apply wrappers to incoming user-
defined listener functions which modify how they are called
- an mapper event can receive either the instance of the
object being operated upon, or its underlying
<tt class="docutils literal"><span class="pre">InstanceState</span></tt> object. An attribute event can opt whether
or not to have the responsibility of returning a new value.</p>
<p>Several systems now build upon the new event API, including
the new &#8220;mutable attributes&#8221; API as well as composite
attributes. The greater emphasis on events has also led to
the introduction of a handful of new events, including
attribute expiration and refresh operations, pickle
loads/dumps operations, completed mapper construction
operations.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../core/event.html"><em>Events</em></a></p>
</div>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1902">#1902</a></p>
</div>
<div class="section" id="hybrid-attributes-implements-supersedes-synonym-comparable-property">
<h3>Hybrid Attributes, implements/supersedes synonym(), comparable_property()<a class="headerlink" href="#hybrid-attributes-implements-supersedes-synonym-comparable-property" title="Permalink to this headline">¶</a></h3>
<p>The &#8220;derived attributes&#8221; example has now been turned into an
official extension.   The typical use case for <tt class="docutils literal"><span class="pre">synonym()</span></tt>
is to provide descriptor access to a mapped column; the use
case for <tt class="docutils literal"><span class="pre">comparable_property()</span></tt> is to be able to return a
<tt class="docutils literal"><span class="pre">PropComparator</span></tt> from any descriptor.   In practice, the
approach of &#8220;derived&#8221; is easier to use, more extensible, is
implemented in a few dozen lines of pure Python with almost
no imports, and doesn&#8217;t require the ORM core to even be
aware of it.   The feature is now known as the &#8220;Hybrid
Attributes&#8221; extension.</p>
<p><tt class="docutils literal"><span class="pre">synonym()</span></tt> and <tt class="docutils literal"><span class="pre">comparable_property()</span></tt> are still part
of the ORM, though their implementations have been moved
outwards, building on an approach that is similar to that of
the hybrid extension, so that the core ORM
mapper/query/property modules aren&#8217;t really aware of them
otherwise.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../orm/extensions/hybrid.html"><em>Hybrid Attributes</em></a></p>
</div>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1903">#1903</a></p>
</div>
<div class="section" id="speed-enhancements">
<h3>Speed Enhancements<a class="headerlink" href="#speed-enhancements" title="Permalink to this headline">¶</a></h3>
<p>As is customary with all major SQLA releases, a wide pass
through the internals to reduce overhead and callcounts has
been made which further reduces the work needed in common
scenarios. Highlights of this release include:</p>
<ul class="simple">
<li>The flush process will now bundle INSERT statements into
batches fed   to <tt class="docutils literal"><span class="pre">cursor.executemany()</span></tt>, for rows where
the primary key is already   present.   In particular this
usually applies to the &#8220;child&#8221; table on a joined   table
inheritance configuration, meaning the number of calls to
<tt class="docutils literal"><span class="pre">cursor.execute</span></tt>   for a large bulk insert of joined-
table objects can be cut in half, allowing   native DBAPI
optimizations to take place for those statements passed
to <tt class="docutils literal"><span class="pre">cursor.executemany()</span></tt> (such as re-using a prepared
statement).</li>
<li>The codepath invoked when accessing a many-to-one
reference to a related object   that&#8217;s already loaded has
been greatly simplified.  The identity map is checked
directly without the need to generate a new <tt class="docutils literal"><span class="pre">Query</span></tt>
object first, which is   expensive in the context of
thousands of in-memory many-to-ones being accessed.   The
usage of constructed-per-call &#8220;loader&#8221; objects is also no
longer used for   the majority of lazy attribute loads.</li>
<li>The rewrite of composites allows a shorter codepath when
mapper internals   access mapped attributes within a
flush.</li>
<li>New inlined attribute access functions replace the
previous usage of   &#8220;history&#8221; when the &#8220;save-update&#8221; and
other cascade operations need to   cascade among the full
scope of datamembers associated with an attribute.   This
reduces the overhead of generating a new <tt class="docutils literal"><span class="pre">History</span></tt>
object for this speed-critical   operation.</li>
<li>The internals of the <tt class="docutils literal"><span class="pre">ExecutionContext</span></tt>, the object
corresponding to a statement   execution, have been
inlined and simplified.</li>
<li>The <tt class="docutils literal"><span class="pre">bind_processor()</span></tt> and <tt class="docutils literal"><span class="pre">result_processor()</span></tt>
callables generated by types   for each statement
execution are now cached (carefully, so as to avoid memory
leaks for ad-hoc types and dialects) for the lifespan of
that type, further   reducing per-statement call overhead.</li>
<li>The collection of &#8220;bind processors&#8221; for a particular
<tt class="docutils literal"><span class="pre">Compiled</span></tt> instance of   a statement is also cached on
the <tt class="docutils literal"><span class="pre">Compiled</span></tt> object, taking further   advantage of the
&#8220;compiled cache&#8221; used by the flush process to re-use the
same   compiled form of INSERT, UPDATE, DELETE statements.</li>
</ul>
<p>A demonstration of callcount reduction including a sample
benchmark script is at
<a class="reference external" href="http://techspot.zzzeek.org/2010/12/12/a-tale-of-three">http://techspot.zzzeek.org/2010/12/12/a-tale-of-three</a>-
profiles/</p>
</div>
<div class="section" id="composites-rewritten">
<h3>Composites Rewritten<a class="headerlink" href="#composites-rewritten" title="Permalink to this headline">¶</a></h3>
<p>The &#8220;composite&#8221; feature has been rewritten, like
<tt class="docutils literal"><span class="pre">synonym()</span></tt> and <tt class="docutils literal"><span class="pre">comparable_property()</span></tt>, to use a
lighter weight implementation based on descriptors and
events, rather than building into the ORM internals.  This
allowed the removal of some latency from the mapper/unit of
work internals, and simplifies the workings of composite.
The composite attribute now no longer conceals the
underlying columns it builds upon, which now remain as
regular attributes.  Composites can also act as a proxy for
<tt class="docutils literal"><span class="pre">relationship()</span></tt> as well as <tt class="docutils literal"><span class="pre">Column()</span></tt> attributes.</p>
<p>The major backwards-incompatible change of composites is
that they no longer use the <tt class="docutils literal"><span class="pre">mutable=True</span></tt> system to
detect in-place mutations.   Please use the <a class="reference external" href="http://www.sqlalchemy.org/docs/07/orm/extensions/mutable.html">Mutation
Tracking</a> extension to establish in-place change events
to existing composite usage.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="../orm/mapper_config.html#mapper-composite"><em>Composite Column Types</em></a></p>
<p class="last"><a class="reference internal" href="../orm/extensions/mutable.html"><em>Mutation Tracking</em></a></p>
</div>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2008">#2008</a> <a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2024">#2024</a></p>
</div>
<div class="section" id="more-succinct-form-of-query-join-target-onclause">
<h3>More succinct form of query.join(target, onclause)<a class="headerlink" href="#more-succinct-form-of-query-join-target-onclause" title="Permalink to this headline">¶</a></h3>
<p>The default method of issuing <tt class="docutils literal"><span class="pre">query.join()</span></tt> to a target
with an explicit onclause is now:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">query</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">,</span> <span class="n">SomeClass</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="n">ParentClass</span><span class="o">.</span><span class="n">some_id</span><span class="p">)</span></pre></div>
</div>
<p>In 0.6, this usage was considered to be an error, because
<tt class="docutils literal"><span class="pre">join()</span></tt> accepts multiple arguments corresponding to
multiple JOIN clauses - the two-argument form needed to be
in a tuple to disambiguate between single-argument and two-
argument join targets.  In the middle of 0.6 we added
detection and an error message for this specific calling
style, since it was so common.  In 0.7, since we are
detecting the exact pattern anyway, and since having to type
out a tuple for no reason is extremely annoying, the non-
tuple method now becomes the &#8220;normal&#8221; way to do it.  The
&#8220;multiple JOIN&#8221; use case is exceedingly rare compared to the
single join case, and multiple joins these days are more
clearly represented by multiple calls to <tt class="docutils literal"><span class="pre">join()</span></tt>.</p>
<p>The tuple form will remain for backwards compatibility.</p>
<p>Note that all the other forms of <tt class="docutils literal"><span class="pre">query.join()</span></tt> remain
unchanged:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">query</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">MyClass</span><span class="o">.</span><span class="n">somerelation</span><span class="p">)</span>
<span class="n">query</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s">&quot;somerelation&quot;</span><span class="p">)</span>
<span class="n">query</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">MyTarget</span><span class="p">)</span>
<span class="c"># ... etc</span></pre></div>
</div>
<p><a class="reference external" href="http://www.sqlalchemy.org/docs/07/orm/tutorial.html#querying-with-joins">Querying with Joins</a></p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1923">#1923</a></p>
</div>
<div class="section" id="mutation-event-extension-supersedes-mutable-true">
<span id="migration-mutation-extension"></span><h3>Mutation event extension, supersedes &#8220;mutable=True&#8221;<a class="headerlink" href="#mutation-event-extension-supersedes-mutable-true" title="Permalink to this headline">¶</a></h3>
<p>A new extension, <a class="reference internal" href="../orm/extensions/mutable.html"><em>Mutation Tracking</em></a>, provides a
mechanism by which user-defined datatypes can provide change
events back to the owning parent or parents.   The extension
includes an approach for scalar database values, such as
those managed by <a class="reference internal" href="../core/types.html#sqlalchemy.types.PickleType" title="sqlalchemy.types.PickleType"><tt class="xref py py-class docutils literal"><span class="pre">PickleType</span></tt></a>, <tt class="docutils literal"><span class="pre">postgresql.ARRAY</span></tt>, or
other custom <tt class="docutils literal"><span class="pre">MutableType</span></tt> classes, as well as an approach
for ORM &#8220;composites&#8221;, those configured using <a class="reference internal" href="../orm/mapper_config.html#sqlalchemy.orm.composite" title="sqlalchemy.orm.composite"><tt class="xref py py-func docutils literal"><span class="pre">composite()</span></tt></a>.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../orm/extensions/mutable.html"><em>Mutation Tracking</em></a></p>
</div>
</div>
<div class="section" id="nulls-first-nulls-last-operators">
<h3>NULLS FIRST / NULLS LAST operators<a class="headerlink" href="#nulls-first-nulls-last-operators" title="Permalink to this headline">¶</a></h3>
<p>These are implemented as an extension to the <tt class="docutils literal"><span class="pre">asc()</span></tt> and
<tt class="docutils literal"><span class="pre">desc()</span></tt> operators, called <tt class="docutils literal"><span class="pre">nullsfirst()</span></tt> and
<tt class="docutils literal"><span class="pre">nullslast()</span></tt>.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.nullsfirst" title="sqlalchemy.sql.expression.nullsfirst"><tt class="xref py py-func docutils literal"><span class="pre">nullsfirst()</span></tt></a></p>
<p class="last"><a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.nullslast" title="sqlalchemy.sql.expression.nullslast"><tt class="xref py py-func docutils literal"><span class="pre">nullslast()</span></tt></a></p>
</div>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/723">#723</a></p>
</div>
<div class="section" id="select-distinct-query-distinct-accepts-args-for-postgresql-distinct-on">
<h3>select.distinct(), query.distinct() accepts *args for Postgresql DISTINCT ON<a class="headerlink" href="#select-distinct-query-distinct-accepts-args-for-postgresql-distinct-on" title="Permalink to this headline">¶</a></h3>
<p>This was already available by passing a list of expressions
to the <tt class="docutils literal"><span class="pre">distinct</span></tt> keyword argument of <tt class="docutils literal"><span class="pre">select()</span></tt>, the
<tt class="docutils literal"><span class="pre">distinct()</span></tt> method of <tt class="docutils literal"><span class="pre">select()</span></tt> and <tt class="docutils literal"><span class="pre">Query</span></tt> now
accept positional arguments which are rendered as DISTINCT
ON when a Postgresql backend is used.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/docs/07/core/expression_api.html#sqlalchemy.sql.expression.Select.distinct">distinct()</a></p>
<p><a class="reference external" href="http://www.sqlalchemy.org/docs/07/orm/query.html#sqlalchemy.orm.query.Query.distinct">Query.distinct()</a></p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1069">#1069</a></p>
</div>
<div class="section" id="index-can-be-placed-inline-inside-of-table-table-args">
<h3><tt class="docutils literal"><span class="pre">Index()</span></tt> can be placed inline inside of <tt class="docutils literal"><span class="pre">Table</span></tt>, <tt class="docutils literal"><span class="pre">__table_args__</span></tt><a class="headerlink" href="#index-can-be-placed-inline-inside-of-table-table-args" title="Permalink to this headline">¶</a></h3>
<p>The Index() construct can be created inline with a Table
definition, using strings as column names, as an alternative
to the creation of the index outside of the Table.  That is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Table</span><span class="p">(</span><span class="s">&#39;mytable&#39;</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
        <span class="n">Column</span><span class="p">(</span><span class="s">&#39;id&#39;</span><span class="p">,</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">),</span>
        <span class="n">Column</span><span class="p">(</span><span class="s">&#39;name&#39;</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">50</span><span class="p">),</span> <span class="n">nullable</span><span class="o">=</span><span class="bp">False</span><span class="p">),</span>
        <span class="n">Index</span><span class="p">(</span><span class="s">&#39;idx_name&#39;</span><span class="p">,</span> <span class="s">&#39;name&#39;</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The primary rationale here is for the benefit of declarative
<tt class="docutils literal"><span class="pre">__table_args__</span></tt>, particularly when used with mixins:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">HasNameMixin</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="s">&#39;name&#39;</span><span class="p">,</span> <span class="n">String</span><span class="p">(</span><span class="mi">50</span><span class="p">),</span> <span class="n">nullable</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
    <span class="nd">@declared_attr</span>
    <span class="k">def</span> <span class="nf">__table_args__</span><span class="p">(</span><span class="n">cls</span><span class="p">):</span>
        <span class="k">return</span> <span class="p">(</span><span class="n">Index</span><span class="p">(</span><span class="s">&#39;name&#39;</span><span class="p">),</span> <span class="p">{})</span>

<span class="k">class</span> <span class="nc">User</span><span class="p">(</span><span class="n">HasNameMixin</span><span class="p">,</span> <span class="n">Base</span><span class="p">):</span>
    <span class="n">__tablename__</span> <span class="o">=</span> <span class="s">&#39;user&#39;</span>
    <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="s">&#39;id&#39;</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span></pre></div>
</div>
<p><a class="reference external" href="http://www.sqlalchemy.org/docs/07/core/schema.html#indexes">Indexes</a></p>
</div>
<div class="section" id="window-function-sql-construct">
<h3>Window Function SQL Construct<a class="headerlink" href="#window-function-sql-construct" title="Permalink to this headline">¶</a></h3>
<p>A &#8220;window function&#8221; provides to a statement information
about the result set as it&#8217;s produced. This allows criteria
against various things like &#8220;row number&#8221;, &#8220;rank&#8221; and so
forth. They are known to be supported at least by
Postgresql, SQL Server and Oracle, possibly others.</p>
<p>The best introduction to window functions is on Postgresql&#8217;s
site, where window functions have been supported since
version 8.4:</p>
<p><a class="reference external" href="http://www.postgresql.org/docs/9.0/static/tutorial">http://www.postgresql.org/docs/9.0/static/tutorial</a>-
window.html</p>
<p>SQLAlchemy provides a simple construct typically invoked via
an existing function clause, using the <tt class="docutils literal"><span class="pre">over()</span></tt> method,
which accepts <tt class="docutils literal"><span class="pre">order_by</span></tt> and <tt class="docutils literal"><span class="pre">partition_by</span></tt> keyword
arguments. Below we replicate the first example in PG&#8217;s
tutorial:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">table</span><span class="p">,</span> <span class="n">column</span><span class="p">,</span> <span class="n">select</span><span class="p">,</span> <span class="n">func</span>

<span class="n">empsalary</span> <span class="o">=</span> <span class="n">table</span><span class="p">(</span><span class="s">&#39;empsalary&#39;</span><span class="p">,</span>
                <span class="n">column</span><span class="p">(</span><span class="s">&#39;depname&#39;</span><span class="p">),</span>
                <span class="n">column</span><span class="p">(</span><span class="s">&#39;empno&#39;</span><span class="p">),</span>
                <span class="n">column</span><span class="p">(</span><span class="s">&#39;salary&#39;</span><span class="p">))</span>

<span class="n">s</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span>
        <span class="n">empsalary</span><span class="p">,</span>
        <span class="n">func</span><span class="o">.</span><span class="n">avg</span><span class="p">(</span><span class="n">empsalary</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">salary</span><span class="p">)</span><span class="o">.</span>
              <span class="n">over</span><span class="p">(</span><span class="n">partition_by</span><span class="o">=</span><span class="n">empsalary</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">depname</span><span class="p">)</span><span class="o">.</span>
              <span class="n">label</span><span class="p">(</span><span class="s">&#39;avg&#39;</span><span class="p">)</span>
    <span class="p">])</span>

<span class="k">print</span> <span class="n">s</span></pre></div>
</div>
<p>SQL:</p>
<div class="highlight-python"><pre>SELECT empsalary.depname, empsalary.empno, empsalary.salary,
avg(empsalary.salary) OVER (PARTITION BY empsalary.depname) AS avg
FROM empsalary</pre>
</div>
<p><a class="reference external" href="http://www.sqlalchemy.org/docs/07/core/expression_api.html#sqlalchemy.sql.expression.over">sqlalchemy.sql.expression.over</a></p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1844">#1844</a></p>
</div>
<div class="section" id="execution-options-on-connection-accepts-isolation-level-argument">
<h3>execution_options() on Connection accepts &#8220;isolation_level&#8221; argument<a class="headerlink" href="#execution-options-on-connection-accepts-isolation-level-argument" title="Permalink to this headline">¶</a></h3>
<p>This sets the transaction isolation level for a single
<tt class="docutils literal"><span class="pre">Connection</span></tt>, until that <tt class="docutils literal"><span class="pre">Connection</span></tt> is closed and its
underlying DBAPI resource returned to the connection pool,
upon which the isolation level is reset back to the default.
The default isolation level is set using the
<tt class="docutils literal"><span class="pre">isolation_level</span></tt> argument to <tt class="docutils literal"><span class="pre">create_engine()</span></tt>.</p>
<p>Transaction isolation support is currently only supported by
the Postgresql and SQLite backends.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/docs/07/core/connections.html#sqlalchemy.engine.base.Connection.execution_options">execution_options()</a></p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2001">#2001</a></p>
</div>
<div class="section" id="typedecorator-works-with-integer-primary-key-columns">
<h3><tt class="docutils literal"><span class="pre">TypeDecorator</span></tt> works with integer primary key columns<a class="headerlink" href="#typedecorator-works-with-integer-primary-key-columns" title="Permalink to this headline">¶</a></h3>
<p>A <tt class="docutils literal"><span class="pre">TypeDecorator</span></tt> which extends the behavior of
<tt class="docutils literal"><span class="pre">Integer</span></tt> can be used with a primary key column.  The
&#8220;autoincrement&#8221; feature of <tt class="docutils literal"><span class="pre">Column</span></tt> will now recognize
that the underlying database column is still an integer so
that lastrowid mechanisms continue to function.   The
<tt class="docutils literal"><span class="pre">TypeDecorator</span></tt> itself will have its result value
processor applied to newly generated primary keys, including
those received by the DBAPI <tt class="docutils literal"><span class="pre">cursor.lastrowid</span></tt> accessor.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2005">#2005</a> <a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2006">#2006</a></p>
</div>
<div class="section" id="typedecorator-is-present-in-the-sqlalchemy-import-space">
<h3><tt class="docutils literal"><span class="pre">TypeDecorator</span></tt> is present in the &#8220;sqlalchemy&#8221; import space<a class="headerlink" href="#typedecorator-is-present-in-the-sqlalchemy-import-space" title="Permalink to this headline">¶</a></h3>
<p>No longer need to import this from <tt class="docutils literal"><span class="pre">sqlalchemy.types</span></tt>,
it&#8217;s now mirrored in <tt class="docutils literal"><span class="pre">sqlalchemy</span></tt>.</p>
</div>
<div class="section" id="new-dialects">
<h3>New Dialects<a class="headerlink" href="#new-dialects" title="Permalink to this headline">¶</a></h3>
<p>Dialects have been added:</p>
<ul>
<li><p class="first">a MySQLdb driver for the Drizzle database:</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/docs/07/dialects/drizzle.html">Drizzle</a></p>
</li>
<li><p class="first">support for the pymysql DBAPI:</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/docs/07/dialects/mysql.html#module-sqlalchemy.dialects.mysql.pymysql">pymsql Notes</a></p>
</li>
<li><p class="first">psycopg2 now works with Python 3</p>
</li>
</ul>
</div>
</div>
<div class="section" id="behavioral-changes-backwards-compatible">
<h2>Behavioral Changes (Backwards Compatible)<a class="headerlink" href="#behavioral-changes-backwards-compatible" title="Permalink to this headline">¶</a></h2>
<div class="section" id="c-extensions-build-by-default">
<h3>C Extensions Build by Default<a class="headerlink" href="#c-extensions-build-by-default" title="Permalink to this headline">¶</a></h3>
<p>This is as of 0.7b4.   The exts will build if cPython 2.xx
is detected.   If the build fails, such as on a windows
install, that condition is caught and the non-C install
proceeds.    The C exts won&#8217;t build if Python 3 or Pypy is
used.</p>
</div>
<div class="section" id="query-count-simplified-should-work-virtually-always">
<h3>Query.count() simplified, should work virtually always<a class="headerlink" href="#query-count-simplified-should-work-virtually-always" title="Permalink to this headline">¶</a></h3>
<p>The very old guesswork which occurred within
<tt class="docutils literal"><span class="pre">Query.count()</span></tt> has been modernized to use
<tt class="docutils literal"><span class="pre">.from_self()</span></tt>.  That is, <tt class="docutils literal"><span class="pre">query.count()</span></tt> is now
equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">query</span><span class="o">.</span><span class="n">from_self</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">literal_column</span><span class="p">(</span><span class="s">&#39;1&#39;</span><span class="p">)))</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span></pre></div>
</div>
<p>Previously, internal logic attempted to rewrite the columns
clause of the query itself, and upon detection of a
&#8220;subquery&#8221; condition, such as a column-based query that
might have aggregates in it, or a query with DISTINCT, would
go through a convoluted process of rewriting the columns
clause.   This logic failed in complex conditions,
particularly those involving joined table inheritance, and
was long obsolete by the more comprehensive <tt class="docutils literal"><span class="pre">.from_self()</span></tt>
call.</p>
<p>The SQL emitted by <tt class="docutils literal"><span class="pre">query.count()</span></tt> is now always of the
form:</p>
<div class="highlight-python"><pre>SELECT count(1) AS count_1 FROM (
    SELECT user.id AS user_id, user.name AS user_name from user
) AS anon_1</pre>
</div>
<p>that is, the original query is preserved entirely inside of
a subquery, with no more guessing as to how count should be
applied.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2093">#2093</a></p>
<div class="section" id="to-emit-a-non-subquery-form-of-count">
<h4>To emit a non-subquery form of count()<a class="headerlink" href="#to-emit-a-non-subquery-form-of-count" title="Permalink to this headline">¶</a></h4>
<p>MySQL users have already reported that the MyISAM engine not
surprisingly falls over completely with this simple change.
Note that for a simple <tt class="docutils literal"><span class="pre">count()</span></tt> that optimizes for DBs
that can&#8217;t handle simple subqueries, <tt class="docutils literal"><span class="pre">func.count()</span></tt> should
be used:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">func</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">MyClass</span><span class="o">.</span><span class="n">id</span><span class="p">))</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span></pre></div>
</div>
<p>or for <tt class="docutils literal"><span class="pre">count(*)</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">func</span><span class="p">,</span> <span class="n">literal_column</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">literal_column</span><span class="p">(</span><span class="s">&#39;*&#39;</span><span class="p">)))</span><span class="o">.</span><span class="n">select_from</span><span class="p">(</span><span class="n">MyClass</span><span class="p">)</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span></pre></div>
</div>
</div>
</div>
<div class="section" id="limit-offset-clauses-now-use-bind-parameters">
<h3>LIMIT/OFFSET clauses now use bind parameters<a class="headerlink" href="#limit-offset-clauses-now-use-bind-parameters" title="Permalink to this headline">¶</a></h3>
<p>The LIMIT and OFFSET clauses, or their backend equivalents
(i.e. TOP, ROW NUMBER OVER, etc.), use bind parameters for
the actual values, for all backends which support it (most
except for Sybase).  This allows better query optimizer
performance as the textual string for multiple statements
with differing LIMIT/OFFSET are now identical.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/805">#805</a></p>
</div>
<div class="section" id="logging-enhancements">
<h3>Logging enhancements<a class="headerlink" href="#logging-enhancements" title="Permalink to this headline">¶</a></h3>
<p>Vinay Sajip has provided a patch to our logging system such
that the &#8220;hex string&#8221; embedded in logging statements for
engines and pools is no longer needed to allow the <tt class="docutils literal"><span class="pre">echo</span></tt>
flag to work correctly.  A new system that uses filtered
logging objects allows us to maintain our current behavior
of <tt class="docutils literal"><span class="pre">echo</span></tt> being local to individual engines without the
need for additional identifying strings local to those
engines.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1926">#1926</a></p>
</div>
<div class="section" id="simplified-polymorphic-on-assignment">
<h3>Simplified polymorphic_on assignment<a class="headerlink" href="#simplified-polymorphic-on-assignment" title="Permalink to this headline">¶</a></h3>
<p>The population of the <tt class="docutils literal"><span class="pre">polymorphic_on</span></tt> column-mapped
attribute, when used in an inheritance scenario, now occurs
when the object is constructed, i.e. its <tt class="docutils literal"><span class="pre">__init__</span></tt> method
is called, using the init event.  The attribute then behaves
the same as any other column-mapped attribute.   Previously,
special logic would fire off during flush to populate this
column, which prevented any user code from modifying its
behavior.   The new approach improves upon this in three
ways: 1. the polymorphic identity is now present on the
object as soon as its constructed; 2. the polymorphic
identity can be changed by user code without any difference
in behavior from any other column-mapped attribute; 3. the
internals of the mapper during flush are simplified and no
longer need to make special checks for this column.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1895">#1895</a></p>
</div>
<div class="section" id="contains-eager-chains-across-multiple-paths-i-e-all">
<h3>contains_eager() chains across multiple paths (i.e. &#8220;all()&#8221;)<a class="headerlink" href="#contains-eager-chains-across-multiple-paths-i-e-all" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">`contains_eager()``</span></tt> modifier now will chain itself
for a longer path without the need to emit individual
<tt class="docutils literal"><span class="pre">``contains_eager()`</span></tt> calls. Instead of:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">A</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">contains_eager</span><span class="p">(</span><span class="n">A</span><span class="o">.</span><span class="n">b</span><span class="p">),</span> <span class="n">contains_eager</span><span class="p">(</span><span class="n">A</span><span class="o">.</span><span class="n">b</span><span class="p">,</span> <span class="n">B</span><span class="o">.</span><span class="n">c</span><span class="p">))</span></pre></div>
</div>
<p>you can say:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">A</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">contains_eager</span><span class="p">(</span><span class="n">A</span><span class="o">.</span><span class="n">b</span><span class="p">,</span> <span class="n">B</span><span class="o">.</span><span class="n">c</span><span class="p">))</span></pre></div>
</div>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2032">#2032</a></p>
</div>
<div class="section" id="flushing-of-orphans-that-have-no-parent-is-allowed">
<h3>Flushing of orphans that have no parent is allowed<a class="headerlink" href="#flushing-of-orphans-that-have-no-parent-is-allowed" title="Permalink to this headline">¶</a></h3>
<p>We&#8217;ve had a long standing behavior that checks for a so-
called &#8220;orphan&#8221; during flush, that is, an object which is
associated with a <tt class="docutils literal"><span class="pre">relationship()</span></tt> that specifies &#8220;delete-
orphan&#8221; cascade, has been newly added to the session for an
INSERT, and no parent relationship has been established.
This check was added years ago to accommodate some test
cases which tested the orphan behavior for consistency.   In
modern SQLA, this check is no longer needed on the Python
side.   The equivalent behavior of the &#8220;orphan check&#8221; is
accomplished by making the foreign key reference to the
object&#8217;s parent row NOT NULL, where the database does its
job of establishing data consistency in the same way SQLA
allows most other operations to do.   If the object&#8217;s parent
foreign key is nullable, then the row can be inserted.   The
&#8220;orphan&#8221; behavior runs when the object was persisted with a
particular parent, and is then disassociated with that
parent, leading to a DELETE statement emitted for it.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1912">#1912</a></p>
</div>
<div class="section" id="warnings-generated-when-collection-members-scalar-referents-not-part-of-the-flush">
<h3>Warnings generated when collection members, scalar referents not part of the flush<a class="headerlink" href="#warnings-generated-when-collection-members-scalar-referents-not-part-of-the-flush" title="Permalink to this headline">¶</a></h3>
<p>Warnings are now emitted when related objects referenced via
a loaded <tt class="docutils literal"><span class="pre">relationship()</span></tt> on a parent object marked as
&#8220;dirty&#8221; are not present in the current <tt class="docutils literal"><span class="pre">Session</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">save-update</span></tt> cascade takes effect when objects are
added to the <tt class="docutils literal"><span class="pre">Session</span></tt>, or when objects are first
associated with a parent, so that an object and everything
related to it are usually all present in the same
<tt class="docutils literal"><span class="pre">Session</span></tt>.  However, if <tt class="docutils literal"><span class="pre">save-update</span></tt> cascade is
disabled for a particular <tt class="docutils literal"><span class="pre">relationship()</span></tt>, then this
behavior does not occur, and the flush process does not try
to correct for it, instead staying consistent to the
configured cascade behavior.   Previously, when such objects
were detected during the flush, they were silently skipped.
The new behavior is that a warning is emitted, for the
purposes of alerting to a situation that more often than not
is the source of unexpected behavior.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1973">#1973</a></p>
</div>
<div class="section" id="setup-no-longer-installs-a-nose-plugin">
<h3>Setup no longer installs a Nose plugin<a class="headerlink" href="#setup-no-longer-installs-a-nose-plugin" title="Permalink to this headline">¶</a></h3>
<p>Since we moved to nose we&#8217;ve used a plugin that installs via
setuptools, so that the <tt class="docutils literal"><span class="pre">nosetests</span></tt> script would
automatically run SQLA&#8217;s plugin code, necessary for our
tests to have a full environment.  In the middle of 0.6, we
realized that the import pattern here meant that Nose&#8217;s
&#8220;coverage&#8221; plugin would break, since &#8220;coverage&#8221; requires
that it be started before any modules to be covered are
imported; so in the middle of 0.6 we made the situation
worse by adding a separate <tt class="docutils literal"><span class="pre">sqlalchemy-nose</span></tt> package to
the build to overcome this.</p>
<p>In 0.7 we&#8217;ve done away with trying to get <tt class="docutils literal"><span class="pre">nosetests</span></tt> to
work automatically, since the SQLAlchemy module would
produce a large number of nose configuration options for all
usages of <tt class="docutils literal"><span class="pre">nosetests</span></tt>, not just the SQLAlchemy unit tests
themselves, and the additional <tt class="docutils literal"><span class="pre">sqlalchemy-nose</span></tt> install
was an even worse idea, producing an extra package in Python
environments.   The <tt class="docutils literal"><span class="pre">sqla_nose.py</span></tt> script in 0.7 is now
the only way to run the tests with nose.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1949">#1949</a></p>
</div>
<div class="section" id="non-table-derived-constructs-can-be-mapped">
<h3>Non-<tt class="docutils literal"><span class="pre">Table</span></tt>-derived constructs can be mapped<a class="headerlink" href="#non-table-derived-constructs-can-be-mapped" title="Permalink to this headline">¶</a></h3>
<p>A construct that isn&#8217;t against any <tt class="docutils literal"><span class="pre">Table</span></tt> at all, like a
function, can be mapped.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">select</span><span class="p">,</span> <span class="n">func</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="kn">import</span> <span class="n">mapper</span>

<span class="k">class</span> <span class="nc">Subset</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="k">pass</span>
<span class="n">selectable</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="s">&quot;x&quot;</span><span class="p">,</span> <span class="s">&quot;y&quot;</span><span class="p">,</span> <span class="s">&quot;z&quot;</span><span class="p">])</span><span class="o">.</span><span class="n">select_from</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">some_db_function</span><span class="p">())</span><span class="o">.</span><span class="n">alias</span><span class="p">()</span>
<span class="n">mapper</span><span class="p">(</span><span class="n">Subset</span><span class="p">,</span> <span class="n">selectable</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="p">[</span><span class="n">selectable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">])</span></pre></div>
</div>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1876">#1876</a></p>
</div>
<div class="section" id="aliased-accepts-fromclause-elements">
<h3>aliased() accepts <tt class="docutils literal"><span class="pre">FromClause</span></tt> elements<a class="headerlink" href="#aliased-accepts-fromclause-elements" title="Permalink to this headline">¶</a></h3>
<p>This is a convenience helper such that in the case a plain
<tt class="docutils literal"><span class="pre">FromClause</span></tt>, such as a <tt class="docutils literal"><span class="pre">select</span></tt>, <tt class="docutils literal"><span class="pre">Table</span></tt> or <tt class="docutils literal"><span class="pre">join</span></tt>
is passed to the <tt class="docutils literal"><span class="pre">orm.aliased()</span></tt> construct, it passes
through to the <tt class="docutils literal"><span class="pre">.alias()</span></tt> method of that from construct
rather than constructing an ORM level <tt class="docutils literal"><span class="pre">AliasedClass</span></tt>.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2018">#2018</a></p>
</div>
<div class="section" id="session-connection-session-execute-accept-bind">
<h3>Session.connection(), Session.execute() accept &#8216;bind&#8217;<a class="headerlink" href="#session-connection-session-execute-accept-bind" title="Permalink to this headline">¶</a></h3>
<p>This is to allow execute/connection operations to
participate in the open transaction of an engine explicitly.
It also allows custom subclasses of <tt class="docutils literal"><span class="pre">Session</span></tt> that
implement their own <tt class="docutils literal"><span class="pre">get_bind()</span></tt> method and arguments to
use those custom arguments with both the <tt class="docutils literal"><span class="pre">execute()</span></tt> and
<tt class="docutils literal"><span class="pre">connection()</span></tt> methods equally.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/docs/07/orm/session.html#sqlalchemy.orm.session.Session.connection">Session.connection</a>
<a class="reference external" href="http://www.sqlalchemy.org/docs/07/orm/session.html#sqlalchemy.orm.session.Session.execute">Session.execute</a></p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1996">#1996</a></p>
</div>
<div class="section" id="standalone-bind-parameters-in-columns-clause-auto-labeled">
<h3>Standalone bind parameters in columns clause auto-labeled.<a class="headerlink" href="#standalone-bind-parameters-in-columns-clause-auto-labeled" title="Permalink to this headline">¶</a></h3>
<p>Bind parameters present in the &#8220;columns clause&#8221; of a select
are now auto-labeled like other &#8220;anonymous&#8221; clauses, which
among other things allows their &#8220;type&#8221; to be meaningful when
the row is fetched, as in result row processors.</p>
</div>
<div class="section" id="sqlite-relative-file-paths-are-normalized-through-os-path-abspath">
<h3>SQLite - relative file paths are normalized through os.path.abspath()<a class="headerlink" href="#sqlite-relative-file-paths-are-normalized-through-os-path-abspath" title="Permalink to this headline">¶</a></h3>
<p>This so that a script that changes the current directory
will continue to target the same location as subsequent
SQLite connections are established.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2036">#2036</a></p>
</div>
<div class="section" id="ms-sql-string-unicode-varchar-nvarchar-varbinary-emit-max-for-no-length">
<h3>MS-SQL - <tt class="docutils literal"><span class="pre">String</span></tt>/<tt class="docutils literal"><span class="pre">Unicode</span></tt>/<tt class="docutils literal"><span class="pre">VARCHAR</span></tt>/<tt class="docutils literal"><span class="pre">NVARCHAR</span></tt>/<tt class="docutils literal"><span class="pre">VARBINARY</span></tt> emit &#8220;max&#8221; for no length<a class="headerlink" href="#ms-sql-string-unicode-varchar-nvarchar-varbinary-emit-max-for-no-length" title="Permalink to this headline">¶</a></h3>
<p>On the MS-SQL backend, the String/Unicode types, and their
counterparts VARCHAR/ NVARCHAR, as well as VARBINARY
(<a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1833">#1833</a>) emit &#8220;max&#8221; as the length when no length is
specified. This makes it more compatible with Postgresql&#8217;s
VARCHAR type which is similarly unbounded when no length
specified.   SQL Server defaults the length on these types
to &#8216;1&#8217; when no length is specified.</p>
</div>
</div>
<div class="section" id="behavioral-changes-backwards-incompatible">
<h2>Behavioral Changes (Backwards Incompatible)<a class="headerlink" href="#behavioral-changes-backwards-incompatible" title="Permalink to this headline">¶</a></h2>
<p>Note again, aside from the default mutability change, most
of these changes are *extremely minor* and will not affect
most users.</p>
<div class="section" id="pickletype-and-array-mutability-turned-off-by-default">
<h3><tt class="docutils literal"><span class="pre">PickleType</span></tt> and ARRAY mutability turned off by default<a class="headerlink" href="#pickletype-and-array-mutability-turned-off-by-default" title="Permalink to this headline">¶</a></h3>
<p>This change refers to the default behavior of the ORM when
mapping columns that have either the <tt class="docutils literal"><span class="pre">PickleType</span></tt> or
<tt class="docutils literal"><span class="pre">postgresql.ARRAY</span></tt> datatypes.  The <tt class="docutils literal"><span class="pre">mutable</span></tt> flag is now
set to <tt class="docutils literal"><span class="pre">False</span></tt> by default. If an existing application uses
these types and depends upon detection of in-place
mutations, the type object must be constructed with
<tt class="docutils literal"><span class="pre">mutable=True</span></tt> to restore the 0.6 behavior:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Table</span><span class="p">(</span><span class="s">&#39;mytable&#39;</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
    <span class="c"># ....</span>

    <span class="n">Column</span><span class="p">(</span><span class="s">&#39;pickled_data&#39;</span><span class="p">,</span> <span class="n">PickleType</span><span class="p">(</span><span class="n">mutable</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
<span class="p">)</span></pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">mutable=True</span></tt> flag is being phased out, in favor of
the new <a class="reference external" href="http://www.sqlalchemy.org/docs/07/orm/extensions/mutable.html">Mutation Tracking</a> extension.  This extension
provides a mechanism by which user-defined datatypes can
provide change events back to the owning parent or parents.</p>
<p>The previous approach of using <tt class="docutils literal"><span class="pre">mutable=True</span></tt> does not
provide for change events - instead, the ORM must scan
through all mutable values present in a session and compare
them against their original value for changes every time
<tt class="docutils literal"><span class="pre">flush()</span></tt> is called, which is a very time consuming event.
This is a holdover from the very early days of SQLAlchemy
when <tt class="docutils literal"><span class="pre">flush()</span></tt> was not automatic and the history tracking
system was not nearly as sophisticated as it is now.</p>
<p>Existing applications which use <tt class="docutils literal"><span class="pre">PickleType</span></tt>,
<tt class="docutils literal"><span class="pre">postgresql.ARRAY</span></tt> or other <tt class="docutils literal"><span class="pre">MutableType</span></tt> subclasses,
and require in-place mutation detection, should migrate to
the new mutation tracking system, as <tt class="docutils literal"><span class="pre">mutable=True</span></tt> is
likely to be deprecated in the future.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1980">#1980</a></p>
</div>
<div class="section" id="mutability-detection-of-composite-requires-the-mutation-tracking-extension">
<h3>Mutability detection of <tt class="docutils literal"><span class="pre">composite()</span></tt> requires the Mutation Tracking Extension<a class="headerlink" href="#mutability-detection-of-composite-requires-the-mutation-tracking-extension" title="Permalink to this headline">¶</a></h3>
<p>So-called &#8220;composite&#8221; mapped attributes, those configured
using the technique described at <a class="reference external" href="http://www.sqlalchemy.org/docs/07/orm/mapper_config.html#composite-column-types">Composite Column Types</a>, have been re-implemented such
that the ORM internals are no longer aware of them (leading
to shorter and more efficient codepaths in critical
sections).   While composite types are generally intended to
be treated as immutable value objects, this was never
enforced.   For applications that use composites with
mutability, the <a class="reference external" href="http://www.sqlalchemy.org/docs/07/orm/extensions/mutable.html">Mutation Tracking</a> extension offers a
base class which establishes a mechanism for user-defined
composite types to send change event messages back to the
owning parent or parents of each object.</p>
<p>Applications which use composite types and rely upon in-
place mutation detection of these objects should either
migrate to the &#8220;mutation tracking&#8221; extension, or change the
usage of the composite types such that in-place changes are
no longer needed (i.e., treat them as immutable value
objects).</p>
</div>
<div class="section" id="sqlite-the-sqlite-dialect-now-uses-nullpool-for-file-based-databases">
<h3>SQLite - the SQLite dialect now uses <tt class="docutils literal"><span class="pre">NullPool</span></tt> for file-based databases<a class="headerlink" href="#sqlite-the-sqlite-dialect-now-uses-nullpool-for-file-based-databases" title="Permalink to this headline">¶</a></h3>
<p>This change is <strong>99.999% backwards compatible</strong>, unless you
are using temporary tables across connection pool
connections.</p>
<p>A file-based SQLite connection is blazingly fast, and using
<tt class="docutils literal"><span class="pre">NullPool</span></tt> means that each call to <tt class="docutils literal"><span class="pre">Engine.connect</span></tt>
creates a new pysqlite connection.</p>
<p>Previously, the <tt class="docutils literal"><span class="pre">SingletonThreadPool</span></tt> was used, which
meant that all connections to a certain engine in a thread
would be the same connection.   It&#8217;s intended that the new
approach is more intuitive, particularly when multiple
connections are used.</p>
<p><tt class="docutils literal"><span class="pre">SingletonThreadPool</span></tt> is still the default engine when a
<tt class="docutils literal"><span class="pre">:memory:</span></tt> database is used.</p>
<p>Note that this change <strong>breaks temporary tables used across
Session commits</strong>, due to the way SQLite handles temp
tables. See the note at
<a class="reference external" href="http://www.sqlalchemy.org/docs/dialects/sqlite.html#using">http://www.sqlalchemy.org/docs/dialects/sqlite.html#using</a>-
temporary-tables-with-sqlite if temporary tables beyond the
scope of one pool connection are desired.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1921">#1921</a></p>
</div>
<div class="section" id="session-merge-checks-version-ids-for-versioned-mappers">
<h3><tt class="docutils literal"><span class="pre">Session.merge()</span></tt> checks version ids for versioned mappers<a class="headerlink" href="#session-merge-checks-version-ids-for-versioned-mappers" title="Permalink to this headline">¶</a></h3>
<p>Session.merge() will check the version id of the incoming
state against that of the database, assuming the mapping
uses version ids and incoming state has a version_id
assigned, and raise StaleDataError if they don&#8217;t match.
This is the correct behavior, in that if incoming state
contains a stale version id, it should be assumed the state
is stale.</p>
<p>If merging data into a versioned state, the version id
attribute can be left undefined, and no version check will
take place.</p>
<p>This check was confirmed by examining what Hibernate does -
both the <tt class="docutils literal"><span class="pre">merge()</span></tt> and the versioning features were
originally adapted from Hibernate.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2027">#2027</a></p>
</div>
<div class="section" id="tuple-label-names-in-query-improved">
<h3>Tuple label names in Query Improved<a class="headerlink" href="#tuple-label-names-in-query-improved" title="Permalink to this headline">¶</a></h3>
<p>This improvement is potentially slightly backwards
incompatible for an application that relied upon the old
behavior.</p>
<p>Given two mapped classes <tt class="docutils literal"><span class="pre">Foo</span></tt> and <tt class="docutils literal"><span class="pre">Bar</span></tt> each with a
column <tt class="docutils literal"><span class="pre">spam</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">qa</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Foo</span><span class="o">.</span><span class="n">spam</span><span class="p">)</span>
<span class="n">qb</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Bar</span><span class="o">.</span><span class="n">spam</span><span class="p">)</span>

<span class="n">qu</span> <span class="o">=</span> <span class="n">qa</span><span class="o">.</span><span class="n">union</span><span class="p">(</span><span class="n">qb</span><span class="p">)</span></pre></div>
</div>
<p>The name given to the single column yielded by <tt class="docutils literal"><span class="pre">qu</span></tt> will
be <tt class="docutils literal"><span class="pre">spam</span></tt>.  Previously it would be something like
<tt class="docutils literal"><span class="pre">foo_spam</span></tt> due to the way the <tt class="docutils literal"><span class="pre">union</span></tt> would combine
things, which is inconsistent with the name <tt class="docutils literal"><span class="pre">spam</span></tt> in the
case of a non-unioned query.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1942">#1942</a></p>
</div>
<div class="section" id="mapped-column-attributes-reference-the-most-specific-column-first">
<h3>Mapped column attributes reference the most specific column first<a class="headerlink" href="#mapped-column-attributes-reference-the-most-specific-column-first" title="Permalink to this headline">¶</a></h3>
<p>This is a change to the behavior involved when a mapped
column attribute references multiple columns, specifically
when dealing with an attribute on a joined-table subclass
that has the same name as that of an attribute on the
superclass.</p>
<p>Using declarative, the scenario is this:</p>
<div class="highlight-python"><pre>class Parent(Base):
    __tablename__ = 'parent'
    id = Column(Integer, primary_key=True)

class Child(Parent):
   __tablename__ = 'child'
    id = Column(Integer, ForeignKey('parent.id'), primary_key=True)</pre>
</div>
<p>Above, the attribute <tt class="docutils literal"><span class="pre">Child.id</span></tt> refers to both the
<tt class="docutils literal"><span class="pre">child.id</span></tt> column as well as <tt class="docutils literal"><span class="pre">parent.id</span></tt> - this due to
the name of the attribute.  If it were named differently on
the class, such as <tt class="docutils literal"><span class="pre">Child.child_id</span></tt>, it then maps
distinctly to <tt class="docutils literal"><span class="pre">child.id</span></tt>, with <tt class="docutils literal"><span class="pre">Child.id</span></tt> being the same
attribute as <tt class="docutils literal"><span class="pre">Parent.id</span></tt>.</p>
<p>When the <tt class="docutils literal"><span class="pre">id</span></tt> attribute is made to reference both
<tt class="docutils literal"><span class="pre">parent.id</span></tt> and <tt class="docutils literal"><span class="pre">child.id</span></tt>, it stores them in an ordered
list.   An expression such as <tt class="docutils literal"><span class="pre">Child.id</span></tt> then refers to
just <em>one</em> of those columns when rendered. Up until 0.6,
this column would be <tt class="docutils literal"><span class="pre">parent.id</span></tt>.  In 0.7, it is the less
surprising <tt class="docutils literal"><span class="pre">child.id</span></tt>.</p>
<p>The legacy of this behavior deals with behaviors and
restrictions of the ORM that don&#8217;t really apply anymore; all
that was needed was to reverse the order.</p>
<p>A primary advantage of this approach is that it&#8217;s now easier
to construct <tt class="docutils literal"><span class="pre">primaryjoin</span></tt> expressions that refer to the
local column:</p>
<div class="highlight-python"><pre>class Child(Parent):
   __tablename__ = 'child'
    id = Column(Integer, ForeignKey('parent.id'), primary_key=True)
    some_related = relationship("SomeRelated",
                    primaryjoin="Child.id==SomeRelated.child_id")

class SomeRelated(Base):
   __tablename__ = 'some_related'
    id = Column(Integer, primary_key=True)
    child_id = Column(Integer, ForeignKey('child.id'))</pre>
</div>
<p>Prior to 0.7 the <tt class="docutils literal"><span class="pre">Child.id</span></tt> expression would reference
<tt class="docutils literal"><span class="pre">Parent.id</span></tt>, and it would be necessary to map <tt class="docutils literal"><span class="pre">child.id</span></tt>
to a distinct attribute.</p>
<p>It also means that a query like this one changes its
behavior:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Parent</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">Child</span><span class="o">.</span><span class="n">id</span> <span class="o">&gt;</span> <span class="mi">7</span><span class="p">)</span></pre></div>
</div>
<p>In 0.6, this would render:</p>
<div class="highlight-python"><pre>SELECT parent.id AS parent_id
FROM parent
WHERE parent.id &gt; :id_1</pre>
</div>
<p>in 0.7, you get:</p>
<div class="highlight-python"><pre>SELECT parent.id AS parent_id
FROM parent, child
WHERE child.id &gt; :id_1</pre>
</div>
<p>which you&#8217;ll note is a cartesian product - this behavior is
now equivalent to that of any other attribute that is local
to <tt class="docutils literal"><span class="pre">Child</span></tt>.   The <tt class="docutils literal"><span class="pre">with_polymorphic()</span></tt> method, or a
similar strategy of explicitly joining the underlying
<tt class="docutils literal"><span class="pre">Table</span></tt> objects, is used to render a query against all
<tt class="docutils literal"><span class="pre">Parent</span></tt> objects with criteria against <tt class="docutils literal"><span class="pre">Child</span></tt>, in the
same manner as that of 0.5 and 0.6:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span> <span class="n">s</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Parent</span><span class="p">)</span><span class="o">.</span><span class="n">with_polymorphic</span><span class="p">([</span><span class="n">Child</span><span class="p">])</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">Child</span><span class="o">.</span><span class="n">id</span> <span class="o">&gt;</span> <span class="mi">7</span><span class="p">)</span></pre></div>
</div>
<p>Which on both 0.6 and 0.7 renders:</p>
<div class="highlight-python"><pre>SELECT parent.id AS parent_id, child.id AS child_id
FROM parent LEFT OUTER JOIN child ON parent.id = child.id
WHERE child.id &gt; :id_1</pre>
</div>
<p>Another effect of this change is that a joined-inheritance
load across two tables will populate from the child table&#8217;s
value, not that of the parent table. An unusual case is that
a query against &#8220;Parent&#8221; using <tt class="docutils literal"><span class="pre">with_polymorphic=&quot;*&quot;</span></tt>
issues a query against &#8220;parent&#8221;, with a LEFT OUTER JOIN to
&#8220;child&#8221;.  The row is located in &#8220;Parent&#8221;, sees the
polymorphic identity corresponds to &#8220;Child&#8221;, but suppose the
actual row in &#8220;child&#8221; has been <em>deleted</em>.  Due to this
corruption, the row comes in with all the columns
corresponding to &#8220;child&#8221; set to NULL - this is now the value
that gets populated, not the one in the parent table.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1892">#1892</a></p>
</div>
<div class="section" id="mapping-to-joins-with-two-or-more-same-named-columns-requires-explicit-declaration">
<h3>Mapping to joins with two or more same-named columns requires explicit declaration<a class="headerlink" href="#mapping-to-joins-with-two-or-more-same-named-columns-requires-explicit-declaration" title="Permalink to this headline">¶</a></h3>
<p>This is somewhat related to the previous change in
<a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1892">#1892</a>.   When mapping to a join, same-named columns
must be explicitly linked to mapped attributes, i.e. as
described in <a class="reference external" href="http://www.sqlalchemy.org/docs/07/orm/mapper_config.html#mapping-a-class-against-multiple-tables">Mapping a Class Against Multiple Tables</a>.</p>
<p>Given two tables <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt>, each with a primary
key column <tt class="docutils literal"><span class="pre">id</span></tt>, the following now produces an error:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">foobar</span> <span class="o">=</span> <span class="n">foo</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">bar</span><span class="p">,</span> <span class="n">foo</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="n">bar</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">foo_id</span><span class="p">)</span>
<span class="n">mapper</span><span class="p">(</span><span class="n">FooBar</span><span class="p">,</span> <span class="n">foobar</span><span class="p">)</span></pre></div>
</div>
<p>This because the <tt class="docutils literal"><span class="pre">mapper()</span></tt> refuses to guess what column
is the primary representation of <tt class="docutils literal"><span class="pre">FooBar.id</span></tt> - is it
<tt class="docutils literal"><span class="pre">foo.c.id</span></tt> or is it <tt class="docutils literal"><span class="pre">bar.c.id</span></tt> ?   The attribute must be
explicit:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">foobar</span> <span class="o">=</span> <span class="n">foo</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">bar</span><span class="p">,</span> <span class="n">foo</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="n">bar</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">foo_id</span><span class="p">)</span>
<span class="n">mapper</span><span class="p">(</span><span class="n">FooBar</span><span class="p">,</span> <span class="n">foobar</span><span class="p">,</span> <span class="n">properties</span><span class="o">=</span><span class="p">{</span>
    <span class="s">&#39;id&#39;</span><span class="p">:[</span><span class="n">foo</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">bar</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">]</span>
<span class="p">})</span></pre></div>
</div>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1896">#1896</a></p>
</div>
<div class="section" id="mapper-requires-that-polymorphic-on-column-be-present-in-the-mapped-selectable">
<h3>Mapper requires that polymorphic_on column be present in the mapped selectable<a class="headerlink" href="#mapper-requires-that-polymorphic-on-column-be-present-in-the-mapped-selectable" title="Permalink to this headline">¶</a></h3>
<p>This is a warning in 0.6, now an error in 0.7.   The column
given for <tt class="docutils literal"><span class="pre">polymorphic_on</span></tt> must be in the mapped
selectable.  This to prevent some occasional user errors
such as:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">mapper</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">,</span> <span class="n">sometable</span><span class="p">,</span> <span class="n">polymorphic_on</span><span class="o">=</span><span class="n">some_lookup_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">)</span></pre></div>
</div>
<p>where above the polymorphic_on needs to be on a
<tt class="docutils literal"><span class="pre">sometable</span></tt> column, in this case perhaps
<tt class="docutils literal"><span class="pre">sometable.c.some_lookup_id</span></tt>.   There are also some
&#8220;polymorphic union&#8221; scenarios where similar mistakes
sometimes occur.</p>
<p>Such a configuration error has always been &#8220;wrong&#8221;, and the
above mapping doesn&#8217;t work as specified - the column would
be ignored.  It is however potentially backwards
incompatible in the rare case that an application has been
unknowingly relying upon this behavior.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1875">#1875</a></p>
</div>
<div class="section" id="ddl-constructs-now-escape-percent-signs">
<h3><tt class="docutils literal"><span class="pre">DDL()</span></tt> constructs now escape percent signs<a class="headerlink" href="#ddl-constructs-now-escape-percent-signs" title="Permalink to this headline">¶</a></h3>
<p>Previously, percent signs in <tt class="docutils literal"><span class="pre">DDL()</span></tt> strings would have to
be escaped, i.e. <tt class="docutils literal"><span class="pre">%%</span></tt> depending on DBAPI, for those DBAPIs
that accept <tt class="docutils literal"><span class="pre">pyformat</span></tt> or <tt class="docutils literal"><span class="pre">format</span></tt> binds (i.e. psycopg2,
mysql-python), which was inconsistent versus <tt class="docutils literal"><span class="pre">text()</span></tt>
constructs which did this automatically.  The same escaping
now occurs for <tt class="docutils literal"><span class="pre">DDL()</span></tt> as for <tt class="docutils literal"><span class="pre">text()</span></tt>.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1897">#1897</a></p>
</div>
<div class="section" id="table-c-metadata-tables-refined-a-bit-don-t-allow-direct-mutation">
<h3><tt class="docutils literal"><span class="pre">Table.c</span></tt> / <tt class="docutils literal"><span class="pre">MetaData.tables</span></tt> refined a bit, don&#8217;t allow direct mutation<a class="headerlink" href="#table-c-metadata-tables-refined-a-bit-don-t-allow-direct-mutation" title="Permalink to this headline">¶</a></h3>
<p>Another area where some users were tinkering around in such
a way that doesn&#8217;t actually work as expected, but still left
an exceedingly small chance that some application was
relying upon this behavior, the construct returned by the
<tt class="docutils literal"><span class="pre">.c</span></tt> attribute on <tt class="docutils literal"><span class="pre">Table</span></tt> and the <tt class="docutils literal"><span class="pre">.tables</span></tt> attribute
on <tt class="docutils literal"><span class="pre">MetaData</span></tt> is explicitly non-mutable.    The &#8220;mutable&#8221;
version of the construct is now private.   Adding columns to
<tt class="docutils literal"><span class="pre">.c</span></tt> involves using the <tt class="docutils literal"><span class="pre">append_column()</span></tt> method of
<tt class="docutils literal"><span class="pre">Table</span></tt>, which ensures things are associated with the
parent <tt class="docutils literal"><span class="pre">Table</span></tt> in the appropriate way; similarly,
<tt class="docutils literal"><span class="pre">MetaData.tables</span></tt> has a contract with the <tt class="docutils literal"><span class="pre">Table</span></tt>
objects stored in this dictionary, as well as a little bit
of new bookkeeping in that a <tt class="docutils literal"><span class="pre">set()</span></tt> of all schema names
is tracked, which is satisfied only by using the public
<tt class="docutils literal"><span class="pre">Table</span></tt> constructor as well as <tt class="docutils literal"><span class="pre">Table.tometadata()</span></tt>.</p>
<p>It is of course possible that the <tt class="docutils literal"><span class="pre">ColumnCollection</span></tt> and
<tt class="docutils literal"><span class="pre">dict</span></tt> collections consulted by these attributes could
someday implement events on all of their mutational methods
such that the appropriate bookkeeping occurred upon direct
mutation of the collections, but until someone has the
motivation to implement all that along with dozens of new
unit tests, narrowing the paths to mutation of these
collections will ensure no application is attempting to rely
upon usages that are currently not supported.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1893">#1893</a> <a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1917">#1917</a></p>
</div>
<div class="section" id="server-default-consistently-returns-none-for-all-inserted-primary-key-values">
<h3>server_default consistently returns None for all inserted_primary_key values<a class="headerlink" href="#server-default-consistently-returns-none-for-all-inserted-primary-key-values" title="Permalink to this headline">¶</a></h3>
<p>Established consistency when server_default is present on an
Integer PK column. SQLA doesn&#8217;t pre-fetch these, nor do they
come back in cursor.lastrowid (DBAPI). Ensured all backends
consistently return None in result.inserted_primary_key for
these - some backends may have returned a value previously.
Using a server_default on a primary key column is extremely
unusual.   If a special function or SQL expression is used
to generate primary key defaults, this should be established
as a Python-side &#8220;default&#8221; instead of server_default.</p>
<p>Regarding reflection for this case, reflection of an int PK
col with a server_default sets the &#8220;autoincrement&#8221; flag to
False, except in the case of a PG SERIAL col where we
detected a sequence default.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2020">#2020</a> <a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/2021">#2021</a></p>
</div>
<div class="section" id="the-sqlalchemy-exceptions-alias-in-sys-modules-is-removed">
<h3>The <tt class="docutils literal"><span class="pre">sqlalchemy.exceptions</span></tt> alias in sys.modules is removed<a class="headerlink" href="#the-sqlalchemy-exceptions-alias-in-sys-modules-is-removed" title="Permalink to this headline">¶</a></h3>
<p>For a few years we&#8217;ve added the string
<tt class="docutils literal"><span class="pre">sqlalchemy.exceptions</span></tt> to <tt class="docutils literal"><span class="pre">sys.modules</span></tt>, so that a
statement like &#8220;<tt class="docutils literal"><span class="pre">import</span> <span class="pre">sqlalchemy.exceptions</span></tt>&#8221; would
work.   The name of the core exceptions module has been
<tt class="docutils literal"><span class="pre">exc</span></tt> for a long time now, so the recommended import for
this module is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">exc</span></pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">exceptions</span></tt> name is still present in &#8220;<tt class="docutils literal"><span class="pre">sqlalchemy</span></tt>&#8221;
for applications which might have said <tt class="docutils literal"><span class="pre">from</span> <span class="pre">sqlalchemy</span>
<span class="pre">import</span> <span class="pre">exceptions</span></tt>, but they should also start using the
<tt class="docutils literal"><span class="pre">exc</span></tt> name.</p>
</div>
<div class="section" id="query-timing-recipe-changes">
<h3>Query Timing Recipe Changes<a class="headerlink" href="#query-timing-recipe-changes" title="Permalink to this headline">¶</a></h3>
<p>While not part of SQLAlchemy itself, it&#8217;s worth mentioning
that the rework of the <tt class="docutils literal"><span class="pre">ConnectionProxy</span></tt> into the new
event system means it is no longer appropriate for the
&#8220;Timing all Queries&#8221; recipe.  Please adjust query-timers to
use the <tt class="docutils literal"><span class="pre">before_cursor_execute()</span></tt> and
<tt class="docutils literal"><span class="pre">after_cursor_execute()</span></tt> events, demonstrated in the
updated recipe UsageRecipes/Profiling.</p>
</div>
</div>
<div class="section" id="deprecated-api">
<h2>Deprecated API<a class="headerlink" href="#deprecated-api" title="Permalink to this headline">¶</a></h2>
<div class="section" id="default-constructor-on-types-will-not-accept-arguments">
<h3>Default constructor on types will not accept arguments<a class="headerlink" href="#default-constructor-on-types-will-not-accept-arguments" title="Permalink to this headline">¶</a></h3>
<p>Simple types like <tt class="docutils literal"><span class="pre">Integer</span></tt>, <tt class="docutils literal"><span class="pre">Date</span></tt> etc. in the core
types module don&#8217;t accept arguments.  The default
constructor that accepts/ignores a catchall <tt class="docutils literal"><span class="pre">\*args,</span>
<span class="pre">\**kwargs</span></tt> is restored as of 0.7b4/0.7.0, but emits a
deprecation warning.</p>
<p>If arguments are being used with a core type like
<tt class="docutils literal"><span class="pre">Integer</span></tt>, it may be that you intended to use a dialect
specific type, such as <tt class="docutils literal"><span class="pre">sqlalchemy.dialects.mysql.INTEGER</span></tt>
which does accept a &#8220;display_width&#8221; argument for example.</p>
</div>
<div class="section" id="compile-mappers-renamed-configure-mappers-simplified-configuration-internals">
<h3>compile_mappers() renamed configure_mappers(), simplified configuration internals<a class="headerlink" href="#compile-mappers-renamed-configure-mappers-simplified-configuration-internals" title="Permalink to this headline">¶</a></h3>
<p>This system slowly morphed from something small, implemented
local to an individual mapper, and poorly named into
something that&#8217;s more of a global &#8220;registry-&#8221; level function
and poorly named, so we&#8217;ve fixed both by moving the
implementation out of <tt class="docutils literal"><span class="pre">Mapper</span></tt> altogether and renaming it
to <tt class="docutils literal"><span class="pre">configure_mappers()</span></tt>.   It is of course normally not
needed for an application to call <tt class="docutils literal"><span class="pre">configure_mappers()</span></tt> as
this process occurs on an as-needed basis, as soon as the
mappings are needed via attribute or query access.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1966">#1966</a></p>
</div>
<div class="section" id="core-listener-proxy-superseded-by-event-listeners">
<h3>Core listener/proxy superseded by event listeners<a class="headerlink" href="#core-listener-proxy-superseded-by-event-listeners" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">PoolListener</span></tt>, <tt class="docutils literal"><span class="pre">ConnectionProxy</span></tt>,
<tt class="docutils literal"><span class="pre">DDLElement.execute_at</span></tt> are superseded by
<tt class="docutils literal"><span class="pre">event.listen()</span></tt>, using the <tt class="docutils literal"><span class="pre">PoolEvents</span></tt>,
<tt class="docutils literal"><span class="pre">EngineEvents</span></tt>, <tt class="docutils literal"><span class="pre">DDLEvents</span></tt> dispatch targets,
respectively.</p>
</div>
<div class="section" id="orm-extensions-superseded-by-event-listeners">
<h3>ORM extensions superseded by event listeners<a class="headerlink" href="#orm-extensions-superseded-by-event-listeners" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">MapperExtension</span></tt>, <tt class="docutils literal"><span class="pre">AttributeExtension</span></tt>,
<tt class="docutils literal"><span class="pre">SessionExtension</span></tt> are superseded by <tt class="docutils literal"><span class="pre">event.listen()</span></tt>,
using the <tt class="docutils literal"><span class="pre">MapperEvents</span></tt>/<tt class="docutils literal"><span class="pre">InstanceEvents</span></tt>,
<tt class="docutils literal"><span class="pre">AttributeEvents</span></tt>, <tt class="docutils literal"><span class="pre">SessionEvents</span></tt>, dispatch targets,
respectively.</p>
</div>
<div class="section" id="sending-a-string-to-distinct-in-select-for-mysql-should-be-done-via-prefixes">
<h3>Sending a string to &#8216;distinct&#8217; in select() for MySQL should be done via prefixes<a class="headerlink" href="#sending-a-string-to-distinct-in-select-for-mysql-should-be-done-via-prefixes" title="Permalink to this headline">¶</a></h3>
<p>This obscure feature allows this pattern with the MySQL
backend:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">select</span><span class="p">([</span><span class="n">mytable</span><span class="p">],</span> <span class="n">distinct</span><span class="o">=</span><span class="s">&#39;ALL&#39;</span><span class="p">,</span> <span class="n">prefixes</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;HIGH_PRIORITY&#39;</span><span class="p">])</span></pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">prefixes</span></tt> keyword or <tt class="docutils literal"><span class="pre">prefix_with()</span></tt> method should
be used for non-standard or unusual prefixes:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">select</span><span class="p">([</span><span class="n">mytable</span><span class="p">])</span><span class="o">.</span><span class="n">prefix_with</span><span class="p">(</span><span class="s">&#39;HIGH_PRIORITY&#39;</span><span class="p">,</span> <span class="s">&#39;ALL&#39;</span><span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="useexisting-superseded-by-extend-existing-and-keep-existing">
<h3><tt class="docutils literal"><span class="pre">useexisting</span></tt> superseded by <tt class="docutils literal"><span class="pre">extend_existing</span></tt> and <tt class="docutils literal"><span class="pre">keep_existing</span></tt><a class="headerlink" href="#useexisting-superseded-by-extend-existing-and-keep-existing" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">useexisting</span></tt> flag on Table has been superseded by a
new pair of flags <tt class="docutils literal"><span class="pre">keep_existing</span></tt> and <tt class="docutils literal"><span class="pre">extend_existing</span></tt>.
<tt class="docutils literal"><span class="pre">extend_existing</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">useexisting</span></tt> - the
existing Table is returned, and additional constructor
elements are added. With <tt class="docutils literal"><span class="pre">keep_existing</span></tt>, the existing
Table is returned, but additional constructor elements are
not added - these elements are only applied when the Table
is newly created.</p>
</div>
</div>
<div class="section" id="backwards-incompatible-api-changes">
<h2>Backwards Incompatible API Changes<a class="headerlink" href="#backwards-incompatible-api-changes" title="Permalink to this headline">¶</a></h2>
<div class="section" id="callables-passed-to-bindparam-don-t-get-evaluated-affects-the-beaker-example">
<h3>Callables passed to <tt class="docutils literal"><span class="pre">bindparam()</span></tt> don&#8217;t get evaluated - affects the Beaker example<a class="headerlink" href="#callables-passed-to-bindparam-don-t-get-evaluated-affects-the-beaker-example" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1950">#1950</a></p>
<p>Note this affects the Beaker caching example, where the
workings of the <tt class="docutils literal"><span class="pre">_params_from_query()</span></tt> function needed a
slight adjustment. If you&#8217;re using code from the Beaker
example, this change should be applied.</p>
</div>
<div class="section" id="types-type-map-is-now-private-types-type-map">
<h3>types.type_map is now private, types._type_map<a class="headerlink" href="#types-type-map-is-now-private-types-type-map" title="Permalink to this headline">¶</a></h3>
<p>We noticed some users tapping into this dictionary inside of
<tt class="docutils literal"><span class="pre">sqlalchemy.types</span></tt> as a shortcut to associating Python
types with SQL types. We can&#8217;t guarantee the contents or
format of this dictionary, and additionally the business of
associating Python types in a one-to-one fashion has some
grey areas that should are best decided by individual
applications, so we&#8217;ve underscored this attribute.</p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1870">#1870</a></p>
</div>
<div class="section" id="renamed-the-alias-keyword-arg-of-standalone-alias-function-to-name">
<h3>Renamed the <tt class="docutils literal"><span class="pre">alias</span></tt> keyword arg of standalone <tt class="docutils literal"><span class="pre">alias()</span></tt> function to <tt class="docutils literal"><span class="pre">name</span></tt><a class="headerlink" href="#renamed-the-alias-keyword-arg-of-standalone-alias-function-to-name" title="Permalink to this headline">¶</a></h3>
<p>This so that the keyword argument <tt class="docutils literal"><span class="pre">name</span></tt> matches that of
the <tt class="docutils literal"><span class="pre">alias()</span></tt> methods on all <tt class="docutils literal"><span class="pre">FromClause</span></tt> objects as
well as the <tt class="docutils literal"><span class="pre">name</span></tt> argument on <tt class="docutils literal"><span class="pre">Query.subquery()</span></tt>.</p>
<p>Only code that uses the standalone <tt class="docutils literal"><span class="pre">alias()</span></tt> function, and
not the method bound functions, and passes the alias name
using the explicit keyword name <tt class="docutils literal"><span class="pre">alias</span></tt>, and not
positionally, would need modification here.</p>
</div>
<div class="section" id="non-public-pool-methods-underscored">
<h3>Non-public <tt class="docutils literal"><span class="pre">Pool</span></tt> methods underscored<a class="headerlink" href="#non-public-pool-methods-underscored" title="Permalink to this headline">¶</a></h3>
<p>All methods of <tt class="docutils literal"><span class="pre">Pool</span></tt> and subclasses which are not
intended for public use have been renamed with underscores.
That they were not named this way previously was a bug.</p>
<p>Pooling methods now underscored or removed:</p>
<p><tt class="docutils literal"><span class="pre">Pool.create_connection()</span></tt> -&gt;
<tt class="docutils literal"><span class="pre">Pool._create_connection()</span></tt></p>
<p><tt class="docutils literal"><span class="pre">Pool.do_get()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">Pool._do_get()</span></tt></p>
<p><tt class="docutils literal"><span class="pre">Pool.do_return_conn()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">Pool._do_return_conn()</span></tt></p>
<p><tt class="docutils literal"><span class="pre">Pool.do_return_invalid()</span></tt> -&gt; removed, was not used</p>
<p><tt class="docutils literal"><span class="pre">Pool.return_conn()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">Pool._return_conn()</span></tt></p>
<p><tt class="docutils literal"><span class="pre">Pool.get()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">Pool._get()</span></tt>, public API is
<tt class="docutils literal"><span class="pre">Pool.connect()</span></tt></p>
<p><tt class="docutils literal"><span class="pre">SingletonThreadPool.cleanup()</span></tt> -&gt; <tt class="docutils literal"><span class="pre">_cleanup()</span></tt></p>
<p><tt class="docutils literal"><span class="pre">SingletonThreadPool.dispose_local()</span></tt> -&gt; removed, use
<tt class="docutils literal"><span class="pre">conn.invalidate()</span></tt></p>
<p><a class="reference external" href="http://www.sqlalchemy.org/trac/ticket/1982">#1982</a></p>
</div>
</div>
<div class="section" id="previously-deprecated-now-removed">
<h2>Previously Deprecated, Now Removed<a class="headerlink" href="#previously-deprecated-now-removed" title="Permalink to this headline">¶</a></h2>
<div class="section" id="query-join-query-outerjoin-eagerload-eagerload-all-others-no-longer-allow-lists-of-attributes-as-arguments">
<h3>Query.join(), Query.outerjoin(), eagerload(), eagerload_all(), others no longer allow lists of attributes as arguments<a class="headerlink" href="#query-join-query-outerjoin-eagerload-eagerload-all-others-no-longer-allow-lists-of-attributes-as-arguments" title="Permalink to this headline">¶</a></h3>
<p>Passing a list of attributes or attribute names to
<tt class="docutils literal"><span class="pre">Query.join</span></tt>, <tt class="docutils literal"><span class="pre">eagerload()</span></tt>, and similar has been
deprecated since 0.5:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># old way, deprecated since 0.5</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Houses</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">Houses</span><span class="o">.</span><span class="n">rooms</span><span class="p">,</span> <span class="n">Room</span><span class="o">.</span><span class="n">closets</span><span class="p">])</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Houses</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">eagerload_all</span><span class="p">([</span><span class="n">Houses</span><span class="o">.</span><span class="n">rooms</span><span class="p">,</span> <span class="n">Room</span><span class="o">.</span><span class="n">closets</span><span class="p">]))</span></pre></div>
</div>
<p>These methods all accept *args as of the 0.5 series:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># current way, in place since 0.5</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Houses</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">Houses</span><span class="o">.</span><span class="n">rooms</span><span class="p">,</span> <span class="n">Room</span><span class="o">.</span><span class="n">closets</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Houses</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">eagerload_all</span><span class="p">(</span><span class="n">Houses</span><span class="o">.</span><span class="n">rooms</span><span class="p">,</span> <span class="n">Room</span><span class="o">.</span><span class="n">closets</span><span class="p">))</span></pre></div>
</div>
</div>
<div class="section" id="scopedsession-mapper-is-removed">
<h3><tt class="docutils literal"><span class="pre">ScopedSession.mapper</span></tt> is removed<a class="headerlink" href="#scopedsession-mapper-is-removed" title="Permalink to this headline">¶</a></h3>
<p>This feature provided a mapper extension which linked class-
based functionality with a particular <tt class="docutils literal"><span class="pre">ScopedSession</span></tt>, in
particular providing the behavior such that new object
instances would be automatically associated with that
session.   The feature was overused by tutorials and
frameworks which led to great user confusion due to its
implicit behavior, and was deprecated in 0.5.5.   Techniques
for replicating its functionality are at
[wiki:UsageRecipes/SessionAwareMapper]</p>
</div>
</div>
</div>

    </div>

</div>

<div id="docs-bottom-navigation" class="docs-navigation-links">
        Previous:
        <a href="migration_08.html" title="previous chapter">What&#8217;s New in SQLAlchemy 0.8?</a>
        Next:
        <a href="migration_06.html" title="next chapter">What&#8217;s New in SQLAlchemy 0.6?</a>

    <div id="docs-copyright">
        &copy; <a href="../copyright.html">Copyright</a> 2007-2014, the SQLAlchemy authors and contributors.
        Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1.
    </div>
</div>

</div>

        
    </body>
</html>