<!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.5?
—
SQLAlchemy 0.8 Documentation
</title>
<!-- begin iterate through SQLA + sphinx environment css_files -->
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/docs.css" type="text/css" />
<link rel="stylesheet" href="../_static/changelog.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" />
<!-- end iterate through SQLA + sphinx environment css_files -->
<!-- begin layout.mako headers -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.8.7',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<!-- begin iterate through sphinx environment script_files -->
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<!-- end iterate through sphinx environment script_files -->
<script type="text/javascript" src="../_static/detectmobile.js"></script>
<script type="text/javascript" src="../_static/init.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="SQLAlchemy 0.8 Documentation" href="../index.html" />
<link rel="up" title="Changes and Migration" href="index.html" />
<link rel="next" title="What’s new in SQLAlchemy 0.4?" href="migration_04.html" />
<link rel="prev" title="What’s New in SQLAlchemy 0.6?" href="migration_06.html" />
<!-- end layout.mako headers -->
</head>
<body>
<div id="docs-container">
<div id="docs-top-navigation-container" class="body-background">
<div id="docs-header">
<div id="docs-version-header">
Release: <span class="version-num">0.8.7</span> | Release Date: July 22, 2014
</div>
<h1>SQLAlchemy 0.8 Documentation</h1>
</div>
</div>
<div id="docs-body-container">
<div id="fixed-sidebar" class="withsidebar">
<div id="docs-sidebar-popout">
<h3><a href="../index.html">SQLAlchemy 0.8 Documentation</a></h3>
<p id="sidebar-paginate">
<a href="index.html" title="Changes and Migration">Up</a> |
<a href="migration_06.html" title="What’s New in SQLAlchemy 0.6?">Prev</a> |
<a href="migration_04.html" title="What’s new in SQLAlchemy 0.4?">Next</a>
</p>
<p id="sidebar-topnav">
<a href="../index.html">Contents</a> |
<a href="../genindex.html">Index</a>
</p>
<div id="sidebar-search">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="12" /> <input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div id="docs-sidebar">
<h3><a href="#">
What’s new in SQLAlchemy 0.5?
</a></h3>
<ul>
<li><a class="reference internal" href="#">What’s new in SQLAlchemy 0.5?</a><ul>
<li><a class="reference internal" href="#major-documentation-changes">Major Documentation Changes</a></li>
<li><a class="reference internal" href="#deprecations-source">Deprecations Source</a></li>
<li><a class="reference internal" href="#requirements-changes">Requirements Changes</a></li>
<li><a class="reference internal" href="#object-relational-mapping">Object Relational Mapping</a></li>
<li><a class="reference internal" href="#extending-the-orm">Extending the ORM</a></li>
<li><a class="reference internal" href="#schema-types">Schema/Types</a></li>
<li><a class="reference internal" href="#connection-pool-no-longer-threadlocal-by-default">Connection Pool no longer threadlocal by default</a></li>
<li><a class="reference internal" href="#args-accepted-args-no-longer-accepted">*args Accepted, *args No Longer Accepted</a></li>
<li><a class="reference internal" href="#removed">Removed</a></li>
<li><a class="reference internal" href="#renamed-or-moved">Renamed or Moved</a></li>
<li><a class="reference internal" href="#deprecated">Deprecated</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="docs-body" class="withsidebar" >
<div class="section" id="what-s-new-in-sqlalchemy-0-5">
<h1>What’s new in SQLAlchemy 0.5?<a class="headerlink" href="#what-s-new-in-sqlalchemy-0-5" title="Permalink to this headline">¶</a></h1>
<div class="admonition-about-this-document admonition">
<p class="first admonition-title">About this Document</p>
<p>This document describes changes between SQLAlchemy version 0.4,
last released October 12, 2008, and SQLAlchemy version 0.5,
last released January 16, 2010.</p>
<p class="last">Document date: August 4, 2009</p>
</div>
<p>This guide documents API changes which affect users
migrating their applications from the 0.4 series of
SQLAlchemy to 0.5. It’s also recommended for those working
from <a class="reference external" href="http://oreilly.com/catalog/9780596516147/">Essential SQLAlchemy</a>, which only
covers 0.4 and seems to even have some old 0.3isms in it.
Note that SQLAlchemy 0.5 removes many behaviors which were
deprecated throughout the span of the 0.4 series, and also
deprecates more behaviors specific to 0.4.</p>
<div class="section" id="major-documentation-changes">
<h2>Major Documentation Changes<a class="headerlink" href="#major-documentation-changes" title="Permalink to this headline">¶</a></h2>
<p>Some sections of the documentation have been completely
rewritten and can serve as an introduction to new ORM
features. The <tt class="docutils literal"><span class="pre">Query</span></tt> and <tt class="docutils literal"><span class="pre">Session</span></tt> objects in
particular have some distinct differences in API and
behavior which fundamentally change many of the basic ways
things are done, particularly with regards to constructing
highly customized ORM queries and dealing with stale session
state, commits and rollbacks.</p>
<ul class="simple">
<li><a class="reference external" href="http://www.sqlalchemy.org/docs/05/ormtutorial.html">ORM Tutorial</a></li>
<li><a class="reference external" href="http://www.sqlalchemy.org/docs/05/session.html">Session Documentation</a></li>
</ul>
</div>
<div class="section" id="deprecations-source">
<h2>Deprecations Source<a class="headerlink" href="#deprecations-source" title="Permalink to this headline">¶</a></h2>
<p>Another source of information is documented within a series
of unit tests illustrating up to date usages of some common
<tt class="docutils literal"><span class="pre">Query</span></tt> patterns; this file can be viewed at
[source:sqlalchemy/trunk/test/orm/test_deprecations.py].</p>
</div>
<div class="section" id="requirements-changes">
<h2>Requirements Changes<a class="headerlink" href="#requirements-changes" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>Python 2.4 or higher is required. The SQLAlchemy 0.4 line
is the last version with Python 2.3 support.</li>
</ul>
</div>
<div class="section" id="object-relational-mapping">
<h2>Object Relational Mapping<a class="headerlink" href="#object-relational-mapping" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first"><strong>Column level expressions within Query.</strong> - as detailed
in the <a class="reference external" href="http://www.sqlalchemy.org/docs/05/ormtutorial.html">tutorial</a>,
<tt class="docutils literal"><span class="pre">Query</span></tt> has the capability to create specific SELECT
statements, not just those against full rows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</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">Address</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span><span class="n">label</span><span class="p">(</span><span class="s">"numaddresses"</span><span class="p">))</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">Address</span><span class="p">)</span><span class="o">.</span><span class="n">group_by</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="p">)</span></pre></div>
</div>
<p>The tuples returned by any multi-column/entity query are
<em>named</em>‘ tuples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</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">Address</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span><span class="n">label</span><span class="p">(</span><span class="s">'numaddresses'</span><span class="p">))</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">Address</span><span class="p">)</span><span class="o">.</span><span class="n">group_by</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="p">):</span>
<span class="k">print</span> <span class="s">"name"</span><span class="p">,</span> <span class="n">row</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="s">"number"</span><span class="p">,</span> <span class="n">row</span><span class="o">.</span><span class="n">numaddresses</span></pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">Query</span></tt> has a <tt class="docutils literal"><span class="pre">statement</span></tt> accessor, as well as a
<tt class="docutils literal"><span class="pre">subquery()</span></tt> method which allow <tt class="docutils literal"><span class="pre">Query</span></tt> to be used to
create more complex combinations:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">subq</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">Keyword</span><span class="o">.</span><span class="n">id</span><span class="o">.</span><span class="n">label</span><span class="p">(</span><span class="s">'keyword_id'</span><span class="p">))</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">Keyword</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">in_</span><span class="p">([</span><span class="s">'beans'</span><span class="p">,</span> <span class="s">'carrots'</span><span class="p">]))</span><span class="o">.</span><span class="n">subquery</span><span class="p">()</span>
<span class="n">recipes</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">Recipe</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">exists</span><span class="p">()</span><span class="o">.</span>
<span class="n">where</span><span class="p">(</span><span class="n">Recipe</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="n">recipe_keywords</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">recipe_id</span><span class="p">)</span><span class="o">.</span>
<span class="n">where</span><span class="p">(</span><span class="n">recipe_keywords</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">keyword_id</span><span class="o">==</span><span class="n">subq</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">keyword_id</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
</li>
<li><p class="first"><strong>Explicit ORM aliases are recommended for aliased joins</strong>
- The <tt class="docutils literal"><span class="pre">aliased()</span></tt> function produces an “alias” of a
class, which allows fine-grained control of aliases in
conjunction with ORM queries. While a table-level alias
(i.e. <tt class="docutils literal"><span class="pre">table.alias()</span></tt>) is still usable, an ORM level
alias retains the semantics of the ORM mapped object which
is significant for inheritance mappings, options, and
other scenarios. E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Friend</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">Person</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">Person</span><span class="p">,</span> <span class="n">Friend</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">((</span><span class="n">Friend</span><span class="p">,</span> <span class="n">Person</span><span class="o">.</span><span class="n">friends</span><span class="p">))</span><span class="o">.</span><span class="n">all</span><span class="p">()</span></pre></div>
</div>
</li>
<li><p class="first"><strong>query.join() greatly enhanced.</strong> - You can now specify
the target and ON clause for a join in multiple ways. A
target class alone can be provided where SQLA will attempt
to form a join to it via foreign key in the same way as
<tt class="docutils literal"><span class="pre">table.join(someothertable)</span></tt>. A target and an explicit
ON condition can be provided, where the ON condition can
be a <tt class="docutils literal"><span class="pre">relation()</span></tt> name, an actual class descriptor, or a
SQL expression. Or the old way of just a <tt class="docutils literal"><span class="pre">relation()</span></tt>
name or class descriptor works too. See the ORM tutorial
which has several examples.</p>
</li>
<li><p class="first"><strong>Declarative is recommended for applications which don’t
require (and don’t prefer) abstraction between tables and
mappers</strong> - The [/docs/05/reference/ext/declarative.html
Declarative] module, which is used to combine the
expression of <tt class="docutils literal"><span class="pre">Table</span></tt>, <tt class="docutils literal"><span class="pre">mapper()</span></tt>, and user defined
class objects together, is highly recommended as it
simplifies application configuration, ensures the “one
mapper per class” pattern, and allows the full range of
configuration available to distinct <tt class="docutils literal"><span class="pre">mapper()</span></tt> calls.
Separate <tt class="docutils literal"><span class="pre">mapper()</span></tt> and <tt class="docutils literal"><span class="pre">Table</span></tt> usage is now referred
to as “classical SQLAlchemy usage” and of course is freely
mixable with declarative.</p>
</li>
<li><p class="first"><strong>The .c. attribute has been removed</strong> from classes (i.e.
<tt class="docutils literal"><span class="pre">MyClass.c.somecolumn</span></tt>). As is the case in 0.4, class-
level properties are usable as query elements, i.e.
<tt class="docutils literal"><span class="pre">Class.c.propname</span></tt> is now superseded by
<tt class="docutils literal"><span class="pre">Class.propname</span></tt>, and the <tt class="docutils literal"><span class="pre">c</span></tt> attribute continues to
remain on <tt class="docutils literal"><span class="pre">Table</span></tt> objects where they indicate the
namespace of <tt class="docutils literal"><span class="pre">Column</span></tt> objects present on the table.</p>
<p>To get at the Table for a mapped class (if you didn’t keep
it around already):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">table</span> <span class="o">=</span> <span class="n">class_mapper</span><span class="p">(</span><span class="n">someclass</span><span class="p">)</span><span class="o">.</span><span class="n">mapped_table</span></pre></div>
</div>
<p>Iterate through columns:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">col</span> <span class="ow">in</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="p">:</span>
<span class="k">print</span> <span class="n">col</span></pre></div>
</div>
<p>Work with a specific column:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">somecolumn</span></pre></div>
</div>
<p>The class-bound descriptors support the full set of Column
operators as well as the documented relation-oriented
operators like <tt class="docutils literal"><span class="pre">has()</span></tt>, <tt class="docutils literal"><span class="pre">any()</span></tt>, <tt class="docutils literal"><span class="pre">contains()</span></tt>, etc.</p>
<p>The reason for the hard removal of <tt class="docutils literal"><span class="pre">.c.</span></tt> is that in 0.5,
class-bound descriptors carry potentially different
meaning, as well as information regarding class mappings,
versus plain <tt class="docutils literal"><span class="pre">Column</span></tt> objects - and there are use cases
where you’d specifically want to use one or the other.
Generally, using class-bound descriptors invokes a set of
mapping/polymorphic aware translations, and using table-
bound columns does not. In 0.4, these translations were
applied across the board to all expressions, but 0.5
differentiates completely between columns and mapped
descriptors, only applying translations to the latter. So
in many cases, particularly when dealing with joined table
inheritance configurations as well as when using
<tt class="docutils literal"><span class="pre">query(<columns>)</span></tt>, <tt class="docutils literal"><span class="pre">Class.propname</span></tt> and
<tt class="docutils literal"><span class="pre">table.c.colname</span></tt> are not interchangeable.</p>
<p>For example, <tt class="docutils literal"><span class="pre">session.query(users.c.id,</span> <span class="pre">users.c.name)</span></tt>
is different versus <tt class="docutils literal"><span class="pre">session.query(User.id,</span> <span class="pre">User.name)</span></tt>;
in the latter case, the <tt class="docutils literal"><span class="pre">Query</span></tt> is aware of the mapper
in use and further mapper-specific operations like
<tt class="docutils literal"><span class="pre">query.join(<propname>)</span></tt>, <tt class="docutils literal"><span class="pre">query.with_parent()</span></tt> etc.
may be used, but in the former case cannot. Additionally,
in polymorphic inheritance scenarios, the class-bound
descriptors refer to the columns present in the
polymorphic selectable in use, not necessarily the table
column which directly corresponds to the descriptor. For
example, a set of classes related by joined-table
inheritance to the <tt class="docutils literal"><span class="pre">person</span></tt> table along the
<tt class="docutils literal"><span class="pre">person_id</span></tt> column of each table will all have their
<tt class="docutils literal"><span class="pre">Class.person_id</span></tt> attribute mapped to the <tt class="docutils literal"><span class="pre">person_id</span></tt>
column in <tt class="docutils literal"><span class="pre">person</span></tt>, and not their subclass table.
Version 0.4 would map this behavior onto table-bound
<tt class="docutils literal"><span class="pre">Column</span></tt> objects automatically. In 0.5, this automatic
conversion has been removed, so that you in fact <em>can</em> use
table-bound columns as a means to override the
translations which occur with polymorphic querying; this
allows <tt class="docutils literal"><span class="pre">Query</span></tt> to be able to create optimized selects
among joined-table or concrete-table inheritance setups,
as well as portable subqueries, etc.</p>
</li>
<li><p class="first"><strong>Session Now Synchronizes Automatically with
Transactions.</strong> Session now synchronizes against the
transaction automatically by default, including autoflush
and autoexpire. A transaction is present at all times
unless disabled using the <tt class="docutils literal"><span class="pre">autocommit</span></tt> option. When all
three flags are set to their default, the Session recovers
gracefully after rollbacks and it’s very difficult to get
stale data into the session. See the new Session
documentation for details.</p>
</li>
<li><p class="first"><strong>Implicit Order By Is Removed</strong>. This will impact ORM
users who rely upon SA’s “implicit ordering” behavior,
which states that all Query objects which don’t have an
<tt class="docutils literal"><span class="pre">order_by()</span></tt> will ORDER BY the “id” or “oid” column of
the primary mapped table, and all lazy/eagerly loaded
collections apply a similar ordering. In 0.5, automatic
ordering must be explicitly configured on <tt class="docutils literal"><span class="pre">mapper()</span></tt> and
<tt class="docutils literal"><span class="pre">relation()</span></tt> objects (if desired), or otherwise when
using <tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
<p>To convert an 0.4 mapping to 0.5, such that its ordering
behavior will be extremely similar to 0.4 or previous, use
the <tt class="docutils literal"><span class="pre">order_by</span></tt> setting on <tt class="docutils literal"><span class="pre">mapper()</span></tt> and
<tt class="docutils literal"><span class="pre">relation()</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">mapper</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">users</span><span class="p">,</span> <span class="n">properties</span><span class="o">=</span><span class="p">{</span>
<span class="s">'addresses'</span><span class="p">:</span><span class="n">relation</span><span class="p">(</span><span class="n">Address</span><span class="p">,</span> <span class="n">order_by</span><span class="o">=</span><span class="n">addresses</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> <span class="n">order_by</span><span class="o">=</span><span class="n">users</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>To set ordering on a backref, use the <tt class="docutils literal"><span class="pre">backref()</span></tt>
function:</p>
<div class="highlight-python"><pre>'keywords':relation(Keyword, secondary=item_keywords,
order_by=keywords.c.name, backref=backref('items', order_by=items.c.id))</pre>
</div>
<p>Using declarative ? To help with the new <tt class="docutils literal"><span class="pre">order_by</span></tt>
requirement, <tt class="docutils literal"><span class="pre">order_by</span></tt> and friends can now be set using
strings which are evaluated in Python later on (this works
<strong>only</strong> with declarative, not plain mappers):</p>
<div class="highlight-python"><pre>class MyClass(MyDeclarativeBase):
...
'addresses':relation("Address", order_by="Address.id")</pre>
</div>
<p>It’s generally a good idea to set <tt class="docutils literal"><span class="pre">order_by</span></tt> on
<tt class="docutils literal"><span class="pre">relation()s</span></tt> which load list-based collections of
items, since that ordering cannot otherwise be affected.
Other than that, the best practice is to use
<tt class="docutils literal"><span class="pre">Query.order_by()</span></tt> to control ordering of the primary
entities being loaded.</p>
</li>
<li><p class="first"><strong>Session is now
autoflush=True/autoexpire=True/autocommit=False.</strong> - To
set it up, just call <tt class="docutils literal"><span class="pre">sessionmaker()</span></tt> with no arguments.
The name <tt class="docutils literal"><span class="pre">transactional=True</span></tt> is now
<tt class="docutils literal"><span class="pre">autocommit=False</span></tt>. Flushes occur upon each query
issued (disable with <tt class="docutils literal"><span class="pre">autoflush=False</span></tt>), within each
<tt class="docutils literal"><span class="pre">commit()</span></tt> (as always), and before each
<tt class="docutils literal"><span class="pre">begin_nested()</span></tt> (so rolling back to the SAVEPOINT is
meaningful). All objects are expired after each
<tt class="docutils literal"><span class="pre">commit()</span></tt> and after each <tt class="docutils literal"><span class="pre">rollback()</span></tt>. After
rollback, pending objects are expunged, deleted objects
move back to persistent. These defaults work together
very nicely and there’s really no more need for old
techniques like <tt class="docutils literal"><span class="pre">clear()</span></tt> (which is renamed to
<tt class="docutils literal"><span class="pre">expunge_all()</span></tt> as well).</p>
<p>P.S.: sessions are now reusable after a <tt class="docutils literal"><span class="pre">rollback()</span></tt>.
Scalar and collection attribute changes, adds and deletes
are all rolled back.</p>
</li>
<li><p class="first"><strong>session.add() replaces session.save(), session.update(),
session.save_or_update().</strong> - the
<tt class="docutils literal"><span class="pre">session.add(someitem)</span></tt> and <tt class="docutils literal"><span class="pre">session.add_all([list</span> <span class="pre">of</span>
<span class="pre">items])</span></tt> methods replace <tt class="docutils literal"><span class="pre">save()</span></tt>, <tt class="docutils literal"><span class="pre">update()</span></tt>, and
<tt class="docutils literal"><span class="pre">save_or_update()</span></tt>. Those methods will remain
deprecated throughout 0.5.</p>
</li>
<li><p class="first"><strong>backref configuration made less verbose.</strong> - The
<tt class="docutils literal"><span class="pre">backref()</span></tt> function now uses the <tt class="docutils literal"><span class="pre">primaryjoin</span></tt> and
<tt class="docutils literal"><span class="pre">secondaryjoin</span></tt> arguments of the forwards-facing
<tt class="docutils literal"><span class="pre">relation()</span></tt> when they are not explicitly stated. It’s
no longer necessary to specify
<tt class="docutils literal"><span class="pre">primaryjoin</span></tt>/<tt class="docutils literal"><span class="pre">secondaryjoin</span></tt> in both directions
separately.</p>
</li>
<li><p class="first"><strong>Simplified polymorphic options.</strong> - The ORM’s
“polymorphic load” behavior has been simplified. In 0.4,
mapper() had an argument called <tt class="docutils literal"><span class="pre">polymorphic_fetch</span></tt>
which could be configured as <tt class="docutils literal"><span class="pre">select</span></tt> or <tt class="docutils literal"><span class="pre">deferred</span></tt>.
This option is removed; the mapper will now just defer any
columns which were not present in the SELECT statement.
The actual SELECT statement used is controlled by the
<tt class="docutils literal"><span class="pre">with_polymorphic</span></tt> mapper argument (which is also in 0.4
and replaces <tt class="docutils literal"><span class="pre">select_table</span></tt>), as well as the
<tt class="docutils literal"><span class="pre">with_polymorphic()</span></tt> method on <tt class="docutils literal"><span class="pre">Query</span></tt> (also in 0.4).</p>
<p>An improvement to the deferred loading of inheriting
classes is that the mapper now produces the “optimized”
version of the SELECT statement in all cases; that is, if
class B inherits from A, and several attributes only
present on class B have been expired, the refresh
operation will only include B’s table in the SELECT
statement and will not JOIN to A.</p>
</li>
<li><p class="first">The <tt class="docutils literal"><span class="pre">execute()</span></tt> method on <tt class="docutils literal"><span class="pre">Session</span></tt> converts plain
strings into <tt class="docutils literal"><span class="pre">text()</span></tt> constructs, so that bind
parameters may all be specified as ”:bindname” without
needing to call <tt class="docutils literal"><span class="pre">text()</span></tt> explicitly. If “raw” SQL is
desired here, use <tt class="docutils literal"><span class="pre">session.connection().execute("raw</span>
<span class="pre">text")</span></tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">session.Query().iterate_instances()</span></tt> has been renamed
to just <tt class="docutils literal"><span class="pre">instances()</span></tt>. The old <tt class="docutils literal"><span class="pre">instances()</span></tt> method
returning a list instead of an iterator no longer exists.
If you were relying on that behavior, you should use
<tt class="docutils literal"><span class="pre">list(your_query.instances())</span></tt>.</p>
</li>
</ul>
</div>
<div class="section" id="extending-the-orm">
<h2>Extending the ORM<a class="headerlink" href="#extending-the-orm" title="Permalink to this headline">¶</a></h2>
<p>In 0.5 we’re moving forward with more ways to modify and
extend the ORM. Heres a summary:</p>
<ul class="simple">
<li><strong>MapperExtension.</strong> - This is the classic extension
class, which remains. Methods which should rarely be
needed are <tt class="docutils literal"><span class="pre">create_instance()</span></tt> and
<tt class="docutils literal"><span class="pre">populate_instance()</span></tt>. To control the initialization of
an object when it’s loaded from the database, use the
<tt class="docutils literal"><span class="pre">reconstruct_instance()</span></tt> method, or more easily the
<tt class="docutils literal"><span class="pre">@reconstructor</span></tt> decorator described in the
documentation.</li>
<li><strong>SessionExtension.</strong> - This is an easy to use extension
class for session events. In particular, it provides
<tt class="docutils literal"><span class="pre">before_flush()</span></tt>, <tt class="docutils literal"><span class="pre">after_flush()</span></tt> and
<tt class="docutils literal"><span class="pre">after_flush_postexec()</span></tt> methods. This usage is
recommended over <tt class="docutils literal"><span class="pre">MapperExtension.before_XXX</span></tt> in many
cases since within <tt class="docutils literal"><span class="pre">before_flush()</span></tt> you can modify the
flush plan of the session freely, something which cannot
be done from within <tt class="docutils literal"><span class="pre">MapperExtension</span></tt>.</li>
<li><strong>AttributeExtension.</strong> - This class is now part of the
public API, and allows the interception of userland events
on attributes, including attribute set and delete
operations, and collection appends and removes. It also
allows the value to be set or appended to be modified.
The <tt class="docutils literal"><span class="pre">@validates</span></tt> decorator, described in the
documentation, provides a quick way to mark any mapped
attributes as being “validated” by a particular class
method.</li>
<li><strong>Attribute Instrumentation Customization.</strong> - An API is
provided for ambitious efforts to entirely replace
SQLAlchemy’s attribute instrumentation, or just to augment
it in some cases. This API was produced for the purposes
of the Trellis toolkit, but is available as a public API.
Some examples are provided in the distribution in the
<tt class="docutils literal"><span class="pre">/examples/custom_attributes</span></tt> directory.</li>
</ul>
</div>
<div class="section" id="schema-types">
<h2>Schema/Types<a class="headerlink" href="#schema-types" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first"><strong>String with no length no longer generates TEXT, it
generates VARCHAR</strong> - The <tt class="docutils literal"><span class="pre">String</span></tt> type no longer
magically converts into a <tt class="docutils literal"><span class="pre">Text</span></tt> type when specified
with no length. This only has an effect when CREATE TABLE
is issued, as it will issue <tt class="docutils literal"><span class="pre">VARCHAR</span></tt> with no length
parameter, which is not valid on many (but not all)
databases. To create a TEXT (or CLOB, i.e. unbounded
string) column, use the <tt class="docutils literal"><span class="pre">Text</span></tt> type.</p>
</li>
<li><p class="first"><strong>PickleType() with mutable=True requires an __eq__()
method</strong> - The <tt class="docutils literal"><span class="pre">PickleType</span></tt> type needs to compare values
when mutable=True. The method of comparing
<tt class="docutils literal"><span class="pre">pickle.dumps()</span></tt> is inefficient and unreliable. If an
incoming object does not implement <tt class="docutils literal"><span class="pre">__eq__()</span></tt> and is
also not <tt class="docutils literal"><span class="pre">None</span></tt>, the <tt class="docutils literal"><span class="pre">dumps()</span></tt> comparison is used but
a warning is raised. For types which implement
<tt class="docutils literal"><span class="pre">__eq__()</span></tt> which includes all dictionaries, lists, etc.,
comparison will use <tt class="docutils literal"><span class="pre">==</span></tt> and is now reliable by default.</p>
</li>
<li><p class="first"><strong>convert_bind_param() and convert_result_value() methods
of TypeEngine/TypeDecorator are removed.</strong> - The O’Reilly
book unfortunately documented these methods even though
they were deprecated post 0.3. For a user-defined type
which subclasses <tt class="docutils literal"><span class="pre">TypeEngine</span></tt>, the <tt class="docutils literal"><span class="pre">bind_processor()</span></tt>
and <tt class="docutils literal"><span class="pre">result_processor()</span></tt> methods should be used for
bind/result processing. Any user defined type, whether
extending <tt class="docutils literal"><span class="pre">TypeEngine</span></tt> or <tt class="docutils literal"><span class="pre">TypeDecorator</span></tt>, which uses
the old 0.3 style can be easily adapted to the new style
using the following adapter:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">AdaptOldConvertMethods</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="sd">"""A mixin which adapts 0.3-style convert_bind_param and</span>
<span class="sd"> convert_result_value methods</span>
<span class="sd"> """</span>
<span class="k">def</span> <span class="nf">bind_processor</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">convert</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">convert_bind_param</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">)</span>
<span class="k">return</span> <span class="n">convert</span>
<span class="k">def</span> <span class="nf">result_processor</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">convert</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">convert_result_value</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">)</span>
<span class="k">return</span> <span class="n">convert</span>
<span class="k">def</span> <span class="nf">convert_result_value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
<span class="k">return</span> <span class="n">value</span>
<span class="k">def</span> <span class="nf">convert_bind_param</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">dialect</span><span class="p">):</span>
<span class="k">return</span> <span class="n">value</span></pre></div>
</div>
<p>To use the above mixin:</p>
<div class="highlight-python"><pre>class MyType(AdaptOldConvertMethods, TypeEngine):
# ...</pre>
</div>
</li>
<li><p class="first">The <tt class="docutils literal"><span class="pre">quote</span></tt> flag on <tt class="docutils literal"><span class="pre">Column</span></tt> and <tt class="docutils literal"><span class="pre">Table</span></tt> as well as
the <tt class="docutils literal"><span class="pre">quote_schema</span></tt> flag on <tt class="docutils literal"><span class="pre">Table</span></tt> now control quoting
both positively and negatively. The default is <tt class="docutils literal"><span class="pre">None</span></tt>,
meaning let regular quoting rules take effect. When
<tt class="docutils literal"><span class="pre">True</span></tt>, quoting is forced on. When <tt class="docutils literal"><span class="pre">False</span></tt>, quoting
is forced off.</p>
</li>
<li><p class="first">Column <tt class="docutils literal"><span class="pre">DEFAULT</span></tt> value DDL can now be more conveniently
specified with <tt class="docutils literal"><span class="pre">Column(...,</span> <span class="pre">server_default='val')</span></tt>,
deprecating <tt class="docutils literal"><span class="pre">Column(...,</span> <span class="pre">PassiveDefault('val'))</span></tt>.
<tt class="docutils literal"><span class="pre">default=</span></tt> is now exclusively for Python-initiated
default values, and can coexist with server_default. A
new <tt class="docutils literal"><span class="pre">server_default=FetchedValue()</span></tt> replaces the
<tt class="docutils literal"><span class="pre">PassiveDefault('')</span></tt> idiom for marking columns as
subject to influence from external triggers and has no DDL
side effects.</p>
</li>
<li><p class="first">SQLite’s <tt class="docutils literal"><span class="pre">DateTime</span></tt>, <tt class="docutils literal"><span class="pre">Time</span></tt> and <tt class="docutils literal"><span class="pre">Date</span></tt> types now
<strong>only accept datetime objects, not strings</strong> as bind
parameter input. If you’d like to create your own
“hybrid” type which accepts strings and returns results as
date objects (from whatever format you’d like), create a
<tt class="docutils literal"><span class="pre">TypeDecorator</span></tt> that builds on <tt class="docutils literal"><span class="pre">String</span></tt>. If you only
want string-based dates, just use <tt class="docutils literal"><span class="pre">String</span></tt>.</p>
</li>
<li><p class="first">Additionally, the <tt class="docutils literal"><span class="pre">DateTime</span></tt> and <tt class="docutils literal"><span class="pre">Time</span></tt> types, when
used with SQLite, now represent the “microseconds” field
of the Python <tt class="docutils literal"><span class="pre">datetime.datetime</span></tt> object in the same
manner as <tt class="docutils literal"><span class="pre">str(datetime)</span></tt> - as fractional seconds, not a
count of microseconds. That is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2008</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">27</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">125</span><span class="p">)</span> <span class="c"># 125 usec</span>
<span class="c"># old way</span>
<span class="s">'2008-06-27 12:00:00.125'</span>
<span class="c"># new way</span>
<span class="s">'2008-06-27 12:00:00.000125'</span></pre></div>
</div>
<p>So if an existing SQLite file-based database intends to be
used across 0.4 and 0.5, you either have to upgrade the
datetime columns to store the new format (NOTE: please
test this, I’m pretty sure its correct):</p>
<div class="highlight-python"><pre>UPDATE mytable SET somedatecol =
substr(somedatecol, 0, 19) || '.' || substr((substr(somedatecol, 21, -1) / 1000000), 3, -1);</pre>
</div>
<p>or, enable “legacy” mode as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.databases.sqlite</span> <span class="kn">import</span> <span class="n">DateTimeMixin</span>
<span class="n">DateTimeMixin</span><span class="o">.</span><span class="n">__legacy_microseconds__</span> <span class="o">=</span> <span class="bp">True</span></pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="connection-pool-no-longer-threadlocal-by-default">
<h2>Connection Pool no longer threadlocal by default<a class="headerlink" href="#connection-pool-no-longer-threadlocal-by-default" title="Permalink to this headline">¶</a></h2>
<p>0.4 has an unfortunate default setting of
“pool_threadlocal=True”, leading to surprise behavior when,
for example, using multiple Sessions within a single thread.
This flag is now off in 0.5. To re-enable 0.4’s behavior,
specify <tt class="docutils literal"><span class="pre">pool_threadlocal=True</span></tt> to <tt class="docutils literal"><span class="pre">create_engine()</span></tt>, or
alternatively use the “threadlocal” strategy via
<tt class="docutils literal"><span class="pre">strategy="threadlocal"</span></tt>.</p>
</div>
<div class="section" id="args-accepted-args-no-longer-accepted">
<h2>*args Accepted, *args No Longer Accepted<a class="headerlink" href="#args-accepted-args-no-longer-accepted" title="Permalink to this headline">¶</a></h2>
<p>The policy with <tt class="docutils literal"><span class="pre">method(\*args)</span></tt> vs. <tt class="docutils literal"><span class="pre">method([args])</span></tt>
is, if the method accepts a variable-length set of items
which represent a fixed structure, it takes <tt class="docutils literal"><span class="pre">\*args</span></tt>. If
the method accepts a variable-length set of items that are
data-driven, it takes <tt class="docutils literal"><span class="pre">[args]</span></tt>.</p>
<ul>
<li><p class="first">The various Query.options() functions <tt class="docutils literal"><span class="pre">eagerload()</span></tt>,
<tt class="docutils literal"><span class="pre">eagerload_all()</span></tt>, <tt class="docutils literal"><span class="pre">lazyload()</span></tt>, <tt class="docutils literal"><span class="pre">contains_eager()</span></tt>,
<tt class="docutils literal"><span class="pre">defer()</span></tt>, <tt class="docutils literal"><span class="pre">undefer()</span></tt> all accept variable-length
<tt class="docutils literal"><span class="pre">\*keys</span></tt> as their argument now, which allows a path to
be formulated using descriptors, ie.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">query</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">User</span><span class="o">.</span><span class="n">orders</span><span class="p">,</span> <span class="n">Order</span><span class="o">.</span><span class="n">items</span><span class="p">,</span> <span class="n">Item</span><span class="o">.</span><span class="n">keywords</span><span class="p">))</span></pre></div>
</div>
<p>A single array argument is still accepted for backwards
compatibility.</p>
</li>
<li><p class="first">Similarly, the <tt class="docutils literal"><span class="pre">Query.join()</span></tt> and <tt class="docutils literal"><span class="pre">Query.outerjoin()</span></tt>
methods accept a variable length *args, with a single
array accepted for backwards compatibility:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">query</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s">'orders'</span><span class="p">,</span> <span class="s">'items'</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">User</span><span class="o">.</span><span class="n">orders</span><span class="p">,</span> <span class="n">Order</span><span class="o">.</span><span class="n">items</span><span class="p">)</span></pre></div>
</div>
</li>
<li><p class="first">the <tt class="docutils literal"><span class="pre">in_()</span></tt> method on columns and similar only accepts a
list argument now. It no longer accepts <tt class="docutils literal"><span class="pre">\*args</span></tt>.</p>
</li>
</ul>
</div>
<div class="section" id="removed">
<h2>Removed<a class="headerlink" href="#removed" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first"><strong>entity_name</strong> - This feature was always problematic and
rarely used. 0.5’s more deeply fleshed out use cases
revealed further issues with <tt class="docutils literal"><span class="pre">entity_name</span></tt> which led to
its removal. If different mappings are required for a
single class, break the class into separate subclasses and
map them separately. An example of this is at
[wiki:UsageRecipes/EntityName]. More information
regarding rationale is described at http://groups.google.c
om/group/sqlalchemy/browse_thread/thread/9e23a0641a88b96d?
hl=en .</p>
</li>
<li><p class="first"><strong>get()/load() cleanup</strong></p>
<p>The <tt class="docutils literal"><span class="pre">load()</span></tt> method has been removed. Its
functionality was kind of arbitrary and basically copied
from Hibernate, where it’s also not a particularly
meaningful method.</p>
<p>To get equivalent functionality:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">x</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">SomeClass</span><span class="p">)</span><span class="o">.</span><span class="n">populate_existing</span><span class="p">()</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span></pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">Session.get(cls,</span> <span class="pre">id)</span></tt> and <tt class="docutils literal"><span class="pre">Session.load(cls,</span> <span class="pre">id)</span></tt>
have been removed. <tt class="docutils literal"><span class="pre">Session.get()</span></tt> is redundant vs.
<tt class="docutils literal"><span class="pre">session.query(cls).get(id)</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">MapperExtension.get()</span></tt> is also removed (as is
<tt class="docutils literal"><span class="pre">MapperExtension.load()</span></tt>). To override the
functionality of <tt class="docutils literal"><span class="pre">Query.get()</span></tt>, use a subclass:</p>
<div class="highlight-python"><pre>class MyQuery(Query):
def get(self, ident):
# ...
session = sessionmaker(query_cls=MyQuery)()
ad1 = session.query(Address).get(1)</pre>
</div>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.orm.relation()</span></tt></p>
<p>The following deprecated keyword arguments have been
removed:</p>
<p>foreignkey, association, private, attributeext, is_backref</p>
<p>In particular, <tt class="docutils literal"><span class="pre">attributeext</span></tt> is replaced with
<tt class="docutils literal"><span class="pre">extension</span></tt> - the <tt class="docutils literal"><span class="pre">AttributeExtension</span></tt> class is now in
the public API.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">session.Query()</span></tt></p>
<p>The following deprecated functions have been removed:</p>
<p>list, scalar, count_by, select_whereclause, get_by,
select_by, join_by, selectfirst, selectone, select,
execute, select_statement, select_text, join_to, join_via,
selectfirst_by, selectone_by, apply_max, apply_min,
apply_avg, apply_sum</p>
<p>Additionally, the <tt class="docutils literal"><span class="pre">id</span></tt> keyword argument to <tt class="docutils literal"><span class="pre">join()</span></tt>,
<tt class="docutils literal"><span class="pre">outerjoin()</span></tt>, <tt class="docutils literal"><span class="pre">add_entity()</span></tt> and <tt class="docutils literal"><span class="pre">add_column()</span></tt> has
been removed. To target table aliases in <tt class="docutils literal"><span class="pre">Query</span></tt> to
result columns, use the <tt class="docutils literal"><span class="pre">aliased</span></tt> construct:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="kn">import</span> <span class="n">aliased</span>
<span class="n">address_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">Address</span><span class="p">)</span>
<span class="k">print</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">address_alias</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">((</span><span class="n">address_alias</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">))</span><span class="o">.</span><span class="n">all</span><span class="p">()</span></pre></div>
</div>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.orm.Mapper</span></tt></p>
<ul class="simple">
<li>instances()</li>
<li>get_session() - this method was not very noticeable, but
had the effect of associating lazy loads with a
particular session even if the parent object was
entirely detached, when an extension such as
<tt class="docutils literal"><span class="pre">scoped_session()</span></tt> or the old <tt class="docutils literal"><span class="pre">SessionContextExt</span></tt>
was used. It’s possible that some applications which
relied upon this behavior will no longer work as
expected; but the better programming practice here is
to always ensure objects are present within sessions if
database access from their attributes are required.</li>
</ul>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">mapper(MyClass,</span> <span class="pre">mytable)</span></tt></p>
<p>Mapped classes no are longer instrumented with a “c” class
attribute; e.g. <tt class="docutils literal"><span class="pre">MyClass.c</span></tt></p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.orm.collections</span></tt></p>
<p>The _prepare_instrumentation alias for
prepare_instrumentation has been removed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.orm</span></tt></p>
<p>Removed the <tt class="docutils literal"><span class="pre">EXT_PASS</span></tt> alias of <tt class="docutils literal"><span class="pre">EXT_CONTINUE</span></tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.engine</span></tt></p>
<p>The alias from <tt class="docutils literal"><span class="pre">DefaultDialect.preexecute_sequences</span></tt> to
<tt class="docutils literal"><span class="pre">.preexecute_pk_sequences</span></tt> has been removed.</p>
<p>The deprecated engine_descriptors() function has been
removed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.activemapper</span></tt></p>
<p>Module removed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.assignmapper</span></tt></p>
<p>Module removed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.associationproxy</span></tt></p>
<p>Pass-through of keyword args on the proxy’s
<tt class="docutils literal"><span class="pre">.append(item,</span> <span class="pre">\**kw)</span></tt> has been removed and is now
simply <tt class="docutils literal"><span class="pre">.append(item)</span></tt></p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.selectresults</span></tt>,
<tt class="docutils literal"><span class="pre">sqlalchemy.mods.selectresults</span></tt></p>
<p>Modules removed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.declarative</span></tt></p>
<p><tt class="docutils literal"><span class="pre">declared_synonym()</span></tt> removed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.sessioncontext</span></tt></p>
<p>Module removed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.log</span></tt></p>
<p>The <tt class="docutils literal"><span class="pre">SADeprecationWarning</span></tt> alias to
<tt class="docutils literal"><span class="pre">sqlalchemy.exc.SADeprecationWarning</span></tt> has been removed.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.exc</span></tt></p>
<p><tt class="docutils literal"><span class="pre">exc.AssertionError</span></tt> has been removed and usage replaced
by the Python built-in of the same name.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.databases.mysql</span></tt></p>
<p>The deprecated <tt class="docutils literal"><span class="pre">get_version_info</span></tt> dialect method has
been removed.</p>
</li>
</ul>
</div>
<div class="section" id="renamed-or-moved">
<h2>Renamed or Moved<a class="headerlink" href="#renamed-or-moved" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.exceptions</span></tt> is now <tt class="docutils literal"><span class="pre">sqlalchemy.exc</span></tt></p>
<p>The module may still be imported under the old name until
0.6.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">FlushError</span></tt>, <tt class="docutils literal"><span class="pre">ConcurrentModificationError</span></tt>,
<tt class="docutils literal"><span class="pre">UnmappedColumnError</span></tt> -> sqlalchemy.orm.exc</p>
<p>These exceptions moved to the orm package. Importing
‘sqlalchemy.orm’ will install aliases in sqlalchemy.exc
for compatibility until 0.6.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.logging</span></tt> -> <tt class="docutils literal"><span class="pre">sqlalchemy.log</span></tt></p>
<p>This internal module was renamed. No longer needs to be
special cased when packaging SA with py2app and similar
tools that scan imports.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">session.Query().iterate_instances()</span></tt> ->
<tt class="docutils literal"><span class="pre">session.Query().instances()</span></tt>.</p>
</li>
</ul>
</div>
<div class="section" id="deprecated">
<h2>Deprecated<a class="headerlink" href="#deprecated" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">Session.save()</span></tt>, <tt class="docutils literal"><span class="pre">Session.update()</span></tt>,
<tt class="docutils literal"><span class="pre">Session.save_or_update()</span></tt></p>
<p>All three replaced by <tt class="docutils literal"><span class="pre">Session.add()</span></tt></p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.PassiveDefault</span></tt></p>
<p>Use <tt class="docutils literal"><span class="pre">Column(server_default=...)</span></tt> Translates to
sqlalchemy.DefaultClause() under the hood.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">session.Query().iterate_instances()</span></tt>. It has been
renamed to <tt class="docutils literal"><span class="pre">instances()</span></tt>.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links">
Previous:
<a href="migration_06.html" title="previous chapter">What’s New in SQLAlchemy 0.6?</a>
Next:
<a href="migration_04.html" title="next chapter">What’s new in SQLAlchemy 0.4?</a>
<div id="docs-copyright">
© <a href="../copyright.html">Copyright</a> 2007-2014, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1.
</div>
</div>
</div>
</body>
</html>
