Sqlalchemy

:released: Sun May 17 2009

.. change::
:tags: orm
:tickets: 1398

Significant performance enhancements regarding Sessions/flush()
in conjunction with large mapper graphs, large numbers of
objects:

- Removed all* O(N) scanning behavior from the flush() process,
i.e. operations that were scanning the full session,
including an extremely expensive one that was erroneously
assuming primary key values were changing when this
was not the case.

* one edge case remains which may invoke a full scan,
if an existing primary key attribute is modified
to a new value.

- The Session's "weak referencing" behavior is now *full* -
no strong references whatsoever are made to a mapped object
or related items/collections in its __dict__. Backrefs and
other cycles in objects no longer affect the Session's ability
to lose all references to unmodified objects. Objects with
pending changes still are maintained strongly until flush.


The implementation also improves performance by moving
the "resurrection" process of garbage collected items
to only be relevant for mappings that map "mutable"
attributes (i.e. PickleType, composite attrs). This removes
overhead from the gc process and simplifies internal
behavior.

If a "mutable" attribute change is the sole change on an object
which is then dereferenced, the mapper will not have access to
other attribute state when the UPDATE is issued. This may present
itself differently to some MapperExtensions.

The change also affects the internal attribute API, but not
the AttributeExtension interface nor any of the publicly
documented attribute functions.

- The unit of work no longer generates a graph of "dependency"
processors for the full graph of mappers during flush(), instead
creating such processors only for those mappers which represent
objects with pending changes. This saves a tremendous number
of method calls in the context of a large interconnected
graph of mappers.

- Cached a wasteful "table sort" operation that previously
occurred multiple times per flush, also removing significant
method call count from flush().

- Other redundant behaviors have been simplified in
mapper._save_obj().

.. change::
:tags: orm
:tickets:

Modified query_cls on DynamicAttributeImpl to accept a full
mixin version of the AppenderQuery, which allows subclassing
the AppenderMixin.

.. change::
:tags: orm
:tickets: 1300

The "polymorphic discriminator" column may be part of a
primary key, and it will be populated with the correct
discriminator value.

.. change::
:tags: orm
:tickets:

Fixed the evaluator not being able to evaluate IS NULL clauses.

.. change::
:tags: orm
:tickets: 1352

Fixed the "set collection" function on "dynamic" relations to
initiate events correctly. Previously a collection could only
be assigned to a pending parent instance, otherwise modified
events would not be fired correctly. Set collection is now
compatible with merge(), fixes.

.. change::
:tags: orm
:tickets:

Allowed pickling of PropertyOption objects constructed with
instrumented descriptors; previously, pickle errors would occur
when pickling an object which was loaded with a descriptor-based
option, such as query.options(eagerload(MyClass.foo)).

.. change::
:tags: orm
:tickets: 1357

Lazy loader will not use get() if the "lazy load" SQL clause
matches the clause used by get(), but contains some parameters
hardcoded. Previously the lazy strategy would fail with the
get(). Ideally get() would be used with the hardcoded
parameters but this would require further development.

.. change::
:tags: orm
:tickets: 1391

MapperOptions and other state associated with query.options()
is no longer bundled within callables associated with each
lazy/deferred-loading attribute during a load.
The options are now associated with the instance's
state object just once when it's populated. This removes
the need in most cases for per-instance/attribute loader
objects, improving load speed and memory overhead for
individual instances.

.. change::
:tags: orm
:tickets: 1360

Fixed another location where autoflush was interfering
with session.merge(). autoflush is disabled completely
for the duration of merge() now.

.. change::
:tags: orm
:tickets: 1406

Fixed bug which prevented "mutable primary key" dependency
logic from functioning properly on a one-to-one
relation().

.. change::
:tags: orm
:tickets:

Fixed bug in relation(), introduced in 0.5.3,
whereby a self referential relation
from a base class to a joined-table subclass would
not configure correctly.

.. change::
:tags: orm
:tickets:

Fixed obscure mapper compilation issue when inheriting
mappers are used which would result in un-initialized
attributes.

.. change::
:tags: orm
:tickets:

Fixed documentation for session weak_identity_map -
the default value is True, indicating a weak
referencing map in use.

.. change::
:tags: orm
:tickets: 1376

Fixed a unit of work issue whereby the foreign
key attribute on an item contained within a collection
owned by an object being deleted would not be set to
None if the relation() was self-referential.

.. change::
:tags: orm
:tickets: 1378

Fixed Query.update() and Query.delete() failures with eagerloaded
relations.

.. change::
:tags: orm
:tickets:

It is now an error to specify both columns of a binary primaryjoin
condition in the foreign_keys or remote_side collection. Whereas
previously it was just nonsensical, but would succeed in a
non-deterministic way.

.. change::
:tags: ticket: 594, 1341, schema
:tickets:

Added a quote_schema() method to the IdentifierPreparer class
so that dialects can override how schemas get handled. This
enables the MSSQL dialect to treat schemas as multipart
identifiers, such as 'database.owner'.

.. change::
:tags: sql
:tickets:

Back-ported the "compiler" extension from SQLA 0.6. This
is a standardized interface which allows the creation of custom
ClauseElement subclasses and compilers. In particular it's
handy as an alternative to text() when you'd like to
build a construct that has database-specific compilations.
See the extension docs for details.

.. change::
:tags: sql
:tickets: 1413

Exception messages are truncated when the list of bound
parameters is larger than 10, preventing enormous
multi-page exceptions from filling up screens and logfiles
for large executemany() statements.

.. change::
:tags: sql
:tickets:

``sqlalchemy.extract()`` is now dialect sensitive and can
extract components of timestamps idiomatically across the
supported databases, including SQLite.

.. change::
:tags: sql
:tickets: 1353

Fixed __repr__() and other _get_colspec() methods on
ForeignKey constructed from __clause_element__() style
construct (i.e. declarative columns).

.. change::
:tags: mysql
:tickets: 1405

Reflecting a FOREIGN KEY construct will take into account
a dotted schema.tablename combination, if the foreign key
references a table in a remote schema.

.. change::
:tags: mssql
:tickets:

Modified how savepoint logic works to prevent it from
stepping on non-savepoint oriented routines. Savepoint
support is still very experimental.

.. change::
:tags: mssql
:tickets: 1310

Added in reserved words for MSSQL that covers version 2008
and all prior versions.

.. change::
:tags: mssql
:tickets: 1343

Corrected problem with information schema not working with a
binary collation based database. Cleaned up information schema
since it is only used by mssql now.

.. change::
:tags: sqlite
:tickets: 1402

Corrected the SLBoolean type so that it properly treats only 1
as True.

.. change::
:tags: sqlite
:tickets: 1273

Corrected the float type so that it correctly maps to a
SLFloat type when being reflected.

.. change::
:tags: extensions
:tickets: 1379

Fixed adding of deferred or other column properties to a
declarative class.

.. changelog::

:released: Tue Mar 24 2009

.. change::
:tags: orm
:tickets: 1315

The "objects" argument to session.flush() is deprecated.
State which represents the linkage between a parent and
child object does not support "flushed" status on
one side of the link and not the other, so supporting
this operation leads to misleading results.

.. change::
:tags: orm
:tickets:

Query now implements __clause_element__() which produces
its selectable, which means a Query instance can be accepted
in many SQL expressions, including col.in_(query),
union(query1, query2), select([foo]).select_from(query),
etc.

.. change::
:tags: orm
:tickets: 1337

Query.join() can now construct multiple FROM clauses, if
needed. Such as, query(A, B).join(A.x).join(B.y)
might say SELECT A.*, B.* FROM A JOIN X, B JOIN Y.
Eager loading can also tack its joins onto those
multiple FROM clauses.

.. change::
:tags: orm
:tickets: 1347

Fixed bug in dynamic_loader() where append/remove events
after construction time were not being propagated to the
UOW to pick up on flush().

.. change::
:tags: orm
:tickets:

Fixed bug where column_prefix wasn't being checked before
not mapping an attribute that already had class-level
name present.

.. change::
:tags: orm
:tickets: 1315

a session.expire() on a particular collection attribute
will clear any pending backref additions as well, so that
the next access correctly returns only what was present
in the database. Presents some degree of a workaround for, although we are considering removing the
flush([objects]) feature altogether.

.. change::
:tags: orm
:tickets:

Session.scalar() now converts raw SQL strings to text()
the same way Session.execute() does and accepts same
alternative \**kw args.

.. change::
:tags: orm
:tickets:

improvements to the "determine direction" logic of
relation() such that the direction of tricky situations
like mapper(A.join(B)) -> relation-> mapper(B) can be
determined.

.. change::
:tags: orm
:tickets: 1306

When flushing partial sets of objects using session.flush([somelist]),
pending objects which remain pending after the operation won't
inadvertently be added as persistent.

.. change::
:tags: orm
:tickets: 1314

Added "post_configure_attribute" method to InstrumentationManager,
so that the "listen_for_events.py" example works again.

.. change::
:tags: orm
:tickets:

a forward and complementing backwards reference which are both
of the same direction, i.e. ONETOMANY or MANYTOONE,
is now detected, and an error message is raised.
Saves crazy CircularDependencyErrors later on.

.. change::
:tags: orm
:tickets:

Fixed bugs in Query regarding simultaneous selection of
multiple joined-table inheritance entities with common base
classes:

- previously the adaption applied to "B" on
"A JOIN B" would be erroneously partially applied
to "A".

- comparisons on relations (i.e. A.related==someb)
were not getting adapted when they should.

- Other filterings, like
query(A).join(A.bs).filter(B.foo=='bar'), were erroneously
adapting "B.foo" as though it were an "A".

.. change::
:tags: orm
:tickets: 1325

Fixed adaptation of EXISTS clauses via any(), has(), etc.
in conjunction with an aliased object on the left and
of_type() on the right.

.. change::
:tags: orm
:tickets:

Added an attribute helper method ``set_committed_value`` in
sqlalchemy.orm.attributes. Given an object, attribute name,
and value, will set the value on the object as part of its
"committed" state, i.e. state that is understood to have
been loaded from the database. Helps with the creation of
homegrown collection loaders and such.

.. change::
:tags: orm
:tickets:

Query won't fail with weakref error when a non-mapper/class
instrumented descriptor is passed, raises
"Invalid column expression".

.. change::
:tags: orm
:tickets:

Query.group_by() properly takes into account aliasing applied
to the FROM clause, such as with select_from(), using
with_polymorphic(), or using from_self().

.. change::
:tags: sql
:tickets:

An alias() of a select() will convert to a "scalar subquery"
when used in an unambiguously scalar context, i.e. it's used
in a comparison operation. This applies to
the ORM when using query.subquery() as well.

.. change::
:tags: sql
:tickets: 1302

Fixed missing _label attribute on Function object, others
when used in a select() with use_labels (such as when used
in an ORM column_property()).

.. change::
:tags: sql
:tickets: 1309

anonymous alias names now truncate down to the max length
allowed by the dialect. More significant on DBs like
Oracle with very small character limits.

.. change::
:tags: sql
:tickets:

the __selectable__() interface has been replaced entirely
by __clause_element__().

.. change::
:tags: sql
:tickets: 1299

The per-dialect cache used by TypeEngine to cache
dialect-specific types is now a WeakKeyDictionary.
This to prevent dialect objects from
being referenced forever for an application that
creates an arbitrarily large number of engines
or dialects. There is a small performance penalty
which will be resolved in 0.6.

.. change::
:tags: sqlite
:tickets:

Fixed SQLite reflection methods so that non-present
cursor.description, which triggers an auto-cursor
close, will be detected so that no results doesn't
fail on recent versions of pysqlite which raise
an error when fetchone() called with no rows present.

.. change::
:tags: postgresql
:tickets:

Index reflection won't fail when an index with
multiple expressions is encountered.

.. change::
:tags: postgresql
:tickets: 1327

Added PGUuid and PGBit types to
sqlalchemy.databases.postgres.

.. change::
:tags: postgresql
:tickets: 1327

Refection of unknown PG types won't crash when those
types are specified within a domain.

.. change::
:tags: mssql
:tickets:

Preliminary support for pymssql 1.0.1

.. change::
:tags: mssql
:tickets:

Corrected issue on mssql where max_identifier_length was
not being respected.

.. change::
:tags: extensions
:tickets:

Fixed a recursive pickling issue in serializer, triggered
by an EXISTS or other embedded FROM construct.

.. change::
:tags: extensions
:tickets:

Declarative locates the "inherits" class using a search
through __bases__, to skip over mixins that are local
to subclasses.

.. change::
:tags: extensions
:tickets:

Declarative figures out joined-table inheritance primary join
condition even if "inherits" mapper argument is given
explicitly.

.. change::
:tags: extensions
:tickets:

Declarative will properly interpret the "foreign_keys" argument
on a backref() if it's a string.

.. change::
:tags: extensions
:tickets:

Declarative will accept a table-bound column as a property
when used in conjunction with __table__, if the column is already
present in __table__. The column will be remapped to the given
key the same way as when added to the mapper() properties dict.

.. changelog::

:released: Sat Jan 24 2009

.. change::
:tags: orm
:tickets:

Further refined 0.5.1's warning about delete-orphan cascade
placed on a many-to-many relation. First, the bad news:
the warning will apply to both many-to-many as well as
many-to-one relations. This is necessary since in both
cases, SQLA does not scan the full set of potential parents
when determining "orphan" status - for a persistent object
it only detects an in-python de-association event to establish
the object as an "orphan". Next, the good news: to support
one-to-one via a foreign key or association table, or to
support one-to-many via an association table, a new flag
single_parent=True may be set which indicates objects
linked to the relation are only meant to have a single parent.
The relation will raise an error if multiple parent-association
events occur within Python.

.. change::
:tags: orm
:tickets: 1292

Adjusted the attribute instrumentation change from 0.5.1 to
fully establish instrumentation for subclasses where the mapper
was created after the superclass had already been fully
instrumented.

.. change::
:tags: orm
:tickets:

Fixed bug in delete-orphan cascade whereby two one-to-one
relations from two different parent classes to the same target
class would prematurely expunge the instance.

.. change::
:tags: orm
:tickets:

Fixed an eager loading bug whereby self-referential eager
loading would prevent other eager loads, self referential or not,
from joining to the parent JOIN properly. Thanks to Alex K
for creating a great test case.

.. change::
:tags: orm
:tickets:

session.expire() and related methods will not expire() unloaded
deferred attributes. This prevents them from being needlessly
loaded when the instance is refreshed.

.. change::
:tags: orm
:tickets: 1293

query.join()/outerjoin() will now properly join an aliased()
construct to the existing left side, even if query.from_self()
or query.select_from(someselectable) has been called.

.. change::
:tags: sql
:tickets: 1284

Further fixes to the "percent signs and spaces in column/table
names" functionality.

.. change::
:tags: mssql
:tickets: 1291

Restored convert_unicode handling. Results were being passed
on through without conversion.

.. change::
:tags: mssql
:tickets: 1282

Really fixing the decimal handling this time..

.. change::
:tags: Ticket:1289, mssql
:tickets:

Modified table reflection code to use only kwargs when
constructing tables.

.. changelog::

:released: Sat Jan 17 2009

.. change::
:tags: orm
:tickets:

Removed an internal join cache which could potentially leak
memory when issuing query.join() repeatedly to ad-hoc
selectables.

.. change::
:tags: orm
:tickets:

The "clear()", "save()", "update()", "save_or_update()"
Session methods have been deprecated, replaced by
"expunge_all()" and "add()". "expunge_all()" has also
been added to ScopedSession.

.. change::
:tags: orm
:tickets:

Modernized the "no mapped table" exception and added a more
explicit __table__/__tablename__ exception to declarative.

.. change::
:tags: orm
:tickets: 1237

Concrete inheriting mappers now instrument attributes which
are inherited from the superclass, but are not defined for
the concrete mapper itself, with an InstrumentedAttribute that
issues a descriptive error when accessed.

.. change::
:tags: orm
:tickets: 1237, 781

Added a new `relation()` keyword `back_populates`. This
allows configuration of backreferences using explicit
relations. This is required when creating
bidirectional relations between a hierarchy of concrete
mappers and another class.

.. change::
:tags: orm
:tickets: 1237

Test coverage added for `relation()` objects specified on
concrete mappers.

.. change::
:tags: orm
:tickets: 1276

Query.from_self() as well as query.subquery() both disable
the rendering of eager joins inside the subquery produced.
The "disable all eager joins" feature is available publicly
via a new query.enable_eagerloads() generative.

.. change::
:tags: orm
:tickets:

Added a rudimental series of set operations to Query that
receive Query objects as arguments, including union(),
union_all(), intersect(), except_(), intersect_all(),
except_all(). See the API documentation for
Query.union() for examples.

.. change::
:tags: orm
:tickets:

Fixed bug that prevented Query.join() and eagerloads from
attaching to a query that selected from a union or aliased union.

.. change::
:tags: orm
:tickets: 1237

A short documentation example added for bidirectional
relations specified on concrete mappers.

.. change::
:tags: orm
:tickets: 1269

Mappers now instrument class attributes upon construction
with the final InstrumentedAttribute object which remains
persistent. The `_CompileOnAttr`/`__getattribute__()`
methodology has been removed. The net effect is that
Column-based mapped class attributes can now be used fully
at the class level without invoking a mapper compilation
operation, greatly simplifying typical usage patterns
within declarative.

.. change::
:tags: orm
:tickets:

ColumnProperty (and front-end helpers such as ``deferred``) no
longer ignores unknown \**keyword arguments.

.. change::
:tags: orm
:tickets:

Fixed a bug with the unitofwork's "row switch" mechanism,
i.e. the conversion of INSERT/DELETE into an UPDATE, when
combined with joined-table inheritance and an object
which contained no defined values for the child table where
an UPDATE with no SET clause would be rendered.

.. change::
:tags: orm
:tickets: 1281

Using delete-orphan on a many-to-many relation is deprecated.
This produces misleading or erroneous results since SQLA does
not retrieve the full list of "parents" for m2m. To get delete-orphan
behavior with an m2m table, use an explicit association class
so that the individual association row is treated as a parent.

.. change::
:tags: orm
:tickets: 1281

delete-orphan cascade always requires delete cascade. Specifying
delete-orphan without delete now raises a deprecation warning.

.. change::
:tags: sql
:tickets: 1256

Improved the methodology to handling percent signs in column
names from. Added more tests. MySQL and
PostgreSQL dialects still do not issue correct CREATE TABLE
statements for identifiers with percent signs in them.

.. change::
:tags: schema
:tickets: 1214

Index now accepts column-oriented InstrumentedAttributes
(i.e. column-based mapped class attributes) as column
arguments.

.. change::
:tags: schema
:tickets:

Column with no name (as in declarative) won't raise a
NoneType error when its string output is requested
(such as in a stack trace).

.. change::
:tags: schema
:tickets: 1278

Fixed bug when overriding a Column with a ForeignKey
on a reflected table, where derived columns (i.e. the
"virtual" columns of a select, etc.) would inadvertently
call upon schema-level cleanup logic intended only
for the original column.

.. change::
:tags: declarative
:tickets:

Can now specify Column objects on subclasses which have no
table of their own (i.e. use single table inheritance).
The columns will be appended to the base table, but only
mapped by the subclass.

.. change::
:tags: declarative
:tickets:

For both joined and single inheriting subclasses, the subclass
will only map those columns which are already mapped on the
superclass and those explicit on the subclass. Other
columns that are present on the `Table` will be excluded
from the mapping by default, which can be disabled
by passing a blank `exclude_properties` collection to the
`__mapper_args__`. This is so that single-inheriting
classes which define their own columns are the only classes
to map those columns. The effect is actually a more organized
mapping than you'd normally get with explicit `mapper()`
calls unless you set up the `exclude_properties` arguments
explicitly.

.. change::
:tags: declarative
:tickets:

It's an error to add new Column objects to a declarative class
that specified an existing table using __table__.

.. change::
:tags: mysql
:tickets:

Added the missing keywords from MySQL 4.1 so they get escaped
properly.

.. change::
:tags: mssql
:tickets: 1280

Corrected handling of large decimal values with more robust
tests. Removed string manipulation on floats.

.. change::
:tags: mssql
:tickets:

Modified the do_begin handling in mssql to use the Cursor not
the Connection so it is DBAPI compatible.

.. change::
:tags: mssql
:tickets:

Corrected SAVEPOINT support on adodbapi by changing the
handling of savepoint_release, which is unsupported on mssql.

.. changelog::

:released: Tue Jan 06 2009

.. change::
:tags: general
:tickets:

Documentation has been converted to Sphinx. In particular,
the generated API documentation has been constructed into a
full blown "API Reference" section which organizes editorial
documentation combined with generated docstrings. Cross
linking between sections and API docs are vastly improved, a
javascript-powered search feature is provided, and a full
index of all classes, functions and members is provided.

.. change::
:tags: general
:tickets:

setup.py now imports setuptools only optionally. If not
present, distutils is used. The new "pip" installer is
recommended over easy_install as it installs in a more
simplified way.

.. change::
:tags: general
:tickets:

added an extremely basic illustration of a PostGIS integration
to the examples folder.

.. change::
:tags: orm
:tickets:

Query.with_polymorphic() now accepts a third argument
"discriminator" which will replace the value of
mapper.polymorphic_on for that query. Mappers themselves no
longer require polymorphic_on to be set, even if the mapper
has a polymorphic_identity. When not set, the mapper will
load non-polymorphically by default. Together, these two
features allow a non-polymorphic concrete inheritance setup to
use polymorphic loading on a per-query basis, since concrete
setups are prone to many issues when used polymorphically in
all cases.

.. change::
:tags: orm
:tickets:

dynamic_loader accepts a query_class= to customize the Query
classes used for both the dynamic collection and the queries
built from it.

.. change::
:tags: orm
:tickets: 1079

query.order_by() accepts None which will remove any pending
order_by state from the query, as well as cancel out any
mapper/relation configured ordering. This is primarily useful
for overriding the ordering specified on a dynamic_loader().

.. change::
:tags: sql
:tickets: 935

RowProxy objects can be used in place of dictionary arguments
sent to connection.execute() and friends.

.. change::
:tags: dialect
:tickets:

Added a new description_encoding attribute on the dialect that
is used for encoding the column name when processing the
metadata. This usually defaults to utf-8.

.. change::
:tags: mssql
:tickets:

Added in a new MSGenericBinary type. This maps to the Binary
type so it can implement the specialized behavior of treating
length specified types as fixed-width Binary types and
non-length types as an unbound variable length Binary type.

.. change::
:tags: mssql
:tickets: 1249

Added in new types: MSVarBinary and MSImage.

.. change::
:tags: mssql
:tickets:

Added in the MSReal, MSNText, MSSmallDateTime, MSTime,
MSDateTimeOffset, and MSDateTime2 types

.. change::
:tags: sqlite
:tickets: 1266

Table reflection now stores the actual DefaultClause value for
the column.

.. change::
:tags: sqlite
:tickets:

bugfixes, behavioral changes

.. change::
:tags: orm
:tickets:

Exceptions raised during compile_mappers() are now preserved
to provide "sticky behavior" - if a hasattr() call on a
pre-compiled mapped attribute triggers a failing compile and
suppresses the exception, subsequent compilation is blocked
and the exception will be reiterated on the next compile()
call. This issue occurs frequently when using declarative.

.. change::
:tags: orm
:tickets:

property.of_type() is now recognized on a single-table
inheriting target, when used in the context of
prop.of_type(..).any()/has(), as well as
query.join(prop.of_type(...)).

.. change::
:tags: orm
:tickets:

query.join() raises an error when the target of the join
doesn't match the property-based attribute - while it's
unlikely anyone is doing this, the SQLAlchemy author was
guilty of this particular loosey-goosey behavior.

.. change::
:tags: orm
:tickets: 1272

Fixed bug when using weak_instance_map=False where modified
events would not be intercepted for a flush().

.. change::
:tags: orm
:tickets: 1268

Fixed some deep "column correspondence" issues which could
impact a Query made against a selectable containing multiple
versions of the same table, as well as unions and similar
which contained the same table columns in different column
positions at different levels.

.. change::
:tags: orm
:tickets:

Custom comparator classes used in conjunction with
column_property(), relation() etc. can define new comparison
methods on the Comparator, which will become available via
__getattr__() on the InstrumentedAttribute. In the case of
synonym() or comparable_property(), attributes are resolved
first on the user-defined descriptor, then on the user-defined
comparator.

.. change::
:tags: orm
:tickets: 976

Added ScopedSession.is_active accessor.

.. change::
:tags: orm
:tickets: 1262

Can pass mapped attributes and column objects as keys to
query.update({}).

.. change::
:tags: orm
:tickets:

Mapped attributes passed to the values() of an expression
level insert() or update() will use the keys of the mapped
columns, not that of the mapped attribute.

.. change::
:tags: orm
:tickets: 1242

Corrected problem with Query.delete() and Query.update() not
working properly with bind parameters.

.. change::
:tags: orm
:tickets:

Query.select_from(), from_statement() ensure that the given
argument is a FromClause, or Text/Select/Union, respectively.

.. change::
:tags: orm
:tickets: 1253

Query() can be passed a "composite" attribute as a column
expression and it will be expanded. Somewhat related to.

.. change::
:tags: orm
:tickets:

Query() is a little more robust when passed various column
expressions such as strings, clauselists, text() constructs
(which may mean it just raises an error more nicely).

.. change::
:tags: orm
:tickets:

first() works as expected with Query.from_statement().

.. change::
:tags: orm
:tickets:

Fixed bug introduced in 0.5rc4 involving eager loading not
functioning for properties which were added to a mapper
post-compile using add_property() or equivalent.

.. change::
:tags: orm
:tickets:

Fixed bug where many-to-many relation() with viewonly=True
would not correctly reference the link between
secondary->remote.

.. change::
:tags: orm
:tickets: 1232

Duplicate items in a list-based collection will be maintained
when issuing INSERTs to a "secondary" table in a many-to-many
relation. Assuming the m2m table has a unique or primary key
constraint on it, this will raise the expected constraint
violation instead of silently dropping the duplicate
entries. Note that the old behavior remains for a one-to-many
relation since collection entries in that case don't result in
INSERT statements and SQLA doesn't manually police
collections.

.. change::
:tags: orm
:tickets:

Query.add_column() can accept FromClause objects in the same
manner as session.query() can.

.. change::
:tags: orm
:tickets:

Comparison of many-to-one relation to NULL is properly
converted to IS NOT NULL based on not_().

.. change::
:tags: orm
:tickets: 1087

Extra checks added to ensure explicit
primaryjoin/secondaryjoin are ClauseElement instances, to
prevent more confusing errors later on.

.. change::
:tags: orm
:tickets: 1236

Improved mapper() check for non-class classes.

.. change::
:tags: orm
:tickets: 5051

comparator_factory argument is now documented and supported by
all MapperProperty types, including column_property(),
relation(), backref(), and synonym().

.. change::
:tags: orm
:tickets:

Changed the name of PropertyLoader to RelationProperty, to be
consistent with all the other names. PropertyLoader is still
present as a synonym.

.. change::
:tags: orm
:tickets: 1099, 1228

fixed "double iter()" call causing bus errors in shard API,
removed errant result.close() left over from the 0.4
version.

.. change::
:tags: orm
:tickets:

made Session.merge cascades not trigger autoflush. Fixes
merged instances getting prematurely inserted with missing
values.

.. change::
:tags: orm
:tickets:

Two fixes to help prevent out-of-band columns from being
rendered in polymorphic_union inheritance scenarios (which
then causes extra tables to be rendered in the FROM clause
causing cartesian products):

- improvements to "column adaption" for a->b->c inheritance
situations to better locate columns that are related to
one another via multiple levels of indirection, rather
than rendering the non-adapted column.

- the "polymorphic discriminator" column is only rendered
for the actual mapper being queried against. The column
won't be "pulled in" from a subclass or superclass mapper
since it's not needed.

.. change::
:tags: orm
:tickets: 1072

Fixed shard_id argument on ShardedSession.execute().

.. change::
:tags: sql
:tickets: 1256

Columns can again contain percent signs within their
names.

.. change::
:tags: sql
:tickets:

sqlalchemy.sql.expression.Function is now a public class. It
can be subclassed to provide user-defined SQL functions in an
imperative style, including with pre-established behaviors.
The postgis.py example illustrates one usage of this.

.. change::
:tags: sql
:tickets:

PickleType now favors == comparison by default, if the
incoming object (such as a dict) implements __eq__(). If the
object does not implement __eq__() and mutable=True, a
deprecation warning is raised.

.. change::
:tags: sql
:tickets: 1215

Fixed the import weirdness in sqlalchemy.sql to not export
__names__.

.. change::
:tags: sql
:tickets: 1238

Using the same ForeignKey object repeatedly raises an error
instead of silently failing later.

.. change::
:tags: sql
:tickets:

Added NotImplementedError for params() method on
Insert/Update/Delete constructs. These items currently don't
support this functionality, which also would be a little
misleading compared to values().

.. change::
:tags: sql
:tickets: 650

Reflected foreign keys will properly locate their referenced
column, even if the column was given a "key" attribute
different from the reflected name. This is achieved via a new
flag on ForeignKey/ForeignKeyConstraint called "link_to_name",
if True means the given name is the referred-to column's name,
not its assigned key.

.. change::
:tags: sql
:tickets: 1253

select() can accept a ClauseList as a column in the same way
as a Table or other selectable and the interior expressions
will be used as column elements.

.. change::
:tags: sql
:tickets:

the "passive" flag on session.is_modified() is correctly
propagated to the attribute manager.

.. change::
:tags: sql
:tickets:

union() and union_all() will not whack any order_by() that has
been applied to the select()s inside. If you union() a
select() with order_by() (presumably to support LIMIT/OFFSET),
you should also call self_group() on it to apply parenthesis.

.. change::
:tags: engine/pool
:tickets: 1246

Connection.invalidate() checks for closed status to avoid
attribute errors.

.. change::
:tags: engine/pool
:tickets: 1094

NullPool supports reconnect on failure behavior.

.. change::
:tags: engine/pool
:tickets: 799

Added a mutex for the initial pool creation when using
pool.manage(dbapi). This prevents a minor case of "dogpile"
behavior which would otherwise occur upon a heavy load
startup.

.. change::
:tags: engine/pool
:tickets:

_execute_clauseelement() goes back to being a private method.
Subclassing Connection is not needed now that ConnectionProxy
is available.

.. change::
:tags: documentation
:tickets: 1149, 1200

Tickets.

.. change::
:tags: documentation
:tickets:

Added note about create_session() defaults.

.. change::
:tags: documentation
:tickets:

Added section about metadata.reflect().

.. change::
:tags: documentation
:tickets:

Updated `TypeDecorator` section.

.. change::
:tags: documentation
:tickets:

Rewrote the "threadlocal" strategy section of the docs due to
recent confusion over this feature.

.. change::
:tags: documentation
:tickets:

Removed badly out of date 'polymorphic_fetch' and
'select_table' docs from inheritance, reworked the second half
of "joined table inheritance".

.. change::
:tags: documentation
:tickets:

Documented `comparator_factory` kwarg, added new doc section
"Custom Comparators".

.. change::
:tags: mssql
:tickets: 1254

Refactored the Date/Time types. The ``smalldatetime`` data
type no longer truncates to a date only, and will now be
mapped to the MSSmallDateTime type.

.. change::
:tags: mssql
:tickets:

Corrected an issue with Numerics to accept an int.

.. change::
:tags: mssql
:tickets:

Mapped ``char_length`` to the ``LEN()`` function.

.. change::
:tags: mssql
:tickets:

If an ``INSERT`` includes a subselect the ``INSERT`` is
converted from an ``INSERT INTO VALUES`` construct to a
``INSERT INTO SELECT`` construct.

.. change::
:tags: mssql
:tickets:

If the column is part of a ``primary_key`` it will be ``NOT
NULL`` since MSSQL doesn't allow ``NULL`` in primary_key
columns.

.. change::
:tags: mssql
:tickets: 1249

``MSBinary`` now returns a ``BINARY`` instead of an
``IMAGE``. This is a backwards incompatible change in that
``BINARY`` is a fixed length data type whereas ``IMAGE`` is a
variable length data type.

.. change::
:tags: mssql
:tickets: 1258

``get_default_schema_name`` is now reflected from the database
based on the user's default schema. This only works with MSSQL
2005 and later.

.. change::
:tags: mssql
:tickets: 1248

Added collation support through the use of a new collation
argument. This is supported on the following types: char,
nchar, varchar, nvarchar, text, ntext.

.. change::
:tags: mssql
:tickets:

Changes to the connection string parameters favor DSN as the
default specification for pyodbc. See the mssql.py docstring
for detailed usage instructions.

.. change::
:tags: mssql
:tickets:

Added experimental support of savepoints. It currently does
not work fully with sessions.

.. change::
:tags: mssql
:tickets: 1243

Support for three levels of column nullability: NULL, NOT
NULL, and the database's configured default. The default
Column configuration (nullable=True) will now generate NULL in
the DDL. Previously no specification was emitted and the
database default would take effect (usually NULL, but not
always). To explicitly request the database default,
configure columns with nullable=None and no specification will
be emitted in DDL. This is backwards incompatible
behavior.

.. change::
:tags: postgres
:tickets: 1267

"%" signs in text() constructs are automatically escaped to
"%%". Because of the backwards incompatible nature of this
change, a warning is emitted if '%%' is detected in the
string.

.. change::
:tags: postgres
:tickets:

Calling alias.execute() in conjunction with
server_side_cursors won't raise AttributeError.

.. change::
:tags: postgres
:tickets: 714

Added Index reflection support to PostgreSQL, using a great
patch we long neglected, submitted by Ken
Kuhlman.

.. change::
:tags: oracle
:tickets:

Adjusted the format of create_xid() to repair two-phase
commit. We now have field reports of Oracle two-phase commit
working properly with this change.

.. change::
:tags: oracle
:tickets: 1233

Added OracleNVarchar type, produces NVARCHAR2, and also
subclasses Unicode so that convert_unicode=True by default.
NVARCHAR2 reflects into this type automatically so these
columns pass unicode on a reflected table with no explicit
convert_unicode=True flags.

.. change::
:tags: oracle
:tickets: 1265

Fixed bug which was preventing out params of certain types
from being received; thanks a ton to huddlej at wwu.edu !

.. change::
:tags: mysql
:tickets:

"%" signs in text() constructs are automatically escaped to
"%%". Because of the backwards incompatible nature of this
change, a warning is emitted if '%%' is detected in the
string.

.. change::
:tags: mysql
:tickets: 1241

Fixed bug in exception raise when FK columns not present
during reflection.

.. change::
:tags: mysql
:tickets:

Fixed bug involving reflection of a remote-schema table with a
foreign key ref to another table in that schema.

.. change::
:tags: associationproxy
:tickets:

The association proxy properties are make themselves available
at the class level, e.g. MyClass.aproxy. Previously this
evaluated to None.

.. change::
:tags: declarative
:tickets:

The full list of arguments accepted as string by backref()
includes 'primaryjoin', 'secondaryjoin', 'secondary',
'foreign_keys', 'remote_side', 'order_by'.

.. changelog::

:released: Fri Nov 14 2008

.. change::
:tags: orm
:tickets:

Query.count() has been enhanced to do the "right thing" in a
wider variety of cases. It can now count multiple-entity
queries, as well as column-based queries. Note that this means
if you say query(A, B).count() without any joining criterion,
it's going to count the cartesian product of A*B. Any query
which is against column-based entities will automatically
issue "SELECT count(1) FROM (SELECT...)" so that the real
rowcount is returned, meaning a query such as
query(func.count(A.name)).count() will return a value of one,
since that query would return one row.

.. change::
:tags: orm
:tickets:

Lots of performance tuning. A rough guesstimate over various
ORM operations places it 10% faster over 0.5.0rc3, 25-30% over
0.4.8.

.. change::
:tags: orm
:tickets:

bugfixes and behavioral changes

.. change::
:tags: general
:tickets:

global "propigate"->"propagate" change.

.. change::
:tags: orm
:tickets:

Adjustments to the enhanced garbage collection on
InstanceState to better guard against errors due to lost
state.

.. change::
:tags: orm
:tickets: 1220

Query.get() returns a more informative error message when
executed against multiple entities.

.. change::
:tags: orm
:tickets: 1140, 1221

Restored NotImplementedError on Cls.relation.in_()

.. change::
:tags: orm
:tickets: 1226

Fixed PendingDeprecationWarning involving order_by parameter
on relation().

.. change::
:tags: sql
:tickets:

Removed the 'properties' attribute of the Connection object,
Connection.info should be used.

.. change::
:tags: sql
:tickets:

Restored "active rowcount" fetch before ResultProxy autocloses
the cursor. This was removed in 0.5rc3.

.. change::
:tags: sql
:tickets:

Rearranged the `load_dialect_impl()` method in `TypeDecorator`
such that it will take effect even if the user-defined
`TypeDecorator` uses another `TypeDecorator` as its impl.

.. change::
:tags: access
:tickets:

Added support for Currency type.

.. change::
:tags: access
:tickets: 1017

Functions were not return their result.

.. change::
:tags: access
:tickets: 1017

Corrected problem with joins. Access only support LEFT OUTER
or INNER not just JOIN by itself.

.. change::
:tags: mssql
:tickets:

Lots of cleanup and fixes to correct problems with limit and
offset.

.. change::
:tags: mssql
:tickets:

Correct situation where subqueries as part of a binary
expression need to be translated to use the IN and NOT IN
syntax.

.. change::
:tags: mssql
:tickets: 1216

Fixed E Notation issue that prevented the ability to insert
decimal values less than 1E-6.

.. change::
:tags: mssql
:tickets: 1217

Corrected problems with reflection when dealing with schemas,
particularly when those schemas are the default
schema.

.. change::
:tags: mssql
:tickets:

Corrected problem with casting a zero length item to a
varchar. It now correctly adjusts the CAST.

.. change::
:tags: ext
:tickets:

Can now use a custom "inherit_condition" in __mapper_args__
when using declarative.

.. change::
:tags: ext
:tickets:

fixed string-based "remote_side", "order_by" and others not
propagating correctly when used in backref().

.. changelog::