1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
<html xmlns="http://www.w3.org/1999/xhtml">
6
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11
What’s new in SQLAlchemy 0.5?
13
SQLAlchemy 0.8 Documentation
17
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
18
<link rel="stylesheet" href="../_static/docs.css" type="text/css" />
20
<script type="text/javascript">
21
var DOCUMENTATION_OPTIONS = {
24
COLLAPSE_MODINDEX: false,
28
<script type="text/javascript" src="../_static/jquery.js"></script>
29
<script type="text/javascript" src="../_static/underscore.js"></script>
30
<script type="text/javascript" src="../_static/doctools.js"></script>
31
<script type="text/javascript" src="../_static/init.js"></script>
32
<link rel="index" title="Index" href="../genindex.html" />
33
<link rel="search" title="Search" href="../search.html" />
34
<link rel="copyright" title="Copyright" href="../copyright.html" />
35
<link rel="top" title="SQLAlchemy 0.8 Documentation" href="../index.html" />
36
<link rel="up" title="Changes and Migration" href="index.html" />
37
<link rel="next" title="What’s new in SQLAlchemy 0.4?" href="migration_04.html" />
38
<link rel="prev" title="What’s New in SQLAlchemy 0.6?" href="migration_06.html" />
53
<div id="docs-container">
57
<div id="docs-header">
58
<h1>SQLAlchemy 0.8 Documentation</h1>
60
<div id="docs-search">
62
<form class="search" action="../search.html" method="get">
63
<input type="text" name="q" size="18" /> <input type="submit" value="Search" />
64
<input type="hidden" name="check_keywords" value="yes" />
65
<input type="hidden" name="area" value="default" />
69
<div id="docs-version-header">
70
Release: <span class="version-num">0.8.2</span> | Release Date: July 3, 2013
77
<div id="docs-top-navigation">
78
<div id="docs-top-page-control" class="docs-navigation-links">
81
<a href="migration_06.html" title="previous chapter">What’s New in SQLAlchemy 0.6?</a>
84
<a href="migration_04.html" title="next chapter">What’s new in SQLAlchemy 0.4?</a>
88
<a href="../contents.html">Table of Contents</a> |
89
<a href="../genindex.html">Index</a>
90
| <a href="../_sources/changelog/migration_05.txt">view source
95
<div id="docs-navigation-banner">
96
<a href="../index.html">SQLAlchemy 0.8 Documentation</a>
97
» <a href="index.html" title="Changes and Migration">Changes and Migration</a>
99
What’s new in SQLAlchemy 0.5?
104
What’s new in SQLAlchemy 0.5?
111
<div id="docs-body-container">
113
<div id="docs-sidebar">
114
<h3><a href="../index.html">Table of Contents</a></h3>
116
<li><a class="reference internal" href="#">What’s new in SQLAlchemy 0.5?</a><ul>
117
<li><a class="reference internal" href="#major-documentation-changes">Major Documentation Changes</a></li>
118
<li><a class="reference internal" href="#deprecations-source">Deprecations Source</a></li>
119
<li><a class="reference internal" href="#requirements-changes">Requirements Changes</a></li>
120
<li><a class="reference internal" href="#object-relational-mapping">Object Relational Mapping</a></li>
121
<li><a class="reference internal" href="#extending-the-orm">Extending the ORM</a></li>
122
<li><a class="reference internal" href="#schema-types">Schema/Types</a></li>
123
<li><a class="reference internal" href="#connection-pool-no-longer-threadlocal-by-default">Connection Pool no longer threadlocal by default</a></li>
124
<li><a class="reference internal" href="#args-accepted-args-no-longer-accepted">*args Accepted, *args No Longer Accepted</a></li>
125
<li><a class="reference internal" href="#removed">Removed</a></li>
126
<li><a class="reference internal" href="#renamed-or-moved">Renamed or Moved</a></li>
127
<li><a class="reference internal" href="#deprecated">Deprecated</a></li>
133
<h4>Previous Topic</h4>
135
<a href="migration_06.html" title="previous chapter">What’s New in SQLAlchemy 0.6?</a>
139
<a href="migration_04.html" title="next chapter">What’s new in SQLAlchemy 0.4?</a>
143
<h4>Quick Search</h4>
145
<form class="search" action="../search.html" method="get">
146
<input type="text" name="q" size="18" /> <input type="submit" value="Search" />
147
<input type="hidden" name="check_keywords" value="yes" />
148
<input type="hidden" name="area" value="default" />
154
<div id="docs-body" class="withsidebar" >
156
<div class="section" id="what-s-new-in-sqlalchemy-0-5">
157
<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>
158
<div class="admonition-about-this-document admonition">
159
<p class="first admonition-title">About this Document</p>
160
<p>This document describes changes between SQLAlchemy version 0.4,
161
last released October 12, 2008, and SQLAlchemy version 0.5,
162
last released January 16, 2010.</p>
163
<p class="last">Document date: August 4, 2009</p>
165
<p>This guide documents API changes which affect users
166
migrating their applications from the 0.4 series of
167
SQLAlchemy to 0.5. It’s also recommended for those working
168
from <a class="reference external" href="http://oreilly.com/catalog/9780596516147/">Essential SQLAlchemy</a>, which only
169
covers 0.4 and seems to even have some old 0.3isms in it.
170
Note that SQLAlchemy 0.5 removes many behaviors which were
171
deprecated throughout the span of the 0.4 series, and also
172
deprecates more behaviors specific to 0.4.</p>
173
<div class="section" id="major-documentation-changes">
174
<h2>Major Documentation Changes<a class="headerlink" href="#major-documentation-changes" title="Permalink to this headline">¶</a></h2>
175
<p>Some sections of the documentation have been completely
176
rewritten and can serve as an introduction to new ORM
177
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
178
particular have some distinct differences in API and
179
behavior which fundamentally change many of the basic ways
180
things are done, particularly with regards to constructing
181
highly customized ORM queries and dealing with stale session
182
state, commits and rollbacks.</p>
184
<li><a class="reference external" href="http://www.sqlalchemy.org/docs/05/ormtutorial.html">ORM Tutorial</a></li>
185
<li><a class="reference external" href="http://www.sqlalchemy.org/docs/05/session.html">Session Documentation</a></li>
188
<div class="section" id="deprecations-source">
189
<h2>Deprecations Source<a class="headerlink" href="#deprecations-source" title="Permalink to this headline">¶</a></h2>
190
<p>Another source of information is documented within a series
191
of unit tests illustrating up to date usages of some common
192
<tt class="docutils literal"><span class="pre">Query</span></tt> patterns; this file can be viewed at
193
[source:sqlalchemy/trunk/test/orm/test_deprecations.py].</p>
195
<div class="section" id="requirements-changes">
196
<h2>Requirements Changes<a class="headerlink" href="#requirements-changes" title="Permalink to this headline">¶</a></h2>
198
<li>Python 2.4 or higher is required. The SQLAlchemy 0.4 line
199
is the last version with Python 2.3 support.</li>
202
<div class="section" id="object-relational-mapping">
203
<h2>Object Relational Mapping<a class="headerlink" href="#object-relational-mapping" title="Permalink to this headline">¶</a></h2>
205
<li><p class="first"><strong>Column level expressions within Query.</strong> - as detailed
206
in the <a class="reference external" href="http://www.sqlalchemy.org/docs/05/ormtutorial.html">tutorial</a>,
207
<tt class="docutils literal"><span class="pre">Query</span></tt> has the capability to create specific SELECT
208
statements, not just those against full rows:</p>
209
<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>
211
<p>The tuples returned by any multi-column/entity query are
212
<em>named</em>‘ tuples:</p>
213
<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>
214
<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>
216
<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
217
<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
218
create more complex combinations:</p>
219
<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>
220
<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>
221
<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>
222
<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>
223
<span class="p">)</span></pre></div>
226
<li><p class="first"><strong>Explicit ORM aliases are recommended for aliased joins</strong>
227
- The <tt class="docutils literal"><span class="pre">aliased()</span></tt> function produces an “alias” of a
228
class, which allows fine-grained control of aliases in
229
conjunction with ORM queries. While a table-level alias
230
(i.e. <tt class="docutils literal"><span class="pre">table.alias()</span></tt>) is still usable, an ORM level
231
alias retains the semantics of the ORM mapped object which
232
is significant for inheritance mappings, options, and
233
other scenarios. E.g.:</p>
234
<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>
235
<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>
238
<li><p class="first"><strong>query.join() greatly enhanced.</strong> - You can now specify
239
the target and ON clause for a join in multiple ways. A
240
target class alone can be provided where SQLA will attempt
241
to form a join to it via foreign key in the same way as
242
<tt class="docutils literal"><span class="pre">table.join(someothertable)</span></tt>. A target and an explicit
243
ON condition can be provided, where the ON condition can
244
be a <tt class="docutils literal"><span class="pre">relation()</span></tt> name, an actual class descriptor, or a
245
SQL expression. Or the old way of just a <tt class="docutils literal"><span class="pre">relation()</span></tt>
246
name or class descriptor works too. See the ORM tutorial
247
which has several examples.</p>
249
<li><p class="first"><strong>Declarative is recommended for applications which don’t
250
require (and don’t prefer) abstraction between tables and
251
mappers</strong> - The [/docs/05/reference/ext/declarative.html
252
Declarative] module, which is used to combine the
253
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
254
class objects together, is highly recommended as it
255
simplifies application configuration, ensures the “one
256
mapper per class” pattern, and allows the full range of
257
configuration available to distinct <tt class="docutils literal"><span class="pre">mapper()</span></tt> calls.
258
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
259
to as “classical SQLAlchemy usage” and of course is freely
260
mixable with declarative.</p>
262
<li><p class="first"><strong>The .c. attribute has been removed</strong> from classes (i.e.
263
<tt class="docutils literal"><span class="pre">MyClass.c.somecolumn</span></tt>). As is the case in 0.4, class-
264
level properties are usable as query elements, i.e.
265
<tt class="docutils literal"><span class="pre">Class.c.propname</span></tt> is now superseded by
266
<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
267
remain on <tt class="docutils literal"><span class="pre">Table</span></tt> objects where they indicate the
268
namespace of <tt class="docutils literal"><span class="pre">Column</span></tt> objects present on the table.</p>
269
<p>To get at the Table for a mapped class (if you didn’t keep
270
it around already):</p>
271
<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>
273
<p>Iterate through columns:</p>
274
<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>
275
<span class="k">print</span> <span class="n">col</span></pre></div>
277
<p>Work with a specific column:</p>
278
<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>
280
<p>The class-bound descriptors support the full set of Column
281
operators as well as the documented relation-oriented
282
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>
283
<p>The reason for the hard removal of <tt class="docutils literal"><span class="pre">.c.</span></tt> is that in 0.5,
284
class-bound descriptors carry potentially different
285
meaning, as well as information regarding class mappings,
286
versus plain <tt class="docutils literal"><span class="pre">Column</span></tt> objects - and there are use cases
287
where you’d specifically want to use one or the other.
288
Generally, using class-bound descriptors invokes a set of
289
mapping/polymorphic aware translations, and using table-
290
bound columns does not. In 0.4, these translations were
291
applied across the board to all expressions, but 0.5
292
differentiates completely between columns and mapped
293
descriptors, only applying translations to the latter. So
294
in many cases, particularly when dealing with joined table
295
inheritance configurations as well as when using
296
<tt class="docutils literal"><span class="pre">query(<columns>)</span></tt>, <tt class="docutils literal"><span class="pre">Class.propname</span></tt> and
297
<tt class="docutils literal"><span class="pre">table.c.colname</span></tt> are not interchangeable.</p>
298
<p>For example, <tt class="docutils literal"><span class="pre">session.query(users.c.id,</span> <span class="pre">users.c.name)</span></tt>
299
is different versus <tt class="docutils literal"><span class="pre">session.query(User.id,</span> <span class="pre">User.name)</span></tt>;
300
in the latter case, the <tt class="docutils literal"><span class="pre">Query</span></tt> is aware of the mapper
301
in use and further mapper-specific operations like
302
<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.
303
may be used, but in the former case cannot. Additionally,
304
in polymorphic inheritance scenarios, the class-bound
305
descriptors refer to the columns present in the
306
polymorphic selectable in use, not necessarily the table
307
column which directly corresponds to the descriptor. For
308
example, a set of classes related by joined-table
309
inheritance to the <tt class="docutils literal"><span class="pre">person</span></tt> table along the
310
<tt class="docutils literal"><span class="pre">person_id</span></tt> column of each table will all have their
311
<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>
312
column in <tt class="docutils literal"><span class="pre">person</span></tt>, and not their subclass table.
313
Version 0.4 would map this behavior onto table-bound
314
<tt class="docutils literal"><span class="pre">Column</span></tt> objects automatically. In 0.5, this automatic
315
conversion has been removed, so that you in fact <em>can</em> use
316
table-bound columns as a means to override the
317
translations which occur with polymorphic querying; this
318
allows <tt class="docutils literal"><span class="pre">Query</span></tt> to be able to create optimized selects
319
among joined-table or concrete-table inheritance setups,
320
as well as portable subqueries, etc.</p>
322
<li><p class="first"><strong>Session Now Synchronizes Automatically with
323
Transactions.</strong> Session now synchronizes against the
324
transaction automatically by default, including autoflush
325
and autoexpire. A transaction is present at all times
326
unless disabled using the <tt class="docutils literal"><span class="pre">autocommit</span></tt> option. When all
327
three flags are set to their default, the Session recovers
328
gracefully after rollbacks and it’s very difficult to get
329
stale data into the session. See the new Session
330
documentation for details.</p>
332
<li><p class="first"><strong>Implicit Order By Is Removed</strong>. This will impact ORM
333
users who rely upon SA’s “implicit ordering” behavior,
334
which states that all Query objects which don’t have an
335
<tt class="docutils literal"><span class="pre">order_by()</span></tt> will ORDER BY the “id” or “oid” column of
336
the primary mapped table, and all lazy/eagerly loaded
337
collections apply a similar ordering. In 0.5, automatic
338
ordering must be explicitly configured on <tt class="docutils literal"><span class="pre">mapper()</span></tt> and
339
<tt class="docutils literal"><span class="pre">relation()</span></tt> objects (if desired), or otherwise when
340
using <tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
341
<p>To convert an 0.4 mapping to 0.5, such that its ordering
342
behavior will be extremely similar to 0.4 or previous, use
343
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
344
<tt class="docutils literal"><span class="pre">relation()</span></tt>:</p>
345
<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>
346
<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>
347
<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>
349
<p>To set ordering on a backref, use the <tt class="docutils literal"><span class="pre">backref()</span></tt>
351
<div class="highlight-python"><pre>'keywords':relation(Keyword, secondary=item_keywords,
352
order_by=keywords.c.name, backref=backref('items', order_by=items.c.id))</pre>
354
<p>Using declarative ? To help with the new <tt class="docutils literal"><span class="pre">order_by</span></tt>
355
requirement, <tt class="docutils literal"><span class="pre">order_by</span></tt> and friends can now be set using
356
strings which are evaluated in Python later on (this works
357
<strong>only</strong> with declarative, not plain mappers):</p>
358
<div class="highlight-python"><pre>class MyClass(MyDeclarativeBase):
360
'addresses':relation("Address", order_by="Address.id")</pre>
362
<p>It’s generally a good idea to set <tt class="docutils literal"><span class="pre">order_by</span></tt> on
363
<tt class="docutils literal"><span class="pre">relation()s</span></tt> which load list-based collections of
364
items, since that ordering cannot otherwise be affected.
365
Other than that, the best practice is to use
366
<tt class="docutils literal"><span class="pre">Query.order_by()</span></tt> to control ordering of the primary
367
entities being loaded.</p>
369
<li><p class="first"><strong>Session is now
370
autoflush=True/autoexpire=True/autocommit=False.</strong> - To
371
set it up, just call <tt class="docutils literal"><span class="pre">sessionmaker()</span></tt> with no arguments.
372
The name <tt class="docutils literal"><span class="pre">transactional=True</span></tt> is now
373
<tt class="docutils literal"><span class="pre">autocommit=False</span></tt>. Flushes occur upon each query
374
issued (disable with <tt class="docutils literal"><span class="pre">autoflush=False</span></tt>), within each
375
<tt class="docutils literal"><span class="pre">commit()</span></tt> (as always), and before each
376
<tt class="docutils literal"><span class="pre">begin_nested()</span></tt> (so rolling back to the SAVEPOINT is
377
meaningful). All objects are expired after each
378
<tt class="docutils literal"><span class="pre">commit()</span></tt> and after each <tt class="docutils literal"><span class="pre">rollback()</span></tt>. After
379
rollback, pending objects are expunged, deleted objects
380
move back to persistent. These defaults work together
381
very nicely and there’s really no more need for old
382
techniques like <tt class="docutils literal"><span class="pre">clear()</span></tt> (which is renamed to
383
<tt class="docutils literal"><span class="pre">expunge_all()</span></tt> as well).</p>
384
<p>P.S.: sessions are now reusable after a <tt class="docutils literal"><span class="pre">rollback()</span></tt>.
385
Scalar and collection attribute changes, adds and deletes
386
are all rolled back.</p>
388
<li><p class="first"><strong>session.add() replaces session.save(), session.update(),
389
session.save_or_update().</strong> - the
390
<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>
391
<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
392
<tt class="docutils literal"><span class="pre">save_or_update()</span></tt>. Those methods will remain
393
deprecated throughout 0.5.</p>
395
<li><p class="first"><strong>backref configuration made less verbose.</strong> - The
396
<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
397
<tt class="docutils literal"><span class="pre">secondaryjoin</span></tt> arguments of the forwards-facing
398
<tt class="docutils literal"><span class="pre">relation()</span></tt> when they are not explicitly stated. It’s
399
no longer necessary to specify
400
<tt class="docutils literal"><span class="pre">primaryjoin</span></tt>/<tt class="docutils literal"><span class="pre">secondaryjoin</span></tt> in both directions
403
<li><p class="first"><strong>Simplified polymorphic options.</strong> - The ORM’s
404
“polymorphic load” behavior has been simplified. In 0.4,
405
mapper() had an argument called <tt class="docutils literal"><span class="pre">polymorphic_fetch</span></tt>
406
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>.
407
This option is removed; the mapper will now just defer any
408
columns which were not present in the SELECT statement.
409
The actual SELECT statement used is controlled by the
410
<tt class="docutils literal"><span class="pre">with_polymorphic</span></tt> mapper argument (which is also in 0.4
411
and replaces <tt class="docutils literal"><span class="pre">select_table</span></tt>), as well as the
412
<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>
413
<p>An improvement to the deferred loading of inheriting
414
classes is that the mapper now produces the “optimized”
415
version of the SELECT statement in all cases; that is, if
416
class B inherits from A, and several attributes only
417
present on class B have been expired, the refresh
418
operation will only include B’s table in the SELECT
419
statement and will not JOIN to A.</p>
421
<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
422
strings into <tt class="docutils literal"><span class="pre">text()</span></tt> constructs, so that bind
423
parameters may all be specified as ”:bindname” without
424
needing to call <tt class="docutils literal"><span class="pre">text()</span></tt> explicitly. If “raw” SQL is
425
desired here, use <tt class="docutils literal"><span class="pre">session.connection().execute("raw</span>
426
<span class="pre">text")</span></tt>.</p>
428
<li><p class="first"><tt class="docutils literal"><span class="pre">session.Query().iterate_instances()</span></tt> has been renamed
429
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
430
returning a list instead of an iterator no longer exists.
431
If you were relying on that behavior, you should use
432
<tt class="docutils literal"><span class="pre">list(your_query.instances())</span></tt>.</p>
436
<div class="section" id="extending-the-orm">
437
<h2>Extending the ORM<a class="headerlink" href="#extending-the-orm" title="Permalink to this headline">¶</a></h2>
438
<p>In 0.5 we’re moving forward with more ways to modify and
439
extend the ORM. Heres a summary:</p>
441
<li><strong>MapperExtension.</strong> - This is the classic extension
442
class, which remains. Methods which should rarely be
443
needed are <tt class="docutils literal"><span class="pre">create_instance()</span></tt> and
444
<tt class="docutils literal"><span class="pre">populate_instance()</span></tt>. To control the initialization of
445
an object when it’s loaded from the database, use the
446
<tt class="docutils literal"><span class="pre">reconstruct_instance()</span></tt> method, or more easily the
447
<tt class="docutils literal"><span class="pre">@reconstructor</span></tt> decorator described in the
449
<li><strong>SessionExtension.</strong> - This is an easy to use extension
450
class for session events. In particular, it provides
451
<tt class="docutils literal"><span class="pre">before_flush()</span></tt>, <tt class="docutils literal"><span class="pre">after_flush()</span></tt> and
452
<tt class="docutils literal"><span class="pre">after_flush_postexec()</span></tt> methods. It’s usage is
453
recommended over <tt class="docutils literal"><span class="pre">MapperExtension.before_XXX</span></tt> in many
454
cases since within <tt class="docutils literal"><span class="pre">before_flush()</span></tt> you can modify the
455
flush plan of the session freely, something which cannot
456
be done from within <tt class="docutils literal"><span class="pre">MapperExtension</span></tt>.</li>
457
<li><strong>AttributeExtension.</strong> - This class is now part of the
458
public API, and allows the interception of userland events
459
on attributes, including attribute set and delete
460
operations, and collection appends and removes. It also
461
allows the value to be set or appended to be modified.
462
The <tt class="docutils literal"><span class="pre">@validates</span></tt> decorator, described in the
463
documentation, provides a quick way to mark any mapped
464
attributes as being “validated” by a particular class
466
<li><strong>Attribute Instrumentation Customization.</strong> - An API is
467
provided for ambitious efforts to entirely replace
468
SQLAlchemy’s attribute instrumentation, or just to augment
469
it in some cases. This API was produced for the purposes
470
of the Trellis toolkit, but is available as a public API.
471
Some examples are provided in the distribution in the
472
<tt class="docutils literal"><span class="pre">/examples/custom_attributes</span></tt> directory.</li>
475
<div class="section" id="schema-types">
476
<h2>Schema/Types<a class="headerlink" href="#schema-types" title="Permalink to this headline">¶</a></h2>
478
<li><p class="first"><strong>String with no length no longer generates TEXT, it
479
generates VARCHAR</strong> - The <tt class="docutils literal"><span class="pre">String</span></tt> type no longer
480
magically converts into a <tt class="docutils literal"><span class="pre">Text</span></tt> type when specified
481
with no length. This only has an effect when CREATE TABLE
482
is issued, as it will issue <tt class="docutils literal"><span class="pre">VARCHAR</span></tt> with no length
483
parameter, which is not valid on many (but not all)
484
databases. To create a TEXT (or CLOB, i.e. unbounded
485
string) column, use the <tt class="docutils literal"><span class="pre">Text</span></tt> type.</p>
487
<li><p class="first"><strong>PickleType() with mutable=True requires an __eq__()
488
method</strong> - The <tt class="docutils literal"><span class="pre">PickleType</span></tt> type needs to compare values
489
when mutable=True. The method of comparing
490
<tt class="docutils literal"><span class="pre">pickle.dumps()</span></tt> is inefficient and unreliable. If an
491
incoming object does not implement <tt class="docutils literal"><span class="pre">__eq__()</span></tt> and is
492
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
493
a warning is raised. For types which implement
494
<tt class="docutils literal"><span class="pre">__eq__()</span></tt> which includes all dictionaries, lists, etc.,
495
comparison will use <tt class="docutils literal"><span class="pre">==</span></tt> and is now reliable by default.</p>
497
<li><p class="first"><strong>convert_bind_param() and convert_result_value() methods
498
of TypeEngine/TypeDecorator are removed.</strong> - The O’Reilly
499
book unfortunately documented these methods even though
500
they were deprecated post 0.3. For a user-defined type
501
which subclasses <tt class="docutils literal"><span class="pre">TypeEngine</span></tt>, the <tt class="docutils literal"><span class="pre">bind_processor()</span></tt>
502
and <tt class="docutils literal"><span class="pre">result_processor()</span></tt> methods should be used for
503
bind/result processing. Any user defined type, whether
504
extending <tt class="docutils literal"><span class="pre">TypeEngine</span></tt> or <tt class="docutils literal"><span class="pre">TypeDecorator</span></tt>, which uses
505
the old 0.3 style can be easily adapted to the new style
506
using the following adapter:</p>
507
<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>
508
<span class="sd">"""A mixin which adapts 0.3-style convert_bind_param and</span>
509
<span class="sd"> convert_result_value methods</span>
511
<span class="sd"> """</span>
512
<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>
513
<span class="k">def</span> <span class="nf">convert</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
514
<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>
515
<span class="k">return</span> <span class="n">convert</span>
517
<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>
518
<span class="k">def</span> <span class="nf">convert</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
519
<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>
520
<span class="k">return</span> <span class="n">convert</span>
522
<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>
523
<span class="k">return</span> <span class="n">value</span>
525
<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>
526
<span class="k">return</span> <span class="n">value</span></pre></div>
528
<p>To use the above mixin:</p>
529
<div class="highlight-python"><pre>class MyType(AdaptOldConvertMethods, TypeEngine):
533
<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
534
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
535
both positively and negatively. The default is <tt class="docutils literal"><span class="pre">None</span></tt>,
536
meaning let regular quoting rules take effect. When
537
<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
540
<li><p class="first">Column <tt class="docutils literal"><span class="pre">DEFAULT</span></tt> value DDL can now be more conveniently
541
specified with <tt class="docutils literal"><span class="pre">Column(...,</span> <span class="pre">server_default='val')</span></tt>,
542
deprecating <tt class="docutils literal"><span class="pre">Column(...,</span> <span class="pre">PassiveDefault('val'))</span></tt>.
543
<tt class="docutils literal"><span class="pre">default=</span></tt> is now exclusively for Python-initiated
544
default values, and can coexist with server_default. A
545
new <tt class="docutils literal"><span class="pre">server_default=FetchedValue()</span></tt> replaces the
546
<tt class="docutils literal"><span class="pre">PassiveDefault('')</span></tt> idiom for marking columns as
547
subject to influence from external triggers and has no DDL
550
<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
551
<strong>only accept datetime objects, not strings</strong> as bind
552
parameter input. If you’d like to create your own
553
“hybrid” type which accepts strings and returns results as
554
date objects (from whatever format you’d like), create a
555
<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
556
want string-based dates, just use <tt class="docutils literal"><span class="pre">String</span></tt>.</p>
558
<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
559
used with SQLite, now represent the “microseconds” field
560
of the Python <tt class="docutils literal"><span class="pre">datetime.datetime</span></tt> object in the same
561
manner as <tt class="docutils literal"><span class="pre">str(datetime)</span></tt> - as fractional seconds, not a
562
count of microseconds. That is:</p>
563
<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>
565
<span class="c"># old way</span>
566
<span class="s">'2008-06-27 12:00:00.125'</span>
568
<span class="c"># new way</span>
569
<span class="s">'2008-06-27 12:00:00.000125'</span></pre></div>
571
<p>So if an existing SQLite file-based database intends to be
572
used across 0.4 and 0.5, you either have to upgrade the
573
datetime columns to store the new format (NOTE: please
574
test this, I’m pretty sure its correct):</p>
575
<div class="highlight-python"><pre>UPDATE mytable SET somedatecol =
576
substr(somedatecol, 0, 19) || '.' || substr((substr(somedatecol, 21, -1) / 1000000), 3, -1);</pre>
578
<p>or, enable “legacy” mode as follows:</p>
579
<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>
580
<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>
585
<div class="section" id="connection-pool-no-longer-threadlocal-by-default">
586
<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>
587
<p>0.4 has an unfortunate default setting of
588
“pool_threadlocal=True”, leading to surprise behavior when,
589
for example, using multiple Sessions within a single thread.
590
This flag is now off in 0.5. To re-enable 0.4’s behavior,
591
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
592
alternatively use the “threadlocal” strategy via
593
<tt class="docutils literal"><span class="pre">strategy="threadlocal"</span></tt>.</p>
595
<div class="section" id="args-accepted-args-no-longer-accepted">
596
<h2>*args Accepted, *args No Longer Accepted<a class="headerlink" href="#args-accepted-args-no-longer-accepted" title="Permalink to this headline">¶</a></h2>
597
<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>
598
is, if the method accepts a variable-length set of items
599
which represent a fixed structure, it takes <tt class="docutils literal"><span class="pre">\*args</span></tt>. If
600
the method accepts a variable-length set of items that are
601
data-driven, it takes <tt class="docutils literal"><span class="pre">[args]</span></tt>.</p>
603
<li><p class="first">The various Query.options() functions <tt class="docutils literal"><span class="pre">eagerload()</span></tt>,
604
<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>,
605
<tt class="docutils literal"><span class="pre">defer()</span></tt>, <tt class="docutils literal"><span class="pre">undefer()</span></tt> all accept variable-length
606
<tt class="docutils literal"><span class="pre">\*keys</span></tt> as their argument now, which allows a path to
607
be formulated using descriptors, ie.:</p>
608
<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>
610
<p>A single array argument is still accepted for backwards
613
<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>
614
methods accept a variable length *args, with a single
615
array accepted for backwards compatibility:</p>
616
<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>
617
<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>
620
<li><p class="first">the <tt class="docutils literal"><span class="pre">in_()</span></tt> method on columns and similar only accepts a
621
list argument now. It no longer accepts <tt class="docutils literal"><span class="pre">\*args</span></tt>.</p>
625
<div class="section" id="removed">
626
<h2>Removed<a class="headerlink" href="#removed" title="Permalink to this headline">¶</a></h2>
628
<li><p class="first"><strong>entity_name</strong> - This feature was always problematic and
629
rarely used. 0.5’s more deeply fleshed out use cases
630
revealed further issues with <tt class="docutils literal"><span class="pre">entity_name</span></tt> which led to
631
its removal. If different mappings are required for a
632
single class, break the class into separate subclasses and
633
map them separately. An example of this is at
634
[wiki:UsageRecipes/EntityName]. More information
635
regarding rationale is described at http://groups.google.c
636
om/group/sqlalchemy/browse_thread/thread/9e23a0641a88b96d?
639
<li><p class="first"><strong>get()/load() cleanup</strong></p>
640
<p>The <tt class="docutils literal"><span class="pre">load()</span></tt> method has been removed. It’s
641
functionality was kind of arbitrary and basically copied
642
from Hibernate, where it’s also not a particularly
643
meaningful method.</p>
644
<p>To get equivalent functionality:</p>
645
<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>
647
<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>
648
have been removed. <tt class="docutils literal"><span class="pre">Session.get()</span></tt> is redundant vs.
649
<tt class="docutils literal"><span class="pre">session.query(cls).get(id)</span></tt>.</p>
650
<p><tt class="docutils literal"><span class="pre">MapperExtension.get()</span></tt> is also removed (as is
651
<tt class="docutils literal"><span class="pre">MapperExtension.load()</span></tt>). To override the
652
functionality of <tt class="docutils literal"><span class="pre">Query.get()</span></tt>, use a subclass:</p>
653
<div class="highlight-python"><pre>class MyQuery(Query):
654
def get(self, ident):
657
session = sessionmaker(query_cls=MyQuery)()
659
ad1 = session.query(Address).get(1)</pre>
662
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.orm.relation()</span></tt></p>
663
<p>The following deprecated keyword arguments have been
665
<p>foreignkey, association, private, attributeext, is_backref</p>
666
<p>In particular, <tt class="docutils literal"><span class="pre">attributeext</span></tt> is replaced with
667
<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
670
<li><p class="first"><tt class="docutils literal"><span class="pre">session.Query()</span></tt></p>
671
<p>The following deprecated functions have been removed:</p>
672
<p>list, scalar, count_by, select_whereclause, get_by,
673
select_by, join_by, selectfirst, selectone, select,
674
execute, select_statement, select_text, join_to, join_via,
675
selectfirst_by, selectone_by, apply_max, apply_min,
676
apply_avg, apply_sum</p>
677
<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>,
678
<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
679
been removed. To target table aliases in <tt class="docutils literal"><span class="pre">Query</span></tt> to
680
result columns, use the <tt class="docutils literal"><span class="pre">aliased</span></tt> construct:</p>
681
<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>
682
<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>
683
<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>
686
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.orm.Mapper</span></tt></p>
689
<li>get_session() - this method was not very noticeable, but
690
had the effect of associating lazy loads with a
691
particular session even if the parent object was
692
entirely detached, when an extension such as
693
<tt class="docutils literal"><span class="pre">scoped_session()</span></tt> or the old <tt class="docutils literal"><span class="pre">SessionContextExt</span></tt>
694
was used. It’s possible that some applications which
695
relied upon this behavior will no longer work as
696
expected; but the better programming practice here is
697
to always ensure objects are present within sessions if
698
database access from their attributes are required.</li>
701
<li><p class="first"><tt class="docutils literal"><span class="pre">mapper(MyClass,</span> <span class="pre">mytable)</span></tt></p>
702
<p>Mapped classes no are longer instrumented with a “c” class
703
attribute; e.g. <tt class="docutils literal"><span class="pre">MyClass.c</span></tt></p>
705
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.orm.collections</span></tt></p>
706
<p>The _prepare_instrumentation alias for
707
prepare_instrumentation has been removed.</p>
709
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.orm</span></tt></p>
710
<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>
712
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.engine</span></tt></p>
713
<p>The alias from <tt class="docutils literal"><span class="pre">DefaultDialect.preexecute_sequences</span></tt> to
714
<tt class="docutils literal"><span class="pre">.preexecute_pk_sequences</span></tt> has been removed.</p>
715
<p>The deprecated engine_descriptors() function has been
718
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.activemapper</span></tt></p>
719
<p>Module removed.</p>
721
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.assignmapper</span></tt></p>
722
<p>Module removed.</p>
724
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.associationproxy</span></tt></p>
725
<p>Pass-through of keyword args on the proxy’s
726
<tt class="docutils literal"><span class="pre">.append(item,</span> <span class="pre">\**kw)</span></tt> has been removed and is now
727
simply <tt class="docutils literal"><span class="pre">.append(item)</span></tt></p>
729
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.selectresults</span></tt>,
730
<tt class="docutils literal"><span class="pre">sqlalchemy.mods.selectresults</span></tt></p>
731
<p>Modules removed.</p>
733
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.declarative</span></tt></p>
734
<p><tt class="docutils literal"><span class="pre">declared_synonym()</span></tt> removed.</p>
736
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.ext.sessioncontext</span></tt></p>
737
<p>Module removed.</p>
739
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.log</span></tt></p>
740
<p>The <tt class="docutils literal"><span class="pre">SADeprecationWarning</span></tt> alias to
741
<tt class="docutils literal"><span class="pre">sqlalchemy.exc.SADeprecationWarning</span></tt> has been removed.</p>
743
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.exc</span></tt></p>
744
<p><tt class="docutils literal"><span class="pre">exc.AssertionError</span></tt> has been removed and usage replaced
745
by the Python built-in of the same name.</p>
747
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.databases.mysql</span></tt></p>
748
<p>The deprecated <tt class="docutils literal"><span class="pre">get_version_info</span></tt> dialect method has
753
<div class="section" id="renamed-or-moved">
754
<h2>Renamed or Moved<a class="headerlink" href="#renamed-or-moved" title="Permalink to this headline">¶</a></h2>
756
<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>
757
<p>The module may still be imported under the old name until
760
<li><p class="first"><tt class="docutils literal"><span class="pre">FlushError</span></tt>, <tt class="docutils literal"><span class="pre">ConcurrentModificationError</span></tt>,
761
<tt class="docutils literal"><span class="pre">UnmappedColumnError</span></tt> -> sqlalchemy.orm.exc</p>
762
<p>These exceptions moved to the orm package. Importing
763
‘sqlalchemy.orm’ will install aliases in sqlalchemy.exc
764
for compatibility until 0.6.</p>
766
<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>
767
<p>This internal module was renamed. No longer needs to be
768
special cased when packaging SA with py2app and similar
769
tools that scan imports.</p>
771
<li><p class="first"><tt class="docutils literal"><span class="pre">session.Query().iterate_instances()</span></tt> ->
772
<tt class="docutils literal"><span class="pre">session.Query().instances()</span></tt>.</p>
776
<div class="section" id="deprecated">
777
<h2>Deprecated<a class="headerlink" href="#deprecated" title="Permalink to this headline">¶</a></h2>
779
<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>,
780
<tt class="docutils literal"><span class="pre">Session.save_or_update()</span></tt></p>
781
<p>All three replaced by <tt class="docutils literal"><span class="pre">Session.add()</span></tt></p>
783
<li><p class="first"><tt class="docutils literal"><span class="pre">sqlalchemy.PassiveDefault</span></tt></p>
784
<p>Use <tt class="docutils literal"><span class="pre">Column(server_default=...)</span></tt> Translates to
785
sqlalchemy.DefaultClause() under the hood.</p>
787
<li><p class="first"><tt class="docutils literal"><span class="pre">session.Query().iterate_instances()</span></tt>. It has been
788
renamed to <tt class="docutils literal"><span class="pre">instances()</span></tt>.</p>
798
<div id="docs-bottom-navigation" class="docs-navigation-links">
800
<a href="migration_06.html" title="previous chapter">What’s New in SQLAlchemy 0.6?</a>
802
<a href="migration_04.html" title="next chapter">What’s new in SQLAlchemy 0.4?</a>
804
<div id="docs-copyright">
805
© <a href="../copyright.html">Copyright</a> 2007-2013, the SQLAlchemy authors and contributors.
806
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
added
removed
doc/changelog/migration_05.html
