:released: Sun Aug 12 2007
.. change::
:tags: orm
:tickets:
Speed! Along with recent speedups to ResultProxy, total number of function
calls significantly reduced for large loads.
.. change::
:tags: orm
:tickets:
test/perf/masseagerload.py reports 0.4 as having the fewest number of
function calls across all SA versions (0.1, 0.2, and 0.3).
.. change::
:tags: orm
:tickets: 213
New collection_class api and implementation. Collections are
now instrumented via decorations rather than proxying. You can now have
collections that manage their own membership, and your class instance will
be directly exposed on the relation property. The changes are transparent
for most users.
.. change::
:tags: orm
:tickets:
InstrumentedList (as it was) is removed, and relation properties no
longer have 'clear()', '.data', or any other added methods beyond those
provided by the collection type. You are free, of course, to add them to
a custom class.
.. change::
:tags: orm
:tickets:
__setitem__-like assignments now fire remove events for the existing
value, if any.
.. change::
:tags: orm
:tickets:
dict-likes used as collection classes no longer need to change __iter__
semantics- itervalues() is used by default instead. This is a backwards
incompatible change.
.. change::
:tags: orm
:tickets:
Subclassing dict for a mapped collection is no longer needed in most
cases. orm.collections provides canned implementations that key objects
by a specified column or a custom function of your choice.
.. change::
:tags: orm
:tickets:
Collection assignment now requires a compatible type- assigning None to
clear a collection or assigning a list to a dict collection will now
raise an argument error.
.. change::
:tags: orm
:tickets:
AttributeExtension moved to interfaces, and .delete is now .remove The
event method signature has also been swapped around.
.. change::
:tags: orm
:tickets:
Major overhaul for Query:
.. change::
:tags: orm
:tickets:
All selectXXX methods are deprecated. Generative methods are now the
standard way to do things, i.e. filter(), filter_by(), all(), one(),
etc. Deprecated methods are docstring'ed with their new replacements.
.. change::
:tags: orm
:tickets: 643
Class-level properties are now usable as query elements... no more
'.c.'! "Class.c.propname" is now superseded by "Class.propname". All
clause operators are supported, as well as higher level operators such
as Class.prop==<some instance> for scalar attributes,
Class.prop.contains(<some instance>) and Class.prop.any(<some
expression>) for collection-based attributes (all are also
negatable). Table-based column expressions as well as columns mounted
on mapped classes via 'c' are of course still fully available and can be
freely mixed with the new attributes.
.. change::
:tags: orm
:tickets:
Removed ancient query.select_by_attributename() capability.
.. change::
:tags: orm
:tickets:
The aliasing logic used by eager loading has been generalized, so that
it also adds full automatic aliasing support to Query. It's no longer
necessary to create an explicit Alias to join to the same tables
multiple times; *even for self-referential relationships*.
- join() and outerjoin() take arguments "aliased=True". Yhis causes
their joins to be built on aliased tables; subsequent calls to
filter() and filter_by() will translate all table expressions (yes,
real expressions using the original mapped Table) to be that of the
Alias for the duration of that join() (i.e. until reset_joinpoint() or
another join() is called).
- join() and outerjoin() take arguments "id=<somestring>". When used
with "aliased=True", the id can be referenced by add_entity(cls,
id=<somestring>) so that you can select the joined instances even if
they're from an alias.
- join() and outerjoin() now work with self-referential relationships!
Using "aliased=True", you can join as many levels deep as desired,
i.e. query.join(['children', 'children'], aliased=True); filter
criterion will be against the rightmost joined table
.. change::
:tags: orm
:tickets: 660
Added query.populate_existing(), marks the query to reload all
attributes and collections of all instances touched in the query,
including eagerly-loaded entities.
.. change::
:tags: orm
:tickets:
Added eagerload_all(), allows eagerload_all('x.y.z') to specify eager
loading of all properties in the given path.
.. change::
:tags: orm
:tickets:
Major overhaul for Session:
.. change::
:tags: orm
:tickets:
New function which "configures" a session called "sessionmaker()". Send
various keyword arguments to this function once, returns a new class
which creates a Session against that stereotype.
.. change::
:tags: orm
:tickets:
SessionTransaction removed from "public" API. You now can call begin()/
commit()/rollback() on the Session itself.
.. change::
:tags: orm
:tickets:
Session also supports SAVEPOINT transactions; call begin_nested().
.. change::
:tags: orm
:tickets:
Session supports two-phase commit behavior when vertically or
horizontally partitioning (i.e., using more than one engine). Use
twophase=True.
.. change::
:tags: orm
:tickets:
Session flag "transactional=True" produces a session which always places
itself into a transaction when first used. Upon commit(), rollback() or
close(), the transaction ends; but begins again on the next usage.
.. change::
:tags: orm
:tickets:
Session supports "autoflush=True". This issues a flush() before each
query. Use in conjunction with transactional, and you can just
save()/update() and then query, the new objects will be there. Use
commit() at the end (or flush() if non-transactional) to flush remaining
changes.
.. change::
:tags: orm
:tickets:
New scoped_session() function replaces SessionContext and assignmapper.
Builds onto "sessionmaker()" concept to produce a class whose Session()
construction returns the thread-local session. Or, call all Session
methods as class methods, i.e. Session.save(foo); Session.commit().
just like the old "objectstore" days.
.. change::
:tags: orm
:tickets:
Added new "binds" argument to Session to support configuration of
multiple binds with sessionmaker() function.
.. change::
:tags: orm
:tickets:
A rudimental SessionExtension class has been added, allowing
user-defined functionality to take place at flush(), commit(), and
rollback() boundaries.
.. change::
:tags: orm
:tickets:
Query-based relation()s available with dynamic_loader(). This is a
*writable* collection (supporting append() and remove()) which is also a
live Query object when accessed for reads. Ideal for dealing with very
large collections where only partial loading is desired.
.. change::
:tags: orm
:tickets:
flush()-embedded inline INSERT/UPDATE expressions. Assign any SQL
expression, like "sometable.c.column + 1", to an instance's attribute.
Upon flush(), the mapper detects the expression and embeds it directly in
the INSERT or UPDATE statement; the attribute gets deferred on the
instance so it loads the new value the next time you access it.
.. change::
:tags: orm
:tickets: 618
A rudimental sharding (horizontal scaling) system is introduced. This
system uses a modified Session which can distribute read and write
operations among multiple databases, based on user-defined functions
defining the "sharding strategy". Instances and their dependents can be
distributed and queried among multiple databases based on attribute
values, round-robin approaches or any other user-defined
system.
.. change::
:tags: orm
:tickets: 659
Eager loading has been enhanced to allow even more joins in more places.
It now functions at any arbitrary depth along self-referential and
cyclical structures. When loading cyclical structures, specify
"join_depth" on relation() indicating how many times you'd like the table
to join to itself; each level gets a distinct table alias. The alias
names themselves are generated at compile time using a simple counting
scheme now and are a lot easier on the eyes, as well as of course
completely deterministic.
.. change::
:tags: orm
:tickets: 211
Added composite column properties. This allows you to create a type which
is represented by more than one column, when using the ORM. Objects of
the new type are fully functional in query expressions, comparisons,
query.get() clauses, etc. and act as though they are regular single-column
scalars... except they're not! Use the function composite(cls, \*columns)
inside of the mapper's "properties" dict, and instances of cls will be
created/mapped to a single attribute, comprised of the values corresponding
to \*columns.
.. change::
:tags: orm
:tickets:
Improved support for custom column_property() attributes which feature
correlated subqueries, works better with eager loading now.
.. change::
:tags: orm
:tickets: 611
Primary key "collapse" behavior; the mapper will analyze all columns in
its given selectable for primary key "equivalence", that is, columns which
are equivalent via foreign key relationship or via an explicit
inherit_condition. primarily for joined-table inheritance scenarios where
different named PK columns in inheriting tables should "collapse" into a
single-valued (or fewer-valued) primary key. Fixes things like.
.. change::
:tags: orm
:tickets:
Joined-table inheritance will now generate the primary key columns of all
inherited classes against the root table of the join only. This implies
that each row in the root table is distinct to a single instance. If for
some rare reason this is not desirable, explicit primary_key settings on
individual mappers will override it.
.. change::
:tags: orm
:tickets:
When "polymorphic" flags are used with joined-table or single-table
inheritance, all identity keys are generated against the root class of the
inheritance hierarchy; this allows query.get() to work polymorphically
using the same caching semantics as a non-polymorphic get. Note that this
currently does not work with concrete inheritance.
.. change::
:tags: orm
:tickets:
Secondary inheritance loading: polymorphic mappers can be constructed
*without* a select_table argument. inheriting mappers whose tables were
not represented in the initial load will issue a second SQL query
immediately, once per instance (i.e. not very efficient for large lists),
in order to load the remaining columns.
.. change::
:tags: orm
:tickets:
Secondary inheritance loading can also move its second query into a
column-level "deferred" load, via the "polymorphic_fetch" argument, which
can be set to 'select' or 'deferred'
.. change::
:tags: orm
:tickets: 696
It's now possible to map only a subset of available selectable columns
onto mapper properties, using include_columns/exclude_columns..
.. change::
:tags: orm
:tickets:
Added undefer_group() MapperOption, sets a set of "deferred" columns
joined by a "group" to load as "undeferred".
.. change::
:tags: orm
:tickets:
Rewrite of the "deterministic alias name" logic to be part of the SQL
layer, produces much simpler alias and label names more in the style of
Hibernate
.. change::
:tags: sql
:tickets:
Speed! Clause compilation as well as the mechanics of SQL constructs have
been streamlined and simplified to a significant degree, for a 20-30%
improvement of the statement construction/compilation overhead of 0.3.
.. change::
:tags: sql
:tickets:
All "type" keyword arguments, such as those to bindparam(), column(),
Column(), and func.<something>(), renamed to "type\_". Those objects still
name their "type" attribute as "type".
.. change::
:tags: sql
:tickets:
case_sensitive=(True|False) setting removed from schema items, since
checking this state added a lot of method call overhead and there was no
decent reason to ever set it to False. Table and column names which are
all lower case will be treated as case-insensitive (yes we adjust for
Oracle's UPPERCASE style too).
.. change::
:tags: transactions
:tickets:
Added context manager (with statement) support for transactions.
.. change::
:tags: transactions
:tickets:
Added support for two phase commit, works with mysql and postgres so far.
.. change::
:tags: transactions
:tickets:
Added a subtransaction implementation that uses savepoints.
.. change::
:tags: transactions
:tickets:
Added support for savepoints.
.. change::
:tags: metadata
:tickets:
Tables can be reflected from the database en-masse without declaring
them in advance. MetaData(engine, reflect=True) will load all tables
present in the database, or use metadata.reflect() for finer control.
.. change::
:tags: metadata
:tickets:
DynamicMetaData has been renamed to ThreadLocalMetaData
.. change::
:tags: metadata
:tickets:
The ThreadLocalMetaData constructor now takes no arguments.
.. change::
:tags: metadata
:tickets:
BoundMetaData has been removed- regular MetaData is equivalent
.. change::
:tags: metadata
:tickets: 646
Numeric and Float types now have an "asdecimal" flag; defaults to True for
Numeric, False for Float. When True, values are returned as
decimal.Decimal objects; when False, values are returned as float(). The
defaults of True/False are already the behavior for PG and MySQL's DBAPI
modules.
.. change::
:tags: metadata
:tickets: 475
New SQL operator implementation which removes all hardcoded operators from
expression structures and moves them into compilation; allows greater
flexibility of operator compilation; for example, "+" compiles to "||"
when used in a string context, or "concat(a,b)" on MySQL; whereas in a
numeric context it compiles to "+". Fixes.
.. change::
:tags: metadata
:tickets:
"Anonymous" alias and label names are now generated at SQL compilation
time in a completely deterministic fashion... no more random hex IDs
.. change::
:tags: metadata
:tickets:
Significant architectural overhaul to SQL elements (ClauseElement). All
elements share a common "mutability" framework which allows a consistent
approach to in-place modifications of elements as well as generative
behavior. Improves stability of the ORM which makes heavy usage of
mutations to SQL expressions.
.. change::
:tags: metadata
:tickets:
select() and union()'s now have "generative" behavior. Methods like
order_by() and group_by() return a *new* instance - the original instance
is left unchanged. Non-generative methods remain as well.
.. change::
:tags: metadata
:tickets: 569, 52
The internals of select/union vastly simplified- all decision making
regarding "is subquery" and "correlation" pushed to SQL generation phase.
select() elements are now *never* mutated by their enclosing containers or
by any dialect's compilation process
.. change::
:tags: metadata
:tickets:
select(scalar=True) argument is deprecated; use select(..).as_scalar().
The resulting object obeys the full "column" interface and plays better
within expressions.
.. change::
:tags: metadata
:tickets: 504
Added select().with_prefix('foo') allowing any set of keywords to be
placed before the columns clause of the SELECT
.. change::
:tags: metadata
:tickets: 686
Added array slice support to row[<index>]
.. change::
:tags: metadata
:tickets:
Result sets make a better attempt at matching the DBAPI types present in
cursor.description to the TypeEngine objects defined by the dialect, which
are then used for result-processing. Note this only takes effect for
textual SQL; constructed SQL statements always have an explicit type map.
.. change::
:tags: metadata
:tickets:
Result sets from CRUD operations close their underlying cursor immediately
and will also autoclose the connection if defined for the operation; this
allows more efficient usage of connections for successive CRUD operations
with less chance of "dangling connections".
.. change::
:tags: metadata
:tickets: 559
Column defaults and onupdate Python functions (i.e. passed to
ColumnDefault) may take zero or one arguments; the one argument is the
ExecutionContext, from which you can call "context.parameters[someparam]"
to access the other bind parameter values affixed to the statement. The connection used for the execution is available as well
so that you can pre-execute statements.
.. change::
:tags: metadata
:tickets:
Added "explicit" create/drop/execute support for sequences (i.e. you can
pass a "connectable" to each of those methods on Sequence).
.. change::
:tags: metadata
:tickets:
Better quoting of identifiers when manipulating schemas.
.. change::
:tags: metadata
:tickets:
Standardized the behavior for table reflection where types can't be
located; NullType is substituted instead, warning is raised.
.. change::
:tags: metadata
:tickets: 606
ColumnCollection (i.e. the 'c' attribute on tables) follows dictionary
semantics for "__contains__"
.. change::
:tags: engines
:tickets:
Speed! The mechanics of result processing and bind parameter processing
have been overhauled, streamlined and optimized to issue as little method
calls as possible. Bench tests for mass INSERT and mass rowset iteration
both show 0.4 to be over twice as fast as 0.3, using 68% fewer function
calls.
.. change::
:tags: engines
:tickets:
You can now hook into the pool lifecycle and run SQL statements or other
logic at new each DBAPI connection, pool check-out and check-in.
.. change::
:tags: engines
:tickets:
Connections gain a .properties collection, with contents scoped to the
lifetime of the underlying DBAPI connection
.. change::
:tags: engines
:tickets:
Removed auto_close_cursors and disallow_open_cursors arguments from Pool;
reduces overhead as cursors are normally closed by ResultProxy and
Connection.
.. change::
:tags: extensions
:tickets:
proxyengine is temporarily removed, pending an actually working
replacement.
.. change::
:tags: extensions
:tickets:
SelectResults has been replaced by Query. SelectResults /
SelectResultsExt still exist but just return a slightly modified Query
object for backwards-compatibility. join_to() method from SelectResults
isn't present anymore, need to use join().
.. change::
:tags: mysql
:tickets:
Table and column names loaded via reflection are now Unicode.
.. change::
:tags: mysql
:tickets:
All standard column types are now supported, including SET.
.. change::
:tags: mysql
:tickets:
Table reflection can now be performed in as little as one round-trip.
.. change::
:tags: mysql
:tickets:
ANSI and ANSI_QUOTES sql modes are now supported.
.. change::
:tags: mysql
:tickets:
Indexes are now reflected.
.. change::
:tags: postgres
:tickets:
Added PGArray datatype for using postgres array datatypes.
.. change::
:tags: oracle
:tickets: 507
Very rudimental support for OUT parameters added; use sql.outparam(name,
type) to set up an OUT parameter, just like bindparam(); after execution,
values are available via result.out_parameters dictionary.
=============
0.5 Changelog
=============
.. changelog::
:version: 0.5.9
:released:
.. change::
:tags: sql
:tickets: 1661
Fixed erroneous self_group() call in expression package.
.. changelog::