<!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’s New in SQLAlchemy 0.7? — SQLAlchemy 1.2 Documentation </title> <!-- begin iterate through site-imported + 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/changelog.css" type="text/css" /> <link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" /> <!-- end iterate through site-imported + sphinx environment css_files --> <!-- begin layout.mako headers --> <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 1.2 Documentation" href="../index.html" /> <link rel="up" title="Changes and Migration" href="index.html" /> <link rel="next" title="What’s New in SQLAlchemy 0.6?" href="migration_06.html" /> <link rel="prev" title="What’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">1.2.19</span> | Release Date: April 15, 2019 </div> <h1>SQLAlchemy 1.2 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 1.2 Documentation</a></h3> <p id="sidebar-topnav"> <a href="../contents.html">Contents</a> | <a href="../genindex.html">Index</a> </p> <div id="sidebar-search"> <form class="search" action="../search.html" method="get"> <label> Search terms: <input type="text" placeholder="search..." name="q" size="12" /> </label> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div id="docs-sidebar"> <div id="sidebar-banner"> </div> <div id="docs-sidebar-inner"> <h3> <a href="index.html" title="Changes and Migration">Changes and Migration</a> </h3> <ul> <li><span class="link-container"><a class="reference external" href="migration_12.html">What’s New in SQLAlchemy 1.2?</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_12.html">1.2 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_11.html">1.1 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_10.html">1.0 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_09.html">0.9 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_08.html">0.8 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_07.html">0.7 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_06.html">0.6 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_05.html">0.5 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_04.html">0.4 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_03.html">0.3 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_02.html">0.2 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="changelog_01.html">0.1 Changelog</a></span></li> <li><span class="link-container"><a class="reference external" href="migration_11.html">What’s New in SQLAlchemy 1.1?</a></span></li> <li><span class="link-container"><a class="reference external" href="migration_10.html">What’s New in SQLAlchemy 1.0?</a></span></li> <li><span class="link-container"><a class="reference external" href="migration_09.html">What’s New in SQLAlchemy 0.9?</a></span></li> <li><span class="link-container"><a class="reference external" href="migration_08.html">What’s New in SQLAlchemy 0.8?</a></span></li> <li class="selected"><span class="link-container"><strong>What’s New in SQLAlchemy 0.7?</strong><a class="paramlink headerlink reference internal" href="#">¶</a></span><ul> <li><span class="link-container"><a class="reference external" href="#introduction">Introduction</a></span></li> <li><span class="link-container"><a class="reference external" href="#new-features">New Features</a></span><ul> <li><span class="link-container"><a class="reference external" href="#new-event-system">New Event System</a></span></li> <li><span class="link-container"><a class="reference external" href="#hybrid-attributes-implements-supersedes-synonym-comparable-property">Hybrid Attributes, implements/supersedes synonym(), comparable_property()</a></span></li> <li><span class="link-container"><a class="reference external" href="#speed-enhancements">Speed Enhancements</a></span></li> <li><span class="link-container"><a class="reference external" href="#composites-rewritten">Composites Rewritten</a></span></li> <li><span class="link-container"><a class="reference external" href="#more-succinct-form-of-query-join-target-onclause">More succinct form of query.join(target, onclause)</a></span></li> <li><span class="link-container"><a class="reference external" href="#mutation-event-extension-supersedes-mutable-true">Mutation event extension, supersedes “mutable=True”</a></span></li> <li><span class="link-container"><a class="reference external" href="#nulls-first-nulls-last-operators">NULLS FIRST / NULLS LAST operators</a></span></li> <li><span class="link-container"><a class="reference external" href="#select-distinct-query-distinct-accepts-args-for-postgresql-distinct-on">select.distinct(), query.distinct() accepts *args for PostgreSQL DISTINCT ON</a></span></li> <li><span class="link-container"><a class="reference external" href="#index-can-be-placed-inline-inside-of-table-table-args"><code class="docutils literal notranslate"><span class="pre">Index()</span></code> can be placed inline inside of <code class="docutils literal notranslate"><span class="pre">Table</span></code>, <code class="docutils literal notranslate"><span class="pre">__table_args__</span></code></a></span></li> <li><span class="link-container"><a class="reference external" href="#window-function-sql-construct">Window Function SQL Construct</a></span></li> <li><span class="link-container"><a class="reference external" href="#execution-options-on-connection-accepts-isolation-level-argument">execution_options() on Connection accepts “isolation_level” argument</a></span></li> <li><span class="link-container"><a class="reference external" href="#typedecorator-works-with-integer-primary-key-columns"><code class="docutils literal notranslate"><span class="pre">TypeDecorator</span></code> works with integer primary key columns</a></span></li> <li><span class="link-container"><a class="reference external" href="#typedecorator-is-present-in-the-sqlalchemy-import-space"><code class="docutils literal notranslate"><span class="pre">TypeDecorator</span></code> is present in the “sqlalchemy” import space</a></span></li> <li><span class="link-container"><a class="reference external" href="#new-dialects">New Dialects</a></span></li> </ul> </li> <li><span class="link-container"><a class="reference external" href="#behavioral-changes-backwards-compatible">Behavioral Changes (Backwards Compatible)</a></span><ul> <li><span class="link-container"><a class="reference external" href="#c-extensions-build-by-default">C Extensions Build by Default</a></span></li> <li><span class="link-container"><a class="reference external" href="#query-count-simplified-should-work-virtually-always">Query.count() simplified, should work virtually always</a></span><ul> <li><span class="link-container"><a class="reference external" href="#to-emit-a-non-subquery-form-of-count">To emit a non-subquery form of count()</a></span></li> </ul> </li> <li><span class="link-container"><a class="reference external" href="#limit-offset-clauses-now-use-bind-parameters">LIMIT/OFFSET clauses now use bind parameters</a></span></li> <li><span class="link-container"><a class="reference external" href="#logging-enhancements">Logging enhancements</a></span></li> <li><span class="link-container"><a class="reference external" href="#simplified-polymorphic-on-assignment">Simplified polymorphic_on assignment</a></span></li> <li><span class="link-container"><a class="reference external" href="#contains-eager-chains-across-multiple-paths-i-e-all">contains_eager() chains across multiple paths (i.e. “all()”)</a></span></li> <li><span class="link-container"><a class="reference external" href="#flushing-of-orphans-that-have-no-parent-is-allowed">Flushing of orphans that have no parent is allowed</a></span></li> <li><span class="link-container"><a class="reference external" 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></span></li> <li><span class="link-container"><a class="reference external" href="#setup-no-longer-installs-a-nose-plugin">Setup no longer installs a Nose plugin</a></span></li> <li><span class="link-container"><a class="reference external" href="#non-table-derived-constructs-can-be-mapped">Non-<code class="docutils literal notranslate"><span class="pre">Table</span></code>-derived constructs can be mapped</a></span></li> <li><span class="link-container"><a class="reference external" href="#aliased-accepts-fromclause-elements">aliased() accepts <code class="docutils literal notranslate"><span class="pre">FromClause</span></code> elements</a></span></li> <li><span class="link-container"><a class="reference external" href="#session-connection-session-execute-accept-bind">Session.connection(), Session.execute() accept ‘bind’</a></span></li> <li><span class="link-container"><a class="reference external" href="#standalone-bind-parameters-in-columns-clause-auto-labeled">Standalone bind parameters in columns clause auto-labeled.</a></span></li> <li><span class="link-container"><a class="reference external" href="#sqlite-relative-file-paths-are-normalized-through-os-path-abspath">SQLite - relative file paths are normalized through os.path.abspath()</a></span></li> <li><span class="link-container"><a class="reference external" href="#ms-sql-string-unicode-varchar-nvarchar-varbinary-emit-max-for-no-length">MS-SQL - <code class="docutils literal notranslate"><span class="pre">String</span></code>/<code class="docutils literal notranslate"><span class="pre">Unicode</span></code>/<code class="docutils literal notranslate"><span class="pre">VARCHAR</span></code>/<code class="docutils literal notranslate"><span class="pre">NVARCHAR</span></code>/<code class="docutils literal notranslate"><span class="pre">VARBINARY</span></code> emit “max” for no length</a></span></li> </ul> </li> <li><span class="link-container"><a class="reference external" href="#behavioral-changes-backwards-incompatible">Behavioral Changes (Backwards Incompatible)</a></span><ul> <li><span class="link-container"><a class="reference external" href="#pickletype-and-array-mutability-turned-off-by-default"><code class="docutils literal notranslate"><span class="pre">PickleType</span></code> and ARRAY mutability turned off by default</a></span></li> <li><span class="link-container"><a class="reference external" href="#mutability-detection-of-composite-requires-the-mutation-tracking-extension">Mutability detection of <code class="docutils literal notranslate"><span class="pre">composite()</span></code> requires the Mutation Tracking Extension</a></span></li> <li><span class="link-container"><a class="reference external" href="#sqlite-the-sqlite-dialect-now-uses-nullpool-for-file-based-databases">SQLite - the SQLite dialect now uses <code class="docutils literal notranslate"><span class="pre">NullPool</span></code> for file-based databases</a></span></li> <li><span class="link-container"><a class="reference external" href="#session-merge-checks-version-ids-for-versioned-mappers"><code class="docutils literal notranslate"><span class="pre">Session.merge()</span></code> checks version ids for versioned mappers</a></span></li> <li><span class="link-container"><a class="reference external" href="#tuple-label-names-in-query-improved">Tuple label names in Query Improved</a></span></li> <li><span class="link-container"><a class="reference external" href="#mapped-column-attributes-reference-the-most-specific-column-first">Mapped column attributes reference the most specific column first</a></span></li> <li><span class="link-container"><a class="reference external" 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></span></li> <li><span class="link-container"><a class="reference external" 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></span></li> <li><span class="link-container"><a class="reference external" href="#ddl-constructs-now-escape-percent-signs"><code class="docutils literal notranslate"><span class="pre">DDL()</span></code> constructs now escape percent signs</a></span></li> <li><span class="link-container"><a class="reference external" href="#table-c-metadata-tables-refined-a-bit-don-t-allow-direct-mutation"><code class="docutils literal notranslate"><span class="pre">Table.c</span></code> / <code class="docutils literal notranslate"><span class="pre">MetaData.tables</span></code> refined a bit, don’t allow direct mutation</a></span></li> <li><span class="link-container"><a class="reference external" href="#server-default-consistently-returns-none-for-all-inserted-primary-key-values">server_default consistently returns None for all inserted_primary_key values</a></span></li> <li><span class="link-container"><a class="reference external" href="#the-sqlalchemy-exceptions-alias-in-sys-modules-is-removed">The <code class="docutils literal notranslate"><span class="pre">sqlalchemy.exceptions</span></code> alias in sys.modules is removed</a></span></li> <li><span class="link-container"><a class="reference external" href="#query-timing-recipe-changes">Query Timing Recipe Changes</a></span></li> </ul> </li> <li><span class="link-container"><a class="reference external" href="#deprecated-api">Deprecated API</a></span><ul> <li><span class="link-container"><a class="reference external" href="#default-constructor-on-types-will-not-accept-arguments">Default constructor on types will not accept arguments</a></span></li> <li><span class="link-container"><a class="reference external" href="#compile-mappers-renamed-configure-mappers-simplified-configuration-internals">compile_mappers() renamed configure_mappers(), simplified configuration internals</a></span></li> <li><span class="link-container"><a class="reference external" href="#core-listener-proxy-superseded-by-event-listeners">Core listener/proxy superseded by event listeners</a></span></li> <li><span class="link-container"><a class="reference external" href="#orm-extensions-superseded-by-event-listeners">ORM extensions superseded by event listeners</a></span></li> <li><span class="link-container"><a class="reference external" href="#sending-a-string-to-distinct-in-select-for-mysql-should-be-done-via-prefixes">Sending a string to ‘distinct’ in select() for MySQL should be done via prefixes</a></span></li> <li><span class="link-container"><a class="reference external" href="#useexisting-superseded-by-extend-existing-and-keep-existing"><code class="docutils literal notranslate"><span class="pre">useexisting</span></code> superseded by <code class="docutils literal notranslate"><span class="pre">extend_existing</span></code> and <code class="docutils literal notranslate"><span class="pre">keep_existing</span></code></a></span></li> </ul> </li> <li><span class="link-container"><a class="reference external" href="#backwards-incompatible-api-changes">Backwards Incompatible API Changes</a></span><ul> <li><span class="link-container"><a class="reference external" href="#callables-passed-to-bindparam-don-t-get-evaluated-affects-the-beaker-example">Callables passed to <code class="docutils literal notranslate"><span class="pre">bindparam()</span></code> don’t get evaluated - affects the Beaker example</a></span></li> <li><span class="link-container"><a class="reference external" href="#types-type-map-is-now-private-types-type-map">types.type_map is now private, types._type_map</a></span></li> <li><span class="link-container"><a class="reference external" href="#renamed-the-alias-keyword-arg-of-standalone-alias-function-to-name">Renamed the <code class="docutils literal notranslate"><span class="pre">alias</span></code> keyword arg of standalone <code class="docutils literal notranslate"><span class="pre">alias()</span></code> function to <code class="docutils literal notranslate"><span class="pre">name</span></code></a></span></li> <li><span class="link-container"><a class="reference external" href="#non-public-pool-methods-underscored">Non-public <code class="docutils literal notranslate"><span class="pre">Pool</span></code> methods underscored</a></span></li> </ul> </li> <li><span class="link-container"><a class="reference external" href="#previously-deprecated-now-removed">Previously Deprecated, Now Removed</a></span><ul> <li><span class="link-container"><a class="reference external" 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></span></li> <li><span class="link-container"><a class="reference external" href="#scopedsession-mapper-is-removed"><code class="docutils literal notranslate"><span class="pre">ScopedSession.mapper</span></code> is removed</a></span></li> </ul> </li> </ul> </li> <li><span class="link-container"><a class="reference external" href="migration_06.html">What’s New in SQLAlchemy 0.6?</a></span></li> <li><span class="link-container"><a class="reference external" href="migration_05.html">What’s new in SQLAlchemy 0.5?</a></span></li> <li><span class="link-container"><a class="reference external" href="migration_04.html">What’s new in SQLAlchemy 0.4?</a></span></li> </ul> </div> </div> </div> <div id="docs-body" class="withsidebar" > <div class="section" id="what-s-new-in-sqlalchemy-0-7"> <h1>What’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="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>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’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’s not much difference between the terms “superseded” and “deprecated”, except that the former has a much weaker suggestion of the old feature would ever be removed. In 0.7, features like <code class="docutils literal notranslate"><span class="pre">synonym</span></code> and <code class="docutils literal notranslate"><span class="pre">comparable_property</span></code>, as well as all the <code class="docutils literal notranslate"><span class="pre">Extension</span></code> and other event classes, have been superseded. But these “superseded” features have been re-implemented such that their implementations live mostly outside of core ORM code, so their continued “hanging around” doesn’t impact SQLAlchemy’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 <code class="docutils literal notranslate"><span class="pre">MapperExtension</span></code> 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 “extension”, “listener”, and “proxy” 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; <code class="docutils literal notranslate"><span class="pre">ConnectionProxy</span></code> objects wanted to provide a system of rewriting statements and parameters; <code class="docutils literal notranslate"><span class="pre">AttributeExtension</span></code> provided a system of replacing incoming values, and <code class="docutils literal notranslate"><span class="pre">DDL</span></code> 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 <code class="docutils literal notranslate"><span class="pre">MapperExtension</span></code>, <code class="docutils literal notranslate"><span class="pre">SessionExtension</span></code>, <code class="docutils literal notranslate"><span class="pre">AttributeExtension</span></code>, <code class="docutils literal notranslate"><span class="pre">ConnectionProxy</span></code>, <code class="docutils literal notranslate"><span class="pre">PoolListener</span></code> as well as the <code class="docutils literal notranslate"><span class="pre">DDLElement.execute_at</span></code> 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’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 <code class="docutils literal notranslate"><span class="pre">Session</span></code> or <code class="docutils literal notranslate"><span class="pre">Engine</span></code> objects, with specific instances of API classes, such as for a specific <code class="docutils literal notranslate"><span class="pre">Pool</span></code> or <code class="docutils literal notranslate"><span class="pre">Mapper</span></code>, as well as for related objects like a user- defined class that’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 <code class="docutils literal notranslate"><span class="pre">InstanceState</span></code> 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 “mutable attributes” 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="admonition-title">See also</p> <p><a class="reference internal" href="../core/event.html"><span class="std std-ref">Events</span></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 “derived attributes” example has now been turned into an official extension. The typical use case for <code class="docutils literal notranslate"><span class="pre">synonym()</span></code> is to provide descriptor access to a mapped column; the use case for <code class="docutils literal notranslate"><span class="pre">comparable_property()</span></code> is to be able to return a <code class="docutils literal notranslate"><span class="pre">PropComparator</span></code> from any descriptor. In practice, the approach of “derived” is easier to use, more extensible, is implemented in a few dozen lines of pure Python with almost no imports, and doesn’t require the ORM core to even be aware of it. The feature is now known as the “Hybrid Attributes” extension.</p> <p><code class="docutils literal notranslate"><span class="pre">synonym()</span></code> and <code class="docutils literal notranslate"><span class="pre">comparable_property()</span></code> 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’t really aware of them otherwise.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p><a class="reference internal" href="../orm/extensions/hybrid.html"><span class="std std-ref">Hybrid Attributes</span></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><p>The flush process will now bundle INSERT statements into batches fed to <code class="docutils literal notranslate"><span class="pre">cursor.executemany()</span></code>, for rows where the primary key is already present. In particular this usually applies to the “child” table on a joined table inheritance configuration, meaning the number of calls to <code class="docutils literal notranslate"><span class="pre">cursor.execute</span></code> 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 <code class="docutils literal notranslate"><span class="pre">cursor.executemany()</span></code> (such as re-using a prepared statement).</p></li> <li><p>The codepath invoked when accessing a many-to-one reference to a related object that’s already loaded has been greatly simplified. The identity map is checked directly without the need to generate a new <code class="docutils literal notranslate"><span class="pre">Query</span></code> object first, which is expensive in the context of thousands of in-memory many-to-ones being accessed. The usage of constructed-per-call “loader” objects is also no longer used for the majority of lazy attribute loads.</p></li> <li><p>The rewrite of composites allows a shorter codepath when mapper internals access mapped attributes within a flush.</p></li> <li><p>New inlined attribute access functions replace the previous usage of “history” when the “save-update” 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 <code class="docutils literal notranslate"><span class="pre">History</span></code> object for this speed-critical operation.</p></li> <li><p>The internals of the <code class="docutils literal notranslate"><span class="pre">ExecutionContext</span></code>, the object corresponding to a statement execution, have been inlined and simplified.</p></li> <li><p>The <code class="docutils literal notranslate"><span class="pre">bind_processor()</span></code> and <code class="docutils literal notranslate"><span class="pre">result_processor()</span></code> 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.</p></li> <li><p>The collection of “bind processors” for a particular <code class="docutils literal notranslate"><span class="pre">Compiled</span></code> instance of a statement is also cached on the <code class="docutils literal notranslate"><span class="pre">Compiled</span></code> object, taking further advantage of the “compiled cache” used by the flush process to re-use the same compiled form of INSERT, UPDATE, DELETE statements.</p></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 “composite” feature has been rewritten, like <code class="docutils literal notranslate"><span class="pre">synonym()</span></code> and <code class="docutils literal notranslate"><span class="pre">comparable_property()</span></code>, 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 <code class="docutils literal notranslate"><span class="pre">relationship()</span></code> as well as <code class="docutils literal notranslate"><span class="pre">Column()</span></code> attributes.</p> <p>The major backwards-incompatible change of composites is that they no longer use the <code class="docutils literal notranslate"><span class="pre">mutable=True</span></code> 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="admonition-title">See also</p> <p><a class="reference internal" href="../orm/composites.html#mapper-composite"><span class="std std-ref">Composite Column Types</span></a></p> <p><a class="reference internal" href="../orm/extensions/mutable.html"><span class="std std-ref">Mutation Tracking</span></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 <code class="docutils literal notranslate"><span class="pre">query.join()</span></code> to a target with an explicit onclause is now:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">join()</span></code> 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 “normal” way to do it. The “multiple JOIN” use case is exceedingly rare compared to the single join case, and multiple joins these days are more clearly represented by multiple calls to <code class="docutils literal notranslate"><span class="pre">join()</span></code>.</p> <p>The tuple form will remain for backwards compatibility.</p> <p>Note that all the other forms of <code class="docutils literal notranslate"><span class="pre">query.join()</span></code> remain unchanged:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s2">"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="n">MyTarget</span><span class="p">)</span> <span class="c1"># ... 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 “mutable=True”<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"><span class="std std-ref">Mutation Tracking</span></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/type_basics.html#sqlalchemy.types.PickleType" title="sqlalchemy.types.PickleType"><code class="xref py py-class docutils literal notranslate"><span class="pre">PickleType</span></code></a>, <code class="docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code>, or other custom <code class="docutils literal notranslate"><span class="pre">MutableType</span></code> classes, as well as an approach for ORM “composites”, those configured using <a class="reference internal" href="../orm/composites.html#sqlalchemy.orm.composite" title="sqlalchemy.orm.composite"><code class="xref py py-func docutils literal notranslate"><span class="pre">composite()</span></code></a>.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p><a class="reference internal" href="../orm/extensions/mutable.html"><span class="std std-ref">Mutation Tracking</span></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 <code class="docutils literal notranslate"><span class="pre">asc()</span></code> and <code class="docutils literal notranslate"><span class="pre">desc()</span></code> operators, called <code class="docutils literal notranslate"><span class="pre">nullsfirst()</span></code> and <code class="docutils literal notranslate"><span class="pre">nullslast()</span></code>.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p><a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.nullsfirst" title="sqlalchemy.sql.expression.nullsfirst"><code class="xref py py-func docutils literal notranslate"><span class="pre">nullsfirst()</span></code></a></p> <p><a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.nullslast" title="sqlalchemy.sql.expression.nullslast"><code class="xref py py-func docutils literal notranslate"><span class="pre">nullslast()</span></code></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 <code class="docutils literal notranslate"><span class="pre">distinct</span></code> keyword argument of <code class="docutils literal notranslate"><span class="pre">select()</span></code>, the <code class="docutils literal notranslate"><span class="pre">distinct()</span></code> method of <code class="docutils literal notranslate"><span class="pre">select()</span></code> and <code class="docutils literal notranslate"><span class="pre">Query</span></code> 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><code class="docutils literal notranslate"><span class="pre">Index()</span></code> can be placed inline inside of <code class="docutils literal notranslate"><span class="pre">Table</span></code>, <code class="docutils literal notranslate"><span class="pre">__table_args__</span></code><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-default notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="p">(</span><span class="s1">'mytable'</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="s1">'id'</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="kc">True</span><span class="p">),</span> <span class="n">Column</span><span class="p">(</span><span class="s1">'name'</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="kc">False</span><span class="p">),</span> <span class="n">Index</span><span class="p">(</span><span class="s1">'idx_name'</span><span class="p">,</span> <span class="s1">'name'</span><span class="p">)</span> <span class="p">)</span></pre></div> </div> <p>The primary rationale here is for the benefit of declarative <code class="docutils literal notranslate"><span class="pre">__table_args__</span></code>, particularly when used with mixins:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'name'</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="kc">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="bp">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="s1">'name'</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="s1">'user'</span> <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="s1">'id'</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="kc">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 “window function” provides to a statement information about the result set as it’s produced. This allows criteria against various things like “row number”, “rank” 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’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 <code class="docutils literal notranslate"><span class="pre">over()</span></code> method, which accepts <code class="docutils literal notranslate"><span class="pre">order_by</span></code> and <code class="docutils literal notranslate"><span class="pre">partition_by</span></code> keyword arguments. Below we replicate the first example in PG’s tutorial:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="k">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="s1">'empsalary'</span><span class="p">,</span> <span class="n">column</span><span class="p">(</span><span class="s1">'depname'</span><span class="p">),</span> <span class="n">column</span><span class="p">(</span><span class="s1">'empno'</span><span class="p">),</span> <span class="n">column</span><span class="p">(</span><span class="s1">'salary'</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="s1">'avg'</span><span class="p">)</span> <span class="p">])</span> <span class="nb">print</span><span class="p">(</span><span class="n">s</span><span class="p">)</span></pre></div> </div> <p>SQL:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">empsalary</span><span class="o">.</span><span class="n">depname</span><span class="p">,</span> <span class="n">empsalary</span><span class="o">.</span><span class="n">empno</span><span class="p">,</span> <span class="n">empsalary</span><span class="o">.</span><span class="n">salary</span><span class="p">,</span> <span class="n">avg</span><span class="p">(</span><span class="n">empsalary</span><span class="o">.</span><span class="n">salary</span><span class="p">)</span> <span class="n">OVER</span> <span class="p">(</span><span class="n">PARTITION</span> <span class="n">BY</span> <span class="n">empsalary</span><span class="o">.</span><span class="n">depname</span><span class="p">)</span> <span class="n">AS</span> <span class="n">avg</span> <span class="n">FROM</span> <span class="n">empsalary</span></pre></div> </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 “isolation_level” 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 <code class="docutils literal notranslate"><span class="pre">Connection</span></code>, until that <code class="docutils literal notranslate"><span class="pre">Connection</span></code> 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 <code class="docutils literal notranslate"><span class="pre">isolation_level</span></code> argument to <code class="docutils literal notranslate"><span class="pre">create_engine()</span></code>.</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><code class="docutils literal notranslate"><span class="pre">TypeDecorator</span></code> 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 <code class="docutils literal notranslate"><span class="pre">TypeDecorator</span></code> which extends the behavior of <code class="docutils literal notranslate"><span class="pre">Integer</span></code> can be used with a primary key column. The “autoincrement” feature of <code class="docutils literal notranslate"><span class="pre">Column</span></code> will now recognize that the underlying database column is still an integer so that lastrowid mechanisms continue to function. The <code class="docutils literal notranslate"><span class="pre">TypeDecorator</span></code> itself will have its result value processor applied to newly generated primary keys, including those received by the DBAPI <code class="docutils literal notranslate"><span class="pre">cursor.lastrowid</span></code> 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><code class="docutils literal notranslate"><span class="pre">TypeDecorator</span></code> is present in the “sqlalchemy” 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 <code class="docutils literal notranslate"><span class="pre">sqlalchemy.types</span></code>, it’s now mirrored in <code class="docutils literal notranslate"><span class="pre">sqlalchemy</span></code>.</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>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>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>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’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 <code class="docutils literal notranslate"><span class="pre">Query.count()</span></code> has been modernized to use <code class="docutils literal notranslate"><span class="pre">.from_self()</span></code>. That is, <code class="docutils literal notranslate"><span class="pre">query.count()</span></code> is now equivalent to:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'1'</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 “subquery” 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 <code class="docutils literal notranslate"><span class="pre">.from_self()</span></code> call.</p> <p>The SQL emitted by <code class="docutils literal notranslate"><span class="pre">query.count()</span></code> is now always of the form:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">count</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="n">AS</span> <span class="n">count_1</span> <span class="n">FROM</span> <span class="p">(</span> <span class="n">SELECT</span> <span class="n">user</span><span class="o">.</span><span class="n">id</span> <span class="n">AS</span> <span class="n">user_id</span><span class="p">,</span> <span class="n">user</span><span class="o">.</span><span class="n">name</span> <span class="n">AS</span> <span class="n">user_name</span> <span class="kn">from</span> <span class="nn">user</span> <span class="p">)</span> <span class="n">AS</span> <span class="n">anon_1</span></pre></div> </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 <code class="docutils literal notranslate"><span class="pre">count()</span></code> that optimizes for DBs that can’t handle simple subqueries, <code class="docutils literal notranslate"><span class="pre">func.count()</span></code> should be used:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">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 <code class="docutils literal notranslate"><span class="pre">count(*)</span></code>:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">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="s1">'*'</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 “hex string” embedded in logging statements for engines and pools is no longer needed to allow the <code class="docutils literal notranslate"><span class="pre">echo</span></code> flag to work correctly. A new system that uses filtered logging objects allows us to maintain our current behavior of <code class="docutils literal notranslate"><span class="pre">echo</span></code> 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 <code class="docutils literal notranslate"><span class="pre">polymorphic_on</span></code> column-mapped attribute, when used in an inheritance scenario, now occurs when the object is constructed, i.e. its <code class="docutils literal notranslate"><span class="pre">__init__</span></code> 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. “all()”)<a class="headerlink" href="#contains-eager-chains-across-multiple-paths-i-e-all" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">`contains_eager()``</span></code> modifier now will chain itself for a longer path without the need to emit individual <code class="docutils literal notranslate"><span class="pre">``contains_eager()`</span></code> calls. Instead of:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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-default notranslate"><div class="highlight"><pre><span></span><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’ve had a long standing behavior that checks for a so- called “orphan” during flush, that is, an object which is associated with a <code class="docutils literal notranslate"><span class="pre">relationship()</span></code> that specifies “delete- orphan” 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 “orphan check” is accomplished by making the foreign key reference to the object’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’s parent foreign key is nullable, then the row can be inserted. The “orphan” 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 <code class="docutils literal notranslate"><span class="pre">relationship()</span></code> on a parent object marked as “dirty” are not present in the current <code class="docutils literal notranslate"><span class="pre">Session</span></code>.</p> <p>The <code class="docutils literal notranslate"><span class="pre">save-update</span></code> cascade takes effect when objects are added to the <code class="docutils literal notranslate"><span class="pre">Session</span></code>, 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 <code class="docutils literal notranslate"><span class="pre">Session</span></code>. However, if <code class="docutils literal notranslate"><span class="pre">save-update</span></code> cascade is disabled for a particular <code class="docutils literal notranslate"><span class="pre">relationship()</span></code>, 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’ve used a plugin that installs via setuptools, so that the <code class="docutils literal notranslate"><span class="pre">nosetests</span></code> script would automatically run SQLA’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’s “coverage” plugin would break, since “coverage” 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 <code class="docutils literal notranslate"><span class="pre">sqlalchemy-nose</span></code> package to the build to overcome this.</p> <p>In 0.7 we’ve done away with trying to get <code class="docutils literal notranslate"><span class="pre">nosetests</span></code> to work automatically, since the SQLAlchemy module would produce a large number of nose configuration options for all usages of <code class="docutils literal notranslate"><span class="pre">nosetests</span></code>, not just the SQLAlchemy unit tests themselves, and the additional <code class="docutils literal notranslate"><span class="pre">sqlalchemy-nose</span></code> install was an even worse idea, producing an extra package in Python environments. The <code class="docutils literal notranslate"><span class="pre">sqla_nose.py</span></code> 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-<code class="docutils literal notranslate"><span class="pre">Table</span></code>-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’t against any <code class="docutils literal notranslate"><span class="pre">Table</span></code> at all, like a function, can be mapped.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">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="k">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="s2">"x"</span><span class="p">,</span> <span class="s2">"y"</span><span class="p">,</span> <span class="s2">"z"</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 <code class="docutils literal notranslate"><span class="pre">FromClause</span></code> 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 <code class="docutils literal notranslate"><span class="pre">FromClause</span></code>, such as a <code class="docutils literal notranslate"><span class="pre">select</span></code>, <code class="docutils literal notranslate"><span class="pre">Table</span></code> or <code class="docutils literal notranslate"><span class="pre">join</span></code> is passed to the <code class="docutils literal notranslate"><span class="pre">orm.aliased()</span></code> construct, it passes through to the <code class="docutils literal notranslate"><span class="pre">.alias()</span></code> method of that from construct rather than constructing an ORM level <code class="docutils literal notranslate"><span class="pre">AliasedClass</span></code>.</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 ‘bind’<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 <code class="docutils literal notranslate"><span class="pre">Session</span></code> that implement their own <code class="docutils literal notranslate"><span class="pre">get_bind()</span></code> method and arguments to use those custom arguments with both the <code class="docutils literal notranslate"><span class="pre">execute()</span></code> and <code class="docutils literal notranslate"><span class="pre">connection()</span></code> 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 “columns clause” of a select are now auto-labeled like other “anonymous” clauses, which among other things allows their “type” 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 - <code class="docutils literal notranslate"><span class="pre">String</span></code>/<code class="docutils literal notranslate"><span class="pre">Unicode</span></code>/<code class="docutils literal notranslate"><span class="pre">VARCHAR</span></code>/<code class="docutils literal notranslate"><span class="pre">NVARCHAR</span></code>/<code class="docutils literal notranslate"><span class="pre">VARBINARY</span></code> emit “max” 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 “max” as the length when no length is specified. This makes it more compatible with PostgreSQL’s VARCHAR type which is similarly unbounded when no length specified. SQL Server defaults the length on these types to ‘1’ 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><code class="docutils literal notranslate"><span class="pre">PickleType</span></code> 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 <code class="docutils literal notranslate"><span class="pre">PickleType</span></code> or <code class="docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code> datatypes. The <code class="docutils literal notranslate"><span class="pre">mutable</span></code> flag is now set to <code class="docutils literal notranslate"><span class="pre">False</span></code> by default. If an existing application uses these types and depends upon detection of in-place mutations, the type object must be constructed with <code class="docutils literal notranslate"><span class="pre">mutable=True</span></code> to restore the 0.6 behavior:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="p">(</span><span class="s1">'mytable'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="c1"># ....</span> <span class="n">Column</span><span class="p">(</span><span class="s1">'pickled_data'</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="kc">True</span><span class="p">))</span> <span class="p">)</span></pre></div> </div> <p>The <code class="docutils literal notranslate"><span class="pre">mutable=True</span></code> 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 <code class="docutils literal notranslate"><span class="pre">mutable=True</span></code> 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 <code class="docutils literal notranslate"><span class="pre">flush()</span></code> is called, which is a very time consuming event. This is a holdover from the very early days of SQLAlchemy when <code class="docutils literal notranslate"><span class="pre">flush()</span></code> was not automatic and the history tracking system was not nearly as sophisticated as it is now.</p> <p>Existing applications which use <code class="docutils literal notranslate"><span class="pre">PickleType</span></code>, <code class="docutils literal notranslate"><span class="pre">postgresql.ARRAY</span></code> or other <code class="docutils literal notranslate"><span class="pre">MutableType</span></code> subclasses, and require in-place mutation detection, should migrate to the new mutation tracking system, as <code class="docutils literal notranslate"><span class="pre">mutable=True</span></code> 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 <code class="docutils literal notranslate"><span class="pre">composite()</span></code> 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 “composite” 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 “mutation tracking” 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 <code class="docutils literal notranslate"><span class="pre">NullPool</span></code> 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 <code class="docutils literal notranslate"><span class="pre">NullPool</span></code> means that each call to <code class="docutils literal notranslate"><span class="pre">Engine.connect</span></code> creates a new pysqlite connection.</p> <p>Previously, the <code class="docutils literal notranslate"><span class="pre">SingletonThreadPool</span></code> was used, which meant that all connections to a certain engine in a thread would be the same connection. It’s intended that the new approach is more intuitive, particularly when multiple connections are used.</p> <p><code class="docutils literal notranslate"><span class="pre">SingletonThreadPool</span></code> is still the default engine when a <code class="docutils literal notranslate"><span class="pre">:memory:</span></code> 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><code class="docutils literal notranslate"><span class="pre">Session.merge()</span></code> 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’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 <code class="docutils literal notranslate"><span class="pre">merge()</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Foo</span></code> and <code class="docutils literal notranslate"><span class="pre">Bar</span></code> each with a column <code class="docutils literal notranslate"><span class="pre">spam</span></code>:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">qu</span></code> will be <code class="docutils literal notranslate"><span class="pre">spam</span></code>. Previously it would be something like <code class="docutils literal notranslate"><span class="pre">foo_spam</span></code> due to the way the <code class="docutils literal notranslate"><span class="pre">union</span></code> would combine things, which is inconsistent with the name <code class="docutils literal notranslate"><span class="pre">spam</span></code> 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-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Parent</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="s1">'parent'</span> <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</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="kc">True</span><span class="p">)</span> <span class="k">class</span> <span class="nc">Child</span><span class="p">(</span><span class="n">Parent</span><span class="p">):</span> <span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'child'</span> <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s1">'parent.id'</span><span class="p">),</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span></pre></div> </div> <p>Above, the attribute <code class="docutils literal notranslate"><span class="pre">Child.id</span></code> refers to both the <code class="docutils literal notranslate"><span class="pre">child.id</span></code> column as well as <code class="docutils literal notranslate"><span class="pre">parent.id</span></code> - this due to the name of the attribute. If it were named differently on the class, such as <code class="docutils literal notranslate"><span class="pre">Child.child_id</span></code>, it then maps distinctly to <code class="docutils literal notranslate"><span class="pre">child.id</span></code>, with <code class="docutils literal notranslate"><span class="pre">Child.id</span></code> being the same attribute as <code class="docutils literal notranslate"><span class="pre">Parent.id</span></code>.</p> <p>When the <code class="docutils literal notranslate"><span class="pre">id</span></code> attribute is made to reference both <code class="docutils literal notranslate"><span class="pre">parent.id</span></code> and <code class="docutils literal notranslate"><span class="pre">child.id</span></code>, it stores them in an ordered list. An expression such as <code class="docutils literal notranslate"><span class="pre">Child.id</span></code> then refers to just <em>one</em> of those columns when rendered. Up until 0.6, this column would be <code class="docutils literal notranslate"><span class="pre">parent.id</span></code>. In 0.7, it is the less surprising <code class="docutils literal notranslate"><span class="pre">child.id</span></code>.</p> <p>The legacy of this behavior deals with behaviors and restrictions of the ORM that don’t really apply anymore; all that was needed was to reverse the order.</p> <p>A primary advantage of this approach is that it’s now easier to construct <code class="docutils literal notranslate"><span class="pre">primaryjoin</span></code> expressions that refer to the local column:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Child</span><span class="p">(</span><span class="n">Parent</span><span class="p">):</span> <span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'child'</span> <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s1">'parent.id'</span><span class="p">),</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="n">some_related</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s2">"SomeRelated"</span><span class="p">,</span> <span class="n">primaryjoin</span><span class="o">=</span><span class="s2">"Child.id==SomeRelated.child_id"</span><span class="p">)</span> <span class="k">class</span> <span class="nc">SomeRelated</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="s1">'some_related'</span> <span class="nb">id</span> <span class="o">=</span> <span class="n">Column</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="kc">True</span><span class="p">)</span> <span class="n">child_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s1">'child.id'</span><span class="p">))</span></pre></div> </div> <p>Prior to 0.7 the <code class="docutils literal notranslate"><span class="pre">Child.id</span></code> expression would reference <code class="docutils literal notranslate"><span class="pre">Parent.id</span></code>, and it would be necessary to map <code class="docutils literal notranslate"><span class="pre">child.id</span></code> to a distinct attribute.</p> <p>It also means that a query like this one changes its behavior:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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">></span> <span class="mi">7</span><span class="p">)</span></pre></div> </div> <p>In 0.6, this would render:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">parent</span><span class="o">.</span><span class="n">id</span> <span class="n">AS</span> <span class="n">parent_id</span> <span class="n">FROM</span> <span class="n">parent</span> <span class="n">WHERE</span> <span class="n">parent</span><span class="o">.</span><span class="n">id</span> <span class="o">></span> <span class="p">:</span><span class="n">id_1</span></pre></div> </div> <p>in 0.7, you get:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">parent</span><span class="o">.</span><span class="n">id</span> <span class="n">AS</span> <span class="n">parent_id</span> <span class="n">FROM</span> <span class="n">parent</span><span class="p">,</span> <span class="n">child</span> <span class="n">WHERE</span> <span class="n">child</span><span class="o">.</span><span class="n">id</span> <span class="o">></span> <span class="p">:</span><span class="n">id_1</span></pre></div> </div> <p>which you’ll note is a cartesian product - this behavior is now equivalent to that of any other attribute that is local to <code class="docutils literal notranslate"><span class="pre">Child</span></code>. The <code class="docutils literal notranslate"><span class="pre">with_polymorphic()</span></code> method, or a similar strategy of explicitly joining the underlying <code class="docutils literal notranslate"><span class="pre">Table</span></code> objects, is used to render a query against all <code class="docutils literal notranslate"><span class="pre">Parent</span></code> objects with criteria against <code class="docutils literal notranslate"><span class="pre">Child</span></code>, in the same manner as that of 0.5 and 0.6:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</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">></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-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">parent</span><span class="o">.</span><span class="n">id</span> <span class="n">AS</span> <span class="n">parent_id</span><span class="p">,</span> <span class="n">child</span><span class="o">.</span><span class="n">id</span> <span class="n">AS</span> <span class="n">child_id</span> <span class="n">FROM</span> <span class="n">parent</span> <span class="n">LEFT</span> <span class="n">OUTER</span> <span class="n">JOIN</span> <span class="n">child</span> <span class="n">ON</span> <span class="n">parent</span><span class="o">.</span><span class="n">id</span> <span class="o">=</span> <span class="n">child</span><span class="o">.</span><span class="n">id</span> <span class="n">WHERE</span> <span class="n">child</span><span class="o">.</span><span class="n">id</span> <span class="o">></span> <span class="p">:</span><span class="n">id_1</span></pre></div> </div> <p>Another effect of this change is that a joined-inheritance load across two tables will populate from the child table’s value, not that of the parent table. An unusual case is that a query against “Parent” using <code class="docutils literal notranslate"><span class="pre">with_polymorphic="*"</span></code> issues a query against “parent”, with a LEFT OUTER JOIN to “child”. The row is located in “Parent”, sees the polymorphic identity corresponds to “Child”, but suppose the actual row in “child” has been <em>deleted</em>. Due to this corruption, the row comes in with all the columns corresponding to “child” 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 <code class="docutils literal notranslate"><span class="pre">foo</span></code> and <code class="docutils literal notranslate"><span class="pre">bar</span></code>, each with a primary key column <code class="docutils literal notranslate"><span class="pre">id</span></code>, the following now produces an error:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">mapper()</span></code> refuses to guess what column is the primary representation of <code class="docutils literal notranslate"><span class="pre">FooBar.id</span></code> - is it <code class="docutils literal notranslate"><span class="pre">foo.c.id</span></code> or is it <code class="docutils literal notranslate"><span class="pre">bar.c.id</span></code> ? The attribute must be explicit:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'id'</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 <code class="docutils literal notranslate"><span class="pre">polymorphic_on</span></code> must be in the mapped selectable. This to prevent some occasional user errors such as:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">sometable</span></code> column, in this case perhaps <code class="docutils literal notranslate"><span class="pre">sometable.c.some_lookup_id</span></code>. There are also some “polymorphic union” scenarios where similar mistakes sometimes occur.</p> <p>Such a configuration error has always been “wrong”, and the above mapping doesn’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><code class="docutils literal notranslate"><span class="pre">DDL()</span></code> 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 <code class="docutils literal notranslate"><span class="pre">DDL()</span></code> strings would have to be escaped, i.e. <code class="docutils literal notranslate"><span class="pre">%%</span></code> depending on DBAPI, for those DBAPIs that accept <code class="docutils literal notranslate"><span class="pre">pyformat</span></code> or <code class="docutils literal notranslate"><span class="pre">format</span></code> binds (i.e. psycopg2, mysql-python), which was inconsistent versus <code class="docutils literal notranslate"><span class="pre">text()</span></code> constructs which did this automatically. The same escaping now occurs for <code class="docutils literal notranslate"><span class="pre">DDL()</span></code> as for <code class="docutils literal notranslate"><span class="pre">text()</span></code>.</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><code class="docutils literal notranslate"><span class="pre">Table.c</span></code> / <code class="docutils literal notranslate"><span class="pre">MetaData.tables</span></code> refined a bit, don’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’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 <code class="docutils literal notranslate"><span class="pre">.c</span></code> attribute on <code class="docutils literal notranslate"><span class="pre">Table</span></code> and the <code class="docutils literal notranslate"><span class="pre">.tables</span></code> attribute on <code class="docutils literal notranslate"><span class="pre">MetaData</span></code> is explicitly non-mutable. The “mutable” version of the construct is now private. Adding columns to <code class="docutils literal notranslate"><span class="pre">.c</span></code> involves using the <code class="docutils literal notranslate"><span class="pre">append_column()</span></code> method of <code class="docutils literal notranslate"><span class="pre">Table</span></code>, which ensures things are associated with the parent <code class="docutils literal notranslate"><span class="pre">Table</span></code> in the appropriate way; similarly, <code class="docutils literal notranslate"><span class="pre">MetaData.tables</span></code> has a contract with the <code class="docutils literal notranslate"><span class="pre">Table</span></code> objects stored in this dictionary, as well as a little bit of new bookkeeping in that a <code class="docutils literal notranslate"><span class="pre">set()</span></code> of all schema names is tracked, which is satisfied only by using the public <code class="docutils literal notranslate"><span class="pre">Table</span></code> constructor as well as <code class="docutils literal notranslate"><span class="pre">Table.tometadata()</span></code>.</p> <p>It is of course possible that the <code class="docutils literal notranslate"><span class="pre">ColumnCollection</span></code> and <code class="docutils literal notranslate"><span class="pre">dict</span></code> 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’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 “default” instead of server_default.</p> <p>Regarding reflection for this case, reflection of an int PK col with a server_default sets the “autoincrement” 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 <code class="docutils literal notranslate"><span class="pre">sqlalchemy.exceptions</span></code> 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’ve added the string <code class="docutils literal notranslate"><span class="pre">sqlalchemy.exceptions</span></code> to <code class="docutils literal notranslate"><span class="pre">sys.modules</span></code>, so that a statement like “<code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">sqlalchemy.exceptions</span></code>” would work. The name of the core exceptions module has been <code class="docutils literal notranslate"><span class="pre">exc</span></code> for a long time now, so the recommended import for this module is:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">exc</span></pre></div> </div> <p>The <code class="docutils literal notranslate"><span class="pre">exceptions</span></code> name is still present in “<code class="docutils literal notranslate"><span class="pre">sqlalchemy</span></code>” for applications which might have said <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">sqlalchemy</span> <span class="pre">import</span> <span class="pre">exceptions</span></code>, but they should also start using the <code class="docutils literal notranslate"><span class="pre">exc</span></code> 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’s worth mentioning that the rework of the <code class="docutils literal notranslate"><span class="pre">ConnectionProxy</span></code> into the new event system means it is no longer appropriate for the “Timing all Queries” recipe. Please adjust query-timers to use the <code class="docutils literal notranslate"><span class="pre">before_cursor_execute()</span></code> and <code class="docutils literal notranslate"><span class="pre">after_cursor_execute()</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Integer</span></code>, <code class="docutils literal notranslate"><span class="pre">Date</span></code> etc. in the core types module don’t accept arguments. The default constructor that accepts/ignores a catchall <code class="docutils literal notranslate"><span class="pre">\*args,</span> <span class="pre">\**kwargs</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Integer</span></code>, it may be that you intended to use a dialect specific type, such as <code class="docutils literal notranslate"><span class="pre">sqlalchemy.dialects.mysql.INTEGER</span></code> which does accept a “display_width” 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’s more of a global “registry-” level function and poorly named, so we’ve fixed both by moving the implementation out of <code class="docutils literal notranslate"><span class="pre">Mapper</span></code> altogether and renaming it to <code class="docutils literal notranslate"><span class="pre">configure_mappers()</span></code>. It is of course normally not needed for an application to call <code class="docutils literal notranslate"><span class="pre">configure_mappers()</span></code> 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><code class="docutils literal notranslate"><span class="pre">PoolListener</span></code>, <code class="docutils literal notranslate"><span class="pre">ConnectionProxy</span></code>, <code class="docutils literal notranslate"><span class="pre">DDLElement.execute_at</span></code> are superseded by <code class="docutils literal notranslate"><span class="pre">event.listen()</span></code>, using the <code class="docutils literal notranslate"><span class="pre">PoolEvents</span></code>, <code class="docutils literal notranslate"><span class="pre">EngineEvents</span></code>, <code class="docutils literal notranslate"><span class="pre">DDLEvents</span></code> 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><code class="docutils literal notranslate"><span class="pre">MapperExtension</span></code>, <code class="docutils literal notranslate"><span class="pre">AttributeExtension</span></code>, <code class="docutils literal notranslate"><span class="pre">SessionExtension</span></code> are superseded by <code class="docutils literal notranslate"><span class="pre">event.listen()</span></code>, using the <code class="docutils literal notranslate"><span class="pre">MapperEvents</span></code>/<code class="docutils literal notranslate"><span class="pre">InstanceEvents</span></code>, <code class="docutils literal notranslate"><span class="pre">AttributeEvents</span></code>, <code class="docutils literal notranslate"><span class="pre">SessionEvents</span></code>, 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 ‘distinct’ 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-default notranslate"><div class="highlight"><pre><span></span><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="s1">'ALL'</span><span class="p">,</span> <span class="n">prefixes</span><span class="o">=</span><span class="p">[</span><span class="s1">'HIGH_PRIORITY'</span><span class="p">])</span></pre></div> </div> <p>The <code class="docutils literal notranslate"><span class="pre">prefixes</span></code> keyword or <code class="docutils literal notranslate"><span class="pre">prefix_with()</span></code> method should be used for non-standard or unusual prefixes:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'HIGH_PRIORITY'</span><span class="p">,</span> <span class="s1">'ALL'</span><span class="p">)</span></pre></div> </div> </div> <div class="section" id="useexisting-superseded-by-extend-existing-and-keep-existing"> <h3><code class="docutils literal notranslate"><span class="pre">useexisting</span></code> superseded by <code class="docutils literal notranslate"><span class="pre">extend_existing</span></code> and <code class="docutils literal notranslate"><span class="pre">keep_existing</span></code><a class="headerlink" href="#useexisting-superseded-by-extend-existing-and-keep-existing" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">useexisting</span></code> flag on Table has been superseded by a new pair of flags <code class="docutils literal notranslate"><span class="pre">keep_existing</span></code> and <code class="docutils literal notranslate"><span class="pre">extend_existing</span></code>. <code class="docutils literal notranslate"><span class="pre">extend_existing</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">useexisting</span></code> - the existing Table is returned, and additional constructor elements are added. With <code class="docutils literal notranslate"><span class="pre">keep_existing</span></code>, 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 <code class="docutils literal notranslate"><span class="pre">bindparam()</span></code> don’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 <code class="docutils literal notranslate"><span class="pre">_params_from_query()</span></code> function needed a slight adjustment. If you’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 <code class="docutils literal notranslate"><span class="pre">sqlalchemy.types</span></code> as a shortcut to associating Python types with SQL types. We can’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’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 <code class="docutils literal notranslate"><span class="pre">alias</span></code> keyword arg of standalone <code class="docutils literal notranslate"><span class="pre">alias()</span></code> function to <code class="docutils literal notranslate"><span class="pre">name</span></code><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 <code class="docutils literal notranslate"><span class="pre">name</span></code> matches that of the <code class="docutils literal notranslate"><span class="pre">alias()</span></code> methods on all <code class="docutils literal notranslate"><span class="pre">FromClause</span></code> objects as well as the <code class="docutils literal notranslate"><span class="pre">name</span></code> argument on <code class="docutils literal notranslate"><span class="pre">Query.subquery()</span></code>.</p> <p>Only code that uses the standalone <code class="docutils literal notranslate"><span class="pre">alias()</span></code> function, and not the method bound functions, and passes the alias name using the explicit keyword name <code class="docutils literal notranslate"><span class="pre">alias</span></code>, and not positionally, would need modification here.</p> </div> <div class="section" id="non-public-pool-methods-underscored"> <h3>Non-public <code class="docutils literal notranslate"><span class="pre">Pool</span></code> methods underscored<a class="headerlink" href="#non-public-pool-methods-underscored" title="Permalink to this headline">¶</a></h3> <p>All methods of <code class="docutils literal notranslate"><span class="pre">Pool</span></code> 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><code class="docutils literal notranslate"><span class="pre">Pool.create_connection()</span></code> -> <code class="docutils literal notranslate"><span class="pre">Pool._create_connection()</span></code></p> <p><code class="docutils literal notranslate"><span class="pre">Pool.do_get()</span></code> -> <code class="docutils literal notranslate"><span class="pre">Pool._do_get()</span></code></p> <p><code class="docutils literal notranslate"><span class="pre">Pool.do_return_conn()</span></code> -> <code class="docutils literal notranslate"><span class="pre">Pool._do_return_conn()</span></code></p> <p><code class="docutils literal notranslate"><span class="pre">Pool.do_return_invalid()</span></code> -> removed, was not used</p> <p><code class="docutils literal notranslate"><span class="pre">Pool.return_conn()</span></code> -> <code class="docutils literal notranslate"><span class="pre">Pool._return_conn()</span></code></p> <p><code class="docutils literal notranslate"><span class="pre">Pool.get()</span></code> -> <code class="docutils literal notranslate"><span class="pre">Pool._get()</span></code>, public API is <code class="docutils literal notranslate"><span class="pre">Pool.connect()</span></code></p> <p><code class="docutils literal notranslate"><span class="pre">SingletonThreadPool.cleanup()</span></code> -> <code class="docutils literal notranslate"><span class="pre">_cleanup()</span></code></p> <p><code class="docutils literal notranslate"><span class="pre">SingletonThreadPool.dispose_local()</span></code> -> removed, use <code class="docutils literal notranslate"><span class="pre">conn.invalidate()</span></code></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 <code class="docutils literal notranslate"><span class="pre">Query.join</span></code>, <code class="docutils literal notranslate"><span class="pre">eagerload()</span></code>, and similar has been deprecated since 0.5:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># 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-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># 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><code class="docutils literal notranslate"><span class="pre">ScopedSession.mapper</span></code> 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 <code class="docutils literal notranslate"><span class="pre">ScopedSession</span></code>, 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, withsidebar"> Previous: <a href="migration_08.html" title="previous chapter">What’s New in SQLAlchemy 0.8?</a> Next: <a href="migration_06.html" title="next chapter">What’s New in SQLAlchemy 0.6?</a> <div id="docs-copyright"> © <a href="../copyright.html">Copyright</a> 2007-2019, the SQLAlchemy authors and contributors. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1. </div> </div> </div> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../', VERSION: '1.2.19', COLLAPSE_MODINDEX: false, FILE_SUFFIX: '.html' }; </script> <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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> <script type="text/javascript" src="../_static/language_data.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> </body> </html>