Changelogs » Sqlalchemy

Sqlalchemy

1.3.10

:include_notes_from: unreleased_13

.. changelog::

1.3.9

:released: October 4, 2019

.. change::
:tags: usecase, engine
:tickets: 4857

Added new :func:`.create_engine` parameter
:paramref:`.create_engine.max_identifier_length`. This overrides the
dialect-coded "max identifier length" in order to accommodate for databases
that have recently changed this length and the SQLAlchemy dialect has
not yet been adjusted to detect for that version.  This parameter interacts
with the existing :paramref:`.create_engine.label_length` parameter in that
it establishes the maximum (and default) value for anonymously generated
labels.   Additionally, post-connection detection of max identifier lengths
has been added to the dialect system.  This feature is first being used
by the Oracle dialect.

.. seealso::

:ref:`oracle_max_identifier_lengths` - in the Oracle dialect documentation

.. change::
:tags: usecase, oracle
:tickets: 4857

The Oracle dialect now emits a warning if Oracle version 12.2 or greater is
used, and the :paramref:`.create_engine.max_identifier_length` parameter is
not set.   The version in this specific case defaults to that of the
"compatibility" version set in the Oracle server configuration, not the
actual server version.   In version 1.4, the default max_identifier_length
for 12.2 or greater will move to 128 characters.  In order to maintain
forwards compatibility, applications should set
:paramref:`.create_engine.max_identifier_length` to 30 in order to maintain
the same length behavior, or to 128 in order to test the upcoming behavior.
This length determines among other things how generated constraint names
are truncated for statements like ``CREATE CONSTRAINT`` and ``DROP
CONSTRAINT``, which means a the new length may produce a name-mismatch
against a name that was generated with the old length, impacting database
migrations.

.. seealso::

:ref:`oracle_max_identifier_lengths` - in the Oracle dialect documentation

.. change::
:tags: usecase, sqlite
:tickets: 4863

Added support for sqlite "URI" connections, which allow for sqlite-specific
flags to be passed in the query string such as "read only" for Python
sqlite3 drivers that support this.

.. seealso::

:ref:`pysqlite_uri_connections`

.. change::
:tags: bug, tests
:tickets: 4285

Fixed unit test regression released in 1.3.8 that would cause failure for
Oracle, SQL Server and other non-native ENUM platforms due to new
enumeration tests added as part of :ticket:`4285` enum sortability in the
unit of work; the enumerations created constraints that were duplicated on
name.

.. change::
:tags: bug, oracle
:tickets: 4886

Restored adding cx_Oracle.DATETIME to the setinputsizes() call when a
SQLAlchemy :class:`.Date`, :class:`.DateTime` or :class:`.Time` datatype is
used, as some complex queries require this to be present.  This was removed
in the 1.2 series for arbitrary reasons.

.. change::
:tags: bug, mssql
:tickets: 4883

Added identifier quoting to the schema name applied to the "use" statement
which is invoked when a SQL Server multipart schema name is used within  a
:class:`.Table` that is being reflected, as well as for :class:`.Inspector`
methods such as :meth:`.Inspector.get_table_names`; this accommodates for
special characters or spaces in the database name.  Additionally, the "use"
statement is not emitted if the current database matches the target owner
database name being passed.

.. change::
:tags: bug, orm
:tickets: 4872

Fixed regression in selectinload loader strategy caused by :ticket:`4775`
(released in version 1.3.6) where a many-to-one attribute of None would no
longer be populated by the loader.  While this was usually not noticeable
due to the lazyloader populating None upon get, it would lead to a detached
instance error if the object were detached.

.. change::
:tags: bug, orm
:tickets: 4873

Passing a plain string expression to :meth:`.Session.query` is deprecated,
as all string coercions were removed in :ticket:`4481` and this one should
have been included.   The :func:`.literal_column` function may be used to
produce a textual column expression.

.. change::
:tags: usecase, sql
:tickets: 4847

Added an explicit error message for the case when objects passed to
:class:`.Table` are not :class:`.SchemaItem` objects, rather than resolving
to an attribute error.


.. change::
:tags: bug, orm
:tickets: 4890

A warning is emitted for a condition in which the :class:`.Session` may
implicitly swap an object out of the identity map for another one with the
same primary key, detaching the old one, which can be an observed result of
load operations which occur within the :meth:`.SessionEvents.after_flush`
hook.  The warning is intended to notify the user that some special
condition has caused this to happen and that the previous object may not be
in the expected state.

.. change::
:tags: bug, sql
:tickets: 4837

Characters that interfere with "pyformat" or "named" formats in bound
parameters, namely ``%, (, )`` and the space character, as well as a few
other typically undesirable characters, are stripped early for a
:func:`.bindparam` that is using an anonymized name, which is typically
generated automatically from a named column which itself includes these
characters in its name and does not use a ``.key``, so that they do not
interfere either with the SQLAlchemy compiler's use of string formatting or
with the driver-level parsing of the parameter, both of which could be
demonstrated before the fix.  The change only applies to anonymized
parameter names that are generated and consumed internally, not end-user
defined names, so the change should have no impact on any existing code.
Applies in particular to the psycopg2 driver which does not otherwise quote
special parameter names, but also strips leading underscores to suit Oracle
(but not yet leading numbers, as some anon parameters are currently
entirely numeric/underscore based); Oracle in any case continues to quote
parameter names that include special characters.

.. changelog::

1.3.8

:released: August 27, 2019

.. change::
:tags: bug, orm
:tickets: 4823

Fixed bug where :class:`.Load` objects were not pickleable due to
mapper/relationship state in the internal context dictionary.  These
objects are now converted to picklable using similar techniques as that of
other elements within the loader option system that have long been
serializable.

.. change::
:tags: bug, postgresql
:tickets: 4623

Revised the approach for the just added support for the psycopg2
"execute_values()" feature added in 1.3.7 for :ticket:`4623`.  The approach
relied upon a regular expression that would fail to match for a more
complex INSERT statement such as one which had subqueries involved.   The
new approach matches exactly the string that was rendered as the VALUES
clause.

.. change::
:tags: usecase, orm
:tickets: 4285

Added support for the use of an :class:`.Enum` datatype using Python
pep-435 enumeration objects as values for use as a primary key column
mapped by the ORM.  As these values are not inherently sortable, as
required by the ORM for primary keys, a new
:attr:`.TypeEngine.sort_key_function` attribute is added to the typing
system which allows any SQL type to  implement a sorting for Python objects
of its type which is consulted by the unit of work.   The :class:`.Enum`
type then defines this using the  database value of a given enumeration.
The sorting scheme can be  also be redefined by passing a callable to the
:paramref:`.Enum.sort_key_function` parameter.  Pull request courtesy
Nicolas Caniart.

.. change::
:tags: bug, engine
:tickets: 4807

Fixed an issue whereby if the dialect "initialize" process which occurs on
first connect would encounter an unexpected exception, the initialize
process would fail to complete and then no longer attempt on subsequent
connection attempts, leaving the dialect in an un-initialized, or partially
initialized state, within the scope of parameters that need to be
established based on inspection of a live connection.   The "invoke once"
logic in the event system has been reworked to accommodate for this
occurrence using new, private API features that establish an "exec once"
hook that will continue to allow the initializer to fire off on subsequent
connections, until it completes without raising an exception. This does not
impact the behavior of the existing ``once=True`` flag within the event
system.

.. change::
:tags: bug, sqlite, reflection
:tickets: 4810

Fixed bug where a FOREIGN KEY that was set up to refer to the parent table
by table name only without the column names would not correctly be
reflected as far as setting up the "referred columns", since SQLite's
PRAGMA does not report on these columns if they weren't given explicitly.
For some reason this was harcoded to assume the name of the local column,
which might work for some cases but is not correct. The new approach
reflects the primary key of the referred table and uses the constraint
columns list as the referred columns list, if the remote column(s) aren't
present in the reflected pragma directly.


.. change::
:tags: bug, postgresql
:tickets: 4822

Fixed bug where Postgresql operators such as
:meth:`.postgresql.ARRAY.Comparator.contains` and
:meth:`.postgresql.ARRAY.Comparator.contained_by` would fail to function
correctly for non-integer values when used against a
:class:`.postgresql.array` object, due to an erroneous assert statement.

.. change::
:tags: feature, engine
:tickets: 4815

Added new parameter :paramref:`.create_engine.hide_parameters` which when
set to True will cause SQL parameters to no longer be logged, nor rendered
in the string representation of a :class:`.StatementError` object.


.. change::
:tags: usecase, postgresql
:tickets: 4824

Added support for reflection of CHECK constraints that include the special
PostgreSQL qualifier "NOT VALID", which can be present for CHECK
constraints that were added to an exsiting table with the directive that
they not be applied to existing data in the table. The PostgreSQL
dictionary for CHECK constraints as returned by
:meth:`.Inspector.get_check_constraints` may include an additional entry
``dialect_options`` which within will contain an entry ``"not_valid":
True`` if this symbol is detected.   Pull request courtesy Bill Finn.

.. changelog::

1.3.7

:released: August 14, 2019

.. change::
:tags: bug, sql
:tickets: 4778

Fixed issue where :class:`.Index` object which contained a mixture of
functional expressions which were not resolvable to a particular column,
in combination with string-based column names, would fail to initialize
its internal state correctly leading to failures during DDL compilation.

.. change::
:tags: bug, sqlite
:tickets: 4798

The dialects that support json are supposed to take arguments
``json_serializer`` and ``json_deserializer`` at the create_engine() level,
however the SQLite dialect calls them ``_json_serilizer`` and
``_json_deserilalizer``.  The names have been corrected, the old names are
accepted with a change warning, and these parameters are now documented as
:paramref:`.create_engine.json_serializer` and
:paramref:`.create_engine.json_deserializer`.


.. change::
:tags: bug, mysql
:tickets: 4804

The MySQL dialects will emit "SET NAMES" at the start of a connection when
charset is given to the MySQL driver, to appease an apparent behavior
observed in MySQL 8.0 that raises a collation error when a UNION includes
string columns unioned against columns of the form CAST(NULL AS CHAR(..)),
which is what SQLAlchemy's polymorphic_union function does.   The issue
seems to have affected PyMySQL for at least a year, however has recently
appeared as of mysqlclient 1.4.4 based on changes in how this DBAPI creates
a connection.  As the presence of this directive impacts three separate
MySQL charset settings which each have intricate effects based on their
presense,  SQLAlchemy will now emit the directive on new connections to
ensure correct behavior.

.. change::
:tags: usecase, postgresql
:tickets: 4623

Added new dialect flag for the psycopg2 dialect, ``executemany_mode`` which
supersedes the previous experimental ``use_batch_mode`` flag.
``executemany_mode`` supports both the "execute batch" and "execute values"
functions provided by psycopg2, the latter which is used for compiled
:func:`.insert` constructs.   Pull request courtesy Yuval Dinari.

.. seealso::

:ref:`psycopg2_executemany_mode`




.. change::
:tags: bug, sql
:tickets: 4787

Fixed bug where :meth:`.TypeEngine.column_expression` method would not be
applied to subsequent SELECT statements inside of a UNION or other
:class:`.CompoundSelect`, even though the SELECT statements are rendered at
the topmost level of the statement.   New logic now differentiates between
rendering the column expression, which is needed for all SELECTs in the
list, vs. gathering the returned data type for the result row, which is
needed only for the first SELECT.

.. change::
:tags: bug, sqlite
:tickets: 4793

Fixed bug where usage of "PRAGMA table_info" in SQLite dialect meant that
reflection features to detect for table existence, list of table columns,
and list of foreign keys, would default to any table in any attached
database, when no schema name was given and the table did not exist in the
base schema.  The fix explicitly runs PRAGMA for the 'main' schema and then
the 'temp' schema if the 'main' returned no rows, to maintain the behavior
of tables + temp tables in the "no schema" namespace, attached tables only
in the "schema" namespace.


.. change::
:tags: bug, sql
:tickets: 4780

Fixed issue where internal cloning of SELECT constructs could lead to a key
error if the copy of the SELECT changed its state such that its list of
columns changed.  This was observed to be occurring in some ORM scenarios
which may be unique to 1.3 and above, so is partially a regression fix.



.. change::
:tags: bug, orm
:tickets: 4777

Fixed regression caused by new selectinload for many-to-one logic where
a primaryjoin condition not based on real foreign keys would cause
KeyError if a related object did not exist for a given key value on the
parent object.

.. change::
:tags: usecase, mysql
:tickets: 4783

Added reserved words ARRAY and MEMBER to the MySQL reserved words list, as
MySQL 8.0 has now made these reserved.


.. change::
:tags: bug, events
:tickets: 4794

Fixed issue in event system where using the ``once=True`` flag with
dynamically generated listener functions would cause event registration of
future events to fail if those listener functions were garbage collected
after they were used, due to an assumption that a listened function is
strongly referenced.  The "once" wrapped is now modified to strongly
reference the inner function persistently, and documentation is updated
that using "once" does not imply automatic de-registration of listener
functions.

.. change::
:tags: bug, mysql
:tickets: 4751

Added another fix for an upstream MySQL 8 issue where a case sensitive
table name is reported incorrectly in foreign key constraint reflection,
this is an extension of the fix first added for :ticket:`4344` which
affects a case sensitive column name.  The new issue occurs through MySQL
8.0.17, so the general logic of the 88718 fix remains in place.

.. seealso::

https://bugs.mysql.com/bug.php?id=96365 - upstream bug


.. change::
:tags: usecase, mssql
:tickets: 4782

Added new :func:`.mssql.try_cast` construct for SQL Server which emits
"TRY_CAST" syntax.  Pull request courtesy Leonel Atencio.

.. change::
:tags: bug, orm
:tickets: 4803

Fixed bug where using :meth:`.Query.first` or a slice expression in
conjunction with a query that has an expression based "offset" applied
would raise TypeError, due to an "or" conditional against "offset" that did
not expect it to be a SQL expression as opposed to an integer or None.


.. changelog::

1.3.6

:released: July 21, 2019

.. change::
:tags: bug, engine
:tickets: 4754

Fixed bug where using reflection function such as :meth:`.MetaData.reflect`
with an :class:`.Engine` object that had execution options applied to it
would fail, as the resulting :class:`.OptionEngine` proxy object failed to
include a ``.engine`` attribute used within the reflection routines.

.. change::
:tags: bug, mysql
:tickets: 4743

Fixed bug where the special logic to render "NULL" for the
:class:`.TIMESTAMP` datatype when ``nullable=True`` would not work if the
column's datatype were a :class:`.TypeDecorator` or a :class:`.Variant`.
The logic now ensures that it unwraps down to the original
:class:`.TIMESTAMP` so that this special case NULL keyword is correctly
rendered when requested.

.. change::
:tags: performance, orm
:tickets: 4775

The optimization applied to selectin loading in :ticket:`4340` where a JOIN
is not needed to eagerly load related items is now applied to many-to-one
relationships as well, so that only the related table is queried for a
simple join condition.   In this case, the related items are queried
based on the value of a foreign key column on the parent; if these columns
are deferred or otherwise not loaded on any of the parent objects in
the collection, the loader falls back to the JOIN method.


.. change::
:tags: bug, orm
:tickets: 4773

Fixed regression caused by :ticket:`4365` where a join from an entity to
itself without using aliases no longer raises an informative error message,
instead failing on an assertion.  The informative error condition has been
restored.


.. change::
:tags: orm, feature
:tickets: 4736

Added new loader option method :meth:`.Load.options` which allows loader
options to be constructed hierarchically, so that many sub-options can be
applied to a particular path without needing to call :func:`.defaultload`
many times.  Thanks to Alessio Bogon for the idea.


.. change::
:tags: usecase, postgresql
:tickets: 4771

Added support for reflection of indexes on PostgreSQL partitioned tables,
which was added to PostgreSQL as of version 11.

.. change::
:tags: bug, mysql
:tickets: 4624

Enhanced MySQL/MariaDB version string parsing to accommodate for exotic
MariaDB version strings where the "MariaDB" word is embedded among other
alphanumeric characters such as "MariaDBV1".   This detection is critical in
order to correctly accommodate for API features that have split between MySQL
and MariaDB such as the "transaction_isolation" system variable.


.. change::
:tags: bug, mssql
:tickets: 4745

Ensured that the queries used to reflect indexes and view definitions will
explicitly CAST string parameters into NVARCHAR, as many SQL Server drivers
frequently treat string values, particularly those with non-ascii
characters or larger string values, as TEXT which often don't compare
correctly against VARCHAR characters in SQL Server's information schema
tables for some reason.    These CAST operations already take place for
reflection queries against SQL Server ``information_schema.`` tables but
were missing from three additional queries that are against ``sys.``
tables.

.. change::
:tags: bug, orm
:tickets: 4713

Fixed an issue where the :meth:`.orm._ORMJoin.join` method, which is a
not-internally-used ORM-level method that exposes what is normally an
internal process of :meth:`.Query.join`, did not propagate the ``full`` and
``outerjoin`` keyword arguments correctly.  Pull request courtesy Denis
Kataev.

.. change::
:tags: bug, sql
:tickets: 4758

Adjusted the initialization for :class:`.Enum` to minimize how often it
invokes the ``.__members__`` attribute of a given PEP-435 enumeration
object, to suit the case where this attribute is expensive to invoke, as is
the case for some popular third party enumeration libraries.


.. change::
:tags: bug, orm
:tickets: 4772

Fixed bug where a many-to-one relationship that specified ``uselist=True``
would fail to update correctly during a primary key change where a related
column needs to change.


.. change::
:tags: bug, orm
:tickets: 4772

Fixed bug where the detection for many-to-one or one-to-one use with a
"dynamic" relationship, which is an invalid configuration, would fail to
raise if the relationship were configured with ``uselist=True``.  The
current fix is that it warns, instead of raises, as this would otherwise be
backwards incompatible, however in a future release it will be a raise.


.. change::
:tags: bug, orm
:tickets: 4767

Fixed bug where a synonym created against a mapped attribute that does not
exist yet, as is the case when it refers to backref before mappers are
configured, would raise recursion errors when trying to test for attributes
on it which ultimately don't exist (as occurs when the classes are run
through Sphinx autodoc), as the unconfigured state of the synonym would put
it into an attribute not found loop.


.. change::
:tags: usecase, postgresql
:tickets: 4756

Added support for multidimensional Postgresql array literals via nesting
the :class:`.postgresql.array` object within another one.  The
multidimensional array type is detected automatically.

.. seealso::

:class:`.postgresql.array`

.. change::
:tags: bug, sql, postgresql
:tickets: 4760

Fixed issue where the :class:`.array_agg` construct in combination with
:meth:`.FunctionElement.filter` would not produce the correct operator
precedence in combination with the array index operator.


.. change::
:tags: bug, sql
:tickets: 4747

Fixed an unlikely issue where the "corresponding column" routine for unions
and other :class:`.CompoundSelect` objects could return the wrong column in
some overlapping column situtations, thus potentially impacting some ORM
operations when set operations are in use, if the underlying
:func:`.select` constructs were used previously in other similar kinds of
routines, due to a cached value not being cleared.

.. change::
:tags: usecase, sqlite
:tickets: 4766

Added support for composite (tuple) IN operators with SQLite, by rendering
the VALUES keyword for this backend.  As other backends such as DB2 are
known to use the same syntax, the syntax is enabled in the base compiler
using a dialect-level flag ``tuple_in_values``.   The change also includes
support for "empty IN tuple" expressions for SQLite when using "in_()"
between a tuple value and an empty set.


.. changelog::

1.3.5

:released: June 17, 2019

.. change::
:tags: bug, mysql
:tickets: 4715

Fixed bug where MySQL ON DUPLICATE KEY UPDATE would not accommodate setting
a column to the value NULL.  Pull request courtesy Lukáš Banič.

.. change::
:tags: bug, orm
:tickets: 4723

Fixed a series of related bugs regarding joined table inheritance more than
two levels deep, in conjunction with modification to primary key values,
where those primary key columns are also linked together in a foreign key
relationship as is typical for joined table inheritance.  The intermediary
table in a  three-level inheritance hierarchy will now get its UPDATE if
only the primary key value has changed and passive_updates=False (e.g.
foreign key constraints not being enforced), whereas before it would be
skipped; similarly, with passive_updates=True (e.g. ON UPDATE  CASCADE in
effect), the third-level table will not receive an UPDATE statement as was
the case earlier which would fail since CASCADE already modified it.   In a
related issue, a relationship linked to a three-level inheritance hierarchy
on the primary key of an intermediary table of a joined-inheritance
hierarchy will also correctly have its foreign key column updated when the
parent object's primary key is modified, even if that parent object is a
subclass of the linked parent class, whereas before these classes would
not be counted.

.. change::
:tags: bug, orm
:tickets: 4729

Fixed bug where the :attr:`.Mapper.all_orm_descriptors` accessor would
return an entry for the :class:`.Mapper` itself under the declarative
``__mapper___`` key, when this is not a descriptor.  The ``.is_attribute``
flag that's present on all :class:`.InspectionAttr` objects is now
consulted, which has also been modified to be ``True`` for an association
proxy, as it was erroneously set to False for this object.

.. change::
:tags: bug, orm
:tickets: 4704

Fixed regression in :meth:`.Query.join` where the ``aliased=True`` flag
would not properly apply clause adaptation to filter criteria, if a
previous join were made to the same entity.  This is because the adapters
were placed in the wrong order.   The order has been reversed so that the
adapter for the most recent ``aliased=True`` call takes precedence as was
the case in 1.2 and earlier.  This broke the "elementtree" examples among
other things.

.. change::
:tags: bug, orm, py3k
:tickets: 4674

Replaced the Python compatbility routines for ``getfullargspec()`` with a
fully vendored version from Python 3.3.  Originally, Python was emitting
deprecation warnings for this function in Python 3.8 alphas.  While this
change was reverted, it was observed that Python 3 implementations for
``getfullargspec()`` are an order of magnitude slower as of the 3.4 series
where it was rewritten against ``Signature``.  While Python plans to
improve upon this situation, SQLAlchemy projects for now are using a simple
replacement to avoid any future issues.

.. change::
:tags: bug, orm
:tickets: 4694

Reworked the attribute mechanics used by :class:`.AliasedClass` to no
longer rely upon calling ``__getattribute__`` on the MRO of the wrapped
class, and to instead resolve the attribute normally on the wrapped class
using getattr(), and then unwrap/adapt that.  This allows a greater range
of attribute styles on the mapped class including special ``__getattr__()``
schemes; but it also makes the code simpler and more resilient in general.

.. change::
:tags: usecase, postgresql
:tickets: 4717

Added support for column sorting flags when reflecting indexes for
PostgreSQL, including ASC, DESC, NULLSFIRST, NULLSLAST.  Also adds this
facility to the reflection system in general which can be applied to other
dialects in future releases.  Pull request courtesy Eli Collins.

.. change::
:tags: bug, postgresql
:tickets: 4701

Fixed bug where PostgreSQL dialect could not correctly reflect an ENUM
datatype that has no members, returning a list with ``None`` for the
``get_enums()`` call and raising a TypeError when reflecting a column which
has such a datatype.   The inspection now returns an empty list.

.. change::
:tags: bug, sql
:tickets: 4730

Fixed a series of quoting issues which all stemmed from the concept of the
:func:`.literal_column` construct, which when being "proxied" through a
subquery to be referred towards by a label that matches its text, the label
would not have quoting rules applied to it, even if the string in the
:class:`.Label` were set up as a :class:`.quoted_name` construct.  Not
applying quoting to the text of the :class:`.Label` is a bug because this
text is strictly a SQL identifier name and not a SQL expression, and the
string should not have quotes embedded into it already unlike the
:func:`.literal_column` which it may be applied towards.   The existing
behavior of a non-labeled :func:`.literal_column` being propagated as is on
the outside of a subquery is maintained in order to help with manual
quoting schemes, although it's not clear if valid SQL can be generated for
such a construct in any case.

.. changelog::

1.3.4

:released: May 27, 2019

.. change::
:tags: feature, mssql
:tickets: 4657

Added support for SQL Server filtered indexes, via the ``mssql_where``
parameter which works similarly to that of the ``postgresql_where`` index
function in the PostgreSQL dialect.

.. seealso::

:ref:`mssql_index_where`

.. change::
:tags: bug, misc
:tickets: 4625

Removed errant "sqla_nose.py" symbol from MANIFEST.in which created an
undesirable warning message.

.. change::
:tags: bug, sql
:tickets: 4653

Fixed that the :class:`.GenericFunction` class was inadvertently
registering itself as one of the named functions.  Pull request courtesy
Adrien Berchet.

.. change::
:tags: bug, engine, postgresql
:tickets: 4663

Moved the "rollback" which occurs during dialect initialization so that it
occurs after additional dialect-specific initialize steps, in particular
those of the psycopg2 dialect which would inadvertently leave transactional
state on the first new connection, which could interfere with some
psycopg2-specific APIs which require that no transaction is started.  Pull
request courtesy Matthew Wilkes.


.. change::
:tags: bug, orm
:tickets: 4695

Fixed issue where the :paramref:`.AttributeEvents.active_history` flag
would not be set for an event listener that propgated to a subclass via the
:paramref:`.AttributeEvents.propagate` flag.   This bug has been present
for the full span of the :class:`.AttributeEvents` system.


.. change::
:tags: bug, orm
:tickets: 4690

Fixed regression where new association proxy system was still not proxying
hybrid attributes when they made use of the ``hybrid_property.expression``
decorator to return an alternate SQL expression, or when the hybrid
returned an arbitrary :class:`.PropComparator`, at the expression level.
This involved further generalization of the heuristics used to detect the
type of object being proxied at the level of :class:`.QueryableAttribute`,
to better detect if the descriptor ultimately serves mapped classes or
column expressions.

.. change::
:tags: bug, orm
:tickets: 4686

Applied the mapper "configure mutex" against the declarative class mapping
process, to guard against the race which can occur if mappers are used
while dynamic module import schemes are still in the process of configuring
mappers for related classes.  This does not guard against all possible race
conditions, such as if the concurrent import has not yet encountered the
dependent classes as of yet, however it guards against as much as possible
within the SQLAlchemy declarative process.

.. change::
:tags: bug, mssql
:tickets: 4680

Added error code 20047 to "is_disconnect" for pymssql.  Pull request
courtesy Jon Schuff.


.. change::
:tags: bug, postgresql, orm
:tickets: 4661

Fixed an issue where the "number of rows matched" warning would emit even if
the dialect reported "supports_sane_multi_rowcount=False", as is the case
for psycogp2 with ``use_batch_mode=True`` and others.


.. change::
:tags: bug, sql
:tickets: 4618

Fixed issue where double negation of a boolean column wouldn't reset
the "NOT" operator.

.. change::
:tags: mysql, bug
:tickets: 4650

Added support for DROP CHECK constraint which is required by MySQL 8.0.16
to drop a CHECK constraint; MariaDB supports plain DROP CONSTRAINT.  The
logic distinguishes between the two syntaxes by checking the server version
string for MariaDB presence.    Alembic migrations has already worked
around this issue by implementing its own DROP for MySQL / MariaDB CHECK
constraints, however this change implements it straight in Core so that its
available for general use.   Pull request courtesy Hannes Hansen.

.. change::
:tags: bug, orm
:tickets: 4647

A warning is now emitted for the case where a transient object is being
merged into the session with :meth:`.Session.merge` when that object is
already transient in the :class:`.Session`.   This warns for the case where
the object would normally be double-inserted.


.. change::
:tags: bug, orm
:tickets: 4676

Fixed regression in new relationship m2o comparison logic first introduced
at :ref:`change_4359` when comparing to an attribute that is persisted as
NULL and is in an un-fetched state in the mapped instance.  Since the
attribute has no explicit default, it needs to default to NULL when
accessed in a persistent setting.


.. change::
:tags: bug, sql
:tickets: 4569

The :class:`.GenericFunction` namespace is being migrated so that function
names are looked up in a case-insensitive manner, as SQL  functions do not
collide on case sensitive differences nor is this something which would
occur with user-defined functions or stored procedures.   Lookups for
functions declared with :class:`.GenericFunction` now use a case
insensitive scheme,  however a deprecation case is supported which allows
two or more :class:`.GenericFunction` objects with the same name of
different cases to exist, which will cause case sensitive lookups to occur
for that particular name, while emitting a warning at function registration
time.  Thanks to Adrien Berchet for a lot of work on this complicated
feature.


.. changelog::

1.3.3

:released: April 15, 2019

.. change::
:tags: bug, postgresql
:tickets: 4601

Fixed regression from release 1.3.2 caused by :ticket:`4562` where a URL
that contained only a query string and no hostname, such as for the
purposes of specifying a service file with connection information, would no
longer be propagated to psycopg2 properly.   The change in :ticket:`4562`
has been adjusted to further suit psycopg2's exact requirements, which is
that if there are any connection parameters whatsoever, the "dsn" parameter
is no longer required, so in this case the query string parameters are
passed alone.

.. change::
:tags: bug, pool
:tickets: 4585

Fixed behavioral regression as a result of deprecating the "use_threadlocal"
flag for :class:`.Pool`, where the :class:`.SingletonThreadPool` no longer
makes use of this option which causes the "rollback on return" logic to take
place when the same :class:`.Engine` is used multiple times in the context
of a transaction to connect or implicitly execute, thereby cancelling the
transaction.   While this is not the recommended way to work with engines
and connections, it is nonetheless a confusing behavioral change as when
using :class:`.SingletonThreadPool`, the transaction should stay open
regardless of what else is done with the same engine in the same thread.
The ``use_threadlocal`` flag remains deprecated however the
:class:`.SingletonThreadPool` now implements its own version of the same
logic.


.. change::
:tags: bug, orm
:tickets: 4584

Fixed 1.3 regression in new "ambiguous FROMs" query logic introduced in
:ref:`change_4365` where a :class:`.Query` that explicitly places an entity
in the FROM clause with :meth:`.Query.select_from` and also joins to it
using :meth:`.Query.join` would later cause an "ambiguous FROM" error if
that entity were used in additional joins, as the entity appears twice in
the "from" list of the :class:`.Query`.  The fix resolves this ambiguity by
folding the standalone entity into the join that it's already a part of in
the same way that ultimately happens when the SELECT statement is rendered.

.. change::
:tags: bug, ext
:tickets: 4603

Fixed bug where using ``copy.copy()`` or ``copy.deepcopy()`` on
:class:`.MutableList` would cause the items within the list to be
duplicated, due to an inconsistency in how Python pickle and copy both make
use of ``__getstate__()`` and ``__setstate__()`` regarding lists.  In order
to resolve, a ``__reduce_ex__`` method had to be added to
:class:`.MutableList`.  In order to maintain backwards compatibility with
existing pickles based on ``__getstate__()``, the ``__setstate__()`` method
remains as well; the test suite asserts that pickles made against the old
version of the class can still be deserialized by the pickle module.

.. change::
:tags: bug, orm
:tickets: 4606

Adjusted the :meth:`.Query.filter_by` method to not call :func:`.and()`
internally against multiple criteria, instead passing it off to
:meth:`.Query.filter` as a series of criteria, instead of a single criteria.
This allows :meth:`.Query.filter_by` to defer to :meth:`.Query.filter`'s
treatment of variable numbers of clauses, including the case where the list
is empty.  In this case, the :class:`.Query` object will not have a
``.whereclause``, which allows subsequent "no whereclause" methods like
:meth:`.Query.select_from` to behave consistently.

.. change::
:tags: bug, mssql
:tickets: 4587

Fixed issue in SQL Server dialect where if a bound parameter were present in
an ORDER BY expression that would ultimately not be rendered in the SQL
Server version of the statement, the parameters would still be part of the
execution parameters, leading to DBAPI-level errors.  Pull request courtesy
Matt Lewellyn.

.. changelog::

1.3.2

:released: April 2, 2019

.. change::
:tags: bug, documentation, sql
:tickets: 4580

Thanks to :ref:`change_3981`, we no longer need to rely on recipes that
subclass dialect-specific types directly, :class:`.TypeDecorator` can now
handle all cases.   Additionally, the above change made it slightly less
likely that a direct subclass of a base SQLAlchemy type would work as
expected, which could be misleading.  Documentation has been updated to use
:class:`.TypeDecorator` for these examples including the PostgreSQL
"ArrayOfEnum" example datatype and direct support for the "subclass a type
directly" has been removed.

.. change::
:tags: bug, postgresql
:tickets: 4550

Modified the :paramref:`.Select.with_for_update.of` parameter so that if a
join or other composed selectable is passed, the individual :class:`.Table`
objects will be filtered from it, allowing one to pass a join() object to
the parameter, as occurs normally when using joined table inheritance with
the ORM.  Pull request courtesy Raymond Lu.


.. change::
:tags: feature, postgresql
:tickets: 4562

Added support for parameter-less connection URLs for the psycopg2 dialect,
meaning, the URL can be passed to :func:`.create_engine` as
``"postgresql+psycopg2://"`` with no additional arguments to indicate an
empty DSN passed to libpq, which indicates to connect to "localhost" with
no username, password, or database given. Pull request courtesy Julian
Mehnle.

.. change::
:tags: bug, orm, ext
:tickets: 4574, 4573

Restored instance-level support for plain Python descriptors, e.g.
``property`` objects, in conjunction with association proxies, in that if
the proxied object is not within ORM scope at all, it gets classified as
"ambiguous" but is proxed directly.  For class level access, a basic class
level``__get__()`` now returns the
:class:`.AmbiguousAssociationProxyInstance` directly, rather than raising
its exception, which is the closest approximation to the previous behavior
that returned the :class:`.AssociationProxy` itself that's possible.  Also
improved the stringification of these objects to be more descriptive of
current state.

.. change::
:tags: bug, orm
:tickets: 4537

Fixed bug where use of :func:`.with_polymorphic` or other aliased construct
would not properly adapt when the aliased target were used as the
:meth:`.Select.correlate_except` target of a subquery used inside of a
:func:`.column_property`. This required a fix to the clause adaption
mechanics to properly handle a selectable that shows up in the "correlate
except" list, in a similar manner as which occurs for selectables that show
up in the "correlate" list.  This is ultimately a fairly fundamental bug
that has lasted for a long time but it is hard to come across it.


.. change::
:tags: bug, orm
:tickets: 4566

Fixed regression where a new error message that was supposed to raise when
attempting to link a relationship option to an AliasedClass without using
:meth:`.PropComparator.of_type` would instead raise an ``AttributeError``.
Note that in 1.3, it is no longer valid to create an option path from a
plain mapper relationship to an :class:`.AliasedClass` without using
:meth:`.PropComparator.of_type`.

.. changelog::

1.3.1

:released: March 9, 2019

.. change::
:tags: bug, mssql
:tickets: 4525

Fixed regression in SQL Server reflection due to :ticket:`4393` where the
removal of open-ended ``**kw`` from the :class:`.Float` datatype caused
reflection of this type to fail due to a "scale" argument being passed.

.. change::
:tags: bug, orm, ext
:tickets: 4522

Fixed regression where an association proxy linked to a synonym would no
longer work, both at instance level and at class level.

.. changelog::

1.3.0

:released: March 4, 2019

.. change::
:tags: feature, schema
:tickets: 4517

Added new parameters :paramref:`.Table.resolve_fks` and
:paramref:`.MetaData.reflect.resolve_fks` which when set to False will
disable the automatic reflection of related tables encountered in
:class:`.ForeignKey` objects, which can both reduce SQL overhead for omitted
tables as well as avoid tables that can't be reflected for database-specific
reasons.  Two :class:`.Table` objects present in the same :class:`.MetaData`
collection can still refer to each other even if the reflection of the two
tables occurred separately.


.. change::
:tags: feature, orm
:tickets: 4316

The :meth:`.Query.get` method can now accept a dictionary of attribute keys
and values as a means of indicating the primary key value to load; is
particularly useful for composite primary keys.  Pull request courtesy
Sanjana S.

.. change::
:tags: feature, orm
:tickets: 3133

A SQL expression can now be assigned to a primary key attribute for an ORM
flush in the same manner as ordinary attributes as described in
:ref:`flush_embedded_sql_expressions` where the expression will be evaulated
and then returned to the ORM using RETURNING, or in the case of pysqlite,
works using the cursor.lastrowid attribute.Requires either a database that
supports RETURNING (e.g. Postgresql, Oracle, SQL Server) or pysqlite.

.. change::
:tags: bug, sql
:tickets: 4509

The :class:`.Alias` class and related subclasses :class:`.CTE`,
:class:`.Lateral` and :class:`.TableSample` have been reworked so that it is
not possible for a user to construct the objects directly.  These constructs
require that the standalone construction function or selectable-bound method
be used to instantiate new objects.


.. change::
:tags: feature, engine
:tickets: 4500

Revised the formatting for :class:`.StatementError` when stringified. Each
error detail is broken up over multiple newlines instead of spaced out on a
single line.  Additionally, the SQL representation now stringifies the SQL
statement rather than using ``repr()``, so that newlines are rendered as is.
Pull request courtesy Nate Clark.

.. seealso::

:ref:`change_4500`

.. changelog::

1.3.0b3

:released: March 4, 2019
:released: February 8, 2019

.. change::
:tags: bug, ext
:tickets: 2642

Implemented a more comprehensive assignment operation (e.g. "bulk replace")
when using association proxy with sets or dictionaries.  Fixes the problem
of redundant proxy objects being created to replace the old ones, which
leads to excessive events and SQL and in the case of unique constraints
will cause the flush to fail.

.. seealso::

:ref:`change_2642`

.. change::
:tags: bug, postgresql
:tickets: 4473

Fixed issue where using an uppercase name for an index type (e.g. GIST,
BTREE, etc. ) or an EXCLUDE constraint would treat it as an identifier to
be quoted, rather than rendering it as is. The new behavior converts these
types to lowercase and ensures they contain only valid SQL characters.

.. change::
:tags: bug, orm
:tickets: 4469

Improved the behavior of :func:`.orm.with_polymorphic` in conjunction with
loader options, in particular wildcard operations as well as
:func:`.orm.load_only`.  The polymorphic object will be more accurately
targeted so that column-level options on the entity will correctly take
effect.The issue is a continuation of the same kinds of things fixed in
:ticket:`4468`.


.. change::
:tags: bug, sql
:tickets: 4481

Fully removed the behavior of strings passed directly as components of a
:func:`.select` or :class:`.Query` object being coerced to :func:`.text`
constructs automatically; the warning that has been emitted is now an
ArgumentError or in the case of order_by() / group_by() a CompileError.
This has emitted a warning since version 1.0 however its presence continues
to create concerns for the potential of mis-use of this behavior.

Note that public CVEs have been posted for order_by() / group_by() which
are resolved by this commit:  CVE-2019-7164  CVE-2019-7548


.. seealso::

:ref:`change_4481`

.. change::
:tags: bug, sql
:tickets: 4467

Quoting is applied to :class:`.Function` names, those which are usually but
not necessarily generated from the :attr:`.sql.func` construct,  at compile
time if they contain illegal characters, such as spaces or punctuation. The
names are as before treated as case insensitive however, meaning if the
names contain uppercase or mixed case characters, that alone does not
trigger quoting. The case insensitivity is currently maintained for
backwards compatibility.


.. change::
:tags: bug, sql
:tickets: 4481

Added "SQL phrase validation" to key DDL phrases that are accepted as plain
strings, including :paramref:`.ForeignKeyConstraint.on_delete`,
:paramref:`.ForeignKeyConstraint.on_update`,
:paramref:`.ExcludeConstraint.using`,
:paramref:`.ForeignKeyConstraint.initially`, for areas where a series of SQL
keywords only are expected.Any non-space characters that suggest the phrase
would need to be quoted will raise a :class:`.CompileError`.   This change
is related to the series of changes committed as part of :ticket:`4481`.

.. change::
:tags: bug, orm, declarative
:tickets: 4470

Added some helper exceptions that invoke when a mapping based on
:class:`.AbstractConcreteBase`, :class:`.DeferredReflection`, or
:class:`.AutoMap` is used before the mapping is ready to be used, which
contain descriptive information on the class, rather than falling through
into other failure modes that are less informative.


.. change::
:tags: change, tests
:tickets: 4460

The test system has removed support for Nose, which is unmaintained for
several years and is producing warnings under Python 3. The test suite is
currently standardized on Pytest.  Pull request courtesy Parth Shandilya.

.. changelog::

1.3.0b2

:released: March 4, 2019
:released: January 25, 2019

.. change::
:tags: bug, ext
:tickets: 4401

Fixed a regression in 1.3.0b1 caused by :ticket:`3423` where association
proxy objects that access an attribute that's only present on a polymorphic
subclass would raise an ``AttributeError`` even though the actual instance
being accessed was an instance of that subclass.

.. change::
:tags: bug, orm
:tickets: 1103

Fixed long-standing issue where duplicate collection members would cause a
backref to delete the association between the member and its parent object
when one of the duplicates were removed, as occurs as a side effect of
swapping two objects in one statement.

.. seealso::

:ref:`change_1103`

.. change::
:tags: bug, mssql
:tickets: 4442

The ``literal_processor`` for the :class:`.Unicode` and
:class:`.UnicodeText` datatypes now render an ``N`` character in front of
the literal string expression as required by SQL Server for Unicode string
values rendered in SQL expressions.

.. change::
:tags: feature, orm
:tickets: 4423

Implemented a new feature whereby the :class:`.AliasedClass` construct can
now be used as the target of a :func:`.relationship`.  This allows the
concept of "non primary mappers" to no longer be necessary, as the
:class:`.AliasedClass` is much easier to configure and automatically inherits
all the relationships of the mapped class, as well as preserves the
ability for loader options to work normally.

.. seealso::

:ref:`change_4423`

.. change::
:tags: bug, orm
:tickets: 4373

Extended the fix first made as part of :ticket:`3287`, where a loader option
made against a subclass using a wildcard would extend itself to include
application of the wildcard to attributes on the super classes as well, to a
"bound" loader option as well, e.g. in an expression like
``Load(SomeSubClass).load_only('foo')``.  Columns that are part of the
parent class of ``SomeSubClass`` will also be excluded in the same way as if
the unbound option ``load_only('foo')`` were used.

.. change::
:tags: bug, orm
:tickets: 4433

Improved error messages emitted by the ORM in the area of loader option
traversal.  This includes early detection of mis-matched loader strategies
along with a clearer explanation why these strategies don't match.


.. change::
:tags: change, orm
:tickets: 4412

Added a new function :func:`.close_all_sessions` which takes
over the task of the :meth:`.Session.close_all` method, which
is now deprecated as this is confusing as a classmethod.
Pull request courtesy Augustin Trancart.

.. change::
:tags: feature, orm
:tickets: 4397

Added new :meth:`.MapperEvents.before_mapper_configured` event.   This
event complements the other "configure" stage mapper events with a per
mapper event that receives each :class:`.Mapper` right before its
configure step, and additionally may be used to prevent or delay the
configuration of specific :class:`.Mapper` objects using a new
return value :attr:`.orm.interfaces.EXT_SKIP`.  See the
documentation link for an example.

.. seealso::

:meth:`.MapperEvents.before_mapper_configured`



.. change::
:tags: bug, orm

The "remove" event for collections is now called before the item is removed
in the case of the ``collection.remove()`` method, as is consistent with the
behavior for most other forms of collection item removal (such as
``__delitem__``, replacement under ``__setitem__``).  For ``pop()`` methods,
the remove event still fires after the operation.

.. change::
:tags: bug, orm declarative
:tickets: 4372

Added a ``__clause_element__()`` method to :class:`.ColumnProperty` which
can allow the usage of a not-fully-declared column or deferred attribute in
a declarative mapped class slightly more friendly when it's used in a
constraint or other column-oriented scenario within the class declaration,
though this still can't work in open-ended expressions; prefer to call the
:attr:`.ColumnProperty.expression` attribute if receiving ``TypeError``.

.. change::
:tags: bug, orm, engine
:tickets: 4464

Added accessors for execution options to Core and ORM, via
:meth:`.Query.get_execution_options`,
:meth:`.Connection.get_execution_options`,
:meth:`.Engine.get_execution_options`, and
:meth:`.Executable.get_execution_options`.  PR courtesy Daniel Lister.

.. change::
:tags: bug, orm
:tickets: 4446

Fixed issue in association proxy due to :ticket:`3423` which caused the use
of custom :class:`.PropComparator` objects with hybrid attributes, such as
the one demonstrated in  the ``dictlike-polymorphic`` example to not
function within an association proxy.  The strictness that was added in
:ticket:`3423` has been relaxed, and additional logic to accommodate for
an association proxy that links to a custom hybrid have been added.

.. change::
:tags: change, general
:tickets: 4393

A large change throughout the library has ensured that all objects,
parameters, and behaviors which have been noted as deprecated or legacy now
emit ``DeprecationWarning`` warnings when invoked.As the Python 3
interpreter now defaults to displaying deprecation warnings, as well as that
modern test suites based on tools like tox and pytest tend to display
deprecation warnings, this change should make it easier to note what API
features are obsolete. A major rationale for this change is so that long-
deprecated features that nonetheless still see continue to see real world
use can  finally be removed in the near future; the biggest example of this
are the :class:`.SessionExtension` and :class:`.MapperExtension` classes as
well as a handful of other pre-event extension hooks, which have been
deprecated since version 0.7 but still remain in the library.  Another is
that several major longstanding behaviors are to be deprecated as well,
including the threadlocal engine strategy, the convert_unicode flag, and non
primary mappers.

.. seealso::

:ref:`change_4393_general`


.. change::
:tags: change, engine
:tickets: 4393

The "threadlocal" engine strategy which has been a legacy feature of
SQLAlchemy since around version 0.2 is now deprecated, along with the
:paramref:`.Pool.threadlocal` parameter of :class:`.Pool` which has no
effect in most modern use cases.

.. seealso::

:ref:`change_4393_threadlocal`

.. change::
:tags: change, sql
:tickets: 4393

The :paramref:`.create_engine.convert_unicode` and
:paramref:`.String.convert_unicode` parameters have been deprecated.  These
parameters were built back when most Python DBAPIs had little to no support
for Python Unicode objects, and SQLAlchemy needed to take on the very
complex task of marshalling data and SQL strings between Unicode and
bytestrings throughout the system in a performant way.  Thanks to Python 3,
DBAPIs were compelled to adapt to Unicode-aware APIs and today all DBAPIs
supported by SQLAlchemy support Unicode natively, including on Python 2,
allowing this long-lived and very complicated feature to finally be (mostly)
removed.  There are still of course a few Python 2 edge cases where
SQLAlchemy has to deal with Unicode however these are handled automatically;
in modern use, there should be no need for end-user interaction with these
flags.

.. seealso::

:ref:`change_4393_convertunicode`

.. change::
:tags: bug, orm
:tickets: 3777

Implemented the ``.get_history()`` method, which also implies availability
of :attr:`.AttributeState.history`, for :func:`.synonym` attributes.
Previously, trying to access attribute history via a synonym would raise an
``AttributeError``.

.. change::
:tags: feature, engine
:tickets: 3689

Added public accessor :meth:`.QueuePool.timeout` that returns the configured
timeout for a :class:`.QueuePool` object.  Pull request courtesy Irina Delamare.

.. change::
:tags: feature, sql
:tickets: 4386

Amended the :class:`.AnsiFunction` class, the base of common SQL
functions like ``CURRENT_TIMESTAMP``, to accept positional arguments
like a regular ad-hoc function.  This to suit the case that many of
these functions on specific backends accept arguments such as
"fractional seconds" precision and such.  If the function is created
with arguments, it renders the parenthesis and the arguments.  If
no arguments are present, the compiler generates the non-parenthesized form.

.. changelog::

1.3.0b1

:released: March 4, 2019
:released: November 16, 2018

.. change::
:tags: bug, ext
:tickets: 3423

Reworked :class:`.AssociationProxy` to store state that's specific to a
parent class in a separate object, so that a single
:class:`.AssociationProxy` can serve for multiple parent classes, as is
intrinsic to inheritance, without any ambiguity in the state returned by it.
A new method :meth:`.AssociationProxy.for_class` is added to allow
inspection of class-specific state.

.. seealso::

:ref:`change_3423`


.. change::
:tags: bug, oracle
:tickets: 4369

Updated the parameters that can be sent to the cx_Oracle DBAPI to both allow
for all current parameters as well as for future parameters not added yet.
In addition, removed unused parameters that were deprecated in version 1.2,
and additionally we are now defaulting "threaded" to False.

.. seealso::

:ref:`change_4369`

.. change::
:tags: bug, oracle
:tickets: 4242

The Oracle dialect will no longer use the NCHAR/NCLOB datatypes
represent generic unicode strings or clob fields in conjunction with
:class:`.Unicode` and :class:`.UnicodeText` unless the flag
``use_nchar_for_unicode=True`` is passed to :func:`.create_engine` -
this includes CREATE TABLE behavior as well as ``setinputsizes()`` for
bound parameters.   On the read side, automatic Unicode conversion under
Python 2 has been added to CHAR/VARCHAR/CLOB result rows, to match the
behavior of cx_Oracle under Python 3.  In order to mitigate the performance
hit under Python 2, SQLAlchemy's very performant (when C extensions
are built) native Unicode handlers are used under Python 2.

.. seealso::

:ref:`change_4242`

.. change::
:tags: bug, orm
:tickets: 3844

Fixed issue regarding passive_deletes="all", where the foreign key
attribute of an object is maintained with its value even after the object
is removed from its parent collection.  Previously, the unit of work would
set this to NULL even though passive_deletes indicated it should not be
modified.

.. seealso::

:ref:`change_3844`

.. change::
:tags: bug, ext
:tickets: 4268

The long-standing behavior of the association proxy collection maintaining
only a weak reference to the parent object is reverted; the proxy will now
maintain a strong reference to the parent for as long as the proxy
collection itself is also in memory, eliminating the "stale association
proxy" error. This change is being made on an experimental basis to see if
any use cases arise where it causes side effects.

.. seealso::

:ref:`change_4268`


.. change::
:tags: bug, sql
:tickets: 4302

Added "like" based operators as "comparison" operators, including
:meth:`.ColumnOperators.startswith` :meth:`.ColumnOperators.endswith`
:meth:`.ColumnOperators.ilike` :meth:`.ColumnOperators.notilike` among many
others, so that all of these operators can be the basis for an ORM
"primaryjoin" condition.


.. change::
:tags: feature, sqlite
:tickets: 3850

Added support for SQLite's json functionality via the new
SQLite implementation for :class:`.types.JSON`, :class:`.sqlite.JSON`.
The name used for the type is ``JSON``, following an example found at
SQLite's own documentation. Pull request courtesy Ilja Everilä.

.. seealso::

:ref:`change_3850`

.. change::
:tags: feature, engine

Added new "lifo" mode to :class:`.QueuePool`, typically enabled by setting
the flag :paramref:`.create_engine.pool_use_lifo` to True.   "lifo" mode
means the same connection just checked in will be the first to be checked
out again, allowing excess connections to be cleaned up from the server
side during periods of the pool being only partially utilized.  Pull request
courtesy Taem Park.

.. seealso::

:ref:`change_pr467`

.. change::
:tags: bug, orm
:tickets: 4359

Improved the behavior of a relationship-bound many-to-one object expression
such that the retrieval of column values on the related object are now
resilient against the object being detached from its parent
:class:`.Session`, even if the attribute has been expired.  New features
within the :class:`.InstanceState` are used to memoize the last known value
of a particular column attribute before its expired, so that the expression
can still evaluate when the object is detached and expired at the same
time.  Error conditions are also improved using modern attribute state
features to produce more specific messages as needed.

.. seealso::

:ref:`change_4359`

.. change::
:tags: feature, mysql
:tickets: 4219

Support added for the "WITH PARSER" syntax of CREATE FULLTEXT INDEX
in MySQL, using the ``mysql_with_parser`` keyword argument.  Reflection
is also supported, which accommodates MySQL's special comment format
for reporting on this option as well.  Additionally, the "FULLTEXT" and
"SPATIAL" index prefixes are now reflected back into the ``mysql_prefix``
index option.



.. change::
:tags: bug, orm, mysql, postgresql
:tickets: 4246

The ORM now doubles the "FOR UPDATE" clause within the subquery that
renders in conjunction with joined eager loading in some cases, as it has
been observed that MySQL does not lock the rows from a subquery.   This
means the query renders with two FOR UPDATE clauses; note that on some
backends such as Oracle, FOR UPDATE clauses on subqueries are silently
ignored since they are unnecessary.  Additionally, in the case of the "OF"
clause used primarily with PostgreSQL, the FOR UPDATE is rendered only on
the inner subquery when this is used so that the selectable can be targeted
to the table within the SELECT statement.

.. seealso::

:ref:`change_4246`

.. change::
:tags: feature, mssql
:tickets: 4158

Added ``fast_executemany=True`` parameter to the SQL Server pyodbc dialect,
which enables use of pyodbc's new performance feature of the same name
when using Microsoft ODBC drivers.

.. seealso::

:ref:`change_4158`

.. change::
:tags: bug, ext
:tickets: 4308

Fixed multiple issues regarding de-association of scalar objects with the
association proxy.  ``del`` now works, and additionally a new flag
:paramref:`.AssociationProxy.cascade_scalar_deletes` is added, which when
set to True indicates that setting a scalar attribute to ``None`` or
deleting via ``del`` will also set the source association to ``None``.

.. seealso::

:ref:`change_4308`


.. change::
:tags: feature, ext
:tickets: 4318

Added new feature :meth:`.BakedQuery.to_query`, which allows for a
clean way of using one :class:`.BakedQuery` as a subquery inside of another
:class:`.BakedQuery` without needing to refer explicitly to a
:class:`.Session`.


.. change::
:tags: feature, sqlite
:tickets: 4360

Implemented the SQLite ``ON CONFLICT`` clause as understood at the DDL
level, e.g. for primary key, unique, and CHECK constraints as well as
specified on a :class:`.Column` to satisfy inline primary key and NOT NULL.
Pull request courtesy Denis Kataev.

.. seealso::

:ref:`change_4360`

.. change::
:tags: feature, postgresql
:tickets: 4237

Added rudimental support for reflection of PostgreSQL
partitioned tables, e.g. that relkind='p' is added to reflection
queries that return table information.

.. seealso::

:ref:`change_4237`

.. change::
:tags: feature, ext
:tickets: 4351

The :class:`.AssociationProxy` now has standard column comparison operations
such as :meth:`.ColumnOperators.like` and
:meth:`.ColumnOperators.startswith` available when the target attribute is a
plain column - the EXISTS expression that joins to the target table is
rendered as usual, but the column expression is then use within the WHERE
criteria of the EXISTS.  Note that this alters the behavior of the
``.contains()`` method on the association proxy to make use of
:meth:`.ColumnOperators.contains` when used on a column-based attribute.

.. seealso::

:ref:`change_4351`


.. change::
:tags: feature, orm

Added new flag :paramref:`.Session.bulk_save_objects.preserve_order` to the
:meth:`.Session.bulk_save_objects` method, which defaults to True. When set
to False, the given mappings will be grouped into inserts and updates per
each object type, to allow for greater opportunities to batch common
operations together.  Pull request courtesy Alessandro Cucci.

.. change::
:tags: bug, orm
:tickets: 4365

Refactored :meth:`.Query.join` to further clarify the individual components
of structuring the join. This refactor adds the ability for
:meth:`.Query.join` to determine the most appropriate "left" side of the
join when there is more than one element in the FROM list or the query is
against multiple entities.  If more than one FROM/entity matches, an error
is raised that asks for an ON clause to be specified to resolve the
ambiguity.  In particular this targets the regression we saw in
:ticket:`4363` but is also of general use.   The codepaths within
:meth:`.Query.join` are now easier to follow and the error cases are
decided more specifically at an earlier point in the operation.

.. seealso::

:ref:`change_4365`

.. change::
:tags: bug, sql
:tickets: 3981

Fixed issue with :meth:`.TypeEngine.bind_expression` and
:meth:`.TypeEngine.column_expression` methods where these methods would not
work if the target type were part of a :class:`.Variant`, or other target
type of a :class:`.TypeDecorator`.  Additionally, the SQL compiler now
calls upon the dialect-level implementation when it renders these methods
so that dialects can now provide for SQL-level processing for built-in
types.

.. seealso::

:ref:`change_3981`


.. change::
:tags: bug, orm
:tickets: 4304

Fixed long-standing issue in :class:`.Query` where a scalar subquery such
as produced by :meth:`.Query.exists`, :meth:`.Query.as_scalar` and other
derivations from :attr:`.Query.statement` would not correctly be adapted
when used in a new :class:`.Query` that required entity adaptation, such as
when the query were turned into a union, or a from_self(), etc. The change
removes the "no adaptation" annotation from the :func:`.select` object
produced by the :attr:`.Query.statement` accessor.

.. change::
:tags: bug, orm, declarative
:tickets: 4133

Fixed bug where declarative would not update the state of the
:class:`.Mapper` as far as what attributes were present, when additional
attributes were added or removed after the mapper attribute collections had
already been called and memoized.  Additionally, a ``NotImplementedError``
is now raised if a fully mapped attribute (e.g. column, relationship, etc.)
is deleted from a class that is currently mapped, since the mapper will not
function correctly if the attribute has been removed.

.. change::
:tags: bug, mssql
:tickets: 4362

Deprecated the use of :class:`.Sequence` with SQL Server in order to affect
the "start" and "increment" of the IDENTITY value, in favor of new
parameters ``mssql_identity_start`` and ``mssql_identity_increment`` which
set these parameters directly.  :class:`.Sequence` will be used to generate
real ``CREATE SEQUENCE`` DDL with SQL Server in a future release.

.. seealso::

:ref:`change_4362`


.. change::
:tags: feature, mysql

Added support for the parameters in an ON DUPLICATE KEY UPDATE statement on
MySQL to be ordered, since parameter order in a MySQL UPDATE clause is
significant, in a similar manner as that described at
:ref:`updates_order_parameters`.  Pull request courtesy Maxim Bublis.

.. seealso::

:ref:`change_mysql_ondupordering`

.. change::
:tags: feature, sql
:tickets: 4144

Added :class:`.Sequence` to the "string SQL" system that will render a
meaningful string expression (``"<next sequence value: my_sequence>"``)
when stringifying without a dialect a statement that includes a "sequence
nextvalue" expression, rather than raising a compilation error.



.. change::
:tags: bug, orm
:tickets: 4232

An informative exception is re-raised when a primary key value is not
sortable in Python during an ORM flush under Python 3, such as an ``Enum``
that has no ``__lt__()`` method; normally Python 3 raises a ``TypeError``
in this case.   The flush process sorts persistent objects by primary key
in Python so the values must be sortable.


.. change::
:tags: orm, bug
:tickets: 3604

Removed the collection converter used by the :class:`.MappedCollection`
class. This converter was used only to assert that the incoming dictionary
keys matched that of their corresponding objects, and only during a bulk set
operation.  The converter can interfere with a custom validator or
:meth:`.AttributeEvents.bulk_replace` listener that wants to convert
incoming values further.  The ``TypeError`` which would be raised by this
converter when an incoming key didn't match the value is removed; incoming
values during a bulk assignment will be keyed to their value-generated key,
and not the key that's explicitly present in the dictionary.

Overall, converter is superseded by the
:meth:`.AttributeEvents.bulk_replace` event handler added as part of
:ticket:`3896`.

.. change::
:tags: feature, sql
:tickets: 3989

Added new naming convention tokens ``column_0N_name``, ``column_0_N_name``,
etc., which will render the names / keys / labels for all columns referenced
by a particular constraint in a sequence.  In order to accommodate for the
length of such a naming convention, the SQL compiler's auto-truncation
feature now applies itself to constraint names as well, which creates a
shortened, deterministically generated name for the constraint that will
apply to a target backend without going over the character limit of that
backend.

The change also repairs two other issues.  One is that the  ``column_0_key``
token wasn't available even though this token was documented, the other was
that the ``referred_column_0_name`` token would  inadvertently render the
``.key`` and not the ``.name`` of the column if these two values were
different.

.. seealso::

:ref:`change_3989`


.. change::
:tags: feature, ext
:tickets: 4196

Added support for bulk :meth:`.Query.update` and :meth:`.Query.delete`
to the :class:`.ShardedQuery` class within the horizontal sharding
extension.  This also adds an additional expansion hook to the
bulk update/delete methods :meth:`.Query._execute_crud`.

.. seealso::

:ref:`change_4196`

.. change::
:tags: feature, sql
:tickets: 4271

Added new logic to the "expanding IN" bound parameter feature whereby if
the given list is empty, a special "empty set" expression that is specific
to different backends is generated, thus allowing IN expressions to be
fully dynamic including empty IN expressions.

.. seealso::

:ref:`change_4271`



.. change::
:tags: feature, mysql

The "pre-ping" feature of the connection pool now uses
the ``ping()`` method of the DBAPI connection in the case of
mysqlclient, PyMySQL and mysql-connector-python.  Pull request
courtesy Maxim Bublis.

.. seealso::

:ref:`change_mysql_ping`

.. change::
:tags: feature, orm
:tickets: 4340

The "selectin" loader strategy now omits the JOIN in the case of a simple
one-to-many load, where it instead relies loads only from the related
table, relying upon the foreign key columns of the related table in order
to match up to primary keys in the parent table.   This optimization can be
disabled by setting the :paramref:`.relationship.omit_join` flag to False.
Many thanks to Jayson Reis for the efforts on this.

.. seealso::

:ref:`change_4340`

.. change::
:tags: bug, orm
:tickets: 4353

Added new behavior to the lazy load that takes place when the "old" value of
a many-to-one is retrieved, such that exceptions which would be raised due
to either ``lazy="raise"`` or a detached session error are skipped.

.. seealso::

:ref:`change_4353`

.. change::
:tags: feature, sql

The Python builtin ``dir()`` is now supported for a SQLAlchemy "properties"
object, such as that of a Core columns collection (e.g. ``.c``),
``mapper.attrs``, etc.  Allows iPython autocompletion to work as well.
Pull request courtesy Uwe Korn.

.. change::
:tags: feature, orm
:tickets: 4257

Added ``.info`` dictionary to the :class:`.InstanceState` class, the object
that comes from calling :func:`.inspect` on a mapped object.

.. seealso::

:ref:`change_4257`

.. change::
:tags: feature, sql
:tickets: 3831

Added new feature :meth:`.FunctionElement.as_comparison` which allows a SQL
function to act as a binary comparison operation that can work within the
ORM.

.. seealso::

:ref:`change_3831`

.. change::
:tags: bug, orm
:tickets: 4354

A long-standing oversight in the ORM, the ``__delete__`` method for a many-
to-one relationship was non-functional, e.g. for an operation such as ``del
a.b``.  This is now implemented and is equivalent to setting the attribute
to ``None``.

.. seealso::

:ref:`change_4354`

1.2.19

:released: April 15, 2019

.. change::
:tags: bug, orm
:tickets: 4507

Fixed a regression in 1.2 due to the introduction of baked queries for
relationship lazy loaders, where a race condition is created during the
generation of the "lazy clause" which occurs within a memoized attribute. If
two threads initialize the memoized attribute concurrently, the baked query
could be generated with bind parameter keys that are then replaced with new
keys by the next run, leading to a lazy load query that specifies the
related criteria as ``None``. The fix establishes that the parameter names
are fixed before the new clause and parameter objects are generated, so that
the names are the same every time.

.. change::
:tags: bug, oracle
:tickets: 4506

Added support for reflection of the :class:`.NCHAR` datatype to the Oracle
dialect, and added :class:`.NCHAR` to the list of types exported by the
Oracle dialect.


.. change::
:tags: bug, examples
:tickets: 4528

Fixed bug in large_resultsets example case where a re-named "id" variable
due to code reformatting caused the test to fail.  Pull request courtesy
Matt Schuchhardt.

.. change::
:tags: bug, mssql
:tickets: 4536
:versions: 1.3.1

A commit() is emitted after an isolation level change to SNAPSHOT, as both
pyodbc and pymssql open an implicit transaction which blocks subsequent SQL
from being emitted in the current transaction.

.. change::
:tags: bug, engine
:tickets: 4406

Comparing two objects of :class:`.URL` using ``__eq__()`` did not take port
number into consideration, two objects differing only by port number were
considered equal. Port comparison is now added in ``__eq__()`` method of
:class:`.URL`, objects differing by port number are now not equal.
Additionally, ``__ne__()`` was not implemented for :class:`.URL` which
caused unexpected result when ``!=`` was used in Python2, since there are no
implied relationships among the comparison operators in Python2.

.. changelog::

1.2.18

:released: February 15, 2019

.. change::
:tags: bug, orm
:tickets: 4468

Fixed a regression in 1.2 where a wildcard/load_only loader option would
not work correctly against a loader path where of_type() were used to limit
to a particular subclass.  The fix only works for of_type() of a simple
subclass so far, not a with_polymorphic entity which will be addressed in a
separate issue; it is unlikely this latter case was working previously.


.. change::
:tags: bug, orm
:tickets: 4489

Fixed fairly simple but critical issue where the
:meth:`.SessionEvents.pending_to_persistent` event would be invoked for
objects not just when they move from pending to persistent, but when they
were also already persistent and just being updated, thus causing the event
to be invoked for all objects on every update.

.. change::
:tags: bug, sql
:tickets: 4485

Fixed issue where the :class:`.JSON` type had a read-only
:attr:`.JSON.should_evaluate_none` attribute, which would cause failures
when making use of the :meth:`.TypeEngine.evaluates_none` method in
conjunction with this type.  Pull request courtesy Sanjana S.

.. change::
:tags: bug, mssql
:tickets: 4499

Fixed bug where the SQL Server "IDENTITY_INSERT" logic that allows an INSERT
to proceed with an explicit value on an IDENTITY column was not detecting
the case where :meth:`.Insert.values` were used with a dictionary that
contained a :class:`.Column` as key and a SQL expression as a value.

.. change::
:tags: bug, sqlite
:tickets: 4474

Fixed bug in SQLite DDL where using an expression as a server side default
required that it be contained within parenthesis to be accepted by the
sqlite parser.  Pull request courtesy Bartlomiej Biernacki.

.. change::
:tags: bug, mysql
:tickets: 4492

Fixed a second regression caused by :ticket:`4344` (the first was
:ticket:`4361`), which works around MySQL issue 88718, where the lower
casing function used was not correct for Python 2 with OSX/Windows casing
conventions, which would then raise ``TypeError``.  Full coverage has been
added to this logic so that every codepath is exercised in a mock style for
all three casing conventions on all versions of Python. MySQL 8.0 has
meanwhile fixed issue 88718 so the workaround is only applies to a
particular span of MySQL 8.0 versions.

.. changelog::

1.2.17

:released: January 25, 2019

.. change::
:tags: feature, orm
:tickets: 4461

Added new event hooks :meth:`.QueryEvents.before_compile_update` and
:meth:`.QueryEvents.before_compile_delete` which complement
:meth:`.QueryEvents.before_compile` in the case of the :meth:`.Query.update`
and :meth:`.Query.delete` methods.


.. change::
:tags: bug, postgresql
:tickets: 4463

Revised the query used when reflecting CHECK constraints to make use of the
``pg_get_constraintdef`` function, as the ``consrc`` column is being
deprecated in PG 12.  Thanks to John A Stevenson for the tip.


.. change::
:tags: bug, orm
:tickets: 4454

Fixed issue where when using single-table inheritance in conjunction with a
joined inheritance hierarchy that uses "with polymorphic" loading, the
"single table criteria" for that single-table entity could get confused for
that of other entities from the same hierarchy used in the same query.The
adaption of the "single table criteria" is made more specific to the target
entity to avoid it accidentally getting adapted to other tables in the
query.


.. change::
:tags: bug, oracle
:tickets: 4457

Fixed regression in integer precision logic due to the refactor of the
cx_Oracle dialect in 1.2.  We now no longer apply the cx_Oracle.NATIVE_INT
type to result columns sending integer values (detected as positive
precision with scale ==0) which encounters integer overflow issues with
values that go beyond the 32 bit boundary.  Instead, the output variable
is left untyped so that cx_Oracle can choose the best option.

.. changelog::

1.2.16

:released: January 11, 2019

.. change::
:tag: bug, sql
:tickets: 4394

Fixed issue in "expanding IN" feature where using the same bound parameter
name more than once in a query would lead to a KeyError within the process
of rewriting the parameters in the query.

.. change::
:tags: bug, postgresql
:tickets: 4416

Fixed issue where a :class:`.postgresql.ENUM` or a custom domain present
in a remote schema would not be recognized within column reflection if
the name of the enum/domain or the name of the schema required quoting.
A new parsing scheme now fully parses out quoted or non-quoted tokens
including support for SQL-escaped quotes.

.. change::
:tags: bug, postgresql

Fixed issue where multiple :class:`.postgresql.ENUM` objects referred to
by the same :class:`.MetaData` object would fail to be created if
multiple objects had the same name under different schema names.  The
internal memoization the PostgreSQL dialect uses to track if it has
created a particular :class:`.postgresql.ENUM` in the database during
a DDL creation sequence now takes schema name into account.

.. change::
:tags: bug, engine
:tickets: 4429

Fixed a regression introduced in version 1.2 where a refactor
of the :class:`.SQLAlchemyError` base exception class introduced an
inappropriate coercion of a plain string message into Unicode under
python 2k, which is not handled by the Python interpreter for characters
outside of the platform's encoding (typically ascii).  The
:class:`.SQLAlchemyError` class now passes a bytestring through under
Py2K for ``__str__()`` as is the behavior of exception objects in general
under Py2K, does a safe coercion to unicode utf-8 with
backslash fallback for ``__unicode__()``.  For Py3K the message is
typically unicode already, but if not is again safe-coerced with utf-8
with backslash fallback for the ``__str__()`` method.

.. change::
:tags: bug, sql, oracle, mysql
:tickets: 4436

Fixed issue where the DDL emitted for :class:`.DropTableComment`, which
will be used by an upcoming version of Alembic, was incorrect for the MySQL
and Oracle databases.

.. change::
:tags: bug, sqlite
:tickets: 4431

Reflection of an index based on SQL expressions are now skipped with a
warning, in the same way as that of the Postgresql dialect, where we currently
do not support reflecting indexes that have SQL expressions within them.
Previously, an index with columns of None were produced which would break
tools like Alembic.

.. changelog::

1.2.15

:released: December 11, 2018

.. change::
:tags: bug, orm
:tickets: 4367

Fixed bug where the ORM annotations could be incorrect for the
primaryjoin/secondaryjoin a relationship if one used the pattern
``ForeignKey(SomeClass.id)`` in the declarative mappings.   This pattern
would leak undesired annotations into the join conditions which can break
aliasing operations done within :class:`.Query` that are not supposed to
impact elements in that join condition.  These annotations are now removed
up front if present.

.. change::
:tags: bug, orm, declarative
:tickets: 4374

A warning is emitted in the case that a :func:`.column` object is applied to
a declarative class, as it seems likely this intended to be a
:class:`.Column` object.

.. change::
:tags: bug, orm
:tickets: 4366

In continuing with a similar theme as that of very recent :ticket:`4349`,
repaired issue with :meth:`.RelationshipProperty.Comparator.any` and
:meth:`.RelationshipProperty.Comparator.has` where the "secondary"
selectable needs to be explicitly part of the FROM clause in the
EXISTS subquery to suit the case where this "secondary" is a :class:`.Join`
object.

.. change::
:tags: bug, orm
:tickets: 4363

Fixed regression caused by :ticket:`4349` where adding the "secondary"
table to the FROM clause for a dynamic loader would affect the ability of
the :class:`.Query` to make a subsequent join to another entity.   The fix
adds the primary entity as the first element of the FROM list since
:meth:`.Query.join` wants to jump from that.   Version 1.3 will have
a more comprehensive solution to this problem as well (:ticket:`4365`).




.. change::
:tags: bug, orm
:tickests: 4400

Fixed bug where chaining of mapper options using
:meth:`.RelationshipProperty.of_type` in conjunction with a chained option
that refers to an attribute name by string only would fail to locate the
attribute.

.. change::
:tag: feature, mysql
:tickets: 4381

Added support for the ``write_timeout`` flag accepted by mysqlclient and
pymysql to  be passed in the URL string.

.. change::
:tag: bug, postgresql
:tickets: 4377, 4380

Fixed issue where reflection of a PostgreSQL domain that is expressed as an
array would fail to be recognized.  Pull request courtesy Jakub Synowiec.


.. changelog::

1.2.14

:released: November 10, 2018

.. change::
:tags: bug, orm
:tickets: 4357

Fixed bug in :meth:`.Session.bulk_update_mappings` where alternate mapped
attribute names would result in the primary key column of the UPDATE
statement being included in the SET clause, as well as the WHERE clause;
while usually harmless, for SQL Server this can raise an error due to the
IDENTITY column.  This is a continuation of the same bug that was fixed in
:ticket:`3849`, where testing was insufficient to catch this additional
flaw.

.. change::
:tags: bug, mysql
:tickets: 4361

Fixed regression caused by :ticket:`4344` released in 1.2.13, where the fix
for MySQL 8.0's case sensitivity problem with referenced column names when
reflecting foreign key referents is worked around using the
``information_schema.columns`` view.  The workaround was failing on OSX /
``lower_case_table_names=2`` which produces non-matching casing for the
``information_schema.columns`` vs. that of ``SHOW CREATE TABLE``, so in
case-insensitive SQL modes case-insensitive matching is now used.

.. change::
:tags: bug, orm
:tickets: 4347

Fixed a minor performance issue which could in some cases add unnecessary
overhead to result fetching, involving the use of ORM columns and entities
that include those same columns at the same time within a query.  The issue
has to do with hash / eq overhead when referring to the column in different
ways.

.. changelog::

1.2.13

:released: October 31, 2018

.. change::
:tags: bug, postgresql
:tickets: 4337

Added support for the :class:`.aggregate_order_by` function to receive
multiple ORDER BY elements, previously only a single element was accepted.


.. change::
:tags: bug, mysql
:tickets: 4348

Added word ``function`` to the list of reserved words for MySQL, which is
now a keyword in MySQL 8.0

.. change::
:tags: feature, sql
:versions: 1.3.0b1

Refactored :class:`.SQLCompiler` to expose a
:meth:`.SQLCompiler.group_by_clause` method similar to the
:meth:`.SQLCompiler.order_by_clause` and :meth:`.SQLCompiler.limit_clause`
methods, which can be overridden by dialects to customize how GROUP BY
renders.  Pull request courtesy Samuel Chou.

.. change::
:tags: bug, misc

Fixed issue where part of the utility language helper internals was passing
the wrong kind of argument to the Python ``__import__`` builtin as the list
of modules to be imported.  The issue produced no symptoms within the core
library but could cause issues with external applications that redefine the
``__import__`` builtin or otherwise instrument it. Pull request courtesy Joe
Urciuoli.

.. change::
:tags: bug, orm
:tickets: 4349

Fixed bug where "dynamic" loader needs to explicitly set the "secondary"
table in the FROM clause of the query, to suit the case where the secondary
is a join object that is otherwise not pulled into the query from its
columns alone.


.. change::
:tags: bug, orm, declarative
:tickets: 4350

Fixed regression caused by :ticket:`4326` in version 1.2.12 where using
:class:`.declared_attr` with a mixin in conjunction with
:func:`.orm.synonym` would fail to map the synonym properly to an inherited
subclass.

.. change::
:tags: bug, misc, py3k
:tickets: 4339

Fixed additional warnings generated by Python 3.7 due to changes in the
organization of the Python ``collections`` and ``collections.abc`` packages.
Previous ``collections`` warnings were fixed in version 1.2.11. Pull request
courtesy xtreak.

.. change::
:tags: bug, ext

Added missing ``.index()`` method to list-based association collections
in the association proxy extension.

.. change::
:tags: bug, mysql
:tickets: 4344

Added a workaround for a MySQL bug 88718 introduced in the 8.0 series,
where the reflection of a foreign key constraint is not reporting the
correct case sensitivity for the referred column, leading to errors during
use of the reflected constraint such as when using the automap extension.
The workaround emits an additional query to the information_schema tables in
order to retrieve the correct case sensitive name.

.. change::
:tags: bug, sql
:tickets: 4341

Fixed bug where the :paramref:`.Enum.create_constraint` flag on  the
:class:`.Enum` datatype would not be propagated to copies of the type, which
affects use cases such as declarative mixins and abstract bases.

.. change::
:tags: bug, orm, declarative
:tickets: 4352

The column conflict resolution technique discussed at
:ref:`declarative_column_conflicts` is now functional for a :class:`.Column`
that is also a primary key column.  Previously, a check for primary key
columns declared on a single-inheritance subclass would occur before the
column copy were allowed to pass.


.. changelog::

1.2.12

:released: September 19, 2018

.. change::
:tags: bug, postgresql
:tickets: 4325

Fixed bug in PostgreSQL dialect where compiler keyword arguments such as
``literal_binds=True`` were not being propagated to a DISTINCT ON
expression.

.. change::
:tags: bug, ext
:tickets: 4328

Fixed issue where :class:`.BakedQuery` did not include the specific query
class used by the :class:`.Session` as part of the cache key, leading to
incompatibilities when using custom query classes, in particular the
:class:`.ShardedQuery` which has some different argument signatures.

.. change::
:tags: bug, postgresql
:tickets: 4324

Fixed the :func:`.postgresql.array_agg` function, which is a slightly
altered version of the usual :func:`.functions.array_agg` function, to also
accept an incoming "type" argument without forcing an ARRAY around it,
essentially the same thing that was fixed for the generic function in 1.1
in :ticket:`4107`.

.. change::
:tags: bug, postgresql
:tickets: 4323

Fixed bug in PostgreSQL ENUM reflection where a case-sensitive, quoted name
would be reported by the query including quotes, which would not match a
target column during table reflection as the quotes needed to be stripped
off.


.. change::
:tags: bug, orm

Added a check within the weakref cleanup for the :class:`.InstanceState`
object to check for the presence of the ``dict`` builtin, in an effort to
reduce error messages generated when these cleanups occur during interpreter
shutdown.  Pull request courtesy Romuald Brunet.

.. change::
:tags: bug, orm, declarative
:tickets: 4326

Fixed bug where the declarative scan for attributes would receive the
expression proxy delivered by a hybrid attribute at the class level, and
not the hybrid attribute itself, when receiving the descriptor via the
``declared_attr`` callable on a subclass of an already-mapped class. This
would lead to an attribute that did not report itself as a hybrid when
viewed within :attr:`.Mapper.all_orm_descriptors`.


.. change::
:tags: bug, orm
:tickets: 4334
:versions: 1.3.0b1

Fixed bug where use of :class:`.Lateral` construct in conjunction with
:meth:`.Query.join` as well as :meth:`.Query.select_entity_from` would not
apply clause adaption to the right side of the join.   "lateral" introduces
the use case of the right side of a join being correlatable.  Previously,
adaptation of this clause wasn't considered.   Note that in 1.2 only,
a selectable introduced by :meth:`.Query.subquery` is still not adapted
due to :ticket:`4304`; the selectable needs to be produced by the
:func:`.select` function to be the right side of the "lateral" join.

.. change::
:tags: bug, oracle
:tickets: 4335

Fixed issue for cx_Oracle 7.0 where the behavior of Oracle param.getvalue()
now returns a list, rather than a single scalar value, breaking
autoincrement logic throughout the Core and ORM. The dml_ret_array_val
compatibility flag is used for cx_Oracle 6.3 and 6.4 to establish compatible
behavior with 7.0 and forward, for cx_Oracle 6.2.1 and prior a version
number check falls back to the old logic.


.. change::
:tags: bug, orm
:tickets: 4327

Fixed 1.2 regression caused by :ticket:`3472` where the handling of an
"updated_at" style column within the context of a post-update operation
would also occur for a row that is to be deleted following the update,
meaning both that a column with a Python-side value generator would show
the now-deleted value that was emitted for the UPDATE before the DELETE
(which was not the previous behavior), as well as that a SQL- emitted value
generator would have the attribute expired, meaning the previous value
would be unreachable due to the row having been deleted and the object
detached from the session.The "postfetch" logic that was added as part of
:ticket:`3472` is now skipped entirely for an object that ultimately is to
be deleted.

.. changelog::

1.2.11

:released: August 20, 2018

.. change::
:tags: bug, py3k

Started importing "collections" from "collections.abc" under Python 3.3 and
greater for Python 3.8 compatibility.  Pull request courtesy Nathaniel
Knight.

.. change::
:tag: bug, sqlite

Fixed issue where the "schema" name used for a SQLite database within table
reflection would not quote the schema name correctly.  Pull request
courtesy Phillip Cloud.

.. change::
:tags: bug, sql
:tickets: 4320

Fixed issue that is closely related to :ticket:`3639` where an expression
rendered in a boolean context on a non-native boolean backend would
be compared to 1/0 even though it is already an implicitly boolean
expression, when :meth:`.ColumnElement.self_group` were used.  While this
does not affect the user-friendly backends (MySQL, SQLite) it was not
handled by Oracle (and possibly SQL Server).   Whether or not the
expression is implicitly boolean on any database is now determined
up front as an additional check to not generate the integer comparison
within the compilation of the statement.

.. change::
:tags: bug, oracle
:tickets: 4309

For cx_Oracle, Integer datatypes will now be bound to "int", per advice
from the cx_Oracle developers.  Previously, using cx_Oracle.NUMBER caused a
loss in precision within the cx_Oracle 6.x series.


.. change::
:tags: bug, orm, declarative
:tickets: 4321

Fixed issue in previously untested use case, allowing a declarative mapped
class to inherit from a classically-mapped class outside of the declarative
base, including that it accommodates for unmapped intermediate classes. An
unmapped intermediate class may specify ``__abstract__``, which is now
interpreted correctly, or the intermediate class can remain unmarked, and
the classically mapped base class will be detected within the hierarchy
regardless. In order to anticipate existing scenarios which may be mixing
in classical mappings into existing declarative hierarchies, an error is
now raised if multiple mapped bases are detected for a given class.

.. change::
:tags: bug, sql
:tickets: 4322

Added missing window function parameters
:paramref:`.WithinGroup.over.range_` and :paramref:`.WithinGroup.over.rows`
parameters to the :meth:`.WithinGroup.over` and
:meth:`.FunctionFilter.over` methods, to correspond to the range/rows
feature added to the "over" method of SQL functions as part of
:ticket:`3049` in version 1.1.

.. change::
:tags: bug, sql
:tickets: 4313

Fixed bug where the multi-table support for UPDATE and DELETE statements
did not consider the additional FROM elements as targets for correlation,
when a correlated SELECT were also combined with the statement.  This
change now includes that a SELECT statement in the WHERE clause for such a
statement will try to auto-correlate back to these additional tables in the
parent UPDATE/DELETE or unconditionally correlate if
:meth:`.Select.correlate` is used.  Note that auto-correlation raises an
error if the SELECT statement would have no FROM clauses as a result, which
can now occur if the parent UPDATE/DELETE specifies the same tables in its
additional set of tables; specify :meth:`.Select.correlate` explicitly to
resolve.

.. changelog::

1.2.10

:released: July 13, 2018

.. change::
:tags: bug, sql
:tickets: 4300

Fixed bug where a :class:`.Sequence` would be dropped explicitly before any
:class:`.Table` that refers to it, which breaks in the case when the
sequence is also involved in a server-side default for that table, when
using :meth:`.MetaData.drop_all`.   The step which processes sequences
to be dropped via non server-side column default functions is now invoked
after the table itself is dropped.

.. change::
:tags: bug, orm
:tickets: 4295

Fixed bug in :class:`.Bundle` construct where placing two columns of the
same name would be de-duplicated, when the :class:`.Bundle` were used as
part of the rendered SQL, such as in the ORDER BY or GROUP BY of the statement.


.. change::
:tags: bug, orm
:tickets: 4298

Fixed regression in 1.2.9 due to :ticket:`4287` where using a
:class:`.Load` option in conjunction with a string wildcard would result
in a TypeError.

.. changelog::

1.2.9

:released: June 29, 2018

.. change::
:tags: bug, mysql

Fixed percent-sign doubling in mysql-connector-python dialect, which does
not require de-doubling of percent signs.   Additionally, the  mysql-
connector-python driver is inconsistent in how it passes the column names
in cursor.description, so a workaround decoder has been added to
conditionally decode these randomly-sometimes-bytes values to unicode only
if needed.  Also improved test support for mysql-connector-python, however
it should be noted that this driver still has issues with unicode that
continue to be unresolved as of yet.


.. change::
:tags: bug, mssql
:tickets: 4288

Fixed bug in MSSQL reflection where when two same-named tables in different
schemas had same-named primary key constraints, foreign key constraints
referring to one of the tables would have their columns doubled, causing
errors.   Pull request courtesy Sean Dunn.

.. change::
:tags: bug, sql
:tickets: 4279

Fixed regression in 1.2 due to :ticket:`4147` where a :class:`.Table` that
has had some of its indexed columns redefined with new ones, as would occur
when overriding columns during reflection or when using
:paramref:`.Table.extend_existing`, such that the :meth:`.Table.tometadata`
method would fail when attempting to copy those indexes as they still
referred to the replaced column.   The copy logic now accommodates for this
condition.


.. change::
:tags: bug, mysql
:tickets: 4293

Fixed bug in index reflection where on MySQL 8.0 an index that includes
ASC or DESC in an indexed column specification would not be correctly
reflected, as MySQL 8.0 introduces support for returning this information
in a table definition string.

.. change::
:tags: bug, orm
:tickets: 3505

Fixed issue where chaining multiple join elements inside of
:meth:`.Query.join` might not correctly adapt to the previous left-hand
side, when chaining joined inheritance classes that share the same base
class.

.. change::
:tags: bug, orm
:tickets: 4287

Fixed bug in cache key generation for baked queries which could cause a
too-short cache key to be generated for the case of eager loads across
subclasses.  This could in turn cause the eagerload query to be cached in
place of a non-eagerload query, or vice versa, for a polymorhic "selectin"
load, or possibly for lazy loads or selectin loads as well.

.. change::
:tags: bug, sqlite

Fixed issue in test suite where SQLite 3.24 added a new reserved word that
conflicted with a usage in TypeReflectionTest.  Pull request courtesy Nils
Philippsen.

.. change::
:tags: feature, oracle
:tickets: 4290
:versions: 1.3.0b1

Added a new event currently used only by the cx_Oracle dialect,
:meth:`.DialectEvents.setiputsizes`.  The event passes a dictionary of
:class:`.BindParameter` objects to DBAPI-specific type objects that will be
passed, after conversion to parameter names, to the cx_Oracle
``cursor.setinputsizes()`` method.  This allows both visibility into the
setinputsizes process as well as the ability to alter the behavior of what
datatypes are passed to this method.

.. seealso::

:ref:`cx_oracle_setinputsizes`

.. change::
:tags: bug, orm
:tickets: 4286

Fixed bug in new polymorphic selectin loading where the BakedQuery used
internally would be mutated by the given loader options, which would both
inappropriately mutate the subclass query as well as carry over the effect
to subsequent queries.

.. change::
:tags: bug, py3k
:tickets: 4291

Replaced the usage of inspect.formatargspec() with a vendored version
copied from the Python standard library, as inspect.formatargspec()
is deprecated and as of Python 3.7.0 is emitting a warning.

.. change::
:tags: feature, ext
:tickets: 4243
:versions: 1.3.0b1

Added new attribute :attr:`.Query.lazy_loaded_from` which is populated
with an :class:`.InstanceState` that is using this :class:`.Query` in
order to lazy load a relationship.  The rationale for this is that
it serves as a hint for the horizontal sharding feature to use, such that
the identity token of the state can be used as the default identity token
to use for the query within id_chooser().

.. change::
:tags: bug, mysql
:tickets: 4283

Fixed bug in MySQLdb dialect and variants such as PyMySQL where an
additional "unicode returns" check upon connection makes explicit use of
the "utf8" character set, which in MySQL 8.0 emits a warning that utf8mb4
should be used.  This is now replaced with a utf8mb4 equivalent.
Documentation is also updated for the MySQL dialect to specify utf8mb4 in
all examples.  Additional changes have been made to the test suite to use
utf8mb3 charsets and databases (there seem to be collation issues in some
edge cases with utf8mb4), and to support configuration default changes made
in MySQL 8.0 such as explicit_defaults_for_timestamp as well as new errors
raised for invalid MyISAM indexes.



.. change::
:tags: bug, mysql
:tickets: 3645

The :class:`.Update` construct now accommodates a :class:`.Join` object
as supported by MySQL for UPDATE..FROM.  As the construct already
accepted an alias object for a similar purpose, the feature of UPDATE
against a non-table was already implied so this has been added.

.. change::
:tags: bug, mssql, py3k
:tickets: 4273

Fixed issue within the SQL Server dialect under Python 3 where when running
against a non-standard SQL server database that does not contain either the
"sys.dm_exec_sessions" or "sys.dm_pdw_nodes_exec_sessions" views, leading
to a failure to fetch the isolation level, the error raise would fail due
to an UnboundLocalError.



.. change::
:tags: bug, orm
:tickets: 4269

Fixed regression caused by :ticket:`4256` (itself a regression fix for
:ticket:`4228`) which breaks an undocumented behavior which converted for a
non-sequence of entities passed directly to the :class:`.Query` constructor
into a single-element sequence.  While this behavior was never supported or
documented, it's already in use so has been added as a behavioral contract
to :class:`.Query`.

.. change::
:tags: bug, orm
:tickets: 4270

Fixed an issue that was both a performance regression in 1.2 as well as an
incorrect result regarding the "baked" lazy loader, involving the
generation of cache keys from the original :class:`.Query` object's loader
options.  If the loader options were built up in a "branched" style using
common base elements for multiple options, the same options would be
rendered into the cache key repeatedly, causing both a performance issue as
well as generating the wrong cache key.  This is fixed, along with a
performance improvement when such "branched" options are applied via
:meth:`.Query.options` to prevent the same option objects from being
applied repeatedly.

.. change::
:tags: bug, oracle, mysql
:tickets: 4275

Fixed INSERT FROM SELECT with CTEs for the Oracle and MySQL dialects, where
the CTE was being placed above the entire statement as is typical with
other databases, however Oracle and MariaDB 10.2 wants the CTE underneath
the "INSERT" segment. Note that the Oracle and MySQL dialects don't yet
work when a CTE is applied to a subquery inside of an UPDATE or DELETE
statement, as the CTE is still applied to the top rather than inside the
subquery.


.. changelog::

1.2.8

:released: May 28, 2018

.. change::
:tags: bug, orm
:tickets: 4256

Fixed regression in 1.2.7 caused by :ticket:`4228`, which itself was fixing
a 1.2-level regression, where the ``query_cls`` callable passed to a
:class:`.Session` was assumed to be a subclass of :class:`.Query`  with
class method availability, as opposed to an arbitrary callable.    In
particular, the dogpile caching example illustrates ``query_cls`` as a
function and not a :class:`.Query` subclass.

.. change::
:tags: bug, engine
:tickets: 4252

Fixed connection pool issue whereby if a disconnection error were raised
during the connection pool's "reset on return" sequence in conjunction with
an explicit transaction opened against the enclosing :class:`.Connection`
object (such as from calling :meth:`.Session.close` without a rollback or
commit, or calling :meth:`.Connection.close` without first closing a
transaction declared with :meth:`.Connection.begin`), a double-checkin would
result, which could then lead towards concurrent checkouts of the same
connection. The double-checkin condition is now prevented overall by an
assertion, as well as the specific double-checkin scenario has been
fixed.

.. change::
:tags: bug, oracle
:tickets: 4264

The Oracle BINARY_FLOAT and BINARY_DOUBLE datatypes now participate within
cx_Oracle.setinputsizes(), passing along NATIVE_FLOAT, so as to support the
NaN value.  Additionally, :class:`.oracle.BINARY_FLOAT`,
:class:`.oracle.BINARY_DOUBLE` and :class:`.oracle.DOUBLE_PRECISION` now
subclass :class:`.Float`, since these are floating point datatypes, not
decimal.  These datatypes were already defaulting the
:paramref:`.Float.asdecimal` flag to False in line with what
:class:`.Float` already does.

.. change::
:tags: bug, oracle

Added reflection capabilities for the :class:`.oracle.BINARY_FLOAT`,
:class:`.oracle.BINARY_DOUBLE` datatypes.


.. change::
:tags: bug, ext
:tickets: 4247

The horizontal sharding extension now makes use of the identity token
added to ORM identity keys as part of :ticket:`4137`, when an object
refresh or column-based deferred load or unexpiration operation occurs.
Since we know the "shard" that the object originated from, we make
use of this value when refreshing, thereby avoiding queries against
other shards that don't match this object's identity in any case.

.. change::
:tags: bug, sql

Fixed issue where the "ambiguous literal" error message used when
interpreting literal values as SQL expression values would encounter a
tuple value, and fail to format the message properly. Pull request courtesy
Miguel Ventura.

.. change::
:tags: bug, mssql
:tickets: 4250

Fixed a 1.2 regression caused by :ticket:`4061` where the SQL Server
"BIT" type would be considered to be "native boolean".  The goal here
was to avoid creating a CHECK constraint on the column, however the bigger
issue is that the BIT value does not behave like a true/false constant
and cannot be interpreted as a standalone expression, e.g.
"WHERE <column>".   The SQL Server dialect now goes back to being
non-native boolean, but with an extra flag that still avoids creating
the CHECK constraint.

.. change::
:tags: bug, oracle
:tickets: 4259

Altered the Oracle dialect such that when an :class:`.Integer` type is in
use, the cx_Oracle.NUMERIC type is set up for setinputsizes().  In
SQLAlchemy 1.1 and earlier, cx_Oracle.NUMERIC was passed for all numeric
types unconditionally, and in 1.2 this was removed to allow for better
numeric precision.  However, for integers, some database/client setups
will fail to coerce boolean values True/False into integers which introduces
regressive behavior when using SQLAlchemy 1.2.  Overall, the setinputsizes
logic seems like it will need a lot more flexibility going forward so this
is a start for that.

.. change::
:tags: bug, engine

Fixed a reference leak issue where the values of the parameter dictionary
used in a statement execution would remain referenced by the "compiled
cache", as a result of storing the key view used by Python 3 dictionary
keys().  Pull request courtesy Olivier Grisel.

.. change::
:tags: bug, orm
:tickets: 4128

Fixed a long-standing regression that occurred in version
1.0, which prevented the use of a custom :class:`.MapperOption`
that alters the _params of a :class:`.Query` object for a
lazy load, since the lazy loader itself would overwrite those
parameters.   This applies to the "temporal range" example
on the wiki.  Note however that the
:meth:`.Query.populate_existing` method is now required in
order to rewrite the mapper options associated with an object
already loaded in the identity map.

As part of this change, a custom defined
:class:`.MapperOption` will now cause lazy loaders related to
the target object to use a non-baked query by default unless
the :meth:`.MapperOption._generate_cache_key` method is implemented.
In particular, this repairs one regression which occurred when
using the dogpile.cache "advanced" example, which was not
returning cached results and instead emitting SQL due to an
incompatibility with the baked query loader; with the change,
the ``RelationshipCache`` option included for many releases
in the dogpile example will disable the "baked" query altogether.
Note that the dogpile example is also modernized to avoid both
of these issues as part of issue :ticket:`4258`.

.. change::
:tags: bug, ext
:tickets: 4266

Fixed a race condition which could occur if automap
:meth:`.AutomapBase.prepare` were used within a multi-threaded context
against other threads which  may call :func:`.configure_mappers` as a
result of use of other mappers.  The unfinished mapping work of automap
is particularly sensitive to being pulled in by a
:func:`.configure_mappers` step leading to errors.

.. change::
:tags: bug, orm

Fixed bug where the new :meth:`.baked.Result.with_post_criteria`
method would not interact with a subquery-eager loader correctly,
in that the "post criteria" would not be applied to embedded
subquery eager loaders.   This is related to :ticket:`4128` in that
the post criteria feature is now used by the lazy loader.

.. change::
:tags: bug, tests
:tickets: 4249

Fixed a bug in the test suite where if an external dialect returned
``None`` for ``server_version_info``, the exclusion logic would raise an
``AttributeError``.

.. change::
:tags: bug, orm
:tickets: 4258

Updated the dogpile.caching example to include new structures that
accommodate for the "baked" query system, which is used by default within
lazy loaders and some eager relationship loaders. The dogpile.caching
"relationship_caching" and "advanced" examples were also broken due to
:ticket:`4256`.  The issue here is also worked-around by the fix in
:ticket:`4128`.

.. changelog::

1.2.7

:released: April 20, 2018

.. change::
:tags: bug, orm
:tickets: 4228

Fixed regression in 1.2 within sharded query feature where the
new "identity_token" element was not being correctly considered within
the scope of a lazy load operation, when searching the identity map
for a related many-to-one element.   The new behavior will allow for
making use of the "id_chooser" in order to determine the best identity
key to retrieve from the identity map.  In order to achieve this, some
refactoring of 1.2's "identity_token" approach has made some slight changes
to the implementation of ``ShardedQuery`` which should be noted for other
derivations of this class.

.. change::
:tags: bug, postgresql
:tickets: 4229

Fixed bug where the special "not equals" operator for the PostgreSQL
"range" datatypes such as DATERANGE would fail to render "IS NOT NULL" when
compared to the Python ``None`` value.



.. change::
:tags: bug, mssql
:tickets: 4234

Fixed 1.2 regression caused by :ticket:`4060` where the query used to
reflect SQL Server cross-schema foreign keys was limiting the criteria
incorrectly.



.. change::
:tags: bug, oracle

The Oracle NUMBER datatype is reflected as INTEGER if the precision is NULL
and the scale is zero, as this is how INTEGER values come back when
reflected from Oracle's tables.  Pull request courtesy Kent Bower.

.. change::
:tags: feature, postgresql
:tickets: 4160
:versions: 1.3.0b1

Added new PG type :class:`.postgresql.REGCLASS` which assists in casting
table names to OID values.  Pull request courtesy Sebastian Bank.

.. change::
:tags: bug, sql
:tickets: 4231

Fixed issue where the compilation of an INSERT statement with the
"literal_binds" option that also uses an explicit sequence and "inline"
generation, as on PostgreSQL and Oracle, would fail to accommodate the
extra keyword argument within the sequence processing routine.

.. change::
:tags: bug, orm
:tickets: 4241

Fixed issue in single-inheritance loading where the use of an aliased
entity against a single-inheritance subclass in conjunction with the
:meth:`.Query.select_from` method would cause the SQL to be rendered with
the unaliased table mixed in to the query, causing a cartesian product.  In
particular this was affecting the new "selectin" loader when used against a
single-inheritance subclass.

.. changelog::

1.2.6

:released: March 30, 2018

.. change::
:tags: bug, mssql
:tickets: 4227

Adjusted the SQL Server version detection for pyodbc to only allow for
numeric tokens, filtering out non-integers, since the dialect does tuple-
numeric comparisons with this value.  This is normally true for all known
SQL Server / pyodbc drivers in any case.

.. change::
:tags: feature, postgresql

Added support for "PARTITION BY" in PostgreSQL table definitions,
using "postgresql_partition_by".  Pull request courtesy
Vsevolod Solovyov.

.. change::
:tags: bug, sql
:tickets: 4204

Fixed a regression that occurred from the previous fix to :ticket:`4204` in
version 1.2.5, where a CTE that refers to itself after the
:meth:`.CTE.alias` method has been called would not refer to itself
correctly.

.. change::
:tags: bug, engine
:tickets: 4225

Fixed bug in connection pool where a connection could be present in the
pool without all of its "connect" event handlers called, if a previous
"connect" handler threw an exception; note that the dialects themselves
have connect handlers that emit SQL, such as those which set transaction
isolation, which can fail if the database is in a non-available state, but
still allows a connection.  The connection is now invalidated first if any
of the connect handlers fail.

.. change::
:tags: bug, oracle
:tickets: 4211

The minimum cx_Oracle version supported is 5.2 (June 2015).  Previously,
the dialect asserted against version 5.0 but as of 1.2.2 we are using some
symbols that did not appear until 5.2.

.. change::
:tags: bug, declarative
:tickets: 4221

Removed a warning that would be emitted when calling upon
``__table_args__``, ``__mapper_args__`` as named with a ``declared_attr``
method, when called from a non-mapped declarative mixin.  Calling these
directly is documented as the approach to use when one is overriding one
of these methods on a mapped class.  The warning still emits for regular
attribute names.

.. change::
:tags: bug, orm
:tickets: 4215

Fixed bug where using :meth:`.Mutable.associate_with` or
:meth:`.Mutable.as_mutable` in conjunction with a class that has non-
primary mappers set up with alternatively-named attributes would produce an
attribute error.  Since non-primary mappers are not used for persistence,
the mutable extension now excludes non-primary mappers from its
instrumentation steps.


.. changelog::

1.2.5

:released: March 6, 2018

.. change::
:tags: bug, sql
:tickets: 4210

Fixed bug in :class:.`CTE` construct along the same lines as that of
:ticket:`4204` where a :class:`.CTE` that was aliased would not copy itself
correctly during a "clone" operation as is frequent within the ORM as well
as when using the :meth:`.ClauseElement.params` method.

.. change::
:tags: bug, orm
:tickets: 4199

Fixed bug in new "polymorphic selectin" loading when a selection of
polymorphic objects were to be partially loaded from a relationship
lazy loader, leading to an "empty IN" condition within the load that
raises an error for the "inline" form of "IN".

.. change::
:tags: bug, sql
:tickets: 4204

Fixed bug in CTE rendering where a :class:`.CTE` that was also turned into
an :class:`.Alias` would not render its "ctename AS aliasname" clause
appropriately if there were more than one reference to the CTE in a FROM
clause.

.. change::
:tags: bug, orm
:tickets: 4209

Fixed 1.2 regression where a mapper option that contains an
:class:`.AliasedClass` object, as is typical when using the
:meth:`.QueryableAttribute.of_type` method, could not be pickled.   1.1's
behavior was to omit the aliased class objects from the path, so this
behavior is restored.

.. change::
:tags: feature, orm
:versions: 1.3.0b1

Added new feature :meth:`.Query.only_return_tuples`.  Causes the
:class:`.Query` object to return keyed tuple objects unconditionally even
if the query is against a single entity.   Pull request courtesy Eric
Atkin.


.. change::
:tags: bug, sql
:tickets: 4198

Fixed bug in new "expanding IN parameter" feature where the bind parameter
processors for values wasn't working at all, tests failed to cover this
pretty basic case which includes that ENUM values weren't working.

.. changelog::

1.2.4

:released: February 22, 2018

.. change::
:tags: bug, orm
:tickets: 4193

Fixed 1.2 regression in ORM versioning feature where a mapping against a
:func:`.select` or :func:`.alias` that also used a versioning column
against the underlying table would fail due to the check added as part of
:ticket:`3673`.

.. change::
:tags: bug, engine
:tickets: 4190

Fixed regression caused in 1.2.3 due to fix from :ticket:`4181` where
the changes to the event system involving :class:`.Engine` and
:class:`.OptionEngine` did not accommodate for event removals, which
would raise an ``AttributeError`` when invoked at the class
level.

.. change::
:tags: bug, sql
:tickets: 4197

Fixed bug where CTE expressions would not have their name or alias name
quoted when the given name is case sensitive or otherwise requires quoting.
Pull request courtesy Eric Atkin.

.. changelog::

1.2.3

:released: February 16, 2018

.. change::
:tags: bug, oracle
:tickets: 4182

Fixed bug in cx_Oracle disconnect detection, used by pre_ping and other
features, where an error could be raised as DatabaseError which includes a
numeric error code; previously we weren't checking in this case for a
disconnect code.

.. change::
:tags: bug, sqlite

Fixed the import error raised when a platform
has neither pysqlite2 nor sqlite3 installed, such
that the sqlite3-related import error is raised,
not the pysqlite2 one which is not the actual
failure mode.  Pull request courtesy Robin.

.. change::
:tags: bug, orm
:tickets: 4175

Fixed bug where the :class:`.Bundle` object did not
correctly report upon the primary :class:`.Mapper` object
represented by the bundle, if any.   An immediate
side effect of this issue was that the new selectinload
loader strategy wouldn't work with the horizontal sharding
extension.

.. change::
:tags: bug, sql
:tickets: 4180

Fixed bug where the :class:`.Enum` type wouldn't handle
enum "aliases" correctly, when more than one key refers to the
same value.  Pull request courtesy Daniel Knell.


.. change::
:tags: bug, engine
:tickets: 4181

Fixed bug where events associated with an :class:`Engine`
at the class level would be doubled when the
:meth:`.Engine.execution_options` method were used.  To
achieve this, the semi-private class :class:`.OptionEngine`
no longer accepts events directly at the class level
and will raise an error; the class only propagates class-level
events from its parent :class:`.Engine`.   Instance-level
events continue to work as before.

.. change::
:tags: bug, tests
:tickets: 3265

A test added in 1.2 thought to confirm a Python 2.7 behavior turns out to
be confirming the behavior only as of Python 2.7.8. Python bug 8743 still
impacts set comparison in Python 2.7.7 and earlier, so the test in question
involving AssociationSet no longer runs for these older Python 2.7
versions.

.. change::
:tags: feature, oracle

The ON DELETE options for foreign keys are now part of
Oracle reflection.  Oracle does not support ON UPDATE
cascades.  Pull request courtesy Miroslav Shubernetskiy.



.. change::
:tags: bug, orm
:tickets: 4188

Fixed bug in concrete inheritance mapping where user-defined
attributes such as hybrid properties that mirror the names
of mapped attributes from sibling classes would be overwritten by
the mapper as non-accessible at the instance level.   Additionally
ensured that user-bound descriptors are not implicitly invoked at the class
level during the mapper configuration stage.

.. change::
:tags: bug, orm
:tickets: 4178

Fixed bug where the :func:`.orm.reconstructor` event
helper would not be recognized if it were applied to the
``__init__()`` method of the mapped class.

.. change::
:tags: bug, engine
:tickets: 4170

The :class:`.URL` object now allows query keys to be specified multiple
times where their values will be joined into a list.  This is to support
the plugins feature documented at :class:`.CreateEnginePlugin` which
documents that "plugin" can be passed multiple times. Additionally, the
plugin names can be passed to :func:`.create_engine` outside of the URL
using the new :paramref:`.create_engine.plugins` parameter.

.. change::
:tags: feature, sql
:tickets: 3906

Added support for :class:`.Enum` to persist the values of the enumeration,
rather than the keys, when using a Python pep-435 style enumerated object.
The user supplies a callable function that will return the string values to
be persisted.  This allows enumerations against non-string values to be
value-persistable as well.  Pull request courtesy Jon Snyder.

.. change::
:tags: feature, orm

Added new argument :paramref:`.attributes.set_attribute.inititator`
to the :func:`.attributes.set_attribute` function, allowing an
event token received from a listener function to be propagated
to subsequent set events.

.. changelog::

1.2.2

:released: January 24, 2018

.. change::
:tags: bug, mssql
:tickets: 4164

Added ODBC error code 10054 to the list of error
codes that count as a disconnect for ODBC / MSSQL server.


.. change::
:tags: bug, orm
:tickets: 4171

Fixed 1.2 regression regarding new bulk_replace event
where a backref would fail to remove an object from the
previous owner when a bulk-assignment assigned the
object to a new owner.

.. change::
:tags: bug, oracle
:tickets: 4163

The cx_Oracle dialect now calls setinputsizes() with cx_Oracle.NCHAR
unconditionally when the NVARCHAR2 datatype, in SQLAlchemy corresponding
to sqltypes.Unicode(), is in use.  Per cx_Oracle's author this allows
the correct conversions to occur within the Oracle client regardless
of the setting for NLS_NCHAR_CHARACTERSET.

.. change::
:tags: bug, mysql

Added more MySQL 8.0 reserved words to the MySQL dialect
for quoting purposes.  Pull request courtesy
Riccardo Magliocchetti.

.. changelog::

1.2.1

:released: January 15, 2018

.. change::
:tags: bug, orm
:tickets: 4159

Fixed regression where pickle format of a Load / _UnboundLoad object (e.g.
loader options) changed and ``__setstate__()`` was raising an
UnboundLocalError for an object received from the legacy format, even
though an attempt was made to do so.  tests are now added to ensure this
works.

.. change::
:tags: bug, ext
:tickets: 4150

Fixed regression in association proxy due to :ticket:`3769`
(allow for chained any() / has()) where contains() against
an association proxy chained in the form
(o2m relationship, associationproxy(m2o relationship, m2o relationship))
would raise an error regarding the re-application of contains()
on the final link of the chain.

.. change::
:tags: bug, orm
:tickets: 4153

Fixed regression caused by new lazyload caching scheme in :ticket:`3954`
where a query that makes use of loader options with of_type would cause
lazy loads of unrelated paths to fail with a TypeError.

.. change::
:tags: bug, oracle
:tickets: 4157

Fixed regression where the removal of most setinputsizes
rules from cx_Oracle dialect impacted the TIMESTAMP
datatype's ability to retrieve fractional seconds.



.. change::
:tags: bug, tests

Removed an oracle-specific requirements rule from the public
test suite that was interfering with third party dialect
suites.

.. change::
:tags: bug, mssql
:tickets: 4154

Fixed regression in 1.2 where newly repaired quoting
of collation names in :ticket:`3785` breaks SQL Server,
which explicitly does not understand a quoted collation
name.   Whether or not mixed-case collation names are
quoted or not is now deferred down to a dialect-level
decision so that each dialect can prepare these identifiers
directly.

.. change::
:tags: bug, orm
:tickets: 4156

Fixed bug in new "selectin" relationship loader where the loader could try
to load a non-existent relationship when loading a collection of
polymorphic objects, where only some of the mappers include that
relationship, typically when :meth:`.PropComparator.of_type` is being used.

.. change::
:tags: bug, tests

Added a new exclusion rule group_by_complex_expression
which disables tests that use "GROUP BY <expr>", which seems
to be not viable for at least two third party dialects.

.. change::
:tags: bug, oracle

Fixed regression in Oracle imports where a missing comma caused
an undefined symbol to be present.  Pull request courtesy
Miroslav Shubernetskiy.

.. changelog::

1.2.0

:released: December 27, 2017

.. change::
:tags: orm, feature
:tickets: 4137

Added a new data member to the identity key tuple
used by the ORM's identity map, known as the
"identity_token".  This token defaults to None but
may be used by database sharding schemes to differentiate
objects in memory with the same primary key that come
from different databases.   The horizontal sharding
extension integrates this token applying the shard
identifier to it, thus allowing primary keys to be
duplicated across horizontally sharded backends.

.. seealso::

:ref:`change_4137`

.. change::
:tags: bug, mysql
:tickets: 4115

Fixed regression from issue 1.2.0b3 where "MariaDB" version comparison can
fail for some particular MariaDB version strings under Python 3.

.. change::
:tags: enhancement, sql
:tickets: 959

Implemented "DELETE..FROM" syntax for PostgreSQL, MySQL, MS SQL Server
(as well as within the unsupported Sybase dialect) in a manner similar
to how "UPDATE..FROM" works.  A DELETE statement that refers to more than
one table will switch into "multi-table" mode and render the appropriate
"USING" or multi-table "FROM" clause as understood by the database.
Pull request courtesy Pieter Mulder.

.. seealso::

:ref:`change_959`

.. change::
:tags: bug, sql
:tickets: 2694

Reworked the new "autoescape" feature introduced in
:ref:`change_2694` in 1.2.0b2 to be fully automatic; the escape
character now defaults to a forwards slash ``"/"`` and
is applied to percent, underscore, as well as the escape
character itself, for fully automatic escaping.  The
character can also be changed using the "escape" parameter.

.. seealso::

:ref:`change_2694`


.. change::
:tags: bug, sql
:tickets: 4147

Fixed bug where the :meth:`.Table.tometadata` method would not properly
accommodate :class:`.Index` objects that didn't consist of simple
column expressions, such as indexes against a :func:`.text` construct,
indexes that used SQL expressions or :attr:`.func`, etc.   The routine
now copies expressions fully to a new :class:`.Index` object while
substituting all table-bound :class:`.Column` objects for those
of the target table.

.. change::
:tags: bug, sql
:tickets: 4142

Changed the "visit name" of :class:`.ColumnElement` from "column" to
"column_element", so that when this element is used as the basis for a
user-defined SQL element, it is not assumed to behave like a table-bound
:class:`.ColumnClause` when processed by various SQL traversal utilities,
as are commonly used by the ORM.

.. change::
:tags: bug, sql, ext
:tickets: 4141

Fixed issue in :class:`.ARRAY` datatype which is essentially the same
issue as that of :ticket:`3832`, except not a regression, where
column attachment events on top of :class:`.ARRAY` would not fire
correctly, thus interfering with systems which rely upon this.   A key
use case that was broken by this is the use of mixins to declare
columns that make use of :meth:`.MutableList.as_mutable`.

.. change::
:tags: feature, engine
:tickets: 4089

The "password" attribute of the :class:`.url.URL` object can now be
any user-defined or user-subclassed string object that responds to the
Python ``str()`` builtin.   The object passed will be maintained as the
datamember :attr:`.url.URL.password_original` and will be consulted
when the :attr:`.url.URL.password` attribute is read to produce the
string value.

.. change::
:tags: bug, orm
:tickets: 4130

Fixed bug in :func:`.contains_eager` query option where making use of a
path that used :meth:`.PropComparator.of_type` to refer to a subclass
across more than one level of joins would also require that the "alias"
argument were provided with the same subtype in order to avoid adding
unwanted FROM clauses to the query; additionally,  using
:func:`.contains_eager` across subclasses that use :func:`.aliased` objects
of subclasses as the :meth:`.PropComparator.of_type` argument will also
render correctly.




.. change::
:tags: feature, postgresql

Added new :class:`.postgresql.MONEY` datatype.  Pull request courtesy
Cleber J Santos.

.. change::
:tags: bug, sql
:tickets: 4140

Fixed bug in new "expanding bind parameter" feature whereby if multiple
params were used in one statement, the regular expression would not
match the parameter name correctly.

.. change::
:tags: enhancement, ext
:tickets: 4135

Added new method :meth:`.baked.Result.with_post_criteria` to baked
query system, allowing non-SQL-modifying transformations to take place
after the query has been pulled from the cache.  Among other things,
this method can be used with :class:`.horizontal_shard.ShardedQuery`
to set the shard identifier.   :class:`.horizontal_shard.ShardedQuery`
has also been modified such that its :meth:`.ShardedQuery.get` method
interacts correctly with that of :class:`.baked.Result`.

.. change::
:tags: bug, oracle
:tickets: 4064

Added some additional rules to fully handle ``Decimal('Infinity')``,
``Decimal('-Infinity')`` values with cx_Oracle numerics when using
``asdecimal=True``.

.. change::
:tags: bug, mssql
:tickets: 4121

Fixed bug where sqltypes.BINARY and sqltypes.VARBINARY datatypes
would not include correct bound-value handlers for pyodbc,
which allows the pyodbc.NullParam value to be passed that
helps with FreeTDS.




.. change::
:tags: feature, misc

Added a new errors section to the documentation with background
about common error messages.   Selected exceptions within SQLAlchemy
will include a link in their string output to the relevant section
within this page.

.. change::
:tags: bug, orm
:tickets: 4032

The :meth:`.Query.exists` method will now disable eager loaders for when
the query is rendered.  Previously, joined-eager load joins would be rendered
unnecessarily as well as subquery eager load queries would be needlessly
generated.   The new behavior matches that of the :meth:`.Query.subquery`
method.

.. changelog::

1.2.0b3

:released: December 27, 2017
:released: October 13, 2017

.. change::
:tags: feature, postgresql
:tickets: 4109

Added a new flag ``use_batch_mode`` to the psycopg2 dialect.  This flag
enables the use of psycopg2's ``psycopg2.extras.execute_batch``
extension when the :class:`.Engine` calls upon
``cursor.executemany()``. This extension provides a critical
performance increase by over an order of magnitude when running INSERT
statements in batch.  The flag is False by default as it is considered
to be experimental for now.

.. seealso::

:ref:`change_4109`

.. change::
:tags: bug, mssql
:tickets: 4061

SQL Server supports what SQLAlchemy calls "native boolean"
with its BIT type, as this type only accepts 0 or 1 and the
DBAPIs return its value as True/False.   So the SQL Server
dialects now enable "native boolean" support, in that a
CHECK constraint is not generated for a :class:`.Boolean`
datatype.  The only difference vs. other native boolean
is that there are no "true" / "false" constants so "1" and
"0" are still rendered here.


.. change::
:tags: bug, oracle
:tickets: 4064

Partial support for persisting and retrieving the Oracle value
"infinity" is implemented with cx_Oracle, using Python float values
only, e.g. ``float("inf")``.  Decimal support is not yet fulfilled by
the cx_Oracle DBAPI driver.

.. change::
:tags: bug, oracle

The cx_Oracle dialect has been reworked and modernized to take advantage of
new patterns that weren't present in the old 4.x series of cx_Oracle. This
includes that the minimum cx_Oracle version is the 5.x series and that
cx_Oracle 6.x is now fully tested. The most significant change involves
type conversions, primarily regarding the numeric / floating point and LOB
datatypes, making more effective use of cx_Oracle type handling hooks to
simplify how bind parameter and result data is processed.

.. seealso::

:ref:`change_cxoracle_12`

.. change::
:tags: bug, oracle
:tickets: 3997

two phase support for cx_Oracle has been completely removed for all
versions of cx_Oracle, whereas in 1.2.0b1 this change only took effect for
the 6.x series of cx_Oracle.  This feature never worked correctly
in any version of cx_Oracle and in cx_Oracle 6.x, the API which SQLAlchemy
relied upon was removed.

.. seealso::

:ref:`change_cxoracle_12`

.. change::
:tags: bug, oracle

The column keys present in a result set when using :meth:`.Insert.returning`
with the cx_Oracle backend now use the correct column / label names
like that of all other dialects.  Previously, these came out as
``ret_nnn``.

.. seealso::

:ref:`change_cxoracle_12`

.. change::
:tags: bug, oracle

Several parameters to the cx_Oracle dialect are now deprecated and will
have no effect: ``auto_setinputsizes``, ``exclude_setinputsizes``,
``allow_twophase``.

.. seealso::

:ref:`change_cxoracle_12`


.. change::
:tags: bug, sql
:tickets: 4075

Added a new method :meth:`.DefaultExecutionContext.get_current_parameters`
which is used within a function-based default value generator in
order to retrieve the current parameters being passed to the statement.
The new function differs from the
:attr:`.DefaultExecutionContext.current_parameters` attribute in
that it also provides for optional grouping of parameters that
correspond to a multi-valued "insert" construct.  Previously it was not
possible to identify the subset of parameters that were relevant to
the function call.

.. seealso::

:ref:`change_4075`

:ref:`context_default_functions`

.. change::
:tags: bug, orm
:tickets: 4050

Fixed regression introduced in 1.2.0b1 due to :ticket:`3934` where the
:class:`.Session` would fail to "deactivate" the transaction, if a
rollback failed (the target issue is when MySQL loses track of a SAVEPOINT).
This would cause a subsequent call to :meth:`.Session.rollback` to raise
an error a second time, rather than completing and bringing the
:class:`.Session` back to ACTIVE.

.. change::
:tags: bug, postgresql
:tickets: 4041

Fixed bug where the pg8000 driver would fail if using
:meth:`.MetaData.reflect` with a schema name, since the schema name would
be sent as a "quoted_name" object that's a string subclass, which pg8000
doesn't recognize.   The quoted_name type is added to pg8000's
py_types collection on connect.

.. change::
:tags: bug, postgresql
:tickets: 4016

Enabled UUID support for the pg8000 driver, which supports native Python
uuid round trips for this datatype.  Arrays of UUID are still not supported,
however.

.. change::
:tags: mssql, bug
:tickets: 4057

Fixed the pymssql dialect so that percent signs in SQL text, such
as used in modulus expressions or literal textual values, are
**not** doubled up, as seems to be what pymssql expects.  This is
despite the fact that the pymssql DBAPI uses the "pyformat" parameter
style which itself considers the percent sign to be significant.

.. change::
:tags: bug, orm, declarative
:tickets: 4091

A warning is emitted if a subclass attempts to override an attribute
that was declared on a superclass using ``declared_attr.cascading``
that the overridden attribute will be ignored. This use
case cannot be fully supported down to further subclasses without more
complex development efforts, so for consistency the "cascading" is
honored all the way down regardless of overriding attributes.

.. change::
:tags: bug, orm, declarative
:tickets: 4092

A warning is emitted if the ``declared_attr.cascading`` attribute is
used with a special declarative name such as ``__tablename__``, as this
has no effect.

.. change::
:tags: feature, engine
:tickets: 4077

Added ``__next__()`` and ``next()`` methods to :class:`.ResultProxy`,
so that the ``next()`` builtin function works on the object directly.
:class:`.ResultProxy` has long had an ``__iter__()`` method which already
allows it to respond to the ``iter()`` builtin.   The implementation
for ``__iter__()`` is unchanged, as performance testing has indicated
that iteration using a ``__next__()`` method with ``StopIteration``
is about 20% slower in both Python 2.7 and 3.6.

.. change::
:tags: feature, mssql
:tickets: 4086

Added a new :class:`.mssql.TIMESTAMP` datatype, that
correctly acts like a binary datatype for SQL Server
rather than a datetime type, as SQL Server breaks the
SQL standard here.  Also added :class:`.mssql.ROWVERSION`,
as the "TIMESTAMP" type in SQL Server is deprecated in
favor of ROWVERSION.

.. change::
:tags: bug, orm
:tickets: 4084

Fixed issue where the :func:`.make_transient_to_detached` function
would expire all attributes on the target object, including "deferred"
attributes, which has the effect of the attribute being undeferred
for the next refresh, causing an unexpected load of the attribute.

.. change::
:tags: bug, orm
:tickets: 4040

Fixed bug involving delete-orphan cascade where a related item
that becomes an orphan before the parent object is part of a
session is still tracked as moving into orphan status, which results
in it being expunged from the session rather than being flushed.

.. note::  This fix was inadvertently merged during the 1.2.0b3
release and was **not added to the changelog** at that time.
This changelog note was added to the release retroactively as of
version 1.2.13.

.. change::
:tags: bug, orm
:tickets: 4026

Fixed bug in :ref:`change_3948` which prevented "selectin" and
"inline" settings in a multi-level class hierarchy from interacting
together as expected.    A new example is added to the documentation.

.. seealso::

:ref:`polymorphic_selectin_and_withpoly`

.. change::
:tags: bug, oracle
:tickets: 4042

Fixed bug where an index reflected under Oracle with an expression like
"column DESC" would not be returned, if the table also had no primary
key, as a result of logic that attempts to filter out the
index implicitly added by Oracle onto the primary key columns.

.. change::
:tags: bug, orm
:tickets: 4071

Removed the warnings that are emitted when the LRU caches employed
by the mapper as well as loader strategies reach their threshold; the
purpose of this warning was at first a guard against excess cache keys
being generated but became basically a check on the "creating many
engines" antipattern.   While this is still an antipattern, the presence
of test suites which both create an engine per test as well as raise
on all warnings will be an inconvenience; it should not be critical
that such test suites change their architecture just for this warning
(though engine-per-test suite is always better).

.. change::
:tags: bug, orm
:tickets: 4049

Fixed regression where the use of a :func:`.undefer_group` option
in conjunction with a lazy loaded relationship option would cause
an attribute error, due to a bug in the SQL cache key generation
added in 1.2 as part of :ticket:`3954`.

.. change::
:tags: bug, oracle
:tickets: 4045

Fixed more regressions caused by cx_Oracle 6.0; at the moment, the only
behavioral change for users is disconnect detection now detects for
cx_Oracle.DatabaseError in addition to cx_Oracle.InterfaceError, as
this behavior seems to have changed.   Other issues regarding numeric
precision and uncloseable connections are pending with the upstream
cx_Oracle issue tracker.

.. change::
:tags: bug, mssql
:tickets: 4060

Fixed bug where the SQL Server dialect could pull columns from multiple
schemas when reflecting a self-referential foreign key constraint, if
multiple schemas contained a constraint of the same name against a
table of the same name.


.. change::
:tags: feature, mssql
:tickets: 4058

Added support for "AUTOCOMMIT" isolation level, as established
via :meth:`.Connection.execution_options`, to the
PyODBC and pymssql dialects.   This isolation level sets the
appropriate DBAPI-specific flags on the underlying
connection object.

.. change::
:tags: bug, orm
:tickets: 4073

Modified the change made to the ORM update/delete evaluator in
:ticket:`3366` such that if an unmapped column expression is present
in the update or delete, if the evaluator can match its name to the
mapped columns of the target class, a warning is emitted, rather than
raising UnevaluatableError.  This is essentially the pre-1.2 behavior,
and is to allow migration for applications that are currently relying
upon this pattern.  However, if the given attribute name cannot be
matched to the columns of the mapper, the UnevaluatableError is
still raised, which is what was fixed in :ticket:`3366`.

.. change::
:tags: bug, sql
:tickets: 4087

Fixed bug in new SQL comments feature where table and column comment
would not be copied when using :meth:`.Table.tometadata`.

.. change::
:tags: bug, sql
:tickets: 4102

In release 1.1, the :class:`.Boolean` type was broken in that
boolean coercion via ``bool()`` would occur for backends that did not
feature "native boolean", but would not occur for native boolean backends,
meaning the string ``"0"`` now behaved inconsistently. After a poll, a
consensus was reached that non-boolean values should be raising an error,
especially in the ambiguous case of string ``"0"``; so the :class:`.Boolean`
datatype will now raise ``ValueError`` if an incoming value is not
within the range ``None, True, False, 1, 0``.

.. seealso::

:ref:`change_4102`

.. change::
:tags: bug, sql
:tickets: 4063

Refined the behavior of :meth:`.Operators.op` such that in all cases,
if the :paramref:`.Operators.op.is_comparison` flag is set to True,
the return type of the resulting expression will be
:class:`.Boolean`, and if the flag is False, the return type of the
resulting expression will be the same type as that of the left-hand
expression, which is the typical default behavior of other operators.
Also added a new parameter :paramref:`.Operators.op.return_type` as well
as a helper method :meth:`.Operators.bool_op`.

.. seealso::

:ref:`change_4063`

.. change::
:tags: bug, mysql
:tickets: 4072

Changed the name of the ``.values`` attribute of the new MySQL
INSERT..ON DUPLICATE KEY UPDATE construct to ``.inserted``, as
:class:`.Insert` already has a method called :meth:`.Insert.values`.
The ``.inserted`` attribute ultimately renders the MySQL ``VALUES()``
function.

.. change::
:tags: bug, mssql, orm
:tickets: 4062

Added a new class of "rowcount support" for dialects that is specific to
when "RETURNING", which on SQL Server looks like "OUTPUT inserted", is in
use, as the PyODBC backend isn't able to give us rowcount on an UPDATE or
DELETE statement when OUTPUT is in effect.  This primarily affects the ORM
when a flush is updating a row that contains server-calculated values,
raising an error if the backend does not return the expected row count.
PyODBC now states that it supports rowcount except if OUTPUT.inserted is
present, which is taken into account by the ORM during a flush as to
whether it will look for a rowcount.

.. change::
:tags: bug, sql
:tickets: 4088

Internal refinements to the :class:`.Enum`, :class:`.Interval`, and
:class:`.Boolean` types, which now extend a common mixin
:class:`.Emulated` that indicates a type that provides Python-side
emulation of a DB native type, switching out to the DB native type when a
supporting backend is in use.   The PostgreSQL :class:`.INTERVAL` type
when used directly will now include the correct type coercion rules for
SQL expressions that also take effect for :class:`.sqltypes.Interval`
(such as adding a date to an interval yields a datetime).


.. change::
:tags: bug, mssql, orm

Enabled the "sane_rowcount" flag for the pymssql dialect, indicating
that the DBAPI now reports the correct number of rows affected from
an UPDATE or DELETE statement.  This impacts mostly the ORM versioning
feature in that it now can verify the number of rows affected on a
target version.

.. change:: 4028
:tags: bug, engine
:tickets: 4028

Made some adjustments to :class:`.Pool` and :class:`.Connection` such
that recovery logic is not run underneath exception catches for
``pool.Empty``, ``AttributeError``, since when the recovery operation
itself fails, Python 3 creates a misleading stack trace referring to the
``Empty`` / ``AttributeError`` as the cause, when in fact these exception
catches are part of control flow.


.. change::
:tags: bug, oracle
:tickets: 4076

Fixed bug where Oracle 8 "non ansi" join mode would not add the
``(+)`` operator to expressions that used an operator other than the
``=`` operator.  The ``(+)`` needs to be on all columns that are part
of the right-hand side.

.. change::
:tags: bug, mssql
:tickets: 4059

Added a rule to SQL Server index reflection to ignore the so-called
"heap" index that is implicitly present on a table that does not
specify a clustered index.


.. changelog::

1.2.0b2

:released: December 27, 2017
:released: July 24, 2017

.. change:: 4033
:tags: bug, orm
:tickets: 4033

Fixed regression from 1.1.11 where adding additional non-entity
columns to a query that includes an entity with subqueryload
relationships would fail, due to an inspection added in 1.1.11 as a
result of :ticket:`4011`.


.. changelog::

1.2.0b1

:released: December 27, 2017
:released: July 10, 2017

.. change:: scoped_autocommit
:tags: feature, orm

Added ``.autocommit`` attribute to :class:`.scoped_session`, proxying
the ``.autocommit`` attribute of the underling :class:`.Session`
currently assigned to the thread.  Pull request courtesy
Ben Fagin.

.. change:: 4009
:tags: feature, mysql
:tickets: 4009

Added support for MySQL's ON DUPLICATE KEY UPDATE
MySQL-specific :class:`.mysql.dml.Insert` object.
Pull request courtesy Michael Doronin.

.. seealso::

:ref:`change_4009`

.. change:: 4018
:tags: bug, sql
:tickets: 4018

The rules for type coercion between :class:`.Numeric`, :class:`.Integer`,
and date-related types now include additional logic that will attempt
to preserve the settings of the incoming type on the "resolved" type.
Currently the target for this is the ``asdecimal`` flag, so that
a math operation between :class:`.Numeric` or :class:`.Float` and
:class:`.Integer` will preserve the "asdecimal" flag as well as
if the type should be the :class:`.Float` subclass.

.. seealso::

:ref:`change_floats_12`

.. change:: 4020
:tags: bug, sql, mysql
:tickets: 4020

The result processor for the :class:`.Float` type now unconditionally
runs values through the ``float()`` processor if the dialect
specifies that it also supports "native decimal" mode.  While most
backends will deliver Python ``float`` objects for a floating point
datatype, the MySQL backends in some cases lack the typing information
in order to provide this and return ``Decimal`` unless the float
conversion is done.

.. seealso::

:ref:`change_floats_12`

.. change:: 4017
:tags: bug, sql
:tickets: 4017

Added some extra strictness to the handling of Python "float" values
passed to SQL statements.  A "float" value will be associated with the
:class:`.Float` datatype and not the Decimal-coercing :class:`.Numeric`
datatype as was the case before, eliminating a confusing warning
emitted on SQLite as well as unnecessary coercion to Decimal.

.. seealso::

:ref:`change_floats_12`

.. change:: 3058
:tags: feature, orm
:tickets: 3058

Added a new feature :func:`.orm.with_expression` that allows an ad-hoc
SQL expression to be added to a specific entity in a query at result
time.  This is an alternative to the SQL expression being delivered as
a separate element in the result tuple.

.. seealso::

:ref:`change_3058`

.. change:: 3496
:tags: bug, orm
:tickets: 3496

An UPDATE emitted as a result of the
:paramref:`.relationship.post_update` feature will now integrate with
the versioning feature to both bump the version id of the row as well
as assert that the existing version number was matched.

.. seealso::

:ref:`change_3496`

.. change:: 3769
:tags: bug, ext
:tickets: 3769

The :meth:`.AssociationProxy.any`, :meth:`.AssociationProxy.has`
and :meth:`.AssociationProxy.contains` comparison methods now support
linkage to an attribute that is itself also an
:class:`.AssociationProxy`, recursively.

.. seealso::

:ref:`change_3769`

.. change:: 3853
:tags: bug, ext
:tickets: 3853

Implemented in-place mutation operators ``__ior__``, ``__iand__``,
``__ixor__`` and ``__isub__`` for :class:`.mutable.MutableSet`
and ``__iadd__`` for :class:`.mutable.MutableList` so that change
events are fired off when these mutator methods are used to alter the
collection.

.. seealso::

:ref:`change_3853`

.. change:: 3847
:tags: bug, declarative
:tickets: 3847

A warning is emitted if the :attr:`.declared_attr.cascading` modifier
is used with a declarative attribute that is itself declared on
a class that is to be mapped, as opposed to a declarative mixin
class or ``__abstract__`` class.  The :attr:`.declared_attr.cascading`
modifier currently only applies to mixin/abstract classes.

.. change:: 4003
:tags: feature, oracle
:tickets: 4003

The Oracle dialect now inspects unique and check constraints when using
:meth:`.Inspector.get_unique_constraints`,
:meth:`.Inspector.get_check_constraints`.
As Oracle does not have unique constraints that are separate from a unique
:class:`.Index`, a :class:`.Table` that's reflected will still continue
to not have :class:`.UniqueConstraint` objects associated with it.
Pull requests courtesy Eloy Felix.

.. seealso::

:ref:`change_4003`

.. change:: 3948
:tags: feature, orm
:tickets: 3948

Added a new style of mapper-level inheritance loading
"polymorphic selectin".  This style of loading
emits queries for each subclass in an inheritance
hierarchy subsequent to the load of the base
object type, using IN to specify the desired
primary key values.

.. seealso::

:ref:`change_3948`

.. change:: 3472
:tags: bug, orm
:tickets: 3471, 3472

Repaired several use cases involving the
:paramref:`.relationship.post_update` feature when used in conjunction
with a column that has an "onupdate" value.   When the UPDATE emits,
the corresponding object attribute is now expired or refreshed so that
the newly generated "onupdate" value can populate on the object;
previously the stale value would remain.  Additionally, if the target
attribute is set in Python for the INSERT of the object, the value is
now re-sent during the UPDATE so that the "onupdate" does not overwrite
it (note this works just as well for server-generated onupdates).
Finally, the :meth:`.SessionEvents.refresh_flush` event is now emitted
for these attributes when refreshed within the flush.

.. seealso::

:ref:`change_3471`

.. change:: 3996
:tags: bug, orm
:tickets: 3996

Fixed bug where programmatic version_id counter in conjunction with
joined table inheritance would fail if the version_id counter
were not actually incremented and no other values on the base table
were modified, as the UPDATE would have an empty SET clause.  Since
programmatic version_id where version counter is not incremented
is a documented use case, this specific condition is now detected
and the UPDATE now sets the version_id value to itself, so that
concurrency checks still take place.

.. change:: 3848
:tags: bug, orm, declarative
:tickets: 3848

Fixed bug where using :class:`.declared_attr` on an
:class:`.AbstractConcreteBase` where a particular return value were some
non-mapped symbol, including ``None``, would cause the attribute
to hard-evaluate just once and store the value to the object
dictionary, not allowing it to invoke for subclasses.   This behavior
is normal when :class:`.declared_attr` is on a mapped class, and
does not occur on a mixin or abstract class.  Since
:class:`.AbstractConcreteBase` is both "abstract" and actually
"mapped", a special exception case is made here so that the
"abstract" behavior takes precedence for :class:`.declared_attr`.

.. change:: 3673
:tags: bug, orm
:tickets: 3673

The versioning feature does not support NULL for the version counter.
An exception is now raised if the version id is programmatic and
was set to NULL for an UPDATE.  Pull request courtesy Diana Clarke.

.. change:: 3999
:tags: bug, sql
:tickets: 3999

The operator precedence for all comparison operators such as LIKE, IS,
IN, MATCH, equals, greater than, less than, etc. has all been merged
into one level, so that expressions which make use of these against
each other will produce parentheses between them.   This suits the
stated operator precedence of databases like Oracle, MySQL and others
which place all of these operators as equal precedence, as well as
PostgreSQL as of 9.5 which has also flattened its operator precedence.

.. seealso::

:ref:`change_3999`


.. change:: 3796
:tags: bug, orm
:tickets: 3796

Removed a very old keyword argument from :class:`.scoped_session`
called ``scope``.  This keyword was never documented and was an
early attempt at allowing for variable scopes.

.. seealso::

:ref:`change_3796`

.. change:: 3871
:tags: bug, mysql
:tickets: 3871

Added support for views that are unreflectable due to stale
table definitions, when calling :meth:`.MetaData.reflect`; a warning
is emitted for the table that cannot respond to ``DESCRIBE``,
but the operation succeeds.

.. change:: baked_opts
:tags: feature, ext

Added new flag :paramref:`.Session.enable_baked_queries` to the
:class:`.Session` to allow baked queries to be disabled
session-wide, reducing memory use.   Also added new :class:`.Bakery`
wrapper so that the bakery returned by :paramref:`.BakedQuery.bakery`
can be inspected.

.. change:: 3988
:tags: bug, orm
:tickets: 3988

Fixed bug where combining a "with_polymorphic" load in conjunction
with subclass-linked relationships that specify joinedload with
innerjoin=True, would fail to demote those "innerjoins" to
"outerjoins" to suit the other polymorphic classes that don't
support that relationship.   This applies to both a single and a
joined inheritance polymorphic load.

.. change:: 3991
:tags: bug, orm
:tickets: 3991

Added new argument :paramref:`.with_for_update` to the
:meth:`.Session.refresh` method.  When the :meth:`.Query.with_lockmode`
method were deprecated in favor of :meth:`.Query.with_for_update`,
the :meth:`.Session.refresh` method was never updated to reflect
the new option.

.. seealso::

:ref:`change_3991`

.. change:: 3984
:tags: bug, orm
:tickets: 3984

Fixed bug where a :func:`.column_property` that is also marked as
"deferred" would be marked as "expired" during a flush, causing it
to be loaded along with the unexpiry of regular attributes even
though this attribute was never accessed.

.. change:: 3873
:tags: bug, sql
:tickets: 3873

Repaired issue where the type of an expression that used
:meth:`.ColumnOperators.is_` or similar would not be a "boolean" type,
instead the type would be "nulltype", as well as when using custom
comparison operators against an untyped expression.   This typing can
impact how the expression behaves in larger contexts as well as
in result-row-handling.

.. change:: 3941
:tags: bug, ext
:tickets: 3941

Improved the association proxy list collection so that premature
autoflush against a newly created association object can be prevented
in the case where ``list.append()`` is being used, and a lazy load
would be invoked when the association proxy accesses the endpoint
collection.  The endpoint collection is now accessed first before
the creator is invoked to produce the association object.

.. change:: 3969
:tags: bug, sql
:tickets: 3969

Fixed the negation of a :class:`.Label` construct so that the
inner element is negated correctly, when the :func:`.not_` modifier
is applied to the labeled expression.

.. change:: 3944
:tags: feature, orm
:tickets: 3944

Added a new kind of eager loading called "selectin" loading.  This
style of loading is very similar to "subquery" eager loading,
except that it uses an IN expression given a list of primary key
values from the loaded parent objects, rather than re-stating the
original query.   This produces a more efficient query that is
"baked" (e.g. the SQL string is cached) and also works in the
context of :meth:`.Query.yield_per`.

.. seealso::

:ref:`change_3944`

.. change::
:tags: bug, orm
:tickets: 3967

Fixed bug in subquery eager loading where the "join_depth" parameter
for self-referential relationships would not be correctly honored,
loading all available levels deep rather than correctly counting
the specified number of levels for eager loading.

.. change::
:tags: bug, orm

Added warnings to the LRU "compiled cache" used by the :class:`.Mapper`
(and ultimately will be for other ORM-based LRU caches) such that
when the cache starts hitting its size limits, the application will
emit a warning that this is a performance-degrading situation that
may require attention.   The LRU caches can reach their size limits
primarily if an application is making use of an unbounded number
of :class:`.Engine` objects, which is an antipattern.  Otherwise,
this may suggest an issue that should be brought to the SQLAlchemy
developer's attention.

.. change:: 3964
:tags: bug, postgresql
:tickets: 3964

Fixed bug where the base :class:`.sqltypes.ARRAY` datatype would not
invoke the bind/result processors of :class:`.postgresql.ARRAY`.

.. change:: 3963
:tags: bug, orm
:tickets: 3963

Fixed bug to improve upon the specificity of loader options that
take effect subsequent to the lazy load of a related entity, so
that the loader options will match to an aliased or non-aliased
entity more specifically if those options include entity information.

.. change:: 3954
:tags: feature, orm
:tickets: 3954

The ``lazy="select"`` loader strategy now makes used of the
:class:`.BakedQuery` query caching system in all cases.  This
removes most overhead of generating a :class:`.Query` object and
running it into a :func:`.select` and then string SQL statement from
the process of lazy-loading related collections and objects.  The
"baked" lazy loader has also been improved such that it can now
cache in most cases where query load options are used.

.. seealso::

:ref:`change_3954`

.. change:: 3740
:tags: bug, sql
:tickets: 3740

The system by which percent signs in SQL statements are "doubled"
for escaping purposes has been refined.   The "doubling" of percent
signs mostly associated with the :obj:`.literal_column` construct
as well as operators like :meth:`.ColumnOperators.contains` now
occurs based on the stated paramstyle of the DBAPI in use; for
percent-sensitive paramstyles as are common with the PostgreSQL
and MySQL drivers the doubling will occur, for others like that
of SQLite it will not.   This allows more database-agnostic use
of the :obj:`.literal_column` construct to be possible.

.. seealso::

:ref:`change_3740`

.. change:: 3959
:tags: bug, postgresql
:tickets: 3959

Added support for all possible "fields" identifiers when reflecting the
PostgreSQL ``INTERVAL`` datatype, e.g. "YEAR", "MONTH", "DAY TO
MINUTE", etc..   In addition, the :class:`.postgresql.INTERVAL`
datatype itself now includes a new parameter
:paramref:`.postgresql.INTERVAL.fields` where these qualifiers can be
specified; the qualifier is also reflected back into the resulting
datatype upon reflection / inspection.

.. seealso::

:ref:`change_3959`

.. change:: 3957
:tags: bug, sql
:tickets: 3957

Fixed bug where a column-level :class:`.CheckConstraint` would fail
to compile the SQL expression using the underlying dialect compiler
as well as apply proper flags to generate literal values as
inline, in the case that the sqltext is a Core expression and
not just a plain string.   This was long-ago fixed for table-level
check constraints in 0.9 as part of :ticket:`2742`, which more commonly
feature Core SQL expressions as opposed to plain string expressions.

.. change:: 2626
:tags: bug, mssql
:tickets: 2626

The SQL Server dialect now allows for a database and/or owner name
with a dot inside of it, using brackets explicitly in the string around
the owner and optionally the database name as well.  In addition,
sending the :class:`.quoted_name` construct for the schema name will
not split on the dot and will deliver the full string as the "owner".
:class:`.quoted_name` is also now available from the ``sqlalchemy.sql``
import space.

.. seealso::

:ref:`change_2626`

.. change:: 3953
:tags: feature, sql
:tickets: 3953

Added a new kind of :func:`.bindparam` called "expanding".  This is
for use in ``IN`` expressions where the list of elements is rendered
into individual bound parameters at statement execution time, rather
than at statement compilation time.  This allows both a single bound
parameter name to be linked to an IN expression of multiple elements,
as well as allows query caching to be used with IN expressions.  The
new feature allows the related features of "select in" loading and
"polymorphic in" loading to make use of the baked query extension
to reduce call overhead.   This feature should be considered to be
**experimental** for 1.2.

.. seealso::

:ref:`change_3953`

.. change:: 3923
:tags: bug, sql
:tickets: 3923

Fixed bug where a SQL-oriented Python-side column default could fail to
be executed properly upon INSERT in the "pre-execute" codepath, if the
SQL itself were an untyped expression, such as plain text.  The "pre-
execute" codepath is fairly uncommon however can apply to non-integer
primary key columns with SQL defaults when RETURNING is not used.

.. change:: 3785
:tags: bug, sql
:tickets: 3785

The expression used for COLLATE as rendered by the column-level
:func:`.expression.collate` and :meth:`.ColumnOperators.collate` is now
quoted as an identifier when the name is case sensitive, e.g. has
uppercase characters.  Note that this does not impact type-level
collation, which is already quoted.

.. seealso::

:ref:`change_3785`

.. change:: 3229
:tags: feature, orm, ext
:tickets: 3229

The :meth:`.Query.update` method can now accommodate both
hybrid attributes as well as composite attributes as a source
of the key to be placed in the SET clause.   For hybrids, an
additional decorator :meth:`.hybrid_property.update_expression`
is supplied for which the user supplies a tuple-returning function.

.. seealso::

:ref:`change_3229`

.. change:: 3753
:tags: bug, orm
:tickets: 3753

The :func:`.attributes.flag_modified` function now raises
:class:`.InvalidRequestError` if the named attribute key is not
present within the object, as this is assumed to be present
in the flush process.  To mark an object "dirty" for a flush
without referring to any specific attribute, the
:func:`.attributes.flag_dirty` function may be used.

.. seealso::

:ref:`change_3753`

.. change:: 3911_3912
:tags: bug, ext
:tickets: 3911, 3912

The :class:`sqlalchemy.ext.hybrid.hybrid_property` class now supports
calling mutators like ``setter``, ``expression`` etc. multiple times
across subclasses, and now provides a ``getter`` mutator, so that
a particular hybrid can be repurposed across subclasses or other
classes.  This now matches the behavior of ``property`` in standard
Python.

.. seealso::

:ref:`change_3911_3912`



.. change:: 1546
:tags: feature, sql, postgresql, mysql, oracle
:tickets: 1546

Added support for SQL comments on :class:`.Table` and :class:`.Column`
objects, via the new :paramref:`.Table.comment` and
:paramref:`.Column.comment` arguments.   The comments are included
as part of DDL on table creation, either inline or via an appropriate
ALTER statement, and are also reflected back within table reflection,
as well as via the :class:`.Inspector`.   Supported backends currently
include MySQL, PostgreSQL, and Oracle.  Many thanks to Frazer McLean
for a large amount of effort on this.

.. seealso::

:ref:`change_1546`

.. change:: 3919
:tags: feature, engine
:tickets: 3919

Added native "pessimistic disconnection" handling to the :class:`.Pool`
object.  The new parameter :paramref:`.Pool.pre_ping`, available from
the engine as :paramref:`.create_engine.pool_pre_ping`, applies an
efficient form of the "pre-ping" recipe featured in the pooling
documentation, which upon each connection check out, emits a simple
statement, typically "SELECT 1", to test the connection for liveness.
If the existing connection is no longer able to respond to commands,
the connection is transparently recycled, and all other connections
made prior to the current timestamp are invalidated.

.. seealso::

:ref:`pool_disconnects_pessimistic`

:ref:`change_3919`

.. change:: 3939
:tags: bug, sql
:tickets: 3939

Fixed bug where the use of an :class:`.Alias` object in a column
context would raise an argument error when it tried to group itself
into a parenthesized expression.   Using :class:`.Alias` in this way
is not yet a fully supported API, however it applies to some end-user
recipes and may have a more prominent role in support of some
future PostgreSQL features.

.. change:: 3366
:tags: bug, orm
:tickets: 3366

The "evaluate" strategy used by :meth:`.Query.update` and
:meth:`.Query.delete` can now accommodate a simple
object comparison from a many-to-one relationship to an instance,
when the attribute names of the primary key / foreign key columns
don't match the actual names of the columns.  Previously this would
do a simple name-based match and fail with an AttributeError.

.. change:: 3896_a
:tags: feature, orm
:tickets: 3896

Added new attribute event :meth:`.AttributeEvents.bulk_replace`.
This event is triggered when a collection is assigned to a
relationship, before the incoming collection is compared with the
existing one.  This early event allows for conversion of incoming
non-ORM objects as well.  The event is integrated with the
``validates`` decorator.

.. seealso::

:ref:`change_3896_event`

.. change:: 3896_b
:tags: bug, orm
:tickets: 3896

The ``validates`` decorator now allows the decorated method to receive
objects from a "bulk collection set" operation that have not yet
been compared to the existing collection.  This allows incoming values
to be converted to compatible ORM objects as is already allowed
from an "append" event.   Note that this means that the
``validates`` method is called for **all** values during a collection
assignment, rather than just the ones that are new.

.. seealso::

:ref:`change_3896_validates`

.. change:: 3938
:tags: bug, engine
:tickets: 3938

Fixed bug where in the unusual case of passing a
:class:`.Compiled` object directly to :meth:`.Connection.execute`,
the dialect with which the :class:`.Compiled` object were generated
was not consulted for the paramstyle of the string statement, instead
assuming it would match the dialect-level paramstyle, causing
mismatches to occur.

.. change:: 3303
:tags: feature, orm
:tickets: 3303

Added new event handler :meth:`.AttributeEvents.modified` which is
triggered when the func:`.attributes.flag_modified` function is
invoked, which is common when using the :mod:`sqlalchemy.ext.mutable`
extension module.

.. seealso::

:ref:`change_3303`

.. change:: 3918
:tags: bug, ext
:tickets: 3918

Fixed a bug in the ``sqlalchemy.ext.serializer`` extension whereby
an "annotated" SQL element (as produced by the ORM for many types
of SQL expressions) could not be reliably serialized.  Also bumped
the default pickle level for the serializer to "HIGHEST_PROTOCOL".

.. change:: 3891
:tags: bug, orm
:tickets: 3891

Fixed bug in single-table inheritance where the select_from()
argument would not be taken into account when limiting rows
to a subclass.  Previously, only expressions in the
columns requested would be taken into account.

.. seealso::

:ref:`change_3891`

.. change:: 3913
:tags: bug, orm
:tickets: 3913

When assigning a collection to an attribute mapped by a relationship,
the previous collection is no longer mutated.  Previously, the old
collection would be emptied out in conjunction with the "item remove"
events that fire off; the events now fire off without affecting
the old collection.

.. seealso::

:ref:`change_3913`

.. change:: 3932
:tags: bug, oracle
:tickets: 3932

The cx_Oracle dialect now supports "sane multi rowcount", that is,
when a series of parameter sets are executed via DBAPI
``cursor.executemany()``, we can make use of ``cursor.rowcount`` to
verify the number of rows matched.  This has an impact within the
ORM when detecting concurrent modification scenarios, in that
some simple conditions can now be detected even when the ORM
is batching statements, as well as when the more strict versioning
feature is used, the ORM can still use statement batching.  The
flag is enabled for cx_Oracle assuming at least version 5.0, which
is now commonplace.

.. change:: 3907
:tags: feature, sql
:tickets: 3907

The longstanding behavior of the :meth:`.ColumnOperators.in_` and
:meth:`.ColumnOperators.notin_` operators emitting a warning when
the right-hand condition is an empty sequence has been revised;
a simple "static" expression of "1 != 1" or "1 = 1" is now rendered
by default, rather than pulling in the original left-hand
expression.  This causes the result for a NULL column comparison
against an empty set to change from NULL to true/false.  The
behavior is configurable, and the old behavior can be enabled
using the :paramref:`.create_engine.empty_in_strategy` parameter
to :func:`.create_engine`.

.. seealso::

:ref:`change_3907`

.. change:: 3276
:tags: bug, oracle
:tickets: 3276

Oracle reflection now "normalizes" the name given to a foreign key
constraint, that is, returns it as all lower case for a case
insensitive name.  This was already the behavior for indexes
and primary key constraints as well as all table and column names.
This will allow Alembic autogenerate scripts to compare and render
foreign key constraint names correctly when initially specified
as case insensitive.

.. seealso::

:ref:`change_3276`

.. change:: 2694
:tags: feature, sql
:tickets: 2694

Added a new option ``autoescape`` to the "startswith" and
"endswith" classes of comparators; this supplies an escape character
also applies it to all occurrences of the wildcard characters "%"
and "_" automatically.  Pull request courtesy Diana Clarke.

.. note::  This feature has been changed as of 1.2.0 from its initial
implementation in 1.2.0b2 such that autoescape is now passed as a
boolean value, rather than a specific character to use as the escape
character.

.. seealso::

:ref:`change_2694`

.. change:: 3934
:tags: bug, orm
:tickets: 3934

The state of the :class:`.Session` is now present when the
:meth:`.SessionEvents.after_rollback` event is emitted, that is,  the
attribute state of objects prior to their being expired.   This is now
consistent with the  behavior of the
:meth:`.SessionEvents.after_commit` event which  also emits before the
attribute state of objects is expired.

.. seealso::

:ref:`change_3934`

.. change:: 3607
:tags: bug, orm
:tickets: 3607

Fixed bug where :meth:`.Query.with_parent` would not work if the
:class:`.Query` were against an :func:`.aliased` construct rather than
a regular mapped class.  Also adds a new parameter
:paramref:`.util.with_parent.from_entity` to the standalone
:func:`.util.with_parent` function as well as
:meth:`.Query.with_parent`.


=============
1.3 Changelog
=============

.. changelog_imports::

.. include:: changelog_12.rst
:start-line: 5

.. include:: changelog_11.rst
:start-line: 5

.. changelog::

1.1.18

:released: March 6, 2018

.. change::
:tags: bug, mysql
:tickets: 4205
:versions: 1.2.5

MySQL dialects now query the server version using ``SELECT version``
explicitly to the server to ensure we are getting the correct version
information back.   Proxy servers like MaxScale interfere with the value
that is passed to the DBAPI's connection.server_version value so this
is no longer reliable.

.. change::
:tags: bug, postgresql, py3k
:tickets: 4208
:versions: 1.2.5

Fixed bug in PostgreSQL COLLATE / ARRAY adjustment first introduced
in :ticket:`4006` where new behaviors in Python 3.7 regular expressions
caused the fix to fail.

.. changelog::

1.1.17

:released: February 22, 2018

.. change::
:tags: bug, ext
:tickets: 4185

Repaired regression caused in 1.2.3 and 1.1.16 regarding association proxy
objects, revising the approach to :ticket:`4185` when calculating the
"owning class" of an association proxy to default to choosing the current
class if the proxy object is not directly associated with a mapped class,
such as a mixin.

.. changelog::

1.1.16

:released: February 16, 2018

.. change::
:tags: bug, postgresql
:versions: 1.2.3

Added "SSL SYSCALL error: Operation timed out" to the list
of messages that trigger a "disconnect" scenario for the
psycopg2 driver.  Pull request courtesy André Cruz.

.. change::
:tags: bug, orm
:tickets: 4187
:versions: 1.2.3

Fixed issue in post_update feature where an UPDATE is emitted
when the parent object has been deleted but the dependent object
is not.   This issue has existed for a long time however
since 1.2 now asserts rows matched for post_update, this
was raising an error.

.. change::
:tags: bug, mysql
:tickets: 4136
:versions: 1.2.0b4

Fixed bug where the MySQL "concat" and "match" operators failed to
propagate kwargs to the left and right expressions, causing compiler
options such as "literal_binds" to fail.

.. change::
:tags: bug, sql
:versions: 1.2.0b4

Added :func:`.nullsfirst` and :func:`.nullslast` as top level imports
in the ``sqlalchemy.`` and ``sqlalchemy.sql.`` namespace.  Pull request
courtesy Lele Gaifax.

.. change::
:tags: bug, orm
:tickets: 4185
:versions: 1.2.3

Fixed regression caused by fix for issue :ticket:`4116` affecting versions
1.2.2 as well as 1.1.15, which had the effect of mis-calculation of the
"owning class" of an :class:`.AssociationProxy` as the ``NoneType`` class
in some declarative mixin/inheritance situations as well as if the
association proxy were accessed off of an un-mapped class.  The "figure out
the owner" logic has been replaced by an in-depth routine that searches
through the complete mapper hierarchy assigned to the class or subclass to
determine the correct (we hope) match; will not assign the owner if no
match is found.  An exception is now raised if the proxy is used
against an un-mapped instance.


.. change::
:tags: bug, sql
:tickets: 4162
:versions: 1.2.1

Fixed bug in :meth:`.Insert.values` where using the "multi-values"
format in combination with :class:`.Column` objects as keys rather
than strings would fail.   Pull request courtesy Aubrey Stark-Toller.

.. change::
:tags: bug, postgresql
:versions: 1.2.3

Added "TRUNCATE" to the list of keywords accepted by the
PostgreSQL dialect as an "autocommit"-triggering keyword.
Pull request courtesy Jacob Hayes.

.. change::
:tags: bug, pool
:tickets: 4184
:versions: 1.2.3

Fixed a fairly serious connection pool bug where a connection that is
acquired after being refreshed as a result of a user-defined
:class:`.DisconnectionError` or due to the 1.2-released "pre_ping" feature
would not be correctly reset if the connection were returned to the pool by
weakref cleanup (e.g. the front-facing object is garbage collected); the
weakref would still refer to the previously invalidated DBAPI connection
which would have the reset operation erroneously called upon it instead.
This would lead to stack traces in the logs and a connection being checked
into the pool without being reset, which can cause locking issues.


.. change::
:tags: bug, orm
:tickets: 4151
:versions: 1.2.1

Fixed bug where an object that is expunged during a rollback of
a nested or subtransaction which also had its primary key mutated
would not be correctly removed from the session, causing subsequent
issues in using the session.

.. changelog::

1.1.15

:released: November 3, 2017

.. change:
:tags: bug, sqlite
:tickets: 4099
:versions: 1.2.0b3

Fixed bug where SQLite CHECK constraint reflection would fail
if the referenced table were in a remote schema, e.g. on SQLite a
remote database referred to by ATTACH.

.. change::
:tags: bug, mysql
:tickets: 4097
:versions: 1.2.0b3

Warning emitted when MariaDB 10.2.8 or earlier in the 10.2
series is detected as there are major issues with CHECK
constraints within these versions that were resolved as of
10.2.9.

Note that this changelog message was NOT released with
SQLAlchemy 1.2.0b3 and was added retroactively.

.. change::
:tags: bug, mssql
:tickets: 4095
:versions: 1.2.0b3

Added a full range of "connection closed" exception codes to the
PyODBC dialect for SQL Server, including '08S01', '01002', '08003',
'08007', '08S02', '08001', 'HYT00', 'HY010'.  Previously, only '08S01'
was covered.

.. change::
:tags: bug, sql
:tickets: 4126
:versions: 1.2.0

Fixed bug where ``__repr__`` of :class:`.ColumnDefault` would fail
if the argument were a tuple.  Pull request courtesy Nicolas Caniart.

.. change::
:tags: bug, orm, declarative
:tickets: 4124
:versions: 1.2.0

Fixed bug where a descriptor that is elsewhere a mapped column
or relationship within a hierarchy based on :class:`.AbstractConcreteBase`
would be referred towards during a refresh operation, causing an error
as the attribute is not mapped as a mapper property.
A similar issue can arise for other attributes like the "type" column
added by :class:`.AbstractConcreteBase` if the class fails to include
"concrete=True" in its mapper, however the check here should also
prevent that scenario from causing a problem.

.. change:: 4006
:tags: bug, postgresql
:tickets: 4006
:versions: 1.2.0b3

Made further fixes to the :class:`.ARRAY` class in conjunction with
COLLATE, as the fix made in :ticket:`4006` failed to accommodate
for a multidimensional array.

.. change::
:tags: bug, orm, ext
:tickets: 4116
:versions: 1.2.0

Fixed bug where the association proxy would inadvertently link itself
to an :class:`.AliasedClass` object if it were called first with
the :class:`.AliasedClass` as a parent, causing errors upon subsequent
usage.

.. change::
:tags: bug, mysql
:tickets: 4120
:versions: 1.2.0

MySQL 5.7.20 now warns for use of the tx_isolation variable; a version
check is now performed and uses transaction_isolation instead
to prevent this warning.

.. change::
:tags: bug, postgresql
:tickets: 4107
:versions: 1.2.0b3

Fixed bug in :obj:`.array_agg` function where passing an argument
that is already of type :class:`.ARRAY`, such as a PostgreSQL
:obj:`.postgresql.array` construct, would produce a ``ValueError``, due
to the function attempting to nest the arrays.

.. change::
:tags: bug, orm
:tickets: 4078
:versions: 1.2.0b3

Fixed bug where ORM relationship would warn against conflicting sync
targets (e.g. two relationships would both write to the same column) for
sibling classes in an inheritance hierarchy, where the two relationships
would never actually conflict during writes.

.. change::
:tags: bug, postgresql
:tickets: 4074
:versions: 1.2.0b3

Fixed bug in PostgreSQL :meth:`.postgresql.dml.Insert.on_conflict_do_update`
which would prevent the insert statement from being used as a CTE,
e.g. via :meth:`.Insert.cte`, within another statement.

.. change::
:tags: bug, orm
:tickets: 4103
:versions: 1.2.0b3

Fixed bug where correlated select used against single-table inheritance
entity would fail to render correctly in the outer query, due to adjustment
for single inheritance discriminator criteria inappropriately re-applying
the criteria to the outer query.

.. change:
:tags: bug, mysql
:tickets: 4096
:versions: 1.2.0b3

Fixed issue where CURRENT_TIMESTAMP would not reflect correctly
in the MariaDB 10.2 series due to a syntax change, where the function
is now represented as ``current_timestamp()``.

.. change:
:tags: bug, mysql
:tickets: 4098
:versions: 1.2.0b3

MariaDB 10.2 now supports CHECK constraints (warning: use version 10.2.9
or greater due to upstream issues noted in :ticket:`4097`).  Reflection
now takes these CHECK constraints into account when they are present in
the ``SHOW CREATE TABLE`` output.

.. change::
:tags: bug, sql
:tickets: 4093
:versions: 1.2.0b3

Fixed bug where the recently added :meth:`.ColumnOperators.any_`
and :meth:`.ColumnOperators.all_` methods didn't work when called
as methods, as opposed to using the standalone functions
:func:`~.expression.any_` and :func:`~.expression.all_`.  Also
added documentation examples for these relatively unintuitive
SQL operators.

.. changelog::

1.1.14

:released: September 5, 2017

.. change::
:tags: bug, orm
:tickets: 4069
:versions: 1.2.0b3

Fixed bug in :meth:`.Session.merge` following along similar lines as that
of :ticket:`4030`, where an internal check for a target object in
the identity map could lead to an error if it were to be garbage collected
immediately before the merge routine actually retrieves the object.

.. change::
:tags: bug, orm
:tickets: 4048
:versions: 1.2.0b3

Fixed bug where an :func:`.undefer_group` option would not be recognized
if it extended from a relationship that was loading using joined eager
loading.  Additionally, as the bug led to excess work being performed,
Python function call counts are also improved by 20% within the initial
calculation of result set columns, complementing the joined eager load
improvements of :ticket:`3915`.

.. change::
:tags: bug, orm
:tickets: 4068

Fixed race condition in ORM identity map which would cause objects
to be inappropriately removed during a load operation, causing
duplicate object identities to occur, particularly under joined eager
loading which involves deduplication of objects.  The issue is specific
to garbage collection of weak references and is observed only under the
PyPy interpreter.

.. change::
:tags: bug, orm
:tickets: 4056
:versions: 1.2.0b3

Fixed bug in :meth:`.Session.merge` where objects in a collection that had
the primary key attribute set to ``None`` for a key that is  typically
autoincrementing would be considered to be a database-persisted key for
part of the internal deduplication process, causing only one object to
actually be inserted in the database.

.. change::
:tags: bug, sql
:tickets: 4053

Altered the range specification for window functions to allow
for two of the same PRECEDING or FOLLOWING keywords in a range
by allowing for the left side of the range to be positive
and for the right to be negative, e.g. (1, 3) is
"1 FOLLOWING AND 3 FOLLOWING".

.. change::
:tags: bug, orm
:tickets: 4067
:versions: 1.2.0b3

An :class:`.InvalidRequestError` is raised when a :func:`.synonym`
is used against an attribute that is not against a :class:`.MapperProperty`,
such as an association proxy.  Previously, a recursion overflow would
occur trying to locate non-existent attributes.

.. changelog::

1.1.13

:released: August 3, 2017

.. changelog::

1.1.12

:released: July 24, 2017

.. change:: cache_order_sequence
:tags: feature, oracle, postgresql
:versions: 1.2.0b1

Added new keywords :paramref:`.Sequence.cache` and
:paramref:`.Sequence.order` to :class:`.Sequence`, to allow rendering
of the CACHE parameter understood by Oracle and PostgreSQL, and the
ORDER parameter understood by Oracle.  Pull request
courtesy David Moore.


.. change:: 4033
:tags: bug, orm
:tickets: 4033
:versions: 1.2.0b2

Fixed regression from 1.1.11 where adding additional non-entity
columns to a query that includes an entity with subqueryload
relationships would fail, due to an inspection added in 1.1.11 as a
result of :ticket:`4011`.


.. change:: 4031
:tags: bug, orm
:versions: 1.2.0b2
:tickets: 4031

Fixed bug involving JSON NULL evaluation logic added in 1.1 as part
of :ticket:`3514` where the logic would not accommodate ORM
mapped attributes named differently from the :class:`.Column`
that was mapped.

.. change:: 4030
:tags: bug, orm
:versions: 1.2.0b2
:tickets: 4030

Added ``KeyError`` checks to all methods within
:class:`.WeakInstanceDict` where a check for ``key in dict`` is
followed by indexed access to that key, to guard against a race against
garbage collection that under load can remove the key from the dict
after the code assumes its present, leading to very infrequent
``KeyError`` raises.

.. changelog::

1.1.11

:released: Monday, June 19, 2017

.. change:: 4012
:tags: bug, sql
:tickets: 4012
:versions: 1.2.0b1

Fixed AttributeError which would occur in :class:`.WithinGroup`
construct during an iteration of the structure.

.. change:: 4011
:tags: bug, orm
:tickets: 4011
:versions: 1.2.0b1

Fixed issue with subquery eagerloading which continues on from
the series of issues fixed in :ticket:`2699`, :ticket:`3106`,
:ticket:`3893` involving that the "subquery" contains the correct
FROM clause when beginning from a joined inheritance subclass
and then subquery eager loading onto a relationship from
the base class, while the query also includes criteria against
the subclass. The fix in the previous tickets did not accommodate
for additional subqueryload operations loading more deeply from
the first level, so the fix has been further generalized.

.. change:: 4005
:tags: bug, postgresql
:tickets: 4005
:versions: 1.2.0b1

Continuing with the fix that correctly handles PostgreSQL
version string "10devel" released in 1.1.8, an additional regexp
bump to handle version strings of the form "10beta1".   While
PostgreSQL now offers better ways to get this information, we
are sticking w/ the regexp at least through 1.1.x for the least
amount of risk to compatibility w/ older or alternate PostgreSQL
databases.

.. change:: 4006
:tags: bug, postgresql
:tickets: 4006
:versions: 1.2.0b1

Fixed bug where using :class:`.ARRAY` with a string type that
features a collation would fail to produce the correct syntax
within CREATE TABLE.

.. change:: 4007
:tags: bug, mysql
:tickets: 4007
:versions: 1.2.0b1

MySQL 5.7 has introduced permission limiting for the "SHOW VARIABLES"
command; the MySQL dialect will now handle when SHOW returns no
row, in particular for the initial fetch of SQL_MODE, and will
emit a warning that user permissions should be modified to allow the
row to be present.

.. change:: 3994
:tags: bug, mssql
:tickets: 3994
:versions: 1.2.0b1

Fixed bug where SQL Server transaction isolation must be fetched
from a different view when using Azure data warehouse, the query
is now attempted against both views and then a NotImplemented
is raised unconditionally if failure continues to provide the
best resiliency against future arbitrary API changes in new
SQL Server versions.

.. change:: 3997
:tags: bug, oracle
:tickets: 3997
:versions: 1.2.0b1

Support for two-phase transactions has been removed entirely for
cx_Oracle when version 6.0b1 or later of the DBAPI is in use.  The two-
phase feature historically has never been usable under cx_Oracle 5.x in
any case, and cx_Oracle 6.x has removed the connection-level "twophase"
flag upon which this feature relied.

.. change:: 3973
:tags: bug, mssql
:tickets: 3973
:versions: 1.2.0b1

Added a placeholder type :class:`.mssql.XML` to the SQL Server
dialect, so that a reflected table which includes this type can
be re-rendered as a CREATE TABLE.  The type has no special round-trip
behavior nor does it currently support additional qualifying
arguments.

.. changelog::

1.1.10

:released: Friday, May 19, 2017

.. change:: 3986
:tags: bug, orm
:versions: 1.2.0b1
:tickets: 3986

Fixed bug where a cascade such as "delete-orphan" (but others as well)
would fail to locate an object linked to a relationship that itself
is local to a subclass in an inheritance relationship, thus causing
the operation to not take place.

.. change:: 3975
:tags: bug, oracle
:versions: 1.2.0b1
:tickets: 3975

Fixed bug in cx_Oracle dialect where version string parsing would
fail for cx_Oracle version 6.0b1 due to the "b" character.  Version
string parsing is now via a regexp rather than a simple split.

.. change:: 3949
:tags: bug, schema
:versions: 1.2.0b1
:tickets: 3949

An :class:`.ArgumentError` is now raised if a
:class:`.ForeignKeyConstraint` object is created with a mismatched
number of "local" and "remote" columns, which otherwise causes the
internal state of the constraint to be incorrect.   Note that this
also impacts the condition where a dialect's reflection process
produces a mismatched set of columns for a foreign key constraint.

.. change:: 3980
:tags: bug, ext
:versions: 1.2.0b1
:tickets: 3980

Protected against testing "None" as a class in the case where
declarative classes are being garbage collected and new
automap prepare() operations are taking place concurrently, very
infrequently hitting a weakref that has not been fully acted upon
after gc.

.. change::
:tags: bug, postgresql
:versions: 1.2.0b1

Added "autocommit" support for GRANT, REVOKE keywords.  Pull request
courtesy Jacob Hayes.

.. change:: 3966
:tags: bug, mysql
:versions: 1.2.0b1
:tickets: 3966

Removed an ancient and unnecessary intercept of the UTC_TIMESTAMP
MySQL function, which was getting in the way of using it with a
parameter.

.. change:: 3961
:tags: bug, mysql
:versions: 1.2.0b1
:tickets: 3961

Fixed bug in MySQL dialect regarding rendering of table options in
conjunction with PARTITION options when rendering CREATE TABLE.
The PARTITION related options need to follow the table options,
whereas previously this ordering was not enforced.


.. changelog::

1.1.9

:released: April 4, 2017

.. change:: 3956
:tags: bug, ext
:tickets: 3956

Fixed regression released in 1.1.8 due to :ticket:`3950` where the
deeper search for information about column types in the case of a
"schema type" or a :class:`.TypeDecorator` would produce an attribute
error if the mapping also contained a :obj:`.column_property`.

.. change:: 3952
:tags: bug, sql
:versions: 1.2.0b1
:tickets: 3952

Fixed regression released in 1.1.5 due to :ticket:`3859` where
adjustments to the "right-hand-side" evaluation of an expression
based on :class:`.Variant` to honor the underlying type's
"right-hand-side" rules caused the :class:`.Variant` type
to be inappropriately lost, in those cases when we *do* want the
left-hand side type to be transferred directly to the right hand side
so that bind-level rules can be applied to the expression's argument.

.. change:: 3955
:tags: bug, sql, postgresql
:versions: 1.2.0b1
:tickets: 3955

Changed the mechanics of :class:`.ResultProxy` to unconditionally
delay the "autoclose" step until the :class:`.Connection` is done
with the object; in the case where PostgreSQL ON CONFLICT with
RETURNING returns no rows, autoclose was occurring in this previously
non-existent use case, causing the usual autocommit behavior that
occurs unconditionally upon INSERT/UPDATE/DELETE to fail.

.. changelog::

1.1.8

:released: March 31, 2017

.. change:: 3950
:tags: bug, ext
:versions: 1.2.0b1
:tickets: 3950

Fixed bug in :mod:`sqlalchemy.ext.mutable` where the
:meth:`.Mutable.as_mutable` method would not track a type that had
been copied using :meth:`.TypeEngine.copy`.  This became more of
a regression in 1.1 compared to 1.0 because the :class:`.TypeDecorator`
class is now a subclass of :class:`.SchemaEventTarget`, which among
other things indicates to the parent :class:`.Column` that the type
should be copied when the :class:`.Column` is.  These copies are
common when using declarative with mixins or abstract classes.

.. change::
:tags: bug, ext
:versions: 1.2.0b1

Added support for bound parameters, e.g. those normally set up
via :meth:`.Query.params`, to the :meth:`.baked.Result.count`
method.  Previously, support for parameters were omitted. Pull request
courtesy Pat Deegan.

.. change::
:tags: bug, postgresql
:versions: 1.2.0b1

Added support for parsing the PostgreSQL version string for
a development version like "PostgreSQL 10devel".  Pull request
courtesy Sean McCully.

.. changelog::

1.1.7

:released: March 27, 2017

.. change::
:tags: feature, orm
:tickets: 3933
:versions: 1.2.0b1

An :func:`.aliased()` construct can now be passed to the
:meth:`.Query.select_entity_from` method.   Entities will be pulled
from the selectable represented by the :func:`.aliased` construct.
This allows special options for :func:`.aliased` such as
:paramref:`.aliased.adapt_on_names` to be used in conjunction with
:meth:`.Query.select_entity_from`.

.. change::
:tags: bug, engine
:tickets: 3946
:versions: 1.2.0b1

Added an exception handler that will warn for the "cause" exception on
Py2K when the "autorollback" feature of :class:`.Connection` itself
raises an exception. In Py3K, the two exceptions are naturally reported
by the interpreter as one occurring during the handling of the other.
This is continuing with the series of changes for rollback failure
handling that were last visited as part of :ticket:`2696` in 1.0.12.

.. change::
:tags: bug, orm
:tickets: 3947
:versions: 1.2.0b1

Fixed a race condition which could occur under threaded environments
as a result of the caching added via :ticket:`3915`.   An internal
collection of ``Column`` objects could be regenerated on an alias
object inappropriately, confusing a joined eager loader when it
attempts to render SQL and collect results and resulting in an
attribute error.   The collection is now generated up front before
the alias object is cached and shared among threads.

.. change::
:tags: bug, sql, postgresql
:tickets: 2892

Added support for the :class:`.Variant` and the :class:`.SchemaType`
objects to be compatible with each other.  That is, a variant
can be created against a type like :class:`.Enum`, and the instructions
to create constraints and/or database-specific type objects will
propagate correctly as per the variant's dialect mapping.

.. change::
:tags: bug, sql
:tickets: 3931

Fixed bug in compiler where the string identifier of a savepoint would
be cached in the identifier quoting dictionary; as these identifiers
are arbitrary, a small memory leak could occur if a single
:class:`.Connection` had an unbounded number of savepoints used,
as well as if the savepoint clause constructs were used directly
with an unbounded umber of savepoint names.   The memory leak does
**not** impact the vast majority of cases as normally the
:class:`.Connection`, which renders savepoint names with a simple
counter starting at "1", is used on a per-transaction or
per-fixed-number-of-transactions basis before being discarded.

.. change::
:tags: bug, sql
:tickets: 3924

Fixed bug in new "schema translate" feature where the translated schema
name would be invoked in terms of an alias name when rendered along
with a column expression; occurred only when the source translate
name was "None".   The "schema translate" feature now only takes
effect for :class:`.SchemaItem` and :class:`.SchemaType` subclasses,
that is, objects that correspond to a DDL-creatable structure in
a database.

.. changelog::

1.1.6

:released: February 28, 2017

.. change::
:tags: bug, mysql

Added new MySQL 8.0 reserved words to the MySQL dialect for proper
quoting.  Pull request courtesy Hanno Schlichting.

.. change:: 3915
:tags: bug, orm
:tickets: 3915

Addressed some long unattended performance concerns within the joined
eager loader query construction system that have accumulated since
earlier versions as a result of increased abstraction. The use of ad-
hoc :class:`.AliasedClass` objects per query, which produces lots of
column lookup overhead each time, has been replaced with a cached
approach that makes use of a small pool of :class:`.AliasedClass`
objects that are reused between invocations of joined eager loading.
Some mechanics involving eager join path construction have also been
optimized.   Callcounts for an end-to-end query construction + single
row fetch test with a worst-case joined loader scenario have been
reduced by about 60% vs. 1.1.5 and 42% vs. that of 0.8.6.

.. change:: 3804
:tags: bug, postgresql
:tickets: 3804

Added regular expressions for the "IMPORT FOREIGN SCHEMA",
"REFRESH MATERIALIZED VIEW" PostgreSQL statements so that they
autocommit when invoked via a connection or engine without
an explicit transaction.  Pull requests courtesy Frazer McLean
and Paweł Stiasny.

.. change:: 3909
:tags: bug, orm
:tickets: 3909

Fixed a major inefficiency in the "eager_defaults" feature whereby
an unnecessary SELECT would be emitted for column values where the
ORM had explicitly inserted NULL, corresponding to attributes that
were unset on the object but did not have any server default
specified, as well as expired attributes on update that nevertheless
had no server onupdate set up.   As these columns are not part of the
RETURNING that eager_defaults tries to use, they should not be
post-SELECTed either.

.. change:: 3908
:tags: bug, orm
:tickets: 3908

Fixed two closely related bugs involving the mapper eager_defaults
flag in conjunction with single-table inheritance; one where the
eager defaults logic would inadvertently try to access a column
that's part of the mapper's "exclude_properties" list (used by
Declarative with single table inheritance) during the eager defaults
fetch, and the other where the full load of the row in order to
fetch the defaults would fail to use the correct inheriting mapper.


.. change:: 3905
:tags: bug, sql
:tickets: 3905

Fixed bug whereby the :meth:`.DDLEvents.column_reflect` event would not
allow a non-textual expression to be passed as the value of the
"default" for the new column, such as a :class:`.FetchedValue`
object to indicate a generic triggered default or a
:func:`.sql.expression.text` construct.  Clarified the documentation
in this regard as well.

.. change:: 3901
:tags: bug, ext
:tickets: 3901

Fixed bug in new :mod:`sqlalchemy.ext.indexable` extension
where setting of a property that itself refers to another property
would fail.

.. change:: 3900
:tags: bug, postgresql
:tickets: 3900

Fixed bug in PostgreSQL :class:`.ExcludeConstraint` where the
"whereclause" and "using" parameters would not be copied during an
operation like :meth:`.Table.tometadata`.

.. change:: 3898
:tags: bug, mssql
:tickets: 3898

Added a version check to the "get_isolation_level" feature, which is
invoked upon first connect, so that it skips for SQL Server version
2000, as the necessary system view is not available prior to SQL Server
2005.

.. change:: 3897
:tags: feature, ext
:tickets: 3896

Added :meth:`.baked.Result.scalar` and :meth:`.baked.Result.count`
to the "baked" query system.

.. change:: 3895
:tags: bug, orm, declarative
:tickets: 3895

Fixed bug where the "automatic exclude" feature of declarative that
ensures a column local to a single table inheritance subclass does
not appear as an attribute on other derivations of the base would
not take effect for multiple levels of subclassing from the base.

.. change:: 3893
:tags: bug, orm
:tickets: 3893

Fixed bug first introduced in 0.9.7 as a result of :ticket:`3106`
which would cause an incorrect query in some forms of multi-level
subqueryload against aliased entities, with an unnecessary extra
FROM entity in the innermost subquery.

.. changelog::

1.1.5

:released: January 17, 2017

.. change:: mysql_index_prefix
:tags: feature, mysql

Added a new parameter ``mysql_prefix`` supported by the :class:`.Index`
construct, allows specification of MySQL-specific prefixes such as
"FULLTEXT". Pull request courtesy Joseph Schorr.

.. change:: 3854
:tags: bug, orm
:tickets: 3854

Fixed bug in subquery loading where an object encountered as an
"existing" row, e.g. already loaded from a different path in the
same query, would not invoke subquery loaders for unloaded attributes
that specified this loading.  This issue is in the same area
as that of :ticket:`3431`, :ticket:`3811` which involved
similar issues with joined loading.

.. change:: 3888
:tags: bug, postgresql
:tickets: 3888

Fixed bug in new "ON CONFLICT DO UPDATE" feature where the "set"
values for the UPDATE clause would not be subject to type-level
processing, as normally takes effect to handle both user-defined
type level conversions as well as dialect-required conversions, such
as those required for JSON datatypes.   Additionally, clarified that
the keys in the ``set_`` dictionary should match the "key" of the
column, if distinct from the column name.  A warning is emitted
for remaining column names that don't match column keys; for
compatibility reasons, these are emitted as they were previously.

.. change:: 3872
:tags: bug, examples
:tickets: 3872

Fixed two issues with the versioned_history example, one is that
the history table now gets autoincrement=False to avoid 1.1's new
errors regarding composite primary keys with autoincrement; the other
is that the sqlite_autoincrement flag is now used to ensure on SQLite,
unique identifiers are used for the lifespan of a table even if
some rows are deleted.  Pull request courtesy Carlos García Montoro.

.. change:: 3882
:tags: bug, sql
:tikets: 3882

Fixed bug originally introduced in 0.9 via :ticket:`1068` where
order_by(<some Label()>) would order by the label name based on name
alone, that is, even if the labeled expression were not at all the same
expression otherwise present, implicitly or explicitly, in the
selectable.  The logic that orders by label now ensures that the
labeled expression is related to the one that resolves to that name
before ordering by the label name; additionally, the name has to
resolve to an actual label explicit in the expression elsewhere, not
just a column name.  This logic is carefully kept separate from the
order by(textual name) feature that has a slightly different purpose.

.. change:: try_finally_for_noautoflush
:tags: bug, orm

The :attr:`.Session.no_autoflush` context manager now ensures that
the autoflush flag is reset within a "finally" block, so that if
an exception is raised within the block, the state still resets
appropriately.  Pull request courtesy Emin Arakelian.

.. change:: 3878
:tags: bug, sql
:tickets: 3878

Fixed 1.1 regression where "import *" would not work for
sqlalchemy.sql.expression, due to mis-spelled ``any_`` and ``all_``
functions.

.. change:: 3880
:tags: bg, sql
:tickets: 3880

Fixed bug where literal_binds compiler flag was not honored by the
:class:`.Insert` construct for the "multiple values" feature; the
subsequent values are now rendered as literals.

.. change:: 3877
:tags: bug, oracle, postgresql
:tickets: 3877

Fixed bug where an INSERT from SELECT where the source table contains
an autoincrementing Sequence would fail to compile correctly.

.. change:: 3876
:tags: bug, mssql
:tickets: 3876

Fixed bug where SQL Server dialects would attempt to select the
last row identity for an INSERT from SELECT, failing in the case when
the SELECT has no rows.  For such a statement,
the inline flag is set to True indicating no last primary key
should be fetched.

.. change:: 3875
:tags: bug, oracle
:tickets: 3875

Fixed bug where the "COMPRESSION" keyword was used in the ALL_TABLES
query on Oracle 9.2; even though Oracle docs state table compression
was introduced in 9i, the actual column is not present until
10.1.

.. change:: 3874
:tags: bug, orm
:tickets: 3874

Fixed bug where the single-table inheritance query criteria would not
be inserted into the query in the case that the :class:`.Bundle`
construct were used as the selection criteria.

.. change:: repr_for_url_reflect
:tags: bug, sql

The engine URL embedded in the exception for "could not reflect"
in :meth:`.MetaData.reflect` now conceals the password; also
the ``__repr__`` for :class:`.TLEngine` now acts like that of
:class:`.Engine`, concealing the URL password.  Pull request courtesy
Valery Yundin.

.. change:: 3867
:tags: bug, mysql
:tickets: 3867

The MySQL dialect now will not warn when a reflected column has a
"COMMENT" keyword on it, but note however the comment is not yet
reflected; this is on the roadmap for a future release.  Pull request
courtesy Lele Long.

.. change:: pg_timestamp_zero_prec
:tags: bug, postgresql

The :class:`.postgresql.TIME` and :class:`.postgresql.TIMESTAMP`
datatypes now support a setting of zero for "precision"; previously
a zero would be ignored.  Pull request courtesy Ionuț Ciocîrlan.

.. change:: 3861
:tags: bug, engine
:tickets: 3861

The "extend_existing" option of :class:`.Table` reflection would
cause indexes and constraints to be doubled up in the case that the parameter
were used with :meth:`.MetaData.reflect` (as the automap extension does)
due to tables being reflected both within the foreign key path as well
as directly.  A new de-duplicating set is passed through within the
:meth:`.MetaData.reflect` sequence to prevent double reflection in this
way.

.. change:: 3859
:tags: bug, sql
:tickets: 3859

Fixed issue in :class:`.Variant` where the "right hand coercion" logic,
inherited from :class:`.TypeDecorator`, would
coerce the right-hand side into the :class:`.Variant` itself, rather than
what the default type for the :class:`.Variant` would do.   In the
case of :class:`.Variant`, we want the type to act mostly like the base
type so the default logic of :class:`.TypeDecorator` is now overridden
to fall back to the underlying wrapped type's logic.   Is mostly relevant
for JSON at the moment.

.. change:: 3856
:tags: bug, orm
:tickets: 3856

Fixed bug related to :ticket:`3177`, where a UNION or other set operation
emitted by a :class:`.Query` would apply "single-inheritance" criteria
to the outside of the union (also referencing the wrong selectable),
even though this criteria is now expected to
be already present on the inside subqueries.  The single-inheritance
criteria is now omitted once union() or another set operation is
called against :class:`.Query` in the same way as :meth:`.Query.from_self`.

.. change:: 3548
:tags: bug, firebird
:tickets: 3548

Ported the fix for Oracle quoted-lowercase names to Firebird, so that
a table name that is quoted as lower case can be reflected properly
including when the table name comes from the get_table_names()
inspection function.

.. changelog::

1.1.4

:released: November 15, 2016

.. change::  3842
:tags: bug, sql
:tickets: 3842

Fixed bug where newly added warning for primary key on insert w/o
autoincrement setting (see :ref:`change_3216`) would fail to emit
correctly when invoked upon a lower-case :func:`.table` construct.

.. change::  3852
:tags: bug, orm
:tickets: 3852

Fixed regression in collections due to :ticket:`3457` whereby
deserialize during pickle or deepcopy would fail to establish all
attributes of an ORM collection, causing further mutation operations to
fail.

.. change::  default_schema
:tags: bug, engine

Removed long-broken "default_schema_name()" method from
:class:`.Connection`.  This method was left over from a very old
version and was non-working (e.g. would raise).  Pull request
courtesy Benjamin Dopplinger.

.. change:: pragma
:tags: bug, sqlite

Added quotes to the PRAGMA directives in the pysqlcipher dialect
to support additional cipher arguments appropriately.  Pull request
courtesy Kevin Jurczyk.

.. change:: 3846
:tags: bug, postgresql
:tickets: 3846, 3807

Fixed regression caused by the fix in :ticket:`3807` (version 1.1.0)
where we ensured that the tablename was qualified in the WHERE clause
of the DO UPDATE portion of PostgreSQL's ON CONFLICT, however you
*cannot* put the table name in the  WHERE clause in the actual ON
CONFLICT itself.   This was an incorrect assumption, so that portion
of the change in :ticket:`3807` is rolled back.

.. change:: 3845
:tags: bug, orm
:tickets: 3845

Fixed long-standing bug where the "noload" relationship loading
strategy would cause backrefs and/or back_populates options to be
ignored.

.. change:: sscursor_mysql
:tags: feature, mysql

Added support for server side cursors to the mysqlclient and
pymysql dialects.   This feature is available via the
:paramref:`.Connection.execution_options.stream_results` flag as well
as the ``server_side_cursors=True`` dialect argument in the
same way that it has been for psycopg2 on PostgreSQL.  Pull request
courtesy Roman Podoliaka.

.. change::
:tags: bug, mysql
:tickets: 3841

MySQL's native ENUM type supports any non-valid value being sent, and
in response will return a blank string.  A hardcoded rule to check for
"is returning the blank string" has been added to the  MySQL
implementation for ENUM so that this blank string is returned to the
application rather than being rejected as a non-valid value.  Note that
if your MySQL enum is linking values to objects, you still get the
blank string back.

.. change::
:tags: bug, sqlite, py3k

Added an optional import for the pysqlcipher3 DBAPI when using the
pysqlcipher dialect.  This package will attempt to be imported
if the Python-2 only pysqlcipher DBAPI is non-present.
Pull request courtesy Kevin Jurczyk.

.. changelog::

1.1.3

:released: October 27, 2016

.. change::
:tags: bug, orm
:tickets: 3839

Fixed regression caused by :ticket:`2677` whereby calling
:meth:`.Session.delete` on an object that was already flushed as
deleted in that session would fail to set up the object in the
identity map (or reject the object), causing flush errors as the
object were in a state not accommodated by the unit of work.
The pre-1.1 behavior in this case has been restored, which is that
the object is put back into the identity map so that the DELETE
statement will be attempted again, which emits a warning that the number
of expected rows was not matched (unless the row were restored outside
of the session).

.. change::
:tags: bug, postgresql
:tickets: 3835

PostgreSQL table reflection will ensure that the
:paramref:`.Column.autoincrement` flag is set to False when reflecting
a primary key column that is not of an :class:`.Integer` datatype,
even if the default is related to an integer-generating sequence.
This can happen if a column is created as SERIAL and the datatype
is changed.  The autoincrement flag can only be True if the datatype
is of integer affinity in the 1.1 series.

.. change::
:tags: bug, orm
:tickets: 3836

Fixed regression where some :class:`.Query` methods like
:meth:`.Query.update` and others would fail if the :class:`.Query`
were against a series of mapped columns, rather than the mapped
entity as a whole.

.. change::
:tags: bug, sql
:tickets: 3833

Fixed bug involving new value translation and validation feature
in :class:`.Enum` whereby using the enum object in a string
concatenation would maintain the :class:`.Enum` type as the type
of the expression overall, producing missing lookups.  A string
concatenation against an :class:`.Enum`-typed column now uses
:class:`.String` as the datatype of the expression itself.

.. change::
:tags: bug, sql
:tickets: 3832

Fixed regression which occurred as a side effect of :ticket:`2919`,
which in the less typical case of a user-defined
:class:`.TypeDecorator` that was also itself an instance of
:class:`.SchemaType` (rather than the implementation being such)
would cause the column attachment events to be skipped for the
type itself.


.. changelog::

1.1.2

:released: October 17, 2016

.. change::
:tags: bug, sql
:tickets: 3823

Fixed a regression caused by a newly added function that performs the
"wrap callable" function of sql :class:`.DefaultGenerator` objects,
an attribute error raised for ``__module__`` when the default callable
was a ``functools.partial`` or other object that doesn't have a
``__module__`` attribute.

.. change::
:tags: bug, orm
:tickets: 3824

Fixed bug involving the rule to disable a joined collection eager
loader on the other side of a many-to-one lazy loader, first added
in :ticket:`1495`, where the rule would fail if the parent object
had some other lazyloader-bound query options associated with it.

.. change::
:tags: bug, orm
:tickets: 3822

Fixed self-referential entity, deferred column loading issue in a
similar style as that of :ticket:`3431`, :ticket:`3811` where an entity
is present in multiple positions within the row due to self-referential
eager loading; when the deferred loader only applies to one of the
paths, the "present" column loader will now override the deferred non-
load for that entity regardless of row ordering.

.. change::
:tags: bug, sql, postgresql
:tickets: 3827

Fixed regression in :class:`.Enum` type where event handlers were not
transferred in the case of the type object being copied, due to a
conflicting copy() method added as part of :ticket:`3250`.  This copy
occurs normally in situations when the column is copied, such as
in tometadata() or when using declarative mixins with columns.  The
event handler not being present would impact the constraint being
created for a non-native enumerated type, but more critically the
ENUM object on the PostgreSQL backend.


.. change::
:tags: bug, postgresql, sql
:tickets: 3828

Changed the naming convention used when generating bound parameters
for a multi-VALUES insert statement, so that the numbered parameter
names don't conflict with the anonymized parameters of a WHERE clause,
as is now common in a PostgreSQL ON CONFLICT construct.

.. changelog::

1.1.1

:released: October 7, 2016

.. change::
:tags: bug, mssql
:tickets: 3820

The "SELECT SERVERPROPERTY"
query added in :ticket:`3810` and :ticket:`3814` is failing on unknown
combinations of Pyodbc and SQL Server.  While failure of this function
was anticipated, the exception catch was not broad enough so it now
catches all forms of pyodbc.Error.

.. change::
:tags: bug, core
:tickets: 3216

Changed the CompileError raised when various primary key missing
situations are detected to a warning.  The statement is again
passed to the database where it will fail and the DBAPI error (usually
IntegrityError) raises as usual.

.. seealso::

:ref:`change_3216`

.. changelog::

1.1.0

:released: October 5, 2016

.. change::
:tags: bug, sql
:tickets: 3805

Execution options can now be propagated from within a
statement at compile time to the outermost statement, so that
if an embedded element wants to set "autocommit" to be True for example,
it can propagate this to the enclosing statement.  Currently, this
feature is enabled for a DML-oriented CTE embedded inside of a SELECT
statement, e.g. INSERT/UPDATE/DELETE inside of SELECT.

.. change::
:tags: bug, orm
:tickets: 3802

ORM attributes can now be assigned any object that is has a
``__clause_element__()`` attribute, which will result in inline
SQL the way any :class:`.ClauseElement` class does.  This covers other
mapped attributes not otherwise transformed by further expression
constructs.

.. change::
:tags: feature, orm
:tickets: 3812

Enhanced the new "raise" lazy loader strategy to also include a
"raise_on_sql" variant, available both via :paramref:`.orm.relationship.lazy`
as well as :func:`.orm.raiseload`.   This variant only raises if the
lazy load would actually emit SQL, vs. raising if the lazy loader
mechanism is invoked at all.

.. change::
:tags: bug, postgresql
:tickets: 3813

An adjustment to ON CONFLICT such that the "inserted_primary_key"
logic is able to accommodate the case where there's no INSERT or
UPDATE and there's no net change.  The value comes out as None
in this case, rather than failing on an exception.

.. change::
:tags: bug, orm
:tickets: 3811

Made an adjustment to the bug fix first introduced in [ticket:3431]
that involves an object appearing in multiple contexts in a single
result set, such that an eager loader that would set the related
object value to be None will still fire off, thus satisfying the
load of that attribute.  Previously, the adjustment only honored
a non-None value arriving for an eagerly loaded attribute in a
secondary row.

.. change::
:tags: bug, orm
:tickets: 3808

Fixed bug in new :meth:`.SessionEvents.persistent_to_deleted` event
where the target object could be garbage collected before the event
is fired off.

.. change::
:tags: bug, sql
:tickets: 3809

A string sent as a column default via the
:paramref:`.Column.server_default` parameter is now escaped for quotes.

.. seealso::

:ref:`change_3809`

.. change::
:tags: bug, postgresql
:tickets: 3807

Fixed issue in new PG "on conflict" construct where columns including
those of the "excluded" namespace would not be table-qualified
in the WHERE clauses in the statement.

.. change::
:tags: bug, sql, postgresql
:tickets: 3806

Added compiler-level flags used by PostgreSQL to place additional
parenthesis than would normally be generated by precedence rules
around operations involving JSON, HSTORE indexing operators as well as
within their operands since it has been observed that PostgreSQL's
precedence rules for at least the HSTORE indexing operator is not
consistent between 9.4 and 9.5.

.. change::
:tags: bug, sql, mysql
:tickets: 3803

The ``BaseException`` exception class is now intercepted by the
exception-handling routines of :class:`.Connection`, and includes
handling by the :meth:`~.ConnectionEvents.handle_error`
event.  The :class:`.Connection` is now **invalidated** by default in
the case of a system level exception that is not a subclass of
``Exception``, including ``KeyboardInterrupt`` and the greenlet
``GreenletExit`` class, to prevent further operations from occurring
upon a database connection that is in an unknown and possibly
corrupted state.  The MySQL drivers are most targeted by this change
however the change is across all DBAPIs.

.. seealso::

:ref:`change_3803`

.. change::
:tags: bug, sql
:tickets: 3799

The "eq" and "ne" operators are no longer part of the list of
"associative" operators, while they remain considered to be
"commutative".  This allows an expression like ``(x == y) == z``
to be maintained at the SQL level with parenthesis.  Pull request
courtesy John Passaro.

.. change::
:tags: bug, orm
:tickets: 3767

The primaryjoin of a :func:`.relationship` construct can now include
a :func:`.bindparam` object that includes a callable function to
generate values.  Previously, the lazy loader strategy would
be incompatible with this use, and additionally would fail to correctly
detect if the "use_get" criteria should be used if the primary key
were involved with the bound parameter.

.. change::
:tags: bug, orm
:tickets: 3801

An UPDATE emitted from the ORM flush process can now accommodate a
SQL expression element for a column within the primary key of an
object, if the target database supports RETURNING in order to provide
the new value, or if the PK value is set "to itself" for the purposes
of bumping some other trigger / onupdate on the column.

.. change::
:tags: bug, orm
:tickets: 3788

Fixed bug where the "simple many-to-one" condition that allows  lazy
loading to use get() from identity map would fail to be  invoked if the
primaryjoin of the relationship had multiple clauses separated by AND
which were not in the same order as that of the primary key columns
being compared in each clause. This ordering
difference occurs for a composite foreign key where the table-bound
columns on the referencing side were not in the same order in the .c
collection as the primary key columns on the referenced side....which
in turn occurs a lot if one is using declarative mixins and/or
declared_attr to set up columns.

.. change::
:tags: bug, sql
:tickets: 3789

Stringify of expression with unnamed :class:`.Column` objects, as
occurs in lots of situations including ORM error reporting,
will now render the name in string context as "<name unknown>"
rather than raising a compile error.

.. change::
:tags: bug, sql
:tickets: 3786

Raise a more descriptive exception / message when ClauseElement
or non-SQLAlchemy objects that are not "executable" are erroneously
passed to ``.execute()``; a new exception ObjectNotExecutableError
is raised consistently in all cases.

.. change::
:tags: bug, orm
:tickets: 3776

An exception is raised when two ``validates`` decorators on a mapping
make use of the same name.  Only one validator of a certain name
at a time is supported, there's no mechanism to chain these together,
as the order of the validators at the level of function decorator
can't be made deterministic.

.. seealso::

:ref:`change_3776`

.. change::
:tags: bug, orm

Mapper errors raised during :func:`.configure_mappers` now explicitly
include the name of the originating mapper in the exception message
to help in those situations where the wrapped exception does not
itself include the source mapper.  Pull request courtesy
John Perkins.

.. change::
:tags: bug, mysql
:tickets: 3766

Fixed bug where the "literal_binds" flag would not be propagated
to a CAST expression under MySQL.

.. change::
:tags: bug, sql, postgresql, mysql
:tickets: 3765

Fixed regression in JSON datatypes where the "literal processor" for
a JSON index value would not be invoked.  The native String and Integer
datatypes are now called upon from within the JSONIndexType
and JSONPathType.  This is applied to the generic, PostgreSQL, and
MySQL JSON types and also has a dependency on :ticket:`3766`.

.. change::
:tags: change, orm

Passing False to :meth:`.Query.order_by` in order to cancel
all order by's is deprecated; there is no longer any difference
between calling this method with False or with None.

.. change::
:tags: feature, orm

The :meth:`.Query.group_by` method now resets the group by collection
if an argument of ``None`` is passed, in the same way that
:meth:`.Query.order_by` has worked for a long time.  Pull request
courtesy Iuri Diniz.

.. change::
:tags: bug, sql
:tickets: 3763

Fixed bug where :class:`.Index` would fail to extract columns from
compound SQL expressions if those SQL expressions were wrapped inside
of an ORM-style ``__clause_element__()`` construct.  This bug
exists in 1.0.x as well, however in 1.1 is more noticeable as
hybrid_property expression now returns a wrapped element.

.. change::
:tags: change, orm, declarative

Constructing a declarative base class that inherits from another class
will also inherit its docstring. This means
:func:`~.ext.declarative.as_declarative` acts more like a normal class
decorator.

.. changelog::

1.1.0b3

:released: July 26, 2016

.. change::
:tags: change, orm
:tickets: 3749

Removed a warning that dates back to 0.4 which emits when a same-named
relationship is placed on two mappers that inherits via joined or
single table inheritance.   The warning does not apply to the
current unit of work implementation.

.. seealso::

:ref:`change_3749`


.. change::
:tags: bug, sql
:tickets: 3745

Fixed bug in new CTE feature for update/insert/delete stated
as a CTE inside of an enclosing statement (typically SELECT) whereby
oninsert and onupdate values weren't called upon for the embedded
statement.

.. change::
:tags: bug, sql
:tickets: 3744

Fixed bug in new CTE feature for update/insert/delete whereby
an anonymous (e.g. no name passed) :class:`.CTE` construct around
the statement would fail.

.. change::
:tags: bug, ext

sqlalchemy.ext.indexable will intercept IndexError as well
as KeyError when raising as AttributeError.

.. change::
:tags: feature, ext

Added a "default" parameter to the new sqlalchemy.ext.indexable
extension.

.. changelog::

1.1.0b2

:released: July 1, 2016

.. change::
:tags: bug, ext, postgresql
:tickets: 3732

Made a slight behavioral change in the ``sqlalchemy.ext.compiler``
extension, whereby the existing compilation schemes for an established
construct would be removed if that construct itself didn't already
have its own dedicated ``__visit_name__``.  This was a
rare occurrence in 1.0, however in 1.1 :class:`.postgresql.ARRAY`
subclasses :class:`.sqltypes.ARRAY` and has this behavior.
As a result, setting up a compilation handler for another dialect
such as SQLite would render the main :class:`.postgresql.ARRAY`
object no longer compilable.

.. change::
:tags: bug, sql
:tickets: 3730

The processing performed by the :class:`.Boolean` datatype for backends
that only feature integer types has been made consistent between the
pure Python and C-extension versions, in that the C-extension version
will accept any integer value from the database as a boolean, not just
zero and one; additionally, non-boolean integer values being sent to
the database are coerced to exactly zero or one, instead of being
passed as the original integer value.

.. seealso::

:ref:`change_3730`

.. change::
:tags: bug, sql
:tickets: 3725

Rolled back the validation rules a bit in :class:`.Enum` to allow
unknown string values to pass through, unless the flag
``validate_string=True`` is passed to the Enum; any other kind of object is
still of course rejected.  While the immediate use
is to allow comparisons to enums with LIKE, the fact that this
use exists indicates there may be more unknown-string-comparison use
cases than we expected, which hints that perhaps there are some
unknown string-INSERT cases too.

.. change::
:tags: bug, mysql
:tickets: 3726

Dialed back the "order the primary key columns per auto-increment"
described in :ref:`change_mysql_3216` a bit, so that if the
:class:`.PrimaryKeyConstraint` is explicitly defined, the order
of columns is maintained exactly, allowing control of this behavior
when necessary.

.. changelog::

1.1.0b1

:released: June 16, 2016

.. change::
:tags: feature, sql
:tickets: 3718

Added TABLESAMPLE support via the new :meth:`.FromClause.tablesample`
method and standalone function.  Pull request courtesy Ilja Everilä.

.. seealso::

:ref:`change_3718`

.. change::
:tags: feature, orm, ext

A new ORM extension :ref:`indexable_toplevel` is added, which allows
construction of Python attributes which refer to specific elements
of "indexed" structures such as arrays and JSON fields.  Pull request
courtesy Jeong YunWon.

.. seealso::

:ref:`feature_indexable`

.. change::
:tags: bug, sql
:tickets: 3724

:meth:`.FromClause.count` is deprecated.  This function makes use of
an arbitrary column in the table and is not reliable; for Core use,
``func.count()`` should be preferred.

.. change::
:tags: feature, postgresql
:tickets: 3529

Added support for PostgreSQL's INSERT..ON CONFLICT using a new
PostgreSQL-specific :class:`.postgresql.dml.Insert` object.
Pull request and extensive efforts here by Robin Thomas.

.. seealso::

:ref:`change_3529`

.. change::
:tags: feature, postgresql

The DDL for DROP INDEX will emit "CONCURRENTLY" if the
``postgresql_concurrently`` flag is set upon the
:class:`.Index` and if the database in use is detected as
PostgreSQL version 9.2 or greater.   For CREATE INDEX, database
version detection is also added which will omit the clause if
PG version is less than 8.2.  Pull request courtesy Iuri de Silvio.

.. change::
:tags: bug, orm
:tickets: 3708

Fixed an issue where a many-to-one change of an object from one
parent to another could work inconsistently when combined with
an un-flushed modification of the foreign key attribute.  The attribute
move now considers the database-committed value of the foreign key
in order to locate the "previous" parent of the object being
moved.   This allows events to fire off correctly including
backref events.  Previously, these events would not always fire.
Applications which may have relied on the previously broken
behavior may be affected.

.. seealso::

:ref:`change_3708`

.. change::
:tags: feature, sql
:tickets: 3049

Added support for ranges in window functions, using the
:paramref:`.expression.over.range_` and
:paramref:`.expression.over.rows` parameters.

.. seealso::

:ref:`change_3049`

.. change::
:tags: feature, orm

Added new flag :paramref:`.Session.bulk_insert_mappings.render_nulls`
which allows an ORM bulk INSERT to occur with NULL values rendered;
this bypasses server side defaults, however allows all statements
to be formed with the same set of columns, allowing them to be
batched.  Pull request courtesy Tobias Sauerwein.

.. change::
:tags: feature, postgresql
:tickets: 3588

Added new parameter :paramref:`.PGInspector.get_view_names.include`,
allowing specification for what kinds of views should be returned.
Currently "plain" and "materialized" views are included.  Pull
request courtesy Sebastian Bank.

.. change::
:tags: feature, mssql

The ``mssql_clustered`` flag available on :class:`.UniqueConstraint`,
:class:`.PrimaryKeyConstraint`, :class:`.Index` now defaults to
``None``, and can be set to False which will render the NONCLUSTERED
keyword in particular for a primary key, allowing a different index to
be used as "clustered". Pull request courtesy Saulius Žemaitaitis.

.. change::
:tags: feature, orm
:tickets: 1311

Added new event :meth:`.AttributeEvents.init_scalar`, as well
as a new example suite illustrating its use.  This event can be used
to provide a Core-generated default value to a Python-side attribute
before the object is persisted.

.. seealso::

:ref:`change_1311`

.. change::
:tags: feature, postgresql
:tickets: 3720

Added ``postgresql_tablespace`` as an argument to :class:`.Index`
to allow specification of TABLESPACE for an index in PostgreSQL.
Complements the same-named parameter on :class:`.Table`.  Pull
request courtesy Benjamin Bertrand.

.. change::
:tags: orm, feature

Added :paramref:`.AutomapBase.prepare.schema` to the
:meth:`.AutomapBase.prepare` method, to indicate which schema
tables should be reflected from if not the default schema.
Pull request courtesy Josh Marlow.

.. change::
:tags: feature, sqlite

The SQLite dialect now reflects ON UPDATE and ON DELETE phrases
within foreign key constraints.  Pull request courtesy
Michal Petrucha.

.. change::
:tags: bug, mssql

Adjustments to the mxODBC dialect to make use of the ``BinaryNull``
symbol when appropriate in conjunction with the ``VARBINARY``
data type.  Pull request courtesy Sheila Allen.

.. change::
:tags: feature, sql

Implemented reflection of CHECK constraints for SQLite and PostgreSQL.
This is available via the new inspector method
:meth:`.Inspector.get_check_constraints` as well as when reflecting
:class:`.Table` objects in the form of :class:`.CheckConstraint`
objects present in the constraints collection.  Pull request courtesy
Alex Grönholm.

.. change::
:tags: feature, postgresql

Added new parameter
:paramref:`.GenerativeSelect.with_for_update.key_share`, which
will render the ``FOR NO KEY UPDATE`` version of ``FOR UPDATE``
and ``FOR KEY SHARE`` instead of ``FOR SHARE``
on the PostgreSQL backend.  Pull request courtesy Sergey Skopin.

.. change::
:tags: feature, postgresql, oracle

Added new parameter
:paramref:`.GenerativeSelect.with_for_update.skip_locked`, which
will render the ``SKIP LOCKED`` phrase for a ``FOR UPDATE`` or
``FOR SHARE`` lock on the PostgreSQL and Oracle backends.  Pull
request courtesy Jack Zhou.

.. change::
:tags: change, orm
:tickets: 3394

The :paramref:`.Mapper.order_by` parameter is deprecated.
This is an old parameter no longer relevant to how SQLAlchemy
works, once the Query object was introduced.  By deprecating it
we establish that we aren't supporting non-working use cases
and that we encourage applications to move off of the use of this
parameter.

.. seealso::

:ref:`change_3394`

.. change::
:tags: feature, postgresql

Added a new dialect for the PyGreSQL PostgreSQL dialect.  Thanks
to Christoph Zwerschke and Kaolin Imago Fire for their efforts.

.. change::
:tags: bug, ext
:tickets: 3653

The docstring specified on a hybrid property or method is now honored
at the class level, allowing it to work with tools like Sphinx
autodoc.  The mechanics here necessarily involve some wrapping of
expressions to occur for hybrid properties, which may cause them
to appear differently using introspection.

.. seealso::

:ref:`change_3653`

.. change::
:tags: feature, sql

New :meth:`.ColumnOperators.is_distinct_from` and
:meth:`.ColumnOperators.isnot_distinct_from` operators; pull request
courtesy Sebastian Bank.

.. seealso::

:ref:`change_is_distinct_from`

.. change::
:tags: bug, orm
:tickets: 3488

Fixed bug where deferred columns would inadvertently be set up
for database load on the next object-wide unexpire, when the object
were merged into the session with ``session.merge(obj, load=False)``.

.. change::
:tags: feature, sql

Added a hook in :meth:`.DDLCompiler.visit_create_table` called
:meth:`.DDLCompiler.create_table_suffix`, allowing custom dialects
to add keywords after the "CREATE TABLE" clause.  Pull request
courtesy Mark Sandan.

.. change::
:tags: feature, sql

Negative integer indexes are now accommodated by rows
returned from a :class:`.ResultProxy`.  Pull request courtesy
Emanuele Gaifas.

.. seealso::

:ref:`change_gh_231`

.. change::
:tags: feature, sqlite
:tickets: 3629

The SQLite dialect now reflects the names of primary key constraints.
Pull request courtesy Diana Clarke.

.. seealso::

:ref:`change_3629`

.. change::
:tags: feature, sql
:tickets: 2857

Added :meth:`.Select.lateral` and related constructs to allow
for the SQL standard LATERAL keyword, currently only supported
by PostgreSQL.

.. seealso::

:ref:`change_2857`

.. change::
:tags: feature, sql
:tickets: 1957

Added support for rendering "FULL OUTER JOIN" to both Core and ORM.
Pull request courtesy Stefan Urbanek.

.. seealso::

:ref:`change_1957`

.. change::
:tags: feature, engine

Added connection pool events :meth:`ConnectionEvents.close`,
:meth:`.ConnectionEvents.detach`,
:meth:`.ConnectionEvents.close_detached`.

.. change::
:tags: bug, orm, mysql
:tickets: 3680

Further continuing on the common MySQL exception case of
a savepoint being cancelled first covered in :ticket:`2696`,
the failure mode in which the :class:`.Session` is placed when a
SAVEPOINT vanishes before rollback has been improved to allow the
:class:`.Session` to still function outside of that savepoint.
It is assumed that the savepoint operation failed and was cancelled.

.. seealso::

:ref:`change_3680`

.. change::
:tags: feature, mssql
:tickets: 3534

Added basic isolation level support to the SQL Server dialects
via :paramref:`.create_engine.isolation_level` and
:paramref:`.Connection.execution_options.isolation_level`
parameters.

.. seealso::

:ref:`change_3534`

.. change::
:tags: feature, mysql
:tickets: 3332

Added support for "autocommit" on MySQL drivers, via the
AUTOCOMMIT isolation level setting.  Pull request courtesy
Roman Podoliaka.

.. seealso::

:ref:`change_3332`

.. change::
:tags: bug, orm
:tickets: 3677

Fixed bug where a newly inserted instance that is rolled back
would still potentially cause persistence conflicts on the next
transaction, because the instance would not be checked that it
was expired.   This fix will resolve a large class of cases that
erroneously cause the "New instance with identity X conflicts with
persistent instance Y" error.

.. seealso::

:ref:`change_3677`

.. change::
:tags: bug, orm
:tickets: 3662

An improvement to the workings of :meth:`.Query.correlate` such
that when a "polymorphic" entity is used which represents a straight
join of several tables, the statement will ensure that all the
tables within the join are part of what's correlating.

.. seealso::

:ref:`change_3662`

.. change::
:tags: bug, orm
:tickets: 3431

Fixed bug which would cause an eagerly loaded many-to-one attribute
to not be loaded, if the joined eager load were from a row where the
same entity were present multiple times, some calling for the attribute
to be eagerly loaded and others not.  The logic here is revised to
take in the attribute even though a different loader path has
handled the parent entity already.

.. seealso::

:ref:`change_3431`

.. change::
:tags: feature, engine
:tickets: 2837

All string formatting of bound parameter sets and result rows for
logging, exception, and  ``repr()`` purposes now truncate very large
scalar values within each collection, including an
"N characters truncated"
notation, similar to how the display for large multiple-parameter sets
are themselves truncated.


.. seealso::

:ref:`change_2837`

.. change::
:tags: feature, ext
:tickets: 3297

Added :class:`.MutableSet` and :class:`.MutableList` helper classes
to the :ref:`mutable_toplevel` extension.  Pull request courtesy
Jeong YunWon.

.. change::
:tags: feature, sql
:tickets: 2551

CTE functionality has been expanded to support all DML, allowing
INSERT, UPDATE, and DELETE statements to both specify their own
WITH clause, as well as for these statements themselves to be
CTE expressions when they include a RETURNING clause.

.. seealso::

:ref:`change_2551`

.. change::
:tags: bug, orm
:tickets: 3641

A refinement to the logic which adds columns to the resulting SQL when
:meth:`.Query.distinct` is combined with :meth:`.Query.order_by` such
that columns which are already present will not be added
a second time, even if they are labeled with a different name.
Regardless of this change, the extra columns added to the SQL have
never been returned in the final result, so this change only impacts
the string form of the statement as well as its behavior when used in
a Core execution context.   Additionally, columns are no longer added
when the DISTINCT ON format is used, provided the query is not
wrapped inside a subquery due to joined eager loading.

.. seealso::

:ref:`change_3641`

.. change::
:tags: feature, sql
:tickets: 3292, 3095

Added support for PEP-435-style enumerated classes, namely
Python 3's ``enum.Enum`` class but also including compatible
enumeration libraries, to the :class:`.types.Enum` datatype.
The :class:`.types.Enum` datatype now also performs in-Python validation
of incoming values, and adds an option to forego creating the
CHECK constraint :paramref:`.Enum.create_constraint`.
Pull request courtesy Alex Grönholm.

.. seealso::

:ref:`change_3292`

:ref:`change_3095`

.. change::
:tags: change, postgresql

The ``sqlalchemy.dialects.postgres`` module, long deprecated, is
removed; this has emitted a warning for many years and projects
should be calling upon ``sqlalchemy.dialects.postgresql``.
Engine URLs of the form ``postgres://`` will still continue to function,
however.

.. change::
:tags: bug, sqlite
:tickets: 3634

The workaround for right-nested joins on SQLite, where they are rewritten
as subqueries in order to work around SQLite's lack of support for this
syntax, is lifted when SQLite version 3.7.16 or greater is detected.

.. seealso::

:ref:`change_3634`

.. change::
:tags: bug, sqlite
:tickets: 3633

The workaround for SQLite's unexpected delivery of column names as
``tablename.columnname`` for some kinds of queries is now disabled
when SQLite version 3.10.0 or greater is detected.

.. seealso::

:ref:`change_3633`

.. change::
:tags: feature, orm
:tickets: 2349

Added new parameter :paramref:`.orm.mapper.passive_deletes` to
available mapper options.   This allows a DELETE to proceed
for a joined-table inheritance mapping against the base table only,
while allowing for ON DELETE CASCADE to handle deleting the row
from the subclass tables.

.. seealso::

:ref:`change_2349`


.. change::
:tags: bug, sybase
:tickets: 2278

The unsupported Sybase dialect now raises ``NotImplementedError``
when attempting to compile a query that includes "offset"; Sybase
has no straightforward "offset" feature.

.. change::
:tags: feature, orm
:tickets: 3631

Calling str() on a core SQL construct has been made more "friendly",
when the construct contains non-standard SQL elements such as
RETURNING, array index operations, or dialect-specific or custom
datatypes.  A string is now returned in these cases rendering an
approximation of the construct (typically the PostgreSQL-style
version of it) rather than raising an error.

.. seealso::

:ref:`change_3631`

.. change::
:tags: bug, orm
:tickets: 3630

Fixed issue where two same-named relationships that refer to
a base class and a concrete-inherited subclass would raise an error
if those relationships were set up using "backref", while setting up the
identical configuration using relationship() instead with the conflicting
names would succeed, as is allowed in the case of a concrete mapping.

.. seealso::

:ref:`change_3630`

.. change::
:tags: feature, orm
:tickets: 3081

The ``str()`` call for :class:`.Query` will now take into account
the :class:`.Engine` to which the :class:`.Session` is bound, when
generating the string form of the SQL, so that the actual SQL
that would be emitted to the database is shown, if possible.  Previously,
only the engine associated with the :class:`.MetaData` to which the
mappings are associated would be used, if present.  If
no bind can be located either on the :class:`.Session` or on
the :class:`.MetaData` to which the mappings are associated, then
the "default" dialect is used to render the SQL, as was the case
previously.

.. seealso::

:ref:`change_3081`

.. change::
:tags: feature, sql
:tickets: 3501

A deep improvement to the recently added :meth:`.TextClause.columns`
method, and its interaction with result-row processing, now allows
the columns passed to the method to be positionally matched with the
result columns in the statement, rather than matching on name alone.
The advantage to this includes that when linking a textual SQL statement
to an ORM or Core table model, no system of labeling or de-duping of
common column names needs to occur, which also means there's no need
to worry about how label names match to ORM columns and so-forth.  In
addition, the :class:`.ResultProxy` has been further enhanced to
map column and string keys to a row with greater precision in some
cases.

.. seealso::

:ref:`change_3501` - feature overview

:ref:`behavior_change_3501` - backwards compatibility remarks

.. change::
:tags: feature, engine
:tickets: 2685

Multi-tenancy schema translation for :class:`.Table` objects is added.
This supports the use case of an application that uses the same set of
:class:`.Table` objects in many schemas, such as schema-per-user.
A new execution option
:paramref:`.Connection.execution_options.schema_translate_map` is
added.

.. seealso::

:ref:`change_2685`

.. change::
:tags: feature, engine
:tickets: 3536

Added a new entrypoint system to the engine to allow "plugins" to
be stated in the query string for a URL.   Custom plugins can
be written which will be given the chance up front to alter and/or
consume the engine's URL and keyword arguments, and then at engine
create time will be given the engine itself to allow additional
modifications or event registration.  Plugins are written as a
subclass of :class:`.CreateEnginePlugin`; see that class for
details.

.. change::
:tags: feature, mysql
:tickets: 3547

Added :class:`.mysql.JSON` for MySQL 5.7.  The JSON type provides
persistence of JSON values in MySQL as well as basic operator support
of "getitem" and "getpath", making use of the ``JSON_EXTRACT``
function in order to refer to individual paths in a JSON structure.

.. seealso::

:ref:`change_3547`

.. change::
:tags: feature, sql
:tickets: 3619

Added a new type to core :class:`.types.JSON`.  This is the
base of the PostgreSQL :class:`.postgresql.JSON` type as well as that
of the new :class:`.mysql.JSON` type, so that a PG/MySQL-agnostic
JSON column may be used.  The type features basic index and path
searching support.

.. seealso::

:ref:`change_3619`

.. change::
:tags: bug, sql
:tickets: 3616

Fixed an assertion that would raise somewhat inappropriately
if a :class:`.Index` were associated with a :class:`.Column` that
is associated with a lower-case-t :class:`.TableClause`; the
association should be ignored for the purposes of associating
the index with a :class:`.Table`.

.. change::
:tags: bug, orm
:tickets: 3601

The :meth:`.Session.merge` method now tracks pending objects by
primary key before emitting an INSERT, and merges distinct objects with
duplicate primary keys together as they are encountered, which is
essentially semi-deterministic at best.   This behavior
matches what happens already with persistent objects.

.. seealso::

:ref:`change_3601`

.. change::
:tags: bug, postgresql
:tickets: 3587

Added support for reflecting the source of materialized views
to the PostgreSQL version of the :meth:`.Inspector.get_view_definition`
method.

.. change::
:tags: bug, orm
:tickets: 3582

Fixed bug where the "single table inheritance" criteria would be
added onto the end of a query in some inappropriate situations, such
as when querying from an exists() of a single-inheritance subclass.

.. seealso::

:ref:`change_3582`

.. change::
:tags: enhancement, schema

The default generation functions passed to :class:`.Column` objects
are now run through "update_wrapper", or an equivalent function
if a callable non-function is passed, so that introspection tools
preserve the name and docstring of the wrapped function.  Pull
request courtesy hsum.

.. change::
:tags: change, sql, mysql
:tickets: 3216

The system by which a :class:`.Column` considers itself to be an
"auto increment" column has been changed, such that autoincrement
is no longer implicitly enabled for a :class:`.Table` that has a
composite primary key.  In order to accommodate being able to enable
autoincrement for a composite PK member column while at the same time
maintaining SQLAlchemy's long standing behavior of enabling
implicit autoincrement for a single integer primary key, a third
state has been added to the :paramref:`.Column.autoincrement` parameter
``"auto"``, which is now the default.

.. seealso::

:ref:`change_3216`

:ref:`change_mysql_3216`

.. change::
:tags: change, mysql
:tickets: 3216

The MySQL dialect no longer generates an extra "KEY" directive when
generating CREATE TABLE DDL for a table using InnoDB with a
composite primary key with AUTO_INCREMENT on a column that isn't the
first column;  to overcome InnoDB's limitation here, the PRIMARY KEY
constraint is now generated with the AUTO_INCREMENT column placed
first in the list of columns.

.. seealso::

:ref:`change_mysql_3216`

:ref:`change_3216`

.. change::
:tags: change, sqlite

Added support to the SQLite dialect for the
:meth:`.Inspector.get_schema_names` method to work with SQLite;
pull request courtesy Brian Van Klaveren.  Also repaired support
for creation of indexes with schemas as well as reflection of
foreign key constraints in schema-bound tables.

.. seealso::

:ref:`change_sqlite_schemas`

.. change::
:tags: change, mssql
:tickets: 3434

The ``legacy_schema_aliasing`` flag, introduced in version 1.0.5
as part of :ticket:`3424` to allow disabling of the MSSQL dialect's
attempts to create aliases for schema-qualified tables, now defaults
to False; the old behavior is now disabled unless explicitly turned on.

.. seealso::

:ref:`change_3434`

.. change::
:tags: bug, orm
:tickets: 3250

Added a new type-level modifier :meth:`.TypeEngine.evaluates_none`
which indicates to the ORM that a positive set of None should be
persisted as the value NULL, instead of omitting the column from
the INSERT statement.  This feature is used both as part of the
implementation for :ticket:`3514` as well as a standalone feature
available on any type.

.. seealso::

:ref:`change_3250`

.. change::
:tags: bug, postgresql
:tickets: 2729

The use of a :class:`.postgresql.ARRAY` object that refers
to a :class:`.types.Enum` or :class:`.postgresql.ENUM` subtype
will now emit the expected "CREATE TYPE" and "DROP TYPE" DDL when
the type is used within a "CREATE TABLE" or "DROP TABLE".

.. seealso::

:ref:`change_2729`

.. change::
:tags: bug, sql
:tickets: 3531

The :func:`.type_coerce` construct is now a fully fledged Core
expression element which is late-evaluated at compile time.  Previously,
the function was only a conversion function which would handle different
expression inputs by returning either a :class:`.Label` of a column-oriented
expression or a copy of a given :class:`.BindParameter` object,
which in particular prevented the operation from being logically
maintained when an ORM-level expression transformation would convert
a column to a bound parameter (e.g. for lazy loading).

.. seealso::

:ref:`change_3531`

.. change::
:tags: bug, orm
:tickets: 3526

Internal calls to "bookkeeping" functions within
:meth:`.Session.bulk_save_objects` and related bulk methods have
been scaled back to the extent that this functionality is not
currently used, e.g. checks for column default values to be
fetched after an INSERT or UPDATE statement.

.. change::
:tags: feature, orm
:tickets: 2677

The :class:`.SessionEvents` suite now includes events to allow
unambiguous tracking of all object lifecycle state transitions
in terms of the :class:`.Session` itself, e.g. pending,
transient,  persistent, detached.   The state of the object
within each event is also defined.

.. seealso::

:ref:`change_2677`

.. change::
:tags: feature, orm
:tickets: 2677

Added a new session lifecycle state :term:`deleted`.  This new state
represents an object that has been deleted from the :term:`persistent`
state and will move to the :term:`detached` state once the transaction
is committed.  This resolves the long-standing issue that objects
which were deleted existed in a gray area between persistent and
detached.   The :attr:`.InstanceState.persistent` accessor will
**no longer** report on a deleted object as persistent; the
:attr:`.InstanceState.deleted` accessor will instead be True for
these objects, until they become detached.

.. seealso::

:ref:`change_2677`

.. change::
:tags: change, orm
:tickets: 2677

The :paramref:`.Session.weak_identity_map` parameter is deprecated.
See the new recipe at :ref:`session_referencing_behavior` for
an event-based approach to maintaining strong identity map behavior.

.. seealso::

:ref:`change_2677`

.. change::
:tags: bug, sql
:tickets: 2919

The :class:`.TypeDecorator` type extender will now work in conjunction
with a :class:`.SchemaType` implementation, typically :class:`.Enum`
or :class:`.Boolean` with regards to ensuring that the per-table
events are propagated from the implementation type to the outer type.
These events are used
to ensure that the constraints or PostgreSQL types (e.g. ENUM)
are correctly created (and possibly dropped) along with the parent
table.

.. seealso::

:ref:`change_2919`

.. change::
:tags: feature, sql
:tickets: 1370

Added support for "set-aggregate" functions of the form
``<function> WITHIN GROUP (ORDER BY <criteria>)``, using the
method :meth:`.FunctionElement.within_group`.  A series of common
set-aggregate functions with return types derived from the set have
been added. This includes functions like :class:`.percentile_cont`,
:class:`.dense_rank` and others.

.. seealso::

:ref:`change_3132`

.. change::
:tags: feature, sql, postgresql
:tickets: 3132

Added support for the SQL-standard function :class:`.array_agg`,
which automatically returns an :class:`.postgresql.ARRAY` of the correct type
and supports index / slice operations, as well as
:func:`.postgresql.array_agg`, which returns a :class:`.postgresql.ARRAY`
with additional comparison features.   As arrays are only
supported on PostgreSQL at the moment, only actually works on
PostgreSQL.  Also added a new construct
:class:`.postgresql.aggregate_order_by` in support of PG's
"ORDER BY" extension.

.. seealso::

:ref:`change_3132`

.. change::
:tags: feature, sql
:tickets: 3516

Added a new type to core :class:`.types.ARRAY`.  This is the
base of the PostgreSQL :class:`.postgresql.ARRAY` type, and is now part of Core
to begin supporting various SQL-standard array-supporting features
including some functions and eventual support for native arrays
on other databases that have an "array" concept, such as DB2 or Oracle.
Additionally, new operators :func:`.expression.any_` and
:func:`.expression.all_` have been added.  These support not just
array constructs on PostgreSQL, but also subqueries that are usable
on MySQL (but sadly not on PostgreSQL).

.. seealso::

:ref:`change_3516`

.. change::
:tags: feature, orm
:tickets: 3321

Added new checks for the common error case of passing mapped classes
or mapped instances into contexts where they are interpreted as
SQL bound parameters; a new exception is raised for this.

.. seealso::

:ref:`change_3321`

.. change::
:tags: bug, postgresql
:tickets: 3499

The "hashable" flag on special datatypes such as :class:`.postgresql.ARRAY`,
:class:`.postgresql.JSON` and :class:`.postgresql.HSTORE` is now
set to False, which allows these types to be fetchable in ORM
queries that include entities within the row.

.. seealso::

:ref:`change_3499`

:ref:`change_3499_postgresql`

.. change::
:tags: bug, postgresql
:tickets: 3487

The PostgreSQL :class:`.postgresql.ARRAY` type now supports multidimensional
indexed access, e.g. expressions such as ``somecol[5][6]`` without
any need for explicit casts or type coercions, provided
that the :paramref:`.postgresql.ARRAY.dimensions` parameter is set to the
desired number of dimensions.

.. seealso::

:ref:`change_3503`

.. change::
:tags: bug, postgresql
:tickets: 3503

The return type for the :class:`.postgresql.JSON` and :class:`.postgresql.JSONB`
when using indexed access has been fixed to work like PostgreSQL itself,
and returns an expression that itself is of type :class:`.postgresql.JSON`
or :class:`.postgresql.JSONB`.  Previously, the accessor would return
:class:`.NullType` which disallowed subsequent JSON-like operators to be
used.

.. seealso::

:ref:`change_3503`

.. change::
:tags: bug, postgresql
:tickets: 3503

The :class:`.postgresql.JSON`, :class:`.postgresql.JSONB` and
:class:`.postgresql.HSTORE` datatypes now allow full control over the
return type from an indexed textual access operation, either ``column[someindex].astext``
for a JSON type or ``column[someindex]`` for an HSTORE type,
via the :paramref:`.postgresql.JSON.astext_type` and
:paramref:`.postgresql.HSTORE.text_type` parameters.

.. seealso::

:ref:`change_3503`


.. change::
:tags: bug, postgresql
:tickets: 3503

The :attr:`.postgresql.JSON.Comparator.astext` modifier no longer
calls upon :meth:`.ColumnElement.cast` implicitly, as PG's JSON/JSONB
types allow cross-casting between each other as well.  Code that
makes use of :meth:`.ColumnElement.cast` on JSON indexed access,
e.g. ``col[someindex].cast(Integer)``, will need to be changed
to call :attr:`.postgresql.JSON.Comparator.astext` explicitly.

.. seealso::

:ref:`change_3503_cast`


.. change::
:tags: bug, orm, postgresql
:tickets: 3514

Additional fixes have been made regarding the value of ``None``
in conjunction with the PostgreSQL :class:`.postgresql.JSON` type.  When
the :paramref:`.JSON.none_as_null` flag is left at its default
value of ``False``, the ORM will now correctly insert the JSON
"'null'" string into the column whenever the value on the ORM
object is set to the value ``None`` or when the value ``None``
is used with :meth:`.Session.bulk_insert_mappings`,
**including** if the column has a default or server default on it.

.. seealso::

:ref:`change_3514`

:ref:`change_3250`

.. change::
:tags: feature, postgresql
:tickets: 3514

Added a new constant :attr:`.postgresql.JSON.NULL`, indicating
that the JSON NULL value should be used for a value
regardless of other settings.

.. seealso::

:ref:`change_3514_jsonnull`

.. change::
:tags: bug, sql
:tickets: 2528

The behavior of the :func:`.union` construct and related constructs
such as :meth:`.Query.union` now handle the case where the embedded
SELECT statements need to be parenthesized due to the fact that they
include LIMIT, OFFSET and/or ORDER BY.   These queries **do not work
on SQLite**, and will fail on that backend as they did before, but
should now work on all other backends.

.. seealso::

:ref:`change_2528`

.. change::
:tags: feature, orm
:tickets: 3512

Added new relationship loading strategy :func:`.orm.raiseload` (also
accessible via ``lazy='raise'``).  This strategy behaves almost like
:func:`.orm.noload` but instead of returning ``None`` it raises an
InvalidRequestError.  Pull request courtesy Adrian Moennich.

.. seealso::

:ref:`change_3512`

.. change::
:tags: bug, mssql
:tickets: 3504

Fixed issue where the SQL Server dialect would reflect a string-
or other variable-length column type with unbounded length
by assigning the token ``"max"`` to the
length attribute of the string.   While using the ``"max"`` token
explicitly is supported by the SQL Server dialect, it isn't part
of the normal contract of the base string types, and instead the
length should just be left as None.   The dialect now assigns the
length to None on reflection of the type so that the type behaves
normally in other contexts.

.. seealso::

:ref:`change_3504`


=============
1.2 Changelog
=============

.. changelog_imports::

.. include:: changelog_11.rst
:start-line: 5

.. include:: changelog_10.rst
:start-line: 5

.. changelog::
:version: 1.2.20
:include_notes_from: unreleased_12

.. changelog::

1.0.19

:released: August 3, 2017

.. change::
:tags: bug, oracle, performance, py2k
:tickets: 4035
:versions: 1.0.19, 1.1.13, 1.2.0b3

Fixed performance regression caused by the fix for :ticket:`3937` where
cx_Oracle as of version 5.3 dropped the ``.UNICODE`` symbol from its
namespace,  which was interpreted as cx_Oracle's "WITH_UNICODE" mode being
turned on unconditionally, which invokes functions on the SQLAlchemy
side which convert all strings to unicode unconditionally and causing
a performance impact.  In fact, per cx_Oracle's author the
"WITH_UNICODE" mode has been removed entirely as of 5.1, so the expensive unicode
conversion functions are no longer necessary and are disabled if
cx_Oracle 5.1 or greater is detected under Python 2.  The warning against
"WITH_UNICODE" mode that was removed under :ticket:`3937` is also restored.

.. changelog::

1.0.18

:released: July 24, 2017

.. change::
:tags: bug, tests, py3k
:tickets: 4034
:versions: 1.0.18, 1.1.12, 1.2.0b2

Fixed issue in testing fixtures which was incompatible with a change
made as of Python 3.6.2 involving context managers.

.. change:: 3937
:tags: bug, oracle
:tickets: 3937
:versions: 1.1.7

A fix to cx_Oracle's WITH_UNICODE mode which was uncovered by the
fact that cx_Oracle 5.3 now seems to hardcode this flag on in
the build; an internal method that uses this mode wasn't using
the correct signature.


.. changelog::

1.0.17

:released: January 17, 2017

.. change::
:tags: bug, py3k
:tickets: 3886
:versions: 1.1.5

Fixed Python 3.6 DeprecationWarnings related to escaped strings without
the 'r' modifier, and added test coverage for Python 3.6.

.. change::
:tags: bug, orm
:tickets: 3884
:versions: 1.1.5

Fixed bug involving joined eager loading against multiple entities
when polymorphic inheritance is also in use which would throw
"'NoneType' object has no attribute 'isa'".  The issue was introduced
by the fix for :ticket:`3611`.

.. changelog::

1.0.16

:released: November 15, 2016

.. change::
:tags: bug, orm
:tickets: 3849
:versions: 1.1.4

Fixed bug in :meth:`.Session.bulk_update_mappings` where an alternate-named
primary key attribute would not track properly into the UPDATE statement.

.. change::
:tags: bug, mssql
:tickets: 3810
:versions: 1.1.0

Changed the query used to get "default schema name", from one that
queries the database principals table to using the
"schema_name()" function, as issues have been reported that the
former system was unavailable on the Azure Data Warehouse edition.
It is hoped that this will finally work across all SQL Server
versions and authentication styles.

.. change::
:tags: bug, mssql
:tickets: 3814
:versions: 1.1.0

Updated the server version info scheme for pyodbc to use SQL Server
SERVERPROPERTY(), rather than relying upon pyodbc.SQL_DBMS_VER, which
continues to be unreliable particularly with FreeTDS.

.. change::
:tags: bug, orm
:tickets: 3800
:versions: 1.1.0

Fixed bug where joined eager loading would fail for a polymorphically-
loaded mapper, where the polymorphic_on was set to an un-mapped
expression such as a CASE expression.

.. change::
:tags: bug, orm
:tickets: 3798
:versions: 1.1.0

Fixed bug where the ArgumentError raised for an invalid bind
sent to a Session via :meth:`.Session.bind_mapper`,
:meth:`.Session.bind_table`,
or the constructor would fail to be correctly raised.

.. change::
:tags: bug, mssql
:tickes: 3791
:versions: 1.1.0

Added error code 20017 "unexpected EOF from the server" to the list of
disconnect exceptions that result in a connection pool reset.  Pull
request courtesy Ken Robbins.

.. change::
:tags: bug, orm.declarative
:tickets: 3797
:versions: 1.1.0

Fixed bug where setting up a single-table inh subclass of a joined-table
subclass which included an extra column would corrupt the foreign keys
collection of the mapped table, thereby interfering with the
initialization of relationships.

.. change::
:tags: bug, orm
:tickets: 3781
:versions: 1.1.4

Fixed bug in :meth:`.Session.bulk_save` where an UPDATE would
not function correctly in conjunction with a mapping that
implements a version id counter.

.. 3778

.. change::
:tags: bug, orm
:tickets: 3778
:versions: 1.1.4

Fixed bug where the :attr:`.Mapper.attrs`,
:attr:`.Mapper.all_orm_descriptors` and other derived attributes would
fail to refresh when mapper properties or other ORM constructs were
added to the mapper/class after these  accessors were first called.

.. change:: 3762
:tags: bug, mssql
:tickets: 3762
:versions: 1.1.4

Fixed bug in pyodbc dialect (as well as in the mostly non-working
adodbapi dialect) whereby a semicolon present in the password
or username fields could be interpreted as a separator for another
token; the values are now quoted when semicolons are present.

.. changelog::

1.0.15

:released: September 1, 2016

.. change::
:tags: bug, mysql
:tickets: 3787
:versions: 1.1.0

Added support for parsing MySQL/Connector boolean and integer
arguments within the URL query string: connection_timeout,
connect_timeout, pool_size, get_warnings,
raise_on_warnings, raw, consume_results, ssl_verify_cert, force_ipv6,
pool_reset_session, compress, allow_local_infile, use_pure.

.. change::
:tags: bug, orm
:tickets: 3773, 3774
:versions: 1.1.0

Fixed bug in subquery eager loading where a subqueryload
of an "of_type()" object linked to a second subqueryload of a plain
mapped class, or a longer chain of several "of_type()" attributes,
would fail to link the joins correctly.

.. change::
:tags: bug, sql
:tickets: 3755
:versions: 1.1.0

Fixed bug in :class:`.Table` where the internal method
``_reset_exported()`` would corrupt the state of the object.  This
method is intended for selectable objects and is called by the ORM
in some cases; an erroneous mapper configuration would could lead the
ORM to call this on a :class:`.Table` object.

.. change::
:tags: bug, ext
:tickets: 3743
:versions: 1.1.0b3

Fixed bug in ``sqlalchemy.ext.baked`` where the unbaking of a
subquery eager loader query would fail due to a variable scoping
issue, when multiple subquery loaders were involved.  Pull request
courtesy Mark Hahnenberg.

.. changelog::

1.0.14

:released: July 6, 2016

.. change::
:tags: bug, postgresql
:tickets: 3739
:versions: 1.1.0b3

Fixed bug whereby :class:`.TypeDecorator` and :class:`.Variant`
types were not deeply inspected enough by the PostgreSQL dialect
to determine if SMALLSERIAL or BIGSERIAL needed to be rendered
rather than SERIAL.

.. change::
:tags: bug, oracle
:tickets: 3741
:versions: 1.1.0b3

Fixed bug in :paramref:`.Select.with_for_update.of`, where the Oracle
"rownum" approach to LIMIT/OFFSET would fail to accommodate for the
expressions inside the "OF" clause, which must be stated at the topmost
level referring to expression within the subquery.  The expressions are
now added to the subquery if needed.

.. change::
:tags: bug, sql
:tickets: 3735
:versions: 1.1.0b2

Fixed issue in SQL math negation operator where the type of the
expression would no longer be the numeric type of the original.
This would cause issues where the type determined result set
behaviors.

.. change::
:tags: bug, sql
:tickets: 3728
:versions: 1.1.0b2

Fixed bug whereby the ``__getstate__`` / ``__setstate__``
methods for sqlalchemy.util.Properties were
non-working due to the transition in the 1.0 series to ``__slots__``.
The issue potentially impacted some third-party applications.
Pull request courtesy Pieter Mulder.

.. change::
:tags: bug, sql
:tickets: 3724

:meth:`.FromClause.count` is pending deprecation for 1.1.  This function
makes use of an arbitrary column in the table and is not reliable;
for Core use, ``func.count()`` should be preferred.

.. change::
:tags: bug, sql
:tickets: 3722

Fixed bug in :class:`.CTE` structure which would cause it to not
clone properly when a union was used, as is common in a recursive
CTE.  The improper cloning would cause errors when the CTE is used
in various ORM contexts such as that of a :func:`.column_property`.

.. change::
:tags: bug, sql
:tickets: 3721

Fixed bug whereby :meth:`.Table.tometadata` would make a duplicate
:class:`.UniqueConstraint` for each :class:`.Column` object that
featured the ``unique=True`` parameter.

.. change::
:tags: bug, engine, postgresql
:tickets: 3716

Fixed bug in cross-schema foreign key reflection in conjunction
with the :paramref:`.MetaData.schema` argument, where a referenced
table that is present in the "default" schema would fail since there
would be no way to indicate a :class:`.Table` that has "blank" for
a schema.  The special symbol :attr:`.schema.BLANK_SCHEMA` has been
added as an available value for :paramref:`.Table.schema` and
:paramref:`.Sequence.schema`, indicating that the schema name
should be forced to be ``None`` even if :paramref:`.MetaData.schema`
is specified.

.. change::
:tags: bug, examples
:tickets: 3704

Fixed a regression that occurred in the
examples/vertical/dictlike-polymorphic.py example which prevented it
from running.

.. changelog::

1.0.13

:released: May 16, 2016

.. change::
:tags: bug, orm
:tickets: 3700

Fixed bug in "evaluate" strategy of :meth:`.Query.update` and
:meth:`.Query.delete` which would fail to accommodate a bound
parameter with a "callable" value, as which occurs when filtering
by a many-to-one equality expression along a relationship.

.. change::
:tags: bug, postgresql
:tickets: 3715

Added disconnect detection support for the error string
"SSL error: decryption failed or bad record mac".  Pull
request courtesy Iuri de Silvio.

.. change::
:tags: bug, mssql
:tickets: 3711

Fixed bug where by ROW_NUMBER OVER clause applied for OFFSET
selects in SQL Server would inappropriately substitute a plain column
from the local statement that overlaps with a label name used by
the ORDER BY criteria of the statement.

.. change::
:tags: bug, orm
:tickets: 3710

Fixed bug whereby the event listeners used for backrefs could
be inadvertently applied multiple times, when using a deep class
inheritance hierarchy in conjunction with multiple mapper configuration
steps.

.. change::
:tags: bug, orm
:tickets: 3706

Fixed bug whereby passing a :func:`.text` construct to the
:meth:`.Query.group_by` method would raise an error, instead
of interpreting the object as a SQL fragment.

.. change::
:tags: bug, oracle
:tickets: 3705

Fixed a bug in the cx_Oracle connect process that caused a TypeError
when the either the user, password or dsn was empty. This prevented
external authentication to Oracle databases, and prevented connecting
to the default dsn.  The connect string oracle:// now logs into the
default dsn using the Operating System username, equivalent to
connecting using '/' with sqlplus.

.. change::
:tags: bug, oracle
:tickets: 3699

Fixed a bug in the result proxy used mainly by Oracle when binary and
other LOB types are in play, such that when query / statement caching
were used, the type-level result processors, notably that required by
the binary type itself but also any other processor, would become lost
after the first run of the statement due to it being removed from the
cached result metadata.

.. change::
:tags: bug, examples
:tickets: 3698

Changed the "directed graph" example to no longer consider
integer identifiers of nodes as significant; the "higher" / "lower"
references now allow mutual edges in both directions.

.. change::
:tags: bug, sql
:tickets: 3690

Fixed bug where when using ``case_sensitive=False`` with an
:class:`.Engine`, the result set would fail to correctly accommodate
for duplicate column names in the result set, causing an error
when the statement is executed in 1.0, and preventing the
"ambiguous column" exception from functioning in 1.1.

.. change::
:tags: bug, sql
:tickets: 3682

Fixed bug where the negation of an EXISTS expression would not
be properly typed as boolean in the result, and also would fail to be
anonymously aliased in a SELECT list as is the case with a
non-negated EXISTS construct.

.. change::
:tags: bug, sql
:tickets: 3666

Fixed bug where "unconsumed column names" exception would fail to
be raised in the case where :meth:`.Insert.values` were called
with a list of parameter mappings, instead of a single mapping
of parameters.  Pull request courtesy Athena Yao.

.. change::
:tags: bug, orm
:tickets: 3663

Anonymous labeling is applied to a :attr:`.func` construct that is
passed to :func:`.column_property`, so that if the same attribute
is referred to as a column expression twice the names are de-duped,
thus avoiding "ambiguous column" errors.   Previously, the
``.label(None)`` would need to be applied in order for the name
to be de-anonymized.

.. change::
:tags: bug, py3k
:tickets: 3660

Fixed bug in "to_list" conversion where a single bytes object
would be turned into a list of individual characters.  This would
impact among other things using the :meth:`.Query.get` method
on a primary key that's a bytes object.

.. change::
:tags: bug, orm
:tickets: 3658

Fixed regression appearing in the 1.0 series in ORM loading where the
exception raised for an expected column missing would incorrectly
be a ``NoneType`` error, rather than the expected
:class:`.NoSuchColumnError`.

.. change::
:tags: bug, mssql, oracle
:tickets: 3657

Fixed regression appearing in the 1.0 series which would cause the Oracle
and SQL Server dialects to incorrectly account for result set columns
when these dialects would wrap a SELECT in a subquery in order to
provide LIMIT/OFFSET behavior, and the original SELECT statement
referred to the same column multiple times, such as a column and
a label of that same column.  This issue is related
to :ticket:`3658` in that when the error occurred, it would also
cause a ``NoneType`` error, rather than reporting that it couldn't
locate a column.

.. changelog::

1.0.12

:released: February 15, 2016

.. change::
:tags: bug, orm
:tickets: 3647

Fixed bug in :meth:`.Session.merge` where an object with a composite
primary key that has values for some but not all of the PK fields
would emit a SELECT statement leaking the internal NEVER_SET symbol
into the query, rather than detecting that this object does not have
a searchable primary key and no SELECT should be emitted.

.. change::
:tags: bug, postgresql
:tickets: 3644

Fixed bug in :func:`.expression.text` construct where a double-colon
expression would not escape properly, e.g. ``some\:\:expr``, as is most
commonly required when rendering PostgreSQL-style CAST expressions.

.. change::
:tags: bug, sql
:tickets: 3643

Fixed issue where the "literal_binds" flag was not propagated
for :func:`.expression.insert`, :func:`.expression.update` or
:func:`.expression.delete` constructs when compiled to string
SQL.  Pull request courtesy Tim Tate.

.. change::
:tags: bug, oracle, jython
:tickets: 3621

Fixed a small issue in the Jython Oracle compiler involving the
rendering of "RETURNING" which allows this currently
unsupported/untested dialect to work rudimentally with the 1.0 series.
Pull request courtesy Carlos Rivas.

.. change::
:tags: bug, sql
:tickets: 3642

Fixed issue where inadvertent use of the Python ``__contains__``
override with a column expression (e.g. by using ``'x' in col``)
would cause an endless loop in the case of an ARRAY type, as Python
defers this to ``__getitem__`` access which never raises for this
type.  Overall, all use of ``__contains__`` now raises
NotImplementedError.

.. change::
:tags: bug, engine, mysql
:tickets: 2696

Revisiting :ticket:`2696`, first released in 1.0.10, which attempts to
work around Python 2's lack of exception context reporting by emitting
a warning for an exception that was interrupted by a second exception
when attempting to roll back the already-failed transaction; this
issue continues to occur for MySQL backends in conjunction with a
savepoint that gets unexpectedly lost, which then causes a
"no such savepoint" error when the rollback is attempted, obscuring
what the original condition was.

The approach has been generalized to the Core "safe
reraise" function which takes place across the ORM and Core in any
place that a transaction is being rolled back in response to an error
which occurred trying to commit, including the context managers
provided by :class:`.Session` and :class:`.Connection`, and taking
place for operations such as a failure on "RELEASE SAVEPOINT".
Previously, the fix was only in place for a specific path within
the ORM flush/commit process; it now takes place for all transactional
context managers as well.

.. change::
:tags: bug, sql
:tickets: 3632

Fixed bug in :class:`.Table` metadata construct which appeared
around the 0.9 series where adding columns to a :class:`.Table`
that was unpickled would fail to correctly establish the
:class:`.Column` within the 'c' collection, leading to issues in
areas such as ORM configuration.   This could impact use cases such
as ``extend_existing`` and others.

.. change::
:tags: bug, py3k
:tickets: 3625

Fixed bug where some exception re-raise scenarios would attach
the exception to itself as the "cause"; while the Python 3 interpreter
is OK with this, it could cause endless loops in iPython.

.. change::
:tags: bug, mssql
:tickets: 3624

Fixed the syntax of the :func:`.extract` function when used on
MSSQL against a datetime value; the quotes around the keyword
are removed.  Pull request courtesy Guillaume Doumenc.

.. change::
:tags: bug, orm
:tickets: 3623

Fixed regression since 0.9 where the 0.9 style loader options
system failed to accommodate for multiple :func:`.undefer_group`
loader options in a single query.   Multiple :func:`.undefer_group`
options will now be taken into account even against the same
entity.

.. change::
:tags: bug, mssql, firebird
:tickets: 3622

Fixed 1.0 regression where the eager fetch of cursor.rowcount was
no longer called for an UPDATE or DELETE statement emitted via plain
text or via the :func:`.text` construct, affecting those drivers
that erase cursor.rowcount once the cursor is closed such as SQL
Server ODBC and Firebird drivers.


.. changelog::

1.0.11

:released: December 22, 2015

.. change::
:tags: bug, mysql
:tickets: 3613

An adjustment to the regular expression used to parse MySQL views,
such that we no longer assume the "ALGORITHM" keyword is present in
the reflected view source, as some users have reported this not being
present in some Amazon RDS environments.

.. change::
:tags: bug, mysql

Added new reserved words for MySQL 5.7 to the MySQL dialect,
including 'generated', 'optimizer_costs', 'stored', 'virtual'.
Pull request courtesy Hanno Schlichting.

.. change::
:tags: bug, ext
:tickets: 3605

Further fixes to :ticket:`3605`, pop method on :class:`.MutableDict`,
where the "default" argument was not included.

.. change::
:tags: bug, ext
:tickets: 3612

Fixed bug in baked loader system where the systemwide monkeypatch
for setting up baked lazy loaders would interfere with other
loader strategies that rely on lazy loading as a fallback, e.g.
joined and subquery eager loaders, leading to ``IndexError``
exceptions at mapper configuration time.

.. change::
:tags: bug, orm
:tickets: 3611

Fixed regression caused in 1.0.10 by the fix for :ticket:`3593` where
the check added for a polymorphic joinedload from a
poly_subclass->class->poly_baseclass connection would fail for the
scenario of class->poly_subclass->class.

.. change::
:tags: bug, orm
:tickets: 3610

Fixed bug where :meth:`.Session.bulk_update_mappings` and related
would not bump a version id counter when in use.  The experience
here is still a little rough as the original version id is required
in the given dictionaries and there's not clean error reporting
on that yet.

.. change::
:tags: bug, sql
:tickets: 3609

Fixed bug in :meth:`.Update.return_defaults` which would cause all
insert-default holding columns not otherwise included in the SET
clause (such as primary key cols) to get rendered into the RETURNING
even though this is an UPDATE.

.. change::
:tags: bug, orm
:tickets: 3609

Major fixes to the :paramref:`.Mapper.eager_defaults` flag, this
flag would not be honored correctly in the case that multiple
UPDATE statements were to be emitted, either as part of a flush
or a bulk update operation.  Additionally, RETURNING
would be emitted unnecessarily within update statements.

.. change::
:tags: bug, orm
:tickets: 3606

Fixed bug where use of the :meth:`.Query.select_from` method would
cause a subsequent call to the :meth:`.Query.with_parent` method to
fail.

.. changelog::

1.0.10

:released: December 11, 2015

.. change::
:tags: bug, ext
:tickets: 3605

Added support for the ``dict.pop()`` and ``dict.popitem()`` methods
to the :class:`.mutable.MutableDict` class.

.. change::
:tags: change, tests

The ORM and Core tutorials, which have always been in doctest format,
are now exercised within the normal unit test suite in both Python
2 and Python 3.

.. change::
:tags: bug, sql
:tickets: 3603

Fixed issue within the :meth:`.Insert.from_select` construct whereby
the :class:`.Select` construct would have its ``._raw_columns``
collection mutated in-place when compiling the :class:`.Insert`
construct, when the target :class:`.Table` has Python-side defaults.
The :class:`.Select` construct would compile standalone with the
erroneous column present subsequent to compilation of the
:class:`.Insert`, and the :class:`.Insert` statement itself would
fail on a second compile attempt due to duplicate bound parameters.

.. change::
:tags: bug, mysql
:tickets: 3602

Fixed bug in MySQL reflection where the "fractional sections portion"
of the :class:`.mysql.DATETIME`, :class:`.mysql.TIMESTAMP` and
:class:`.mysql.TIME` types would be incorrectly placed into the
``timezone`` attribute, which is unused by MySQL, instead of the
``fsp`` attribute.

.. change::
:tags: bug, orm
:tickets: 3599

Fixed issue where post_update on a many-to-one relationship would
fail to emit an UPDATE in the case where the attribute were set to
None and not previously loaded.

.. change::
:tags: bug, sql, postgresql
:tickets: 3598

Fixed bug where CREATE TABLE with a no-column table, but a constraint
such as a CHECK constraint would render an erroneous comma in the
definition; this scenario can occur such as with a PostgreSQL
INHERITS table that has no columns of its own.

.. change::
:tags: bug, mssql
:tickets: 3585


Added the error "20006: Write to the server failed" to the list
of disconnect errors for the pymssql driver, as this has been observed
to render a connection unusable.

.. change::
:tags: bug, postgresql
:tickets: 3573


Fixed issue where the "FOR UPDATE OF" PostgreSQL-specific SELECT
modifier would fail if the referred table had a schema qualifier;
PG needs the schema name to be omitted.  Pull request courtesy
Diana Clarke.

.. change::
:tags: bug, postgresql


Fixed bug where some varieties of SQL expression passed to the
"where" clause of :class:`.postgresql.ExcludeConstraint` would fail
to be accepted correctly.  Pull request courtesy aisch.

.. change::
:tags: bug, orm, declarative


Fixed bug where in Py2K a unicode literal would not be accepted as the
string name of a class or other argument within declarative using
:func:`.backref` on :func:`.relationship`.  Pull request courtesy
Nils Philippsen.

.. change::
:tags: bug, mssql

A descriptive ValueError is now raised in the event that SQL server
returns an invalid date or time format from a DATE or TIME
column, rather than failing with a NoneType error.  Pull request
courtesy Ed Avis.

.. change::
:tags: bug, py3k

Updates to internal getargspec() calls, some py36-related
fixture updates, and alterations to two iterators to "return" instead
of raising StopIteration, to allow tests to pass without
errors or warnings on Py3.5, Py3.6, pull requests courtesy
Jacob MacDonald, Luri de Silvio, and Phil Jones.

.. change::
:tags: bug, ext
:tickets: 3597

Fixed an issue in baked queries where the .get() method, used either
directly or within lazy loads, didn't consider the mapper's "get clause"
as part of the cache key, causing bound parameter mismatches if the
clause got re-generated.  This clause is cached by mappers
on the fly but in highly concurrent scenarios may be generated more
than once when first accessed.

.. change::
:tags: feature, sql

Added support for parameter-ordered SET clauses in an UPDATE
statement.  This feature is available by passing the
:paramref:`~.sqlalchemy.sql.expression.update.preserve_parameter_order`
flag either to the core :class:`.Update` construct or alternatively
adding it to the :paramref:`.Query.update.update_args` dictionary at
the ORM-level, also passing the parameters themselves as a list of 2-tuples.
Thanks to Gorka Eguileor for implementation and tests.

.. seealso::

:ref:`updates_order_parameters`

.. change::
:tags: bug, orm
:tickets: 3593

Fixed bug which is actually a regression that occurred between
versions 0.8.0 and 0.8.1, due :ticket:`2714`.  The case where
joined eager loading needs to join out over a subclass-bound
relationship when "with_polymorphic" were also used would fail
to join from the correct entity.

.. change::
:tags: bug, orm
:tickets: 3592

Fixed joinedload bug which would occur when a. the query includes
limit/offset criteria that forces a subquery b. the relationship
uses "secondary" c. the primaryjoin of the relationship refers to
a column that is either not part of the primary key, or is a PK
col in a joined-inheritance subclass table that is under a different
attribute name than the parent table's primary key column d. the
query defers the columns that are present in the primaryjoin, typically
via not being included in load_only(); the necessary column(s) would
not be present in the subquery and produce invalid SQL.

.. change::
:tags: bug, orm
:tickets: 2696

A rare case which occurs when a :meth:`.Session.rollback` fails in the
scope of a :meth:`.Session.flush` operation that's raising an
exception, as has been observed in some MySQL SAVEPOINT cases, prevents
the original  database exception from being observed when it was
emitted during  flush, but only on Py2K because Py2K does not support
exception  chaining; on Py3K the originating exception is chained.  As
a workaround, a warning is emitted in this specific case showing at
least the string message of the original database error before we
proceed to raise  the rollback-originating exception.

.. change::
:tags: bug, postgresql
:tickets: 3571

Fixed the ``.python_type`` attribute of :class:`.postgresql.INTERVAL`
to return ``datetime.timedelta`` in the same way as that of
:obj:`.types.Interval.python_type`, rather than raising
``NotImplementedError``.

.. change::
:tags: bug, mssql


Fixed issue where DDL generated for the MSSQL types DATETIME2,
TIME and DATETIMEOFFSET with a precision of "zero" would not generate
the precision field.  Pull request courtesy Jacobo de Vera.


.. changelog::

1.0.9

:released: October 20, 2015

.. change::
:tags: bug, orm, postgresql
:tickets: 3556

Fixed regression in 1.0 where new feature of using "executemany"
for UPDATE statements in the ORM (e.g. :ref:`feature_updatemany`)
would break on PostgreSQL and other RETURNING backends
when using server-side version generation
schemes, as the server side value is retrieved via RETURNING which
is not supported with executemany.

.. change::
:tags: feature, ext
:tickets: 3551

Added the :paramref:`.AssociationProxy.info` parameter to the
:class:`.AssociationProxy` constructor, to suit the
:attr:`.AssociationProxy.info` accessor that was added in
:ticket:`2971`.  This is possible because :class:`.AssociationProxy`
is constructed explicitly, unlike a hybrid which is constructed
implicitly via the decorator syntax.

.. change::
:tags: bug, oracle
:tickets: 3548

Fixed bug in Oracle dialect where reflection of tables and other
symbols with names quoted to force all-lower-case would not be
identified properly in reflection queries.  The :class:`.quoted_name`
construct is now applied to incoming symbol names that detect as
forced into all-lower-case within the "name normalize" process.

.. change::
:tags: feature, orm

Added new method :meth:`.Query.one_or_none`; same as
:meth:`.Query.one` but returns None if no row found.  Pull request
courtesy esiegerman.

.. change::
:tags: bug, orm
:tickets: 3539

Fixed rare TypeError which could occur when stringifying certain
kinds of internal column loader options within internal logging.

.. change::
:tags: bug, orm
:tickets: 3525

Fixed bug in :meth:`.Session.bulk_save_objects` where a mapped
column that had some kind of "fetch on update" value and was not
locally present in the given object would cause an AttributeError
within the operation.

.. change::
:tags: bug, sql
:tickets: 3520

Fixed regression in 1.0-released default-processor for multi-VALUES
insert statement, :ticket:`3288`, where the column type for the
default-holding column would not be propagated to the compiled
statement in the case where the default was being used,
leading to bind-level type handlers not being invoked.

.. change::
:tags: bug, examples


Fixed two issues in the "history_meta" example where history tracking
could encounter empty history, and where a column keyed to an alternate
attribute name would fail to track properly.  Fixes courtesy
Alex Fraser.

.. change::
:tags: bug, orm
:tickets: 3510


Fixed 1.0 regression where the "noload" loader strategy would fail
to function for a many-to-one relationship.  The loader used an
API to place "None" into the dictionary which no longer actually
writes a value; this is a side effect of :ticket:`3061`.

.. change::
:tags: bug, sybase
:tickets: 3508, 3509


Fixed two issues regarding Sybase reflection, allowing tables
without primary keys to be reflected as well as ensured that
a SQL statement involved in foreign key detection is pre-fetched up
front to avoid driver issues upon nested queries.  Fixes here
courtesy Eugene Zapolsky; note that we cannot currently test
Sybase to locally verify these changes.

.. change::
:tags: bug, postgresql


An adjustment to the new PostgreSQL feature of reflecting storage
options and USING of :ticket:`3455` released in 1.0.6,
to disable the feature for PostgreSQL versions < 8.2 where the
``reloptions`` column is not provided; this allows Amazon Redshift
to again work as it is based on an 8.0.x version of PostgreSQL.
Fix courtesy Pete Hollobon.


.. changelog::

1.0.8

:released: July 22, 2015

.. change::
:tags: bug, misc
:tickets: 3494

Fixed an issue where a particular base class within utils
didn't implement ``__slots__``, and therefore meant all subclasses
of that class didn't either, negating the rationale for ``__slots__``
to be in use.  Didn't cause any issue except on IronPython
which apparently does not implement ``__slots__`` behavior compatibly
with cPython.


.. changelog::

1.0.7

:released: July 20, 2015

.. change::
:tags: feature, sql
:tickets: 3459

Added a :meth:`.ColumnElement.cast` method which performs the same
purpose as the standalone :func:`.cast` function.  Pull request
courtesy Sebastian Bank.

.. change::
:tags: bug, engine
:tickets: 3481

Fixed regression where new methods on :class:`.ResultProxy` used
by the ORM :class:`.Query` object (part of the performance
enhancements of :ticket:`3175`) would not raise the "this result
does not return rows" exception in the case where the driver
(typically MySQL) fails to generate cursor.description correctly;
an AttributeError against NoneType would be raised instead.

.. change::
:tags: bug, engine
:tickets: 3483

Fixed regression where :meth:`.ResultProxy.keys` would return
un-adjusted internal symbol names for "anonymous" labels, which
are the "foo_1" types of labels we see generated for SQL functions
without labels and similar.  This was a side effect of the
performance enhancements implemented as part of 918.


.. change::
:tags: bug, sql
:tickets: 3490

Fixed bug where coercion of literal ``True`` or ``False`` constant
in conjunction with :func:`.and_` or :func:`.or_` would fail
with an AttributeError.

.. change::
:tags: bug, sql
:tickets: 3485

Fixed potential issue where a custom subclass
of :class:`.FunctionElement` or other column element that incorrectly
states 'None' or any other invalid object as the ``.type``
attribute will report this exception instead of recursion overflow.

.. change::
:tags: bug, sql

Fixed bug where the modulus SQL operator wouldn't work in reverse
due to a missing ``__rmod__`` method.  Pull request courtesy
dan-gittik.

.. change::
:tags: feature, schema

Added support for the MINVALUE, MAXVALUE, NO MINVALUE, NO MAXVALUE,
and CYCLE arguments for CREATE SEQUENCE as supported by PostgreSQL
and Oracle.  Pull request courtesy jakeogh.

.. change::
:tags: bug, orm, declarative
:tickets: 3480

Fixed bug in :class:`.AbstractConcreteBase` extension where
a column setup on the ABC base which had a different attribute
name vs. column name would not be correctly mapped on the final
base class.   The failure on 0.9 would be silent whereas on
1.0 it raised an ArgumentError, so may not have been noticed
prior to 1.0.

.. change::
:tags: bug, orm
:tickets: 3469

Fixed 1.0 regression where value objects that override
``__eq__()`` to return a non-boolean-capable object, such as
some geoalchemy types as well as numpy types, were being tested
for ``bool()`` during a unit of work update operation, where in
0.9 the return value of ``__eq__()`` was tested against "is True"
to guard against this.

.. change::
:tags: bug, orm
:tickets: 3468

Fixed 1.0 regression where a "deferred" attribute would not populate
correctly if it were loaded within the "optimized inheritance load",
which is a special SELECT emitted in the case of joined table
inheritance used to populate expired or unloaded attributes against
a joined table without loading the base table.  This is related to
the fact that SQLA 1.0 no longer guesses about loading deferred
columns and must be directed explicitly.

.. change::
:tags: bug, orm
:tickets: 3466

Fixed 1.0 regression where the "parent entity" of a synonym-
mapped attribute on top of an :func:`.aliased` object would
resolve to the original mapper, not the :func:`.aliased`
version of it, thereby causing problems for a :class:`.Query`
that relies on this attribute (e.g. it's the only representative
attribute given in the constructor) to figure out the correct FROM
clause for the query.

.. changelog::

1.0.6

:released: June 25, 2015

.. change::
:tags: bug, orm
:tickets: 3465

Fixed a major regression in the 1.0 series where the version_id_counter
feature would cause an object's version counter to be incremented
when there was no net change to the object's row, but instead an object
related to it via relationship (e.g. typically many-to-one)
were associated or de-associated with it, resulting in an UPDATE
statement that updates the object's version counter and nothing else.
In the use case where the relatively recent "server side" and/or
"programmatic/conditional" version counter feature were used
(e.g. setting version_id_generator to False), the bug could cause an
UPDATE without a valid SET clause to be emitted.

.. change::
:tags: bug, mssql
:tickets: 3464

Fixed issue when using :class:`.VARBINARY` type in conjunction with
an INSERT of NULL + pyodbc; pyodbc requires a special
object be passed in order to persist NULL.  As the :class:`.VARBINARY`
type is now usually the default for :class:`.LargeBinary` due to
:ticket:`3039`, this issue is partially a regression in 1.0.
The pymssql driver appears to be unaffected.

.. change::
:tags: bug, postgresql, pypy
:tickets: 3439

Re-fixed this issue first released in 1.0.5 to fix psycopg2cffi
JSONB support once again, as they suddenly
switched on unconditional decoding of JSONB types in version 2.7.1.
Version detection now specifies 2.7.1 as where we should expect
the DBAPI to do json encoding for us.

.. change::
:tags: feature, postgresql
:tickets: 3455

Added support for storage parameters under CREATE INDEX, using
a new keyword argument ``postgresql_with``.  Also added support for
reflection to support both the ``postgresql_with`` flag as well
as the ``postgresql_using`` flag, which will now be set on
:class:`.Index` objects that are reflected, as well present
in a new "dialect_options" dictionary in the result of
:meth:`.Inspector.get_indexes`.  Pull request courtesy Pete Hollobon.

.. seealso::

:ref:`postgresql_index_storage`

.. change::
:tags: bug, orm
:tickets: 3462

Fixed 1.0 regression where the enhanced behavior of single-inheritance
joins of :ticket:`3222` takes place inappropriately
for a JOIN along explicit join criteria with a single-inheritance
subclass that does not make use of any discriminator, resulting
in an additional "AND NULL" clause.

.. change::
:tags: bug, postgresql
:tickets: 3454

Repaired the :class:`.ExcludeConstraint` construct to support common
features that other objects like :class:`.Index` now do, that
the column expression may be specified as an arbitrary SQL
expression such as :obj:`.cast` or :obj:`.text`.

.. change::
:tags: feature, postgresql

Added new execution option ``max_row_buffer`` which is interpreted
by the psycopg2 dialect when the ``stream_results`` option is
used, which sets a limit on the size of the row buffer that may be
allocated.  This value is also provided based on the integer
value sent to :meth:`.Query.yield_per`.  Pull request courtesy
mcclurem.

.. change::
:tags: bug, orm
:tickets: 3451

Fixed bug in new :meth:`.Session.bulk_update_mappings` feature where
the primary key columns used in the WHERE clause to locate the row
would also be included in the SET clause, setting their value to
themselves unnecessarily.  Pull request courtesy Patrick Hayes.

.. change::
:tags: bug, orm
:tickets: 3448

Fixed an unexpected-use regression whereby custom :class:`.Comparator`
objects that made use of the ``__clause_element__()`` method and
returned an object that was an ORM-mapped
:class:`.InstrumentedAttribute` and not explicitly a
:class:`.ColumnElement` would fail to be correctly
handled when passed as an expression to :meth:`.Session.query`.
The logic in 0.9 happened to succeed on this, so this use case is now
supported.

.. change::
:tags: bug, sql
:tickets: 3445

Fixed a bug where clause adaption as applied to a :class:`.Label`
object would fail to accommodate the labeled SQL expression
in all cases, such that any SQL operation that made use of
:meth:`.Label.self_group` would use the original unadapted
expression.  One effect of this would be that an ORM :func:`.aliased`
construct would not fully accommodate attributes mapped by
:obj:`.column_property`, such that the un-aliased table could
leak out when the property were used in some kinds of SQL
comparisons.

.. change::
:tags: bug, documentation
:tickets: 2077

Fixed an internal "memoization" routine for method types such
that a Python descriptor is no longer used; repairs inspectability
of these methods including support for Sphinx documentation.

.. changelog::

1.0.5

:released: June 7, 2015

.. change::
:tags: feature, engine

Added new engine event :meth:`.ConnectionEvents.engine_disposed`.
Called after the :meth:`.Engine.dispose` method is called.

.. change::
:tags: bug, postgresql, pypy
:tickets: 3439

Repaired some typing and test issues related to the pypy
psycopg2cffi dialect, in particular that the current 2.7.0 version
does not have native support for the JSONB type.  The version detection
for psycopg2 features has been tuned into a specific sub-version
for psycopg2cffi.  Additionally, test coverage has been enabled
for the full series of psycopg2 features under psycopg2cffi.

.. change::
:tags: feature, ext

Added support for ``*args`` to be passed to the baked query
initial callable, in the same way that ``*args`` are supported
for the :meth:`.BakedQuery.add_criteria` and
:meth:`.BakedQuery.with_criteria` methods.  Initial PR courtesy
Naoki INADA.

.. change::
:tags: bug, engine
:tickets: 3435

Fixed bug where known boolean values used by
:func:`.engine_from_config` were not being parsed correctly;
these included ``pool_threadlocal`` and the psycopg2 argument
``use_native_unicode``.

.. change::
:tags: bug, mssql
:tickets: 3424, 3430

Added a new dialect flag to the MSSQL dialect
``legacy_schema_aliasing`` which when set to False will disable a
very old and obsolete behavior, that of the compiler's
attempt to turn all schema-qualified table names into alias names,
to work around old and no longer locatable issues where SQL
server could not parse a multi-part identifier name in all
circumstances.   The behavior prevented more
sophisticated statements from working correctly, including those which
use hints, as well as CRUD statements that embed correlated SELECT
statements.  Rather than continue to repair the feature to work
with more complex statements, it's better to just disable it
as it should no longer be needed for any modern SQL server
version.  The flag defaults to True for the 1.0.x series, leaving
current behavior unchanged for this version series.  In the 1.1
series, it will default to False.  For the 1.0 series,
when not set to either value explicitly, a warning is emitted
when a schema-qualified table is first used in a statement, which
suggests that the flag be set to False for all modern SQL Server
versions.

.. seealso::

:ref:`legacy_schema_rendering`

.. change::
:tags: feature, engine
:tickets: 3379

Adjustments to the engine plugin hook, such that the
:meth:`.URL.get_dialect` method will continue to return the
ultimate :class:`.Dialect` object when a dialect plugin is used,
without the need for the caller to be aware of the
:meth:`.Dialect.get_dialect_cls` method.


.. change::
:tags: bug, ext
:tickets: 3427

Fixed regression in the :mod:`sqlalchemy.ext.mutable` extension
as a result of the bugfix for :ticket:`3167`,
where attribute and validation events are no longer
called within the flush process.  The mutable
extension was relying upon this behavior in the case where a column
level Python-side default were responsible for generating the new value
on INSERT or UPDATE, or when a value were fetched from the RETURNING
clause for "eager defaults" mode.  The new value would not be subject
to any event when populated and the mutable extension could not
establish proper coercion or history listening.  A new event
:meth:`.InstanceEvents.refresh_flush` is added which the mutable
extension now makes use of for this use case.

.. change::
:tags: feature, orm
:tickets: 3427

Added new event :meth:`.InstanceEvents.refresh_flush`, invoked
when an INSERT or UPDATE level default value fetched via RETURNING
or Python-side default is invoked within the flush process.  This
is to provide a hook that is no longer present as a result of
:ticket:`3167`, where attribute and validation events are no longer
called within the flush process.

.. change::
:tags: feature, ext
:tickets: 3427

Added a new semi-public method to :class:`.MutableBase`
:meth:`.MutableBase._get_listen_keys`.  Overriding this method
is needed in the case where a :class:`.MutableBase` subclass needs
events to propagate for attribute keys other than the key to which
the mutable type is associated with, when intercepting the
:meth:`.InstanceEvents.refresh` or
:meth:`.InstanceEvents.refresh_flush` events.  The current example of
this is composites using :class:`.MutableComposite`.

.. change::
:tags: bug, engine
:tickets: 3421

Added support for the case of the misbehaving DBAPI that has
pep-249 exception names linked to exception classes of an entirely
different name, preventing SQLAlchemy's own exception wrapping from
wrapping the error appropriately.
The SQLAlchemy dialect in use needs to implement a new
accessor :attr:`.DefaultDialect.dbapi_exception_translation_map`
to support this feature; this is implemented now for the py-postgresql
dialect.

.. change::
:tags: bug, orm
:tickets: 3420

The "lightweight named tuple" used when a :class:`.Query` returns
rows failed to implement ``__slots__`` correctly such that it still
had a ``__dict__``.    This is resolved, but in the extremely
unlikely case someone was assigning values to the returned tuples,
that will no longer work.

.. change::
:tags: bug, engine
:tickets: 3419

Fixed bug involving the case when pool checkout event handlers are used
and connection attempts are made in the handler itself which fail,
the owning connection record would not be freed until the stack trace
of the connect error itself were freed.   For the case where a test
pool of only a single connection were used, this means the pool would
be fully checked out until that stack trace were freed.  This mostly
impacts very specific debugging scenarios and is unlikely to have been
noticeable in any production application.  The fix applies an
explicit checkin of the record before re-raising the caught exception.


.. changelog::

1.0.4

:released: May 7, 2015

.. change::
:tags: bug, orm
:tickets: 3416

Fixed unexpected-use regression where in the odd case that the
primaryjoin of a relationship involved comparison to an unhashable
type such as an HSTORE, lazy loads would fail due to a hash-oriented
check on the statement parameters, modified in 1.0 as a result of
:ticket:`3061` to use hashing and modified in :ticket:`3368`
to occur in cases more common than "load on pending".
The values are now checked for the ``__hash__`` attribute beforehand.

.. change::
:tags: bug, orm
:tickets: 3412, 3347

Liberalized an assertion that was added as part of :ticket:`3347`
to protect against unknown conditions when splicing inner joins
together within joined eager loads with ``innerjoin=True``; if
some of the joins use a "secondary" table, the assertion needs to
unwrap further joins in order to pass.

.. change::
:tags: bug, schema
:tickets: 3411

Fixed bug in enhanced constraint-attachment logic introduced in
:ticket:`3341` where in the unusual case of a constraint that refers
to a mixture of :class:`.Column` objects and string column names
at the same time, the auto-attach-on-column-attach logic will be
skipped; for the constraint to be auto-attached in this case,
all columns must be assembled on the target table up front.
Added a new section to the migration document regarding the
original feature as well as this change.

.. seealso::

:ref:`change_3341`

.. change::
:tags: bug, orm
:tickets: 3409, 3320

Repaired / added to tests yet more expressions that were reported
as failing with the new 'entity' key value added to
:attr:`.Query.column_descriptions`, the logic to discover the "from"
clause is again reworked to accommodate columns from aliased classes,
as well as to report the correct value for the "aliased" flag in these
cases.


.. changelog::

1.0.3

:released: April 30, 2015

.. change::
:tags: bug, orm, pypy
:tickets: 3405

Fixed regression from 0.9.10 prior to release due to :ticket:`3349`
where the check for query state on :meth:`.Query.update` or
:meth:`.Query.delete` compared the empty tuple to itself using ``is``,
which fails on PyPy to produce ``True`` in this case; this would
erronously emit a warning in 0.9 and raise an exception in 1.0.

.. change::
:tags: feature, engine
:tickets: 3379

New features added to support engine/pool plugins with advanced
functionality.   Added a new "soft invalidate" feature to the
connection pool at the level of the checked out connection wrapper
as well as the :class:`._ConnectionRecord`.  This works similarly
to a modern pool invalidation in that connections aren't actively
closed, but are recycled only on next checkout; this is essentially
a per-connection version of that feature.  A new event
:class:`.PoolEvents.soft_invalidate` is added to complement it.

Also added new flag
:attr:`.ExceptionContext.invalidate_pool_on_disconnect`.
Allows an error handler within :meth:`.ConnectionEvents.handle_error`
to maintain a "disconnect" condition, but to handle calling invalidate
on individual connections in a specific manner within the event.

.. change::
:tags: feature, engine
:tickets: 3355

Added new event :class:`.DialectEvents.do_connect`, which allows
interception / replacement of when the :meth:`.Dialect.connect`
hook is called to create a DBAPI connection.  Also added
dialect plugin hooks :meth:`.Dialect.get_dialect_cls` and
:meth:`.Dialect.engine_created` which allow external plugins to
add events to existing dialects using entry points.

.. change::
:tags: bug, orm
:tickets: 3403, 3320

Fixed regression from 0.9.10 prior to release where the new addition
of ``entity`` to the :attr:`.Query.column_descriptions` accessor
would fail if the target entity was produced from a core selectable
such as a :class:`.Table` or :class:`.CTE` object.

.. change::
:tags: feature, sql

Added a placeholder method :meth:`.TypeEngine.compare_against_backend`
which is now consumed by Alembic migrations as of 0.7.6.  User-defined
types can implement this method to assist in the comparison of
a type against one reflected from the database.

.. change::
:tags: bug, orm
:tickets: 3402

Fixed regression within the flush process when an attribute were
set to a SQL expression for an UPDATE, and the SQL expression when
compared to the previous value of the attribute would produce a SQL
comparison other than ``==`` or ``!=``, the exception "Boolean value
of this clause is not defined" would raise.   The fix ensures that
the unit of work will not interpret the SQL expression in this way.

.. change::
:tags: bug, ext
:tickets: 3397

Fixed bug in association proxy where an any()/has()
on an relationship->scalar non-object attribute comparison would fail,
e.g.
``filter(Parent.some_collection_to_attribute.any(Child.attr == 'foo'))``

.. change::
:tags: bug, sql
:tickets: 3396

Fixed bug where the truncation of long labels in SQL could produce
a label that overlapped another label that is not truncated; this
because the length threshold for truncation was greater than
the portion of the label that remains after truncation.  These
two values have now been made the same; label_length - 6.
The effect here is that shorter column labels will be "truncated"
where they would not have been truncated before.

.. change::
:tags: bug, orm
:tickets: 3392

Fixed unexpected use regression due to :ticket:`2992` where
textual elements placed
into the :meth:`.Query.order_by` clause in conjunction with joined
eager loading would be added to the columns clause of the inner query
in such a way that they were assumed to be table-bound column names,
in the case where the joined eager load needs to wrap the query
in a subquery to accommodate for a limit/offset.

Originally, the behavior here was intentional, in that a query such
as ``query(User).order_by('name').limit(1)``
would order by ``user.name`` even if the query was modified by
joined eager loading to be within a subquery, as ``'name'`` would
be interpreted as a symbol to be located within the FROM clauses,
in this case ``User.name``, which would then be copied into the
columns clause to ensure it were present for ORDER BY.  However, the
feature fails to anticipate the case where ``order_by("name")`` refers
to a specific label name present in the local columns clause already
and not a name bound to a selectable in the FROM clause.

Beyond that, the feature also fails for deprecated cases such as
``order_by("name desc")``, which, while it emits a
warning that :func:`.text` should be used here (note that the issue
does not impact cases where :func:`.text` is used explicitly),
still produces a different query than previously where the "name desc"
expression is copied into the columns clause inappropriately.  The
resolution is such that the "joined eager loading" aspect of the
feature will skip over these so-called "label reference" expressions
when augmenting the inner columns clause, as though they were
:func:`.text` constructs already.

.. change::
:tags: bug, sql
:tickets: 3391

Fixed regression due to :ticket:`3282` where the ``tables`` collection
passed as a keyword argument to the :meth:`.DDLEvents.before_create`,
:meth:`.DDLEvents.after_create`, :meth:`.DDLEvents.before_drop`, and
:meth:`.DDLEvents.after_drop` events would no longer be a list
of tables, but instead a list of tuples which contained a second
entry with foreign keys to be added or dropped.  As the ``tables``
collection, while documented as not necessarily stable, has come
to be relied upon, this change is considered a regression.
Additionally, in some cases for "drop", this collection would
be an iterator that would cause the operation to fail if
prematurely iterated.   The collection is now a list of table
objects in all cases and test coverage for the format of this
collection is now added.


.. change::
:tags: bug, orm
:tickets: 3388

Fixed a regression regarding the :meth:`.MapperEvents.instrument_class`
event where its invocation was moved to be after the class manager's
instrumentation of the class, which is the opposite of what the
documentation for the event explicitly states.  The rationale for the
switch was due to Declarative taking the step of setting up
the full "instrumentation manager" for a class before it was mapped
for the purpose of the new ``declared_attr`` features
described in :ref:`feature_3150`, but the change was also made
against the classical use of :func:`.mapper` for consistency.
However, SQLSoup relies upon the instrumentation event happening
before any instrumentation under classical mapping.
The behavior is reverted in the case of classical and declarative
mapping, the latter implemented by using a simple memoization
without using class manager.

.. change::
:tags: bug, orm
:tickets: 3387

Fixed issue in new :meth:`.QueryEvents.before_compile` event where
changes made to the :class:`.Query` object's collection of entities
to load within the event would render in the SQL, but would not
be reflected during the loading process.

.. changelog::

1.0.2

:released: April 24, 2015

.. change::
:tags: bug, sql
:tickets: 3338, 3385

Fixed a regression that was incorrectly fixed in 1.0.0b4
(hence becoming two regressions); reports that
SELECT statements would GROUP BY a label name and fail was misconstrued
that certain backends such as SQL Server should not be emitting
ORDER BY or GROUP BY on a simple label name at all; when in fact,
we had forgotten that 0.9 was already emitting ORDER BY on a simple
label name for all backends, as described in :ref:`migration_1068`,
even though 1.0 includes a rewrite of this logic as part of
:ticket:`2992`.  As far
as emitting GROUP BY against a simple label, even PostgreSQL has
cases where it will raise an error even though the label to group
on should be apparent, so it is clear that GROUP BY should never
be rendered in this way automatically.

In 1.0.2, SQL Server, Firebird and others will again emit ORDER BY on
a simple label name when passed a
:class:`.Label` construct that is also present in the columns clause.
Additionally, no backend will emit GROUP BY against the simple label
name only when passed a :class:`.Label` construct.

.. change::
:tags: bug, orm, declarative
:tickets: 3383

Fixed unexpected use regression regarding the declarative
``__declare_first__`` and ``__declare_last__`` accessors where these
would no longer be called on the superclass of the declarative base.

.. changelog::

1.0.1

:released: April 23, 2015

.. change::
:tags: bug, firebird
:tickets: 3380

Fixed a regression due to :ticket:`3034` where limit/offset
clauses were not properly interpreted by the Firebird dialect.
Pull request courtesy effem-git.

.. change::
:tags: bug, firebird
:tickets: 3381

Fixed support for "literal_binds" mode when using limit/offset
with Firebird, so that the values are again rendered inline when
this is selected.  Related to :ticket:`3034`.

.. change::
:tags: bug, sqlite
:tickets: 3378

Fixed a regression due to :ticket:`3282`, where due to the fact that
we attempt to assume the availability of ALTER when creating/dropping
schemas, in the case of SQLite we simply said to not worry about
foreign keys at all, since ALTER is not available, when creating
and dropping tables.  This meant that the sorting of tables was
basically skipped in the case of SQLite, and for the vast majority
of SQLite use cases, this is not an issue.

However, users who were doing DROPs on SQLite
with tables that contained data and with referential integrity
turned on would then experience errors, as the
dependency sorting *does* matter in the case of DROP with
enforced constraints, when those tables have data (SQLite will still
happily let you create foreign keys to nonexistent tables and drop
tables referring to existing ones with constraints enabled, as long as
there's no data being referenced).

In order to maintain the new feature of :ticket:`3282` while still
allowing a SQLite DROP operation to maintain ordering, we now
do the sort with full FKs taken under consideration, and if we encounter
an unresolvable cycle, only *then* do we forego attempting to sort
the tables; we instead emit a warning and go with the unsorted list.
If an environment needs both ordered DROPs *and* has foreign key
cycles, then the warning notes they will need to restore the
``use_alter`` flag to their :class:`.ForeignKey` and
:class:`.ForeignKeyConstraint` objects so that just those objects will
be omitted from the dependency sort.

.. seealso::

:ref:`feature_3282` - contains an updated note about SQLite.

.. change::
:tags: bug, sql
:tickets: 3372

Fixed issue where a straight SELECT EXISTS query would fail to
assign the proper result type of Boolean to the result mapping, and
instead would leak column types from within the query into the
result map.  This issue exists in 0.9 and earlier as well, however
has less of an impact in those versions.  In 1.0, due to :ticket:`918`
this becomes a regression in that we now rely upon the result mapping
to be very accurate, else we can assign result-type processors to
the wrong column.   In all versions, this issue also has the effect
that a simple EXISTS will not apply the Boolean type handler, leading
to simple 1/0 values for backends without native boolean instead of
True/False.   The fix includes that an EXISTS columns argument
will be anon-labeled like other column expressions; a similar fix is
implemented for pure-boolean expressions like ``not_(True())``.

.. change::
:tags: bug, orm
:tickets: 3374

Fixed issue where a query of the form
``query(B).filter(B.a != A(id=7))`` would render the ``NEVER_SET``
symbol, when
given a transient object. For a persistent object, it would
always use the persisted database value and not the currently
set value.  Assuming autoflush is turned on, this usually would
not be apparent for persistent values, as any pending changes
would be flushed first in any case.  However, this is inconsistent
vs. the logic used for the  non-negated comparison,
``query(B).filter(B.a == A(id=7))``, which does use the
current value and additionally allows comparisons to transient
objects.  The comparison now uses the current value and not
the database-persisted value.

Unlike the other ``NEVER_SET`` issues that are repaired as regressions
caused by :ticket:`3061` in this release, this particular issue is
present at least as far back as 0.8 and possibly earlier, however it
was discovered as a result of repairing the related ``NEVER_SET``
issues.

.. seealso::

:ref:`bug_3374`

.. change::
:tags: bug, orm
:tickets: 3371

Fixed unexpected use regression cause by :ticket:`3061` where
the NEVER_SET
symbol could leak into relationship-oriented queries, including
``filter()`` and ``with_parent()`` queries.  The ``None`` symbol
is returned in all cases, however many of these queries have never
been correctly supported in any case, and produce comparisons
to NULL without using the IS operator.  For this reason, a warning
is also added to that subset of relationship queries that don't
currently provide for ``IS NULL``.

.. seealso::

:ref:`bug_3371`


.. change::
:tags: bug, orm
:tickets: 3368

Fixed a regression caused by :ticket:`3061` where the
NEVER_SET symbol could leak into a lazyload query, subsequent
to the flush of a pending object.  This would occur typically
for a many-to-one relationship that does not use a simple
"get" strategy.   The good news is that the fix improves efficiency
vs. 0.9, because we can now skip the SELECT statement entirely
when we detect NEVER_SET symbols present in the parameters; prior to
:ticket:`3061`, we couldn't discern if the None here were set or not.


.. changelog::

1.0.0

:released: April 16, 2015

.. change::
:tags: bug, orm
:tickets: 3367

Identified an inconsistency when handling :meth:`.Query.join` to the
same target more than once; it implicitly dedupes only in the case of
a relationship join, and due to :ticket:`3233`, in 1.0 a join
to the same table twice behaves differently than 0.9 in that it no
longer erroneously aliases.   To help document this change,
the verbiage regarding :ticket:`3233` in the migration notes has
been generalized, and a warning has been added when :meth:`.Query.join`
is called against the same target relationship more than once.

.. change::
:tags: bug, orm
:tickets: 3364

Made a small improvement to the heuristics of relationship when
determining remote side with semi-self-referential (e.g. two joined
inh subclasses referring to each other), non-simple join conditions
such that the parententity is taken into account and can reduce the
need for using the ``remote()`` annotation; this can restore some
cases that might have worked without the annotation prior to 0.9.4
via :ticket:`2948`.

.. change::
:tags: bug, mssql
:tickets: 3360

Fixed a regression where the "last inserted id" mechanics would
fail to store the correct value for MSSQL on an INSERT where the
primary key value was present in the insert params before execution,
as well as in the case where an INSERT from SELECT would state the
target columns as column objects, instead of string keys.


.. change::
:tags: bug, mssql

Using the ``Binary`` constructor now present in pymssql rather than
patching one in.  Pull request courtesy Ramiro Morales.

.. change::
:tags: bug, tests
:tickets: 3356

Fixed the pathing used when tests run; for sqla_nose.py and py.test,
the "./lib" prefix is again inserted at the head of sys.path but
only if sys.flags.no_user_site isn't set; this makes it act just
like the way Python puts "." in the current path by default.
For tox, we are setting the PYTHONNOUSERSITE flag now.

.. change::
:tags: feature, sql
:tickets: 3084

The topological sorting used to sort :class:`.Table` objects
and available via the :attr:`.MetaData.sorted_tables` collection
will now produce a **deterministic** ordering; that is, the same
ordering each time given a set of tables with particular names
and dependencies.  This is to help with comparison of DDL scripts
and other use cases.  The tables are sent to the topological sort
sorted by name, and the topological sort itself will process
the incoming data in an ordered fashion.  Pull request
courtesy Sebastian Bank.

.. seealso::

:ref:`feature_3084`

.. change::
:tags: feature, orm

Added new argument :paramref:`.Query.update.update_args` which allows
kw arguments such as ``mysql_limit`` to be passed to the underlying
:class:`.Update` construct.  Pull request courtesy Amir Sadoughi.

.. changelog::

1.0.0b5

:released: April 3, 2015

.. change::
:tags: bug, orm
:tickets: 3349

:class:`.Query` doesn't support joins, subselects, or special
FROM clauses when using the :meth:`.Query.update` or
:meth:`.Query.delete` methods; instead of silently ignoring these
fields if methods like :meth:`.Query.join` or
:meth:`.Query.select_from` has been called, an error is raised.
In 0.9.10 this only emits a warning.

.. change::
:tags: bug, orm

Added a list() call around a weak dictionary used within the
commit phase of the session, which without it could cause
a "dictionary changed size during iter" error if garbage collection
interacted within the process.   Change was introduced by
3139.

.. change::
:tags: bug, postgresql
:tickets: 3343

Fixed bug where updated PG index reflection as a result of
:ticket:`3184` would cause index operations to fail on PostgreSQL
versions 8.4 and earlier.  The enhancements are now
disabled when using an older version of PostgreSQL.

.. change::
:tags: bug, sql
:tickets: 3346

The warning emitted by the unicode type for a non-unicode type
has been liberalized to warn for values that aren't even string
values, such as integers; previously, the updated warning system
of 1.0 made use of string formatting operations which
would raise an internal TypeError.   While these cases should ideally
raise totally, some backends like SQLite and MySQL do accept them
and are potentially in use by legacy code, not to mention that they
will always pass through if unicode conversion is turned off
for the target backend.

.. change::
:tags: bug, orm
:tickets: 3347

Fixed a bug related to "nested" inner join eager loading, which
exists in 0.9 as well but is more of a regression in 1.0 due to
:ticket:`3008` which turns on "nested" by default, such that
a joined eager load that travels across sibling paths from a common
ancestor using innerjoin=True will correctly splice each "innerjoin"
sibling into the appropriate part of the join, when a series of
inner/outer joins are mixed together.

.. changelog::

1.0.0b4

:released: March 29, 2015

.. change::
:tags: bug, mssql, oracle, firebird, sybase
:tickets: 3338

Turned off the "simple order by" flag on the MSSQL, Oracle dialects;
this is the flag that per :ticket:`2992` causes an order by or group by
an expression that's also in the columns clause to be copied by
label, even if referenced as the expression object.   The behavior
for MSSQL is now the old behavior that copies the whole expression
in by default, as MSSQL can be picky on these particularly in
GROUP BY expressions.  The flag is also turned off defensively
for the Firebird and Sybase dialects.

.. note:: this resolution was incorrect, please see version 1.0.2
for a rework of this resolution.

.. change::
:tags: feature, schema
:tickets: 3341

The "auto-attach" feature of constraints such as :class:`.UniqueConstraint`
and :class:`.CheckConstraint` has been further enhanced such that
when the constraint is associated with non-table-bound :class:`.Column`
objects, the constraint will set up event listeners with the
columns themselves such that the constraint auto attaches at the
same time the columns are associated with the table.  This in particular
helps in some edge cases in declarative but is also of general use.

.. seealso::

:ref:`change_3341`

.. change::
:tags: bug, sql
:tickets: 3340

Fixed bug in new "label resolution" feature of :ticket:`2992` where
a label that was anonymous, then labeled again with a name, would
fail to be locatable via a textual label.  This situation occurs
naturally when a mapped :func:`.column_property` is given an
explicit label in a query.

.. change::
:tags: bug, sql
:tickets: 3335

Fixed bug in new "label resolution" feature of :ticket:`2992` where
the string label placed in the order_by() or group_by() of a statement
would place higher priority on the name as found
inside the FROM clause instead of a more locally available name
inside the columns clause.

.. changelog::

1.0.0b3

:released: March 20, 2015

.. change::
:tags: bug, mysql
:tickets: 2771

Repaired the commit for issue 2771 which was inadvertently commented
out.


.. changelog::

1.0.0b2

:released: March 20, 2015

.. change::
:tags: bug, mysql
:tickets: 2771

Fixes to fully support using the ``'utf8mb4'`` MySQL-specific charset
with MySQL dialects, in particular MySQL-Python and PyMySQL.   In
addition, MySQL databases that report more unusual charsets such as
'koi8u' or 'eucjpms' will also work correctly.  Pull request
courtesy Thomas Grainger.

.. change::
:tags: change, orm, declarative
:tickets: 3331

Loosened some restrictions that were added to ``declared_attr``
objects, such that they were prevented from being called outside
of the declarative process; this is related to the enhancements
of 3150 which allow ``declared_attr`` to return a value that is
cached based on the current class as it's being configured.
The exception raise has been removed, and the behavior changed
so that outside of the declarative process, the function decorated by
``declared_attr`` is called every time just like a regular
``property``, without using any caching, as none is available
at this stage.

.. change::
:tags: bug, engine
:tickets: 3330, 3329

The "auto close" for :class:`.ResultProxy` is now a "soft" close.
That is, after exhausting all rows using the fetch methods, the
DBAPI cursor is released as before and the object may be safely
discarded, but the fetch methods may continue to be called for which
they will return an end-of-result object (None for fetchone, empty list
for fetchmany and fetchall).   Only if :meth:`.ResultProxy.close`
is called explicitly will these methods raise the "result is closed"
error.

.. seealso::

:ref:`change_3330`

.. change::
:tags: bug, orm
:tickets: 3327

Fixed unexpected use regression from pullreq github:137 where
Py2K unicode literals (e.g. ``u""``) would not be accepted by the
:paramref:`.relationship.cascade` option.
Pull request courtesy Julien Castets.


.. changelog::

1.0.0b1

:released: March 13, 2015

Version 1.0.0b1 is the first release of the 1.0 series.   Many changes
described here are also present in the 0.9 and sometimes the 0.8
series as well.  For changes that are specific to 1.0 with an emphasis
on compatibility concerns, see :doc:`/changelog/migration_10`.

.. change::
:tags: feature, ext
:tickets: 3054

Added a new extension suite :mod:`sqlalchemy.ext.baked`.  This
simple but unusual system allows for a dramatic savings in Python
overhead for the construction and processing of orm :class:`.Query`
objects, from query construction up through rendering of a string
SQL statement.

.. seealso::

:ref:`baked_toplevel`

.. change::
:tags: bug, postgresql
:tickets: 3319

The PostgreSQL :class:`.postgresql.ENUM` type will emit a
DROP TYPE instruction when a plain ``table.drop()`` is called,
assuming the object is not associated directly with a
:class:`.MetaData` object.   In order to accommodate the use case of
an enumerated type shared between multiple tables, the type should
be associated directly with the :class:`.MetaData` object; in this
case the type will only be created at the metadata level, or if
created directly.  The rules for create/drop of
PostgreSQL enumerated types have been highly reworked in general.

.. seealso::

:ref:`change_3319`

.. change::
:tags: feature, orm
:tickets: 3317

Added a new event suite :class:`.QueryEvents`.  The
:meth:`.QueryEvents.before_compile` event allows the creation
of functions which may place additional modifications to
:class:`.Query` objects before the construction of the SELECT
statement.   It is hoped that this event be made much more
useful via the advent of a new inspection system that will
allow for detailed modifications to be made against
:class:`.Query` objects in an automated fashion.

.. seealso::

:class:`.QueryEvents`


.. change::
:tags: feature, orm
:tickets: 3249

The subquery wrapping which occurs when joined eager loading
is used with a one-to-many query that also features LIMIT,
OFFSET, or DISTINCT has been disabled in the case of a one-to-one
relationship, that is a one-to-many with
:paramref:`.relationship.uselist` set to False.  This will produce
more efficient queries in these cases.

.. seealso::

:ref:`change_3249`


.. change::
:tags: bug, orm
:tickets: 3301

Fixed bug where the session attachment error "object is already
attached to session X" would fail to prevent the object from
also being attached to the new session, in the case that execution
continued after the error raise occurred.

.. change::
:tags: bug, orm, declarative
:tickets: 3219, 3240

Fixed bug where using an ``__abstract__`` mixin in the middle
of a declarative inheritance hierarchy would prevent attributes
and configuration being correctly propagated from the base class
to the inheriting class.

.. change::
:tags: feature, sql
:tickets: 918

The SQL compiler now generates the mapping of expected columns
such that they are matched to the received result set positionally,
rather than by name.  Originally, this was seen as a way to handle
cases where we had columns returned with difficult-to-predict names,
though in modern use that issue has been overcome by anonymous
labeling.   In this version, the approach basically reduces function
call count per-result by a few dozen calls, or more for larger
sets of result columns.  The approach still degrades into a modern
version of the old approach if any discrepancy in size exists between
the compiled set of columns versus what was received, so there's no
issue for partially or fully textual compilation scenarios where these
lists might not line up.

.. change::
:tags: feature, postgresql

The PG8000 dialect now supports the
:paramref:`.create_engine.encoding` parameter, by setting up
the client encoding on the connection which is then intercepted
by pg8000.  Pull request courtesy Tony Locke.

.. change::
:tags: feature, postgresql

Added support for PG8000's native JSONB feature.  Pull request
courtesy Tony Locke.

.. change::
:tags: change, orm

Mapped attributes marked as deferred without explicit undeferral
will now remain "deferred" even if their column is otherwise
present in the result set in some way.   This is a performance
enhancement in that an ORM load no longer spends time searching
for each deferred column when the result set is obtained.  However,
for an application that has been relying upon this, an explicit
:func:`.undefer` or similar option should now be used.

.. change::
:tags: feature, orm
:tickets: 3307

Mapped state internals have been reworked to allow for a 50% reduction
in callcounts specific to the "expiration" of objects, as in
the "auto expire" feature of :meth:`.Session.commit` and
for :meth:`.Session.expire_all`, as well as in the "cleanup" step
which occurs when object states are garbage collected.

.. change::
:tags: bug, mysql

The MySQL dialect now supports CAST on types that are constructed
as :class:`.TypeDecorator` objects.

.. change::
:tags: bug, mysql
:tickets: 3237

A warning is emitted when :func:`.cast` is used with the MySQL
dialect on a type where MySQL does not support CAST; MySQL only
supports CAST on a subset of datatypes.   SQLAlchemy has for a long
time just omitted the CAST for unsupported types in the case of
MySQL.  While we don't want to change this now, we emit a warning
to show that it's taken place.   A warning is also emitted when
a CAST is used with an older MySQL version (< 4) that doesn't support
CAST at all, it's skipped in this case as well.

.. change::
:tags: feature, sql
:tickets: 3087

Literal values within a :class:`.DefaultClause`, which is invoked
when using the :paramref:`.Column.server_default` parameter, will
now be rendered using the "inline" compiler, so that they are rendered
as-is, rather than as bound parameters.

.. seealso::

:ref:`change_3087`

.. change::
:tags: feature, oracle

Added support for cx_oracle connections to a specific service
name, as opposed to a tns name, by passing ``?service_name=<name>``
to the URL.  Pull request courtesy Sławomir Ehlert.

.. change::
:tags: feature, mysql
:tickets: 3155

The MySQL dialect now renders TIMESTAMP with NULL / NOT NULL in
all cases, so that MySQL 5.6.6 with the
``explicit_defaults_for_timestamp`` flag enabled will
will allow TIMESTAMP to continue to work as expected when
``nullable=False``.  Existing applications are unaffected as
SQLAlchemy has always emitted NULL for a TIMESTAMP column that
is ``nullable=True``.

.. seealso::

:ref:`change_3155`

:ref:`mysql_timestamp_null`

.. change::
:tags: bug, schema
:tickets: 3299, 3067

The :class:`.CheckConstraint` construct now supports naming
conventions that include the token ``%(column_0_name)s``; the
constraint expression is scanned for columns.  Additionally,
naming conventions for check constraints that don't include the
``%(constraint_name)s`` token will now work for :class:`.SchemaType`-
generated constraints, such as those of :class:`.Boolean` and
:class:`.Enum`; this stopped working in 0.9.7 due to :ticket:`3067`.

.. seealso::

:ref:`naming_check_constraints`

:ref:`naming_schematypes`


.. change::
:tags: feature, postgresql, pypy
:tickets: 3052

Added support for the psycopg2cffi DBAPI on pypy.   Pull request
courtesy shauns.

.. seealso::

:mod:`sqlalchemy.dialects.postgresql.psycopg2cffi`

.. change::
:tags: feature, orm
:tickets: 3262

A warning is emitted when the same polymorphic identity is assigned
to two different mappers in the same hierarchy.  This is typically a
user error and means that the two different mapping types cannot be
correctly distinguished at load time.  Pull request courtesy
Sebastian Bank.

.. change::
:tags: feature, sql

The type of expression is reported when an object passed to a
SQL expression unit can't be interpreted as a SQL fragment;
pull request courtesy Ryan P. Kelly.

.. change::
:tags: bug, orm
:tickets: 3227, 3242, 1326

The primary :class:`.Mapper` of a :class:`.Query` is now passed to the
:meth:`.Session.get_bind` method when calling upon
:meth:`.Query.count`, :meth:`.Query.update`, :meth:`.Query.delete`,
as well as queries against mapped columns,
:obj:`.column_property` objects, and SQL functions and expressions
derived from mapped columns.   This allows sessions that rely upon
either customized :meth:`.Session.get_bind` schemes or "bound" metadata
to work in all relevant cases.

.. seealso::

:ref:`bug_3227`

.. change::
:tags: enhancement, sql
:tickets: 3074

Custom dialects that implement :class:`.GenericTypeCompiler` can
now be constructed such that the visit methods receive an indication
of the owning expression object, if any.  Any visit method that
accepts keyword arguments (e.g. ``**kw``) will in most cases
receive a keyword argument ``type_expression``, referring to the
expression object that the type is contained within.  For columns
in DDL, the dialect's compiler class may need to alter its
``get_column_specification()`` method to support this as well.
The ``UserDefinedType.get_col_spec()`` method will also receive
``type_expression`` if it provides ``**kw`` in its argument
signature.

.. change::
:tags: bug, sql
:tickets: 3288

The multi-values version of :meth:`.Insert.values` has been
repaired to work more usefully with tables that have Python-
side default values and/or functions, as well as server-side
defaults. The feature will now work with a dialect that uses
"positional" parameters; a Python callable will also be
invoked individually for each row just as is the case with an
"executemany" style invocation; a server- side default column
will no longer implicitly receive the value explicitly
specified for the first row, instead refusing to invoke
without an explicit value.

.. seealso::

:ref:`bug_3288`

.. change::
:tags: feature, general

Structural memory use has been improved via much more significant use
of ``__slots__`` for many internal objects.  This optimization is
particularly geared towards the base memory size of large applications
that have lots of tables and columns, and greatly reduces memory
size for a variety of high-volume objects including event listening
internals, comparator objects and parts of the ORM attribute and
loader strategy system.

.. seealso::

:ref:`feature_slots`

.. change::
:tags: bug, mysql
:tickets: 3283

The :class:`.mysql.SET` type has been overhauled to no longer
assume that the empty string, or a set with a single empty string
value, is in fact a set with a single empty string; instead, this
is by default treated as the empty set.  In order to handle persistence
of a :class:`.mysql.SET` that actually wants to include the blank
value ``''`` as a legitimate value, a new bitwise operational mode
is added which is enabled by the
:paramref:`.mysql.SET.retrieve_as_bitwise` flag, which will persist
and retrieve values unambiguously using their bitflag positioning.
Storage and retrieval of unicode values for driver configurations
that aren't converting unicode natively is also repaired.

.. seealso::

:ref:`change_3283`


.. change::
:tags: feature, schema
:tickets: 3282

The DDL generation system of :meth:`.MetaData.create_all`
and :meth:`.MetaData.drop_all` has been enhanced to in most
cases automatically handle the case of mutually dependent
foreign key constraints; the need for the
:paramref:`.ForeignKeyConstraint.use_alter` flag is greatly
reduced.  The system also works for constraints which aren't given
a name up front; only in the case of DROP is a name required for
at least one of the constraints involved in the cycle.

.. seealso::

:ref:`feature_3282`

.. change::
:tags: feature, schema

Added a new accessor :attr:`.Table.foreign_key_constraints`
to complement the :attr:`.Table.foreign_keys` collection,
as well as :attr:`.ForeignKeyConstraint.referred_table`.

.. change::
:tags: bug, sqlite
:tickets: 3244, 3261

UNIQUE and FOREIGN KEY constraints are now fully reflected on
SQLite both with and without names.  Previously, foreign key
names were ignored and unnamed unique constraints were skipped.
Thanks to Jon Nelson for assistance with this.

.. change::
:tags: feature, examples

A new suite of examples dedicated to providing a detailed study
into performance of SQLAlchemy ORM and Core, as well as the DBAPI,
from multiple perspectives.  The suite runs within a container
that provides built in profiling displays both through console
output as well as graphically via the RunSnake tool.

.. seealso::

:ref:`examples_performance`

.. change::
:tags: feature, orm
:tickets: 3100

A new series of :class:`.Session` methods which provide hooks
directly into the unit of work's facility for emitting INSERT
and UPDATE statements has been created.  When used correctly,
this expert-oriented system can allow ORM-mappings to be used
to generate bulk insert and update statements batched into
executemany groups, allowing the statements to proceed at
speeds that rival direct use of the Core.

.. seealso::

:ref:`bulk_operations`

.. change::
:tags: feature, mssql
:tickets: 3039

SQL Server 2012 now recommends VARCHAR(max), NVARCHAR(max),
VARBINARY(max) for large text/binary types.  The MSSQL dialect will
now respect this based on version detection, as well as the new
``deprecate_large_types`` flag.

.. seealso::

:ref:`mssql_large_type_deprecation`

.. change::
:tags: bug, sqlite
:tickets: 3257

The SQLite dialect, when using the :class:`.sqlite.DATE`,
:class:`.sqlite.TIME`,
or :class:`.sqlite.DATETIME` types, and given a ``storage_format`` that
only renders numbers, will render the types in DDL as
``DATE_CHAR``, ``TIME_CHAR``, and ``DATETIME_CHAR``, so that despite the
lack of alpha characters in the values, the column will still
deliver the "text affinity".  Normally this is not needed, as the
textual values within the default storage formats already
imply text.

.. seealso::

:ref:`sqlite_datetime`

.. change::
:tags: bug, engine
:tickets: 3266

The engine-level error handling and wrapping routines will now
take effect in all engine connection use cases, including
when user-custom connect routines are used via the
:paramref:`.create_engine.creator` parameter, as well as when
the :class:`.Connection` encounters a connection error on
revalidation.

.. seealso::

:ref:`change_3266`

.. change::
:tags: feature, oracle

New Oracle DDL features for tables, indexes: COMPRESS, BITMAP.
Patch courtesy Gabor Gombas.

.. change::
:tags: bug, oracle

An alias name will be properly quoted when referred to using the
``%(name)s`` token inside the :meth:`.Select.with_hint` method.
Previously, the Oracle backend hadn't implemented this quoting.

.. change::
:tags: feature, oracle
:tickets: 3220

Added support for CTEs under Oracle.  This includes some tweaks
to the aliasing syntax, as well as a new CTE feature
:meth:`.CTE.suffix_with`, which is useful for adding in special
Oracle-specific directives to the CTE.

.. seealso::

:ref:`change_3220`

.. change::
:tags: feature, mysql
:tickets: 3121

Updated the "supports_unicode_statements" flag to True for MySQLdb
and Pymysql under Python 2.   This refers to the SQL statements
themselves, not the parameters, and affects issues such as table
and column names using non-ASCII characters.   These drivers both
appear to support Python 2 Unicode objects without issue in modern
versions.

.. change::
:tags: bug, mysql
:tickets: 3263

The :meth:`.ColumnOperators.match` operator is now handled such that the
return type is not strictly assumed to be boolean; it now
returns a :class:`.Boolean` subclass called :class:`.MatchType`.
The type will still produce boolean behavior when used in Python
expressions, however the dialect can override its behavior at
result time.  In the case of MySQL, while the MATCH operator
is typically used in a boolean context within an expression,
if one actually queries for the value of a match expression, a
floating point value is returned; this value is not compatible
with SQLAlchemy's C-based boolean processor, so MySQL's result-set
behavior now follows that of the :class:`.Float` type.
A new operator object ``notmatch_op`` is also added to better allow
dialects to define the negation of a match operation.

.. seealso::

:ref:`change_3263`

.. change::
:tags: bug, postgresql
:tickets: 3264

The :meth:`.PGDialect.has_table` method will now query against
``pg_catalog.pg_table_is_visible(c.oid)``, rather than testing
for an exact schema match, when the schema name is None; this
so that the method will also illustrate that temporary tables
are present.  Note that this is a behavioral change, as PostgreSQL
allows a non-temporary table to silently overwrite an existing
temporary table of the same name, so this changes the behavior
of ``checkfirst`` in that unusual scenario.

.. seealso::

:ref:`change_3264`

.. change::
:tags: bug, sql
:tickets: 3260

Fixed bug in :meth:`.Table.tometadata` method where the
:class:`.CheckConstraint` associated with a :class:`.Boolean`
or :class:`.Enum` type object would be doubled in the target table.
The copy process now tracks the production of this constraint object
as local to a type object.

.. change::
:tags: feature, orm
:tickets: 3217

Added a parameter :paramref:`.Query.join.isouter` which is synonymous
with calling :meth:`.Query.outerjoin`; this flag is to provide a more
consistent interface compared to Core :meth:`.FromClause.join`.
Pull request courtesy Jonathan Vanasco.

.. change::
:tags: bug, sql
:tickets: 3243

The behavioral contract of the :attr:`.ForeignKeyConstraint.columns`
collection has been made consistent; this attribute is now a
:class:`.ColumnCollection` like that of all other constraints and
is initialized at the point when the constraint is associated with
a :class:`.Table`.

.. seealso::

:ref:`change_3243`

.. change::
:tags: bug, orm
:tickets: 3256

The :meth:`.PropComparator.of_type` modifier has been
improved in conjunction with loader directives such as
:func:`.joinedload` and :func:`.contains_eager` such that if
two :meth:`.PropComparator.of_type` modifiers of the same
base type/path are encountered, they will be joined together
into a single "polymorphic" entity, rather than replacing
the entity of type A with the one of type B.  E.g.
a joinedload of ``A.b.of_type(BSub1)->BSub1.c`` combined with
joinedload of ``A.b.of_type(BSub2)->BSub2.c`` will create a
single joinedload of ``A.b.of_type((BSub1, BSub2)) -> BSub1.c, BSub2.c``,
without the need for the ``with_polymorphic`` to be explicit
in the query.

.. seealso::

:ref:`eagerloading_polymorphic_subtypes` - contains an updated
example illustrating the new format.

.. change::
:tags: bug, sql
:tickets: 3245

The :attr:`.Column.key` attribute is now used as the source of
anonymous bound parameter names within expressions, to match the
existing use of this value as the key when rendered in an INSERT
or UPDATE statement.   This allows :attr:`.Column.key` to be used
as a "substitute" string to work around a difficult column name
that doesn't translate well into a bound parameter name.   Note that
the paramstyle is configurable on :func:`.create_engine` in any case,
and most DBAPIs today support a named and positional style.

.. change::
:tags: bug, sql

Fixed the name of the :paramref:`.PoolEvents.reset.dbapi_connection`
parameter as passed to this event; in particular this affects
usage of the "named" argument style for this event.  Pull request
courtesy Jason Goldberger.

.. change::
:tags: feature, sql

Added a new parameter :paramref:`.Table.tometadata.name` to
the :meth:`.Table.tometadata` method.  Similar to
:paramref:`.Table.tometadata.schema`, this argument causes the newly
copied :class:`.Table` to take on the new name instead of
the existing one.  An interesting capability this adds is that of
copying a :class:`.Table` object to the *same* :class:`.MetaData`
target with a new name.  Pull request courtesy n.d. parker.

.. change::
:tags: bug, orm

Repaired support of the ``copy.deepcopy()`` call when used by the
:class:`.orm.util.CascadeOptions` argument, which occurs
if ``copy.deepcopy()`` is being used with :func:`.relationship`
(not an officially supported use case).  Pull request courtesy
duesenfranz.

.. change::
:tags: bug, sql
:tickets: 3170

Reversing a change that was made in 0.9, the "singleton" nature
of the "constants" :func:`.null`, :func:`.true`, and :func:`.false`
has been reverted.   These functions returning a "singleton" object
had the effect that different instances would be treated as the
same regardless of lexical use, which in particular would impact
the rendering of the columns clause of a SELECT statement.

.. seealso::

:ref:`bug_3170`

.. change::
:tags: bug, orm
:tickets: 3139

Fixed bug where :meth:`.Session.expunge` would not fully detach
the given object if the object had been subject to a delete
operation that was flushed, but not committed.  This would also
affect related operations like :func:`.make_transient`.

.. seealso::

:ref:`bug_3139`

.. change::
:tags: bug, orm
:tickets: 3230

A warning is emitted in the case of multiple relationships that
ultimately will populate a foreign key column in conflict with
another, where the relationships are attempting to copy values
from different source columns.  This occurs in the case where
composite foreign keys with overlapping columns are mapped to
relationships that each refer to a different referenced column.
A new documentation section illustrates the example as well as how
to overcome the issue by specifying "foreign" columns specifically
on a per-relationship basis.

.. seealso::

:ref:`relationship_overlapping_foreignkeys`

.. change::
:tags: feature, sql
:tickets: 3172

Exception messages have been spiffed up a bit.  The SQL statement
and parameters are not displayed if None, reducing confusion for
error messages that weren't related to a statement.  The full
module and classname for the DBAPI-level exception is displayed,
making it clear that this is a wrapped DBAPI exception.  The
statement and parameters themselves are bounded within a bracketed
sections to better isolate them from the error message and from
each other.

.. change::
:tags: bug, orm
:tickets: 3228

The :meth:`.Query.update` method will now convert string key
names in the given dictionary of values into mapped attribute names
against the mapped class being updated.  Previously, string names
were taken in directly and passed to the core update statement without
any means to resolve against the mapped entity.  Support for synonyms
and hybrid attributes as the subject attributes of
:meth:`.Query.update` are also supported.

.. seealso::

:ref:`bug_3228`

.. change::
:tags: bug, orm
:tickets: 3035

Improvements to the mechanism used by :class:`.Session` to locate
"binds" (e.g. engines to use), such engines can be associated with
mixin classes, concrete subclasses, as well as a wider variety
of table metadata such as joined inheritance tables.

.. seealso::

:ref:`bug_3035`

.. change::
:tags: bug, general
:tickets: 3218

The ``__module__`` attribute is now set for all those SQL and
ORM functions that are derived as "public factory" symbols, which
should assist with documentation tools being able to report on the
target module.

.. change::
:tags: feature, sql

:meth:`.Insert.from_select` now includes Python and SQL-expression
defaults if otherwise unspecified; the limitation where non-
server column defaults aren't included in an INSERT FROM
SELECT is now lifted and these expressions are rendered as
constants into the SELECT statement.

.. seealso::

:ref:`feature_insert_from_select_defaults`

.. change::
:tags: bug, orm
:tickets: 3233

Fixed bug in single table inheritance where a chain of joins
that included the same single inh entity more than once
(normally this should raise an error) could, in some cases
depending on what was being joined "from", implicitly alias the
second case of the single inh entity, producing
a query that "worked".   But as this implicit aliasing is not
intended in the case of single table inheritance, it didn't
really "work" fully and was very misleading, since it wouldn't
always appear.

.. seealso::

:ref:`bug_3233`


.. change::
:tags: bug, orm
:tickets: 3222

The ON clause rendered when using :meth:`.Query.join`,
:meth:`.Query.outerjoin`, or the standalone :func:`.orm.join` /
:func:`.orm.outerjoin` functions to a single-inheritance subclass will
now include the "single table criteria" in the ON clause even
if the ON clause is otherwise hand-rolled; it is now added to the
criteria using AND, the same way as if joining to a single-table
target using relationship or similar.

This is sort of in-between feature and bug.

.. seealso::

:ref:`migration_3222`

.. change::
:tags: feature, sql
:tickets: 3184

The :class:`.UniqueConstraint` construct is now included when
reflecting a :class:`.Table` object, for databases where this
is applicable.  In order to achieve this
with sufficient accuracy, MySQL and PostgreSQL now contain features
that correct for the duplication of indexes and unique constraints
when reflecting tables, indexes, and constraints.
In the case of MySQL, there is not actually a "unique constraint"
concept independent of a "unique index", so for this backend
:class:`.UniqueConstraint` continues to remain non-present for a
reflected :class:`.Table`.  For PostgreSQL, the query used to
detect indexes against ``pg_index`` has been improved to check for
the same construct in ``pg_constraint``, and the implicitly
constructed unique index is not included with a
reflected :class:`.Table`.

In both cases, the  :meth:`.Inspector.get_indexes` and the
:meth:`.Inspector.get_unique_constraints` methods return both
constructs individually, but include a new token
``duplicates_constraint`` in the case of PostgreSQL or
``duplicates_index`` in the case
of MySQL to indicate when this condition is detected.
Pull request courtesy Johannes Erdfelt.

.. seealso::

:ref:`feature_3184`

.. change::
:tags: feature, postgresql

Added support for the FILTER keyword as applied to aggregate
functions, supported by PostgreSQL 9.4.   Pull request
courtesy Ilja Everilä.

.. seealso::

:ref:`feature_gh134`

.. change::
:tags: bug, sql, engine
:tickets: 3215

Fixed bug where a "branched" connection, that is the kind you get
when you call :meth:`.Connection.connect`, would not share invalidation
status with the parent.  The architecture of branching has been tweaked
a bit so that the branched connection defers to the parent for
all invalidation status and operations.

.. change::
:tags: bug, sql, engine
:tickets: 3190

Fixed bug where a "branched" connection, that is the kind you get
when you call :meth:`.Connection.connect`, would not share transaction
status with the parent.  The architecture of branching has been tweaked
a bit so that the branched connection defers to the parent for
all transactional status and operations.

.. change::
:tags: bug, orm, declarative
:tickets: 2670

A relationship set up with :class:`.declared_attr` on
a :class:`.AbstractConcreteBase` base class will now be configured
on the abstract base mapping automatically, in addition to being
set up on descendant concrete classes as usual.

.. seealso::

:ref:`feature_3150`

.. change::
:tags: feature, orm, declarative
:tickets: 3150

The :class:`.declared_attr` construct has newly improved
behaviors and features in conjunction with declarative.  The
decorated function will now have access to the final column
copies present on the local mixin when invoked, and will also
be invoked exactly once for each mapped class, the returned result
being memoized.   A new modifier :attr:`.declared_attr.cascading`
is added as well.

.. seealso::

:ref:`feature_3150`

.. change::
:tags: feature, ext
:tickets: 3210

The :mod:`sqlalchemy.ext.automap` extension will now set
``cascade="all, delete-orphan"`` automatically on a one-to-many
relationship/backref where the foreign key is detected as containing
one or more non-nullable columns.  This argument is present in the
keywords passed to :func:`.automap.generate_relationship` in this
case and can still be overridden.  Additionally, if the
:class:`.ForeignKeyConstraint` specifies ``ondelete="CASCADE"``
for a non-nullable or ``ondelete="SET NULL"`` for a nullable set
of columns, the argument ``passive_deletes=True`` is also added to the
relationship.  Note that not all backends support reflection of
ondelete, but backends that do include PostgreSQL and MySQL.

.. change::
:tags: feature, sql
:tickets: 3206

Added new method :meth:`.Select.with_statement_hint` and ORM
method :meth:`.Query.with_statement_hint` to support statement-level
hints that are not specific to a table.

.. change::
:tags: bug, sqlite
:tickets: 3203

SQLite now supports reflection of unique constraints from
temp tables; previously, this would fail with a TypeError.
Pull request courtesy Johannes Erdfelt.

.. seealso::

:ref:`change_3204` - changes regarding SQLite temporary
table and view reflection.

.. change::
:tags: bug, sqlite
:tickets: 3204

Added :meth:`.Inspector.get_temp_table_names` and
:meth:`.Inspector.get_temp_view_names`; currently, only the
SQLite and Oracle dialects support these methods.  The return of
temporary table and view names has been **removed** from SQLite and
Oracle's version of :meth:`.Inspector.get_table_names` and
:meth:`.Inspector.get_view_names`; other database backends cannot
support this information (such as MySQL), and the scope of operation
is different in that the tables can be local to a session and
typically aren't supported in remote schemas.

.. seealso::

:ref:`change_3204`

.. change::
:tags: feature, postgresql
:tickets: 2891

Support has been added for reflection of materialized views
and foreign tables, as well as support for materialized views
within :meth:`.Inspector.get_view_names`, and a new method
:meth:`.PGInspector.get_foreign_table_names` available on the
PostgreSQL version of :class:`.Inspector`.  Pull request courtesy
Rodrigo Menezes.

.. seealso::

:ref:`feature_2891`


.. change::
:tags: feature, orm

Added new event handlers :meth:`.AttributeEvents.init_collection`
and :meth:`.AttributeEvents.dispose_collection`, which track when
a collection is first associated with an instance and when it is
replaced.  These handlers supersede the :meth:`.collection.linker`
annotation. The old hook remains supported through an event adapter.

.. change::
:tags: bug, orm
:tickets: 3148, 3188

A major rework to the behavior of expression labels, most
specifically when used with ColumnProperty constructs with
custom SQL expressions and in conjunction with the "order by
labels" logic first introduced in 0.9.  Fixes include that an
``order_by(Entity.some_col_prop)`` will now make use of "order by
label" rules even if Entity has been subject to aliasing,
either via inheritance rendering or via the use of the
``aliased()`` construct; rendering of the same column property
multiple times with aliasing (e.g. ``query(Entity.some_prop,
entity_alias.some_prop)``) will label each occurrence of the
entity with a distinct label, and additionally "order by
label" rules will work for both (e.g.
``order_by(Entity.some_prop, entity_alias.some_prop)``).
Additional issues that could prevent the "order by label"
logic from working in 0.9, most notably that the state of a
Label could change such that "order by label" would stop
working depending on how things were called, has been fixed.

.. seealso::

:ref:`bug_3188`


.. change::
:tags: bug, mysql
:tickets: 3186

MySQL boolean symbols "true", "false" work again.  0.9's change
in :ticket:`2682` disallowed the MySQL dialect from making use of the
"true" and "false" symbols in the context of "IS" / "IS NOT", but
MySQL supports this syntax even though it has no boolean type.
MySQL remains "non native boolean", but the :func:`.true`
and :func:`.false` symbols again produce the
keywords "true" and "false", so that an expression like
``column.is_(true())`` again works on MySQL.

.. seealso::

:ref:`bug_3186`

.. change::
:tags: changed, mssql
:tickets: 3182

The hostname-based connection format for SQL Server when using
pyodbc will no longer specify a default "driver name", and a warning
is emitted if this is missing.  The optimal driver name for SQL Server
changes frequently and is per-platform, so hostname based connections
need to specify this.  DSN-based connections are preferred.

.. seealso::

:ref:`change_3182`

.. change::
:tags: changed, sql

The :func:`~.expression.column` and :func:`~.expression.table`
constructs are now importable from the "from sqlalchemy" namespace,
just like every other Core construct.

.. change::
:tags: changed, sql
:tickets: 2992

The implicit conversion of strings to :func:`.text` constructs
when passed to most builder methods of :func:`.select` as
well as :class:`.Query` now emits a warning with just the
plain string sent.   The textual conversion still proceeds normally,
however.  The only method that accepts a string without a warning
are the "label reference" methods like order_by(), group_by();
these functions will now at compile time attempt to resolve a single
string argument to a column or label expression present in the
selectable; if none is located, the expression still renders, but
you get the warning again. The rationale here is that the implicit
conversion from string to text is more unexpected than not these days,
and it is better that the user send more direction to the Core / ORM
when passing a raw string as to what direction should be taken.
Core/ORM tutorials have been updated to go more in depth as to how text
is handled.

.. seealso::

:ref:`migration_2992`


.. change::
:tags: feature, engine
:tickets: 3178

A new style of warning can be emitted which will "filter" up to
N occurrences of a parameterized string.   This allows parameterized
warnings that can refer to their arguments to be delivered a fixed
number of times until allowing Python warning filters to squelch them,
and prevents memory from growing unbounded within Python's
warning registries.

.. seealso::

:ref:`feature_3178`

.. change::
:tags: feature, orm

The :class:`.Query` will raise an exception when :meth:`.Query.yield_per`
is used with mappings or options where either
subquery eager loading, or joined eager loading with collections,
would take place.  These loading strategies are
not currently compatible with yield_per, so by raising this error,
the method is safer to use.  Eager loads can be disabled with
the ``lazyload('*')`` option or :meth:`.Query.enable_eagerloads`.

.. seealso::

:ref:`migration_yield_per_eager_loading`

.. change::
:tags: bug, orm
:tickets: 3177

Changed the approach by which the "single inheritance criterion"
is applied, when using :meth:`.Query.from_self`, or its common
user :meth:`.Query.count`.  The criteria to limit rows to those
with a certain type is now indicated on the inside subquery,
not the outside one, so that even if the "type" column is not
available in the columns clause, we can filter on it on the "inner"
query.

.. seealso::

:ref:`migration_3177`

.. change::
:tags: changed, orm

The ``proc()`` callable passed to the ``create_row_processor()``
method of custom :class:`.Bundle` classes now accepts only a single
"row" argument.

.. seealso::

:ref:`bundle_api_change`

.. change::
:tags: changed, orm

Deprecated event hooks removed:  ``populate_instance``,
``create_instance``, ``translate_row``, ``append_result``

.. seealso::

:ref:`migration_deprecated_orm_events`

.. change::
:tags: bug, orm
:tickets: 3145

Made a small adjustment to the mechanics of lazy loading,
such that it has less chance of interfering with a joinload() in the
very rare circumstance that an object points to itself; in this
scenario, the object refers to itself while loading its attributes
which can cause a mixup between loaders.   The use case of
"object points to itself" is not fully supported, but the fix also
removes some overhead so for now is part of testing.

.. change::
:tags: feature, orm
:tickets: 3176

A new implementation for :class:`.KeyedTuple` used by the
:class:`.Query` object offers dramatic speed improvements when
fetching large numbers of column-oriented rows.

.. seealso::

:ref:`feature_3176`

.. change::
:tags: feature, orm
:tickets: 3008

The behavior of :paramref:`.joinedload.innerjoin` as well as
:paramref:`.relationship.innerjoin` is now to use "nested"
inner joins, that is, right-nested, as the default behavior when an
inner join joined eager load is chained to an outer join eager load.

.. seealso::

:ref:`migration_3008`

.. change::
:tags: bug, orm
:tickets: 3171

The "resurrect" ORM event has been removed.  This event hook had
no purpose since the old "mutable attribute" system was removed
in 0.8.

.. change::
:tags: bug, sql
:tickets: 3169

Using :meth:`.Insert.from_select`  now implies ``inline=True``
on :func:`.insert`.  This helps to fix a bug where an
INSERT...FROM SELECT construct would inadvertently be compiled
as "implicit returning" on supporting backends, which would
cause breakage in the case of an INSERT that inserts zero rows
(as implicit returning expects a row), as well as arbitrary
return data in the case of an INSERT that inserts multiple
rows (e.g. only the first row of many).
A similar change is also applied to an INSERT..VALUES
with multiple parameter sets; implicit RETURNING will no longer emit
for this statement either.  As both of these constructs deal
with variable numbers of rows, the
:attr:`.ResultProxy.inserted_primary_key` accessor does not
apply.   Previously, there was a documentation note that one
may prefer ``inline=True`` with INSERT..FROM SELECT as some databases
don't support returning and therefore can't do "implicit" returning,
but there's no reason an INSERT...FROM SELECT needs implicit returning
in any case.   Regular explicit :meth:`.Insert.returning` should
be used to return variable numbers of result rows if inserted
data is needed.

.. change::
:tags: bug, orm
:tickets: 3167

Fixed bug where attribute "set" events or columns with
``validates`` would have events triggered within the flush process,
when those columns were the targets of a "fetch and populate"
operation, such as an autoincremented primary key, a Python side
default, or a server-side default "eagerly" fetched via RETURNING.

.. change::
:tags: feature, oracle

Added support for the Oracle table option ON COMMIT.

.. change::
:tags: feature, postgresql
:tickets: 2051

Added support for PG table options TABLESPACE, ON COMMIT,
WITH(OUT) OIDS, and INHERITS, when rendering DDL via
the :class:`.Table` construct.   Pull request courtesy
malikdiarra.

.. seealso::

:ref:`postgresql_table_options`

.. change::
:tags: bug, orm, py3k

The :class:`.IdentityMap` exposed from :attr:`.Session.identity_map`
now returns lists for ``items()`` and ``values()`` in Py3K.
Early porting to Py3K here had these returning iterators, when
they technically should be "iterable views"..for now, lists are OK.

.. change::
:tags: orm, feature

UPDATE statements can now be batched within an ORM flush
into more performant executemany() call, similarly to how INSERT
statements can be batched; this will be invoked within flush
to the degree that subsequent UPDATE statements for the
same mapping and table involve the identical columns within the
VALUES clause, that no SET-level SQL expressions
are embedded, and that the versioning requirements for the mapping
are compatible with the backend dialect's ability to return
a correct rowcount for an executemany operation.

.. change::
:tags: engine, bug
:tickets: 3163

Removing (or adding) an event listener at the same time that the event
is being run itself, either from inside the listener or from a
concurrent thread, now raises a RuntimeError, as the collection used is
now an instance of ``colletions.deque()`` and does not support changes
while being iterated.  Previously, a plain Python list was used where
removal from inside the event itself would produce silent failures.

.. change::
:tags: orm, feature
:tickets: 2963

The ``info`` parameter has been added to the constructor for
:class:`.SynonymProperty` and :class:`.ComparableProperty`.

.. change::
:tags: sql, feature
:tickets: 2963

The ``info`` parameter has been added as a constructor argument
to all schema constructs including :class:`.MetaData`,
:class:`.Index`, :class:`.ForeignKey`, :class:`.ForeignKeyConstraint`,
:class:`.UniqueConstraint`, :class:`.PrimaryKeyConstraint`,
:class:`.CheckConstraint`.

.. change::
:tags: orm, feature
:tickets: 2971

The :attr:`.InspectionAttr.info` collection is now moved down to
:class:`.InspectionAttr`, where in addition to being available
on all :class:`.MapperProperty` objects, it is also now available
on hybrid properties, association proxies, when accessed via
:attr:`.Mapper.all_orm_descriptors`.

.. change::
:tags: sql, feature
:tickets: 3027

The :paramref:`.Table.autoload_with` flag now implies that
:paramref:`.Table.autoload` should be ``True``.  Pull request
courtesy Malik Diarra.

.. change::
:tags: postgresql, feature

Added new method :meth:`.PGInspector.get_enums`, when using the
inspector for PostgreSQL will provide a list of ENUM types.
Pull request courtesy Ilya Pekelny.

.. change::
:tags: mysql, bug

The MySQL dialect will now disable :meth:`.ConnectionEvents.handle_error`
events from firing for those statements which it uses internally
to detect if a table exists or not.   This is achieved using an
execution option ``skip_user_error_events`` that disables the handle
error event for the scope of that execution.   In this way, user code
that rewrites exceptions doesn't need to worry about the MySQL
dialect or other dialects that occasionally need to catch
SQLAlchemy specific exceptions.

.. change::
:tags: mysql, bug
:tickets: 2515

Changed the default value of "raise_on_warnings" to False for
MySQLconnector.  This was set at True for some reason.  The "buffered"
flag unfortunately must stay at True as MySQLconnector does not allow
a cursor to be closed unless all results are fully fetched.

.. change::
:tags: bug, orm
:tickets: 3117

The "evaluator" for query.update()/delete() won't work with multi-table
updates, and needs to be set to `synchronize_session=False` or
`synchronize_session='fetch'`; this now raises an exception, with a
message to change the synchronize setting.
This is upgraded from a warning emitted as of 0.9.7.

.. change::
:tags: removed

The Drizzle dialect has been removed from the Core; it is now
available as `sqlalchemy-drizzle <https://bitbucket.org/zzzeek/sqlalchemy-drizzle>`_,
an independent, third party dialect.  The dialect is still based
almost entirely off of the MySQL dialect present in SQLAlchemy.

.. seealso::

:ref:`change_2984`

.. change::
:tags: enhancement, orm
:tickets: 3061

Adjustment to attribute mechanics concerning when a value is
implicitly initialized to None via first access; this action,
which has always resulted in a population of the attribute,
no longer does so; the None value is returned but the underlying
attribute receives no set event.  This is consistent with how collections
work and allows attribute mechanics to behave more consistently;
in particular, getting an attribute with no value does not squash
the event that should proceed if the value is actually set to None.

.. seealso::

:ref:`migration_3061`

.. change::
:tags: feature, sql
:tickets: 3034

The :meth:`.Select.limit` and :meth:`.Select.offset` methods
now accept any SQL expression, in addition to integer values, as
arguments.  Typically this is used to allow a bound parameter to be
passed, which can be substituted with a value later thus allowing
Python-side caching of the SQL query.   The implementation
here is fully backwards compatible with existing third party dialects,
however those dialects which implement special LIMIT/OFFSET systems
will need modification in order to take advantage of the new
capabilities.  Limit and offset also support "literal_binds" mode,
where bound parameters are rendered inline as strings based on
a compile-time option.
Work on this feature is courtesy of Dobes Vandermeer.


.. seealso::

:ref:`feature_3034`.


=============
1.1 Changelog
=============

.. changelog_imports::

.. include:: changelog_10.rst
:start-line: 5

.. include:: changelog_09.rst
:start-line: 5

.. include:: changelog_08.rst
:start-line: 5

.. include:: changelog_07.rst
:start-line: 5


.. changelog::
:version: 1.1.19
:include_notes_from: unreleased_11

.. changelog::

0.9.10

:released: July 22, 2015

.. change::
:tags: bug, sqlite
:tickets: 3495
:versions: 1.0.8

Fixed bug in SQLite dialect where reflection of UNIQUE constraints
that included non-alphabetic characters in the names, like dots or
spaces, would not be reflected with their name.

.. change::
:tags: feature, sql
:tickets: 3418
:versions: 1.0.5

Added official support for a CTE used by the SELECT present
inside of :meth:`.Insert.from_select`.  This behavior worked
accidentally up until 0.9.9, when it no longer worked due to
unrelated changes as part of :ticket:`3248`.   Note that this
is the rendering of the WITH clause after the INSERT, before the
SELECT; the full functionality of CTEs rendered at the top
level of INSERT, UPDATE, DELETE is a new feature targeted for a
later release.

.. change::
:tags: bug, ext
:tickets: 3408
:versions: 1.0.4

Fixed bug where when using extended attribute instrumentation system,
the correct exception would not be raised when :func:`.class_mapper`
were called with an invalid input that also happened to not
be weak referencable, such as an integer.

.. change::
:tags: bug, tests, pypy
:tickets: 3406
:versions: 1.0.4

Fixed an import that prevented "pypy setup.py test" from working
correctly.

.. change::
:tags: bug, engine
:tickets: 3375
:versions: 1.0.1

Added the string value ``"none"`` to those accepted by the
:paramref:`.Pool.reset_on_return` parameter as a synonym for ``None``,
so that string values can be used for all settings, allowing
utilities like :func:`.engine_from_config` to be usable without
issue.

.. change::
:tags: bug, sql
:tickets: 3362
:versions: 1.0.0

Fixed issue where a :class:`.MetaData` object that used a naming
convention would not properly work with pickle.  The attribute was
skipped leading to inconsistencies and failures if the unpickled
:class:`.MetaData` object were used to base additional tables
from.

.. change::
:tags: bug, postgresql
:tickets: 3354
:versions: 1.0.0

Fixed a long-standing bug where the :class:`.Enum` type as used
with the psycopg2 dialect in conjunction with non-ascii values
and ``native_enum=False`` would fail to decode return results properly.
This stemmed from when the PG :class:`.postgresql.ENUM` type used
to be a standalone type without a "non native" option.

.. change::
:tags: bug, orm
:tickets: 3349

:class:`.Query` doesn't support joins, subselects, or special
FROM clauses when using the :meth:`.Query.update` or
:meth:`.Query.delete` methods; instead of silently ignoring these
fields if methods like :meth:`.Query.join` or
:meth:`.Query.select_from` has been called, a warning is emitted.
As of 1.0.0b5 this will raise an error.

.. change::
:tags: bug, orm
:tickets: 3352
:versions: 1.0.0b5

Fixed bug where the state tracking within multiple, nested
:meth:`.Session.begin_nested` operations would fail to propagate
the "dirty" flag for an object that had been updated within
the inner savepoint, such that if the enclosing savepoint were
rolled back, the object would not be part of the state that was
expired and therefore reverted to its database state.

.. change::
:tags: bug, mysql, pymysql
:tickets: 3337
:versions: 1.0.0b4

Fixed unicode support for PyMySQL when using an "executemany"
operation with unicode parameters.  SQLAlchemy now passes both
the statement as well as the bound parameters as unicode
objects, as PyMySQL generally uses string interpolation
internally to produce the final statement, and in the case of
executemany does the "encode" step only on the final statement.

.. change::
:tags: bug, py3k, mysql
:tickets: 3333
:versions: 1.0.0b2

Fixed the :class:`.mysql.BIT` type on Py3K which was not using the
``ord()`` function correctly.  Pull request courtesy David Marin.

.. change::
:tags: bug, ext
:tickets: 3324

Fixed regression from 0.9.9 where the :func:`.as_declarative`
symbol was removed from the ``sqlalchemy.ext.declarative``
namespace.

.. change::
:tags: feature, orm
:tickets: 3320
:versions: 1.0.0b1

Added a new entry ``"entity"`` to the dictionaries returned by
:attr:`.Query.column_descriptions`.  This refers to the primary ORM
mapped class or aliased class that is referred to by the expression.
Compared to the existing entry for ``"type"``, it will always be
a mapped entity, even if extracted from a column expression, or
None if the given expression is a pure core expression.
See also :ticket:`3403` which repaired a regression in this feature
which was unreleased in 0.9.10 but was released in the 1.0 version.


.. changelog::

0.9.9

:released: March 10, 2015

.. change::
:tags: feature, postgresql
:versions: 1.0.0b1

Added support for the ``CONCURRENTLY`` keyword with PostgreSQL
indexes, established using ``postgresql_concurrently``.  Pull
request courtesy Iuri de Silvio.

.. seealso::

:ref:`postgresql_index_concurrently`

.. change::
:tags: bug, ext, py3k
:versions: 1.0.0b1

Fixed bug where the association proxy list class would not interpret
slices correctly under Py3K.  Pull request courtesy
Gilles Dartiguelongue.

.. change::
:tags: feature, sqlite
:versions: 1.0.0b1

Added support for partial indexes (e.g. with a WHERE clause) on
SQLite.  Pull request courtesy Kai Groner.

.. seealso::

:ref:`sqlite_partial_index`

.. change::
:tags: bug, orm
:tickets: 3310
:versions: 1.0.0b1

Fixed bugs in ORM object comparisons where comparison of
many-to-one ``!= None`` would fail if the source were an aliased
class, or if the query needed to apply special aliasing to the
expression due to aliased joins or polymorphic querying; also fixed
bug in the case where comparing a many-to-one to an object state
would fail if the query needed to apply special aliasing
due to aliased joins or polymorphic querying.

.. change::
:tags: bug, orm
:tickets: 3309
:versions: 1.0.0b1

Fixed bug where internal assertion would fail in the case where
an ``after_rollback()`` handler for a :class:`.Session` incorrectly
adds state to that :class:`.Session` within the handler, and the task
to warn and remove this state (established by :ticket:`2389`) attempts
to proceed.

.. change::
:tags: bug, orm
:versions: 1.0.0b1

Fixed bug where TypeError raised when :meth:`.Query.join` called
with unknown kw arguments would raise its own TypeError due
to broken formatting.  Pull request courtesy Malthe Borch.

.. change::
:tags: bug, engine
:tickets: 3302
:versions: 1.0.0b1

Fixed bug in :class:`.Connection` and pool where the
:meth:`.Connection.invalidate` method, or an invalidation due
to a database disconnect, would fail if the
``isolation_level`` parameter had been used with
:meth:`.Connection.execution_options`; the "finalizer" that resets
the isolation level would be called on the no longer opened connection.

.. change::
:tags: feature, orm
:tickets: 3296
:versions: 1.0.0b1

Added new parameter :paramref:`.Session.connection.execution_options`
which may be used to set up execution options on a :class:`.Connection`
when it is first checked out, before the transaction has begun.
This is used to set up options such as isolation level on the
connection before the transaction starts.

.. seealso::

:ref:`session_transaction_isolation` - new documentation section
detailing best practices for setting transaction isolation with
sessions.

.. change::
:tags: bug, engine
:tickets: 3296
:versions: 1.0.0b1

A warning is emitted if the ``isolation_level`` parameter is used
with :meth:`.Connection.execution_options` when a :class:`.Transaction`
is in play; DBAPIs and/or SQLAlchemy dialects such as psycopg2,
MySQLdb may implicitly rollback or commit the transaction, or
not change the setting til next transaction, so this is never safe.

.. change::
:tags: bug, orm
:tickets: 3300
:versions: 1.0.0b1

Fixed bug in lazy loading SQL construction whereby a complex
primaryjoin that referred to the same "local" column multiple
times in the "column that points to itself" style of self-referential
join would not be substituted in all cases.   The logic to determine
substitutions here has been reworked to be more open-ended.

.. change::
:tags: bug, postgresql
:tickets: 2940
:versions: 1.0.0b1

Repaired support for PostgreSQL UUID types in conjunction with
the ARRAY type when using psycopg2.  The psycopg2 dialect now
employs use of the psycopg2.extras.register_uuid() hook
so that UUID values are always passed to/from the DBAPI as
UUID() objects.   The :paramref:`.UUID.as_uuid` flag is still
honored, except with psycopg2 we need to convert returned
UUID objects back into strings when this is disabled.

.. change::
:tags: bug, postgresql
:versions: 1.0.0b1

Added support for the :class:`postgresql.JSONB` datatype when
using psycopg2 2.5.4 or greater, which features native conversion
of JSONB data so that SQLAlchemy's converters must be disabled;
additionally, the newly added psycopg2 extension
``extras.register_default_jsonb`` is used to establish a JSON
deserializer passed to the dialect via the ``json_deserializer``
argument.  Also repaired the PostgreSQL integration tests which
weren't actually round-tripping the JSONB type as opposed to the
JSON type.  Pull request courtesy Mateusz Susik.

.. change::
:tags: bug, postgresql
:versions: 1.0.0b1

Repaired the use of the "array_oid" flag when registering the
HSTORE type with older psycopg2 versions < 2.4.3, which does not
support this flag, as well as use of the native json serializer
hook "register_default_json" with user-defined ``json_deserializer``
on psycopg2 versions < 2.5, which does not include native json.

.. change::
:tags: bug, schema
:tickets: 3298, 1765

Fixed bug in 0.9's foreign key setup system, such that
the logic used to link a :class:`.ForeignKey` to its parent could fail
when the foreign key used "link_to_name=True" in conjunction with
a target :class:`.Table` that would not receive its parent column until
later, such as within a reflection + "useexisting" scenario,
if the target column in fact had a key value different from its name,
as would occur in reflection if column reflect events were used to
alter the .key of reflected :class:`.Column` objects so that the
link_to_name becomes significant.  Also repaired support for column
type via FK transmission in a similar way when target columns had a
different key and were referenced using link_to_name.

.. change::
:tags: feature, engine
:versions: 1.0.0b1

Added new user-space accessors for viewing transaction isolation
levels; :meth:`.Connection.get_isolation_level`,
:attr:`.Connection.default_isolation_level`.

.. change::
:tags: bug, postgresql
:versions: 1.0.0b1
:tickets: 3174

Fixed bug where PostgreSQL dialect would fail to render an
expression in an :class:`.Index` that did not correspond directly
to a table-bound column; typically when a :func:`.text` construct
was one of the expressions within the index; or could misinterpret the
list of expressions if one or more of them were such an expression.

.. change::
:tags: bug, orm
:versions: 1.0.0b1
:tickets: 3287

The "wildcard" loader options, in particular the one set up by
the :func:`.orm.load_only` option to cover all attributes not
explicitly mentioned, now takes into account the superclasses
of a given entity, if that entity is mapped with inheritance mapping,
so that attribute names within the superclasses are also omitted
from the load.  Additionally, the polymorphic discriminator column
is unconditionally included in the list, just in the same way that
primary key columns are, so that even with load_only() set up,
polymorphic loading of subtypes continues to function correctly.

.. change::
:tags: bug, sql
:versions: 1.0.0b1

Added the ``native_enum`` flag to the ``__repr__()`` output
of :class:`.Enum`, which is mostly important when using it with
Alembic autogenerate.  Pull request courtesy Dimitris Theodorou.

.. change::
:tags: bug, orm, pypy
:versions: 1.0.0b1
:tickets: 3285

Fixed bug where if an exception were thrown at the start of a
:class:`.Query` before it fetched results, particularly when
row processors can't be formed, the cursor would stay open with
results pending and not actually be closed.  This is typically only
an issue on an interpreter like PyPy where the cursor isn't
immediately GC'ed, and can in some circumstances lead to transactions/
locks being open longer than is desirable.

.. change::
:tags: change, mysql
:versions: 1.0.0b1
:tickets: 3275

The ``gaerdbms`` dialect is no longer necessary, and emits a
deprecation warning.  Google now recommends using the MySQLdb
dialect directly.

.. change::
:tags: bug, sql
:versions: 1.0.0b1
:tickets: 3278

Fixed bug where using a :class:`.TypeDecorator` that implemented
a type that was also a :class:`.TypeDecorator` would fail with
Python's "Cannot create a consistent method resolution order (MRO)"
error, when any kind of SQL comparison expression were used against
an object using this type.

.. change::
:tags: bug, mysql
:versions: 1.0.0b1
:tickets: 3274

Added a version check to the MySQLdb dialect surrounding the
check for 'utf8_bin' collation, as this fails on MySQL server < 5.0.

.. change::
:tags: feature, orm
:versions: 1.0.0b1

Added new method :meth:`.Session.invalidate`, functions similarly
to :meth:`.Session.close`, except also calls
:meth:`.Connection.invalidate`
on all connections, guaranteeing that they will not be returned to
the connection pool.  This is useful in situations e.g. dealing
with gevent timeouts when it is not safe to use the connection further,
even for rollbacks.

.. change::
:tags: bug, examples
:versions: 1.0.0b1

Updated the :ref:`examples_versioned_history` example such that
mapped columns are re-mapped to
match column names as well as grouping of columns; in particular,
this allows columns that are explicitly grouped in a same-column-named
joined inheritance scenario to be mapped in the same way in the
history mappings, avoiding warnings added in the 0.9 series
regarding this pattern and allowing the same view of attribute
keys.

.. change::
:tags: bug, examples
:versions: 1.0.0b1

Fixed a bug in the examples/generic_associations/discriminator_on_association.py
example, where the subclasses of AddressAssociation were not being
mapped as "single table inheritance", leading to problems when trying
to use the mappings further.

.. change::
:tags: bug, orm
:versions: 1.0.0b1
:tickets: 3251

Fixed a leak which would occur in the unsupported and highly
non-recommended use case of replacing a relationship on a fixed
mapped class many times, referring to an arbitrarily growing number of
target mappers.  A warning is emitted when the old relationship is
replaced, however if the mapping were already used for querying, the
old relationship would still be referenced within some registries.

.. change::
:tags: bug, sql
:versions: 1.0.0b1
:tickets: 3248

Fixed issue where the columns from a SELECT embedded in an
INSERT, either through the values clause or as a "from select",
would pollute the column types used in the result set produced by
the RETURNING clause when columns from both statements shared the
same name, leading to potential errors or mis-adaptation when
retrieving the returning rows.

.. change::
:tags: bug, orm, sqlite
:versions: 1.0.0b1
:tickets: 3241

Fixed bug regarding expression mutations which could express
itself as a "Could not locate column" error when using
:class:`.Query` to  select from multiple, anonymous column
entities when querying against SQLite, as a side effect of the
"join rewriting" feature used by the SQLite dialect.

.. change::
:tags: feature, sqlite
:versions: 1.0.0b1

Added a new SQLite backend for the SQLCipher backend.  This backend
provides for encrypted SQLite databases using the pysqlcipher Python
driver, which is very similar to the pysqlite driver.

.. seealso::

:mod:`~sqlalchemy.dialects.sqlite.pysqlcipher`

.. change::
:tags: bug, orm
:tickets: 3232
:versions: 1.0.0b1

Fixed bug where the ON clause for :meth:`.Query.join`,
and :meth:`.Query.outerjoin` to a single-inheritance subclass
using ``of_type()`` would not render the "single table criteria" in
the ON clause if the ``from_joinpoint=True`` flag were set.

.. changelog::

0.9.8

:released: October 13, 2014

.. change::
:tags: bug, mysql, mysqlconnector
:versions: 1.0.0b1

Mysqlconnector as of version 2.0, probably as a side effect of
the  python 3 merge, now does not expect percent signs (e.g.
as used as the modulus operator and others) to be doubled,
even when using the "pyformat" bound parameter format (this
change is not documented by Mysqlconnector).  The dialect now
checks for py2k and for mysqlconnector less than version 2.0
when detecting if the modulus operator should be rendered as
``%%`` or ``%``.

.. change::
:tags: bug, mysql, mysqlconnector
:versions: 1.0.0b1

Unicode SQL is now passed for MySQLconnector version 2.0 and above;
for Py2k and MySQL < 2.0, strings are encoded.


.. change::
:tags: bug, oracle
:versions: 1.0.0b1
:tickets: 2138

Fixed long-standing bug in Oracle dialect where bound parameter
names that started with numbers would not be quoted, as Oracle
doesn't like numerics in bound parameter names.

.. change::
:tags: bug, sql
:versions: 1.0.0b1
:tickets: 3195

Fixed bug where a fair number of SQL elements within
the sql package would fail to ``__repr__()`` successfully,
due to a missing ``description`` attribute that would then invoke
a recursion overflow when an internal AttributeError would then
re-invoke ``__repr__()``.

.. change::
:tags: bug, declarative, orm
:versions: 1.0.0b1
:tickets: 3185

Fixed "'NoneType' object has no attribute 'concrete'" error
when using :class:`.AbstractConcreteBase` in conjunction with
a subclass that declares ``__abstract__``.

.. change::
:tags: bug, engine
:versions: 1.0.0b1
:tickets: 3200

The execution options passed to an :class:`.Engine` either via
:paramref:`.create_engine.execution_options` or
:meth:`.Engine.update_execution_options` are not passed to the
special :class:`.Connection` used to initialize the dialect
within the "first connect" event; dialects will usually
perform their own queries in this phase, and none of the
current available  options should be applied here.  In
particular, the "autocommit" option was causing an attempt to
autocommit within this initial connect which would fail with
an AttributeError due to the non-standard state of the
:class:`.Connection`.

.. change::
:tags: bug, sqlite
:versions: 1.0.0b1
:tickets: 3211

When selecting from a UNION using an attached database file,
the pysqlite driver reports column names in cursor.description
as 'dbname.tablename.colname', instead of 'tablename.colname' as
it normally does for a UNION (note that it's supposed to just be
'colname' for both, but we work around it).  The column translation
logic here has been adjusted to retrieve the rightmost token, rather
than the second token, so it works in both cases.   Workaround
courtesy Tony Roberts.

.. change::
:tags: bug, postgresql
:versions: 1.0.0b1
:tickets: 3021

A revisit to this issue first patched in 0.9.5, apparently
psycopg2's ``.closed`` accessor is not as reliable as we assumed,
so we have added an explicit check for the exception messages
"SSL SYSCALL error: Bad file descriptor" and
"SSL SYSCALL error: EOF detected" when detecting an
is-disconnect scenario.   We will continue to consult psycopg2's
connection.closed as a first check.

.. change::
:tags: bug, orm, engine
:versions: 1.0.0b1
:tickets: 3197

Fixed bug that affected generally the same classes of event
as that of :ticket:`3199`, when the ``named=True`` parameter
would be used.  Some events would fail to register, and others
would not invoke the event arguments correctly, generally in the
case of when an event was "wrapped" for adaption in some other way.
The "named" mechanics have been rearranged to not interfere with
the argument signature expected by internal wrapper functions.

.. change::
:tags: bug, declarative
:versions: 1.0.0b1
:tickets: 3208

Fixed an unlikely race condition observed in some exotic end-user
setups, where the attempt to check for "duplicate class name" in
declarative would hit upon a not-totally-cleaned-up weak reference
related to some other class being removed; the check here now ensures
the weakref still references an object before calling upon it further.

.. change::
:tags: bug, orm
:versions: 1.0.0b1
:tickets: 3199

Fixed bug that affected many classes of event, particularly
ORM events but also engine events, where the usual logic of
"de duplicating" a redundant call to :func:`.event.listen`
with the same arguments would fail, for those events where the
listener function is wrapped.  An assertion would be hit within
registry.py.  This assertion has now been integrated into the
deduplication check, with the added bonus of a simpler means
of checking deduplication across the board.

.. change::
:tags: bug, mssql
:versions: 1.0.0b1
:tickets: 3151

Fixed the version string detection in the pymssql dialect to
work with Microsoft SQL Azure, which changes the word "SQL Server"
to "SQL Azure".

.. change::
:tags: bug, orm
:versions: 1.0.0b1
:tickets: 3194

Fixed warning that would emit when a complex self-referential
primaryjoin contained functions, while at the same time remote_side
was specified; the warning would suggest setting "remote side".
It now only emits if remote_side isn't present.

.. change::
:tags: bug, ext
:versions: 1.0.0b1
:tickets: 3191

Fixed bug in ordering list where the order of items would be
thrown off during a collection replace event, if the
reorder_on_append flag were set to True.  The fix ensures that the
ordering list only impacts the list that is explicitly associated
with the object.

.. change::
:tags: bug, sql
:versions: 1.0.0b1
:tickets: 3180

An adjustment to table/index reflection such that if an index
reports a column that isn't found to be present in the table,
a warning is emitted and the column is skipped.  This can occur
for some special system column situations as has been observed
with Oracle.

.. change::
:tags: bug, ext
:versions: 1.0.0b1

Fixed bug where :class:`.ext.mutable.MutableDict`
failed to implement the ``update()`` dictionary method, thus
not catching changes. Pull request courtesy Matt Chisholm.

.. change::
:tags: bug, ext
:versions: 1.0.0b1

Fixed bug where a custom subclass of :class:`.ext.mutable.MutableDict`
would not show up in a "coerce" operation, and would instead
return a plain :class:`.ext.mutable.MutableDict`.  Pull request
courtesy Matt Chisholm.

.. change::
:tags: bug, pool
:versions: 1.0.0b1
:tickets: 3168

Fixed bug in connection pool logging where the "connection checked out"
debug logging message would not emit if the logging were set up using
``logging.setLevel()``, rather than using the ``echo_pool`` flag.
Tests to assert this logging have been added.  This is a
regression that was introduced in 0.9.0.

.. change::
:tags: feature, postgresql, pg8000
:versions: 1.0.0b1

Support is added for "sane multi row count" with the pg8000 driver,
which applies mostly to when using versioning with the ORM.
The feature is version-detected based on pg8000 1.9.14 or greater
in use.  Pull request courtesy Tony Locke.

.. change::
:tags: bug, engine
:versions: 1.0.0b1
:tickets: 3165

The string keys that are used to determine the columns impacted
for an INSERT or UPDATE are now sorted when they contribute towards
the "compiled cache" cache key.   These keys were previously not
deterministically ordered, meaning the same statement could be
cached multiple times on equivalent keys, costing both in terms of
memory as well as performance.

.. change::
:tags: bug, postgresql
:versions: 1.0.0b1
:tickets: 3159

Fixed bug where PostgreSQL JSON type was not able to persist or
otherwise render a SQL NULL column value, rather than a JSON-encoded
``'null'``.  To support this case, changes are as follows:

* The value :func:`.null` can now be specified, which will always
result in a NULL value resulting in the statement.

* A new parameter :paramref:`.JSON.none_as_null` is added, which
when True indicates that the Python ``None`` value should be
persisted as SQL NULL, rather than JSON-encoded ``'null'``.

Retrival of NULL as None is also repaired for DBAPIs other than
psycopg2, namely pg8000.

.. change::
:tags: bug, sql
:versions: 1.0.0b1
:tickets: 3154

Fixed bug in CTE where ``literal_binds`` compiler argument would not
be always be correctly propagated when one CTE referred to another
aliased CTE in a statement.

.. change::
:tags: bug, postgresql
:versions: 1.0.0b1
:tickets: 3075

The exception wrapping system for DBAPI errors can now accommodate
non-standard DBAPI exceptions, such as the psycopg2
TransactionRollbackError.  These exceptions will now be raised
using the closest available subclass in ``sqlalchemy.exc``, in the
case of TransactionRollbackError, ``sqlalchemy.exc.OperationalError``.

.. change::
:tags: bug, sql
:versions: 1.0.0b1
:tickets: 3144, 3067

Fixed 0.9.7 regression caused by :ticket:`3067` in conjunction with
a mis-named unit test such that so-called "schema" types like
:class:`.Boolean` and :class:`.Enum` could no longer be pickled.

.. change::
:tags: bug, postgresql
:versions: 1.0.0b1
:tickets: 3141

Fixed bug in :class:`.postgresql.array` object where comparison
to a plain Python list would fail to use the correct array constructor.
Pull request courtesy Andrew.

.. change::
:tags: bug, postgresql
:versions: 1.0.0b1
:tickets: 3137

Added a supported :meth:`.FunctionElement.alias` method to functions,
e.g. the ``func`` construct.  Previously, behavior for this method
was undefined.  The current behavior mimics that of pre-0.9.4,
which is that the function is turned into a single-column FROM
clause with the given alias name, where the column itself is
anonymously named.

.. changelog::

0.9.7

:released: July 22, 2014

.. change::
:tags: bug, postgresql, pg8000
:tickets: 3134
:versions: 1.0.0b1

Fixed bug introduced in 0.9.5 by new pg8000 isolation level feature
where engine-level isolation level parameter would raise an error
on connect.

.. change::
:tags: bug, oracle, tests
:tickets: 3128
:versions: 1.0.0b1

Fixed bug in oracle dialect test suite where in one test,
'username' was assumed to be in the database URL, even though
this might not be the case.

.. change::
:tags: bug, orm, eagerloading
:tickets: 3131
:versions: 1.0.0b1

Fixed a regression caused by :ticket:`2976` released in 0.9.4 where
the "outer join" propagation along a chain of joined eager loads
would incorrectly convert an "inner join" along a sibling join path
into an outer join as well, when only descendant paths should be
receiving the "outer join" propagation; additionally, fixed related
issue where "nested" join propagation would take place inappropriately
between two sibling join paths.

.. change::
:tags: bug, sqlite
:tickets: 3130
:versions: 1.0.0b1

Fixed a SQLite join rewriting issue where a subquery that is embedded
as a scalar subquery such as within an IN would receive inappropriate
substitutions from the enclosing query, if the same table were present
inside the subquery as were in the enclosing query such as in a
joined inheritance scenario.

.. change::
:tags: bug, sql
:tickets: 3067
:versions: 1.0.0b1

Fix bug in naming convention feature where using a check
constraint convention that includes ``constraint_name`` would
then force all :class:`.Boolean` and :class:`.Enum` types to
require names as well, as these implicitly create a
constraint, even if the ultimate target backend were one that does
not require generation of the constraint such as PostgreSQL.
The mechanics of naming conventions for these particular
constraints has been reorganized such that the naming
determination is done at DDL compile time, rather than at
constraint/table construction time.

.. change::
:tags: bug, mssql
:tickets: 3025

Fixed a regression from 0.9.5 caused by :ticket:`3025` where the
query used to determine "default schema" is invalid in SQL Server 2000.
For SQL Server 2000 we go back to defaulting to the "schema name"
parameter of the dialect, which is configurable but defaults
to 'dbo'.

.. change::
:tags: bug, orm
:tickets: 3083, 2736
:versions: 1.0.0b1

Fixed a regression from 0.9.0 due to :ticket:`2736` where the
:meth:`.Query.select_from` method no longer set up the "from
entity" of the :class:`.Query` object correctly, so that
subsequent :meth:`.Query.filter_by` or :meth:`.Query.join`
calls would fail to check the appropriate "from" entity when
searching for attributes by string name.

.. change::
:tags: bug, sql
:tickets: 3090
:versions: 1.0.0b1

Fixed bug in common table expressions whereby positional bound
parameters could be expressed in the wrong final order
when CTEs were nested in certain ways.

.. change::
:tags: bug, sql
:tickets: 3069
:versions: 1.0.0b1

Fixed bug where multi-valued :class:`.Insert` construct would fail
to check subsequent values entries beyond the first one given
for literal SQL expressions.

.. change::
:tags: bug, sql
:tickets: 3123
:versions: 1.0.0b1

Added a "str()" step to the dialect_kwargs iteration for
Python version < 2.6.5, working around the
"no unicode keyword arg" bug as these args are passed along as
keyword args within some reflection processes.

.. change::
:tags: bug, sql
:tickets: 3122
:versions: 1.0.0b1

The :meth:`.TypeEngine.with_variant` method will now accept a
type class as an argument which is internally converted to an
instance, using the same convention long established by other
constructs such as :class:`.Column`.

.. change::
:tags: bug, orm
:tickets: 3117

The "evaluator" for query.update()/delete() won't work with multi-table
updates, and needs to be set to `synchronize_session=False` or
`synchronize_session='fetch'`; a warning is now emitted.  In
1.0 this will be promoted to a full exception.

.. change::
:tags: bug, tests
:versions: 1.0.0b1

Fixed bug where "python setup.py test" wasn't calling into
distutils appropriately, and errors would be emitted at the end
of the test suite.

.. change::
:tags: feature, postgresql
:versions: 1.0.0b1
:tickets: 3078

Added kw argument ``postgresql_regconfig`` to the
:meth:`.ColumnOperators.match` operator, allows the "reg config" argument
to be specified to the ``to_tsquery()`` function emitted.
Pull request courtesy Jonathan Vanasco.

.. change::
:tags: feature, postgresql
:versions: 1.0.0b1

Added support for PostgreSQL JSONB via :class:`.JSONB`.  Pull request
courtesy Damian Dimmich.

.. change::
:tags: feature, mssql
:versions: 1.0.0b1

Enabled "multivalues insert" for SQL Server 2008.  Pull request
courtesy Albert Cervin.  Also expanded the checks for "IDENTITY INSERT"
mode to include when the identity key is present in the
VALUEs clause of the statement.

.. change::
:tags: feature, engine
:tickets: 3076
:versions: 1.0.0b1

Added new event :meth:`.ConnectionEvents.handle_error`, a more
fully featured and comprehensive replacement for
:meth:`.ConnectionEvents.dbapi_error`.

.. change::
:tags: bug, orm
:tickets: 3108
:versions: 1.0.0b1

Fixed bug where items that were persisted, deleted, or had a
primary key change within a savepoint block would not
participate in being restored to their former state (not in
session, in session, previous PK) after the outer transaction
were rolled back.

.. change::
:tags: bug, orm
:tickets: 3106
:versions: 1.0.0b1

Fixed bug in subquery eager loading in conjunction with
:func:`.with_polymorphic`, the targeting of entities and columns
in the subquery load has been made more accurate with respect
to this type of entity and others.

.. change::
:tags: bug, orm
:tickets: 3099

Fixed bug involving dynamic attributes, that was again a regression
of :ticket:`3060` from version 0.9.5.  A self-referential relationship
with lazy='dynamic' would raise a TypeError within a flush operation.

.. change::
:tags: bug, declarative
:tickets: 3097
:versions: 1.0.0b1

Fixed bug when the declarative ``__abstract__`` flag was not being
distinguished for when it was actually the value ``False``.
The ``__abstract__`` flag needs to actually evaluate to a True
value at the level being tested.

.. changelog::

0.9.6

:released: June 23, 2014

.. change::
:tags: bug, orm
:tickets: 3060

Reverted the change for :ticket:`3060` - this is a unit of work
fix that is updated more comprehensively in 1.0 via :ticket:`3061`.
The fix in :ticket:`3060` unfortunately produces a new issue whereby
an eager load of a many-to-one attribute can produce an event
that is interpreted into an attribute change.

.. changelog::

0.9.5

:released: June 23, 2014

.. change::
:tags: bug, orm
:tickets: 3042
:versions: 1.0.0b1

Additional checks have been added for the case where an inheriting
mapper is implicitly combining one of its column-based attributes
with that of the parent, where those columns normally don't necessarily
share the same value.  This is an extension of an existing check that
was added via :ticket:`1892`; however this new check emits only a
warning, instead of an exception, to allow for applications that may
be relying upon the existing behavior.

.. seealso::

:ref:`faq_combining_columns`

.. change::
:tags: bug, sql
:tickets: 3023
:versions: 1.0.0b1

The :paramref:`.Column.nullable` flag is implicitly set to ``False``
when that :class:`.Column` is referred to in an explicit
:class:`.PrimaryKeyConstraint` for that table.  This behavior now
matches that of when the :class:`.Column` itself has the
:paramref:`.Column.primary_key` flag set to ``True``, which is
intended to be an exactly equivalent case.

.. change::
:tags: enhancement, postgresql
:tickets: 3002
:versions: 1.0.0b1

Added a new type :class:`.postgresql.OID` to the PostgreSQL dialect.
While "oid" is generally a private type within PG that is not exposed
in modern versions, there are some PG use cases such as large object
support where these types might be exposed, as well as within some
user-reported schema reflection use cases.

.. change::
:tags: bug, orm
:tickets: 3080
:versions: 1.0.0b1

Modified the behavior of :func:`.orm.load_only` such that primary key
columns are always added to the list of columns to be "undeferred";
otherwise, the ORM can't load the row's identity.   Apparently,
one can defer the mapped primary keys and the ORM will fail, that
hasn't been changed.  But as load_only is essentially saying
"defer all but X", it's more critical that PK cols not be part of this
deferral.

.. change::
:tags: feature, examples
:versions: 1.0.0b1

Added a new example illustrating materialized paths, using the
latest relationship features.   Example courtesy Jack Zhou.

.. change::
:tags: bug, testsuite
:versions: 1.0.0b1

In public test suite, changed to use of ``String(40)`` from
less-supported ``Text`` in ``StringTest.test_literal_backslashes``.
Pullreq courtesy Jan.

.. change::
:tags: bug, engine
:versions: 1.0.0b1
:tickets: 3063

Fixed bug which would occur if a DBAPI exception
occurs when the engine first connects and does its initial checks,
and the exception is not a disconnect exception, yet the cursor
raises an error when we try to close it.  In this case the real
exception would be quashed as we tried to log the cursor close
exception via the connection pool and failed, as we were trying
to access the pool's logger in a way that is inappropriate
in this very specific scenario.

.. change::
:tags: feature, postgresql
:versions: 1.0.0b1

Added support for AUTOCOMMIT isolation level when using the pg8000
DBAPI.  Pull request courtesy Tony Locke.

.. change::
:tags: bug, postgresql
:tickets: 3021
:versions: 1.0.0b1

The psycopg2 ``.closed`` accessor is now consulted when determining
if an exception is a "disconnect" error; ideally, this should remove
the need for any other inspection of the exception message to detect
disconnect, however we will leave those existing messages in place
as a fallback.   This should be able to handle newer cases like
"SSL EOF" conditions.  Pull request courtesy Dirk Mueller.

.. change::
:tags: bug, orm
:tickets: 3060
:versions: 1.0.0b1

Fixed a few edge cases which arise in the so-called "row switch"
scenario, where an INSERT/DELETE can be turned into an UPDATE.
In this situation, a many-to-one relationship set to None, or
in some cases a scalar attribute set to None, may not be detected
as a net change in value, and therefore the UPDATE would not reset
what was on the previous row.   This is due to some as-yet
unresolved side effects of the way attribute history works in terms
of implicitly assuming None isn't really a "change" for a previously
un-set attribute.  See also :ticket:`3061`.

.. note::

This change has been **REVERTED** in 0.9.6.   The full fix
will be in version 1.0 of SQLAlchemy.


.. change::
:tags: bug, orm
:versions: 1.0.0b1

Related to :ticket:`3060`, an adjustment has been made to the unit
of work such that loading for related many-to-one objects is slightly
more aggressive, in the case of a graph of self-referential objects
that are to be deleted; the load of related objects is to help
determine the correct order for deletion if passive_deletes is
not set.

.. change::
:tags: bug, orm
:tickets: 3057
:versions: 1.0.0b1

Fixed bug in SQLite join rewriting where anonymized column names
due to repeats would not correctly be rewritten in subqueries.
This would affect SELECT queries with any kind of subquery + join.

.. change::
:tags: bug, sql
:tickets: 3012
:versions: 1.0.0b1

Fixed bug where the :meth:`.Operators.__and__`,
:meth:`.Operators.__or__` and :meth:`.Operators.__invert__`
operator overload methods could not be overridden within a custom
:class:`.TypeEngine.Comparator` implementation.

.. change::
:tags: feature, postgresql
:tickets: 2785
:versions: 1.0.0b1

Added a new flag :paramref:`.ARRAY.zero_indexes` to the PostgreSQL
:class:`.ARRAY` type.  When set to ``True``, a value of one will be
added to all array index values before passing to the database, allowing
better interoperability between Python style zero-based indexes and
PostgreSQL one-based indexes.  Pull request courtesy Alexey Terentev.

.. change::
:tags: bug, engine
:tickets: 3043
:versions: 1.0.0b1

Fixed some "double invalidate" situations were detected where
a connection invalidation could occur within an already critical section
like a connection.close(); ultimately, these conditions are caused
by the change in :ticket:`2907`, in that the "reset on return" feature
calls out to the Connection/Transaction in order to handle it, where
"disconnect detection" might be caught.  However, it's possible that
the more recent change in :ticket:`2985` made it more likely for this
to be seen as the "connection invalidate" operation is much quicker,
as the issue is more reproducible on 0.9.4 than 0.9.3.

Checks are now added within any section that
an invalidate might occur to halt further disallowed operations
on the invalidated connection.  This includes two fixes both at the
engine level and at the pool level.   While the issue was observed
with highly concurrent gevent cases, it could in theory occur in
any kind of scenario where a disconnect occurs within the connection
close operation.

.. change::
:tags: feature, orm
:tickets: 3029
:versions: 1.0.0b1

The "primaryjoin" model has been stretched a bit further to allow
a join condition that is strictly from a single column to itself,
translated through some kind of SQL function or expression.  This
is kind of experimental, but the first proof of concept is a
"materialized path" join condition where a path string is compared
to itself using "like".   The :meth:`.ColumnOperators.like` operator has
also been added to the list of valid operators to use in a primaryjoin
condition.

.. change::
:tags: feature, sql
:tickets: 3028
:versions: 1.0.0b1

Liberalized the contract for :class:`.Index` a bit in that you can
specify a :func:`.text` expression as the target; the index no longer
needs to have a table-bound column present if the index is to be
manually added to the table, either via inline declaration or via
:meth:`.Table.append_constraint`.

.. change::
:tags: bug, firebird
:tickets: 3038

Fixed bug where the combination of "limit" rendering as
"SELECT FIRST n ROWS" using a bound parameter (only firebird has both),
combined with column-level subqueries
which also feature "limit" as well as "positional" bound parameters
(e.g. qmark style) would erroneously assign the subquery-level positions
before that of the enclosing SELECT, thus returning parameters which
are out of order.

.. change::
:tags: bug, mssql
:tickets: 3025
:versions: 1.0.0b1

Revised the query used to determine the current default schema name
to use the ``database_principal_id()`` function in conjunction with
the ``sys.database_principals`` view so that we can determine
the default schema independently of the type of login in progress
(e.g., SQL Server, Windows, etc).

.. change::
:tags: bug, sql
:tickets: 3024
:versions: 1.0.0b1

Fixed bug in new :meth:`.DialectKWArgs.argument_for` method where
adding an argument for a construct not previously included for any
special arguments would fail.

.. change::
:tags: bug, py3k, tests
:tickets: 2830
:versions: 1.0.0b1

Corrected for some deprecation warnings involving the ``imp``
module and Python 3.3 or greater, when running tests.  Pull
request courtesy Matt Chisholm.

.. change::
:tags: bug, sql
:tickets: 3020, 1068
:versions: 1.0.0b1

Fixed regression introduced in 0.9 where new "ORDER BY <labelname>"
feature from :ticket:`1068` would not apply quoting rules to the
label name as rendered in the ORDER BY.

.. change::
:tags: feature, orm
:tickets: 3017
:versions: 1.0.0b1

Added new utility function :func:`.make_transient_to_detached` which can
be used to manufacture objects that behave as though they were loaded
from a session, then detached.   Attributes that aren't present
are marked as expired, and the object can be added to a Session
where it will act like a persistent one.

.. change::
:tags: bug, sql
:versions: 1.0.0b1

Restored the import for :class:`.Function` to the ``sqlalchemy.sql.expression``
import namespace, which was removed at the beginning of 0.9.

.. change::
:tags: bug, orm, sql
:tickets: 3013
:versions: 1.0.0b1

Fixes to the newly enhanced boolean coercion in :ticket:`2804` where
the new rules for "where" and "having" woudn't take effect for the
"whereclause" and "having" kw arguments of the :func:`.select` construct,
which is also what :class:`.Query` uses so wasn't working in the
ORM either.

.. change::
:tags: feature, sql
:tickets: 2990
:versions: 1.0.0b1

Added new flag :paramref:`.expression.between.symmetric`, when set to True
renders "BETWEEN SYMMETRIC".  Also added a new negation operator
"notbetween_op", which now allows an expression like ``~col.between(x, y)``
to render as "col NOT BETWEEN x AND y", rather than a parenthesized NOT
string.

.. changelog::

0.9.4

:released: March 28, 2014

.. change::
:tags: feature, orm
:tickets: 3007

Added new parameter :paramref:`.orm.mapper.confirm_deleted_rows`.  Defaults
to True, indicates that a series of DELETE statements should confirm
that the cursor rowcount matches the number of primary keys that should
have matched;  this behavior had been taken off in most cases
(except when version_id is used) to support the unusual edge case of
self-referential ON DELETE CASCADE; to accommodate this, the message
is now just a warning, not an exception, and the flag can be used
to indicate a mapping that expects self-referential cascaded
deletes of this nature.  See also :ticket:`2403` for background on the
original change.

.. change::
:tags: bug, ext, automap
:tickets: 3004

Added support to automap for the case where a relationship should
not be created between two classes that are in a joined inheritance
relationship, for those foreign keys that link the subclass back to
the superclass.

.. change::
:tags: bug, orm
:tickets: 2948

Fixed a very old behavior where the lazy load emitted for a one-to-many
could inappropriately pull in the parent table, and also return results
inconsistent based on what's in the parent table, when the primaryjoin
includes some kind of discriminator against the parent table, such
as ``and_(parent.id == child.parent_id, parent.deleted == False)``.
While this primaryjoin doesn't make that much sense for a one-to-many,
it is slightly more common when applied to the many-to-one side, and
the one-to-many comes as a result of a backref.
Loading rows from ``child`` in this case would keep ``parent.deleted == False``
as is within the query, thereby yanking it into the FROM clause
and doing a cartesian product.  The new behavior will now substitute
the value of the local "parent.deleted" for that parameter as is
appropriate.   Though typically, a real-world app probably wants to use a
different primaryjoin for the o2m side in any case.

.. change::
:tags: bug, orm
:tickets: 2965

Improved the check for "how to join from A to B" such that when
a table has multiple, composite foreign keys targeting a parent table,
the :paramref:`.relationship.foreign_keys` argument will be properly
interpreted in order to resolve the ambiguity; previously this condition
would raise that there were multiple FK paths when in fact the
foreign_keys argument should be establishing which one is expected.

.. change::
:tags: bug, mysql

Tweaked the settings for mysql-connector-python; in Py2K, the
"supports unicode statements" flag is now False, so that SQLAlchemy
will encode the *SQL string* (note: *not* the parameters)
to bytes before sending to the database.  This seems to allow
all unicode-related tests to pass for mysql-connector, including those
that use non-ascii table/column names, as well as some tests for the
TEXT type using unicode under cursor.executemany().

.. change::
:tags: feature, engine

Added some new event mechanics for dialect-level events; the initial
implementation allows an event handler to redefine the specific mechanics
by which an arbitrary dialect invokes execute() or executemany() on a
DBAPI cursor.  The new events, at this point semi-public and experimental,
are in support of some upcoming transaction-related extensions.

.. change::
:tags: feature, engine
:tickets: 2978

An event listener can now be associated with a :class:`.Engine`,
after one or more :class:`.Connection` objects have been created
(such as by an orm :class:`.Session` or via explicit connect)
and the listener will pick up events from those connections.
Previously, performance concerns pushed the event transfer from
:class:`.Engine` to  :class:`.Connection` at init-time only, but
we've inlined a bunch of conditional checks to make this possible
without any additional function calls.

.. change::
:tags: bug, tests
:tickets: 2980

Fixed a few errant ``u''`` strings that would prevent tests from passing
in Py3.2.  Patch courtesy Arfrever Frehtes Taifersar Arahesis.

.. change::
:tags: bug, engine
:tickets: 2985

A major improvement made to the mechanics by which the :class:`.Engine`
recycles the connection pool when a "disconnect" condition is detected;
instead of discarding the pool and explicitly closing out connections,
the pool is retained and a "generational" timestamp is updated to
reflect the current time, thereby causing all existing connections
to be recycled when they are next checked out.   This greatly simplifies
the recycle process, removes the need for "waking up" connect attempts
waiting on the old pool and eliminates the race condition that many
immediately-discarded "pool" objects could be created during the
recycle operation.

.. change::
:tags: bug, oracle
:tickets: 2987

Added new datatype :class:`.oracle.DATE`, which is a subclass of
:class:`.DateTime`.  As Oracle has no "datetime" type per se,
it instead has only ``DATE``, it is appropriate here that the
``DATE`` type as present in the Oracle dialect be an instance of
:class:`.DateTime`.  This issue doesn't change anything as far as
the behavior of the type, as data conversion is handled by the
DBAPI in any case, however the improved subclass layout will help
the use cases of inspecting types for cross-database compatibility.
Also removed uppercase ``DATETIME`` from the Oracle dialect as this
type isn't functional in that context.

.. change::
:tags: bug, sql
:tickets: 2988

Fixed an 0.9 regression where a :class:`.Table` that failed to
reflect correctly wouldn't be removed from the parent
:class:`.MetaData`, even though in an invalid state.  Pullreq
courtesy Roman Podoliaka.

.. change::
:tags: bug, engine

The :meth:`.ConnectionEvents.after_cursor_execute` event is now
emitted for the "_cursor_execute()" method of :class:`.Connection`;
this is the "quick" executor that is used for things like
when a sequence is executed ahead of an INSERT statement, as well as
for dialect startup checks like unicode returns, charset, etc.
the :meth:`.ConnectionEvents.before_cursor_execute` event was already
invoked here.  The "executemany" flag is now always set to False
here, as this event always corresponds to a single execution.
Previously the flag could be True if we were acting on behalf of
an executemany INSERT statement.

.. change::
:tags: bug, orm

Added support for the not-quite-yet-documented ``insert=True``
flag for :func:`.event.listen` to work with mapper / instance events.

.. change::
:tags: feature, sql

Added support for literal rendering of boolean values, e.g.
"true" / "false" or "1" / "0".

.. change::
:tags: feature, sql

Added a new feature :func:`.schema.conv`, the purpose of which is to
mark a constraint name as already having had a naming convention applied.
This token will be used by Alembic migrations as of Alembic 0.6.4
in order to render constraints in migration scripts with names marked
as already having been subject to a naming convention.

.. change::
:tags: bug, sql

:paramref:`.MetaData.naming_convention` feature will now also
apply to :class:`.CheckConstraint` objects that are associated
directly with a :class:`.Column` instead of just on the
:class:`.Table`.

.. change::
:tags: bug, sql
:tickets: 2991

Fixed bug in new :paramref:`.MetaData.naming_convention` feature
where the name of a check constraint making use of the
`"%(constraint_name)s"` token would get doubled up for the
constraint generated by a boolean or enum type, and overall
duplicate events would cause the `"%(constraint_name)s"` token
to keep compounding itself.

.. change::
:tags: feature, orm

A warning is emitted if the :meth:`.MapperEvents.before_configured`
or :meth:`.MapperEvents.after_configured` events are applied to a
specific mapper or mapped class, as the events are only invoked
for the :class:`.Mapper` target at the general level.

.. change::
:tags: feature, orm

Added a new keyword argument ``once=True`` to :func:`.event.listen`
and :func:`.event.listens_for`.  This is a convenience feature which
will wrap the given listener such that it is only invoked once.

.. change::
:tags: feature, oracle
:tickets: 2911

Added a new engine option ``coerce_to_unicode=True`` to the
cx_Oracle dialect, which restores the cx_Oracle outputtypehandler
approach to Python unicode conversion under Python 2, which was
removed in 0.9.2 as a result of :ticket:`2911`.  Some use cases would
prefer that unicode coercion is unconditional for all string values,
despite performance concerns.  Pull request courtesy
Christoph Zwerschke.

.. change::
:tags: bug, pool

Fixed small issue in :class:`.SingletonThreadPool` where the current
connection to be returned might get inadvertently cleaned out during
the "cleanup" process.  Patch courtesy jd23.

.. change::
:tags: bug, ext, py3k

Fixed bug in association proxy where assigning an empty slice
(e.g. ``x[:] = [...]``) would fail on Py3k.

.. change::
:tags: bug, general
:tickets: 2979

Fixed some test/feature failures occurring in Python 3.4,
in particular the logic used to wrap "column default" callables
wouldn't work properly for Python built-ins.

.. change::
:tags: feature, general

Support has been added for pytest to run tests.   This runner
is currently being supported in addition to nose, and will likely
be preferred to nose going forward.   The nose plugin system used
by SQLAlchemy has been split out so that it works under pytest as
well.  There are no plans to drop support for nose at the moment
and we hope that the test suite itself can continue to remain as
agnostic of testing platform as possible.  See the file
README.unittests.rst for updated information on running tests
with pytest.

The test plugin system has also been enhanced to support running
tests against multiple database URLs at once, by specifying the ``--db``
and/or ``--dburi`` flags multiple times.  This does not run the entire test
suite for each database, but instead allows test cases that are specific
to certain backends make use of that backend as the test is run.
When using pytest as the test runner, the system will also run
specific test suites multiple times, once for each database, particularly
those tests within the "dialect suite".   The plan is that the enhanced
system will also be used by Alembic, and allow Alembic to run
migration operation tests against multiple backends in one run, including
third-party backends not included within Alembic itself.
Third party dialects and extensions are also encouraged to standardize
on SQLAlchemy's test suite as a basis; see the file README.dialects.rst
for background on building out from SQLAlchemy's test platform.

.. change::
:tags: feature, orm
:tickets: 2976

Added a new option to :paramref:`.relationship.innerjoin` which is
to specify the string ``"nested"``.  When set to ``"nested"`` as opposed
to ``True``, the "chaining" of joins will parenthesize the inner join on the
right side of an existing outer join, instead of chaining as a string
of outer joins.   This possibly should have been the default behavior
when 0.9 was released, as we introduced the feature of right-nested
joins in the ORM, however we are keeping it as a non-default for now
to avoid further surprises.

.. seealso::

:ref:`feature_2976`

.. change::
:tags: bug, ext
:tickets: 2810

Fixed a regression in association proxy caused by :ticket:`2810` which
caused a user-provided "getter" to no longer receive values of ``None``
when fetching scalar values from a target that is non-present.  The
check for None introduced by this change is now moved into the default
getter, so a user-provided getter will also again receive values of
None.

.. change::
:tags: bug, sql
:tickets: 2974

Adjusted the logic which applies names to the .c collection when
a no-name :class:`.BindParameter` is received, e.g. via :func:`.sql.literal`
or similar; the "key" of the bind param is used as the key within
.c. rather than the rendered name.  Since these binds have "anonymous"
names in any case, this allows individual bound parameters to
have their own name within a selectable if they are otherwise unlabeled.

.. change::
:tags: bug, sql
:tickets: 2974

Some changes to how the :attr:`.FromClause.c` collection behaves
when presented with duplicate columns.  The behavior of emitting a
warning and replacing the old column with the same name still
remains to some degree; the replacement in particular is to maintain
backwards compatibility.  However, the replaced column still remains
associated with the ``c`` collection now in a collection ``._all_columns``,
which is used by constructs such as aliases and unions, to deal with
the set of columns in ``c`` more towards what is actually in the
list of columns rather than the unique set of key names.  This helps
with situations where SELECT statements with same-named columns
are used in unions and such, so that the union can match the columns
up positionally and also there's some chance of :meth:`.FromClause.corresponding_column`
still being usable here (it can now return a column that is only
in selectable.c._all_columns and not otherwise named).
The new collection is underscored as we still need to decide where this
list might end up.   Theoretically it
would become the result of iter(selectable.c), however this would mean
that the length of the iteration would no longer match the length of
keys(), and that behavior needs to be checked out.

.. change::
:tags: bug, sql

Fixed issue in new :meth:`.TextClause.columns` method where the ordering
of columns given positionally would not be preserved.   This could
have potential impact in positional situations such as applying the
resulting :class:`.TextAsFrom` object to a union.

.. change::
:tags: feature, sql
:tickets: 2962, 2866

The new dialect-level keyword argument system for schema-level
constructs has been enhanced in order to assist with existing
schemes that rely upon addition of ad-hoc keyword arguments to
constructs.

E.g., a construct such as :class:`.Index` will again accept
ad-hoc keyword arguments within the :attr:`.Index.kwargs` collection,
after construction::

idx = Index('a', 'b')
idx.kwargs['mysql_someargument'] = True

To suit the use case of allowing custom arguments at construction time,
the :meth:`.DialectKWArgs.argument_for` method now allows this registration::

Index.argument_for('mysql', 'someargument', False)

idx = Index('a', 'b', mysql_someargument=True)

.. seealso::

:meth:`.DialectKWArgs.argument_for`

.. change::
:tags: bug, orm, engine
:tickets: 2973

Fixed bug where events set to listen at the class
level (e.g. on the :class:`.Mapper` or :class:`.ClassManager`
level, as opposed to on an individual mapped class, and also on
:class:`.Connection`) that also made use of internal argument conversion
(which is most within those categories) would fail to be removable.

.. change::
:tags: bug, orm

Fixed regression from 0.8 where using an option like
:func:`.orm.lazyload` with the "wildcard" expression, e.g. ``"*"``,
would raise an assertion error in the case where the query didn't
contain any actual entities.  This assertion is meant for other cases
and was catching this one inadvertently.

.. change::
:tags: bug, examples

Fixed bug in the versioned_history example where column-level INSERT
defaults would prevent history values of NULL from being written.

.. change::
:tags: orm, bug, sqlite
:tickets: 2969

More fixes to SQLite "join rewriting"; the fix from :ticket:`2967`
implemented right before the release of 0.9.3 affected the case where
a UNION contained nested joins in it.   "Join rewriting" is a feature
with a wide range of possibilities and is the first intricate
"SQL rewriting" feature we've introduced in years, so we're sort of
going through a lot of iterations with it (not unlike eager loading
back in the 0.2/0.3 series, polymorphic loading in 0.4/0.5). We should
be there soon so thanks for bearing with us :).


.. changelog::

0.9.3

:released: February 19, 2014

.. change::
:tags: orm, bug, sqlite
:tickets: 2967

Fixed bug in SQLite "join rewriting" where usage of an exists() construct
would fail to be rewritten properly, such as when the exists is
mapped to a column_property in an intricate nested-join scenario.
Also fixed a somewhat related issue where join rewriting would fail
on the columns clause of the SELECT statement if the targets were
aliased tables, as opposed to individual aliased columns.

.. change::
:tags: sqlite, bug

The SQLite dialect will now skip unsupported arguments when reflecting
types; such as if it encounters a string like ``INTEGER(5)``, the
:class:`.INTEGER` type will be instantiated without the "5" being included,
based on detecting a ``TypeError`` on the first attempt.

.. change::
:tags: sqlite, bug

Support has been added to SQLite type reflection to fully support
the "type affinity" contract specified at http://www.sqlite.org/datatype3.html.
In this scheme, keywords like ``INT``, ``CHAR``, ``BLOB`` or
``REAL`` located in the type name generically associate the type with
one of five affinities.  Pull request courtesy Erich Blume.

.. seealso::

:ref:`sqlite_type_reflection`

.. change::
:tags: postgresql, feature

Added the :attr:`.TypeEngine.python_type` convenience accessor onto the
:class:`.postgresql.ARRAY` type.  Pull request courtesy Alexey Terentev.

.. change::
:tags: examples, feature

Added optional "changed" column to the versioned rows example, as well
as support for when the versioned :class:`.Table` has an explicit
:paramref:`~.Table.schema` argument.   Pull request
courtesy jplaverdure.

.. change::
:tags: bug, postgresql
:tickets: 2946

Added server version detection to the newly added dialect startup
query for  "show standard_conforming_strings"; as this variable was
added as of PG 8.2, we skip the query for PG versions who report a
version string earlier than that.

.. change::
:tags: bug, orm, declarative
:tickets: 2950

Fixed bug where :class:`.AbstractConcreteBase` would fail to be
fully usable within declarative relationship configuration, as its
string classname would not be available in the registry of classnames
at mapper configuration time.   The class now explicitly adds itself
to the class registry, and additionally both :class:`.AbstractConcreteBase`
as well as :class:`.ConcreteBase` set themselves up *before* mappers
are configured within the :func:`.configure_mappers` setup, using
the new :meth:`.MapperEvents.before_configured` event.

.. change::
:tags: feature, orm

Added new :meth:`.MapperEvents.before_configured` event which allows
an event at the start of :func:`.configure_mappers`, as well
as ``__declare_first__()`` hook within declarative to complement
``__declare_last__()``.

.. change::
:tags: bug, mysql, cymysql
:tickets: 2934

Fixed bug in cymysql dialect where a version string such as
``'33a-MariaDB'`` would fail to parse properly.  Pull request
courtesy Matt Schmidt.

.. change::
:tags: bug, orm
:tickets: 2949

Fixed an 0.9 regression where ORM instance or mapper events applied
to a base class such as a declarative base with the propagate=True
flag would fail to apply to existing mapped classes which also
used inheritance due to an assertion.  Additionally, repaired an
attribute error which could occur during removal of such an event,
depending on how it was first assigned.

.. change::
:tags: bug, ext

Fixed bug where the :class:`.AutomapBase` class of the
new automap extension would fail if classes
were pre-arranged in single or potentially joined inheritance patterns.
The repaired joined inheritance issue could also potentially apply when
using :class:`.DeferredReflection` as well.


.. change::
:tags: bug, sql

Fixed regression in new "naming convention" feature where conventions
would fail if the referred table in a foreign key contained a schema
name.  Pull request courtesy Thomas Farvour.

.. change::
:tags: bug, sql

Fixed bug where so-called "literal render" of :func:`.bindparam`
constructs would fail if the bind were constructed with a callable,
rather than a direct value.  This prevented ORM expressions
from being rendered with the "literal_binds" compiler flag.

.. change::
:tags: bug, orm
:tickets: 2935

Improved the initialization logic of composite attributes such that
calling ``MyClass.attribute`` will not require that the configure
mappers step has occurred, e.g. it will just work without throwing
any error.

.. change::
:tags: bug, orm
:tickets: 2932

More issues with [ticket:2932] first resolved in 0.9.2 where
using a column key of the form ``<tablename>_<columnname>``
matching that of an aliased column in the text would still not
match at the ORM level, which is ultimately due to a core
column-matching issue.  Additional rules have been added so that the
column ``_label`` is taken into account when working with a
:class:`.TextAsFrom` construct or with literal columns.

.. changelog::

0.9.2

:released: February 2, 2014

.. change::
:tags: bug, examples

Added a tweak to the "history_meta" example where the check for
"history" on a relationship-bound attribute will now no longer emit
any SQL if the relationship is unloaded.

.. change::
:tags: feature, sql

Added :paramref:`.MetaData.reflect.**dialect_kwargs`
to support dialect-level reflection options for all :class:`.Table`
objects reflected.

.. change::
:tags: feature, postgresql
:tickets: 2922

Added a new dialect-level argument ``postgresql_ignore_search_path``;
this argument is accepted by both the :class:`.Table` constructor
as well as by the :meth:`.MetaData.reflect` method.  When in use
against PostgreSQL, a foreign-key referenced table which specifies
a remote schema name will retain that schema name even if the name
is present in the ``search_path``; the default behavior since 0.7.3
has been that schemas present in ``search_path`` would not be copied
to reflected :class:`.ForeignKey` objects.  The documentation has been
updated to describe in detail the behavior of the ``pg_get_constraintdef()``
function and how the ``postgresql_ignore_search_path`` feature essentially
determines if we will honor the schema qualification reported by
this function or not.

.. seealso::

:ref:`postgresql_schema_reflection`

.. change::
:tags: bug, sql
:tickets: 2913

The behavior of :meth:`.Table.tometadata` has been adjusted such that
the schema target of a :class:`.ForeignKey` will not be changed unless
that schema matches that of the parent table.  That is, if
a table "schema_a.user" has a foreign key to "schema_b.order.id",
the "schema_b" target will be maintained whether or not the
"schema" argument is passed to :meth:`.Table.tometadata`.  However
if a table "schema_a.user" refers to "schema_a.order.id", the presence
of "schema_a" will be updated on both the parent and referred tables.
This is a behavioral change hence isn't likely to be backported to
0.8; it is assumed that the previous behavior is pretty buggy
however and that it's unlikely anyone was relying upon it.

Additionally, a new parameter has been added
:paramref:`.Table.tometadata.referred_schema_fn`.  This refers to a
callable function which will be used to determine the new referred
schema for any :class:`.ForeignKeyConstraint` encountered in the
tometadata operation.  This callable can be used to revert to the
previous behavior or to customize how referred schemas are treated
on a per-constraint basis.

.. change::
:tags: bug, orm
:tickets: 2932

Fixed bug in new :class:`.TextAsFrom` construct where :class:`.Column`-
oriented row lookups were not matching up to the ad-hoc :class:`.ColumnClause`
objects that :class:`.TextAsFrom` generates, thereby making it not
usable as a target in :meth:`.Query.from_statement`.  Also fixed
:meth:`.Query.from_statement` mechanics to not mistake a :class:`.TextAsFrom`
for a :class:`.Select` construct.  This bug is also an 0.9 regression
as the :meth:`.Text.columns` method is called to accommodate the
:paramref:`.text.typemap` argument.

.. change::
:tags: feature, sql
:tickets: 2923

Added a new feature which allows automated naming conventions to be
applied to :class:`.Constraint` and :class:`.Index` objects.  Based
on a recipe in the wiki, the new feature uses schema-events to set up
names as various schema objects are associated with each other.  The
events then expose a configuration system through a new argument
:paramref:`.MetaData.naming_convention`.  This system allows production
of both simple and custom naming schemes for constraints and indexes
on a per-:class:`.MetaData` basis.

.. seealso::

:ref:`constraint_naming_conventions`

.. change::
:tags: bug, orm
:tickets: 2921

Added a new directive used within the scope of an attribute "set" operation
to disable autoflush, in the case that the attribute needs to lazy-load
the "old" value, as in when replacing one-to-one values or some
kinds of many-to-one.  A flush at this point otherwise occurs
at the point that the attribute is None and can cause NULL violations.

.. change::
:tags: feature, orm

Added a new parameter :paramref:`.Operators.op.is_comparison`.  This
flag allows a custom op from :meth:`.Operators.op` to be considered
as a "comparison" operator, thus usable for custom
:paramref:`.relationship.primaryjoin` conditions.

.. seealso::

:ref:`relationship_custom_operator`

.. change::
:tags: bug, sqlite

Fixed bug whereby SQLite compiler failed to propagate compiler arguments
such as "literal binds" into a CAST expression.

.. change::
:tags: bug, sql

Fixed bug whereby binary type would fail in some cases
if used with a "test" dialect, such as a DefaultDialect or other
dialect with no DBAPI.

.. change::
:tags: bug, sql, py3k

Fixed bug where "literal binds" wouldn't work with a bound parameter
that's a binary type.  A similar, but different, issue is fixed
in 0.8.

.. change::
:tags: bug, sql
:tickets: 2927

Fixed regression whereby the "annotation" system used by the ORM was leaking
into the names used by standard functions in :mod:`sqlalchemy.sql.functions`,
such as ``func.coalesce()`` and ``func.max()``.  Using these functions
in ORM attributes and thus producing annotated versions of them could
corrupt the actual function name rendered in the SQL.

.. change::
:tags: bug, sql
:tickets: 2924, 2848

Fixed 0.9 regression where the new sortable support for :class:`.RowProxy`
would lead to ``TypeError`` when compared to non-tuple types as it attempted
to apply tuple() to the "other" object unconditionally.  The
full range of Python comparison operators have now been implemented on
:class:`.RowProxy`, using an approach that guarantees a comparison
system that is equivalent to that of a tuple, and the "other" object
is only coerced if it's an instance of RowProxy.

.. change::
:tags: bug, orm
:tickets: 2918

Fixed an 0.9 regression where the automatic aliasing applied by
:class:`.Query` and in other situations where selects or joins
were aliased (such as joined table inheritance) could fail if a
user-defined :class:`.Column` subclass were used in the expression.
In this case, the subclass would fail to propagate ORM-specific
"annotations" along needed by the adaptation.  The "expression
annotations" system has been corrected to account for this case.

.. change::
:tags: feature, orm

Support is improved for supplying a :func:`.join` construct as the
target of :paramref:`.relationship.secondary` for the purposes
of creating very complex :func:`.relationship` join conditions.
The change includes adjustments to query joining, joined eager loading
to not render a SELECT subquery, changes to lazy loading such that
the "secondary" target is properly included in the SELECT, and
changes to declarative to better support specification of a
join() object with classes as targets.

The new use case is somewhat experimental, but a new documentation section
has been added.

.. seealso::

:ref:`composite_secondary_join`

.. change::
:tags: bug, mysql, sql
:tickets: 2917

Added new test coverage for so-called "down adaptions" of SQL types,
where a more specific type is adapted to a more generic one - this
use case is needed by some third party tools such as ``sqlacodegen``.
The specific cases that needed repair within this test suite were that
of :class:`.mysql.ENUM` being downcast into a :class:`.types.Enum`,
and that of SQLite date types being cast into generic date types.
The ``adapt()`` method needed to become more specific here to counteract
the removal of a "catch all" ``**kwargs`` collection on the base
:class:`.TypeEngine` class that was removed in 0.9.

.. change::
:tags: feature, sql
:tickets: 2910

Options can now be specified on a :class:`.PrimaryKeyConstraint` object
independently of the specification of columns in the table with
the ``primary_key=True`` flag; use a :class:`.PrimaryKeyConstraint`
object with no columns in it to achieve this result.

Previously, an explicit :class:`.PrimaryKeyConstraint` would have the
effect of those columns marked as ``primary_key=True`` being ignored;
since this is no longer the case, the :class:`.PrimaryKeyConstraint`
will now assert that either one style or the other is used to specify
the columns, or if both are present, that the column lists match
exactly.  If an inconsistent set of columns in the
:class:`.PrimaryKeyConstraint`
and within the :class:`.Table` marked as ``primary_key=True`` are
present, a warning is emitted, and the list of columns is taken
only from the :class:`.PrimaryKeyConstraint` alone as was the case
in previous releases.



.. seealso::

:class:`.PrimaryKeyConstraint`

.. change::
:tags: feature, sql
:tickets: 2866

The system by which schema constructs and certain SQL constructs
accept dialect-specific keyword arguments has been enhanced.  This
system includes commonly the :class:`.Table` and :class:`.Index` constructs,
which accept a wide variety of dialect-specific arguments such as
``mysql_engine`` and ``postgresql_where``, as well as the constructs
:class:`.PrimaryKeyConstraint`, :class:`.UniqueConstraint`,
:class:`.Update`, :class:`.Insert` and :class:`.Delete`, and also
newly added kwarg capability to :class:`.ForeignKeyConstraint`
and :class:`.ForeignKey`.  The change is that participating dialects
can now specify acceptable argument lists for these constructs, allowing
an argument error to be raised if an invalid keyword is specified for
a particular dialect.  If the dialect portion of the keyword is unrecognized,
a warning is emitted only; while the system will actually make use
of setuptools entrypoints in order to locate non-local dialects,
the use case where certain dialect-specific arguments are used
in an environment where that third-party dialect is uninstalled remains
supported.  Dialects also have to explicitly opt-in to this system,
so that external dialects which aren't making use of this system
will remain unaffected.

.. change::
:tags: bug, sql

A :class:`.UniqueConstraint` created inline with a :class:`.Table`
that has no columns within it will be skipped.  Pullreq courtesy
Derek Harland.

.. change::
:tags: feature, mssql

Added an option ``mssql_clustered`` to the :class:`.UniqueConstraint`
and :class:`.PrimaryKeyConstraint` constructs; on SQL Server, this adds
the ``CLUSTERED`` keyword to the constraint construct within DDL.
Pullreq courtesy Derek Harland.

.. change::
:tags: bug, sql, orm
:tickets: 2912

Fixed the multiple-table "UPDATE..FROM" construct, only usable on
MySQL, to correctly render the SET clause among multiple columns
with the same name across tables.  This also changes the name used for
the bound parameter in the SET clause to "<tablename>_<colname>" for
the non-primary table only; as this parameter is typically specified
using the :class:`.Column` object directly this should not have an
impact on applications.   The fix takes effect for both
:meth:`.Table.update` as well as :meth:`.Query.update` in the ORM.

.. change::
:tags: bug, oracle
:tickets: 2911

It's been observed that the usage of a cx_Oracle "outputtypehandler"
in Python 2.xx in order to coerce string values to Unicode is inordinately
expensive; even though cx_Oracle is written in C, when you pass the
Python ``unicode`` primitive to cursor.var() and associate with an output
handler, the library counts every conversion as a Python function call
with all the requisite overhead being recorded; this *despite* the fact
when running in Python 3, all strings are also unconditionally coerced
to unicode but it does *not* incur this overhead,
meaning that cx_Oracle is failing to use performant techniques in Py2K.
As SQLAlchemy cannot easily select for this style of type handler on a
per-column basis, the handler was assembled unconditionally thereby
adding the overhead to all string access.

So this logic has been replaced with SQLAlchemy's own unicode
conversion system, which now
only takes effect in Py2K for columns that are requested as unicode.
When C extensions are used, SQLAlchemy's system appears to be 2-3x faster than
cx_Oracle's.  Additionally, SQLAlchemy's unicode conversion has been
enhanced such that when the "conditional" converter is required
(now needed for the Oracle backend), the check for "already unicode" is now
performed in C and no longer introduces significant overhead.

This change has two impacts on the cx_Oracle backend.  One is that
string values in Py2K which aren't specifically requested with the
Unicode type or convert_unicode=True will now come back as ``str``,
not ``unicode`` - this behavior is similar to a backend such as
MySQL.  Additionally, when unicode values are requested with the cx_Oracle
backend, if the C extensions are *not* used, there is now an additional
overhead of an isinstance() check per column.  This tradeoff has been
made as it can be worked around and no longer places a performance burden
on the likely majority of Oracle result columns that are non-unicode
strings.

.. change::
:tags: bug, orm
:tickets: 2908

Fixed a bug involving the new flattened JOIN structures which
are used with :func:`.joinedload()` (thereby causing a regression
in joined eager loading) as well as :func:`.aliased`
in conjunction with the ``flat=True`` flag and joined-table inheritance;
basically multiple joins across a "parent JOIN sub" entity using different
paths to get to a target class wouldn't form the correct ON conditions.
An adjustment / simplification made in the mechanics of figuring
out the "left side" of the join in the case of an aliased, joined-inh
class repairs the issue.

.. change::
:tags: bug, mysql

The MySQL CAST compilation now takes into account aspects of a string
type such as "charset" and "collation".  While MySQL wants all character-
based CAST calls to use the CHAR type, we now create a real CHAR
object at CAST time and copy over all the parameters it has, so that
an expression like ``cast(x, mysql.TEXT(charset='utf8'))`` will
render ``CAST(t.col AS CHAR CHARACTER SET utf8)``.

.. change::
:tags: bug, mysql
:tickets: 2906

Added new "unicode returns" detection to the MySQL dialect and
to the default dialect system overall, such that any dialect
can add extra "tests" to the on-first-connect "does this DBAPI
return unicode directly?" detection. In this case, we are
adding a check specifically against the "utf8" encoding with
an explicit "utf8_bin" collation type (after checking that
this collation is available) to test for some buggy unicode
behavior observed with MySQLdb version 1.2.3.  While MySQLdb
has resolved this issue as of 1.2.4, the check here should
guard against regressions.  The change also allows the "unicode"
checks to log in the engine logs, which was not previously
the case.

.. change::
:tags: bug, mysql, pool, engine
:tickets: 2907

:class:`.Connection` now associates a new
:class:`.RootTransaction` or :class:`.TwoPhaseTransaction`
with its immediate :class:`._ConnectionFairy` as a "reset handler"
for the span of that transaction, which takes over the task
of calling commit() or rollback() for the "reset on return" behavior
of :class:`.Pool` if the transaction was not otherwise completed.
This resolves the issue that a picky transaction
like that of MySQL two-phase will be
properly closed out when the connection is closed without an
explicit rollback or commit (e.g. no longer raises "XAER_RMFAIL"
in this case - note this only shows up in logging as the exception
is not propagated within pool reset).
This issue would arise e.g. when using an orm
:class:`.Session` with ``twophase`` set, and then
:meth:`.Session.close` is called without an explicit rollback or
commit.   The change also has the effect that you will now see
an explicit "ROLLBACK" in the logs when using a :class:`.Session`
object in non-autocommit mode regardless of how that session was
discarded.  Thanks to Jeff Dairiki and Laurence Rowe for isolating
the issue here.

.. change::
:tags: feature, pool, engine

Added a new pool event :meth:`.PoolEvents.invalidate`.  Called when
a DBAPI connection is to be marked as "invalidated" and discarded
from the pool.

.. change::
:tags: bug, pool

The argument names for the :meth:`.PoolEvents.reset` event have been
renamed to ``dbapi_connection`` and ``connection_record`` in order
to maintain consistency with all the other pool events.  It is expected
that any existing listeners for this relatively new and
seldom-used event are using positional style to receive arguments in
any case.

.. change::
:tags: bug, py3k, cextensions

Fixed an issue where the C extensions in Py3K are using the wrong API
to specify the top-level module function, which breaks
in Python 3.4b2.  Py3.4b2 changes PyMODINIT_FUNC to return
"void" instead of ``PyObject *``, so we now make sure to use
"PyMODINIT_FUNC" instead of ``PyObject *`` directly.  Pull request
courtesy cgohlke.

.. change::
:tags: bug, schema

Restored :class:`sqlalchemy.schema.SchemaVisitor` to the ``.schema``
module.  Pullreq courtesy Sean Dague.

.. changelog::

0.9.1

:released: January 5, 2014

.. change::
:tags: bug, orm, events
:tickets: 2905

Fixed regression where using a ``functools.partial()`` with the event
system would cause a recursion overflow due to usage of inspect.getargspec()
on it in order to detect a legacy calling signature for certain events,
and apparently there's no way to do this with a partial object.  Instead
we skip the legacy check and assume the modern style; the check itself
now only occurs for the SessionEvents.after_bulk_update and
SessionEvents.after_bulk_delete events.  Those two events will require
the new signature style if assigned to a "partial" event listener.

.. change::
:tags: feature, orm, extensions

A new, **experimental** extension :mod:`sqlalchemy.ext.automap` is added.
This extension expands upon the functionality of Declarative as well as
the :class:`.DeferredReflection` class to produce a base class which
automatically generates mapped classes *and relationships* based on
table metadata.

.. seealso::

:ref:`feature_automap`

:ref:`automap_toplevel`

.. change::
:tags: feature, sql

Conjunctions like :func:`.and_` and :func:`.or_` can now accept
Python generators as a single argument, e.g.::

and_(x == y for x, y in tuples)

The logic here looks for a single argument ``*args`` where the first
element is an instance of ``types.GeneratorType``.

.. change::
:tags: feature, schema

The :paramref:`.Table.extend_existing` and :paramref:`.Table.autoload_replace`
parameters are now available on the :meth:`.MetaData.reflect`
method.

.. change::
:tags: bug, orm, declarative

Fixed an extremely unlikely memory issue where when using
:class:`.DeferredReflection`
to define classes pending for reflection, if some subset of those
classes were discarded before the :meth:`.DeferredReflection.prepare`
method were called to reflect and map the class, a strong reference
to the class would remain held within the declarative internals.
This internal collection of "classes to map" now uses weak
references against the classes themselves.

.. change::
:tags: bug, orm

Fixed bug where using new :attr:`.Session.info` attribute would fail
if the ``.info`` argument were only passed to the :class:`.sessionmaker`
creation call but not to the object itself.  Courtesy Robin Schoonover.

.. change::
:tags: bug, orm
:tickets: 2901

Fixed regression where we don't check the given name against the
correct string class when setting up a backref based on a name,
therefore causing the error "too many values to unpack".  This was
related to the Py3k conversion.

.. change::
:tags: bug, orm, declarative
:tickets: 2900

A quasi-regression where apparently in 0.8 you can set a class-level
attribute on declarative to simply refer directly to an :class:`.InstrumentedAttribute`
on a superclass or on the class itself, and it
acts more or less like a synonym; in 0.9, this fails to set up enough
bookkeeping to keep up with the more liberalized backref logic
from :ticket:`2789`.  Even though this use case was never directly
considered, it is now detected by declarative at the "setattr()" level
as well as when setting up a subclass, and the mirrored/renamed attribute
is now set up as a :func:`.synonym` instead.

.. change::
:tags: bug, orm
:tickets: 2903

Fixed regression where we apparently still create an implicit
alias when saying query(B).join(B.cs), where "C" is a joined inh
class; however, this implicit alias was created only considering
the immediate left side, and not a longer chain of joins along different
joined-inh subclasses of the same base.   As long as we're still
implicitly aliasing in this case, the behavior is dialed back a bit
so that it will alias the right side in a wider variety of cases.

.. changelog::

0.9.0

:released: December 30, 2013

.. change::
:tags: bug, orm, declarative
:tickets: 2828

Declarative does an extra check to detect if the same
:class:`.Column` is mapped multiple times under different properties
(which typically should be a :func:`.synonym` instead) or if two
or more :class:`.Column` objects are given the same name, raising
a warning if this condition is detected.

.. change::
:tags: bug, firebird
:tickets: 2898

Changed the queries used by Firebird to list table and view names
to query from the ``rdb$relations`` view instead of the
``rdb$relation_fields`` and ``rdb$view_relations`` views.
Variants of both the old and new queries are mentioned on many
FAQ and blogs, however the new queries are taken straight from
the "Firebird FAQ" which appears to be the most official source
of info.

.. change::
:tags: bug, mysql
:tickets: 2893

Improvements to the system by which SQL types generate within
``__repr__()``, particularly with regards to the MySQL integer/numeric/
character types which feature a wide variety of keyword arguments.
The ``__repr__()`` is important for use with Alembic autogenerate
for when Python code is rendered in a migration script.

.. change::
:tags: feature, postgresql
:tickets: 2581

Support for PostgreSQL JSON has been added, using the new
:class:`.JSON` type.   Huge thanks to Nathan Rice for
implementing and testing this.

.. change::
:tags: bug, sql

The :func:`.cast` function, when given a plain literal value,
will now apply the given type to the given literal value on the
bind parameter side according to the type given to the cast,
in the same manner as that of the :func:`.type_coerce` function.
However unlike :func:`.type_coerce`, this only takes effect if a
non-clauseelement value is passed to :func:`.cast`; an existing typed
construct will retain its type.

.. change::
:tags: bug, postgresql

Now using psycopg2 UNICODEARRAY extension for handling unicode arrays
with psycopg2 + normal "native unicode" mode, in the same way the
UNICODE extension is used.

.. change::
:tags: bug, sql
:tickets: 2883

The :class:`.ForeignKey` class more aggressively checks the given
column argument.   If not a string, it checks that the object is
at least a :class:`.ColumnClause`, or an object that resolves to one,
and that the ``.table`` attribute, if present, refers to a
:class:`.TableClause` or subclass, and not something like an
:class:`.Alias`.  Otherwise, a :class:`.ArgumentError` is raised.


.. change::
:tags: feature, orm

The :class:`.exc.StatementError` or DBAPI-related subclass
now can accommodate additional information about the "reason" for
the exception; the :class:`.Session` now adds some detail to it
when the exception occurs within an autoflush.  This approach
is taken as opposed to combining :class:`.FlushError` with
a Python 3 style "chained exception" approach so as to maintain
compatibility both with Py2K code as well as code that already
catches ``IntegrityError`` or similar.

.. change::
:tags: feature, postgresql

Added support for PostgreSQL TSVECTOR via the
:class:`.postgresql.TSVECTOR` type.  Pull request courtesy
Noufal Ibrahim.

.. change::
:tags: feature, engine
:tickets: 2875

The :func:`.engine_from_config` function has been improved so that
we will be able to parse dialect-specific arguments from string
configuration dictionaries.  Dialect classes can now provide their
own list of parameter types and string-conversion routines.
The feature is not yet used by the built-in dialects, however.

.. change::
:tags: bug, sql
:tickets: 2879

The precedence rules for the :meth:`.ColumnOperators.collate` operator
have been modified, such that the COLLATE operator is now of lower
precedence than the comparison operators.  This has the effect that
a COLLATE applied to a comparison will not render parenthesis
around the comparison, which is not parsed by backends such as
MSSQL.  The change is backwards incompatible for those setups that
were working around the issue by applying :meth:`.Operators.collate`
to an individual element of the comparison expression,
rather than the comparison expression as a whole.

.. seealso::

:ref:`migration_2879`

.. change::
:tags: bug, orm, declarative
:tickets: 2865

The :class:`.DeferredReflection` class has been enhanced to provide
automatic reflection support for the "secondary" table referred
to by a :func:`.relationship`.   "secondary", when specified
either as a string table name, or as a :class:`.Table` object with
only a name and :class:`.MetaData` object will also be included
in the reflection process when :meth:`.DeferredReflection.prepare`
is called.

.. change::
:tags: feature, orm, backrefs
:tickets: 1535

Added new argument ``include_backrefs=True`` to the
:func:`.validates` function; when set to False, a validation event
will not be triggered if the event was initated as a backref to
an attribute operation from the other side.

.. seealso::

:ref:`feature_1535`

.. change::
:tags: bug, orm, collections, py3k

Added support for the Python 3 method ``list.clear()`` within
the ORM collection instrumentation system; pull request
courtesy Eduardo Schettino.

.. change::
:tags: bug, postgresql
:tickets: 2878

Fixed bug where values within an ENUM weren't escaped for single
quote signs.   Note that this is backwards-incompatible for existing
workarounds that manually escape the single quotes.

.. seealso::

:ref:`migration_2878`

.. change::
:tags: bug, orm, declarative

Fixed bug where in Py2K a unicode literal would not be accepted
as the string name of a class or other argument within
declarative using :func:`.relationship`.

.. change::
:tags: feature, sql
:tickets: 2877, 2882

New improvements to the :func:`.text` construct, including
more flexible ways to set up bound parameters and return types;
in particular, a :func:`.text` can now be turned into a full
FROM-object, embeddable in other statements as an alias or CTE
using the new method :meth:`.TextClause.columns`.   The :func:`.text`
construct can also render "inline" bound parameters when the construct
is compiled in a "literal bound" context.

.. seealso::

:ref:`feature_2877`

.. change::
:tags: feature, sql

A new API for specifying the ``FOR UPDATE`` clause of a ``SELECT``
is added with the new :meth:`.GenerativeSelect.with_for_update` method.
This method supports a more straightforward system of setting
dialect-specific options compared to the ``for_update`` keyword
argument of :func:`.select`, and also includes support for the
SQL standard ``FOR UPDATE OF`` clause.   The ORM also includes
a new corresponding method :meth:`.Query.with_for_update`.
Pull request courtesy Mario Lassnig.

.. seealso::

:ref:`feature_github_42`

.. change::
:tags: feature, orm

A new API for specifying the ``FOR UPDATE`` clause of a ``SELECT``
is added with the new :meth:`.Query.with_for_update` method,
to complement the new :meth:`.GenerativeSelect.with_for_update` method.
Pull request courtesy Mario Lassnig.

.. seealso::

:ref:`feature_github_42`

.. change::
:tags: bug, engine
:tickets: 2873

The :func:`.create_engine` routine and the related
:func:`.make_url` function no longer considers the ``+`` sign
to be a space within the password field.  The parsing has been
adjusted to match RFC 1738 exactly, in that both ``username``
and ``password`` expect only ``:``, `, and ``/`` to be
encoded.

.. seealso::

:ref:`migration_2873`


.. change::
:tags: bug, orm
:tickets: 2872

Some refinements to the :class:`.AliasedClass` construct with regards
to descriptors, like hybrids, synonyms, composites, user-defined
descriptors, etc.  The attribute
adaptation which goes on has been made more robust, such that if a descriptor
returns another instrumented attribute, rather than a compound SQL
expression element, the operation will still proceed.
Additionally, the "adapted" operator will retain its class; previously,
a change in class from ``InstrumentedAttribute`` to ``QueryableAttribute``
(a superclass) would interact with Python's operator system such that
an expression like ``aliased(MyClass.x) > MyClass.x`` would reverse itself
to read ``myclass.x < myclass_1.x``.   The adapted attribute will also
refer to the new :class:`.AliasedClass` as its parent which was not
always the case before.

.. change::
:tags: feature, sql
:tickets: 2867

The precision used when coercing a returned floating point value to
Python ``Decimal`` via string is now configurable.  The
flag ``decimal_return_scale`` is now supported by all :class:`.Numeric`
and :class:`.Float` types, which will ensure this many digits are taken
from the native floating point value when it is converted to string.
If not present, the type will make use of the value of ``.scale``, if
the type supports this setting and it is non-None.  Otherwise the original
default length of 10 is used.

.. seealso::

:ref:`feature_2867`

.. change::
:tags: bug, schema
:tickets: 2868

Fixed a regression caused by :ticket:`2812` where the repr() for
table and column names would fail if the name contained non-ascii
characters.

.. change::
:tags: bug, engine
:tickets: 2848

The :class:`.RowProxy` object is now sortable in Python as a regular
tuple is; this is accomplished via ensuring tuple() conversion on
both sides within the ``__eq__()`` method as well as
the addition of a ``__lt__()`` method.

.. seealso::

:ref:`migration_2848`

.. change::
:tags: bug, orm
:tickets: 2833

The ``viewonly`` flag on :func:`.relationship` will now prevent
attribute history from being written on behalf of the target attribute.
This has the effect of the object not being written to the
Session.dirty list if it is mutated.  Previously, the object would
be present in Session.dirty, but no change would take place on behalf
of the modified attribute during flush.   The attribute still emits
events such as backref events and user-defined events and will still
receive mutations from backrefs.

.. seealso::

:ref:`migration_2833`

.. change::
:tags: bug, orm

Added support for new :attr:`.Session.info` attribute to
:class:`.scoped_session`.

.. change::
:tags: removed

The "informix" and "informixdb" dialects have been removed; the code
is now available as a separate repository on Bitbucket.   The IBM-DB
project has provided production-level Informix support since the
informixdb dialect was first added.

.. change::
:tags: bug, orm

Fixed bug where usage of new :class:`.Bundle` object would cause
the :attr:`.Query.column_descriptions` attribute to fail.

.. change::
:tags: bug, examples

Fixed bug which prevented history_meta recipe from working with
joined inheritance schemes more than one level deep.

.. change::
:tags: bug, orm, sql, sqlite
:tickets: 2858

Fixed a regression introduced by the join rewriting feature of
:ticket:`2369` and :ticket:`2587` where a nested join with one side
already an aliased select would fail to translate the ON clause on the
outside correctly; in the ORM this could be seen when using a
SELECT statement as a "secondary" table.

.. changelog::
:version: 0.9.0b1
:released: October 26, 2013

.. change::
:tags: feature, orm
:tickets: 2810

The association proxy now returns ``None`` when fetching a scalar
attribute off of a scalar relationship, where the scalar relationship
itself points to ``None``, instead of raising an ``AttributeError``.

.. seealso::

:ref:`migration_2810`

.. change::
:tags: feature, sql, postgresql, mysql
:tickets: 2183

The PostgreSQL and MySQL dialects now support reflection/inspection
of foreign key options, including ON UPDATE, ON DELETE.  PostgreSQL
also reflects MATCH, DEFERRABLE, and INITIALLY.  Courtesy ijl.

.. change::
:tags: bug, mysql
:tickets: 2839

Fix and test parsing of MySQL foreign key options within reflection;
this complements the work in :ticket:`2183` where we begin to support
reflection of foreign key options such as ON UPDATE/ON DELETE
cascade.

.. change::
:tags: bug, orm
:tickets: 2787

:func:`.attributes.get_history()` when used with a scalar column-mapped
attribute will now honor the "passive" flag
passed to it; as this defaults to ``PASSIVE_OFF``, the function will
by default query the database if the value is not present.
This is a behavioral change vs. 0.8.

.. seealso::

:ref:`change_2787`

.. change::
:tags: feature, orm
:tickets: 2787

Added new method :meth:`.AttributeState.load_history`, works like
:attr:`.AttributeState.history` but also fires loader callables.

.. seealso::

:ref:`change_2787`


.. change::
:tags: feature, sql
:tickets: 2850

A :func:`.bindparam` construct with a "null" type (e.g. no type
specified) is now copied when used in a typed expression, and the
new copy is assigned the actual type of the compared column.  Previously,
this logic would occur on the given :func:`.bindparam` in place.
Additionally, a similar process now occurs for :func:`.bindparam` constructs
passed to :meth:`.ValuesBase.values` for an :class:`.Insert` or
:class:`.Update` construct, within the compilation phase of the
construct.

These are both subtle behavioral changes which may impact some
usages.

.. seealso::

:ref:`migration_2850`

.. change::
:tags: feature, sql
:tickets: 2804, 2823, 2734

An overhaul of expression handling for special symbols particularly
with conjunctions, e.g.
``None`` :func:`.expression.null` :func:`.expression.true`
:func:`.expression.false`, including consistency in rendering NULL
in conjunctions, "short-circuiting" of :func:`.and_` and :func:`.or_`
expressions which contain boolean constants, and rendering of
boolean constants and expressions as compared to "1" or "0" for backends
that don't feature ``true``/``false`` constants.

.. seealso::

:ref:`migration_2804`

.. change::
:tags: feature, sql
:tickets: 2838

The typing system now handles the task of rendering "literal bind" values,
e.g. values that are normally bound parameters but due to context must
be rendered as strings, typically within DDL constructs such as
CHECK constraints and indexes (note that "literal bind" values
become used by DDL as of :ticket:`2742`).  A new method
:meth:`.TypeEngine.literal_processor` serves as the base, and
:meth:`.TypeDecorator.process_literal_param` is added to allow wrapping
of a native literal rendering method.

.. seealso::

:ref:`change_2838`

.. change::
:tags: feature, sql
:tickets: 2716

The :meth:`.Table.tometadata` method now produces copies of
all :attr:`.SchemaItem.info` dictionaries from all :class:`.SchemaItem`
objects within the structure including columns, constraints,
foreign keys, etc.   As these dictionaries
are copies, they are independent of the original dictionary.
Previously, only the ``.info`` dictionary of :class:`.Column` was transferred
within this operation, and it was only linked in place, not copied.

.. change::
:tags: feature, postgresql
:tickets: 2840

Added support for rendering ``SMALLSERIAL`` when a :class:`.SmallInteger`
type is used on a primary key autoincrement column, based on server
version detection of PostgreSQL version 9.2 or greater.

.. change::
:tags: feature, mysql
:tickets: 2817

The MySQL :class:`.mysql.SET` type now features the same auto-quoting
behavior as that of :class:`.mysql.ENUM`.  Quotes are not required when
setting up the value, but quotes that are present will be auto-detected
along with a warning.  This also helps with Alembic where
the SET type doesn't render with quotes.

.. change::
:tags: feature, sql

The ``default`` argument of :class:`.Column` now accepts a class
or object method as an argument, in addition to a standalone function;
will properly detect if the "context" argument is accepted or not.

.. change::
:tags: bug, sql
:tickets: 2835

The "name" attribute is set on :class:`.Index` before the "attach"
events are called, so that attachment events can be used to dynamically
generate a name for the index based on the parent table and/or
columns.

.. change::
:tags: bug, engine
:tickets: 2748

The method signature of :meth:`.Dialect.reflecttable`, which in
all known cases is provided by :class:`.DefaultDialect`, has been
tightened to expect ``include_columns`` and ``exclude_columns``
arguments without any kw option, reducing ambiguity - previously
``exclude_columns`` was missing.

.. change::
:tags: bug, sql
:tickets: 2831

The erroneous kw arg "schema" has been removed from the :class:`.ForeignKey`
object. this was an accidental commit that did nothing; a warning is raised
in 0.8.3 when this kw arg is used.

.. change::
:tags: feature, orm
:tickets: 1418

Added a new load option :func:`.orm.load_only`.  This allows a series
of column names to be specified as loading "only" those attributes,
deferring the rest.

.. change::
:tags: feature, orm
:tickets: 1418

The system of loader options has been entirely rearchitected to build
upon a much more comprehensive base, the :class:`.Load` object.  This
base allows any common loader option like :func:`.joinedload`,
:func:`.defer`, etc. to be used in a "chained" style for the purpose
of specifying options down a path, such as ``joinedload("foo").subqueryload("bar")``.
The new system supersedes the usage of dot-separated path names,
multiple attributes within options, and the usage of ``_all()`` options.

.. seealso::

:ref:`feature_1418`

.. change::
:tags: feature, orm
:tickets: 2824

The :func:`.composite` construct now maintains the return object
when used in a column-oriented :class:`.Query`, rather than expanding
out into individual columns.  This makes use of the new :class:`.Bundle`
feature internally.  This behavior is backwards incompatible; to
select from a composite column which will expand out, use
``MyClass.some_composite.clauses``.

.. seealso::

:ref:`migration_2824`

.. change::
:tags: feature, orm
:tickets: 2824

A new construct :class:`.Bundle` is added, which allows for specification
of groups of column expressions to a :class:`.Query` construct.
The group of columns are returned as a single tuple by default.  The
behavior of :class:`.Bundle` can be overridden however to provide
any sort of result processing to the returned row.  The behavior
of :class:`.Bundle` is also embedded into composite attributes now
when they are used in a column-oriented :class:`.Query`.

.. seealso::

:ref:`change_2824`

:ref:`migration_2824`

.. change::
:tags: bug, sql
:tickets: 2812

A rework to the way that "quoted" identifiers are handled, in that
instead of relying upon various ``quote=True`` flags being passed around,
these flags are converted into rich string objects with quoting information
included at the point at which they are passed to common schema constructs
like :class:`.Table`, :class:`.Column`, etc.   This solves the issue
of various methods that don't correctly honor the "quote" flag such
as :meth:`.Engine.has_table` and related methods.  The :class:`.quoted_name`
object is a string subclass that can also be used explicitly if needed;
the object will hold onto the quoting preferences passed and will
also bypass the "name normalization" performed by dialects that
standardize on uppercase symbols, such as Oracle, Firebird and DB2.
The upshot is that the "uppercase" backends can now work with force-quoted
names, such as lowercase-quoted names and new reserved words.

.. seealso::

:ref:`change_2812`

.. change::
:tags: feature, orm
:tickets: 2793

The ``version_id_generator`` parameter of ``Mapper`` can now be specified
to rely upon server generated version identifiers, using triggers
or other database-provided versioning features, or via an optional programmatic
value, by setting ``version_id_generator=False``.
When using a server-generated version identifier, the ORM will use RETURNING when
available to immediately
load the new version value, else it will emit a second SELECT.

.. change::
:tags: feature, orm
:tickets: 2793

The ``eager_defaults`` flag of :class:`.Mapper` will now allow the
newly generated default values to be fetched using an inline
RETURNING clause, rather than a second SELECT statement, for backends
that support RETURNING.

.. change::
:tags: feature, core
:tickets: 2793

Added a new variant to :meth:`.UpdateBase.returning` called
:meth:`.ValuesBase.return_defaults`; this allows arbitrary columns
to be added to the RETURNING clause of the statement without interfering
with the compilers usual "implicit returning" feature, which is used to
efficiently fetch newly generated primary key values.  For supporting
backends, a dictionary of all fetched values is present at
:attr:`.ResultProxy.returned_defaults`.

.. change::
:tags: bug, mysql

Improved support for the cymysql driver, supporting version 0.6.5,
courtesy Hajime Nakagami.

.. change::
:tags: general

A large refactoring of packages has reorganized
the import structure of many Core modules as well as some aspects
of the ORM modules.  In particular ``sqlalchemy.sql`` has been broken
out into several more modules than before so that the very large size
of ``sqlalchemy.sql.expression`` is now pared down.   The effort
has focused on a large reduction in import cycles.   Additionally,
the system of API functions in ``sqlalchemy.sql.expression`` and
``sqlalchemy.orm`` has been reorganized to eliminate redundancy
in documentation between the functions vs. the objects they produce.

.. change::
:tags: orm, feature, orm

Added a new attribute :attr:`.Session.info` to :class:`.Session`;
this is a dictionary where applications can store arbitrary
data local to a :class:`.Session`.
The contents of :attr:`.Session.info` can be also be initialized
using the ``info`` argument of :class:`.Session` or
:class:`.sessionmaker`.


.. change::
:tags: feature, general, py3k
:tickets: 2161

The C extensions are ported to Python 3 and will build under
any supported CPython 2 or 3 environment.

.. change::
:tags: feature, orm
:tickets: 2268

Removal of event listeners is now implemented.    The feature is
provided via the :func:`.event.remove` function.

.. seealso::

:ref:`feature_2268`

.. change::
:tags: feature, orm
:tickets: 2789

The mechanism by which attribute events pass along an
:class:`.AttributeImpl` as an "initiator" token has been changed;
the object is now an event-specific object called :class:`.attributes.Event`.
Additionally, the attribute system no longer halts events based
on a matching "initiator" token; this logic has been moved to be
specific to ORM backref event handlers, which are the typical source
of the re-propagation of an attribute event onto subsequent append/set/remove
operations.  End user code which emulates the behavior of backrefs
must now ensure that recursive event propagation schemes are halted,
if the scheme does not use the backref handlers.   Using this new system,
backref handlers can now perform a
"two-hop" operation when an object is appended to a collection,
associated with a new many-to-one, de-associated with the previous
many-to-one, and then removed from a previous collection.   Before this
change, the last step of removal from the previous collection would
not occur.

.. seealso::

:ref:`migration_2789`

.. change::
:tags: feature, sql
:tickets: 722

Added new method to the :func:`.insert` construct
:meth:`.Insert.from_select`.  Given a list of columns and
a selectable, renders ``INSERT INTO (table) (columns) SELECT ..``.
While this feature is highlighted as part of 0.9 it is also
backported to 0.8.3.

.. seealso::

:ref:`feature_722`

.. change::
:tags: feature, engine
:tickets: 2770

New events added to :class:`.ConnectionEvents`:

* :meth:`.ConnectionEvents.engine_connect`
* :meth:`.ConnectionEvents.set_connection_execution_options`
* :meth:`.ConnectionEvents.set_engine_execution_options`

.. change::
:tags: bug, sql
:tickets: 1765

The resolution of :class:`.ForeignKey` objects to their
target :class:`.Column` has been reworked to be as
immediate as possible, based on the moment that the
target :class:`.Column` is associated with the same
:class:`.MetaData` as this :class:`.ForeignKey`, rather
than waiting for the first time a join is constructed,
or similar. This along with other improvements allows
earlier detection of some foreign key configuration
issues.  Also included here is a rework of the
type-propagation system, so that
it should be reliable now to set the type as ``None``
on any :class:`.Column` that refers to another via
:class:`.ForeignKey` - the type will be copied from the
target column as soon as that other column is associated,
and now works for composite foreign keys as well.

.. seealso::

:ref:`migration_1765`

.. change::
:tags: feature, sql
:tickets: 2744, 2734

Provided a new attribute for :class:`.TypeDecorator`
called :attr:`.TypeDecorator.coerce_to_is_types`,
to make it easier to control how comparisons using
``==`` or ``!=`` to ``None`` and boolean types goes
about producing an ``IS`` expression, or a plain
equality expression with a bound parameter.

.. change::
:tags: feature, pool
:tickets: 2752

Added pool logging for "rollback-on-return" and the less used
"commit-on-return".  This is enabled with the rest of pool
"debug" logging.

.. change::
:tags: bug, orm, associationproxy
:tickets: 2751

Added additional criterion to the ==, != comparators, used with
scalar values, for comparisons to None to also take into account
the association record itself being non-present, in addition to the
existing test for the scalar endpoint on the association record
being NULL.  Previously, comparing ``Cls.scalar == None`` would return
records for which ``Cls.associated`` were present and
``Cls.associated.scalar`` is None, but not rows for which
``Cls.associated`` is non-present.  More significantly, the
inverse operation ``Cls.scalar != None`` *would* return ``Cls``
rows for which ``Cls.associated`` was non-present.

The case for ``Cls.scalar != 'somevalue'`` is also modified
to act more like a direct SQL comparison; only rows for
which ``Cls.associated`` is present and ``Associated.scalar``
is non-NULL and not equal to ``'somevalue'`` are returned.
Previously, this would be a simple ``NOT EXISTS``.

Also added a special use case where you
can call ``Cls.scalar.has()`` with no arguments,
when ``Cls.scalar`` is a column-based value - this returns whether or
not ``Cls.associated`` has any rows present, regardless of whether
or not ``Cls.associated.scalar`` is NULL or not.

.. seealso::

:ref:`migration_2751`


.. change::
:tags: feature, orm
:tickets: 2587

A major change regarding how the ORM constructs joins where
the right side is itself a join or left outer join.   The ORM
is now configured to allow simple nesting of joins of
the form ``a JOIN (b JOIN c ON b.id=c.id) ON a.id=b.id``,
rather than forcing the right side into a ``SELECT`` subquery.
This should allow significant performance improvements on most
backends, most particularly MySQL.   The one database backend
that has for many years held back this change, SQLite, is now addressed by
moving the production of the ``SELECT`` subquery from the
ORM to the SQL compiler; so that a right-nested join on SQLite will still
ultimately render with a ``SELECT``, while all other backends
are no longer impacted by this workaround.

As part of this change, a new argument ``flat=True`` has been added
to the :func:`.orm.aliased`, :meth:`.Join.alias`, and
:func:`.orm.with_polymorphic` functions, which allows an "alias" of a
JOIN to be produced which applies an anonymous alias to each component
table within the join, rather than producing a subquery.

.. seealso::

:ref:`feature_joins_09`


.. change::
:tags: bug, orm
:tickets: 2369

Fixed an obscure bug where the wrong results would be
fetched when joining/joinedloading across a many-to-many
relationship to a single-table-inheriting
subclass with a specific discriminator value, due to "secondary"
rows that would come back.  The "secondary" and right-side
tables are now inner joined inside of parenthesis for all
ORM joins on many-to-many relationships so that the left->right
join can accurately filtered.  This change was made possible
by finally addressing the issue with right-nested joins
outlined in :ticket:`2587`.

.. seealso::

:ref:`feature_joins_09`

.. change::
:tags: bug, mssql, pyodbc
:tickets: 2355

Fixes to MSSQL with Python 3 + pyodbc, including that statements
are passed correctly.

.. change::
:tags: feature, sql
:tickets: 1068

A :func:`~sqlalchemy.sql.expression.label` construct will now render as its name alone
in an ``ORDER BY`` clause, if that label is also referred to
in the columns clause of the select, instead of rewriting the
full expression.  This gives the database a better chance to
optimize the evaluation of the same expression in two different
contexts.

.. seealso::

:ref:`migration_1068`

.. change::
:tags: feature, firebird
:tickets: 2504

The ``fdb`` dialect is now the default dialect when
specified without a dialect qualifier, i.e. ``firebird://``,
per the Firebird project publishing ``fdb`` as their
official Python driver.

.. change::
:tags: feature, general, py3k
:tickets: 2671

The codebase is now "in-place" for Python
2 and 3, the need to run 2to3 has been removed.
Compatibility is now against Python 2.6 on forward.

.. change::
:tags: feature, oracle, py3k

The Oracle unit tests with cx_oracle now pass
fully under Python 3.

.. change::
:tags: bug, orm
:tickets: 2736

The "auto-aliasing" behavior of the :meth:`.Query.select_from`
method has been turned off.  The specific behavior is now
available via a new method :meth:`.Query.select_entity_from`.
The auto-aliasing behavior here was never well documented and
is generally not what's desired, as :meth:`.Query.select_from`
has become more oriented towards controlling how a JOIN is
rendered.  :meth:`.Query.select_entity_from` will also be made
available in 0.8 so that applications which rely on the auto-aliasing
can shift their applications to use this method.

.. seealso::

:ref:`migration_2736`




=============
1.0 Changelog
=============

.. changelog_imports::

.. include:: changelog_09.rst
:start-line: 5

.. include:: changelog_08.rst
:start-line: 5

.. include:: changelog_07.rst
:start-line: 5


.. changelog::

0.8.7

:released: July 22, 2014

.. change::
:tags: bug, mssql
:versions: 1.0.0b1, 0.9.7

Added statement encoding to the "SET IDENTITY_INSERT"
statements which operate when an explicit INSERT is being
interjected into an IDENTITY column, to support non-ascii table
identifiers on drivers such as pyodbc + unix + py2k that don't
support unicode statements.

.. change::
:tags: bug, mssql
:versions: 1.0.0b1, 0.9.7
:tickets: 3091

In the SQL Server pyodbc dialect, repaired the implementation
for the ``description_encoding`` dialect parameter, which when
not explicitly set was preventing  cursor.description from
being parsed correctly in the case of result sets that
contained names in alternate encodings.  This parameter
shouldn't be needed going forward.

.. change::
:tags: bug, sql
:versions: 1.0.0b1, 0.9.7
:tickets: 3124

Fixed bug in :class:`.Enum` and other :class:`.SchemaType`
subclasses where direct association of the type with a
:class:`.MetaData` would lead to a hang when events
(like create events) were emitted on the :class:`.MetaData`.

.. change::
:tags: bug, sql
:versions: 1.0.0b1, 0.9.7
:tickets: 3102

Fixed a bug within the custom operator plus :meth:`.TypeEngine.with_variant`
system, whereby using a :class:`.TypeDecorator` in conjunction with
variant would fail with an MRO error when a comparison operator was used.

.. change::
:tags: bug, mysql
:versions: 1.0.0b1, 0.9.7
:tickets: 3101

MySQL error 2014 "commands out of sync" appears to be raised as a
ProgrammingError, not OperationalError, in modern MySQL-Python versions;
all MySQL error codes that are tested for "is disconnect" are now
checked within OperationalError and ProgrammingError regardless.

.. change::
:tags: bug, mysql
:versions: 1.0.0b1, 0.9.5
:tickets: 3085

Fixed bug where column names added to ``mysql_length`` parameter
on an index needed to have the same quoting for quoted names in
order to be recognized.  The fix makes the quotes optional but
also provides the old behavior for backwards compatibility with those
using the workaround.

.. change::
:tags: bug, declarative
:versions: 1.0.0b1, 0.9.5
:tickets: 3062

The ``__mapper_args__`` dictionary is copied from a declarative
mixin or abstract class when accessed, so that modifications made
to this dictionary by declarative itself won't conflict with that
of other mappings.  The dictionary is modified regarding the
``version_id_col`` and ``polymorphic_on`` arguments, replacing the
column within with the one that is officially mapped to the local
class/table.

.. change::
:tags: bug, sql
:versions: 0.9.5, 1.0.0b1
:tickets: 3044

Fixed bug in INSERT..FROM SELECT construct where selecting from a
UNION would wrap the union in an anonymous (e.g. unlabeled) subquery.

.. change::
:tags: bug, postgresql
:versions: 0.9.5, 1.0.0b1
:tickets: 3053

Added the ``hashable=False`` flag to the PG :class:`.HSTORE` type, which
is needed to allow the ORM to skip over trying to "hash" an ORM-mapped
HSTORE column when requesting it in a mixed column/entity list.
Patch courtesy Gunnlaugur Þór Briem.

.. change::
:tags: bug, orm
:versions: 0.9.5, 1.0.0b1
:tickets: 3055

Fixed bug in subquery eager loading where a long chain of
eager loads across a polymorphic-subclass boundary in conjunction
with polymorphic loading would fail to locate the subclass-link in the
chain, erroring out with a missing property name on an
:class:`.AliasedClass`.

.. change::
:tags: bug, ext
:versions: 0.9.5, 1.0.0b1
:tickets: 3051, 3093

Fixed bug in mutable extension where :class:`.MutableDict` did not
report change events for the ``setdefault()`` dictionary operation.

.. change::
:tags: bug, ext
:versions: 0.9.5, 1.0.0b1
:tickets: 3093, 3051

Fixed bug where :meth:`.MutableDict.setdefault` didn't return the
existing or new value (this bug was not released in any 0.8 version).
Pull request courtesy Thomas Hervé.

.. change::
:tags: bug, mysql
:versions: 0.9.5, 1.0.0b1

Added support for reflecting tables where an index includes
KEY_BLOCK_SIZE using an equal sign.  Pull request courtesy
Sean McGivern.

.. change::
:tags: bug, orm
:tickets: 3047
:versions: 0.9.5, 1.0.0b1

Fixed ORM bug where the :func:`.class_mapper` function would mask
AttributeErrors or KeyErrors that should raise during mapper
configuration due to user errors.  The catch for attribute/keyerror
has been made more specific to not include the configuration step.

.. change::
:tags: bug, sql
:tickets: 3045
:versions: 0.9.5, 1.0.0b1

Fixed bug where :meth:`.Table.update` and :meth:`.Table.delete`
would produce an empty WHERE clause when an empty :func:`.and_()`
or :func:`.or_()` or other blank expression were applied.  This is
now consistent with that of :func:`.select`.

.. change::
:tags: bug, postgresql
:versions: 0.9.5, 1.0.0b1

Added a new "disconnect" message "connection has been closed unexpectedly".
This appears to be related to newer versions of SSL.
Pull request courtesy Antti Haapala.

.. changelog::

0.8.6

:released: March 28, 2014

.. change::
:tags: bug, orm
:tickets: 3006
:versions: 0.9.4

Fixed ORM bug where changing the primary key of an object, then marking
it for DELETE would fail to target the correct row for DELETE.

.. change::
:tags: feature, postgresql
:versions: 0.9.4

Enabled "sane multi-row count" checking for the psycopg2 DBAPI, as
this seems to be supported as of psycopg2 2.0.9.

.. change::
:tags: bug, postgresql
:tickets: 3000
:versions: 0.9.4

Fixed regression caused by release 0.8.5 / 0.9.3's compatibility
enhancements where index reflection on PostgreSQL versions specific
to only the 8.1, 8.2 series again
broke, surrounding the ever problematic int2vector type.  While
int2vector supports array operations as of 8.1, apparently it only
supports CAST to a varchar as of 8.3.

.. change::
:tags: bug, orm
:tickets: 2995,
:versions: 0.9.4

Fixed regression from 0.8.3 as a result of :ticket:`2818`
where :meth:`.Query.exists` wouldn't work on a query that only
had a :meth:`.Query.select_from` entry but no other entities.

.. change::
:tags: bug, general
:tickets: 2986
:versions: 0.9.4

Adjusted ``setup.py`` file to support the possible future
removal of the ``setuptools.Feature`` extension from setuptools.
If this keyword isn't present, the setup will still succeed
with setuptools rather than falling back to distutils.  C extension
building can be disabled now also by setting the
DISABLE_SQLALCHEMY_CEXT environment variable.  This variable works
whether or not setuptools is even available.

.. change::
:tags: bug, ext
:versions: 0.9.4
:tickets: 2997

Fixed bug in mutable extension as well as
:func:`.attributes.flag_modified` where the change event would not be
propagated if the attribute had been reassigned to itself.

.. change::
:tags: bug, orm
:versions: 0.9.4

Improved an error message which would occur if a query() were made
against a non-selectable, such as a :func:`.literal_column`, and then
an attempt was made to use :meth:`.Query.join` such that the "left"
side would be determined as ``None`` and then fail.  This condition
is now detected explicitly.

.. change::
:tags: bug, sql
:versions: 0.9.4
:tickets: 2977

Fixed bug in :func:`.tuple_` construct where the "type" of essentially
the first SQL expression would be applied as the "comparison type"
to a compared tuple value; this has the effect in some cases of an
inappropriate "type coercion" occurring, such as when a tuple that
has a mix of String and Binary values improperly coerces target
values to Binary even though that's not what they are on the left
side.  :func:`.tuple_` now expects heterogeneous types within its
list of values.

.. change::
:tags: orm, bug
:versions: 0.9.4
:tickets: 2975

Removed stale names from ``sqlalchemy.orm.interfaces.__all__`` and
refreshed with current names, so that an ``import *`` from this
module again works.

.. changelog::

0.8.5

:released: February 19, 2014

.. change::
:tags: postgresql, bug
:versions: 0.9.3
:tickets: 2936

Added an additional message to psycopg2 disconnect detection,
"could not send data to server", which complements the existing
"could not receive data from server" and has been observed by users.

.. change::
:tags: postgresql, bug
:versions: 0.9.3

Support has been improved for PostgreSQL reflection behavior on very old
(pre 8.1) versions of PostgreSQL, and potentially other PG engines
such as Redshift (assuming Redshift reports the version as < 8.1).
The query for "indexes" as well as "primary keys" relies upon inspecting
a so-called "int2vector" datatype, which refuses to coerce to an array
prior to 8.1 causing failures regarding the "ANY()" operator used
in the query.  Extensive googling has located the very hacky, but
recommended-by-PG-core-developer query to use when PG version < 8.1
is in use, so index and primary key constraint reflection now work
on these versions.


.. change::
:tags: feature, mysql
:versions: 0.9.3
:tickets: 2941

Added new MySQL-specific :class:`.mysql.DATETIME` which includes
fractional seconds support; also added fractional seconds support
to :class:`.mysql.TIMESTAMP`.  DBAPI support is limited, though
fractional seconds are known to be supported by MySQL Connector/Python.
Patch courtesy Geert JM Vanderkelen.

.. change::
:tags: bug, mysql
:versions: 0.9.3
:tickets: 2966

Added support for the ``PARTITION BY`` and ``PARTITIONS``
MySQL table keywords, specified as ``mysql_partition_by='value'`` and
``mysql_partitions='value'`` to :class:`.Table`.  Pull request
courtesy Marcus McCurdy.

.. change::
:tags: bug, sql
:versions: 0.9.3
:tickets: 2944

Fixed bug where calling :meth:`.Insert.values` with an empty list
or tuple would raise an IndexError.   It now produces an empty
insert construct as would be the case with an empty dictionary.

.. change::
:tags: bug, engine, pool
:versions: 0.9.3
:tickets: 2880, 2964

Fixed a critical regression caused by :ticket:`2880` where the newly
concurrent ability to return connections from the pool means that the
"first_connect" event is now no longer synchronized either, thus leading
to dialect mis-configurations under even minimal concurrency situations.

.. change::
:tags: bug, sqlite

Restored a change that was missed in the backport of unique
constraint reflection to 0.8, where :class:`.UniqueConstraint`
with SQLite would fail if reserved keywords were included in the
names of columns.  Pull request courtesy Roman Podolyaka.

.. change::
:tags: bug, postgresql
:tickets: 2291
:versions: 0.9.3

Revised this very old issue where the PostgreSQL "get primary key"
reflection query were updated to take into account primary key constraints
that were renamed; the newer query fails on very old versions of
PostgreSQL such as version 7, so the old query is restored in those cases
when server_version_info < (8, 0) is detected.

.. change::
:tags: bug, sql
:tickets: 2957
:versions: 0.9.3

Fixed bug where :meth:`.in_()` would go into an endless loop if
erroneously passed a column expression whose comparator included
the ``__getitem__()`` method, such as a column that uses the
:class:`.postgresql.ARRAY` type.

.. change::
:tags: bug, orm
:tickets: 2951
:versions: 0.9.3

Fixed bug where :meth:`.Query.get` would fail to consistently
raise the :class:`.InvalidRequestError` that invokes when called
on a query with existing criterion, when the given identity is
already present in the identity map.

.. change::
:tags: bug, mysql
:tickets: 2933
:versions: 0.9.3

Fixed bug which prevented MySQLdb-based dialects (e.g.
pymysql) from working in Py3K, where a check for "connection
charset" would fail due to Py3K's more strict value comparison
rules.  The call in question  wasn't taking the database
version into account in any case as the server version was
still None at that point, so the method overall has been
simplified to rely upon connection.character_set_name().

.. change::
:tags: bug, mysql
:versions: 0.9.2

Some missing methods added to the cymysql dialect, including
_get_server_version_info() and _detect_charset().  Pullreq
courtesy Hajime Nakagami.

.. change::
:tags: bug, py3k

Fixed Py3K bug where a missing import would cause "literal binary"
mode to fail to import "util.binary_type" when rendering a bound
parameter.  0.9 handles this differently. Pull request courtesy
Andreas Zeidler.

.. change::
:tags: bug, orm
:versions: 0.9.2

Fixed error message when an iterator object is passed to
:func:`.class_mapper` or similar, where the error would fail to
render on string formatting.  Pullreq courtesy Kyle Stark.

.. change::
:tags: bug, firebird
:versions: 0.9.0
:tickets: 2897

The firebird dialect will quote identifiers which begin with an
underscore.  Courtesy Treeve Jelbert.

.. change::
:tags: bug, firebird
:versions: 0.9.0

Fixed bug in Firebird index reflection where the columns within the
index were not sorted correctly; they are now sorted
in order of RDB$FIELD_POSITION.

.. change::
:tags: bug, mssql, firebird
:versions: 0.9.0

The "asdecimal" flag used with the :class:`.Float` type will now
work with Firebird as well as the mssql+pyodbc dialects; previously the
decimal conversion was not occurring.

.. change::
:tags: bug, mssql, pymssql
:versions: 0.9.0

Added "Net-Lib error during Connection reset by peer" message
to the list of messages checked for "disconnect" within the
pymssql dialect.  Courtesy John Anderson.

.. change::
:tags: bug, sql
:versions: 0.9.0
:tickets: 2896

Fixed issue where a primary key column that has a Sequence on it,
yet the column is not the "auto increment" column, either because
it has a foreign key constraint or ``autoincrement=False`` set,
would attempt to fire the Sequence on INSERT for backends that don't
support sequences, when presented with an INSERT missing the primary
key value.  This would take place on non-sequence backends like
SQLite, MySQL.

.. change::
:tags: bug, sql
:versions: 0.9.0
:tickets: 2895

Fixed bug with :meth:`.Insert.from_select` method where the order
of the given names would not be taken into account when generating
the INSERT statement, thus producing a mismatch versus the column
names in the given SELECT statement.  Also noted that
:meth:`.Insert.from_select` implies that Python-side insert defaults
cannot be used, since the statement has no VALUES clause.

.. change::
:tags: enhancement, sql
:versions: 0.9.0

The exception raised when a :class:`.BindParameter` is present
in a compiled statement without a value now includes the key name
of the bound parameter in the error message.

.. change::
:tags: bug, orm
:versions: 0.9.0
:tickets: 2887

An adjustment to the :func:`.subqueryload` strategy which ensures that
the query runs after the loading process has begun; this is so that
the subqueryload takes precedence over other loaders that may be
hitting the same attribute due to other eager/noload situations
at the wrong time.

.. change::
:tags: bug, orm
:versions: 0.9.0
:tickets: 2885

Fixed bug when using joined table inheritance from a table to a
select/alias on the base, where the PK columns were also not same
named; the persistence system would fail to copy primary key values
from the base table to the inherited table upon INSERT.

.. change::
:tags: bug, orm
:versions: 0.9.0
:tickets: 2889

:func:`.composite` will raise an informative error message when the
columns/attribute (names) passed don't resolve to a Column or mapped
attribute (such as an erroneous tuple); previously raised an unbound
local.

.. change::
:tags: bug, declarative
:versions: 0.9.0
:tickets: 2888

Error message when a string arg sent to :func:`.relationship` which
doesn't resolve to a class or mapper has been corrected to work
the same way as when a non-string arg is received, which indicates
the name of the relationship which had the configurational error.

.. changelog::

0.8.4

:released: December 8, 2013

.. change::
:tags: bug, engine
:versions: 0.9.0
:tickets: 2881

A DBAPI that raises an error on ``connect()`` which is not a subclass
of dbapi.Error (such as ``TypeError``, ``NotImplementedError``, etc.)
will propagate the exception unchanged.  Previously,
the error handling specific to the ``connect()`` routine would both
inappropriately run the exception through the dialect's
:meth:`.Dialect.is_disconnect` routine as well as wrap it in
a :class:`sqlalchemy.exc.DBAPIError`.  It is now propagated unchanged
in the same way as occurs within the execute process.

.. change::
:tags: bug, engine, pool
:versions: 0.9.0
:tickets: 2880

The :class:`.QueuePool` has been enhanced to not block new connection
attempts when an existing connection attempt is blocking.  Previously,
the production of new connections was serialized within the block
that monitored overflow; the overflow counter is now altered within
its own critical section outside of the connection process itself.

.. change::
:tags: bug, engine, pool
:versions: 0.9.0
:tickets: 2522

Made a slight adjustment to the logic which waits for a pooled
connection to be available, such that for a connection pool
with no timeout specified, it will every half a second break out of
the wait to check for the so-called "abort" flag, which allows the
waiter to break out in case the whole connection pool was dumped;
normally the waiter should break out due to a notify_all() but it's
possible this notify_all() is missed in very slim cases.
This is an extension of logic first introduced in 0.8.0, and the
issue has only been observed occasionally in stress tests.

.. change::
:tags: bug, mssql
:versions: 0.9.0

Fixed bug introduced in 0.8.0 where the ``DROP INDEX``
statement for an index in MSSQL would render incorrectly if the
index were in an alternate schema; the schemaname/tablename
would be reversed.  The format has been also been revised to
match current MSSQL documentation.  Courtesy Derek Harland.

.. change::
:tags: feature, sql
:tickets: 1443
:versions: 0.9.0b1

Added support for "unique constraint" reflection, via the
:meth:`.Inspector.get_unique_constraints` method.
Thanks for Roman Podolyaka for the patch.

.. change::
:tags: bug, oracle
:tickets: 2864
:versions: 0.9.0

Added ORA-02396 "maximum idle time" error code to list of
"is disconnect" codes with cx_oracle.

.. change::
:tags: bug, engine
:tickets: 2871
:versions: 0.9.0

Fixed bug where SQL statement would be improperly ASCII-encoded
when a pre-DBAPI :class:`.StatementError` were raised within
:meth:`.Connection.execute`, causing encoding errors for
non-ASCII statements.  The stringification now remains within
Python unicode thus avoiding encoding errors.

.. change::
:tags: bug, oracle
:tickets: 2870
:versions: 0.9.0

Fixed bug where Oracle ``VARCHAR`` types given with no length
(e.g. for a ``CAST`` or similar) would incorrectly render ``None CHAR``
or similar.

.. change::
:tags: bug, ext
:tickets: 2869
:versions: 0.9.0

Fixed bug which prevented the ``serializer`` extension from working
correctly with table or column names that contain non-ASCII
characters.

.. change::
:tags: bug, orm
:tickets: 2818
:versions: 0.9.0

Fixed a regression introduced by :ticket:`2818` where the EXISTS
query being generated would produce a "columns being replaced"
warning for a statement with two same-named columns,
as the internal SELECT wouldn't have use_labels set.

.. change::
:tags: bug, postgresql
:tickets: 2855
:versions: 0.9.0

Fixed bug where index reflection would mis-interpret indkey values
when using the pypostgresql adapter, which returns these values
as lists vs. psycopg2's return type of string.

.. changelog::

0.8.3

:released: October 26, 2013

.. change::
:tags: bug, oracle
:tickets: 2853
:versions: 0.9.0b1

Fixed bug where Oracle table reflection using synonyms would fail
if the synonym and the table were in different remote schemas.
Patch to fix courtesy Kyle Derr.

.. change::
:tags: bug, sql
:tickets: 2849
:versions: 0.9.0b1

Fixed bug where :func:`.type_coerce` would not interpret ORM
elements with a ``__clause_element__()`` method properly.

.. change::
:tags: bug, sql
:tickets: 2842
:versions: 0.9.0b1

The :class:`.Enum` and :class:`.Boolean` types now bypass
any custom (e.g. TypeDecorator) type in use when producing the
CHECK constraint for the "non native" type.  This so that the custom type
isn't involved in the expression within the CHECK, since this
expression is against the "impl" value and not the "decorated" value.

.. change::
:tags: bug, postgresql
:tickets: 2844
:versions: 0.9.0b1

Removed a 128-character truncation from the reflection of the
server default for a column; this code was original from
PG system views which truncated the string for readability.

.. change::
:tags: bug, mysql
:tickets: 2721, 2839
:versions: 0.9.0b1

The change in :ticket:`2721`, which is that the ``deferrable`` keyword
of :class:`.ForeignKeyConstraint` is silently ignored on the MySQL
backend, will be reverted as of 0.9; this keyword will now render again, raising
errors on MySQL as it is not understood - the same behavior will also
apply to the ``initially`` keyword.  In 0.8, the keywords will remain
ignored but a warning is emitted.   Additionally, the ``match`` keyword
now raises a :exc:`.CompileError` on 0.9 and emits a warning on 0.8;
this keyword is not only silently ignored by MySQL but also breaks
the ON UPDATE/ON DELETE options.

To use a :class:`.ForeignKeyConstraint`
that does not render or renders differently on MySQL, use a custom
compilation option.  An example of this usage has been added to the
documentation, see :ref:`mysql_foreign_keys`.

.. change::
:tags: bug, sql
:tickets: 2825
:versions: 0.9.0b1

The ``.unique`` flag on :class:`.Index` could be produced as ``None``
if it was generated from a :class:`.Column` that didn't specify ``unique``
(where it defaults to ``None``).  The flag will now always be ``True`` or
``False``.

.. change::
:tags: feature, orm
:tickets: 2836
:versions: 0.9.0b1

Added new option to :func:`.relationship` ``distinct_target_key``.
This enables the subquery eager loader strategy to apply a DISTINCT
to the innermost SELECT subquery, to assist in the case where
duplicate rows are generated by the innermost query which corresponds
to this relationship (there's not yet a general solution to the issue
of dupe rows within subquery eager loading, however, when joins outside
of the innermost subquery produce dupes).  When the flag
is set to ``True``, the DISTINCT is rendered unconditionally, and when
it is set to ``None``, DISTINCT is rendered if the innermost relationship
targets columns that do not comprise a full primary key.
The option defaults to False in 0.8 (e.g. off by default in all cases),
None in 0.9 (e.g. automatic by default).   Thanks to Alexander Koval
for help with this.

.. seealso::

:ref:`change_2836`

.. change::
:tags: bug, mysql
:tickets: 2515
:versions: 0.9.0b1

MySQL-connector dialect now allows options in the create_engine
query string to override those defaults set up in the connect,
including "buffered" and "raise_on_warnings".

.. change::
:tags: bug, postgresql
:tickets: 2742
:versions: 0.9.0b1

Parenthesis will be applied to a compound SQL expression as
rendered in the column list of a CREATE INDEX statement.

.. change::
:tags: bug, sql
:tickets: 2742
:versions: 0.9.0b1

Fixed bug in default compiler plus those of postgresql, mysql, and
mssql to ensure that any literal SQL expression values are
rendered directly as literals, instead of as bound parameters,
within a CREATE INDEX statement.  This also changes the rendering
scheme for other DDL such as constraints.

.. change::
:tags: bug, sql
:tickets: 2815
:versions: 0.9.0b1

A :func:`.select` that is made to refer to itself in its FROM clause,
typically via in-place mutation, will raise an informative error
message rather than causing a recursion overflow.

.. change::
:tags: bug, orm
:tickets: 2813
:versions: 0.9.0b1

Fixed bug where using an annotation such as :func:`.remote` or
:func:`.foreign` on a :class:`.Column` before association with a parent
:class:`.Table` could produce issues related to the parent table not
rendering within joins, due to the inherent copy operation performed
by an annotation.

.. change::
:tags: bug, sql
:tickets: 2831

Non-working "schema" argument on :class:`.ForeignKey` is deprecated;
raises a warning.  Removed in 0.9.

.. change::
:tags: bug, postgresql
:tickets: 2819
:versions: 0.9.0b1

Fixed bug where PostgreSQL version strings that had a prefix preceding
the words "PostgreSQL" or "EnterpriseDB" would not parse.
Courtesy Scott Schaefer.

.. change::
:tags: feature, engine
:tickets: 2821
:versions: 0.9.0b1

``repr()`` for the :class:`.URL` of an :class:`.Engine`
will now conceal the password using asterisks.
Courtesy Gunnlaugur Þór Briem.

.. change::
:tags: bug, orm
:tickets: 2818
:versions: 0.9.0b1

Fixed bug where :meth:`.Query.exists` failed to work correctly
without any WHERE criterion.  Courtesy Vladimir Magamedov.

.. change::
:tags: bug, sql
:tickets: 2811
:versions: 0.9.0b1

Fixed bug where using the ``column_reflect`` event to change the ``.key``
of the incoming :class:`.Column` would prevent primary key constraints,
indexes, and foreign key constraints from being correctly reflected.

.. change::
:tags: feature
:versions: 0.9.0b1

Added a new flag ``system=True`` to :class:`.Column`, which marks
the column as a "system" column which is automatically made present
by the database (such as PostgreSQL ``oid`` or ``xmin``).  The
column will be omitted from the ``CREATE TABLE`` statement but will
otherwise be available for querying.   In addition, the
:class:`.CreateColumn` construct can be applied to a custom
compilation rule which allows skipping of columns, by producing
a rule that returns ``None``.

.. change::
:tags: bug, orm
:tickets: 2779

Backported a change from 0.9 whereby the iteration of a hierarchy
of mappers used in polymorphic inheritance loads is sorted,
which allows the SELECT statements generated for polymorphic queries
to have deterministic rendering, which in turn helps with caching
schemes that cache on the SQL string itself.

.. change::
:tags: bug, orm
:tickets: 2794
:versions: 0.9.0b1

Fixed a potential issue in an ordered sequence implementation used
by the ORM to iterate mapper hierarchies; under the Jython interpreter
this implementation wasn't ordered, even though cPython and PyPy
maintained ordering.

.. change::
:tags: bug, examples
:versions: 0.9.0b1

Added "autoincrement=False" to the history table created in the
versioning example, as this table shouldn't have autoinc on it
in any case, courtesy Patrick Schmid.

.. change::
:tags: bug, sql
:versions: 0.9.0b1

The :meth:`.ColumnOperators.notin_` operator added in 0.8 now properly
produces the negation of the expression "IN" returns
when used against an empty collection.

.. change::
:tags: feature, examples
:versions: 0.9.0b1

Improved the examples in ``examples/generic_associations``, including
that ``discriminator_on_association.py`` makes use of single table
inheritance do the work with the "discriminator".  Also
added a true "generic foreign key" example, which works similarly
to other popular frameworks in that it uses an open-ended integer
to point to any other table, foregoing traditional referential
integrity.  While we don't recommend this pattern, information wants
to be free.

.. change::
:tags: feature, orm, declarative
:versions: 0.9.0b1

Added a convenience class decorator :func:`.as_declarative`, is
a wrapper for :func:`.declarative_base` which allows an existing base
class to be applied using a nifty class-decorated approach.

.. change::
:tags: bug, orm
:tickets: 2786
:versions: 0.9.0b1

Fixed bug in ORM-level event registration where the "raw" or
"propagate" flags could potentially be mis-configured in some
"unmapped base class" configurations.

.. change::
:tags: bug, orm
:tickets: 2778
:versions: 0.9.0b1

A performance fix related to the usage of the :func:`.defer` option
when loading mapped entities.   The function overhead of applying
a per-object deferred callable to an instance at load time was
significantly higher than that of just loading the data from the row
(note that ``defer()`` is meant to reduce DB/network overhead, not
necessarily function call count); the function call overhead is now
less than that of loading data from the column in all cases.  There
is also a reduction in the number of "lazy callable" objects created
per load from N (total deferred values in the result) to 1 (total
number of deferred cols).

.. change::
:tags: bug, sqlite
:tickets: 2781
:versions: 0.9.0b1

The newly added SQLite DATETIME arguments storage_format and
regexp apparently were not fully implemented correctly; while the
arguments were accepted, in practice they would have no effect;
this has been fixed.

.. change::
:tags: bug, sql, postgresql
:tickets: 2780
:versions: 0.9.0b1

Fixed bug where the expression system relied upon the ``str()``
form of a some expressions when referring to the ``.c`` collection
on a ``select()`` construct, but the ``str()`` form isn't available
since the element relies on dialect-specific compilation constructs,
notably the ``__getitem__()`` operator as used with a PostgreSQL
``ARRAY`` element.  The fix also adds a new exception class
:exc:`.UnsupportedCompilationError` which is raised in those cases
where a compiler is asked to compile something it doesn't know
how to.

.. change::
:tags: bug, engine, oracle
:tickets: 2776
:versions: 0.9.0b1

Dialect.initialize() is not called a second time if an :class:`.Engine`
is recreated, due to a disconnect error.   This fixes a particular
issue in the Oracle 8 dialect, but in general the dialect.initialize()
phase should only be once per dialect.

.. change::
:tags: feature, sql
:tickets: 722

Added new method to the :func:`.insert` construct
:meth:`.Insert.from_select`.  Given a list of columns and
a selectable, renders ``INSERT INTO (table) (columns) SELECT ..``.

.. change::
:tags: feature, sql
:versions: 0.9.0b1

The :func:`.update`, :func:`.insert`, and :func:`.delete` constructs
will now interpret ORM entities as target tables to be operated upon,
e.g.::

from sqlalchemy import insert, update, delete

ins = insert(SomeMappedClass).values(x=5)

del_ = delete(SomeMappedClass).where(SomeMappedClass.id == 5)

upd = update(SomeMappedClass).where(SomeMappedClass.id == 5).values(name='ed')

.. change::
:tags: bug, orm
:tickets: 2773
:versions: 0.9.0b1

Fixed bug whereby attribute history functions would fail
when an object we moved from "persistent" to "pending"
using the :func:`.make_transient` function, for operations
involving collection-based backrefs.

.. change::
:tags: bug, engine, pool
:tickets: 2772
:versions: 0.9.0b1

Fixed bug where :class:`.QueuePool` would lose the correct
checked out count if an existing pooled connection failed to reconnect
after an invalidate or recycle event.

.. changelog::

0.8.2

:released: July 3, 2013

.. change::
:tags: bug, mysql
:tickets: 2768
:versions: 0.9.0b1

Fixed bug when using multi-table UPDATE where a supplemental
table is a SELECT with its own bound parameters, where the positioning
of the bound parameters would be reversed versus the statement
itself when using MySQL's special syntax.

.. change::
:tags: bug, sqlite
:tickets: 2764
:versions: 0.9.0b1

Added :class:`sqlalchemy.types.BIGINT` to the list of type names that can be
reflected by the SQLite dialect; courtesy Russell Stuart.

.. change::
:tags: feature, orm, declarative
:tickets: 2761
:versions: 0.9.0b1

ORM descriptors such as hybrid properties can now be referenced
by name in a string argument used with ``order_by``,
``primaryjoin``, or similar in :func:`.relationship`,
in addition to column-bound attributes.

.. change::
:tags: feature, firebird
:tickets: 2763
:versions: 0.9.0b1

Added new flag ``retaining=True`` to the kinterbasdb and fdb dialects.
This controls the value of the ``retaining`` flag sent to the
``commit()`` and ``rollback()`` methods of the DBAPI connection.
Due to historical concerns, this flag defaults to ``True`` in 0.8.2,
however in 0.9.0b1 this flag defaults to ``False``.

.. change::
:tags: requirements
:versions: 0.9.0b1

The Python `mock <https://pypi.python.org/pypi/mock>`_ library
is now required in order to run the unit test suite.  While part
of the standard library as of Python 3.3, previous Python installations
will need to install this in order to run unit tests or to
use the ``sqlalchemy.testing`` package for external dialects.

.. change::
:tags: bug, orm
:tickets: 2750
:versions: 0.9.0b1

A warning is emitted when trying to flush an object of an inherited
class where the polymorphic discriminator has been assigned
to a value that is invalid for the class.

.. change::
:tags: bug, postgresql
:tickets: 2740
:versions: 0.9.0b1

The behavior of :func:`.extract` has been simplified on the
PostgreSQL dialect to no longer inject a hardcoded ``::timestamp``
or similar cast into the given expression, as this interfered
with types such as timezone-aware datetimes, but also
does not appear to be at all necessary with modern versions
of psycopg2.


.. change::
:tags: bug, firebird
:tickets: 2757
:versions: 0.9.0b1

Type lookup when reflecting the Firebird types LONG and
INT64 has been fixed so that LONG is treated as INTEGER,
INT64 treated as BIGINT, unless the type has a "precision"
in which case it's treated as NUMERIC.  Patch courtesy
Russell Stuart.

.. change::
:tags: bug, postgresql
:tickets: 2766
:versions: 0.9.0b1

Fixed bug in HSTORE type where keys/values that contained
backslashed quotes would not be escaped correctly when
using the "non native" (i.e. non-psycopg2) means
of translating HSTORE data.  Patch courtesy Ryan Kelly.

.. change::
:tags: bug, postgresql
:tickets: 2767
:versions: 0.9.0b1

Fixed bug where the order of columns in a multi-column
PostgreSQL index would be reflected in the wrong order.
Courtesy Roman Podolyaka.

.. change::
:tags: bug, sql
:tickets: 2746, 2668
:versions: 0.9.0b1

Multiple fixes to the correlation behavior of
:class:`.Select` constructs, first introduced in 0.8.0:

* To satisfy the use case where FROM entries should be
correlated outwards to a SELECT that encloses another,
which then encloses this one, correlation now works
across multiple levels when explicit correlation is
established via :meth:`.Select.correlate`, provided
that the target select is somewhere along the chain
contained by a WHERE/ORDER BY/columns clause, not
just nested FROM clauses. This makes
:meth:`.Select.correlate` act more compatibly to
that of 0.7 again while still maintaining the new
"smart" correlation.

* When explicit correlation is not used, the usual
"implicit" correlation limits its behavior to just
the immediate enclosing SELECT, to maximize compatibility
with 0.7 applications, and also prevents correlation
across nested FROMs in this case, maintaining compatibility
with 0.8.0/0.8.1.

* The :meth:`.Select.correlate_except` method was not
preventing the given FROM clauses from correlation in
all cases, and also would cause FROM clauses to be incorrectly
omitted entirely (more like what 0.7 would do),
this has been fixed.

* Calling `select.correlate_except(None)` will enter
all FROM clauses into correlation as would be expected.

.. change::
:tags: bug, ext
:versions: 0.9.0b1

Fixed bug whereby if a composite type were set up
with a function instead of a class, the mutable extension
would trip up when it tried to check that column
for being a :class:`.MutableComposite` (which it isn't).
Courtesy asldevi.

.. change::
:tags: feature, sql
:tickets: 2744, 2734

Provided a new attribute for :class:`.TypeDecorator`
called :attr:`.TypeDecorator.coerce_to_is_types`,
to make it easier to control how comparisons using
``==`` or ``!=`` to ``None`` and boolean types goes
about producing an ``IS`` expression, or a plain
equality expression with a bound parameter.

.. change::
:tags: feature, postgresql
:versions: 0.9.0b1

Support for PostgreSQL 9.2 range types has been added.
Currently, no type translation is provided, so works
directly with strings or psycopg2 2.5 range extension types
at the moment.  Patch courtesy Chris Withers.

.. change::
:tags: bug, examples
:versions: 0.9.0b1

Fixed an issue with the "versioning" recipe whereby a many-to-one
reference could produce a meaningless version for the target,
even though it was not changed, when backrefs were present.
Patch courtesy Matt Chisholm.

.. change::
:tags: feature, postgresql
:tickets: 2072
:versions: 0.9.0b1

Added support for "AUTOCOMMIT" isolation when using the psycopg2
DBAPI.   The keyword is available via the ``isolation_level``
execution option.  Patch courtesy Roman Podolyaka.

.. change::
:tags: bug, orm
:tickets: 2759
:versions: 0.9.0b1

Fixed bug in polymorphic SQL generation where multiple joined-inheritance
entities against the same base class joined to each other as well
would not track columns on the base table independently of each other if
the string of joins were more than two entities long.

.. change::
:tags: bug, engine
:versions: 0.9.0b1

Fixed bug where the ``reset_on_return`` argument to various :class:`.Pool`
implementations would not be propagated when the pool was regenerated.
Courtesy Eevee.

.. change::
:tags: bug, orm
:tickets: 2754
:versions: 0.9.0b1

Fixed bug where sending a composite attribute into :meth:`.Query.order_by`
would produce a parenthesized expression not accepted by some databases.

.. change::
:tags: bug, orm
:tickets: 2755
:versions: 0.9.0b1

Fixed the interaction between composite attributes and
the :func:`.aliased` function.  Previously, composite attributes
wouldn't work correctly in comparison operations when aliasing
was applied.

.. change::
:tags: bug, mysql
:tickets: 2715
:versions: 0.9.0b1

Added another conditional to the ``mysql+gaerdbms`` dialect to
detect so-called "development" mode, where we should use the
``rdbms_mysqldb`` DBAPI.  Patch courtesy Brett Slatkin.

.. change::
:tags: feature, mysql
:tickets: 2704
:versions: 0.9.0b1

The ``mysql_length`` parameter used with :class:`.Index` can now
be passed as a dictionary of column names/lengths, for use
with composite indexes.  Big thanks to Roman Podolyaka for the
patch.

.. change::
:tags: bug, mssql
:tickets: 2747
:versions: 0.9.0b1

When querying the information schema on SQL Server 2000, removed
a CAST call that was added in 0.8.1 to help with driver issues,
which apparently is not compatible on 2000.
The CAST remains in place for SQL Server 2005 and greater.

.. change::
:tags: bug, mysql
:tickets: 2721
:versions: 0.9.0b1

The ``deferrable`` keyword argument on :class:`.ForeignKey` and
:class:`.ForeignKeyConstraint` will not render the ``DEFERRABLE`` keyword
on the MySQL dialect.  For a long time we left this in place because
a non-deferrable foreign key would act very differently than a deferrable
one, but some environments just disable FKs on MySQL, so we'll be less
opinionated here.

.. change::
:tags: bug, ext, orm
:tickets: 2730
:versions: 0.9.0b1

Fixed bug where :class:`.MutableDict` didn't report a change event
when ``clear()`` was called.

.. change::
:tags: bug, sql
:tickets: 2738
:versions: 0.9.0b1

Fixed bug whereby joining a select() of a table "A" with multiple
foreign key paths to a table "B", to that table "B", would fail
to produce the "ambiguous join condition" error that would be
reported if you join table "A" directly to "B"; it would instead
produce a join condition with multiple criteria.

.. change::
:tags: bug, sql, reflection
:tickets: 2728
:versions: 0.9.0b1

Fixed bug whereby using :meth:`.MetaData.reflect` across a remote
schema as well as a local schema could produce wrong results
in the case where both schemas had a table of the same name.

.. change::
:tags: bug, sql
:tickets: 2726
:versions: 0.9.0b1

Removed the "not implemented" ``__iter__()`` call from the base
:class:`.ColumnOperators` class, while this was introduced
in 0.8.0 to prevent an endless, memory-growing loop when one also
implements a ``__getitem__()`` method on a custom
operator and then calls erroneously ``list()`` on that object,
it had the effect of causing column elements to report that they
were in fact iterable types which then throw an error when you try
to iterate.   There's no real way to have both sides here so we
stick with Python best practices.  Careful with implementing
``__getitem__()`` on your custom operators!

.. change::
:tags: feature, orm
:tickets: 2736

Added a new method :meth:`.Query.select_entity_from` which
will in 0.9 replace part of the functionality of
:meth:`.Query.select_from`.  In 0.8, the two methods perform
the same function, so that code can be migrated to use the
:meth:`.Query.select_entity_from` method as appropriate.
See the 0.9 migration guide for details.

.. change::
:tags: bug, orm
:tickets: 2737

Fixed a regression caused by :ticket:`2682` whereby the
evaluation invoked by :meth:`.Query.update` and :meth:`.Query.delete`
would hit upon unsupported ``True`` and ``False`` symbols
which now appear due to the usage of ``IS``.

.. change::
:tags: bug, postgresql
:tickets: 2735

Fixed the HSTORE type to correctly encode/decode for unicode.
This is always on, as the hstore is a textual type, and
matches the behavior of psycopg2 when using Python 3.
Courtesy Dmitry Mugtasimov.

.. change::
:tags: bug, examples

Fixed a small bug in the dogpile example where the generation
of SQL cache keys wasn't applying deduping labels to the
statement the same way :class:`.Query` normally does.

.. change::
:tags: bug, engine, sybase
:tickets: 2732

Fixed a bug where the routine to detect the correct kwargs
being sent to :func:`.create_engine` would fail in some cases,
such as with the Sybase dialect.

.. change::
:tags: bug, orm
:tickets: 2481

Fixed a regression from 0.7 caused by this ticket, which
made the check for recursion overflow in self-referential
eager joining too loose, missing a particular circumstance
where a subclass had lazy="joined" or "subquery" configured
and the load was a "with_polymorphic" against the base.

.. change::
:tags: bug, orm
:tickets: 2718

Fixed a regression from 0.7 where the contextmanager feature
of :meth:`.Session.begin_nested` would fail to correctly
roll back the transaction when a flush error occurred, instead
raising its own exception while leaving the session still
pending a rollback.

.. change::
:tags: bug, mysql

Updated mysqlconnector dialect to check for disconnect based
on the apparent string message sent in the exception; tested
against mysqlconnector 1.0.9.

.. change::
:tags: bug, sql, mssql
:tickets: 2682

Regression from this ticket caused the unsupported keyword
"true" to render, added logic to convert this to 1/0
for SQL server.

.. changelog::

0.8.1

:released: April 27, 2013

.. change::
:tags: bug, orm
:tickets: 2698

Fixes to the ``sqlalchemy.ext.serializer`` extension, including
that the "id" passed from the pickler is turned into a string
to prevent against bytes being parsed on Py3K, as well as that
``relationship()`` and ``orm.join()`` constructs are now properly
serialized.

.. change::
:tags: bug, orm
:tickets: 2714

A significant improvement to the inner workings of query.join(),
such that the decisionmaking involved on how to join has been
dramatically simplified.  New test cases now pass such as
multiple joins extending from the middle of an already complex
series of joins involving inheritance and such.   Joining from
deeply nested subquery structures is still complicated and
not without caveats, but with these improvements the edge
cases are hopefully pushed even farther out to the edges.

.. change::
:tags: feature, orm
:tickets: 2673

Added a convenience method to Query that turns a query into an
EXISTS subquery of the form
``EXISTS (SELECT 1 FROM ... WHERE ...)``.

.. change::
:tags: bug, orm

Added a conditional to the unpickling process for ORM
mapped objects, such that if the reference to the object
were lost when the object was pickled, we don't
erroneously try to set up _sa_instance_state - fixes
a NoneType error.

.. change::
:tags: bug, postgresql
:tickets: 2712

Opened up the checking for "disconnect" with psycopg2/libpq
to check for all the various "disconnect" messages within
the full exception hierarchy.  Specifically the
"closed the connection unexpectedly" message has now been
seen in at least three different exception types.
Courtesy Eli Collins.

.. change::
:tags: bug, sql, mysql
:tickets: 2682

Fully implemented the IS and IS NOT operators with
regards to the True/False constants.  An expression like
``col.is_(True)`` will now render ``col IS true``
on the target platform, rather than converting the True/
False constant to an integer bound parameter.
This allows the ``is_()`` operator to work on MySQL when
given True/False constants.

.. change::
:tags: bug, postgresql
:tickets: 2681

The operators for the PostgreSQL ARRAY type supports
input types of sets, generators, etc. even when
a dimension is not specified, by turning the given
iterable into a collection unconditionally.

.. change::
:tags: bug, mysql

Fixes to support the latest cymysql DBAPI, courtesy
Hajime Nakagami.

.. change::
:tags: bug, mysql
:tickets: 2663

Improvements to the operation of the pymysql dialect on
Python 3, including some important decode/bytes steps.
Issues remain with BLOB types due to driver issues.
Courtesy Ben Trofatter.

.. change::
:tags: bug, orm
:tickets: 2710

Fixed bug where many-to-many relationship with uselist=False
would fail to delete the association row and raise an error
if the scalar attribute were set to None.  This was a
regression introduced by the changes for :ticket:`2229`.

.. change::
:tags: bug, orm
:tickets: 2708

Improved the behavior of instance management regarding
the creation of strong references within the Session;
an object will no longer have an internal reference cycle
created if it's in the transient state or moves into the
detached state - the strong ref is created only when the
object is attached to a Session and is removed when the
object is detached.  This makes it somewhat safer for an
object to have a `__del__()` method, even though this is
not recommended, as relationships with backrefs produce
cycles too.  A warning has been added when a class with
a `__del__()` method is mapped.

.. change::
:tags: bug, sql
:tickets: 2702

A major fix to the way in which a select() object produces
labeled columns when apply_labels() is used; this mode
produces a SELECT where each column is labeled as in
<tablename>_<columnname>, to remove column name collisions
for a multiple table select.   The fix is that if two labels
collide when combined with the table name, i.e.
"foo.bar_id" and "foo_bar.id", anonymous aliasing will be
applied to one of the dupes.  This allows the ORM to handle
both columns independently; previously, 0.7
would in some cases silently emit a second SELECT for the
column that was "duped", and in 0.8 an ambiguous column error
would be emitted.   The "keys" applied to the .c. collection
of the select() will also be deduped, so that the "column
being replaced" warning will no longer emit for any select()
that specifies use_labels, though the dupe key will be given
an anonymous label which isn't generally user-friendly.

.. change::
:tags: bug, mysql

Updated a regexp to correctly extract error code on
google app engine v1.7.5 and newer.  Courtesy
Dan Ring.

.. change::
:tags: bug, examples

Fixed a long-standing bug in the caching example, where
the limit/offset parameter values wouldn't be taken into
account when computing the cache key.  The
_key_from_query() function has been simplified to work
directly from the final compiled statement in order to get
at both the full statement as well as the fully processed
parameter list.

.. change::
:tags: bug, mssql
:tickets: 2355

Part of a longer series of fixes needed for pyodbc+
mssql, a CAST to NVARCHAR(max) has been added to the bound
parameter for the table name and schema name in all information schema
queries to avoid the issue of comparing NVARCHAR to NTEXT,
which seems to be rejected by the ODBC driver in some cases,
such as FreeTDS (0.91 only?) plus unicode bound parameters being passed.
The issue seems to be specific to the SQL Server information
schema tables and the workaround is harmless for those cases
where the problem doesn't exist in the first place.

.. change::
:tags: bug, sql
:tickets: 2691

Fixed bug where disconnect detect on error would
raise an attribute error if the error were being
raised after the Connection object had already
been closed.

.. change::
:tags: bug, sql
:tickets: 2703

Reworked internal exception raises that emit
a rollback() before re-raising, so that the stack
trace is preserved from sys.exc_info() before entering
the rollback.  This so that the traceback is preserved
when using coroutine frameworks which may have switched
contexts before the rollback function returns.

.. change::
:tags: bug, orm
:tickets: 2697

Fixed bug whereby ORM would run the wrong kind of
query when refreshing an inheritance-mapped class
where the superclass was mapped to a non-Table
object, like a custom join() or a select(),
running a query that assumed a hierarchy that's
mapped to individual Table-per-class.

.. change::
:tags: bug, orm

Fixed `__repr__()` on mapper property constructs
to work before the object is initialized, so
that Sphinx builds with recent Sphinx versions
can read them.

.. change::
:tags: bug, sql, postgresql

The _Binary base type now converts values through
the bytes() callable when run on Python 3; in particular
psycopg2 2.5 with Python 3.3 seems to now be returning
the "memoryview" type, so this is converted to bytes
before return.

.. change::
:tags: bug, sql
:tickets: 2695

Improvements to Connection auto-invalidation
handling.  If a non-disconnect error occurs,
but leads to a delayed disconnect error within error
handling (happens with MySQL), the disconnect condition
is detected.  The Connection can now also be closed
when in an invalid state, meaning it will raise "closed"
on next usage, and additionally the "close with result"
feature will work even if the autorollback in an error
handling routine fails and regardless of whether the
condition is a disconnect or not.


.. change::
:tags: bug, orm, declarative
:tickets: 2656

Fixed indirect regression regarding :func:`.has_inherited_table`,
where since it considers the current class' ``__table__``, was
sensitive to when it was called.  This is 0.7's behavior also,
but in 0.7 things tended to "work out" within events like
``__mapper_args__()``.  :func:`.has_inherited_table` now only
considers superclasses, so should return the same answer
regarding the current class no matter when it's called
(obviously assuming the state of the superclass).

.. change::
:tags: bug, mssql

Added support for additional "disconnect" messages
to the pymssql dialect.  Courtesy John Anderson.

.. change::
:tags: feature, sql

Loosened the check on dialect-specific argument names
passed to Table(); since we want to support external dialects
and also want to support args without a certain dialect
being installed, it only checks the format of the arg now,
rather than looking for that dialect in sqlalchemy.dialects.

.. change::
:tags: bug, sql

Fixed bug whereby a DBAPI that can return "0"
for cursor.lastrowid would not function correctly
in conjunction with :attr:`.ResultProxy.inserted_primary_key`.

.. change::
:tags: bug, mssql
:tickets: 2683

Fixed Py3K bug regarding "binary" types and
pymssql.  Courtesy Marc Abramowitz.

.. change::
:tags: bug, postgresql
:tickets: 2680

Added missing HSTORE type to postgresql type names
so that the type can be reflected.

.. changelog::

0.8.0

:released: March 9, 2013

.. note::

There are some new behavioral changes as of 0.8.0
not present in 0.8.0b2.  They are present in the
migration document as follows:

* :ref:`legacy_is_orphan_addition`

* :ref:`metadata_create_drop_tables`

* :ref:`correlation_context_specific`

.. change::
:tags: feature, orm
:tickets: 2675

A meaningful :attr:`.QueryableAttribute.info` attribute is
added, which proxies down to the ``.info`` attribute on either
the :class:`.schema.Column` object if directly present, or
the :class:`.MapperProperty` otherwise.  The full behavior
is documented and ensured by tests to remain stable.

.. change::
:tags: bug, sql
:tickets: 2668

The behavior of SELECT correlation has been improved such that
the :meth:`.Select.correlate` and :meth:`.Select.correlate_except`
methods, as well as their ORM analogues, will still retain
"auto-correlation" behavior in that the FROM clause is modified
only if the output would be legal SQL; that is, the FROM clause
is left intact if the correlated SELECT is not used in the context
of an enclosing SELECT inside of the WHERE, columns, or HAVING clause.
The two methods now only specify conditions to the default
"auto correlation", rather than absolute FROM lists.

.. change::
:tags: feature, mysql

New dialect for CyMySQL added, courtesy Hajime Nakagami.

.. change::
:tags: bug, orm
:tickets: 2674

Improved checking for an existing backref name conflict during
mapper configuration; will now test for name conflicts on
superclasses and subclasses, in addition to the current mapper,
as these conflicts break things just as much.  This is new for
0.8, but see below for a warning that will also be triggered
in 0.7.11.

.. change::
:tags: bug, orm
:tickets: 2674

Improved the error message emitted when a "backref loop" is detected,
that is when an attribute event triggers a bidirectional
assignment between two other attributes with no end.
This condition can occur not just when an object of the wrong
type is assigned, but also when an attribute is mis-configured
to backref into an existing backref pair.  Also in 0.7.11.

.. change::
:tags: bug, orm
:tickets: 2674

A warning is emitted when a MapperProperty is assigned to a mapper
that replaces an existing property, if the properties in question
aren't plain column-based properties.   Replacement of relationship
properties is rarely (ever?) what is intended and usually refers to a
mapper mis-configuration.   Also in 0.7.11.

.. change::
:tags: feature, orm

Can set/change the "cascade" attribute on a :func:`.relationship`
construct after it's been constructed already.  This is not
a pattern for normal use but we like to change the setting
for demonstration purposes in tutorials.

.. change::
:tags: bug, schema
:tickets: 2664

:meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all` will
now accommodate an empty list as an instruction to not create/drop
any items, rather than ignoring the collection.


.. change::
:tags: bug, tests
:tickets: 2669

Fixed an import of "logging" in test_execute which was not
working on some linux platforms.  Also in 0.7.11.

.. change::
:tags: bug, orm
:tickets: 2662

A clear error message is emitted if an event handler
attempts to emit SQL on a Session within the after_commit()
handler, where there is not a viable transaction in progress.

.. change::
:tags: bug, orm
:tickets: 2665

Detection of a primary key change within the process
of cascading a natural primary key update will succeed
even if the key is composite and only some of the
attributes have changed.

.. change::
:tags: feature, orm
:tickets: 2658

Added new helper function :func:`.was_deleted`, returns True
if the given object was the subject of a :meth:`.Session.delete`
operation.

.. change::
:tags: bug, orm
:tickets: 2658

An object that's deleted from a session will be de-associated with
that session fully after the transaction is committed, that is
the :func:`.object_session` function will return None.

.. change::
:tags: bug, oracle

The cx_oracle dialect will no longer run the bind parameter names
through ``encode()``, as this is not valid on Python 3, and prevented
statements from functioning correctly on Python 3.  We now
encode only if ``supports_unicode_binds`` is False, which is not
the case for cx_oracle when at least version 5 of cx_oracle is used.

.. change::
:tags: bug, orm
:tickets: 2661

Fixed bug whereby :meth:`.Query.yield_per` would set the execution
options incorrectly, thereby breaking subsequent usage of the
:meth:`.Query.execution_options` method.  Courtesy Ryan Kelly.

.. change::
:tags: bug, orm
:tickets: 1768

Fixed the consideration of the ``between()`` operator
so that it works correctly with the new relationship local/remote
system.

.. change::
:tags: bug, sql
:tickets: 2660, 1768

Fixed a bug regarding column annotations which in particular
could impact some usages of the new :func:`.orm.remote` and
:func:`.orm.local` annotation functions, where annotations
could be lost when the column were used in a subsequent
expression.

.. change::
:tags: bug, mysql, gae
:tickets: 2649

Added a conditional import to the ``gaerdbms`` dialect which attempts
to import rdbms_apiproxy vs. rdbms_googleapi to work
on both dev and production platforms.  Also now honors the
``instance`` attribute.  Courtesy Sean Lynch.
Also in 0.7.10.

.. change::
:tags: bug, sql
:tickets: 2496

The :meth:`.ColumnOperators.in_` operator will now coerce
values of ``None`` to :func:`.null`.

.. change::
:tags: feature, sql
:tickets: 2657

Added a new argument to :class:`.Enum` and its base
:class:`.SchemaType` ``inherit_schema``.  When set to ``True``,
the type will set its ``schema`` attribute of that of the
:class:`.Table` to which it is associated.  This also occurs
during a :meth:`.Table.tometadata` operation; the :class:`.SchemaType`
is now copied in all cases when :meth:`.Table.tometadata` happens,
and if ``inherit_schema=True``, the type will take on the new
schema name passed to the method.   The ``schema`` is important
when used with the PostgreSQL backend, as the type results in
a ``CREATE TYPE`` statement.

.. change::
:tags: feature, postgresql

Added :meth:`.postgresql.ARRAY.Comparator.any` and
:meth:`.postgresql.ARRAY.Comparator.all`
methods, as well as standalone expression constructs.   Big thanks
to Audrius Kažukauskas for the terrific work here.

.. change::
:tags: sql, bug
:tickets: 2643

Fixed bug where :meth:`.Table.tometadata` would fail if a
:class:`.Column` had both a foreign key as well as an
alternate ".key" name for the column.   Also in 0.7.10.

.. change::
:tags: sql, bug
:tickets: 2629

insert().returning() raises an informative CompileError if attempted
to compile on a dialect that doesn't support RETURNING.

.. change::
:tags: orm, bug
:tickets: 2655

the consideration of a pending object as
an "orphan" has been modified to more closely match the
behavior as that of persistent objects, which is that the object
is expunged from the :class:`.Session` as soon as it is
de-associated from any of its orphan-enabled parents.  Previously,
the pending object would be expunged only if de-associated
from all of its orphan-enabled parents.  The new flag ``legacy_is_orphan``
is added to :func:`.orm.mapper` which re-establishes the
legacy behavior.

See the change note and example case at :ref:`legacy_is_orphan_addition`
for a detailed discussion of this change.

.. change::
:tags: orm, bug
:tickets: 2653

Fixed the (most likely never used) "collection.link" collection
method, which fires off each time the collection is associated
or de-associated with a mapped object - the decorator
was not tested or functional.  The decorator method
is now named :meth:`.collection.linker` though the name "link"
remains for backwards compatibility.  Courtesy Luca Wehrstedt.

.. change::
:tags: orm, bug
:tickets: 2654

Made some fixes to the system of producing custom instrumented
collections, mainly that the usage of the collection decorators
will now honor the __mro__ of the given class, applying the
logic of the sub-most classes' version of a particular collection
method.   Previously, it wasn't predictable when subclassing
an existing instrumented class such as :class:`.MappedCollection`
whether or not custom methods would resolve correctly.

.. change::
:tags: orm, removed

The undocumented (and hopefully unused) system of producing
custom collections using an ``__instrumentation__`` datastructure
associated with the collection has been removed, as this was a complex
and untested feature which was also essentially redundant versus the
decorator approach.   Other internal simplifications to the
orm.collections module have been made as well.

.. change::
:tags: mssql, feature

Added ``mssql_include`` and ``mssql_clustered`` options to
:class:`.Index`, renders the ``INCLUDE`` and ``CLUSTERED`` keywords,
respectively.  Courtesy Derek Harland.

.. change::
:tags: sql, feature
:tickets: 695

:class:`.Index` now supports arbitrary SQL expressions and/or
functions, in addition to straight columns.   Common modifiers
include using ``somecolumn.desc()`` for a descending index and
``func.lower(somecolumn)`` for a case-insensitive index, depending on the
capabilities of the target backend.

.. change::
:tags: mssql, bug
:tickets: 2638

Added a py3K conditional around unnecessary .decode()
call in mssql information schema, fixes reflection
in Py3K. Also in 0.7.10.

.. change::
:tags: orm, bug
:tickets: 2650

Fixed potential memory leak which could occur if an
arbitrary number of :class:`.sessionmaker` objects
were created.   The anonymous subclass created by
the sessionmaker, when dereferenced, would not be garbage
collected due to remaining class-level references from the
event package.  This issue also applies to any custom system
that made use of ad-hoc subclasses in conjunction with
an event dispatcher.  Also in 0.7.10.

.. change::
:tags: mssql, bug

Fixed a regression whereby the "collation" parameter
of the character types CHAR, NCHAR, etc. stopped working,
as "collation" is now supported by the base string types.
The TEXT, NCHAR, CHAR, VARCHAR types within the
MSSQL dialect are now synonyms for the base types.

.. change::
:tags: mssql, feature
:tickets: 2644

DDL for IDENTITY columns is now supported on
non-primary key columns, by establishing a
:class:`.Sequence` construct on any
integer column.  Courtesy Derek Harland.

.. change::
:tags: examples, bug

Fixed a regression in the examples/dogpile_caching example
which was due to the change in :ticket:`2614`.

.. change::
:tags: orm, bug
:tickets: 2640

:meth:`.Query.merge_result` can now load rows from an outer join
where an entity may be ``None`` without throwing an error.
Also in 0.7.10.

.. change::
:tags: sql, bug
:tickets: 2648

Tweaked the "REQUIRED" symbol used by the compiler to identify
INSERT/UPDATE bound parameters that need to be passed, so that
it's more easily identifiable when writing custom bind-handling
code.

.. change::
:tags: postgresql, bug

Fixed bug in :class:`~sqlalchemy.dialects.postgresql.array()` construct whereby using it
inside of an :func:`.expression.insert` construct would produce an
error regarding a parameter issue in the ``self_group()`` method.

.. change::
:tags: orm, feature

Extended the :doc:`/core/inspection` system so that all Python descriptors
associated with the ORM or its extensions can be retrieved.
This fulfills the common request of being able to inspect
all :class:`.QueryableAttribute` descriptors in addition to
extension types such as :class:`.hybrid_property` and
:class:`.AssociationProxy`.  See :attr:`.Mapper.all_orm_descriptors`.

.. change::
:tags: mysql, feature

GAE dialect now accepts username/password arguments in the URL,
courtesy Owen Nelson.

.. change::
:tags: mysql, bug

GAE dialect won't fail on None match if the error code can't be extracted
from the exception throw; courtesy Owen Nelson.

.. change::
:tags: orm, bug
:tickets: 2637

Fixes to the "dynamic" loader on :func:`.relationship`, includes
that backrefs will work properly even when autoflush is disabled,
history events are more accurate in scenarios where multiple add/remove
of the same object occurs.

.. changelog::

0.8.0b2

:released: December 14, 2012

.. change::
:tags: orm, bug
:tickets: 2635

The :meth:`.Query.select_from` method can now be used with a
:func:`.aliased` construct without it interfering with the entities
being selected.   Basically, a statement like this::

ua = aliased(User)
session.query(User.name).select_from(ua).join(User, User.name > ua.name)

Will maintain the columns clause of the SELECT as coming from the
unaliased "user", as specified; the select_from only takes place in the
FROM clause::

SELECT users.name AS users_name FROM users AS users_1
JOIN users ON users.name < users_1.name

Note that this behavior is in contrast
to the original, older use case for :meth:`.Query.select_from`, which is that
of restating the mapped entity in terms of a different selectable::

session.query(User.name).\
select_from(user_table.select().where(user_table.c.id > 5))

Which produces::

SELECT anon_1.name AS anon_1_name FROM (SELECT users.id AS id,
users.name AS name FROM users WHERE users.id > :id_1) AS anon_1

It was the "aliasing" behavior of the latter use case that was
getting in the way of the former use case.   The method now
specifically considers a SQL expression like
:func:`.expression.select` or :func:`.expression.alias`
separately from a mapped entity like a :func:`.aliased`
construct.

.. change::
:tags: sql, bug
:tickets: 2633

Fixed a regression caused by :ticket:`2410` whereby a
:class:`.CheckConstraint` would apply itself back to the
original table during a :meth:`.Table.tometadata` operation, as
it would parse the SQL expression for a parent table. The
operation now copies the given expression to correspond to the
new table.

.. change::
:tags: oracle, bug
:tickets: 2619

Fixed table reflection for Oracle when accessing a synonym that refers
to a DBLINK remote database; while the syntax has been present in the
Oracle dialect for some time, up until now it has never been tested.
The syntax has been tested against a sample database linking to itself,
however there's still some uncertainty as to what should be used for the
"owner" when querying the remote database for table information.
Currently, the value of "username" from user_db_links is used to
match the "owner".

.. change::
:tags: orm, feature
:tickets: 2601

Added :meth:`.KeyedTuple._asdict` and :attr:`.KeyedTuple._fields`
to the :class:`.KeyedTuple` class to provide some degree of compatibility
with the Python standard library ``collections.namedtuple()``.

.. change::
:tags: sql, bug
:tickets: 2610

Fixed bug whereby using a label_length on dialect that was smaller
than the size of actual column identifiers would fail to render
the columns correctly in a SELECT statement.

.. change::
:tags: sql, feature
:tickets: 2623

The :class:`.Insert` construct now supports multi-valued inserts,
that is, an INSERT that renders like
"INSERT INTO table VALUES (...), (...), ...".
Supported by PostgreSQL, SQLite, and MySQL.
Big thanks to Idan Kamara for doing the legwork on this one.

.. seealso::

:ref:`feature_2623`

.. change::
:tags: oracle, bug
:tickets: 2620

The Oracle LONG type, while an unbounded text type, does not appear
to use the cx_Oracle.LOB type when result rows are returned,
so the dialect has been repaired to exclude LONG from
having cx_Oracle.LOB filtering applied.  Also in 0.7.10.

.. change::
:tags: oracle, bug
:tickets: 2611

Repaired the usage of ``.prepare()`` in conjunction with
cx_Oracle so that a return value of ``False`` will result
in no call to ``connection.commit()``, hence avoiding
"no transaction" errors.   Two-phase transactions have
now been shown to work in a rudimental fashion with
SQLAlchemy and cx_oracle, however are subject to caveats
observed with the driver; check the documentation
for details.  Also in 0.7.10.

.. change::
:tags: sql, bug
:tickets: 2618

The :class:`~sqlalchemy.types.DECIMAL` type now honors the "precision" and
"scale" arguments when rendering DDL.

.. change::
:tags: orm, bug
:tickets: 2624

The :class:`.MutableComposite` type did not allow for the
:meth:`.MutableBase.coerce` method to be used, even though
the code seemed to indicate this intent, so this now works
and a brief example is added.  As a side-effect,
the mechanics of this event handler have been changed so that
new :class:`.MutableComposite` types no longer add per-type
global event handlers.  Also in 0.7.10.

.. change::
:tags: sql, bug
:tickets: 2621

Made an adjustment to the "boolean", (i.e. ``__nonzero__``)
evaluation of binary expressions, i.e. ``x1 == x2``, such
that the "auto-grouping" applied by :class:`.BinaryExpression`
in some cases won't get in the way of this comparison.
Previously, an expression like::

expr1 = mycolumn > 2
bool(expr1 == expr1)

Would evaluate as ``False``, even though this is an identity
comparison, because ``mycolumn > 2`` would be "grouped" before
being placed into the :class:`.BinaryExpression`, thus changing
its identity.   :class:`.BinaryExpression` now keeps track
of the "original" objects passed in.
Additionally the ``__nonzero__`` method now only returns if
the operator is ``==`` or ``!=`` - all others raise ``TypeError``.

.. change::
:tags: firebird, bug
:tickets: 2622

Added missing import for "fdb" to the experimental
"firebird+fdb" dialect.

.. change::
:tags: orm, feature

Allow synonyms to be used when defining primary and secondary
joins for relationships.

.. change::
:tags: orm, bug
:tickets: 2614

A second overhaul of aliasing/internal pathing mechanics
now allows two subclasses to have different relationships
of the same name, supported with subquery or joined eager
loading on both simultaneously when a full polymorphic
load is used.

.. change::
:tags: orm, bug
:tickets: 2617

Fixed bug whereby a multi-hop subqueryload within
a particular with_polymorphic load would produce a KeyError.
Takes advantage of the same internal pathing overhaul
as :ticket:`2614`.

.. change::
:tags: sql, bug

Fixed a gotcha where inadvertently calling list() on a
:class:`.ColumnElement` would go into an endless loop, if
:meth:`.ColumnOperators.__getitem__` were implemented.
A new NotImplementedError is emitted via ``__iter__()``.

.. change::
:tags: orm, extensions, feature

The :mod:`sqlalchemy.ext.mutable` extension now includes the
example :class:`.MutableDict` class as part of the extension.

.. change::
:tags: postgresql, feature
:tickets: 2606

:class:`.HSTORE` is now available in the PostgreSQL dialect.
Will also use psycopg2's extensions if available.  Courtesy
Audrius Kažukauskas.

.. change::
:tags: sybase, feature
:tickets: 1753

Reflection support has been added to the Sybase dialect.
Big thanks to Ben Trofatter for all the work developing and
testing this.

.. change::
:tags: engine, feature

The :meth:`.Connection.connect` and :meth:`.Connection.contextual_connect`
methods now return a "branched" version so that the :meth:`.Connection.close`
method can be called on the returned connection without affecting the
original.   Allows symmetry when using :class:`.Engine` and
:class:`.Connection` objects as context managers::

with conn.connect() as c:  leaves the Connection open
c.execute("...")

with engine.connect() as c:   closes the Connection
c.execute("...")

.. change::
:tags: engine

The "reflect=True" argument to :class:`~sqlalchemy.schema.MetaData` is deprecated.
Please use the :meth:`.MetaData.reflect` method.

.. change::
:tags: sql, bug
:tickets: 2603

Fixed bug in type_coerce() whereby typing information
could be lost if the statement were used as a subquery
inside of another statement, as well as other similar
situations.  Among other things, would cause
typing information to be lost when the Oracle/mssql dialects
would apply limit/offset wrappings.

.. change::
:tags: orm, bug
:tickets: 2602

Fixed regression where query.update() would produce
an error if an object matched by the "fetch"
synchronization strategy wasn't locally present.
Courtesy Scott Torborg.

.. change::
:tags: sql, bug
:tickets: 2597

Fixed bug whereby the ".key" of a Column wasn't being
used when producing a "proxy" of the column against
a selectable.   This probably didn't occur in 0.7
since 0.7 doesn't respect the ".key" in a wider
range of scenarios.

.. change::
:tags: mssql, feature
:tickets: 2600

Support for reflection of the "name" of primary key
constraints added, courtesy Dave Moore.

.. change::
:tags: informix

Some cruft regarding informix transaction handling has been
removed, including a feature that would skip calling
commit()/rollback() as well as some hardcoded isolation level
assumptions on begin()..   The status of this dialect is not
well understood as we don't have any users working with it,
nor any access to an Informix database.   If someone with
access to Informix wants to help test this dialect, please
let us know.

.. change::
:tags: pool, feature

The :class:`.Pool` will now log all connection.close()
operations equally, including closes which occur for
invalidated connections, detached connections, and connections
beyond the pool capacity.

.. change::
:tags: pool, feature
:tickets: 2611

The :class:`.Pool` now consults the :class:`.Dialect` for
functionality regarding how the connection should be
"auto rolled back", as well as closed.   This grants more
control of transaction scope to the dialect, so that we
will be better able to implement transactional workarounds
like those potentially needed for pysqlite and cx_oracle.

.. change::
:tags: pool, feature

Added new :meth:`.PoolEvents.reset` hook to capture
the event before a connection is auto-rolled back, upon
return to the pool.   Together with
:meth:`.ConnectionEvents.rollback` this allows all rollback
events to be intercepted.

.. changelog::
:version: 0.8.0b1
:released: October 30, 2012

.. change::
:tags: sql, bug
:tickets: 2593

Fixed bug where keyword arguments passed to
:meth:`.Compiler.process` wouldn't get propagated
to the column expressions present in the columns
clause of a SELECT statement.  In particular this would
come up when used by custom compilation schemes that
relied upon special flags.

.. change::
:tags: sql, feature

Added a new method :meth:`.Engine.execution_options`
to :class:`.Engine`.  This method works similarly to
:meth:`.Connection.execution_options` in that it creates
a copy of the parent object which will refer to the new
set of options.   The method can be used to build
sharding schemes where each engine shares the same
underlying pool of connections.   The method
has been tested against the horizontal shard
recipe in the ORM as well.

.. seealso::

:meth:`.Engine.execution_options`

.. change::
:tags: sql, orm, bug
:tickets: 2595

The auto-correlation feature of :func:`.select`, and
by proxy that of :class:`.Query`, will not
take effect for a SELECT statement that is being
rendered directly in the FROM list of the enclosing
SELECT.  Correlation in SQL only applies to column
expressions such as those in the WHERE, ORDER BY,
columns clause.

.. change::
:tags: sqlite
:changeset: c3addcc9ffad

Added :class:`.types.NCHAR`, :class:`.types.NVARCHAR`
to the SQLite dialect's list of recognized type names
for reflection.   SQLite returns the name given
to a type as the name returned.

.. change::
:tags: examples
:tickets: 2589

The Beaker caching example has been converted
to use `dogpile.cache <https://dogpilecache.readthedocs.io/>`_.
This is a new caching library written by the same
creator of Beaker's caching internals, and represents a
vastly improved, simplified, and modernized system of caching.

.. seealso::

:ref:`examples_caching`

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

SQLAlchemy 0.8 now targets Python 2.5 and
above.  Python 2.4 is no longer supported.

.. change::
:tags: removed, general
:tickets: 2433

The "sqlalchemy.exceptions"
synonym for "sqlalchemy.exc" is removed
fully.

.. change::
:tags: removed, orm
:tickets: 2442

The legacy "mutable" system of the
ORM, including the MutableType class as well
as the mutable=True flag on PickleType
and postgresql.ARRAY has been removed.
In-place mutations are detected by the ORM
using the sqlalchemy.ext.mutable extension,
introduced in 0.7.   The removal of MutableType
and associated constructs removes a great
deal of complexity from SQLAlchemy's internals.
The approach performed poorly as it would incur
a scan of the full contents of the Session
when in use.

.. change::
:tags: orm, moved
:tickets:

The InstrumentationManager interface
and the entire related system of alternate
class implementation is now moved out
to sqlalchemy.ext.instrumentation.   This is
a seldom used system that adds significant
complexity and overhead to the mechanics of
class instrumentation.  The new architecture
allows it to remain unused until
InstrumentationManager is actually imported,
at which point it is bootstrapped into
the core.

.. change::
:tags: orm, feature
:tickets: 1401

Major rewrite of relationship()
internals now allow join conditions which
include columns pointing to themselves
within composite foreign keys.   A new
API for very specialized primaryjoin conditions
is added, allowing conditions based on
SQL functions, CAST, etc. to be handled
by placing the annotation functions
remote() and foreign() inline within the
expression when necessary.  Previous recipes
using the semi-private _local_remote_pairs
approach can be upgraded to this new
approach.

.. seealso::

:ref:`feature_relationship_08`

.. change::
:tags: orm, bug
:tickets: 2527

ORM will perform extra effort to determine
that an FK dependency between two tables is
not significant during flush if the tables
are related via joined inheritance and the FK
dependency is not part of the inherit_condition,
saves the user a use_alter directive.

.. change::
:tags: orm, feature
:tickets: 2333

New standalone function with_polymorphic()
provides the functionality of query.with_polymorphic()
in a standalone form.   It can be applied to any
entity within a query, including as the target
of a join in place of the "of_type()" modifier.

.. change::
:tags: orm, feature
:tickets: 1106, 2438

The of_type() construct on attributes
now accepts aliased() class constructs as well
as with_polymorphic constructs, and works with
query.join(), any(), has(), and also
eager loaders subqueryload(), joinedload(),
contains_eager()

.. change::
:tags: orm, feature
:tickets: 2585

Improvements to event listening for
mapped classes allows that unmapped classes
can be specified for instance- and mapper-events.
The established events will be automatically
set up on subclasses of that class when the
propagate=True flag is passed, and the
events will be set up for that class itself
if and when it is ultimately mapped.

.. change::
:tags: orm, bug
:tickets: 2590

The instrumentation events class_instrument(),
class_uninstrument(), and attribute_instrument()
will now fire off only for descendant classes
of the class assigned to listen().  Previously,
an event listener would be assigned to listen
for all classes in all cases regardless of the
"target" argument passed.

.. change::
:tags: orm, bug
:tickets: 1900

with_polymorphic() produces JOINs
in the correct order and with correct inheriting
tables in the case of sending multi-level
subclasses in an arbitrary order or with
intermediary classes missing.

.. change::
:tags: orm, feature
:tickets: 2485

The "deferred declarative
reflection" system has been moved into the
declarative extension itself, using the
new DeferredReflection class.  This
class is now tested with both single
and joined table inheritance use cases.

.. change::
:tags: orm, feature
:tickets: 2208

Added new core function "inspect()",
which serves as a generic gateway to
introspection into mappers, objects,
others.   The Mapper and InstanceState
objects have been enhanced with a public
API that allows inspection of mapped
attributes, including filters for column-bound
or relationship-bound properties, inspection
of current object state, history of
attributes, etc.

.. change::
:tags: orm, feature
:tickets: 2452

Calling rollback() within a
session.begin_nested() will now only expire
those objects that had net changes within the
scope of that transaction, that is objects which
were dirty or were modified on a flush.  This
allows the typical use case for begin_nested(),
that of altering a small subset of objects, to
leave in place the data from the larger enclosing
set of objects that weren't modified in
that sub-transaction.

.. change::
:tags: orm, feature
:tickets: 2372

Added utility feature
Session.enable_relationship_loading(),
supersedes relationship.load_on_pending.
Both features should be avoided, however.

.. change::
:tags: orm, feature
:tickets:

Added support for .info dictionary argument to
column_property(), relationship(), composite().
All MapperProperty classes have an auto-creating .info
dict available overall.

.. change::
:tags: orm, feature
:tickets: 2229

Adding/removing None from a mapped collection
now generates attribute events.  Previously, a None
append would be ignored in some cases.  Related
to.

.. change::
:tags: orm, feature
:tickets: 2229

The presence of None in a mapped collection
now raises an error during flush.   Previously,
None values in collections would be silently ignored.

.. change::
:tags: orm, feature
:tickets:

The Query.update() method is now
more lenient as to the table
being updated.  Plain Table objects are better
supported now, and additional a joined-inheritance
subclass may be used with update(); the subclass
table will be the target of the update,
and if the parent table is referenced in the
WHERE clause, the compiler will call upon
UPDATE..FROM syntax as allowed by the dialect
to satisfy the WHERE clause.  MySQL's multi-table
update feature is also supported if columns
are specified by object in the "values" dictionary.
PG's DELETE..USING is also not available
in Core yet.

.. change::
:tags: orm, feature
:tickets:

New session events after_transaction_create
and after_transaction_end
allows tracking of new SessionTransaction objects.
If the object is inspected, can be used to determine
when a session first becomes active and when
it deactivates.

.. change::
:tags: orm, feature
:tickets: 2592

The Query can now load entity/scalar-mixed
"tuple" rows that contain
types which aren't hashable, by setting the flag
"hashable=False" on the corresponding TypeEngine object
in use.  Custom types that return unhashable types
(typically lists) can set this flag to False.

.. change::
:tags: orm, bug
:tickets: 2481

Improvements to joined/subquery eager
loading dealing with chains of subclass entities
sharing a common base, with no specific "join depth"
provided.  Will chain out to
each subclass mapper individually before detecting
a "cycle", rather than considering the base class
to be the source of the "cycle".

.. change::
:tags: orm, bug
:tickets: 2320

The "passive" flag on Session.is_modified()
no longer has any effect. is_modified() in
all cases looks only at local in-memory
modified flags and will not emit any
SQL or invoke loader callables/initializers.

.. change::
:tags: orm, bug
:tickets: 2405

The warning emitted when using
delete-orphan cascade with one-to-many
or many-to-many without single-parent=True
is now an error.  The ORM
would fail to function subsequent to this
warning in any case.

.. change::
:tags: orm, bug
:tickets: 2350

Lazy loads emitted within flush events
such as before_flush(), before_update(),
etc. will now function as they would
within non-event code, regarding consideration
of the PK/FK values used in the lazy-emitted
query.   Previously,
special flags would be established that
would cause lazy loads to load related items
based on the "previous" value of the
parent PK/FK values specifically when called
upon within a flush; the signal to load
in this way is now localized to where the
unit of work actually needs to load that
way.  Note that the UOW does
sometimes load these collections before
the before_update() event is called,
so the usage of "passive_updates" or not
can affect whether or not a collection will
represent the "old" or "new" data, when
accessed within a flush event, based
on when the lazy load was emitted.
The change is backwards incompatible in
the exceedingly small chance that
user event code depended on the old
behavior.

.. change::
:tags: orm, feature
:tickets: 2179

Query now "auto correlates" by
default in the same way as select() does.
Previously, a Query used as a subquery
in another would require the correlate()
method be called explicitly in order to
correlate a table on the inside to the
outside.  As always, correlate(None)
disables correlation.

.. change::
:tags: orm, feature
:tickets: 2464

The after_attach event is now
emitted after the object is established
in Session.new or Session.identity_map
upon Session.add(), Session.merge(),
etc., so that the object is represented
in these collections when the event
is called.  Added before_attach
event to accommodate use cases that
need autoflush w pre-attached object.

.. change::
:tags: orm, feature
:tickets:

The Session will produce warnings
when unsupported methods are used inside the
"execute" portion of the flush.   These are
the familiar methods add(), delete(), etc.
as well as collection and related-object
manipulations, as called within mapper-level
flush events
like after_insert(), after_update(), etc.
It's been prominently documented for a long
time that  SQLAlchemy cannot guarantee
results when the Session is manipulated within
the execution of the flush plan,
however users are still doing it, so now
there's a warning.   Maybe someday the Session
will be enhanced to support these operations
inside of the flush, but for now, results
can't be guaranteed.

.. change::
:tags: orm, bug
:tickets: 2582, 2566

Continuing regarding extra
state post-flush due to event listeners;
any states that are marked as "dirty" from an
attribute perspective, usually via column-attribute
set events within after_insert(), after_update(),
etc., will get the "history" flag reset
in all cases, instead of only those instances
that were part of the flush.  This has the effect
that this "dirty" state doesn't carry over
after the flush and won't result in UPDATE
statements.   A warning is emitted to this
effect; the set_committed_state()
method can be used to assign attributes on objects
without producing history events.

.. change::
:tags: orm, feature
:tickets: 2245

ORM entities can be passed
to the core select() construct as well
as to the select_from(),
correlate(), and correlate_except()
methods of select(), where they will be unwrapped
into selectables.

.. change::
:tags: orm, feature
:tickets: 2245

Some support for auto-rendering of a
relationship join condition based on the mapped
attribute, with usage of core SQL constructs.
E.g. select([SomeClass]).where(SomeClass.somerelationship)
would render SELECT from "someclass" and use the
primaryjoin of "somerelationship" as the WHERE
clause.   This changes the previous meaning
of "SomeClass.somerelationship" when used in a
core SQL context; previously, it would "resolve"
to the parent selectable, which wasn't generally
useful.  Also works with query.filter().
Related to.

.. change::
:tags: orm, feature
:tickets: 2526

The registry of classes
in declarative_base() is now a
WeakValueDictionary.  So subclasses of
"Base" that are dereferenced will be
garbage collected, *if they are not
referred to by any other mappers/superclass
mappers*. See the next note for this ticket.

.. change::
:tags: orm, feature
:tickets: 2472

Conflicts between columns on
single-inheritance declarative subclasses,
with or without using a mixin, can be resolved
using a new declared_attr usage described
in the documentation.

.. change::
:tags: orm, feature
:tickets: 2472

declared_attr can now be used
on non-mixin classes, even though this is generally
only useful for single-inheritance subclass
column conflict resolution.

.. change::
:tags: orm, feature
:tickets: 2517

declared_attr can now be used with
attributes that are not Column or MapperProperty;
including any user-defined value as well
as association proxy objects.

.. change::
:tags: orm, bug
:tickets: 2565

Fixed a disconnect that slowly evolved
between a declared_attr Column and a
directly-defined Column on a mixin. In both
cases, the Column will be applied to the
declared class' table, but not to that of a
joined inheritance subclass.   Previously,
the directly-defined Column would be placed
on both the base and the sub table, which isn't
typically what's desired.

.. change::
:tags: orm, feature
:tickets: 2526

*Very limited* support for
inheriting mappers to be GC'ed when the
class itself is deferenced.  The mapper
must not have its own table (i.e.
single table inh only) without polymorphic
attributes in place.
This allows for the use case of
creating a temporary subclass of a declarative
mapped class, with no table or mapping
directives of its own, to be garbage collected
when dereferenced by a unit test.

.. change::
:tags: orm, feature
:tickets: 2338

Declarative now maintains a registry
of classes by string name as well as by full
module-qualified name.   Multiple classes with the
same name can now be looked up based on a module-qualified
string within relationship().   Simple class name
lookups where more than one class shares the same
name now raises an informative error message.

.. change::
:tags: orm, feature
:tickets: 2535

Can now provide class-bound attributes
that override columns which are of any
non-ORM type, not just descriptors.

.. change::
:tags: orm, feature
:tickets: 1729

Added with_labels and
reduce_columns keyword arguments to
Query.subquery(), to provide two alternate
strategies for producing queries with uniquely-
named columns. .

.. change::
:tags: orm, feature
:tickets: 2476

A warning is emitted when a reference
to an instrumented collection is no longer
associated with the parent class due to
expiration/attribute refresh/collection
replacement, but an append
or remove operation is received on the
now-detached collection.

.. change::
:tags: orm, bug
:tickets: 2549

Declarative can now propagate a column
declared on a single-table inheritance subclass
up to the parent class' table, when the parent
class is itself mapped to a join() or select()
statement, directly or via joined inheritance,
and not just a Table.

.. change::
:tags: orm, bug
:tickets:

An error is emitted when uselist=False
is combined with a "dynamic" loader.
This is a warning in 0.7.9.

.. change::
:tags: removed, orm
:tickets:

Deprecated identifiers removed:

* allow_null_pks mapper() argument
(use allow_partial_pks)

* _get_col_to_prop() mapper method
(use get_property_by_column())

* dont_load argument to Session.merge()
(use load=True)

* sqlalchemy.orm.shard module
(use sqlalchemy.ext.horizontal_shard)

.. change::
:tags: engine, feature
:tickets: 2511

Connection event listeners can
now be associated with individual
Connection objects, not just Engine
objects.

.. change::
:tags: engine, feature
:tickets: 2459

The before_cursor_execute event
fires off for so-called "_cursor_execute"
events, which are usually special-case
executions of primary-key bound sequences
and default-generation SQL
phrases that invoke separately when RETURNING
is not used with INSERT.

.. change::
:tags: engine, feature
:tickets:

The libraries used by the test suite
have been moved around a bit so that they are
part of the SQLAlchemy install again.  In addition,
a new suite of tests is present in the
new sqlalchemy.testing.suite package.  This is
an under-development system that hopes to provide
a universal testing suite for external dialects.
Dialects which are maintained outside of SQLAlchemy
can use the new test fixture as the framework
for their own tests, and will get for free a
"compliance" suite of dialect-focused tests,
including an improved "requirements" system
where specific capabilities and features can
be enabled or disabled for testing.

.. change::
:tags: engine, bug
:tickets:

The Inspector.get_table_names()
order_by="foreign_key" feature now sorts
tables by dependee first, to be consistent
with util.sort_tables and metadata.sorted_tables.

.. change::
:tags: engine, bug
:tickets: 2522

Fixed bug whereby if a database restart
affected multiple connections, each
connection would individually invoke a new
disposal of the pool, even though only
one disposal is needed.

.. change::
:tags: engine, feature
:tickets: 2462

Added a new system
for registration of new dialects in-process
without using an entrypoint.  See the
docs for "Registering New Dialects".

.. change::
:tags: engine, feature
:tickets: 2556

The "required" flag is set to
True by default, if not passed explicitly,
on bindparam() if the "value" or "callable"
parameters are not passed.
This will cause statement execution to check
for the parameter being present in the final
collection of bound parameters, rather than
implicitly assigning None.

.. change::
:tags: engine, feature
:tickets:

Various API tweaks to the "dialect"
API to better support highly specialized
systems such as the Akiban database, including
more hooks to allow an execution context to
access type processors.

.. change::
:tags: engine, bug
:tickets: 2397

The names of the columns on the
.c. attribute of a select().apply_labels()
is now based on <tablename>_<colkey> instead
of <tablename>_<colname>, for those columns
that have a distinctly named .key.

.. change::
:tags: engine, feature
:tickets: 2422

Inspector.get_primary_keys() is
deprecated; use Inspector.get_pk_constraint().
Courtesy Diana Clarke.

.. change::
:tags: engine, bug
:tickets:

The autoload_replace flag on Table,
when False, will cause any reflected foreign key
constraints which refer to already-declared
columns to be skipped, assuming that the
in-Python declared column will take over
the task of specifying in-Python ForeignKey
or ForeignKeyConstraint declarations.

.. change::
:tags: engine, bug
:tickets: 2498

The ResultProxy methods inserted_primary_key,
last_updated_params(), last_inserted_params(),
postfetch_cols(), prefetch_cols() all
assert that the given statement is a compiled
construct, and is an insert() or update()
statement as is appropriate, else
raise InvalidRequestError.

.. change::
:tags: engine, feature
:tickets:

New C extension module "utils" has
been added for additional function speedups
as we have time to implement.

.. change::
:tags: engine
:tickets:

ResultProxy.last_inserted_ids is removed,
replaced by inserted_primary_key.

.. change::
:tags: feature, sql
:tickets: 2547

Major rework of operator system
in Core, to allow redefinition of existing
operators as well as addition of new operators
at the type level.  New types can be created
from existing ones which add or redefine
operations that are exported out to column
expressions, in a similar manner to how the
ORM has allowed comparator_factory.   The new
architecture moves this capability into the
Core so that it is consistently usable in
all cases, propagating cleanly using existing
type propagation behavior.

.. change::
:tags: feature, sql
:tickets: 1534, 2547

To complement, types
can now provide "bind expressions" and
"column expressions" which allow compile-time
injection of SQL expressions into statements
on a per-column or per-bind level.   This is
to suit the use case of a type which needs
to augment bind- and result- behavior at the
SQL level, as opposed to in the Python level.
Allows for schemes like transparent encryption/
decryption, usage of PostGIS functions, etc.

.. change::
:tags: feature, sql
:tickets:

The Core operator system now includes
the `getitem` operator, i.e. the bracket
operator in Python.  This is used at first
to provide index and slice behavior to the
PostgreSQL ARRAY type, and also provides a hook
for end-user definition of custom __getitem__
schemes which can be applied at the type
level as well as within ORM-level custom
operator schemes.   `lshift` (<<)
and `rshift` (>>) are also supported as
optional operators.

Note that this change has the effect that
descriptor-based __getitem__ schemes used by
the ORM in conjunction with synonym() or other
"descriptor-wrapped" schemes will need
to start using a custom comparator in order
to maintain this behavior.

.. change::
:tags: feature, sql
:tickets: 2537

Revised the rules used to determine
the operator precedence for the user-defined
operator, i.e. that granted using the ``op()``
method.   Previously, the smallest precedence
was applied in all cases, now the default
precedence is zero, lower than all operators
except "comma" (such as, used in the argument
list of a ``func`` call) and "AS", and is
also customizable via the "precedence" argument
on the ``op()`` method.

.. change::
:tags: feature, sql
:tickets: 2276

Added "collation" parameter to all
String types.  When present, renders as
COLLATE <collation>.  This to support the
COLLATE keyword now supported by several
databases including MySQL, SQLite, and PostgreSQL.

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

The Text() type renders the length
given to it, if a length was specified.

.. change::
:tags: feature, sql
:tickets:

Custom unary operators can now be
used by combining operators.custom_op() with
UnaryExpression().

.. change::
:tags: bug, sql
:tickets: 2564

A tweak to column precedence which moves the
"concat" and "match" operators to be the same as
that of "is", "like", and others; this helps with
parenthesization rendering when used in conjunction
with "IS".

.. change::
:tags: feature, sql
:tickets:

Enhanced GenericFunction and func.*
to allow for user-defined GenericFunction
subclasses to be available via the func.*
namespace automatically by classname,
optionally using a package name, as well
as with the ability to have the rendered
name different from the identified name
in func.*.

.. change::
:tags: feature, sql
:tickets: 2562

The cast() and extract() constructs
will now be produced via the func.* accessor
as well, as users naturally try to access these
names from func.* they might as well do
what's expected, even though the returned
object is not a FunctionElement.

.. change::
:tags: changed, sql
:tickets:

Most classes in expression.sql
are no longer preceded with an underscore,
i.e. Label, SelectBase, Generative, CompareMixin.
_BindParamClause is also renamed to
BindParameter.   The old underscore names for
these classes will remain available as synonyms
for the foreseeable future.

.. change::
:tags: feature, sql
:tickets: 2208

The Inspector object can now be
acquired using the new inspect() service,
part of

.. change::
:tags: feature, sql
:tickets: 2418

The column_reflect event now
accepts the Inspector object as the first
argument, preceding "table".   Code which
uses the 0.7 version of this very new
event will need modification to add the
"inspector" object as the first argument.

.. change::
:tags: feature, sql
:tickets: 2423

The behavior of column targeting
in result sets is now case sensitive by
default.   SQLAlchemy for many years would
run a case-insensitive conversion on these values,
probably to alleviate early case sensitivity
issues with dialects like Oracle and
Firebird.   These issues have been more cleanly
solved in more modern versions so the performance
hit of calling lower() on identifiers is removed.
The case insensitive comparisons can be re-enabled
by setting "case_insensitive=False" on
create_engine().

.. change::
:tags: bug, sql
:tickets: 2591

Applying a column expression to a select
statement using a label with or without other
modifying constructs will no longer "target" that
expression to the underlying Column; this affects
ORM operations that rely upon Column targeting
in order to retrieve results.  That is, a query
like query(User.id, User.id.label('foo')) will now
track the value of each "User.id" expression separately
instead of munging them together.  It is not expected
that any users will be impacted by this; however,
a usage that uses select() in conjunction with
query.from_statement() and attempts to load fully
composed ORM entities may not function as expected
if the select() named Column objects with arbitrary
.label() names, as these will no longer target to
the Column objects mapped by that entity.

.. change::
:tags: feature, sql
:tickets: 2415

The "unconsumed column names" warning emitted
when keys are present in insert.values() or update.values()
that aren't in the target table is now an exception.

.. change::
:tags: feature, sql
:tickets: 2502

Added "MATCH" clause to ForeignKey,
ForeignKeyConstraint, courtesy Ryan Kelly.

.. change::
:tags: feature, sql
:tickets: 2507

Added support for DELETE and UPDATE from
an alias of a table, which would assumedly
be related to itself elsewhere in the query,
courtesy Ryan Kelly.

.. change::
:tags: feature, sql
:tickets:

select() features a correlate_except()
method, auto correlates all selectables except those
passed.

.. change::
:tags: feature, sql
:tickets: 2431

The prefix_with() method is now available
on each of select(), insert(), update(), delete(),
all with the same API, accepting multiple
prefix calls, as well as a "dialect name" so that
the prefix can be limited to one kind of dialect.

.. change::
:tags: feature, sql
:tickets: 1729

Added reduce_columns() method
to select() construct, replaces columns inline
using the util.reduce_columns utility function
to remove equivalent columns.  reduce_columns()
also adds "with_only_synonyms" to limit the
reduction just to those columns which have the same
name.  The deprecated fold_equivalents() feature is
removed.

.. change::
:tags: feature, sql
:tickets: 2470

Reworked the startswith(), endswith(),
contains() operators to do a better job with
negation (NOT LIKE), and also to assemble them
at compilation time so that their rendered SQL
can be altered, such as in the case for Firebird
STARTING WITH

.. change::
:tags: feature, sql
:tickets: 2463

Added a hook to the system of rendering
CREATE TABLE that provides access to the render for each
Column individually, by constructing a compiles
function against the new schema.CreateColumn
construct.

.. change::
:tags: feature, sql
:tickets:

"scalar" selects now have a WHERE method
to help with generative building.  Also slight adjustment
regarding how SS "correlates" columns; the new methodology
no longer applies meaning to the underlying
Table column being selected.  This improves
some fairly esoteric situations, and the logic
that was there didn't seem to have any purpose.

.. change::
:tags: bug, sql
:tickets: 2520

Fixes to the interpretation of the
Column "default" parameter as a callable
to not pass ExecutionContext into a keyword
argument parameter.

.. change::
:tags: bug, sql
:tickets: 2410

All of UniqueConstraint, ForeignKeyConstraint,
CheckConstraint, and PrimaryKeyConstraint will
attach themselves to their parent table automatically
when they refer to a Table-bound Column object directly
(i.e. not just string column name), and refer to
one and only one Table.   Prior to 0.8 this behavior
occurred for UniqueConstraint and PrimaryKeyConstraint,
but not ForeignKeyConstraint or CheckConstraint.

.. change::
:tags: bug, sql
:tickets: 2594

TypeDecorator now includes a generic repr()
that works in terms of the "impl" type by default.
This is a behavioral change for those TypeDecorator
classes that specify a custom __init__ method; those
types will need to re-define __repr__() if they need
__repr__() to provide a faithful constructor representation.

.. change::
:tags: bug, sql
:tickets: 2168

column.label(None) now produces an
anonymous label, instead of returning the
column object itself, consistent with the behavior
of label(column, None).

.. change::
:tags: feature, sql
:tickets: 2455

An explicit error is raised when
a ForeignKeyConstraint() that was
constructed to refer to multiple remote tables
is first used.

.. change::
:tags: access, feature
:tickets:

the MS Access dialect has been
moved to its own project on Bitbucket,
taking advantage of the new SQLAlchemy
dialect compliance suite.   The dialect is
still in very rough shape and probably not
ready for general use yet, however
it does have *extremely* rudimental
functionality now.
https://bitbucket.org/zzzeek/sqlalchemy-access

.. change::
:tags: maxdb, moved
:tickets:

The MaxDB dialect, which hasn't been
functional for several years, is
moved out to a pending bitbucket project,
https://bitbucket.org/zzzeek/sqlalchemy-maxdb.

.. change::
:tags: sqlite, feature
:tickets: 2363

the SQLite date and time types
have been overhauled to support a more open
ended format for input and output, using
name based format strings and regexps.  A
new argument "microseconds" also provides
the option to omit the "microseconds"
portion of timestamps.  Thanks to
Nathan Wright for the work and tests on
this.

.. change::
:tags: mssql, feature
:tickets:

SQL Server dialect can be given
database-qualified schema names,
i.e. "schema='mydatabase.dbo'"; reflection
operations will detect this, split the schema
among the "." to get the owner separately,
and emit a "USE mydatabase" statement before
reflecting targets within the "dbo" owner;
the existing database returned from
DB_NAME() is then restored.

.. change::
:tags: mssql, bug
:tickets: 2277

removed legacy behavior whereby
a column comparison to a scalar SELECT via
== would coerce to an IN with the SQL server
dialect.  This is implicit
behavior which fails in other scenarios
so is removed.  Code which relies on this
needs to be modified to use column.in_(select)
explicitly.

.. change::
:tags: mssql, feature
:tickets:

updated support for the mxodbc
driver; mxodbc 3.2.1 is recommended for full
compatibility.

.. change::
:tags: postgresql, feature
:tickets: 2441

postgresql.ARRAY features an optional
"dimension" argument, will assign a specific
number of dimensions to the array which will
render in DDL as ARRAY[][]..., also improves
performance of bind/result processing.

.. change::
:tags: postgresql, feature
:tickets:

postgresql.ARRAY now supports
indexing and slicing.  The Python [] operator
is available on all SQL expressions that are
of type ARRAY; integer or simple slices can be
passed.  The slices can also be used on the
assignment side in the SET clause of an UPDATE
statement by passing them into Update.values();
see the docs for examples.

.. change::
:tags: postgresql, feature
:tickets:

Added new "array literal" construct
postgresql.array().  Basically a "tuple" that
renders as ARRAY[1,2,3].

.. change::
:tags: postgresql, feature
:tickets: 2506

Added support for the PostgreSQL ONLY
keyword, which can appear corresponding to a
table in a SELECT, UPDATE, or DELETE statement.
The phrase is established using with_hint().
Courtesy Ryan Kelly

.. change::
:tags: postgresql, feature
:tickets:

The "ischema_names" dictionary of the
PostgreSQL dialect is "unofficially" customizable.
Meaning, new types such as PostGIS types can
be added into this dictionary, and the PG type
reflection code should be able to handle simple
types with variable numbers of arguments.
The functionality here is "unofficial" for
three reasons:

1. this is not an "official" API.  Ideally
an "official" API would allow custom type-handling
callables at the dialect or global level
in a generic way.
2. This is only implemented for the PG dialect,
in particular because PG has broad support
for custom types vs. other database backends.
A real API would be implemented at the
default dialect level.
3. The reflection code here is only tested against
simple types and probably has issues with more
compositional types.

patch courtesy Éric Lemoine.

.. change::
:tags: firebird, feature
:tickets: 2470

The "startswith()" operator renders
as "STARTING WITH", "~startswith()" renders
as "NOT STARTING WITH", using FB's more efficient
operator.

.. change::
:tags: firebird, bug
:tickets: 2505

CompileError is raised when VARCHAR with
no length is attempted to be emitted, same
way as MySQL.

.. change::
:tags: firebird, bug
:tickets:

Firebird now uses strict "ansi bind rules"
so that bound parameters don't render in the
columns clause of a statement - they render
literally instead.

.. change::
:tags: firebird, bug
:tickets:

Support for passing datetime as date when
using the DateTime type with Firebird; other
dialects support this.

.. change::
:tags: firebird, feature
:tickets: 2504

An experimental dialect for the fdb
driver is added, but is untested as I cannot
get the fdb package to build.

.. change::
:tags: bug, mysql
:tickets: 2404

Dialect no longer emits expensive server
collations query, as well as server casing,
on first connect.  These functions are still
available as semi-private.

.. change::
:tags: feature, mysql
:tickets: 2534

Added TIME type to mysql dialect,
accepts "fst" argument which is the new
"fractional seconds" specifier for recent
MySQL versions.  The datatype will interpret
a microseconds portion received from the driver,
however note that at this time most/all MySQL
DBAPIs do not support returning this value.

.. change::
:tags: oracle, bug
:tickets: 2437

Quoting information is now passed along
from a Column with quote=True when generating
a same-named bound parameter to the bindparam()
object, as is the case in generated INSERT and UPDATE
statements, so that unknown reserved names can
be fully supported.

.. change::
:tags: oracle, feature
:tickets: 2561

The types of columns excluded from the
setinputsizes() set can be customized by sending
a list of string DBAPI type names to exclude,
using the exclude_setinputsizes dialect parameter.
This list was previously fixed.  The list also
now defaults to STRING, UNICODE, removing
CLOB, NCLOB from the list.

.. change::
:tags: oracle, bug
:tickets:

The CreateIndex construct in Oracle
will now schema-qualify the name of the index
to be that of the parent table.  Previously this
name was omitted which apparently creates the
index in the default schema, rather than that
of the table.

.. change::
:tags: sql, feature
:tickets: 2580

Added :meth:`.ColumnOperators.notin_`,
:meth:`.ColumnOperators.notlike`,
:meth:`.ColumnOperators.notilike` to :class:`.ColumnOperators`.

.. change::
:tags: sql, removed

The long-deprecated and non-functional ``assert_unicode`` flag on
:func:`.create_engine` as well as :class:`.String` is removed.


=============
0.9 Changelog
=============

.. changelog_imports::

.. include:: changelog_08.rst
:start-line: 5

.. include:: changelog_07.rst
:start-line: 5

.. _unreleased_changelog::
:version: 0.9.11

.. change::
:tags: bug, oracle, py3k
:tickets: 3491
:versions: 1.0.9

Fixed support for cx_Oracle version 5.2, which was tripping
up SQLAlchemy's version detection under Python 3 and inadvertently
not using the correct unicode mode for Python 3.  This would cause
issues such as bound variables mis-interpreted as NULL and rows
silently not being returned.

.. change::
:tags: bug, engine
:tickets: 3497
:versions: 1.0.8

Fixed critical issue whereby the pool "checkout" event handler
may be called against a stale connection without the "connect"
event handler having been called, in the case where the pool
attempted to reconnect after being invalidated and failed; the stale
connection would remain present and would be used on a subsequent
attempt.  This issue has a greater impact in the 1.0 series subsequent
to 1.0.2, as it also delivers a blanked-out ``.info`` dictionary to
the event handler; prior to 1.0.2 the ``.info`` dictionary is still
the previous one.

.. changelog::

0.7.10

:released: Thu Feb 7 2013

.. change::
:tags: engine, bug
:tickets: 2604
:versions: 0.8.0b2

Fixed :meth:`.MetaData.reflect` to correctly use
the given :class:`.Connection`, if given, without
opening a second connection from that connection's
:class:`.Engine`.

.. change::
:tags: mssql, bug
:tickets:2607
:versions: 0.8.0b2

Fixed bug whereby using "key" with Column
in conjunction with "schema" for the owning
Table would fail to locate result rows due
to the MSSQL dialect's "schema rendering"
logic's failure to take .key into account.

.. change::
:tags: sql, mysql, gae
:tickets: 2649

Added a conditional import to the ``gaerdbms`` dialect which attempts
to import rdbms_apiproxy vs. rdbms_googleapi to work
on both dev and production platforms.  Also now honors the
``instance`` attribute.  Courtesy Sean Lynch.  Also backported
enhancements to allow username/password as well as
fixing error code interpretation from 0.8.

.. change::
:tags: sql, bug
:tickets: 2594, 2584

Backported adjustment to ``__repr__`` for
:class:`.TypeDecorator` to 0.7, allows :class:`.PickleType`
to produce a clean ``repr()`` to help with Alembic.

.. change::
:tags: sql, bug
:tickets: 2643

Fixed bug where :meth:`.Table.tometadata` would fail if a
:class:`.Column` had both a foreign key as well as an
alternate ".key" name for the column.

.. change::
:tags: mssql, bug
:tickets: 2638

Added a Py3K conditional around unnecessary .decode()
call in mssql information schema, fixes reflection
in Py3k.

.. change::
:tags: orm, bug
:tickets: 2650

Fixed potential memory leak which could occur if an
arbitrary number of :class:`.sessionmaker` objects
were created.   The anonymous subclass created by
the sessionmaker, when dereferenced, would not be garbage
collected due to remaining class-level references from the
event package.  This issue also applies to any custom system
that made use of ad-hoc subclasses in conjunction with
an event dispatcher.

.. change::
:tags: orm, bug
:tickets: 2640

:meth:`.Query.merge_result` can now load rows from an outer join
where an entity may be ``None`` without throwing an error.

.. change::
:tags: sqlite, bug
:tickets: 2568
:versions: 0.8.0b2

More adjustment to this SQLite related issue which was released in
0.7.9, to intercept legacy SQLite quoting characters when reflecting
foreign keys.  In addition to intercepting double quotes, other
quoting characters such as brackets, backticks, and single quotes
are now also intercepted.

.. change::
:tags: sql, bug
:tickets: 2631
:versions: 0.8.0b2

Fixed bug where using server_onupdate=<FetchedValue|DefaultClause>
without passing the "for_update=True" flag would apply the default
object to the server_default, blowing away whatever was there.
The explicit for_update=True argument shouldn't be needed with this usage
(especially since the documentation shows an example without it being
used) so it is now arranged internally using a copy of the given default
object, if the flag isn't set to what corresponds to that argument.

.. change::
:tags: oracle, bug
:tickets: 2620

The Oracle LONG type, while an unbounded text type, does not appear
to use the cx_Oracle.LOB type when result rows are returned,
so the dialect has been repaired to exclude LONG from
having cx_Oracle.LOB filtering applied.

.. change::
:tags: oracle, bug
:tickets: 2611

Repaired the usage of ``.prepare()`` in conjunction with
cx_Oracle so that a return value of ``False`` will result
in no call to ``connection.commit()``, hence avoiding
"no transaction" errors.   Two-phase transactions have
now been shown to work in a rudimental fashion with
SQLAlchemy and cx_oracle, however are subject to caveats
observed with the driver; check the documentation
for details.

.. change::
:tags: orm, bug
:tickets: 2624

The :class:`.MutableComposite` type did not allow for the
:meth:`.MutableBase.coerce` method to be used, even though
the code seemed to indicate this intent, so this now works
and a brief example is added.  As a side-effect,
the mechanics of this event handler have been changed so that
new :class:`.MutableComposite` types no longer add per-type
global event handlers.  Also in 0.8.0b2.

.. change::
:tags: orm, bug
:tickets: 2583

Fixed Session accounting bug whereby replacing
a deleted object in the identity map with another
object of the same primary key would raise a
"conflicting state" error on rollback(),
if the replaced primary key were established either
via non-unitofwork-established INSERT statement
or by primary key switch of another instance.

.. change::
:tags: oracle, bug
:tickets: 2561

changed the list of cx_oracle types that are
excluded from the setinputsizes() step to only include
STRING and UNICODE; CLOB and NCLOB are removed.  This
is to work around cx_oracle behavior which is broken
for the executemany() call.  In 0.8, this same change
is applied however it is also configurable via the
exclude_setinputsizes argument.

.. change::
:tags: feature, mysql
:tickets: 2523

Added "raise_on_warnings" flag to OurSQL
dialect.

.. change::
:tags: feature, mysql
:tickets: 2554

Added "read_timeout" flag to MySQLdb
dialect.

.. changelog::

0.7.9

:released: Mon Oct 01 2012

.. change::
:tags: orm, bug
:tickets:

Fixed bug mostly local to new
AbstractConcreteBase helper where the "type"
attribute from the superclass would not
be overridden on the subclass to produce the
"reserved for base" error message, instead placing
a do-nothing attribute there.  This was inconsistent
vs. using ConcreteBase as well as all the behavior
of classical concrete mappings, where the "type"
column from the polymorphic base would be explicitly
disabled on subclasses, unless overridden
explicitly.

.. change::
:tags: orm, bug
:tickets:

A warning is emitted when lazy='dynamic'
is combined with uselist=False.  This is an
exception raise in 0.8.

.. change::
:tags: orm, bug
:tickets:

Fixed bug whereby user error in related-object
assignment could cause recursion overflow if the
assignment triggered a backref of the same name
as a bi-directional attribute on the incorrect
class to the same target.  An informative
error is raised now.

.. change::
:tags: orm, bug
:tickets: 2539

Fixed bug where incorrect type information
would be passed when the ORM would bind the
"version" column, when using the "version" feature.
Tests courtesy Daniel Miller.

.. change::
:tags: orm, bug
:tickets: 2566

Extra logic has been added to the "flush"
that occurs within Session.commit(), such that the
extra state added by an after_flush() or
after_flush_postexec() hook is also flushed in a
subsequent flush, before the "commit" completes.
Subsequent calls to flush() will continue until
the after_flush hooks stop adding new state.
An "overflow" counter of 100 is also in place,
in the event of a broken after_flush() hook
adding new content each time.

.. change::
:tags: bug, sql
:tickets: 2571

Fixed the DropIndex construct to support
an Index associated with a Table in a remote
schema.

.. change::
:tags: bug, sql
:tickets: 2574

Fixed bug in over() construct whereby
passing an empty list for either partition_by
or order_by, as opposed to None, would fail
to generate correctly.
Courtesy Gunnlaugur Þór Briem.

.. change::
:tags: bug, sql
:tickets: 2521

Fixed CTE bug whereby positional
bound parameters present in the CTEs themselves
would corrupt the overall ordering of
bound parameters.  This primarily
affected SQL Server as the platform with
positional binds + CTE support.

.. change::
:tags: bug, sql
:tickets:

Fixed more un-intuitivenesses in CTEs
which prevented referring to a CTE in a union
of itself without it being aliased.
CTEs now render uniquely
on name, rendering the outermost CTE of a given
name only - all other references are rendered
just as the name.   This even includes other
CTE/SELECTs that refer to different versions
of the same CTE object, such as a SELECT
or a UNION ALL of that SELECT. We are
somewhat loosening the usual link between object
identity and lexical identity in this case.
A true name conflict between two unrelated
CTEs now raises an error.

.. change::
:tags: bug, sql
:tickets: 2512

quoting is applied to the column names
inside the WITH RECURSIVE clause of a
common table expression according to the
quoting rules for the originating Column.

.. change::
:tags: bug, sql
:tickets: 2518

Fixed regression introduced in 0.7.6
whereby the FROM list of a SELECT statement
could be incorrect in certain "clone+replace"
scenarios.

.. change::
:tags: bug, sql
:tickets: 2552

Fixed bug whereby usage of a UNION
or similar inside of an embedded subquery
would interfere with result-column targeting,
in the case that a result-column had the same
ultimate name as a name inside the embedded
UNION.

.. change::
:tags: bug, sql
:tickets: 2558

Fixed a regression since 0.6 regarding
result-row targeting.   It should be possible
to use a select() statement with string
based columns in it, that is
select(['id', 'name']).select_from('mytable'),
and have this statement be targetable by
Column objects with those names; this is the
mechanism by which
query(MyClass).from_statement(some_statement)
works.  At some point the specific case of
using select(['id']), which is equivalent to
select([literal_column('id')]), stopped working
here, so this has been re-instated and of
course tested.

.. change::
:tags: bug, sql
:tickets: 2544

Added missing operators is_(), isnot()
to the ColumnOperators base, so that these long-available
operators are present as methods like all
the other operators.

.. change::
:tags: engine, bug
:tickets: 2522

Fixed bug whereby
a disconnect detect + dispose that occurs
when the QueuePool has threads waiting
for connections would leave those
threads waiting for the duration of
the timeout on the old pool (or indefinitely
if timeout was disabled).  The fix
now notifies those waiters with a special
exception case and has them move onto
the new pool.

.. change::
:tags: engine, feature
:tickets: 2516

Dramatic improvement in memory
usage of the event system; instance-level
collections are no longer created for a
particular type of event until
instance-level listeners are established
for that event.

.. change::
:tags: engine, bug
:tickets: 2529

Added gaerdbms import to mysql/__init__.py,
the absence of which was preventing the new
GAE dialect from being loaded.

.. change::
:tags: engine, bug
:tickets: 2553

Fixed cextension bug whereby the
"ambiguous column error" would fail to
function properly if the given index were
a Column object and not a string.
Note there are still some column-targeting
issues here which are fixed in 0.8.

.. change::
:tags: engine, bug
:tickets:

Fixed the repr() of Enum to include
the "name" and "native_enum" flags.  Helps
Alembic autogenerate.

.. change::
:tags: sqlite, bug
:tickets: 2568

Adjusted a very old bugfix which attempted
to work around a SQLite issue that itself was
"fixed" as of sqlite 3.6.14, regarding quotes
surrounding a table name when using
the "foreign_key_list" pragma.  The fix has been
adjusted to not interfere with quotes that
are *actually in the name* of a column or table,
to as much a degree as possible; sqlite still
doesn't return the correct result for foreign_key_list()
if the target table actually has quotes surrounding
its name, as *part* of its name (i.e. """mytable""").

.. change::
:tags: sqlite, bug
:tickets: 2265

Adjusted column default reflection code to
convert non-string values to string, to accommodate
old SQLite versions that don't deliver
default info as a string.

.. change::
:tags: sqlite, feature
:tickets:

Added support for the localtimestamp()
SQL function implemented in SQLite, courtesy
Richard Mitchell.

.. change::
:tags: postgresql, bug
:tickets: 2531

Columns in reflected primary key constraint
are now returned in the order in which the constraint
itself defines them, rather than how the table
orders them.  Courtesy Gunnlaugur Þór Briem..

.. change::
:tags: postgresql, bug
:tickets: 2570

Added 'terminating connection' to the list
of messages we use to detect a disconnect with PG, which
appears to be present in some versions when the server
is restarted.

.. change::
:tags: bug, mysql
:tickets:

Updated mysqlconnector interface to use
updated "client flag" and "charset" APIs,
courtesy David McNelis.

.. change::
:tags: mssql, bug
:tickets: 2538

Fixed compiler bug whereby using a correlated
subquery within an ORDER BY would fail to render correctly
if the statement also used LIMIT/OFFSET, due to mis-rendering
within the ROW_NUMBER() OVER clause.  Fix courtesy
sayap

.. change::
:tags: mssql, bug
:tickets: 2545

Fixed compiler bug whereby a given
select() would be modified if it had an "offset"
attribute, causing the construct to not compile
correctly a second time.

.. change::
:tags: mssql, bug
:tickets:

Fixed bug where reflection of primary key constraint
would double up columns if the same constraint/table
existed in multiple schemas.

.. changelog::

0.7.8

:released: Sat Jun 16 2012

.. change::
:tags: orm, bug
:tickets: 2480

Fixed bug whereby subqueryload() from
a polymorphic mapping to a target would incur
a new invocation of the query for each
distinct class encountered in the polymorphic
result.

.. change::
:tags: orm, bug
:tickets: 2491, 1892

Fixed bug in declarative
whereby the precedence of columns
in a joined-table, composite
column (typically for id) would fail to
be correct if the columns contained
names distinct from their attribute
names.  This would cause things like
primaryjoin conditions made against the
entity attributes to be incorrect.  Related
to as this was supposed
to be part of that, this is.

.. change::
:tags: orm, feature
:tickets:

The 'objects' argument to
flush() is no longer deprecated, as some
valid use cases have been identified.

.. change::
:tags: orm, bug
:tickets: 2508

Fixed identity_key() function which
was not accepting a scalar argument
for the identity. .

.. change::
:tags: orm, bug
:tickets: 2497

Fixed bug whereby populate_existing
option would not propagate to subquery
eager loaders. .

.. change::
:tags: bug, sql
:tickets: 2499

added BIGINT to types.__all__,
BIGINT, BINARY, VARBINARY to sqlalchemy
module namespace, plus test to ensure
this breakage doesn't occur again.

.. change::
:tags: bug, sql
:tickets: 2490

Repaired common table expression
rendering to function correctly when the
SELECT statement contains UNION or other
compound expressions, courtesy btbuilder.

.. change::
:tags: bug, sql
:tickets: 2482

Fixed bug whereby append_column()
wouldn't function correctly on a cloned
select() construct, courtesy
Gunnlaugur Þór Briem.

.. change::
:tags: engine, bug
:tickets: 2489

Fixed memory leak in C version of
result proxy whereby DBAPIs which don't deliver
pure Python tuples for result rows would
fail to decrement refcounts correctly.
The most prominently affected DBAPI
is pyodbc.

.. change::
:tags: engine, bug
:tickets: 2503

Fixed bug affecting Py3K whereby
string positional parameters passed to
engine/connection execute() would fail to be
interpreted correctly, due to __iter__
being present on Py3K string..

.. change::
:tags: postgresql, bug
:tickets: 2510

removed unnecessary table clause when
reflecting enums,.  Courtesy
Gunnlaugur Þór Briem.

.. change::
:tags: oracle, bug
:tickets: 2483

Added ROWID to oracle.*.

.. change::
:tags: feature, mysql
:tickets: 2484

Added a new dialect for Google App
Engine.  Courtesy Richie Foreman.

.. changelog::

0.7.7

:released: Sat May 05 2012

.. change::
:tags: orm, bug
:tickets: 2477

Fixed issue in unit of work
whereby setting a non-None self-referential
many-to-one relationship to None
would fail to persist the change if the
former value was not already loaded..

.. change::
:tags: orm, feature
:tickets: 2443

Added prefix_with() method
to Query, calls upon select().prefix_with()
to allow placement of MySQL SELECT
directives in statements.  Courtesy
Diana Clarke

.. change::
:tags: orm, bug
:tickets: 2409

Fixed bug in 0.7.6 introduced by whereby column_mapped_collection
used against columns that were mapped as
joins or other indirect selectables
would fail to function.

.. change::
:tags: orm, feature
:tickets:

Added new flag to validates
include_removes.  When True, collection
remove and attribute del events
will also be sent to the validation function,
which accepts an additional argument
"is_remove" when this flag is used.

.. change::
:tags: orm, bug
:tickets: 2449

Fixed bug whereby polymorphic_on
column that's not otherwise mapped on the
class would be incorrectly included
in a merge() operation, raising an error.

.. change::
:tags: orm, bug
:tickets: 2453

Fixed bug in expression annotation
mechanics which could lead to incorrect
rendering of SELECT statements with aliases
and joins, particularly when using
column_property().

.. change::
:tags: orm, bug
:tickets: 2454

Fixed bug which would prevent
OrderingList from being pickleable.  Courtesy Jeff Dairiki

.. change::
:tags: orm, bug
:tickets:

Fixed bug in relationship comparisons
whereby calling unimplemented methods like
SomeClass.somerelationship.like() would
produce a recursion overflow, instead
of NotImplementedError.

.. change::
:tags: bug, sql
:tickets:

Removed warning when Index is created
with no columns; while this might not be what
the user intended, it is a valid use case
as an Index could be a placeholder for just an
index of a certain name.

.. change::
:tags: feature, sql
:tickets:

Added new connection event
dbapi_error(). Is called for all DBAPI-level
errors passing the original DBAPI exception
before SQLAlchemy modifies the state
of the cursor.

.. change::
:tags: bug, sql
:tickets:

If conn.begin() fails when calling
"with engine.begin()", the newly acquired
Connection is closed explicitly before
propagating the exception onward normally.

.. change::
:tags: bug, sql
:tickets: 2474

Add BINARY, VARBINARY to types.__all__.

.. change::
:tags: mssql, feature
:tickets:

Added interim create_engine flag
supports_unicode_binds to PyODBC dialect,
to force whether or not the dialect
passes Python unicode literals to PyODBC
or not.

.. change::
:tags: mssql, bug
:tickets:

Repaired the use_scope_identity
create_engine() flag when using the pyodbc
dialect.  Previously this flag would be
ignored if set to False.  When set to False,
you'll get "SELECT identity" after each
INSERT to get at the last inserted ID,
for those tables which have "implicit_returning"
set to False.

.. change::
:tags: mssql, bug
:tickets: 2468

UPDATE..FROM syntax with SQL Server
requires that the updated table be present
in the FROM clause when an alias of that
table is also present in the FROM clause.
The updated table is now always present
in the FROM, when FROM is present
in the first place.  Courtesy sayap.

.. change::
:tags: postgresql, feature
:tickets: 2445

Added new for_update/with_lockmode()
options for PostgreSQL: for_update="read"/
with_lockmode("read"),
for_update="read_nowait"/
with_lockmode("read_nowait").
These emit "FOR SHARE" and "FOR SHARE NOWAIT",
respectively.  Courtesy Diana Clarke

.. change::
:tags: postgresql, bug
:tickets: 2473

removed unnecessary table clause
when reflecting domains.

.. change::
:tags: bug, mysql
:tickets: 2460

Fixed bug whereby column name inside
of "KEY" clause for autoincrement composite
column with InnoDB would double quote a
name that's a reserved word.  Courtesy Jeff
Dairiki.

.. change::
:tags: bug, mysql
:tickets:

Fixed bug whereby get_view_names() for
"information_schema" schema would fail
to retrieve views marked as "SYSTEM VIEW".
courtesy Matthew Turland.

.. change::
:tags: bug, mysql
:tickets: 2467

Fixed bug whereby if cast() is used
on a SQL expression whose type is not supported
by cast() and therefore CAST isn't rendered by
the dialect, the order of evaluation could change
if the casted expression required that it be
grouped; grouping is now applied to those
expressions.

.. change::
:tags: sqlite, feature
:tickets: 2475

Added SQLite execution option
"sqlite_raw_colnames=True", will bypass
attempts to remove "." from column names
returned by SQLite cursor.description.

.. change::
:tags: sqlite, bug
:tickets: 2525

When the primary key column of a Table
is replaced, such as via extend_existing,
the "auto increment" column used by insert()
constructs is reset.  Previously it would
remain referring to the previous primary
key column.

.. changelog::

0.7.6

:released: Wed Mar 14 2012

.. change::
:tags: orm, bug
:tickets: 2424

Fixed event registration bug
which would primarily show up as
events not being registered with
sessionmaker() instances created
after the event was associated
with the Session class.

.. change::
:tags: orm, bug
:tickets: 2425

Fixed bug whereby a primaryjoin
condition with a "literal" in it would
raise an error on compile with certain
kinds of deeply nested expressions
which also needed to render the same
bound parameter name more than once.

.. change::
:tags: orm, feature
:tickets:

Added "no_autoflush" context
manager to Session, used with with:
will temporarily disable autoflush.

.. change::
:tags: orm, feature
:tickets: 1859

Added cte() method to Query,
invokes common table expression support
from the Core (see below).

.. change::
:tags: orm, bug
:tickets: 2403

Removed the check for number of
rows affected when doing a multi-delete
against mapped objects.   If an ON DELETE
CASCADE exists between two rows, we can't
get an accurate rowcount from the DBAPI;
this particular count is not supported
on most DBAPIs in any case, MySQLdb
is the notable case where it is.

.. change::
:tags: orm, bug
:tickets: 2409

Fixed bug whereby objects using
attribute_mapped_collection or
column_mapped_collection could not be
pickled.

.. change::
:tags: orm, bug
:tickets: 2406

Fixed bug whereby MappedCollection
would not get the appropriate collection
instrumentation if it were only used
in a custom subclass that used
collection.internally_instrumented.

.. change::
:tags: orm, bug
:tickets: 2419

Fixed bug whereby SQL adaption mechanics
would fail in a very nested scenario involving
joined-inheritance, joinedload(), limit(), and a
derived function in the columns clause.

.. change::
:tags: orm, bug
:tickets: 2417

Fixed the repr() for CascadeOptions to
include refresh-expire.  Also reworked
CascadeOptions to be a <frozenset>.

.. change::
:tags: orm, feature
:tickets: 2400

Added the ability to query for
Table-bound column names when using
query(sometable).filter_by(colname=value).

.. change::
:tags: orm, bug
:tickets:

Improved the "declarative reflection"
example to support single-table inheritance,
multiple calls to prepare(), tables that
are present in alternate schemas,
establishing only a subset of classes
as reflected.

.. change::
:tags: orm, bug
:tickets: 2390

Scaled back the test applied within
flush() to check for UPDATE against partially
NULL PK within one table to only actually
happen if there's really an UPDATE to occur.

.. change::
:tags: orm, bug
:tickets: 2352

Fixed bug whereby if a method name
conflicted with a column name, a
TypeError would be raised when the mapper
tried to inspect the __get__() method
on the method object.

.. change::
:tags: bug, sql
:tickets: 2427

Fixed memory leak in core which would
occur when C extensions were used with
particular types of result fetches,
in particular when orm query.count()
were called.

.. change::
:tags: bug, sql
:tickets: 2398

Fixed issue whereby attribute-based
column access on a row would raise
AttributeError with non-C version,
NoSuchColumnError with C version.  Now
raises AttributeError in both cases.

.. change::
:tags: feature, sql
:tickets: 1859

Added support for SQL standard
common table expressions (CTE), allowing
SELECT objects as the CTE source (DML
not yet supported).  This is invoked via
the cte() method on any select() construct.

.. change::
:tags: bug, sql
:tickets: 2392

Added support for using the .key
of a Column as a string identifier in a
result set row.   The .key is currently
listed as an "alternate" name for a column,
and is superseded by the name of a column
which has that key value as its regular name.
For the next major release
of SQLAlchemy we may reverse this precedence
so that .key takes precedence, but this
is not decided on yet.

.. change::
:tags: bug, sql
:tickets: 2413

A warning is emitted when a not-present
column is stated in the values() clause
of an insert() or update() construct.
Will move to an exception in 0.8.

.. change::
:tags: bug, sql
:tickets: 2396

A significant change to how labeling
is applied to columns in SELECT statements
allows "truncated" labels, that is label names
that are generated in Python which exceed
the maximum identifier length (note this is
configurable via label_length on create_engine()),
to be properly referenced when rendered inside
of a subquery, as well as to be present
in a result set row using their original
in-Python names.

.. change::
:tags: bug, sql
:tickets: 2402

Fixed bug in new "autoload_replace" flag
which would fail to preserve the primary
key constraint of the reflected table.

.. change::
:tags: bug, sql
:tickets: 2380

Index will raise when arguments passed
cannot be interpreted as columns or expressions.
Will warn when Index is created
with no columns at all.

.. change::
:tags: engine, feature
:tickets: 2407

Added "no_parameters=True" execution
option for connections.   If no parameters
are present, will pass the statement
as cursor.execute(statement), thereby invoking
the DBAPIs behavior when no parameter collection
is present; for psycopg2 and mysql-python, this
means not interpreting % signs in the string.
This only occurs with this option, and not
just if the param list is blank, as otherwise
this would produce inconsistent behavior
of SQL expressions that normally escape percent
signs (and while compiling, can't know ahead of
time if parameters will be present in
some cases).

.. change::
:tags: engine, bug
:tickets:

Added execution_options() call to
MockConnection (i.e., that used with
strategy="mock") which acts as a pass through
for arguments.

.. change::
:tags: engine, feature
:tickets: 2378

Added pool_reset_on_return argument
to create_engine, allows control over
"connection return" behavior.  Also added
new arguments 'rollback', 'commit', None
to pool.reset_on_return to allow more control
over connection return activity.

.. change::
:tags: engine, feature
:tickets:

Added some decent context managers
to Engine, Connection::

with engine.begin() as conn:
<work with conn in a transaction>

and::

with engine.connect() as conn:
<work with conn>

Both close out the connection when done,
commit or rollback transaction with errors
on engine.begin().

.. change::
:tags: sqlite, bug
:tickets: 2432

Fixed bug in C extensions whereby
string format would not be applied to a
Numeric value returned as integer; this
affected primarily SQLite which does
not maintain numeric scale settings.

.. change::
:tags: mssql, feature
:tickets: 2430

Added support for MSSQL INSERT,
UPDATE, and DELETE table hints, using
new with_hint() method on UpdateBase.

.. change::
:tags: feature, mysql
:tickets: 2386

Added support for MySQL index and
primary key constraint types
(i.e. USING) via new mysql_using parameter
to Index and PrimaryKeyConstraint,
courtesy Diana Clarke.

.. change::
:tags: feature, mysql
:tickets: 2394

Added support for the "isolation_level"
parameter to all MySQL dialects.  Thanks
to mu_mind for the patch here.

.. change::
:tags: oracle, feature
:tickets: 2399

Added a new create_engine() flag
coerce_to_decimal=False, disables the precision
numeric handling which can add lots of overhead
by converting all numeric values to
Decimal.

.. change::
:tags: oracle, bug
:tickets: 2401

Added missing compilation support for
LONG

.. change::
:tags: oracle, bug
:tickets: 2435

Added 'LEVEL' to the list of reserved
words for Oracle.

.. change::
:tags: examples, bug
:tickets:

Altered _params_from_query() function
in Beaker example to pull bindparams from the
fully compiled statement, as a quick means
to get everything including subqueries in the
columns clause, etc.

.. changelog::

0.7.5

:released: Sat Jan 28 2012

.. change::
:tags: orm, bug
:tickets: 2389

Fixed issue where modified session state
established after a failed flush would be committed
as part of the subsequent transaction that
begins automatically after manual call
to rollback().   The state of the session is
checked within rollback(), and if new state
is present, a warning is emitted and
restore_snapshot() is called a second time,
discarding those changes.

.. change::
:tags: orm, bug
:tickets: 2345

Fixed regression from 0.7.4 whereby
using an already instrumented column from a
superclass as "polymorphic_on" failed to resolve
the underlying Column.

.. change::
:tags: orm, bug
:tickets: 2370

Raise an exception if xyzload_all() is
used inappropriately with two non-connected
relationships.

.. change::
:tags: orm, feature
:tickets:

Added "class_registry" argument to
declarative_base().  Allows two or more declarative
bases to share the same registry of class names.

.. change::
:tags: orm, feature
:tickets:

query.filter() accepts multiple
criteria which will join via AND, i.e.
query.filter(x==y, z>q, ...)

.. change::
:tags: orm, feature
:tickets: 2351

Added new capability to relationship
loader options to allow "default" loader strategies.
Pass '*' to any of joinedload(), lazyload(),
subqueryload(), or noload() and that becomes the
loader strategy used for all relationships,
except for those explicitly stated in the
Query.  Thanks to up-and-coming contributor
Kent Bower for an exhaustive and well
written test suite !

.. change::
:tags: orm, bug
:tickets: 2367

Fixed bug whereby event.listen(SomeClass)
forced an entirely unnecessary compile of the
mapper, making events very hard to set up
at module import time (nobody noticed this ??)

.. change::
:tags: orm, bug
:tickets:

Fixed bug whereby hybrid_property didn't
work as a kw arg in any(), has().

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

Fixed regression from 0.6 whereby if
"load_on_pending" relationship() flag were used
where a non-"get()" lazy clause needed to be
emitted on a pending object, it would fail
to load.

.. change::
:tags: orm, bug
:tickets: 2371

ensure pickleability of all ORM exceptions
for multiprocessing compatibility.

.. change::
:tags: orm, bug
:tickets: 2353

implemented standard "can't set attribute" /
"can't delete attribute" AttributeError when
setattr/delattr used on a hybrid that doesn't
define fset or fdel.

.. change::
:tags: orm, bug
:tickets: 2362

Fixed bug where unpickled object didn't
have enough of its state set up to work
correctly within the unpickle() event established
by the mutable object extension, if the object
needed ORM attribute access within
__eq__() or similar.

.. change::
:tags: orm, bug
:tickets: 2374

Fixed bug where "merge" cascade could
mis-interpret an unloaded attribute, if the
load_on_pending flag were used with
relationship().  Thanks to Kent Bower
for tests.

.. change::
:tags: orm, feature
:tickets: 2356

New declarative reflection example
added, illustrates how best to mix table reflection
with declarative as well as uses some new features
from.

.. change::
:tags: feature, sql
:tickets: 2356

New reflection feature "autoload_replace";
when set to False on Table, the Table can be autoloaded
without existing columns being replaced.  Allows
more flexible chains of Table construction/reflection
to be constructed, including that it helps with
combining Declarative with table reflection.
See the new example on the wiki.

.. change::
:tags: bug, sql
:tickets: 2356

Improved the API for add_column() such that
if the same column is added to its own table,
an error is not raised and the constraints
don't get doubled up.  Also helps with some
reflection/declarative patterns.

.. change::
:tags: feature, sql
:tickets:

Added "false()" and "true()" expression
constructs to sqlalchemy.sql namespace, though
not part of __all__ as of yet.

.. change::
:tags: feature, sql
:tickets: 2361

Dialect-specific compilers now raise
CompileError for all type/statement compilation
issues, instead of InvalidRequestError or ArgumentError.
The DDL for CREATE TABLE will re-raise
CompileError to include table/column information
for the problematic column.

.. change::
:tags: bug, sql
:tickets: 2381

Fixed issue where the "required" exception
would not be raised for bindparam() with required=True,
if the statement were given no parameters at all.

.. change::
:tags: engine, bug
:tickets: 2371

Added __reduce__ to StatementError,
DBAPIError, column errors so that exceptions
are pickleable, as when using multiprocessing.
However, not
all DBAPIs support this yet, such as
psycopg2.

.. change::
:tags: engine, bug
:tickets: 2382

Improved error messages when a non-string
or invalid string is passed to any of the
date/time processors used by SQLite, including
C and Python versions.

.. change::
:tags: engine, bug
:tickets: 2377

Fixed bug whereby a table-bound Column
object named "<a>_<b>" which matched a column
labeled as "<tablename>_<colname>" could match
inappropriately when targeting in a result
set row.

.. change::
:tags: engine, bug
:tickets: 2384

Fixed bug in "mock" strategy whereby
correct DDL visit method wasn't called, resulting
in "CREATE/DROP SEQUENCE" statements being
duplicated

.. change::
:tags: sqlite, bug
:tickets: 2364

the "name" of an FK constraint in SQLite
is reflected as "None", not "0" or other
integer value.
SQLite does not appear to support constraint
naming in any case.

.. change::
:tags: sqlite, bug
:tickets: 2368

sql.false() and sql.true() compile to
0 and 1, respectively in sqlite

.. change::
:tags: sqlite, bug
:tickets:

removed an erroneous "raise" in the
SQLite dialect when getting table names
and view names, where logic is in place
to fall back to an older version of
SQLite that doesn't have the
"sqlite_temp_master" table.

.. change::
:tags: bug, mysql
:tickets: 2376

fixed regexp that filters out warnings
for non-reflected "PARTITION" directives,
thanks to George Reilly

.. change::
:tags: mssql, bug
:tickets: 2340

Adjusted the regexp used in the
mssql.TIME type to ensure only six digits
are received for the "microseconds" portion
of the value, which is expected by
Python's datetime.time().  Note that
support for sending microseconds doesn't
seem to be possible yet with pyodbc
at least.

.. change::
:tags: mssql, bug
:tickets: 2347

Dropped the "30 char" limit on pymssql,
based on reports that it's doing things
better these days.  pymssql hasn't been
well tested and as the DBAPI is in flux
it's still not clear what the status
is on this driver and how SQLAlchemy's
implementation should adapt.

.. change::
:tags: oracle, bug
:tickets: 2388

Added ORA-03135 to the never ending
list of oracle "connection lost" errors

.. change::
:tags: core, bug
:tickets: 2379

Changed LRUCache, used by the mapper
to cache INSERT/UPDATE/DELETE statements,
to use an incrementing counter instead
of a timestamp to track entries, for greater
reliability versus using time.time(), which
can cause test failures on some platforms.

.. change::
:tags: core, bug
:tickets: 2383

Added a boolean check for the "finalize"
function within the pool connection proxy's
weakref callback before calling it, so that a
warning isn't emitted that this function is None
when the application is exiting and gc has
removed the function from the module before the
weakref callback was invoked.

.. change::
:tags: bug, py3k
:tickets: 2348

Fixed inappropriate usage of util.py3k
flag and renamed it to util.py3k_warning, since
this flag is intended to detect the -3 flag
series of import restrictions only.

.. change::
:tags: examples, feature
:tickets: 2313

Simplified the versioning example
a bit to use a declarative mixin as well
as an event listener, instead of a metaclass +
SessionExtension.

.. change::
:tags: examples, bug
:tickets: 2346

Fixed large_collection.py to close the
session before dropping tables.

.. changelog::

0.7.4

:released: Fri Dec 09 2011

.. change::
:tags: orm, bug
:tickets: 2315

Fixed backref behavior when "popping" the
value off of a many-to-one in response to
a removal from a stale one-to-many - the operation
is skipped, since the many-to-one has since
been updated.

.. change::
:tags: orm, bug
:tickets: 2264

After some years of not doing this, added
more granularity to the "is X a parent of Y"
functionality, which is used when determining
if the FK on "Y" needs to be "nulled out" as well
as if "Y" should be deleted with delete-orphan
cascade.   The test now takes into account the
Python identity of the parent as well its identity
key, to see if the last known parent of Y is
definitely X.   If a decision
can't be made, a StaleDataError is raised.  The
conditions where this error is raised are fairly
rare, requiring that the previous parent was
garbage collected, and previously
could very well inappropriately update/delete
a record that's since moved onto a new parent,
though there may be some cases where
"silent success" occurred previously that will now
raise in the face of ambiguity.
Expiring "Y" resets the "parent" tracker, meaning
X.remove(Y) could then end up deleting Y even
if X is stale, but this is the same behavior
as before; it's advised to expire X also in that
case.

.. change::
:tags: orm, bug
:tickets: 2310

fixed inappropriate evaluation of user-mapped
object in a boolean context within query.get().  Also in 0.6.9.

.. change::
:tags: orm, bug
:tickets: 2304

Added missing comma to PASSIVE_RETURN_NEVER_SET
symbol

.. change::
:tags: orm, bug
:tickets: 1776

Cls.column.collate("some collation") now
works.   Also in 0.6.9

.. change::
:tags: orm, bug
:tickets: 2309

the value of a composite attribute is now
expired after an insert or update operation, instead
of regenerated in place.  This ensures that a
column value which is expired within a flush
will be loaded first, before the composite
is regenerated using that value.

.. change::
:tags: orm, bug
:tickets: 2309, 2308

The fix in also emits the
"refresh" event when the composite value is
loaded on access, even if all column
values were already present, as is appropriate.
This fixes the "mutable" extension which relies
upon the "load" event to ensure the _parents
dictionary is up to date, fixes.
Thanks to Scott Torborg for the test case here.

.. change::
:tags: orm, bug
:tickets: 2312

Fixed bug whereby a subclass of a subclass
using concrete inheritance in conjunction with
the new ConcreteBase or AbstractConcreteBase
would fail to apply the subclasses deeper than
one level to the "polymorphic loader" of each
base

.. change::
:tags: orm, bug
:tickets: 2312

Fixed bug whereby a subclass of a subclass
using the new AbstractConcreteBase would fail
to acquire the correct "base_mapper" attribute
when the "base" mapper was generated, thereby
causing failures later on.

.. change::
:tags: orm, bug
:tickets: 2316

Fixed bug whereby column_property() created
against ORM-level column could be treated as
a distinct entity when producing certain
kinds of joined-inh joins.

.. change::
:tags: orm, bug
:tickets: 2297

Fixed the error formatting raised when
a tuple is inadvertently passed to session.query().  Also in 0.6.9.

.. change::
:tags: orm, bug
:tickets: 2328

Calls to query.join() to a single-table
inheritance subclass are now tracked, and
are used to eliminate the additional WHERE..
IN criterion normally tacked on with single
table inheritance, since the join should
accommodate it.  This allows OUTER JOIN
to a single table subclass to produce
the correct results, and overall will produce
fewer WHERE criterion when dealing with
single table inheritance joins.

.. change::
:tags: orm, bug
:tickets: 2339

__table_args__ can now be passed as
an empty tuple as well as an empty dict..  Thanks to Fayaz Yusuf Khan
for the patch.

.. change::
:tags: orm, bug
:tickets: 2325

Updated warning message when setting
delete-orphan without delete to no longer
refer to 0.6, as we never got around to
upgrading this to an exception.  Ideally
this might be better as an exception but
it's not critical either way.

.. change::
:tags: orm, feature
:tickets: 2345, 2238

polymorphic_on now accepts many
new kinds of values:

* standalone expressions that aren't
otherwise mapped
* column_property() objects
* string names of any column_property()
or attribute name of a mapped Column

The docs include an example using
the case() construct, which is likely to be
a common constructed used here. and part of

Standalone expressions in polymorphic_on
propagate to single-table inheritance
subclasses so that they are used in the
WHERE /JOIN clause to limit rows to that
subclass as is the usual behavior.

.. change::
:tags: orm, feature
:tickets: 2301

IdentitySet supports the - operator
as the same as difference(), handy when dealing
with Session.dirty etc.

.. change::
:tags: orm, feature
:tickets:

Added new value for Column autoincrement
called "ignore_fk", can be used to force autoincrement
on a column that's still part of a ForeignKeyConstraint.
New example in the relationship docs illustrates
its use.

.. change::
:tags: orm, bug
:tickets:

Fixed bug in get_history() when referring
to a composite attribute that has no value;
added coverage for get_history() regarding
composites which is otherwise just a userland
function.

.. change::
:tags: bug, sql
:tickets: 2316, 2261

related to, made some
adjustments to the change from
regarding the "from" list on a select(). The
_froms collection is no longer memoized, as this
simplifies various use cases and removes the
need for a "warning" if a column is attached
to a table after it was already used in an
expression - the select() construct will now
always produce the correct expression.
There's probably no real-world
performance hit here; select() objects are
almost always made ad-hoc, and systems that
wish to optimize the re-use of a select()
would be using the "compiled_cache" feature.
A hit which would occur when calling select.bind
has been reduced, but the vast majority
of users shouldn't be using "bound metadata"
anyway :).

.. change::
:tags: feature, sql
:tickets: 2166, 1944

The update() construct can now accommodate
multiple tables in the WHERE clause, which will
render an "UPDATE..FROM" construct, recognized by
PostgreSQL and MSSQL.  When compiled on MySQL,
will instead generate "UPDATE t1, t2, ..".  MySQL
additionally can render against multiple tables in the
SET clause, if Column objects are used as keys
in the "values" parameter or generative method.

.. change::
:tags: feature, sql
:tickets: 77

Added accessor to types called "python_type",
returns the rudimentary Python type object
for a particular TypeEngine instance, if known,
else raises NotImplementedError.

.. change::
:tags: bug, sql
:tickets: 2261, 2319

further tweak to the fix from,
so that generative methods work a bit better
off of cloned (this is almost a non-use case though).
In particular this allows with_only_columns()
to behave more consistently.   Added additional
documentation to with_only_columns() to clarify
expected behavior, which changed as a result
of.

.. change::
:tags: engine, bug
:tickets: 2317

Fixed bug whereby transaction.rollback()
would throw an error on an invalidated
connection if the transaction were a
two-phase or savepoint transaction.
For plain transactions, rollback() is a no-op
if the connection is invalidated, so while
it wasn't 100% clear if it should be a no-op,
at least now the interface is consistent.

.. change::
:tags: feature, schema
:tickets:

Added new support for remote "schemas":

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

MetaData() accepts "schema" and "quote_schema"
arguments, which will be applied to the same-named
arguments of a Table
or Sequence which leaves these at their default
of ``None``.

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

Sequence accepts "quote_schema" argument

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

tometadata() for Table will use the "schema"
of the incoming MetaData for the new Table
if the schema argument is explicitly "None"

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

Added CreateSchema and DropSchema DDL
constructs - these accept just the string
name of a schema and a "quote" flag.

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

When using default "schema" with MetaData,
ForeignKey will also assume the "default" schema
when locating remote table.  This allows the "schema"
argument on MetaData to be applied to any
set of Table objects that otherwise don't have
a "schema".

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

a "has_schema" method has been implemented
on dialect, but only works on PostgreSQL so far.
Courtesy Manlio Perillo.

.. change::
:tags: feature, schema
:tickets: 1410

The "extend_existing" flag on Table
now allows for the reflection process to take
effect for a Table object that's already been
defined; when autoload=True and extend_existing=True
are both set, the full set of columns will be
reflected from the Table which will then
*overwrite* those columns already present,
rather than no activity occurring.  Columns that
are present directly in the autoload run
will be used as always, however.

.. change::
:tags: bug, schema
:tickets:

Fixed bug whereby TypeDecorator would
return a stale value for _type_affinity, when
using a TypeDecorator that "switches" types,
like the CHAR/UUID type.

.. change::
:tags: bug, schema
:tickets:

Fixed bug whereby "order_by='foreign_key'"
option to Inspector.get_table_names
wasn't implementing the sort properly, replaced
with the existing sort algorithm

.. change::
:tags: bug, schema
:tickets: 2305

the "name" of a column-level CHECK constraint,
if present, is now rendered in the CREATE TABLE
statement using "CONSTRAINT <name> CHECK <expression>".

.. change::
:tags: pyodbc, bug
:tickets: 2318

pyodbc-based dialects now parse the
pyodbc accurately as far as observed
pyodbc strings, including such gems
as "py3-3.0.1-beta4"

.. change::
:tags: postgresql, bug
:tickets: 2311

PostgreSQL dialect memoizes that an ENUM of a
particular name was processed
during a create/drop sequence.  This allows
a create/drop sequence to work without any
calls to "checkfirst", and also means with
"checkfirst" turned on it only needs to
check for the ENUM once.

.. change::
:tags: postgresql, feature
:tickets:

Added create_type constructor argument
to pg.ENUM.  When False, no CREATE/DROP or
checking for the type will be performed as part
of a table create/drop event; only the
create()/drop)() methods called directly
will do this.  Helps with Alembic "offline"
scripts.

.. change::
:tags: mssql, feature
:tickets: 822

lifted the restriction on SAVEPOINT
for SQL Server.  All tests pass using it,
it's not known if there are deeper issues
however.

.. change::
:tags: mssql, bug
:tickets: 2336

repaired the with_hint() feature which
wasn't implemented correctly on MSSQL -
usually used for the "WITH (NOLOCK)" hint
(which you shouldn't be using anyway !
use snapshot isolation instead :) )

.. change::
:tags: mssql, bug
:tickets: 2318

use new pyodbc version detection for
_need_decimal_fix option.

.. change::
:tags: mssql, bug
:tickets: 2343

don't cast "table name" as NVARCHAR
on SQL Server 2000.  Still mostly in the dark
what incantations are needed to make PyODBC
work fully with FreeTDS 0.91 here, however.

.. change::
:tags: mssql, bug
:tickets: 2269

Decode incoming values when retrieving
list of index names and the names of columns
within those indexes.

.. change::
:tags: bug, mysql
:tickets:

Unicode adjustments allow latest pymysql
(post 0.4) to pass 100% on Python 2.

.. change::
:tags: ext, feature
:tickets:

Added an example to the hybrid docs
of a "transformer" - a hybrid that returns a
query-transforming callable in combination
with a custom comparator.   Uses a new method
on Query called with_transformation().  The use
case here is fairly experimental, but only
adds one line of code to Query.

.. change::
:tags: ext, bug
:tickets:

the compiles decorator raises an
informative error message when no "default"
compilation handler is present, rather
than KeyError.

.. change::
:tags: examples, bug
:tickets:

Fixed bug in history_meta.py example where
the "unique" flag was not removed from a
single-table-inheritance subclass which
generates columns to put up onto the base.

.. changelog::

0.7.3

:released: Sun Oct 16 2011

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

Adjusted the "importlater" mechanism, which is
used internally to resolve import cycles,
such that the usage of __import__ is completed
when the import of sqlalchemy or sqlalchemy.orm
is done, thereby avoiding any usage of __import__
after the application starts new threads,
fixes.  Also in 0.6.9.

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

Improved query.join() such that the "left" side
can more flexibly be a non-ORM selectable,
such as a subquery.   A selectable placed
in select_from() will now be used as the left
side, favored over implicit usage
of a mapped entity.
If the join still fails based on lack of
foreign keys, the error message includes
this detail.  Thanks to brianrhude
on IRC for the test case.

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

Added after_soft_rollback() Session event.  This
event fires unconditionally whenever rollback()
is called, regardless of if an actual DBAPI
level rollback occurred.  This event
is specifically designed to allow operations
with the Session to proceed after a rollback
when the Session.is_active is True.

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

added "adapt_on_names" boolean flag to orm.aliased()
construct.  Allows an aliased() construct
to link the ORM entity to a selectable that contains
aggregates or other derived forms of a particular
attribute, provided the name is the same as that
of the entity mapped column.

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

Added new flag expire_on_flush=False to column_property(),
marks those properties that would otherwise be considered
to be "readonly", i.e. derived from SQL expressions,
to retain their value after a flush has occurred, including
if the parent object itself was involved in an update.

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

Enhanced the instrumentation in the ORM to support
Py3K's new argument style of "required kw arguments",
i.e. fn(a, b, \*, c, d), fn(a, b, \*args, c, d).
Argument signatures of mapped object's __init__
method will be preserved, including required kw rules.

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

Fixed bug in unit of work whereby detection of
"cycles" among classes in highly interlinked patterns
would not produce a deterministic
result; thereby sometimes missing some nodes that
should be considered cycles and causing further
issues down the road.  Note this bug is in 0.6
also; not backported at the moment.

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

Fixed a variety of synonym()-related regressions
from 0.6:

* making a synonym against a synonym now works.
* synonyms made against a relationship() can
be passed to query.join(), options sent
to query.options(), passed by name
to query.with_parent().

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

Fixed bug whereby mapper.order_by attribute would
be ignored in the "inner" query within a
subquery eager load. .
Also in 0.6.9.

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

Identity map .discard() uses dict.pop(,None)
internally instead of "del" to avoid KeyError/warning
during a non-determinate gc teardown

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

Fixed regression in new composite rewrite where
deferred=True option failed due to missing
import

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

Reinstated "comparator_factory" argument to
composite(), removed when 0.7 was released.

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

Fixed bug in query.join() which would occur
in a complex multiple-overlapping path scenario,
where the same table could be joined to
twice.  Thanks *much* to Dave Vitek
for the excellent fix here.

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

Query will convert an OFFSET of zero when
slicing into None, so that needless OFFSET
clauses are not invoked.

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

Repaired edge case where mapper would fail
to fully update internal state when a relationship
on a new mapper would establish a backref on the
first mapper.

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

Fixed bug whereby if __eq__() was
redefined, a relationship many-to-one lazyload
would hit the __eq__() and fail.
Does not apply to 0.6.9.

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

Calling class_mapper() and passing in an object
that is not a "type" (i.e. a class that could
potentially be mapped) now raises an informative
ArgumentError, rather than UnmappedClassError.

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

New event hook, MapperEvents.after_configured().
Called after a configure() step has completed and
mappers were in fact affected.   Theoretically this
event is called once per application, unless new mappings
are constructed after existing ones have been used
already.

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

When an open Session is garbage collected, the objects
within it which remain are considered detached again
when they are add()-ed to a new Session.
This is accomplished by an extra check that the previous
"session_key" doesn't actually exist among the pool
of Sessions.

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

New declarative features:

* __declare_last__() method, establishes an event
listener for the class method that will be called
when mappers are completed with the final "configure"
step.
* __abstract__ flag.   The class will not be mapped
at all when this flag is present on the class.
* New helper classes ConcreteBase, AbstractConcreteBase.
Allow concrete mappings using declarative which automatically
set up the "polymorphic_union" when the "configure"
mapper step is invoked.
* The mapper itself has semi-private methods that allow
the "with_polymorphic" selectable to be assigned
to the mapper after it has already been configured.

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

Declarative will warn when a subclass' base uses
declared_attr for a regular column - this attribute
does not propagate to subclasses.

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

The integer "id" used to link a mapped instance with
its owning Session is now generated by a sequence
generation function rather than id(Session), to
eliminate the possibility of recycled id() values
causing an incorrect result, no need to check that
object actually in the session.

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

Behavioral improvement: empty
conjunctions such as and_() and or_() will be
flattened in the context of an enclosing conjunction,
i.e. and_(x, or_()) will produce 'X' and not 'X AND
()'..

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

Fixed bug regarding calculation of "from" list
for a select() element.  The "from" calc is now
delayed, so that if the construct uses a Column
object that is not yet attached to a Table,
but is later associated with a Table, it generates
SQL using the table as a FROM.   This change
impacted fairly deeply the mechanics of how
the FROM list as well as the "correlates" collection
is calculated, as some "clause adaption" schemes
(these are used very heavily in the ORM)
were relying upon the fact that the "froms"
collection would typically be cached before the
adaption completed.   The rework allows it
such that the "froms" collection can be cleared
and re-generated at any time.

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

Fixed bug whereby with_only_columns() method of
Select would fail if a selectable were passed..  Also in 0.6.9.

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

Modified Column.copy() to use _constructor(),
which defaults to self.__class__, in order to
create the new object.  This allows easier support
of subclassing Column.

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

Added a slightly nicer __repr__() to SchemaItem
classes.  Note the repr here can't fully support
the "repr is the constructor" idea since schema
items can be very deeply nested/cyclical, have
late initialization of some things, etc.

.. change::
:tags: engine
:tickets: 2254

The recreate() method in all pool classes uses
self.__class__ to get at the type of pool
to produce, in the case of subclassing.  Note
there's no usual need to subclass pools.

.. change::
:tags: engine
:tickets: 2243

Improvement to multi-param statement logging,
long lists of bound parameter sets will be
compressed with an informative indicator
of the compression taking place.  Exception
messages use the same improved formatting.

.. change::
:tags: engine
:tickets:

Added optional "sa_pool_key" argument to
pool.manage(dbapi).connect() so that serialization
of args is not necessary.

.. change::
:tags: engine
:tickets: 2286

The entry point resolution supported by
create_engine() now supports resolution of
individual DBAPI drivers on top of a built-in
or entry point-resolved dialect, using the
standard '+' notation - it's converted to
a '.' before being resolved as an entry
point.

.. change::
:tags: engine
:tickets: 2299

Added an exception catch + warning for the
"return unicode detection" step within connect,
allows databases that crash on NVARCHAR to
continue initializing, assuming no NVARCHAR
type implemented.

.. change::
:tags: types
:tickets: 2258

Extra keyword arguments to the base Float
type beyond "precision" and "asdecimal" are ignored;
added a deprecation warning here and additional
docs, related to

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

Ensured that the same ValueError is raised for
illegal date/time/datetime string parsed from
the database regardless of whether C
extensions are in use or not.

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

Added "postgresql_using" argument to Index(), produces
USING clause to specify index implementation for
PG. .  Thanks to Ryan P. Kelly for
the patch.

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

Added client_encoding parameter to create_engine()
when the postgresql+psycopg2 dialect is used;
calls the psycopg2 set_client_encoding() method
with the value upon connect.

.. change::
:tags: postgresql
:tickets: 2291, 2141

Fixed bug related to whereby the
same modified index behavior in PG 9 affected
primary key reflection on a renamed column..  Also in 0.6.9.

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

Reflection functions for Table, Sequence no longer
case insensitive.  Names can be differ only in case
and will be correctly distinguished.

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

Use an atomic counter as the "random number"
source for server side cursor names;
conflicts have been reported in rare cases.

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

Narrowed the assumption made when reflecting
a foreign-key referenced table with schema in
the current search path; an explicit schema will
be applied to the referenced table only if
it actually matches that of the referencing table,
which also has an explicit schema.   Previously
it was assumed that "current" schema was synonymous
with the full search_path.

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

a CREATE TABLE will put the COLLATE option
after CHARSET, which appears to be part of
MySQL's arbitrary rules regarding if it will actually
work or not.   Also in 0.6.9.

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

Added mysql_length parameter to Index construct,
specifies "length" for indexes.

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

Changes to attempt support of FreeTDS 0.91 with
Pyodbc.  This includes that string binds are sent as
Python unicode objects when FreeTDS 0.91 is detected,
and a CAST(? AS NVARCHAR) is used when we detect
for a table.   However, I'd continue
to characterize Pyodbc + FreeTDS 0.91 behavior as
pretty crappy, there are still many queries such
as used in reflection which cause a core dump on
Linux, and it is not really usable at all
on OSX, MemoryErrors abound and just plain broken
unicode support.

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

The behavior of =/!= when comparing a scalar select
to a value will no longer produce IN/NOT IN as of 0.8;
this behavior is a little too heavy handed (use in_() if
you want to emit IN) and now emits a deprecation warning.
To get the 0.8 behavior immediately and remove the warning,
a compiler recipe is given at
http://www.sqlalchemy.org/docs/07/dialects/mssql.htmlscalar-select-comparisons
to override the behavior of visit_binary().

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

"0" is accepted as an argument for limit() which
will produce "TOP 0".

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

Fixed ReturningResultProxy for zxjdbc dialect..  Regression from 0.6.

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

The String type now generates VARCHAR2 on Oracle
which is recommended as the default VARCHAR.
Added an explicit VARCHAR2 and NVARCHAR2 to the Oracle
dialect as well.   Using NVARCHAR still generates
"NVARCHAR2" - there is no "NVARCHAR" on Oracle -
this remains a slight breakage of the "uppercase types
always give exactly that" policy.  VARCHAR still
generates "VARCHAR", keeping with the policy.   If
Oracle were to ever define "VARCHAR" as something
different as they claim (IMHO this will never happen),
the type would be available.

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

SQLSoup will not be included in version 0.8
of SQLAlchemy; while useful, we would like to
keep SQLAlchemy itself focused on one ORM
usage paradigm.  SQLSoup will hopefully
soon be superseded by a third party
project.

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

Added local_attr, remote_attr, attr accessors
to AssociationProxy, providing quick access
to the proxied attributes at the class
level.

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

Changed the update() method on association proxy
dictionary to use a duck typing approach, i.e.
checks for "keys", to discern between update({})
and update((a, b)).   Previously, passing a
dictionary that had tuples as keys would be misinterpreted
as a sequence.

.. change::
:tags: examples
:tickets: 2266

Adjusted dictlike-polymorphic.py example
to apply the CAST such that it works on
PG, other databases.
Also in 0.6.9.

.. changelog::

0.7.2

:released: Sun Jul 31 2011

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

Feature enhancement: joined and subquery
loading will now traverse already-present related
objects and collections in search of unpopulated
attributes throughout the scope of the eager load
being defined, so that the eager loading that is
specified via mappings or query options
unconditionally takes place for the full depth,
populating whatever is not already populated.
Previously, this traversal would stop if a related
object or collection were already present leading
to inconsistent behavior (though would save on
loads/cycles for an already-loaded graph). For a
subqueryload, this means that the additional
SELECT statements emitted by subqueryload will
invoke unconditionally, no matter how much of the
existing graph is already present (hence the
controversy). The previous behavior of "stopping"
is still in effect when a query is the result of
an attribute-initiated lazyload, as otherwise an
"N+1" style of collection iteration can become
needlessly expensive when the same related object
is encountered repeatedly. There's also an
as-yet-not-public generative Query method
_with_invoke_all_eagers()
which selects old/new behavior

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

A rework of "replacement traversal" within
the ORM as it alters selectables to be against
aliases of things (i.e. clause adaption) includes
a fix for multiply-nested any()/has() constructs
against a joined table structure.

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

Fixed bug where query.join() + aliased=True
from a joined-inh structure to itself on
relationship() with join condition on the child
table would convert the lead entity into the
joined one inappropriately.
Also in 0.6.9.

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

Fixed regression from 0.6 where Session.add()
against an object which contained None in a
collection would raise an internal exception.
Reverted this to 0.6's behavior which is to
accept the None but obviously nothing is
persisted.  Ideally, collections with None
present or on append() should at least emit a
warning, which is being considered for 0.8.

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

Load of a deferred() attribute on an object
where row can't be located raises
ObjectDeletedError instead of failing later
on; improved the message in ObjectDeletedError
to include other conditions besides a simple
"delete".

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

Fixed regression from 0.6 where a get history
operation on some relationship() based attributes
would fail when a lazyload would emit; this could
trigger within a flush() under certain conditions.  Thanks to the user who submitted
the great test for this.

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

Fixed bug apparent only in Python 3 whereby
sorting of persistent + pending objects during
flush would produce an illegal comparison,
if the persistent object primary key
is not a single integer.
Also in 0.6.9

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

Fixed bug whereby the source clause
used by query.join() would be inconsistent
if against a column expression that combined
multiple entities together.
Also in 0.6.9

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

Fixed bug whereby if a mapped class
redefined __hash__() or __eq__() to something
non-standard, which is a supported use case
as SQLA should never consult these,
the methods would be consulted if the class
was part of a "composite" (i.e. non-single-entity)
result set.
Also in 0.6.9.

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

Added public attribute ".validators" to
Mapper, an immutable dictionary view of
all attributes that have been decorated
with the validates decorator. courtesy Stefano Fontanelli

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

Fixed subtle bug that caused SQL to blow
up if: column_property() against subquery +
joinedload + LIMIT + order by the column
property() occurred. .
Also in 0.6.9

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

The join condition produced by with_parent
as well as when using a "dynamic" relationship
against a parent will generate unique
bindparams, rather than incorrectly repeating
the same bindparam. .
Also in 0.6.9.

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

Added the same "columns-only" check to
mapper.polymorphic_on as used when
receiving user arguments to
relationship.order_by, foreign_keys,
remote_side, etc.

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

Fixed bug whereby comparison of column
expression to a Query() would not call
as_scalar() on the underlying SELECT
statement to produce a scalar subquery,
in the way that occurs if you called
it on Query().subquery().

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

Fixed declarative bug where a class inheriting
from a superclass of the same name would fail
due to an unnecessary lookup of the name
in the _decl_class_registry.

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

Repaired the "no statement condition"
assertion in Query which would attempt
to raise if a generative method were called
after from_statement() were called..  Also in 0.6.9.

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

Fixed two subtle bugs involving column
correspondence in a selectable,
one with the same labeled subquery repeated, the other
when the label has been "grouped" and
loses itself.  Affects.

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

New feature: with_variant() method on
all types.  Produces an instance of Variant(),
a special TypeDecorator which will select
the usage of a different type based on the
dialect in use.

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

Added an informative error message when
ForeignKeyConstraint refers to a column name in
the parent that is not found.  Also in 0.6.9.

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

Fixed bug whereby adaptation of old append_ddl_listener()
function was passing unexpected \**kw through
to the Table event.   Table gets no kws, the MetaData
event in 0.6 would get "tables=somecollection",
this behavior is preserved.

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

Fixed bug where "autoincrement" detection on
Table would fail if the type had no "affinity"
value, in particular this would occur when using
the UUID example on the site that uses TypeEngine
as the "impl".

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

Added an improved repr() to TypeEngine objects
that will only display constructor args which
are positional or kwargs that deviate
from the default.

.. change::
:tags: engine
:tickets:

Context manager provided by Connection.begin()
will issue rollback() if the commit() fails,
not just if an exception occurs.

.. change::
:tags: engine
:tickets: 1682

Use urllib.parse_qsl() in Python 2.6 and above,
no deprecation warning about cgi.parse_qsl()

.. change::
:tags: engine
:tickets:

Added mixin class sqlalchemy.ext.DontWrapMixin.
User-defined exceptions of this type are never
wrapped in StatementException when they
occur in the context of a statement
execution.

.. change::
:tags: engine
:tickets:

StatementException wrapping will display the
original exception class in the message.

.. change::
:tags: engine
:tickets: 2201

Failures on connect which raise dbapi.Error
will forward the error to dialect.is_disconnect()
and set the "connection_invalidated" flag if
the dialect knows this to be a potentially
"retryable" condition.  Only Oracle ORA-01033
implemented for now.

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

SQLite dialect no longer strips quotes
off of reflected default value, allowing
a round trip CREATE TABLE to work.
This is consistent with other dialects
that also maintain the exact form of
the default.

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

Added new "postgresql_ops" argument to
Index, allows specification of PostgreSQL
operator classes for indexed columns.  Courtesy Filip Zyzniewski.

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

Fixed OurSQL dialect to use ansi-neutral
quote symbol "'" for XA commands instead
of '"'. .  Also in 0.6.9.

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

Adjusted the pyodbc dialect such that bound
values are passed as bytes and not unicode
if the "Easysoft" unix drivers are detected.
This is the same behavior as occurs with
FreeTDS.  Easysoft appears to segfault
if Python unicodes are passed under
certain circumstances.

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

Added ORA-00028 to disconnect codes, use
cx_oracle _Error.code to get at the code,.  Also in 0.6.9.

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

Added ORA-01033 to disconnect codes, which
can be caught during a connection
event.

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

repaired the oracle.RAW type which did not
generate the correct DDL.
Also in 0.6.9.

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

added CURRENT to reserved word list. Also in 0.6.9.

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

Fixed bug in the mutable extension whereby
if the same type were used twice in one
mapping, the attributes beyond the first
would not get instrumented.

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

Fixed bug in the mutable extension whereby
if None or a non-corresponding type were set,
an error would be raised.  None is now accepted
which assigns None to all attributes,
illegal values raise ValueError.

.. change::
:tags: examples
:tickets:

Repaired the examples/versioning test runner
to not rely upon SQLAlchemy test libs,
nosetests must be run from within
examples/versioning to get around setup.cfg
breaking it.

.. change::
:tags: examples
:tickets:

Tweak to examples/versioning to pick the
correct foreign key in a multi-level
inheritance situation.

.. change::
:tags: examples
:tickets:

Fixed the attribute shard example to check
for bind param callable correctly in 0.7
style.

.. changelog::

0.7.1

:released: Sun Jun 05 2011

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

Added a workaround for Python bug 7511 where
failure of C extension build does not
raise an appropriate exception on Windows 64
bit + VC express

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

"delete-orphan" cascade is now allowed on
self-referential relationships - this since
SQLA 0.7 no longer enforces "parent with no
child" at the ORM level; this check is left
up to foreign key nullability.
Related to

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

Repaired new "mutable" extension to propagate
events to subclasses correctly; don't
create multiple event listeners for
subclasses either.

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

Modify the text of the message which occurs
when the "identity" key isn't detected on
flush, to include the common cause that
the Column isn't set up to detect
auto-increment correctly;.
Also in 0.6.8.

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

Fixed bug where transaction-level "deleted"
collection wouldn't be cleared of expunged
states, raising an error if they later
became transient.
Also in 0.6.8.

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

Fixed bug whereby metadata.reflect(bind)
would close a Connection passed as a
bind argument.  Regression from 0.6.

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

Streamlined the process by which a Select
determines what's in its '.c' collection.
Behaves identically, except that a
raw ClauseList() passed to select([])
(which is not a documented case anyway) will
now be expanded into its individual column
elements instead of being ignored.

.. change::
:tags: engine
:tickets:

Deprecate schema/SQL-oriented methods on
Connection/Engine that were never well known
and are redundant:  reflecttable(), create(),
drop(), text(), engine.func

.. change::
:tags: engine
:tickets: 2178

Adjusted the __contains__() method of
a RowProxy result row such that no exception
throw is generated internally;
NoSuchColumnError() also will generate its
message regardless of whether or not the column
construct can be coerced to a string..  Also in 0.6.8.

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

Accept None from cursor.fetchone() when
"PRAGMA read_uncommitted" is called to determine
current isolation mode at connect time and
default to SERIALIZABLE; this to support SQLite
versions pre-3.3.0 that did not have this
feature.

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

Some unit test fixes regarding numeric arrays,
MATCH operator.   A potential floating-point
inaccuracy issue was fixed, and certain tests
of the MATCH operator only execute within an
EN-oriented locale for now. .
Also in 0.6.8.

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

Unit tests pass 100% on MySQL installed
on windows.

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

Removed the "adjust casing" step that would
fail when reflecting a table on MySQL
on windows with a mixed case name.  After some
experimenting with a windows MySQL server, it's
been determined that this step wasn't really
helping the situation much; MySQL does not return
FK names with proper casing on non-windows
platforms either, and removing the step at
least allows the reflection to act more like
it does on other OSes.   A warning here
has been considered but its difficult to
determine under what conditions such a warning
can be raised, so punted on that for now -
added some docs instead.

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

supports_sane_rowcount will be set to False
if using MySQLdb and the DBAPI doesn't provide
the constants.CLIENT module.

.. changelog::

0.7.0

:released: Fri May 20 2011

.. change::
:tags:
:tickets:

This section documents those changes from 0.7b4
to 0.7.0.  For an overview of what's new in
SQLAlchemy 0.7, see
http://docs.sqlalchemy.org/en/latest/changelog/migration_07.html

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

Fixed regression introduced in 0.7b4 (!) whereby
query.options(someoption("nonexistent name")) would
fail to raise an error.  Also added additional
error catching for cases where the option would
try to build off a column-based element, further
fixed up some of the error messages tailored
in

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

query.count() emits "count(*)" instead of
"count(1)".

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

Fine tuning of Query clause adaptation when
from_self(), union(), or other "select from
myself" operation, such that plain SQL expression
elements added to filter(), order_by() etc.
which are present in the nested "from myself"
query *will* be adapted in the same way an ORM
expression element will, since these
elements are otherwise not easily accessible.

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

Fixed bug where determination of "self referential"
relationship would fail with no workaround
for joined-inh subclass related to itself,
or joined-inh subclass related to a subclass
of that with no cols in the sub-sub class
in the join condition.
Also in 0.6.8.

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

mapper() will ignore non-configured foreign keys
to unrelated tables when determining inherit
condition between parent and child class,
but will raise as usual for unresolved
columns and table names regarding the inherited
table.  This is an enhanced generalization of
behavior that was already applied to declarative
previously.    0.6.8 has a more
conservative version of this which doesn't
fundamentally alter how join conditions
are determined.

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

It is an error to call query.get() when the
given entity is not a single, full class
entity or mapper (i.e. a column).  This is
a deprecation warning in 0.6.8.

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

Fixed a potential KeyError which under some
circumstances could occur with the identity
map, part of

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

added Query.with_session() method, switches
Query to use a different session.

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

horizontal shard query should use execution
options per connection as per

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

a non_primary mapper will inherit the _identity_class
of the primary mapper.  This so that a non_primary
established against a class that's normally in an
inheritance mapping will produce results that are
identity-map compatible with that of the primary
mapper (also in 0.6.8)

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

Fixed the error message emitted for "can't
execute syncrule for destination column 'q';
mapper 'X' does not map this column" to
reference the correct mapper. .
Also in 0.6.8.

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

polymorphic_union() gets a "cast_nulls" option,
disables the usage of CAST when it renders
the labeled NULL columns.

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

polymorphic_union() renders the columns in their
original table order, as according to the first
table/selectable in the list of polymorphic
unions in which they appear.  (which is itself
an unordered mapping unless you pass an OrderedDict).

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

Fixed bug whereby mapper mapped to an anonymous
alias would fail if logging were used, due to
unescaped % sign in the alias name.
Also in 0.6.8.

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

Fixed bug whereby nesting a label of a select()
with another label in it would produce incorrect
exported columns.   Among other things this would
break an ORM column_property() mapping against
another column_property(). .
Also in 0.6.8

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

Changed the handling in determination of join
conditions such that foreign key errors are
only considered between the two given tables.
That is, t1.join(t2) will report FK errors
that involve 't1' or 't2', but anything
involving 't3' will be skipped.   This affects
join(), as well as ORM relationship and
inherit condition logic.

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

Some improvements to error handling inside
of the execute procedure to ensure auto-close
connections are really closed when very
unusual DBAPI errors occur.

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

metadata.reflect() and reflection.Inspector()
had some reliance on GC to close connections
which were internally procured, fixed this.

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

Added explicit check for when Column .name
is assigned as blank string

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

Fixed bug whereby if FetchedValue was passed
to column server_onupdate, it would not
have its parent "column" assigned, added
test coverage for all column default assignment
patterns.   also in 0.6.8

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

Fixed the psycopg2_version parsing in the
psycopg2 dialect.

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

Fixed bug affecting PG 9 whereby index reflection
would fail if against a column whose name
had changed. .  Also in 0.6.8.

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

Fixed bug in MSSQL dialect whereby the aliasing
applied to a schema-qualified table would leak
into enclosing select statements.
Also in 0.6.8.

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

Removed the usage of the "collections.MutableMapping"
abc from the ext.mutable docs as it was being used
incorrectly and makes the example more difficult
to understand in any case.

.. change::
:tags: examples
:tickets:

removed the ancient "polymorphic association"
examples and replaced with an updated set of
examples that use declarative mixins,
"generic_associations".   Each presents an alternative
table layout.

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

Fixed bugs in sqlalchemy.ext.mutable extension where
`None` was not appropriately handled, replacement
events were not appropriately handled.

.. changelog::
:version: 0.7.0b4
:released: Sun Apr 17 2011

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

Changes to the format of CHANGES, this file.
The format changes have been applied to
the 0.7 releases.

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

The "-declarative" changes will now be listed
directly under the "-orm" section, as these
are closely related.

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

The 0.5 series changes have been moved to
the file CHANGES_PRE_06 which replaces
CHANGES_PRE_05.

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

The changelog for 0.6.7 and subsequent within
the 0.6 series is now listed only in the
CHANGES file within the 0.6 branch.
In the 0.7 CHANGES file (i.e. this file), all the
0.6 changes are listed inline within the 0.7
section in which they were also applied
(since all 0.6 changes are in 0.7 as well).
Changes that apply to an 0.6 version here
are noted as are if any differences in
implementation/behavior are present.

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

Some fixes to "evaluate" and "fetch" evaluation
when query.update(), query.delete() are called.
The retrieval of records is done after autoflush
in all cases, and before update/delete is
emitted, guarding against unflushed data present
as well as expired objects failing during
the evaluation.

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

Reworded the exception raised when a flush
is attempted of a subclass that is not polymorphic
against the supertype.

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

Still more wording adjustments when a query option
can't find the target entity.  Explain that the
path must be from one of the root entities.

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

Some fixes to the state handling regarding
backrefs, typically when autoflush=False, where
the back-referenced collection wouldn't
properly handle add/removes with no net
change.  Thanks to Richard Murri for the
test case + patch.
(also in 0.6.7).

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

Added checks inside the UOW to detect the unusual
condition of being asked to UPDATE or DELETE
on a primary key value that contains NULL
in it.

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

Some refinements to attribute history.  More
changes are pending possibly in 0.8, but
for now history has been modified such that
scalar history doesn't have a "side effect"
of populating None for a non-present value.
This allows a slightly better ability to
distinguish between a None set and no actual
change, affects as well.

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

a "having" clause would be copied from the
inside to the outside query if from_self()
were used; in particular this would break
an 0.7 style count() query.
(also in 0.6.7)

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

the Query.execution_options() method now passes
those options to the Connection rather than
the SELECT statement, so that all available
options including isolation level and
compiled cache may be used.

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

The "compiled_cache" execution option now raises
an error when passed to a SELECT statement
rather than a Connection.  Previously it was
being ignored entirely.   We may look into
having this option work on a per-statement
level at some point.

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

Restored the "catchall" constructor on the base
TypeEngine class, with a deprecation warning.
This so that code which does something like
Integer(11) still succeeds.

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

Fixed regression whereby MetaData() coming
back from unpickling did not keep track of
new things it keeps track of now, i.e.
collection of Sequence objects, list
of schema names.

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

The limit/offset keywords to select() as well
as the value passed to select.limit()/offset()
will be coerced to integer.
(also in 0.6.7)

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

fixed bug where "from" clause gathering from an
over() clause would be an itertools.chain() and
not a list, causing "can only concatenate list"
TypeError when combined with other clauses.

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

Fixed incorrect usage of "," in over() clause
being placed between the "partition" and "order by"
clauses.

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

Before/after attach events for PrimaryKeyConstraint
now function, tests added for before/after events
on all constraint types.

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

Added explicit true()/false() constructs to expression
lib - coercion rules will intercept "False"/"True"
into these constructs.  In 0.6, the constructs were
typically converted straight to string, which was
no longer accepted in 0.7.

.. change::
:tags: engine
:tickets: 2129

The C extension is now enabled by default on CPython
2.x with a fallback to pure python if it fails to
compile.

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

The 'useexisting' flag on Table has been superseded
by a new pair of flags 'keep_existing' and
'extend_existing'.   'extend_existing' is equivalent
to 'useexisting' - the existing Table is returned,
and additional constructor elements are added.
With 'keep_existing', the existing Table is returned,
but additional constructor elements are not added -
these elements are only applied when the Table
is newly created.

.. change::
:tags: types
:tickets: 2081

REAL has been added to the core types.  Supported
by PostgreSQL, SQL Server, MySQL, SQLite.  Note
that the SQL Server and MySQL versions, which
add extra arguments, are also still available
from those dialects.

.. change::
:tags: types
:tickets: 2106

Added event.listens_for() decorator, given
target + event name, applies the decorated
function as a listener.

.. change::
:tags: pool
:tickets: 2103

AssertionPool now stores the traceback indicating
where the currently checked out connection was
acquired; this traceback is reported within
the assertion raised upon a second concurrent
checkout; courtesy Gunnlaugur Briem

.. change::
:tags: pool
:tickets:

The "pool.manage" feature doesn't use pickle
anymore to hash the arguments for each pool.

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

Fixed bug where reflection of foreign key
created as "REFERENCES <tablename>" without
col name would fail.
(also in 0.6.7)

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

Psycopg2 for Python 3 is now supported.

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

Fixed support for precision numerics when using
pg8000.

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

Using column names that would require quotes
for the column itself or for a name-generated
bind parameter, such as names with special
characters, underscores, non-ascii characters,
now properly translate bind parameter keys when
talking to cx_oracle.   (Also
in 0.6.7)

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

Oracle dialect adds use_binds_for_limits=False
create_engine() flag, will render the LIMIT/OFFSET
values inline instead of as binds, reported to
modify the execution plan used by Oracle. (Also in 0.6.7)

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

Documented SQLite DATE/TIME/DATETIME types. (also in 0.6.7)

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

Fixed mutable extension docs to show the
correct type-association methods.

.. changelog::
:version: 0.7.0b3
:released: Sun Mar 20 2011

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

Lots of fixes to unit tests when run under PyPy
(courtesy Alex Gaynor).

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

Changed the underlying approach to query.count().
query.count() is now in all cases exactly:

query.
from_self(func.count(literal_column('1'))).
scalar()

That is, "select count(1) from (<full query>)".
This produces a subquery in all cases, but
vastly simplifies all the guessing count()
tried to do previously, which would still
fail in many scenarios particularly when
joined table inheritance and other joins
were involved.  If the subquery produced
for an otherwise very simple count is really
an issue, use query(func.count()) as an
optimization.

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

some changes to the identity map regarding
rare weakref callbacks during iterations.
The mutex has been removed as it apparently
can cause a reentrant (i.e. in one thread) deadlock,
perhaps when gc collects objects at the point of
iteration in order to gain more memory.  It is hoped
that "dictionary changed during iteration" will
be exceedingly rare as iteration methods internally
acquire the full list of objects in a single values()
call. Note 0.6.7 has a more conservative fix here
which still keeps the mutex in place.

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

A tweak to the unit of work causes it to order
the flush along relationship() dependencies even if
the given objects don't have any inter-attribute
references in memory, which was the behavior in
0.5 and earlier, so a flush of Parent/Child with
only foreign key/primary key set will succeed.
This while still maintaining 0.6 and above's not
generating a ton of useless internal dependency
structures within the flush that don't correspond
to state actually within the current flush.

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

Improvements to the error messages emitted when
querying against column-only entities in conjunction
with (typically incorrectly) using loader options,
where the parent entity is not fully present.

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

Fixed bug in query.options() whereby a path
applied to a lazyload using string keys could
overlap a same named attribute on the wrong
entity.  Note 0.6.7 has a more conservative fix
to this.

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

Arguments in __mapper_args__ that aren't "hashable"
aren't mistaken for always-hashable, possibly-column
arguments.  (also in 0.6.7)

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

Added a fully descriptive error message for the
case where Column is subclassed and _make_proxy()
fails to make a copy due to TypeError on the
constructor.   The method _constructor should
be implemented in this case.

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

Added new event "column_reflect" for Table objects.
Receives the info dictionary about a Column before
the object is generated within reflection, and allows
modification to the dictionary for control over
most aspects of the resulting Column including
key, name, type, info dictionary.

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

To help with the "column_reflect" event being used
with specific Table objects instead of all instances
of Table, listeners can be added to a Table object
inline with its construction using a new argument
"listeners", a list of tuples of the form
(<eventname>, <fn>), which are applied to the Table
before the reflection process begins.

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

Added new generic function "next_value()", accepts
a Sequence object as its argument and renders the
appropriate "next value" generation string on the
target platform, if supported.  Also provides
".next_value()" method on Sequence itself.

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

func.next_value() or other SQL expression can
be embedded directly into an insert() construct,
and if implicit or explicit "returning" is used
in conjunction with a primary key column,
the newly generated value will be present in
result.inserted_primary_key.

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

Added accessors to ResultProxy "returns_rows",
"is_insert" (also in 0.6.7)

.. change::
:tags: engine
:tickets: 2097

Fixed AssertionPool regression bug.

.. change::
:tags: engine
:tickets: 2060

Changed exception raised to ArgumentError when an
invalid dialect is specified.

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

Added RESERVED_WORDS for postgresql dialect.
(also in 0.6.7)

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

Fixed the BIT type to allow a "length" parameter, "varying"
parameter.  Reflection also fixed.
(also in 0.6.7)

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

Rewrote the query used to get the definition of a view,
typically when using the Inspector interface, to
use sys.sql_modules instead of the information schema,
thereby allowing views definitions longer than 4000
characters to be fully returned.
(also in 0.6.7)

.. change::
:tags: firebird
:tickets: 2083

The "implicit_returning" flag on create_engine() is
honored if set to False.  (also in 0.6.7)

.. change::
:tags: informix
:tickets: 2092

Added RESERVED_WORDS informix dialect.
(also in 0.6.7)

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

The horizontal_shard ShardedSession class accepts the common
Session argument "query_cls" as a constructor argument,
to enable further subclassing of ShardedQuery. (also in 0.6.7)

.. change::
:tags: examples
:tickets:

Updated the association, association proxy examples
to use declarative, added a new example
dict_of_sets_with_default.py, a "pushing the envelope"
example of association proxy.

.. change::
:tags: examples
:tickets: 2090

The Beaker caching example allows a "query_cls" argument
to the query_callable() function.
(also in 0.6.7)

.. changelog::
:version: 0.7.0b2
:released: Sat Feb 19 2011

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

Fixed bug whereby Session.merge() would call the
load() event with one too few arguments.

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

Added logic which prevents the generation of
events from a MapperExtension or SessionExtension
from generating do-nothing events for all the methods
not overridden.

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

Fixed regression whereby composite() with
Column objects placed inline would fail
to initialize.  The Column objects can now
be inline with the composite() or external
and pulled in via name or object ref.

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

Fix error message referencing old classproperty
name to reference declared_attr
(also in 0.6.7)

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

the dictionary at the end of the __table_args__
tuple is now optional.

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

Renamed the EngineEvents event class to
ConnectionEvents.  As these classes are never
accessed directly by end-user code, this strictly
is a documentation change for end users.  Also
simplified how events get linked to engines
and connections internally.

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

The Sequence() construct, when passed a MetaData()
object via its 'metadata' argument, will be
included in CREATE/DROP statements within
metadata.create_all() and metadata.drop_all(),
including "checkfirst" logic.

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

The Column.references() method now returns True
if it has a foreign key referencing the
given column exactly, not just its parent
table.

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

Fixed regression from 0.6 where SMALLINT and
BIGINT types would both generate SERIAL
on an integer PK column, instead of
SMALLINT and BIGSERIAL

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

Association proxy now has correct behavior for
any(), has(), and contains() when proxying
a many-to-one scalar attribute to a one-to-many
collection (i.e. the reverse of the 'typical'
association proxy use case)

.. change::
:tags: examples
:tickets:

Beaker example now takes into account 'limit'
and 'offset', bind params within embedded
FROM clauses (like when you use union() or
from_self()) when generating a cache key.

.. changelog::
:version: 0.7.0b1
:released: Sat Feb 12 2011

.. change::
:tags:
:tickets:

Detailed descriptions of each change below are
described at:
http://docs.sqlalchemy.org/en/latest/changelog/migration_07.html

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

New event system, supersedes all extensions, listeners,
etc.

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

Logging enhancements

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

Setup no longer installs a Nose plugin

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

The "sqlalchemy.exceptions" alias in sys.modules
has been removed.   Base SQLA exceptions are
available via "from sqlalchemy import exc".
The "exceptions" alias for "exc" remains in
"sqlalchemy" for now, it's just not patched into
sys.modules.

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

More succinct form of query.join(target, onclause)

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

Hybrid Attributes, implements/supersedes synonym()

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

Rewrite of composites

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

Mutation Event Extension, supersedes "mutable=True"

.. seealso::

:ref:`07_migration_mutation_extension`

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

PickleType and ARRAY mutability turned off by default

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

Simplified polymorphic_on assignment

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

Flushing of Orphans that have no parent is allowed

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

Adjusted flush accounting step to occur before
the commit in the case of autocommit=True.  This allows
autocommit=True to work appropriately with
expire_on_commit=True, and also allows post-flush session
hooks to operate in the same transactional context
as when autocommit=False.

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

Warnings generated when collection members, scalar referents
not part of the flush

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

Non-`Table`-derived constructs can be mapped

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

Tuple label names in Query Improved

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

Mapped column attributes reference the most specific
column first

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

Mapping to joins with two or more same-named columns
requires explicit declaration

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

Mapper requires that polymorphic_on column be present
in the mapped selectable

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

compile_mappers() renamed configure_mappers(), simplified
configuration internals

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

the aliased() function, if passed a SQL FromClause element
(i.e. not a mapped class), will return element.alias()
instead of raising an error on AliasedClass.

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

Session.merge() will check the version id of the incoming
state against that of the database, assuming the mapping
uses version ids and incoming state has a version_id
assigned, and raise StaleDataError if they don't
match.

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

Session.connection(), Session.execute() accept 'bind',
to allow execute/connection operations to participate
in the open transaction of an engine explicitly.

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

Query.join(), Query.outerjoin(), eagerload(),
eagerload_all(), others no longer allow lists
of attributes as arguments (i.e. option([x, y, z])
form, deprecated since 0.5)

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

ScopedSession.mapper is removed (deprecated since 0.5).

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

Horizontal shard query places 'shard_id' in
context.attributes where it's accessible by the
"load()" event.

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

A single contains_eager() call across
multiple entities will indicate all collections
along that path should load, instead of requiring
distinct contains_eager() calls for each endpoint
(which was never correctly documented).

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

The "name" field used in orm.aliased() now renders
in the resulting SQL statement.

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

Session weak_instance_dict=False is deprecated.

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

An exception is raised in the unusual case that an
append or similar event on a collection occurs after
the parent object has been dereferenced, which
prevents the parent from being marked as "dirty"
in the session.  Was a warning in 0.6.6.

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

Query.distinct() now accepts column expressions
as \*args, interpreted by the PostgreSQL dialect
as DISTINCT ON (<expr>).

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

Additional tuning to "many-to-one" relationship
loads during a flush().   A change in version 0.6.6
([ticket:2002]) required that more "unnecessary" m2o
loads during a flush could occur.   Extra loading modes have
been added so that the SQL emitted in this
specific use case is trimmed back, while still
retrieving the information the flush needs in order
to not miss anything.

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

the value of "passive" as passed to
attributes.get_history() should be one of the
constants defined in the attributes package.  Sending
True or False is deprecated.

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

Added a `name` argument to `Query.subquery()`, to allow
a fixed name to be assigned to the alias object. (also in 0.6.7)

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

A warning is emitted when a joined-table inheriting mapper
has no primary keys on the locally mapped table
(but has pks on the superclass table).
(also in 0.6.7)

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

Fixed bug where "middle" class in a polymorphic hierarchy
would have no 'polymorphic_on' column if it didn't also
specify a 'polymorphic_identity', leading to strange
errors upon refresh, wrong class loaded when querying
from that target. Also emits the correct WHERE criterion
when using single table inheritance.
(also in 0.6.7)

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

Fixed bug where a column with a SQL or server side default
that was excluded from a mapping with include_properties
or exclude_properties would result in UnmappedColumnError. (also in 0.6.7)

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

A warning is emitted in the unusual case that an
append or similar event on a collection occurs after
the parent object has been dereferenced, which
prevents the parent from being marked as "dirty"
in the session.  This will be an exception in 0.7. (also in 0.6.7)

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

Added an explicit check for the case that the name
'metadata' is used for a column attribute on a
declarative class. (also in 0.6.7)

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

Added over() function, method to FunctionElement
classes, produces the _Over() construct which
in turn generates "window functions", i.e.
"<window function> OVER (PARTITION BY <partition by>,
ORDER BY <order by>)".

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

LIMIT/OFFSET clauses now use bind parameters

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

select.distinct() now accepts column expressions
as \*args, interpreted by the PostgreSQL dialect
as DISTINCT ON (<expr>).  Note this was already
available via passing a list to the `distinct`
keyword argument to select().

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

select.prefix_with() accepts multiple expressions
(i.e. \*expr), 'prefix' keyword argument to select()
accepts a list or tuple.

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

Passing a string to the `distinct` keyword argument
of `select()` for the purpose of emitting special
MySQL keywords (DISTINCTROW etc.) is deprecated -
use `prefix_with()` for this.

.. change::
:tags: sql
:tickets: 2006, 2005

TypeDecorator works with primary key columns

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

DDL() constructs now escape percent signs

.. change::
:tags: sql
:tickets: 1917, 1893

Table.c / MetaData.tables refined a bit, don't allow direct
mutation

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

Callables passed to `bindparam()` don't get evaluated

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

types.type_map is now private, types._type_map

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

Non-public Pool methods underscored

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

Added NULLS FIRST and NULLS LAST support. It's implemented
as an extension to the asc() and desc() operators, called
nullsfirst() and nullslast().

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

The Index() construct can be created inline with a Table
definition, using strings as column names, as an alternative
to the creation of the index outside of the Table.

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

execution_options() on Connection accepts
"isolation_level" argument, sets transaction isolation
level for that connection only until returned to the
connection pool, for those backends which support it
(SQLite, PostgreSQL)

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

A TypeDecorator of Integer can be used with a primary key
column, and the "autoincrement" feature of various dialects
as well as the "sqlite_autoincrement" flag will honor
the underlying database type as being Integer-based.

.. change::
:tags: sql
:tickets: 2020, 2021

Established consistency when server_default is present
on an Integer PK column.  SQLA doesn't pre-fetch these,
nor do they come back in cursor.lastrowid (DBAPI).
Ensured all backends consistently return None
in result.inserted_primary_key for these. Regarding
reflection for this case, reflection of an int PK col
with a server_default sets the "autoincrement" flag to False,
except in the case of a PG SERIAL col where we detected a
sequence default.

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

Result-row processors are applied to pre-executed SQL
defaults, as well as cursor.lastrowid, when determining
the contents of result.inserted_primary_key.

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

Bind parameters present in the "columns clause" of a select
are now auto-labeled like other "anonymous" clauses,
which among other things allows their "type" to be meaningful
when the row is fetched, as in result row processors.

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

TypeDecorator is present in the "sqlalchemy" import space.

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

Non-DBAPI errors which occur in the scope of an `execute()`
call are now wrapped in sqlalchemy.exc.StatementError,
and the text of the SQL statement and repr() of params
is included.  This makes it easier to identify statement
executions which fail before the DBAPI becomes
involved.

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

The concept of associating a ".bind" directly with a
ClauseElement has been explicitly moved to Executable,
i.e. the mixin that describes ClauseElements which represent
engine-executable constructs.  This change is an improvement
to internal organization and is unlikely to affect any
real-world usage.

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

Column.copy(), as used in table.tometadata(), copies the
'doc' attribute.  (also in 0.6.7)

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

Added some defs to the resultproxy.c extension so that
the extension compiles and runs on Python 2.4. (also in 0.6.7)

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

The compiler extension now supports overriding the default
compilation of expression._BindParamClause including that
the auto-generated binds within the VALUES/SET clause
of an insert()/update() statement will also use the new
compilation rules. (also in 0.6.7)

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

SQLite dialect now uses `NullPool` for file-based databases

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

The path given as the location of a sqlite database is now
normalized via os.path.abspath(), so that directory changes
within the process don't affect the ultimate location
of a relative file path.

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

When explicit sequence execution derives the name
of the auto-generated sequence of a SERIAL column,
which currently only occurs if implicit_returning=False,
now accommodates if the table + column name is greater
than 63 characters using the same logic PostgreSQL uses. (also in 0.6.7)

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

Added an additional libpq message to the list of "disconnect"
exceptions, "could not receive data from server" (also in 0.6.7)

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

the String/Unicode types, and their counterparts VARCHAR/
NVARCHAR, emit "max" as the length when no length is
specified, so that the default length, normally '1'
as per SQL server documentation, is instead
'unbounded'.  This also occurs for the VARBINARY type..

This behavior makes these types more closely compatible
with PostgreSQL's VARCHAR type which is similarly unbounded
when no length is specified.

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

New DBAPI support for pymysql, a pure Python port
of MySQL-python.

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

oursql dialect accepts the same "ssl" arguments in
create_engine() as that of MySQLdb.
(also in 0.6.7)

.. change::
:tags: firebird
:tickets: 1885

Some adjustments so that Interbase is supported as well.
FB/Interbase version idents are parsed into a structure
such as (8, 1, 1, 'interbase') or (2, 1, 588, 'firebird')
so they can be distinguished.



=============
0.8 Changelog
=============

.. changelog_imports::

.. include:: changelog_07.rst
:start-line: 5

.. changelog::

0.6.9

:released: Sat May 05 2012

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

Adjusted the "importlater" mechanism, which is
used internally to resolve import cycles,
such that the usage of __import__ is completed
when the import of sqlalchemy or sqlalchemy.orm
is done, thereby avoiding any usage of __import__
after the application starts new threads,
fixes.

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

Fixed bug whereby the source clause
used by query.join() would be inconsistent
if against a column expression that combined
multiple entities together.

.. change::
:tags: orm, bug
:tickets: 2310

fixed inappropriate evaluation of user-mapped
object in a boolean context within query.get().

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

Fixed bug apparent only in Python 3 whereby
sorting of persistent + pending objects during
flush would produce an illegal comparison,
if the persistent object primary key
is not a single integer.

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

Fixed bug where query.join() + aliased=True
from a joined-inh structure to itself on
relationship() with join condition on the child
table would convert the lead entity into the
joined one inappropriately.

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

Fixed bug whereby mapper.order_by attribute would
be ignored in the "inner" query within a
subquery eager load. .

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

Fixed bug whereby if a mapped class
redefined __hash__() or __eq__() to something
non-standard, which is a supported use case
as SQLA should never consult these,
the methods would be consulted if the class
was part of a "composite" (i.e. non-single-entity)
result set.

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

Fixed subtle bug that caused SQL to blow
up if: column_property() against subquery +
joinedload + LIMIT + order by the column
property() occurred. .

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

The join condition produced by with_parent
as well as when using a "dynamic" relationship
against a parent will generate unique
bindparams, rather than incorrectly repeating
the same bindparam. .

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

Repaired the "no statement condition"
assertion in Query which would attempt
to raise if a generative method were called
after from_statement() were called..

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

Cls.column.collate("some collation") now
works.

.. change::
:tags: orm, bug
:tickets: 2297

Fixed the error formatting raised when
a tuple is inadvertently passed to session.query().

.. change::
:tags: engine
:tickets: 2317

Backported the fix for introduced
in 0.7.4, which ensures that the connection
is in a valid state before attempting to call
rollback()/prepare()/release() on savepoint
and two-phase transactions.

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

Fixed two subtle bugs involving column
correspondence in a selectable,
one with the same labeled subquery repeated, the other
when the label has been "grouped" and
loses itself.  Affects.

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

Fixed bug whereby "warn on unicode" flag
would get set for the String type
when used with certain dialects.  This
bug is not in 0.7.

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

Fixed bug whereby with_only_columns() method of
Select would fail if a selectable were passed..   However, the FROM behavior is
still incorrect here, so you need 0.7 in
any case for this use case to be usable.

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

Added an informative error message when
ForeignKeyConstraint refers to a column name in
the parent that is not found.

.. change::
:tags: postgresql
:tickets: 2291, 2141

Fixed bug related to whereby the
same modified index behavior in PG 9 affected
primary key reflection on a renamed column..

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

Fixed OurSQL dialect to use ansi-neutral
quote symbol "'" for XA commands instead
of '"'. .

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

a CREATE TABLE will put the COLLATE option
after CHARSET, which appears to be part of
MySQL's arbitrary rules regarding if it will actually
work or not.

.. change::
:tags: mssql, bug
:tickets: 2269

Decode incoming values when retrieving
list of index names and the names of columns
within those indexes.

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

Added ORA-00028 to disconnect codes, use
cx_oracle _Error.code to get at the code,.

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

repaired the oracle.RAW type which did not
generate the correct DDL.

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

added CURRENT to reserved word list.

.. change::
:tags: examples
:tickets: 2266

Adjusted dictlike-polymorphic.py example
to apply the CAST such that it works on
PG, other databases.

.. changelog::

0.6.8

:released: Sun Jun 05 2011

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

Calling query.get() against a column-based entity is
invalid, this condition now raises a deprecation warning.

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

a non_primary mapper will inherit the _identity_class
of the primary mapper.  This so that a non_primary
established against a class that's normally in an
inheritance mapping will produce results that are
identity-map compatible with that of the primary
mapper

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

Backported 0.7's identity map implementation, which
does not use a mutex around removal.  This as some users
were still getting deadlocks despite the adjustments
in 0.6.7; the 0.7 approach that doesn't use a mutex
does not appear to produce "dictionary changed size"
issues, the original rationale for the mutex.

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

Fixed the error message emitted for "can't
execute syncrule for destination column 'q';
mapper 'X' does not map this column" to
reference the correct mapper. .

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

Fixed bug where determination of "self referential"
relationship would fail with no workaround
for joined-inh subclass related to itself,
or joined-inh subclass related to a subclass
of that with no cols in the sub-sub class
in the join condition.

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

mapper() will ignore non-configured foreign keys
to unrelated tables when determining inherit
condition between parent and child class.
This is equivalent to behavior already
applied to declarative.  Note that 0.7 has a
more comprehensive solution to this, altering
how join() itself determines an FK error.

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

Fixed bug whereby mapper mapped to an anonymous
alias would fail if logging were used, due to
unescaped % sign in the alias name.

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

Modify the text of the message which occurs
when the "identity" key isn't detected on
flush, to include the common cause that
the Column isn't set up to detect
auto-increment correctly;.

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

Fixed bug where transaction-level "deleted"
collection wouldn't be cleared of expunged
states, raising an error if they later
became transient.

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

Fixed bug whereby if FetchedValue was passed
to column server_onupdate, it would not
have its parent "column" assigned, added
test coverage for all column default assignment
patterns.

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

Fixed bug whereby nesting a label of a select()
with another label in it would produce incorrect
exported columns.   Among other things this would
break an ORM column_property() mapping against
another column_property(). .

.. change::
:tags: engine
:tickets: 2178

Adjusted the __contains__() method of
a RowProxy result row such that no exception
throw is generated internally;
NoSuchColumnError() also will generate its
message regardless of whether or not the column
construct can be coerced to a string..

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

Fixed bug affecting PG 9 whereby index reflection
would fail if against a column whose name
had changed. .

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

Some unit test fixes regarding numeric arrays,
MATCH operator.   A potential floating-point
inaccuracy issue was fixed, and certain tests
of the MATCH operator only execute within an
EN-oriented locale for now. .

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

Fixed bug in MSSQL dialect whereby the aliasing
applied to a schema-qualified table would leak
into enclosing select statements.

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

Fixed bug whereby DATETIME2 type would fail on
the "adapt" step when used in result sets or
bound parameters.  This issue is not in 0.7.

.. changelog::

0.6.7

:released: Wed Apr 13 2011

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

Tightened the iterate vs. remove mutex around the
identity map iteration, attempting to reduce the
chance of an (extremely rare) reentrant gc operation
causing a deadlock.  Might remove the mutex in
0.7.

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

Added a `name` argument to `Query.subquery()`, to allow
a fixed name to be assigned to the alias object.

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

A warning is emitted when a joined-table inheriting mapper
has no primary keys on the locally mapped table
(but has pks on the superclass table).

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

Fixed bug where "middle" class in a polymorphic hierarchy
would have no 'polymorphic_on' column if it didn't also
specify a 'polymorphic_identity', leading to strange
errors upon refresh, wrong class loaded when querying
from that target. Also emits the correct WHERE criterion
when using single table inheritance.

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

Fixed bug where a column with a SQL or server side default
that was excluded from a mapping with include_properties
or exclude_properties would result in UnmappedColumnError.

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

A warning is emitted in the unusual case that an
append or similar event on a collection occurs after
the parent object has been dereferenced, which
prevents the parent from being marked as "dirty"
in the session.  This will be an exception in 0.7.

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

Fixed bug in query.options() whereby a path
applied to a lazyload using string keys could
overlap a same named attribute on the wrong
entity.  Note 0.7 has an updated version of this
fix.

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

Reworded the exception raised when a flush
is attempted of a subclass that is not polymorphic
against the supertype.

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

Some fixes to the state handling regarding
backrefs, typically when autoflush=False, where
the back-referenced collection wouldn't
properly handle add/removes with no net
change.  Thanks to Richard Murri for the
test case + patch.

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

a "having" clause would be copied from the
inside to the outside query if from_self()
were used..

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

Column.copy(), as used in table.tometadata(), copies the
'doc' attribute.

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

Added some defs to the resultproxy.c extension so that
the extension compiles and runs on Python 2.4.

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

The compiler extension now supports overriding the default
compilation of expression._BindParamClause including that
the auto-generated binds within the VALUES/SET clause
of an insert()/update() statement will also use the new
compilation rules.

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

Added accessors to ResultProxy "returns_rows", "is_insert"

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

The limit/offset keywords to select() as well
as the value passed to select.limit()/offset()
will be coerced to integer.

.. change::
:tags: engine
:tickets: 2102

Fixed bug in QueuePool, SingletonThreadPool whereby
connections that were discarded via overflow or periodic
cleanup() were not explicitly closed, leaving garbage
collection to the task instead.   This generally only
affects non-reference-counting backends like Jython
and PyPy.  Thanks to Jaimy Azle for spotting
this.

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

Fixed bug where reflection of foreign key
created as "REFERENCES <tablename>" without
col name would fail.

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

When explicit sequence execution derives the name
of the auto-generated sequence of a SERIAL column,
which currently only occurs if implicit_returning=False,
now accommodates if the table + column name is greater
than 63 characters using the same logic PostgreSQL uses.

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

Added an additional libpq message to the list of "disconnect"
exceptions, "could not receive data from server"

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

Added RESERVED_WORDS for postgresql dialect.

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

Fixed the BIT type to allow a "length" parameter, "varying"
parameter.  Reflection also fixed.

.. change::
:tags: informix
:tickets: 2092

Added RESERVED_WORDS informix dialect.

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

Rewrote the query used to get the definition of a view,
typically when using the Inspector interface, to
use sys.sql_modules instead of the information schema,
thereby allowing views definitions longer than 4000
characters to be fully returned.

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

oursql dialect accepts the same "ssl" arguments in
create_engine() as that of MySQLdb.

.. change::
:tags: firebird
:tickets: 2083

The "implicit_returning" flag on create_engine() is
honored if set to False.

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

Using column names that would require quotes
for the column itself or for a name-generated
bind parameter, such as names with special
characters, underscores, non-ascii characters,
now properly translate bind parameter keys when
talking to cx_oracle.

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

Oracle dialect adds use_binds_for_limits=False
create_engine() flag, will render the LIMIT/OFFSET
values inline instead of as binds, reported to
modify the execution plan used by Oracle.

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

The horizontal_shard ShardedSession class accepts the common
Session argument "query_cls" as a constructor argument,
to enable further subclassing of ShardedQuery.

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

Added an explicit check for the case that the name
'metadata' is used for a column attribute on a
declarative class.

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

Fix error message referencing old classproperty
name to reference declared_attr

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

Arguments in __mapper_args__ that aren't "hashable"
aren't mistaken for always-hashable, possibly-column
arguments.

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

Documented SQLite DATE/TIME/DATETIME types.

.. change::
:tags: examples
:tickets: 2090

The Beaker caching example allows a "query_cls" argument
to the query_callable() function.

.. changelog::

0.6.6

:released: Sat Jan 08 2011

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

Fixed bug whereby a non-"mutable" attribute modified event
which occurred on an object that was clean except for
preceding mutable attribute changes would fail to strongly
reference itself in the identity map. This would cause the
object to be garbage collected, losing track of any changes
that weren't previously saved in the "mutable changes"
dictionary.

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

Fixed bug whereby "passive_deletes='all'" wasn't passing
the correct symbols to lazy loaders during flush, thereby
causing an unwarranted load.

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

Fixed bug which prevented composite mapped
attributes from being used on a mapped select statement.. Note the workings of composite are slated to
change significantly in 0.7.

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

active_history flag also added to composite().
The flag has no effect in 0.6, but is instead
a placeholder flag for forwards compatibility,
as it applies in 0.7 for composites.

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

Fixed uow bug whereby expired objects passed to
Session.delete() would not have unloaded references
or collections taken into account when deleting
objects, despite passive_deletes remaining at
its default of False.

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

A warning is emitted when version_id_col is specified
on an inheriting mapper when the inherited mapper
already has one, if those column expressions are not
the same.

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

"innerjoin" flag doesn't take effect along the chain
of joinedload() joins if a previous join in that chain
is an outer join, thus allowing primary rows without
a referenced child row to be correctly returned
in results.

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

Fixed bug regarding "subqueryload" strategy whereby
strategy would fail if the entity was an aliased()
construct.

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

Fixed bug regarding "subqueryload" strategy whereby
the join would fail if using a multi-level load
of the form from A->joined-subclass->C

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

Fixed indexing of Query objects by -1. It was erroneously
transformed to the empty slice -1:0 that resulted in
IndexError.

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

The mapper argument "primary_key" can be passed as a
single column as well as a list or tuple.
The documentation examples that illustrated it as a
scalar value have been changed to lists.

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

Added active_history flag to relationship()
and column_property(), forces attribute events to
always load the "old" value, so that it's available to
attributes.get_history().

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

Query.get() will raise if the number of params
in a composite key is too large, as well as too
small.

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

Backport of "optimized get" fix from 0.7,
improves the generation of joined-inheritance
"load expired row" behavior.

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

A little more verbiage to the "primaryjoin" error,
in an unusual condition that the join condition
"works" for viewonly but doesn't work for non-viewonly,
and foreign_keys wasn't used - adds "foreign_keys" to
the suggestion.  Also add "foreign_keys" to the
suggestion for the generic "direction" error.

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

Fixed operator precedence rules for multiple
chains of a single non-associative operator.
I.e. "x - (y - z)" will compile as "x - (y - z)"
and not "x - y - z".  Also works with labels,
i.e. "x - (y - z).label('foo')"

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

The 'info' attribute of Column is copied during
Column.copy(), i.e. as occurs when using columns
in declarative mixins.

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

Added a bind processor for booleans which coerces
to int, for DBAPIs such as pymssql that naively call
str() on values.

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

CheckConstraint will copy its 'initially', 'deferrable',
and '_create_rule' attributes within a copy()/tometadata()

.. change::
:tags: engine
:tickets:

The "unicode warning" against non-unicode bind data
is now raised only when the
Unicode type is used explicitly; not when
convert_unicode=True is used on the engine
or String type.

.. change::
:tags: engine
:tickets: 1978

Fixed memory leak in C version of Decimal result
processor.

.. change::
:tags: engine
:tickets: 1871

Implemented sequence check capability for the C
version of RowProxy, as well as 2.7 style
"collections.Sequence" registration for RowProxy.

.. change::
:tags: engine
:tickets: 1998

Threadlocal engine methods rollback(), commit(),
prepare() won't raise if no transaction is in progress;
this was a regression introduced in 0.6.

.. change::
:tags: engine
:tickets: 2004

Threadlocal engine returns itself upon begin(),
begin_nested(); engine then implements contextmanager
methods to allow the "with" statement.

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

Single element tuple expressions inside an IN clause
parenthesize correctly, also from

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

Ensured every numeric, float, int code, scalar + array,
are recognized by psycopg2 and pg8000's "numeric"
base type.

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

Added as_uuid=True flag to the UUID type, will receive
and return values as Python UUID() objects rather than
strings.  Currently, the UUID type is only known to
work with psycopg2.

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

Fixed bug whereby KeyError would occur with non-ENUM
supported PG versions after a pool dispose+recreate
would occur.

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

Fixed error handling for Jython + zxjdbc, such that
has_table() property works again.  Regression from
0.6.3 (we don't have a Jython buildbot, sorry)

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

The REFERENCES clause in a CREATE TABLE that includes
a remote schema to another table with the same schema
name now renders the remote name without
the schema clause, as required by SQLite.

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

On the same theme, the REFERENCES clause in a CREATE TABLE
that includes a remote schema to a *different* schema
than that of the parent table doesn't render at all,
as cross-schema references do not appear to be supported.

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

The rewrite of index reflection in was
unfortunately not tested correctly, and returned incorrect
results.   This regression is now fixed.

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

The cx_oracle "decimal detection" logic, which takes place
for result set columns with ambiguous numeric characteristics,
now uses the decimal point character determined by the locale/
NLS_LANG setting, using an on-first-connect detection of
this character.  cx_oracle 5.0.3 or greater is also required
when using a non-period-decimal-point NLS_LANG setting..

.. change::
:tags: firebird
:tickets: 2012

Firebird numeric type now checks for Decimal explicitly,
lets float() pass right through, thereby allowing
special values such as float('inf').

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

An error is raised if __table_args__ is not in tuple
or dict format, and is not None.

.. change::
:tags: sqlsoup
:tickets: 1975

Added "map_to()" method to SqlSoup, which is a "master"
method which accepts explicit arguments for each aspect of
the selectable and mapping, including a base class per
mapping.

.. change::
:tags: sqlsoup
:tickets:

Mapped selectables used with the map(), with_labels(),
join() methods no longer put the given argument into the
internal "cache" dictionary.  Particularly since the
join() and select() objects are created in the method
itself this was pretty much a pure memory leaking behavior.

.. change::
:tags: examples
:tickets:

The versioning example now supports detection of changes
in an associated relationship().

.. changelog::

0.6.5

:released: Sun Oct 24 2010

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

Added a new "lazyload" option "immediateload".
Issues the usual "lazy" load operation automatically
as the object is populated.   The use case
here is when loading objects to be placed in
an offline cache, or otherwise used after
the session isn't available, and straight 'select'
loading, not 'joined' or 'subquery', is desired.

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

New Query methods: query.label(name), query.as_scalar(),
return the query's statement as a scalar subquery
with /without label;
query.with_entities(\*ent), replaces the SELECT list of
the query with new entities.
Roughly equivalent to a generative form of query.values()
which accepts mapped entities as well as column
expressions.

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

Fixed recursion bug which could occur when moving
an object from one reference to another, with
backrefs involved, where the initiating parent
was a subclass (with its own mapper) of the
previous parent.

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

Fixed a regression in 0.6.4 which occurred if you
passed an empty list to "include_properties" on
mapper()

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

Fixed labeling bug in Query whereby the NamedTuple
would mis-apply labels if any of the column
expressions were un-labeled.

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

Patched a case where query.join() would adapt the
right side to the right side of the left's join
inappropriately

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

Query.select_from() has been beefed up to help
ensure that a subsequent call to query.join()
will use the select_from() entity, assuming it's
a mapped entity and not a plain selectable,
as the default "left" side, not the first entity
in the Query object's list of entities.

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

The exception raised by Session when it is used
subsequent to a subtransaction rollback (which is what
happens when a flush fails in autocommit=False mode) has
now been reworded (this is the "inactive due to a
rollback in a subtransaction" message). In particular,
if the rollback was due to an exception during flush(),
the message states this is the case, and reiterates the
string form of the original exception that occurred
during flush. If the session is closed due to explicit
usage of subtransactions (not very common), the message
just states this is the case.

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

The exception raised by Mapper when repeated requests to
its initialization are made after initialization already
failed no longer assumes the "hasattr" case, since
there's other scenarios in which this message gets
emitted, and the message also does not compound onto
itself multiple times - you get the same message for
each attempt at usage. The misnomer "compiles" is being
traded out for "initialize".

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

Fixed bug in query.update() where 'evaluate' or 'fetch'
expiration would fail if the column expression key was
a class attribute with a different keyname as the
actual column name.

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

Added an assertion during flush which ensures
that no NULL-holding identity keys were generated
on "newly persistent" objects.
This can occur when user defined code inadvertently
triggers flushes on not-fully-loaded objects.

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

lazy loads for relationship attributes now use
the current state, not the "committed" state,
of foreign and primary key attributes
when issuing SQL, if a flush is not in process.
Previously, only the database-committed state would
be used.  In particular, this would cause a many-to-one
get()-on-lazyload operation to fail, as autoflush
is not triggered on these loads when the attributes are
determined and the "committed" state may not be
available.

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

A new flag on relationship(), load_on_pending, allows
the lazy loader to fire off on pending objects without a
flush taking place, as well as a transient object that's
been manually "attached" to the session. Note that this
flag blocks attribute events from taking place when an
object is loaded, so backrefs aren't available until
after a flush. The flag is only intended for very
specific use cases.

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

Another new flag on relationship(), cascade_backrefs,
disables the "save-update" cascade when the event was
initiated on the "reverse" side of a bidirectional
relationship.   This is a cleaner behavior so that
many-to-ones can be set on a transient object without
it getting sucked into the child object's session,
while still allowing the forward collection to
cascade.   We *might* default this to False in 0.7.

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

Slight improvement to the behavior of
"passive_updates=False" when placed only on the
many-to-one side of a relationship; documentation has
been clarified that passive_updates=False should really
be on the one-to-many side.

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

Placing passive_deletes=True on a many-to-one emits
a warning, since you probably intended to put it on
the one-to-many side.

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

Fixed bug that would prevent "subqueryload" from
working correctly with single table inheritance
for a relationship from a subclass - the "where
type in (x, y, z)" only gets placed on the inside,
instead of repeatedly.

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

When using from_self() with single table inheritance,
the "where type in (x, y, z)" is placed on the outside
of the query only, instead of repeatedly.   May make
some more adjustments to this.

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

scoped_session emits a warning when configure() is
called if a Session is already present (checks only the
current thread)

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

reworked the internals of mapper.cascade_iterator() to
cut down method calls by about 9% in some circumstances.

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

Fixed bug in TypeDecorator whereby the dialect-specific
type was getting pulled in to generate the DDL for a
given type, which didn't always return the correct result.

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

TypeDecorator can now have a fully constructed type
specified as its "impl", in addition to a type class.

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

TypeDecorator will now place itself as the resulting
type for a binary expression where the type coercion
rules would normally return its impl type - previously,
a copy of the impl type would be returned which would
have the TypeDecorator embedded into it as the "dialect"
impl, this was probably an unintentional way of achieving
the desired effect.

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

TypeDecorator.load_dialect_impl() returns "self.impl" by
default, i.e. not the dialect implementation type of
"self.impl".   This to support compilation correctly.
Behavior can be user-overridden in exactly the same way
as before to the same effect.

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

Added type_coerce(expr, type\_) expression element.
Treats the given expression as the given type when evaluating
expressions and processing result rows, but does not
affect the generation of SQL, other than an anonymous
label.

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

Table.tometadata() now copies Index objects associated
with the Table as well.

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

Table.tometadata() issues a warning if the given Table
is already present in the target MetaData - the existing
Table object is returned.

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

An informative error message is raised if a Column
which has not yet been assigned a name, i.e. as in
declarative, is used in a context where it is
exported to the columns collection of an enclosing
select() construct, or if any construct involving
that column is compiled before its name is
assigned.

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

as_scalar(), label() can be called on a selectable
which contains a Column that is not yet named.

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

Fixed recursion overflow which could occur when operating
with two expressions both of type "NullType", but
not the singleton NULLTYPE instance.

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

classproperty (soon/now declared_attr) takes effect for
__mapper_args__, __table_args__, __tablename__ on
a base class that is not a mixin, as well as mixins.

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

classproperty 's official name/location for usage
with declarative is sqlalchemy.ext.declarative.declared_attr.
Same thing, but moving there since it is more of a
"marker" that's specific to declarative,
not just an attribute technique.

.. change::
:tags: declarative
:tickets: 1931, 1930

Fixed bug whereby columns on a mixin wouldn't propagate
correctly to a single-table, or joined-table,
inheritance scheme where the attribute name is
different than that of the column.,.

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

A mixin can now specify a column that overrides
a column of the same name associated with a superclass.
Thanks to Oystein Haaland.

.. change::
:tags: engine
:tickets:

Fixed a regression in 0.6.4 whereby the change that
allowed cursor errors to be raised consistently broke
the result.lastrowid accessor.   Test coverage has
been added for result.lastrowid.   Note that lastrowid
is only supported by Pysqlite and some MySQL drivers,
so isn't super-useful in the general case.

.. change::
:tags: engine
:tickets:

the logging message emitted by the engine when
a connection is first used is now "BEGIN (implicit)"
to emphasize that DBAPI has no explicit begin().

.. change::
:tags: engine
:tickets: 1936

added "views=True" option to metadata.reflect(),
will add the list of available views to those
being reflected.

.. change::
:tags: engine
:tickets: 1899

engine_from_config() now accepts 'debug' for
'echo', 'echo_pool', 'force' for 'convert_unicode',
boolean values for 'use_native_unicode'.

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

Added "as_tuple" flag to ARRAY type, returns results
as tuples instead of lists to allow hashing.

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

Fixed bug which prevented "domain" built from a
custom type such as "enum" from being reflected.

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

Fixed bug involving reflection of CURRENT_TIMESTAMP
default used with ON UPDATE clause, thanks to
Taavi Burns

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

The implicit_returning argument to create_engine()
is now honored regardless of detected version of
Oracle.  Previously, the flag would be forced
to False if server version info was < 10.

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

Fixed reflection bug which did not properly handle
reflection of unknown types.

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

Fixed bug where aliasing of tables with "schema" would
fail to compile properly.

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

Rewrote the reflection of indexes to use sys.
catalogs, so that column names of any configuration
(spaces, embedded commas, etc.) can be reflected.
Note that reflection of indexes requires SQL
Server 2005 or greater.

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

mssql+pymssql dialect now honors the "port" portion
of the URL instead of discarding it.

.. change::
:tags: informix
:tickets: 1906

*Major* cleanup / modernization of the Informix
dialect for 0.6, courtesy Florian Apolloner.

.. change::
:tags: tests
:tickets:

the NoseSQLAlchemyPlugin has been moved to a
new package "sqlalchemy_nose" which installs
along with "sqlalchemy".  This so that the "nosetests"
script works as always but also allows the
--with-coverage option to turn on coverage before
SQLAlchemy modules are imported, allowing coverage
to work correctly.

.. change::
:tags: misc
:tickets: 1890

CircularDependencyError now has .cycles and .edges
members, which are the set of elements involved in
one or more cycles, and the set of edges as 2-tuples.

.. changelog::

0.6.4

:released: Tue Sep 07 2010

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

The name ConcurrentModificationError has been
changed to StaleDataError, and descriptive
error messages have been revised to reflect
exactly what the issue is.   Both names will
remain available for the foreseeable future
for schemes that may be specifying
ConcurrentModificationError in an "except:"
clause.

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

Added a mutex to the identity map which mutexes
remove operations against iteration methods,
which now pre-buffer before returning an
iterable.   This because asynchronous gc
can remove items via the gc thread at any time.

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

The Session class is now present in sqlalchemy.orm.*.
We're moving away from the usage of create_session(),
which has non-standard defaults, for those situations
where a one-step Session constructor is desired. Most
users should stick with sessionmaker() for general use,
however.

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

query.with_parent() now accepts transient objects
and will use the non-persistent values of their pk/fk
attributes in order to formulate the criterion.
Docs are also clarified as to the purpose of with_parent().

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

The include_properties and exclude_properties arguments
to mapper() now accept Column objects as members in
addition to strings.  This so that same-named Column
objects, such as those within a join(), can be
disambiguated.

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

A warning is now emitted if a mapper is created against a
join or other single selectable that includes multiple
columns with the same name in its .c. collection,
and those columns aren't explicitly named as part of
the same or separate attributes (or excluded).
In 0.7 this warning will be an exception.   Note that
this warning is not emitted when the combination occurs
as a result of inheritance, so that attributes
still allow being overridden naturally..  In 0.7 this will be improved further.

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

The primary_key argument to mapper() can now specify
a series of columns that are only a subset of
the calculated "primary key" columns of the mapped
selectable, without an error being raised.  This
helps for situations where a selectable's effective
primary key is simpler than the number of columns
in the selectable that are actually marked as
"primary_key", such as a join against two
tables on their primary key columns.

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

An object that's been deleted now gets a flag
'deleted', which prohibits the object from
being re-add()ed to the session, as previously
the object would live in the identity map
silently until its attributes were accessed.
The make_transient() function now resets this
flag along with the "key" flag.

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

make_transient() can be safely called on an
already transient instance.

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

a warning is emitted in mapper() if the polymorphic_on
column is not present either in direct or derived
form in the mapped selectable or in the
with_polymorphic selectable, instead of silently
ignoring it.  Look for this to become an
exception in 0.7.

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

Another pass through the series of error messages
emitted when relationship() is configured with
ambiguous arguments.   The "foreign_keys"
setting is no longer mentioned, as it is almost
never needed and it is preferable users set up
correct ForeignKey metadata, which is now the
recommendation.  If 'foreign_keys'
is used and is incorrect, the message suggests
the attribute is probably unnecessary.  Docs
for the attribute are beefed up.  This
because all confused relationship() users on the
ML appear to be attempting to use foreign_keys
due to the message, which only confuses them
further since Table metadata is much clearer.

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

If the "secondary" table has no ForeignKey metadata
and no foreign_keys is set, even though the
user is passing screwed up information, it is assumed
that primary/secondaryjoin expressions should
consider only and all cols in "secondary" to be
foreign.  It's not possible with "secondary" for
the foreign keys to be elsewhere in any case.
A warning is now emitted instead of an error,
and the mapping succeeds.

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

Moving an o2m object from one collection to
another, or vice versa changing the referenced
object by an m2o, where the foreign key is also a
member of the primary key, will now be more
carefully checked during flush if the change in
value of the foreign key on the "many" side is the
result of a change in the primary key of the "one"
side, or if the "one" is just a different object.
In one case, a cascade-capable DB would have
cascaded the value already and we need to look at
the "new" PK value to do an UPDATE, in the other we
need to continue looking at the "old". We now look
at the "old", assuming passive_updates=True,
unless we know it was a PK switch that
triggered the change.

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

The value of version_id_col can be changed
manually, and this will result in an UPDATE
of the row.  Versioned UPDATEs and DELETEs
now use the "committed" value of the
version_id_col in the WHERE clause and
not the pending changed value. The
version generator is also bypassed if
manual changes are present on the attribute.

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

Repaired the usage of merge() when used with
concrete inheriting mappers.  Such mappers frequently
have so-called "concrete" attributes, which are
subclass attributes that "disable" propagation from
the parent - these needed to allow a merge()
operation to pass through without effect.

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

Specifying a non-column based argument
for column_mapped_collection, including string,
text() etc., will raise an error message that
specifically asks for a column element, no longer
misleads with incorrect information about
text() or literal().

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

Similarly, for relationship(), foreign_keys,
remote_side, order_by - all column-based
expressions are enforced - lists of strings
are explicitly disallowed since this is a
very common error

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

Dynamic attributes don't support collection
population - added an assertion for when
set_committed_value() is called, as well as
when joinedload() or subqueryload() options
are applied to a dynamic attribute, instead
of failure / silent failure.

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

Fixed bug whereby generating a Query derived
from one which had the same column repeated
with different label names, typically
in some UNION situations, would fail to
propagate the inner columns completely to
the outer query.

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

object_session() raises the proper
UnmappedInstanceError when presented with an
unmapped instance.

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

Applied further memoizations to calculated Mapper
properties, with significant (~90%) runtime mapper.py
call count reduction in heavily polymorphic mapping
configurations.

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

mapper _get_col_to_prop private method used
by the versioning example is deprecated;
now use mapper.get_property_by_column() which
will remain the public method for this.

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

the versioning example works correctly now
if versioning on a col that was formerly
NULL.

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

Calling execute() on an alias() construct is pending
deprecation for 0.7, as it is not itself an
"executable" construct. It currently "proxies" its
inner element and is conditionally "executable" but
this is not the kind of ambiguity we like these days.

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

The execute() and scalar() methods of ClauseElement
are now moved appropriately to the Executable
subclass. ClauseElement.execute()/ scalar() are still
present and are pending deprecation in 0.7, but note
these would always raise an error anyway if you were
not an Executable (unless you were an alias(), see
previous note).

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

Added basic math expression coercion for
Numeric->Integer,
so that resulting type is Numeric regardless
of the direction of the expression.

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

Changed the scheme used to generate truncated
"auto" index names when using the "index=True"
flag on Column.   The truncation only takes
place with the auto-generated name, not one
that is user-defined (an error would be
raised instead), and the truncation scheme
itself is now based on a fragment of an md5
hash of the identifier name, so that multiple
indexes on columns with similar names still
have unique names.

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

The generated index name also is based on
a "max index name length" attribute which is
separate from the "max identifier length" -
this to appease MySQL who has a max length
of 64 for index names, separate from their
overall max length of 255.

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

the text() construct, if placed in a column
oriented situation, will at least return NULLTYPE
for its type instead of None, allowing it to
be used a little more freely for ad-hoc column
expressions than before.   literal_column()
is still the better choice, however.

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

Added full description of parent table/column,
target table/column in error message raised when
ForeignKey can't resolve target.

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

Fixed bug whereby replacing composite foreign key
columns in a reflected table would cause an attempt
to remove the reflected constraint from the table
a second time, raising a KeyError.

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

the _Label construct, i.e. the one that is produced
whenever you say somecol.label(), now counts itself
in its "proxy_set" unioned with that of its
contained column's proxy set, instead of
directly returning that of the contained column.
This allows column correspondence
operations which depend on the identity of the
_Labels themselves to return the correct result

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

fixes ORM bug.

.. change::
:tags: engine
:tickets:

Calling fetchone() or similar on a result that
has already been exhausted, has been closed,
or is not a result-returning result now
raises ResourceClosedError, a subclass of
InvalidRequestError, in all cases, regardless
of backend.  Previously, some DBAPIs would
raise ProgrammingError (i.e. pysqlite), others
would return None leading to downstream breakages
(i.e. MySQL-python).

.. change::
:tags: engine
:tickets: 1894

Fixed bug in Connection whereby if a "disconnect"
event occurred in the "initialize" phase of the
first connection pool connect, an AttributeError
would be raised when the Connection would attempt
to invalidate the DBAPI connection.

.. change::
:tags: engine
:tickets:

Connection, ResultProxy, as well as Session use
ResourceClosedError for all "this
connection/transaction/result is closed" types of
errors.

.. change::
:tags: engine
:tickets:

Connection.invalidate() can be called more than
once and subsequent calls do nothing.

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

if classproperty is used with a regular class-bound
mapper property attribute, it will be called to get the
actual attribute value during initialization. Currently,
there's no advantage to using classproperty on a column
or relationship attribute of a declarative class that
isn't a mixin - evaluation is at the same time as if
classproperty weren't used. But here we at least allow
it to function as expected.

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

Fixed bug where "Can't add additional column" message
would display the wrong name.

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

Fixed the psycopg2 dialect to use its
set_isolation_level() method instead of relying
upon the base "SET SESSION ISOLATION" command,
as psycopg2 resets the isolation level on each new
transaction otherwise.

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

Fixed "default schema" query to work with
pymssql backend.

.. change::
:tags: firebird
:tickets:

Fixed bug whereby a column default would fail to
reflect if the "default" keyword were lower case.

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

Added ROWID type to the Oracle dialect, for those
cases where an explicit CAST might be needed.

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

Oracle reflection of indexes has been tuned so
that indexes which include some or all primary
key columns, but not the same set of columns
as that of the primary key, are reflected.
Indexes which contain the identical columns
as that of the primary key are skipped within
reflection, as the index in that case is assumed
to be the auto-generated primary key index.
Previously, any index with PK columns present
would be skipped.  Thanks to Kent Bower
for the patch.

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

Oracle now reflects the names of primary key
constraints - also thanks to Kent Bower.

.. change::
:tags: informix
:tickets: 1904

Applied patches from to get
basic Informix functionality up again.  We
rely upon end-user testing to ensure that
Informix is working to some degree.

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

The docs have been reorganized such that the "API
Reference" section is gone - all the docstrings from
there which were public API are moved into the
context of the main doc section that talks about it.
Main docs divided into "SQLAlchemy Core" and
"SQLAlchemy ORM" sections, mapper/relationship docs
have been broken out. Lots of sections rewritten
and/or reorganized.

.. change::
:tags: examples
:tickets:

The beaker_caching example has been reorganized
such that the Session, cache manager,
declarative_base are part of environment, and
custom cache code is portable and now within
"caching_query.py".  This allows the example to
be easier to "drop in" to existing projects.

.. change::
:tags: examples
:tickets: 1887

the history_meta versioning recipe sets "unique=False"
when copying columns, so that the versioning
table handles multiple rows with repeating values.

.. changelog::

0.6.3

:released: Thu Jul 15 2010

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

Removed errant many-to-many load in unitofwork
which triggered unnecessarily on expired/unloaded
collections. This load now takes place only if
passive_updates is False and the parent primary
key has changed, or if passive_deletes is False
and a delete of the parent has occurred.

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

Column-entities (i.e. query(Foo.id)) copy their
state more fully when queries are derived from
themselves + a selectable (i.e. from_self(),
union(), etc.), so that join() and such have the
correct state to work from.

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

Fixed bug where Query.join() would fail if
querying a non-ORM column then joining without
an on clause when a FROM clause is already
present, now raises a checked exception the
same way it does when the clause is not
present.

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

Improved the check for an "unmapped class",
including the case where the superclass is mapped
but the subclass is not.  Any attempts to access
cls._sa_class_manager.mapper now raise
UnmappedClassError().

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

Added "column_descriptions" accessor to Query,
returns a list of dictionaries containing
naming/typing information about the entities
the Query will return.  Can be helpful for
building GUIs on top of ORM queries.

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

The _extract_error_code() method now works
correctly with each MySQL dialect (
MySQL-python, OurSQL, MySQL-Connector-Python,
PyODBC).  Previously,
the reconnect logic would fail for OperationalError
conditions, however since MySQLdb and OurSQL
have their own reconnect feature, there was no
symptom for these drivers here unless one
watched the logs.

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

More tweaks to cx_oracle Decimal handling.
"Ambiguous" numerics with no decimal place
are coerced to int at the connection handler
level.  The advantage here is that ints
come back as ints without SQLA type
objects being involved and without needless
conversion to Decimal first.

Unfortunately, some exotic subquery cases
can even see different types between
individual result rows, so the Numeric
handler, when instructed to return Decimal,
can't take full advantage of "native decimal"
mode and must run isinstance() on every value
to check if its Decimal already. Reopen of

.. changelog::

0.6.2

:released: Tue Jul 06 2010

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

Query.join() will check for a call of the
form query.join(target, clause_expression),
i.e. missing the tuple, and raise an informative
error message that this is the wrong calling form.

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

Fixed bug regarding flushes on self-referential
bi-directional many-to-many relationships, where
two objects made to mutually reference each other
in one flush would fail to insert a row for both
sides.  Regression from 0.5.

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

the post_update feature of relationship() has been
reworked architecturally to integrate more closely
with the new 0.6 unit of work.  The motivation
for the change is so that multiple "post update"
calls, each affecting different foreign key
columns of the same row, are executed in a single
UPDATE statement, rather than one UPDATE
statement per column per row.   Multiple row
updates are also batched into executemany()s as
possible, while maintaining consistent row ordering.

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

Query.statement, Query.subquery(), etc. now transfer
the values of bind parameters, i.e. those specified
by query.params(), into the resulting SQL expression.
Previously the values would not be transferred
and bind parameters would come out as None.

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

Subquery-eager-loading now works with Query objects
which include params(), as well as get() Queries.

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

Can now call make_transient() on an instance that
is referenced by parent objects via many-to-one,
without the parent's foreign key value getting
temporarily set to None - this was a function
of the "detect primary key switch" flush handler.
It now ignores objects that are no longer
in the "persistent" state, and the parent's
foreign key identifier is left unaffected.

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

query.order_by() now accepts False, which cancels
any existing order_by() state on the Query, allowing
subsequent generative methods to be called which do
not support ORDER BY.  This is not the same as the
already existing feature of passing None, which
suppresses any existing order_by() settings, including
those configured on the mapper.  False will make it
as though order_by() was never called, while
None is an active setting.

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

An instance which is moved to "transient", has
an incomplete or missing set of primary key
attributes, and contains expired attributes, will
raise an InvalidRequestError if an expired attribute
is accessed, instead of getting a recursion overflow.

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

The make_transient() function is now in the generated
documentation.

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

make_transient() removes all "loader" callables from
the state being made transient, removing any
"expired" state - all unloaded attributes reset back
to undefined, None/empty on access.

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

The warning emitted by the Unicode and String types
with convert_unicode=True no longer embeds the actual
value passed.   This so that the Python warning
registry does not continue to grow in size, the warning
is emitted once as per the warning filter settings,
and large string values don't pollute the output.

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

Fixed bug that would prevent overridden clause
compilation from working for "annotated" expression
elements, which are often generated by the ORM.

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

The argument to "ESCAPE" of a LIKE operator or similar
is passed through render_literal_value(), which may
implement escaping of backslashes.

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

Fixed bug in Enum type which blew away native_enum
flag when used with TypeDecorators or other adaption
scenarios.

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

Inspector hits bind.connect() when invoked to ensure
initialize has been called.  the internal name ".conn"
is changed to ".bind", since that's what it is.

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

Modified the internals of "column annotation" such that
a custom Column subclass can safely override
_constructor to return Column, for the purposes of
making "configurational" column classes that aren't
involved in proxying, etc.

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

Column.copy() takes along the "unique" attribute
among others, fixes regarding declarative
mixins

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

render_literal_value() is overridden which escapes
backslashes, currently applies to the ESCAPE clause
of LIKE and similar expressions.
Ultimately this will have to detect the value of
"standard_conforming_strings" for full behavior.

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

Won't generate "CREATE TYPE" / "DROP TYPE" if
using types.Enum on a PG version prior to 8.3 -
the supports_native_enum flag is fully
honored.

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

MySQL dialect doesn't emit CAST() for MySQL version
detected < 4.0.2.  This allows the unicode
check on connect to proceed.

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

MySQL dialect now detects NO_BACKSLASH_ESCAPES sql
mode, in addition to ANSI_QUOTES.

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

render_literal_value() is overridden which escapes
backslashes, currently applies to the ESCAPE clause
of LIKE and similar expressions.   This behavior
is derived from detecting the value of
NO_BACKSLASH_ESCAPES.

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

Fixed ora-8 compatibility flags such that they
don't cache a stale value from before the first
database connection actually occurs.

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

Oracle's "native decimal" metadata begins to return
ambiguous typing information about numerics
when columns are embedded in subqueries as well
as when ROWNUM is consulted with subqueries, as we
do for limit/offset.  We've added these ambiguous
conditions to the cx_oracle "convert to Decimal()"
handler, so that we receive numerics as Decimal
in more cases instead of as floats.  These are
then converted, if requested, into Integer
or Float, or otherwise kept as the lossless
Decimal.

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

If server_version_info is outside the usual
range of (8, ), (9, ), (10, ), a warning is emitted
which suggests checking that the FreeTDS version
configuration is using 7.0 or 8.0, not 4.2.

.. change::
:tags: firebird
:tickets: 1823

Fixed incorrect signature in do_execute(), error
introduced in 0.6.1.

.. change::
:tags: firebird
:tickets: 1813

Firebird dialect adds CHAR, VARCHAR types which
accept a "charset" flag, to support Firebird
"CHARACTER SET" clause.

.. change::
:tags: declarative
:tickets: 1805, 1796, 1751

Added support for classproperty to provide
any kind of schema/mapping construct from a
declarative mixin, including columns with foreign
keys, relationships, column_property, deferred.
This solves all such issues on declarative mixins.
An error is raised if any MapperProperty subclass
is specified on a mixin without using classproperty.

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

a mixin class can now define a column that matches
one which is present on a __table__ defined on a
subclass.  It cannot, however, define one that is
not present in the __table__, and the error message
here now works.

.. change::
:tags: extension, compiler
:tickets: 1838

The 'default' compiler is automatically copied over
when overriding the compilation of a built in
clause construct, so no KeyError is raised if the
user-defined compiler is specific to certain
backends and compilation for a different backend
is invoked.

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

Added documentation for the Inspector.

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

Fixed memoized_property and memoized_instancemethod
decorators so that Sphinx documentation picks up
these attributes and methods, such as
ResultProxy.inserted_primary_key.

.. changelog::

0.6.1

:released: Mon May 31 2010

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

Fixed regression introduced in 0.6.0 involving improper
history accounting on mutable attributes.

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

Fixed regression introduced in 0.6.0 unit of work refactor
that broke updates for bi-directional relationship()
with post_update=True.

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

session.merge() will not expire attributes on the returned
instance if that instance is "pending".

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

fixed __setstate__ method of CollectionAdapter to not
fail during deserialize where parent InstanceState not
yet unserialized.

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

Added internal warning in case an instance without a
full PK happened to be expired and then was asked
to refresh.

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

Added more aggressive caching to the mapper's usage of
UPDATE, INSERT, and DELETE expressions.  Assuming the
statement has no per-object SQL expressions attached,
the expression objects are cached by the mapper after
the first create, and their compiled form is stored
persistently in a cache dictionary for the duration of
the related Engine.  The cache is an LRUCache for the
rare case that a mapper receives an extremely
high number of different column patterns as UPDATEs.

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

expr.in_() now accepts a text() construct as the argument.
Grouping parenthesis are added automatically, i.e. usage
is like `col.in_(text("select id from table"))`.

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

Columns of _Binary type (i.e. LargeBinary, BLOB, etc.)
will coerce a "basestring" on the right side into a
_Binary as well so that required DBAPI processing
takes place.

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

Added table.add_is_dependent_on(othertable), allows manual
placement of dependency rules between two Table objects
for use within create_all(), drop_all(), sorted_tables.

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

Fixed bug that prevented implicit RETURNING from functioning
properly with composite primary key that contained zeroes.

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

Fixed errant space character when generating ADD CONSTRAINT
for a named UNIQUE constraint.

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

Fixed "table" argument on constructor of ForeignKeyConstraint

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

Fixed bug in connection pool cursor wrapper whereby if a
cursor threw an exception on close(), the logging of the
message would fail.

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

the _make_proxy() method of ColumnClause and Column now use
self.__class__ to determine the class of object to be returned
instead of hardcoding to ColumnClause/Column, making it slightly
easier to produce specific subclasses of these which work in
alias/subquery situations.

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

func.XXX() doesn't inadvertently resolve to non-Function
classes (e.g. fixes func.text()).

.. change::
:tags: engines
:tickets: 1781

Fixed building the C extensions on Python 2.4.

.. change::
:tags: engines
:tickets:

Pool classes will reuse the same "pool_logging_name" setting
after a dispose() occurs.

.. change::
:tags: engines
:tickets:

Engine gains an "execution_options" argument and
update_execution_options() method, which will apply to
all connections generated by this engine.

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

func.sysdate() emits "SYSDATE()", i.e. with the ending
parenthesis, on MySQL.

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

Fixed concatenation of constraints when "PRIMARY KEY"
constraint gets moved to column level due to SQLite
AUTOINCREMENT keyword being rendered.

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

Added a check for cx_oracle versions lower than version 5,
in which case the incompatible "output type handler" won't
be used.   This will impact decimal accuracy and some
unicode handling issues.

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

Fixed use_ansi=False mode, which was producing broken
WHERE clauses in pretty much all cases.

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

Re-established support for Oracle 8 with cx_oracle,
including that use_ansi is set to False automatically,
NVARCHAR2 and NCLOB are not rendered for Unicode,
"native unicode" check doesn't fail, cx_oracle
"native unicode" mode is disabled, VARCHAR() is emitted
with bytes count instead of char count.

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

oracle_xe 5 doesn't accept a Python unicode object in
its connect string in normal Python 2.x mode - so we coerce
to str() directly.  non-ascii characters aren't supported
in connect strings here since we don't know what encoding
we could use.

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

FOR UPDATE is emitted in the syntactically correct position
when limit/offset is used, i.e. the ROWNUM subquery.
However, Oracle can't really handle FOR UPDATE with ORDER BY
or with subqueries, so its still not very usable, but at
least SQLA gets the SQL past the Oracle parser.

.. change::
:tags: firebird
:tickets: 1521

Added a label to the query used within has_table() and
has_sequence() to work with older versions of Firebird
that don't provide labels for result columns.

.. change::
:tags: firebird
:tickets: 1779

Added integer coercion to the "type_conv" attribute when
passed via query string, so that it is properly interpreted
by Kinterbasdb.

.. change::
:tags: firebird
:tickets: 1646

Added 'connection shutdown' to the list of exception strings
which indicate a dropped connection.

.. change::
:tags: sqlsoup
:tickets: 1783

the SqlSoup constructor accepts a `base` argument which specifies
the base class to use for mapped classes, the default being
`object`.

.. changelog::

0.6.0

:released: Sun Apr 18 2010

.. change::
:tags: orm
:tickets: 1742, 1081

Unit of work internals have been rewritten.  Units of work
with large numbers of objects interdependent objects
can now be flushed without recursion overflows
as there is no longer reliance upon recursive calls.  The number of internal structures now stays
constant for a particular session state, regardless of
how many relationships are present on mappings.  The flow
of events now corresponds to a linear list of steps,
generated by the mappers and relationships based on actual
work to be done, filtered through a single topological sort
for correct ordering.  Flush actions are assembled using
far fewer steps and less memory.

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

Along with the UOW rewrite, this also removes an issue
introduced in 0.6beta3 regarding topological cycle detection
for units of work with long dependency cycles.  We now use
an algorithm written by Guido (thanks Guido!).

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

one-to-many relationships now maintain a list of positive
parent-child associations within the flush, preventing
previous parents marked as deleted from cascading a
delete or NULL foreign key set on those child objects,
despite the end-user not removing the child from the old
association.

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

A collection lazy load will switch off default
eagerloading on the reverse many-to-one side, since
that loading is by definition unnecessary.

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

Session.refresh() now does an equivalent expire()
on the given instance first, so that the "refresh-expire"
cascade is propagated.   Previously, refresh() was
not affected in any way by the presence of "refresh-expire"
cascade.   This is a change in behavior versus that
of 0.6beta2, where the "lockmode" flag passed to refresh()
would cause a version check to occur.  Since the instance
is first expired, refresh() always upgrades the object
to the most recent version.

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

The 'refresh-expire' cascade, when reaching a pending object,
will expunge the object if the cascade also includes
"delete-orphan", or will simply detach it otherwise.

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

id(obj) is no longer used internally within topological.py,
as the sorting functions now require hashable objects
only.

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

The ORM will set the docstring of all generated descriptors
to None by default.  This can be overridden using 'doc'
(or if using Sphinx, attribute docstrings work too).

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

Added kw argument 'doc' to all mapper property callables
as well as Column().  Will assemble the string 'doc' as
the '__doc__' attribute on the descriptor.

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

Usage of version_id_col on a backend that supports
cursor.rowcount for execute() but not executemany() now works
when a delete is issued (already worked for saves, since those
don't use executemany()). For a backend that doesn't support
cursor.rowcount at all, a warning is emitted the same
as with saves.

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

The ORM now short-term caches the "compiled" form of
insert() and update() constructs when flushing lists of
objects of all the same class, thereby avoiding redundant
compilation per individual INSERT/UPDATE within an
individual flush() call.

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

internal getattr(), setattr(), getcommitted() methods
on ColumnProperty, CompositeProperty, RelationshipProperty
have been underscored (i.e. are private), signature has
changed.

.. change::
:tags: engines
:tickets: 1757

The C extension now also works with DBAPIs which use custom
sequences as row (and not only tuples).

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

Restored some bind-labeling logic from 0.5 which ensures
that tables with column names that overlap another column
of the form "<tablename>_<columnname>" won't produce
errors if column._label is used as a bind name during
an UPDATE.  Test coverage which wasn't present in 0.5
has been added.

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

somejoin.select(fold_equivalents=True) is no longer
deprecated, and will eventually be rolled into a more
comprehensive version of the feature for.

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

the Numeric type raises an *enormous* warning when expected
to convert floats to Decimal from a DBAPI that returns floats.
This includes SQLite, Sybase, MS-SQL.

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

Fixed an error in expression typing which caused an endless
loop for expressions with two NULL types.

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

Fixed bug in execution_options() feature whereby the existing
Transaction and other state information from the parent
connection would not be propagated to the sub-connection.

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

Added new 'compiled_cache' execution option.  A dictionary
where Compiled objects will be cached when the Connection
compiles a clause expression into a dialect- and parameter-
specific Compiled object.  It is the user's responsibility to
manage the size of this dictionary, which will have keys
corresponding to the dialect, clause element, the column
names within the VALUES or SET clause of an INSERT or UPDATE,
as well as the "batch" mode for an INSERT or UPDATE statement.

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

Added get_pk_constraint() to reflection.Inspector, similar
to get_primary_keys() except returns a dict that includes the
name of the constraint, for supported backends (PG so far).

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

Table.create() and Table.drop() no longer apply metadata-
level create/drop events.

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

the compiler extension now allows compiles decorators
on base classes that extend to child classes, compiles
decorators on child classes that aren't broken by a
compiles decorator on the base class.

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

Declarative will raise an informative error message
if a non-mapped class attribute is referenced in the
string-based relationship() arguments.

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

Further reworked the "mixin" logic in declarative to
additionally allow __mapper_args__ as a classproperty
on a mixin, such as to dynamically assign polymorphic_identity.

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

PostgreSQL now reflects sequence names associated with
SERIAL columns correctly, after the name of the sequence
has been changed.  Thanks to Kumar McMillan for the patch.

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

Repaired missing import in psycopg2._PGNumeric type when
unknown numeric is received.

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

psycopg2/pg8000 dialects now aware of REAL[], FLOAT[],
DOUBLE_PRECISION[], NUMERIC[] return types without
raising an exception.

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

PostgreSQL reflects the name of primary key constraints,
if one exists.

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

Now using cx_oracle output converters so that the
DBAPI returns natively the kinds of values we prefer:

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

NUMBER values with positive precision + scale convert
to cx_oracle.STRING and then to Decimal.   This
allows perfect precision for the Numeric type when
using cx_oracle.

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

STRING/FIXED_CHAR now convert to unicode natively.
SQLAlchemy's String types then don't need to
apply any kind of conversions.

.. change::
:tags: firebird
:tickets:

The functionality of result.rowcount can be disabled on a
per-engine basis by setting 'enable_rowcount=False'
on create_engine().  Normally, cursor.rowcount is called
after any UPDATE or DELETE statement unconditionally,
because the cursor is then closed and Firebird requires
an open cursor in order to get a rowcount.  This
call is slightly expensive however so it can be disabled.
To re-enable on a per-execution basis, the
'enable_rowcount=True' execution option may be used.

.. change::
:tags: examples
:tickets:

Updated attribute_shard.py example to use a more robust
method of searching a Query for binary expressions which
compare columns against literal values.

.. changelog::

0.6beta3

:released: Sun Mar 28 2010

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

Major feature: Added new "subquery" loading capability to
relationship().   This is an eager loading option which
generates a second SELECT for each collection represented
in a query, across all parents at once.  The query
re-issues the original end-user query wrapped in a subquery,
applies joins out to the target collection, and loads
all those collections fully in one result, similar to
"joined" eager loading but using all inner joins and not
re-fetching full parent rows repeatedly (as most DBAPIs seem
to do, even if columns are skipped).   Subquery loading is
available at mapper config level using "lazy='subquery'" and
at the query options level using "subqueryload(props..)",
"subqueryload_all(props...)".

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

To accommodate the fact that there are now two kinds of eager
loading available, the new names for eagerload() and
eagerload_all() are joinedload() and joinedload_all().  The
old names will remain as synonyms for the foreseeable future.

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

The "lazy" flag on the relationship() function now accepts
a string argument for all kinds of loading: "select", "joined",
"subquery", "noload" and "dynamic", where the default is now
"select".  The old values of True/
False/None still retain their usual meanings and will remain
as synonyms for the foreseeable future.

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

Added with_hint() method to Query() construct.  This calls
directly down to select().with_hint() and also accepts
entities as well as tables and aliases.  See with_hint() in the
SQL section below.

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

Fixed bug in Query whereby calling q.join(prop).from_self(...).
join(prop) would fail to render the second join outside the
subquery, when joining on the same criterion as was on the
inside.

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

Fixed bug in Query whereby the usage of aliased() constructs
would fail if the underlying table (but not the actual alias)
were referenced inside the subquery generated by
q.from_self() or q.select_from().

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

Fixed bug which affected all eagerload() and similar options
such that "remote" eager loads, i.e. eagerloads off of a lazy
load such as query(A).options(eagerload(A.b, B.c))
wouldn't eagerload anything, but using eagerload("b.c") would
work fine.

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

Query gains an add_columns(\*columns) method which is a multi-
version of add_column(col).  add_column(col) is future
deprecated.

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

Query.join() will detect if the end result will be
"FROM A JOIN A", and will raise an error if so.

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

Query.join(Cls.propname, from_joinpoint=True) will check more
carefully that "Cls" is compatible with the current joinpoint,
and act the same way as Query.join("propname", from_joinpoint=True)
in that regard.

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

Added with_hint() method to select() construct.  Specify
a table/alias, hint text, and optional dialect name, and
"hints" will be rendered in the appropriate place in the
statement.  Works for Oracle, Sybase, MySQL.

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

Fixed bug introduced in 0.6beta2 where column labels would
render inside of column expressions already assigned a label.

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

The psycopg2 dialect will log NOTICE messages via the
"sqlalchemy.dialects.postgresql" logger name.

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

the TIME and TIMESTAMP types are now available from the
postgresql dialect directly, which add the PG-specific
argument 'precision' to both.   'precision' and
'timezone' are correctly reflected for both TIME and
TIMEZONE types.

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

No longer guessing that TINYINT(1) should be BOOLEAN
when reflecting - TINYINT(1) is returned.  Use Boolean/
BOOLEAN in table definition to get boolean conversion
behavior.

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

The Oracle dialect will issue VARCHAR type definitions
using character counts, i.e. VARCHAR2(50 CHAR), so that
the column is sized in terms of characters and not bytes.
Column reflection of character types will also use
ALL_TAB_COLUMNS.CHAR_LENGTH instead of
ALL_TAB_COLUMNS.DATA_LENGTH.  Both of these behaviors take
effect when the server version is 9 or higher - for
version 8, the old behaviors are used.

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

Using a mixin won't break if the mixin implements an
unpredictable __getattribute__(), i.e. Zope interfaces.

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

Using classdecorator and similar on mixins to define
__tablename__, __table_args__, etc. now works if
the method references attributes on the ultimate
subclass.

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

relationships and columns with foreign keys aren't
allowed on declarative mixins, sorry.

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

The sqlalchemy.orm.shard module now becomes an extension,
sqlalchemy.ext.horizontal_shard.   The old import
works with a deprecation warning.

.. changelog::

0.6beta2

:released: Sat Mar 20 2010

.. change::
:tags: py3k
:tickets:

Improved the installation/test setup regarding Python 3,
now that Distribute runs on Py3k.   distribute_setup.py
is now included.  See README.py3k for Python 3 installation/
testing instructions.

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

The official name for the relation() function is now
relationship(), to eliminate confusion over the relational
algebra term.  relation() however will remain available
in equal capacity for the foreseeable future.

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

Added "version_id_generator" argument to Mapper, this is a
callable that, given the current value of the "version_id_col",
returns the next version number.  Can be used for alternate
versioning schemes such as uuid, timestamps.

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

added "lockmode" kw argument to Session.refresh(), will
pass through the string value to Query the same as
in with_lockmode(), will also do version check for a
version_id_col-enabled mapping.

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

Fixed bug whereby calling query(A).join(A.bs).add_entity(B)
in a joined inheritance scenario would double-add B as a
target and produce an invalid query.

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

Fixed bug in session.rollback() which involved not removing
formerly "pending" objects from the session before
re-integrating "deleted" objects, typically occurred with
natural primary keys. If there was a primary key conflict
between them, the attach of the deleted would fail
internally. The formerly "pending" objects are now expunged
first.

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

Removed a lot of logging that nobody really cares about,
logging that remains will respond to live changes in the
log level.  No significant overhead is added.

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

Fixed bug in session.merge() which prevented dict-like
collections from merging.

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

session.merge() works with relations that specifically
don't include "merge" in their cascade options - the target
is ignored completely.

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

session.merge() will not expire existing scalar attributes
on an existing target if the target has a value for that
attribute, even if the incoming merged doesn't have
a value for the attribute.  This prevents unnecessary loads
on existing items.  Will still mark the attr as expired
if the destination doesn't have the attr, though, which
fulfills some contracts of deferred cols.

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

The "allow_null_pks" flag is now called "allow_partial_pks",
defaults to True, acts like it did in 0.5 again.  Except,
it also is implemented within merge() such that a SELECT
won't be issued for an incoming instance with partially
NULL primary key if the flag is False.

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

Fixed bug in 0.6-reworked "many-to-one" optimizations
such that a many-to-one that is against a non-primary key
column on the remote table (i.e. foreign key against a
UNIQUE column) will pull the "old" value in from the
database during a change, since if it's in the session
we will need it for proper history/backref accounting,
and we can't pull from the local identity map on a
non-primary key column.

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

fixed internal error which would occur if calling has()
or similar complex expression on a single-table inheritance
relation().

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

query.one() no longer applies LIMIT to the query, this to
ensure that it fully counts all object identities present
in the result, even in the case where joins may conceal
multiple identities for two or more rows.  As a bonus,
one() can now also be called with a query that issued
from_statement() to start with since it no longer modifies
the query.

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

query.get() now returns None if queried for an identifier
that is present in the identity map with a different class
than the one requested, i.e. when using polymorphic loading.

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

A major fix in query.join(), when the "on" clause is an
attribute of an aliased() construct, but there is already
an existing join made out to a compatible target, query properly
joins to the right aliased() construct instead of sticking
onto the right side of the existing join.

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

Slight improvement to the fix for to not issue
needless updates of the primary key column during a so-called
"row switch" operation, i.e. add + delete of two objects
with the same PK.

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

Now uses sqlalchemy.orm.exc.DetachedInstanceError when an
attribute load or refresh action fails due to object
being detached from any Session.   UnboundExecutionError
is specific to engines bound to sessions and statements.

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

Query called in the context of an expression will render
disambiguating labels in all cases.    Note that this does
not apply to the existing .statement and .subquery()
accessor/method, which still honors the .with_labels()
setting that defaults to False.

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

Query.union() retains disambiguating labels within the
returned statement, thus avoiding various SQL composition
errors which can result from column name conflicts.

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

Fixed bug in attribute history that inadvertently invoked
__eq__ on mapped instances.

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

Some internal streamlining of object loading grants a
small speedup for large results, estimates are around
10-15%.   Gave the "state" internals a good solid
cleanup with less complexity, datamembers,
method calls, blank dictionary creates.

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

Documentation clarification for query.delete()

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

Fixed cascade bug in many-to-one relation() when attribute
was set to None, introduced in r6711 (cascade deleted
items into session during add()).

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

Calling query.order_by() or query.distinct() before calling
query.select_from(), query.with_polymorphic(), or
query.from_statement() raises an exception now instead of
silently dropping those criterion.

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

query.scalar() now raises an exception if more than one
row is returned.  All other behavior remains the same.

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

Fixed bug which caused "row switch" logic, that is an
INSERT and DELETE replaced by an UPDATE, to fail when
version_id_col was in use.

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

join() will now simulate a NATURAL JOIN by default.  Meaning,
if the left side is a join, it will attempt to join the right
side to the rightmost side of the left first, and not raise
any exceptions about ambiguous join conditions if successful
even if there are further join targets across the rest of
the left.

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

The most common result processors conversion function were
moved to the new "processors" module.  Dialect authors are
encouraged to use those functions whenever they correspond
to their needs instead of implementing custom ones.

.. change::
:tags: sql
:tickets: 1694, 1698

SchemaType and subclasses Boolean, Enum are now serializable,
including their ddl listener and other event callables.

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

Some platforms will now interpret certain literal values
as non-bind parameters, rendered literally into the SQL
statement.   This to support strict SQL-92 rules that are
enforced by some platforms including MS-SQL and Sybase.
In this model, bind parameters aren't allowed in the
columns clause of a SELECT, nor are certain ambiguous
expressions like "?=?".  When this mode is enabled, the base
compiler will render the binds as inline literals, but only across
strings and numeric values.  Other types such as dates
will raise an error, unless the dialect subclass defines
a literal rendering function for those.  The bind parameter
must have an embedded literal value already or an error
is raised (i.e. won't work with straight bindparam('x')).
Dialects can also expand upon the areas where binds are not
accepted, such as within argument lists of functions
(which don't work on MS-SQL when native SQL binding is used).

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

Added "unicode_errors" parameter to String, Unicode, etc.
Behaves like the 'errors' keyword argument to
the standard library's string.decode() functions.   This flag
requires that `convert_unicode` is set to `"force"` - otherwise,
SQLAlchemy is not guaranteed to handle the task of unicode
conversion.   Note that this flag adds significant performance
overhead to row-fetching operations for backends that already
return unicode objects natively (which most DBAPIs do).  This
flag should only be used as an absolute last resort for reading
strings from a column with varied or corrupted encodings,
which only applies to databases that accept invalid encodings
in the first place (i.e. MySQL. *not* PG, Sqlite, etc.)

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

Added math negation operator support, -x.

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

FunctionElement subclasses are now directly executable the
same way any func.foo() construct is, with automatic
SELECT being applied when passed to execute().

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

The "type" and "bind" keyword arguments of a func.foo()
construct are now local to "func." constructs and are
not part of the FunctionElement base class, allowing
a "type" to be handled in a custom constructor or
class-level variable.

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

Restored the keys() method to ResultProxy.

.. change::
:tags: sql
:tickets: 1647, 1683

The type/expression system now does a more complete job
of determining the return type from an expression
as well as the adaptation of the Python operator into
a SQL operator, based on the full left/right/operator
of the given expression.  In particular
the date/time/interval system created for PostgreSQL
EXTRACT in has now been generalized into
the type system.   The previous behavior which often
occurred of an expression "column + literal" forcing
the type of "literal" to be the same as that of "column"
will now usually not occur - the type of
"literal" is first derived from the Python type of the
literal, assuming standard native Python types + date
types, before falling back to that of the known type
on the other side of the expression.  If the
"fallback" type is compatible (i.e. CHAR from String),
the literal side will use that.  TypeDecorator
types override this by default to coerce the "literal"
side unconditionally, which can be changed by implementing
the coerce_compared_value() method. Also part of.

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

Made sqlalchemy.sql.expressions.Executable part of public
API, used for any expression construct that can be sent to
execute().  FunctionElement now inherits Executable so that
it gains execution_options(), which are also propagated
to the select() that's generated within execute().
Executable in turn subclasses _Generative which marks
any ClauseElement that supports the _generative
decorator - these may also become "public" for the benefit
of the compiler extension at some point.

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

A change to the solution for - an end-user
defined bind parameter name that directly conflicts with
a column-named bind generated directly from the SET or
VALUES clause of an update/insert generates a compile error.
This reduces call counts and eliminates some cases where
undesirable name conflicts could still occur.

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

Column() requires a type if it has no foreign keys (this is
not new).  An error is now raised if a Column() has no type
and no foreign keys.

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

the "scale" argument of the Numeric() type is honored when
coercing a returned floating point value into a string
on its way to Decimal - this allows accuracy to function
on SQLite, MySQL.

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

the copy() method of Column now copies over uninitialized
"on table attach" events.  Helps with the new declarative
"mixin" capability.

.. change::
:tags: engines
:tickets:

Added an optional C extension to speed up the sql layer by
reimplementing RowProxy and the most common result processors.
The actual speedups will depend heavily on your DBAPI and
the mix of datatypes used in your tables, and can vary from
a 30% improvement to more than 200%.  It also provides a modest
(~15-20%) indirect improvement to ORM speed for large queries.
Note that it is *not* built/installed by default.
See README for installation instructions.

.. change::
:tags: engines
:tickets:

the execution sequence pulls all rowcount/last inserted ID
info from the cursor before commit() is called on the
DBAPI connection in an "autocommit" scenario.  This helps
mxodbc with rowcount and is probably a good idea overall.

.. change::
:tags: engines
:tickets: 1719

Opened up logging a bit such that isEnabledFor() is called
more often, so that changes to the log level for engine/pool
will be reflected on next connect.   This adds a small
amount of method call overhead.  It's negligible and will make
life a lot easier for all those situations when logging
just happens to be configured after create_engine() is called.

.. change::
:tags: engines
:tickets:

The assert_unicode flag is deprecated.  SQLAlchemy will raise
a warning in all cases where it is asked to encode a non-unicode
Python string, as well as when a Unicode or UnicodeType type
is explicitly passed a bytestring.  The String type will do nothing
for DBAPIs that already accept Python unicode objects.

.. change::
:tags: engines
:tickets:

Bind parameters are sent as a tuple instead of a list. Some
backend drivers will not accept bind parameters as a list.

.. change::
:tags: engines
:tickets:

threadlocal engine wasn't properly closing the connection
upon close() - fixed that.

.. change::
:tags: engines
:tickets:

Transaction object doesn't rollback or commit if it isn't
"active", allows more accurate nesting of begin/rollback/commit.

.. change::
:tags: engines
:tickets:

Python unicode objects as binds result in the Unicode type,
not string, thus eliminating a certain class of unicode errors
on drivers that don't support unicode binds.

.. change::
:tags: engines
:tickets: 1555

Added "logging_name" argument to create_engine(), Pool() constructor
as well as "pool_logging_name" argument to create_engine() which
filters down to that of Pool.   Issues the given string name
within the "name" field of logging messages instead of the default
hex identifier string.

.. change::
:tags: engines
:tickets:

The visit_pool() method of Dialect is removed, and replaced with
on_connect().  This method returns a callable which receives
the raw DBAPI connection after each one is created.   The callable
is assembled into a first_connect/connect pool listener by the
connection strategy if non-None.   Provides a simpler interface
for dialects.

.. change::
:tags: engines
:tickets: 1728

StaticPool now initializes, disposes and recreates without
opening a new connection - the connection is only opened when
first requested. dispose() also works on AssertionPool now.

.. change::
:tags: ticket: 1673, metadata
:tickets:

Added the ability to strip schema information when using
"tometadata" by passing "schema=None" as an argument. If schema
is not specified then the table's schema is retained.

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

DeclarativeMeta exclusively uses cls.__dict__ (not dict\_)
as the source of class information; _as_declarative exclusively
uses the  dict\_ passed to it as the source of class information
(which when using DeclarativeMeta is cls.__dict__).  This should
in theory make it easier for custom metaclasses to modify
the state passed into _as_declarative.

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

declarative now accepts mixin classes directly, as a means
to provide common functional and column-based elements on
all subclasses, as well as a means to propagate a fixed
set of __table_args__ or __mapper_args__ to subclasses.
For custom combinations of __table_args__/__mapper_args__ from
an inherited mixin to local, descriptors can now be used.
New details are all up in the Declarative documentation.
Thanks to Chris Withers for putting up with my strife
on this.

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

the __mapper_args__ dict is copied when propagating to a subclass,
and is taken straight off the class __dict__ to avoid any
propagation from the parent.  mapper inheritance already
propagates the things you want from the parent mapper.

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

An exception is raised when a single-table subclass specifies
a column that is already present on the base class.

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

Fixed reflection bug whereby when COLLATE was present,
nullable flag and server defaults would not be reflected.

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

Fixed reflection of TINYINT(1) "boolean" columns defined with
integer flags like UNSIGNED.

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

Further fixes for the mysql-connector dialect.

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

Composite PK table on InnoDB where the "autoincrement" column
isn't first will emit an explicit "KEY" phrase within
CREATE TABLE thereby avoiding errors.

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

Added reflection/create table support for a wide range
of MySQL keywords.

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

Fixed import error which could occur reflecting tables on
a Windows host

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

Re-established support for the pymssql dialect.

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

Various fixes for implicit returning, reflection,
etc. - the MS-SQL dialects aren't quite complete
in 0.6 yet (but are close)

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

Added basic support for mxODBC.

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

Removed the text_as_varchar option.

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

"out" parameters require a type that is supported by
cx_oracle.  An error will be raised if no cx_oracle
type can be found.

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

Oracle 'DATE' now does not perform any result processing,
as the DATE type in Oracle stores full date+time objects,
that's what you'll get.  Note that the generic types.Date
type *will* still call value.date() on incoming values,
however.  When reflecting a table, the reflected type
will be 'DATE'.

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

Added preliminary support for Oracle's WITH_UNICODE
mode.  At the very least this establishes initial
support for cx_Oracle with Python 3.  When WITH_UNICODE
mode is used in Python 2.xx, a large and scary warning
is emitted asking that the user seriously consider
the usage of this difficult mode of operation.

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

The except_() method now renders as MINUS on Oracle,
which is more or less equivalent on that platform.

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

Added support for rendering and reflecting
TIMESTAMP WITH TIME ZONE, i.e. TIMESTAMP(timezone=True).

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

Oracle INTERVAL type can now be reflected.

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

Added "native_datetime=True" flag to create_engine().
This will cause the DATE and TIMESTAMP types to skip
all bind parameter and result row processing, under
the assumption that PARSE_DECLTYPES has been enabled
on the connection.  Note that this is not entirely
compatible with the "func.current_date()", which
will be returned as a string.

.. change::
:tags: sybase
:tickets:

Implemented a preliminary working dialect for Sybase,
with sub-implementations for Python-Sybase as well
as Pyodbc.  Handles table
creates/drops and basic round trip functionality.
Does not yet include reflection or comprehensive
support of unicode/special expressions/etc.

.. change::
:tags: examples
:tickets:

Changed the beaker cache example a bit to have a separate
RelationCache option for lazyload caching.  This object
does a lookup among any number of potential attributes
more efficiently by grouping several into a common structure.
Both FromCache and RelationCache are simpler individually.

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

Major cleanup work in the docs to link class, function, and
method names into the API docs.

.. changelog::

0.6beta1

:released: Wed Feb 03 2010

.. change::
:tags: release, major
:tickets:

For the full set of feature descriptions, see
http://docs.sqlalchemy.org/en/latest/changelog/migration_06.html .
This document is a work in progress.

.. change::
:tags: release, major
:tickets:

All bug fixes and feature enhancements from the most
recent 0.5 version and below are also included within 0.6.

.. change::
:tags: release, major
:tickets:

Platforms targeted now include Python 2.4/2.5/2.6, Python
3.1, Jython2.5.

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

Changes to query.update() and query.delete():
- the 'expire' option on query.update() has been renamed to
'fetch', thus matching that of query.delete().
'expire' is deprecated and issues a warning.

- query.update() and query.delete() both default to
'evaluate' for the synchronize strategy.

- the 'synchronize' strategy for update() and delete()
raises an error on failure. There is no implicit fallback
onto "fetch". Failure of evaluation is based on the
structure of criteria, so success/failure is deterministic
based on code structure.

.. change::
:tags: orm
:tickets: 1186, 1492, 1544

Enhancements on many-to-one relations:
- many-to-one relations now fire off a lazyload in fewer
cases, including in most cases will not fetch the "old"
value when a new one is replaced.

- many-to-one relation to a joined-table subclass now uses
get() for a simple load (known as the "use_get"
condition), i.e. Related->Sub(Base), without the need to
redefine the primaryjoin condition in terms of the base
table.

- specifying a foreign key with a declarative column, i.e.
ForeignKey(MyRelatedClass.id) doesn't break the "use_get"
condition from taking place

- relation(), eagerload(), and eagerload_all() now feature
an option called "innerjoin". Specify `True` or `False` to
control whether an eager join is constructed as an INNER
or OUTER join. Default is `False` as always. The mapper
options will override whichever setting is specified on
relation(). Should generally be set for many-to-one, not
nullable foreign key relations to allow improved join
performance.

- the behavior of eagerloading such that the main query is
wrapped in a subquery when LIMIT/OFFSET are present now
makes an exception for the case when all eager loads are
many-to-one joins. In those cases, the eager joins are
against the parent table directly along with the
limit/offset without the extra overhead of a subquery,
since a many-to-one join does not add rows to the result.

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

Enhancements / Changes on Session.merge():

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

the "dont_load=True" flag on Session.merge() is deprecated
and is now "load=False".

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

Session.merge() is performance optimized, using half the
call counts for "load=False" mode compared to 0.5 and
significantly fewer SQL queries in the case of collections
for "load=True" mode.

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

merge() will not issue a needless merge of attributes if the
given instance is the same instance which is already present.

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

merge() now also merges the "options" associated with a given
state, i.e. those passed through query.options() which follow
along with an instance, such as options to eagerly- or
lazyily- load various attributes.   This is essential for
the construction of highly integrated caching schemes.  This
is a subtle behavioral change vs. 0.5.

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

A bug was fixed regarding the serialization of the "loader
path" present on an instance's state, which is also necessary
when combining the usage of merge() with serialized state
and associated options that should be preserved.

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

The all new merge() is showcased in a new comprehensive
example of how to integrate Beaker with SQLAlchemy.  See
the notes in the "examples" note below.

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

Primary key values can now be changed on a joined-table inheritance
object, and ON UPDATE CASCADE will be taken into account when
the flush happens.  Set the new "passive_updates" flag to False
on mapper() when using SQLite or MySQL/MyISAM.

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

flush() now detects when a primary key column was updated by
an ON UPDATE CASCADE operation from another primary key, and
can then locate the row for a subsequent UPDATE on the new PK
value.  This occurs when a relation() is there to establish
the relationship as well as passive_updates=True.

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

the "save-update" cascade will now cascade the pending *removed*
values from a scalar or collection attribute into the new session
during an add() operation.  This so that the flush() operation
will also delete or modify rows of those disconnected items.

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

Using a "dynamic" loader with a "secondary" table now produces
a query where the "secondary" table is *not* aliased.  This
allows the secondary Table object to be used in the "order_by"
attribute of the relation(), and also allows it to be used
in filter criterion against the dynamic relation.

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

relation() with uselist=False will emit a warning when
an eager or lazy load locates more than one valid value for
the row.  This may be due to primaryjoin/secondaryjoin
conditions which aren't appropriate for an eager LEFT OUTER
JOIN or for other conditions.

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

an explicit check occurs when a synonym() is used with
map_column=True, when a ColumnProperty (deferred or otherwise)
exists separately in the properties dictionary sent to mapper
with the same keyname.   Instead of silently replacing
the existing property (and possible options on that property),
an error is raised.

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

a "dynamic" loader sets up its query criterion at construction
time so that the actual query is returned from non-cloning
accessors like "statement".

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

the "named tuple" objects returned when iterating a
Query() are now pickleable.

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

mapping to a select() construct now requires that you
make an alias() out of it distinctly.   This to eliminate
confusion over such issues as

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

query.join() has been reworked to provide more consistent
behavior and more flexibility (includes)

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

query.select_from() accepts multiple clauses to produce
multiple comma separated entries within the FROM clause.
Useful when selecting from multiple-homed join() clauses.

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

query.select_from() also accepts mapped classes, aliased()
constructs, and mappers as arguments.  In particular this
helps when querying from multiple joined-table classes to ensure
the full join gets rendered.

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

query.get() can be used with a mapping to an outer join
where one or more of the primary key values are None.

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

query.from_self(), query.union(), others which do a
"SELECT * from (SELECT...)" type of nesting will do
a better job translating column expressions within the subquery
to the columns clause of the outer query.  This is
potentially backwards incompatible with 0.5, in that this
may break queries with literal expressions that do not have labels
applied (i.e. literal('foo'), etc.)

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

relation primaryjoin and secondaryjoin now check that they
are column-expressions, not just clause elements.  this prohibits
things like FROM expressions being placed there directly.

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

`expression.null()` is fully understood the same way
None is when comparing an object/collection-referencing
attribute within query.filter(), filter_by(), etc.

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

added "make_transient()" helper function which transforms a
persistent/ detached instance into a transient one (i.e.
deletes the instance_key and removes from any session.)

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

the allow_null_pks flag on mapper() is deprecated, and
the feature is turned "on" by default.  This means that
a row which has a non-null value for any of its primary key
columns will be considered an identity.  The need for this
scenario typically only occurs when mapping to an outer join.

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

the mechanics of "backref" have been fully merged into the
finer grained "back_populates" system, and take place entirely
within the _generate_backref() method of RelationProperty.  This
makes the initialization procedure of RelationProperty
simpler and allows easier propagation of settings (such as from
subclasses of RelationProperty) into the reverse reference.
The internal BackRef() is gone and backref() returns a plain
tuple that is understood by RelationProperty.

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

The version_id_col feature on mapper() will raise a warning when
used with dialects that don't support "rowcount" adequately.

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

added "execution_options()" to Query, to so options can be
passed to the resulting statement. Currently only
Select-statements have these options, and the only option
used is "stream_results", and the only dialect which knows
"stream_results" is psycopg2.

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

Query.yield_per() will set the "stream_results" statement
option automatically.

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

Deprecated or removed:
* 'allow_null_pks' flag on mapper() is deprecated.  It does
nothing now and the setting is "on" in all cases.
* 'transactional' flag on sessionmaker() and others is
removed. Use 'autocommit=True' to indicate 'transactional=False'.
* 'polymorphic_fetch' argument on mapper() is removed.
Loading can be controlled using the 'with_polymorphic'
option.
* 'select_table' argument on mapper() is removed.  Use
'with_polymorphic=("*", <some selectable>)' for this
functionality.
* 'proxy' argument on synonym() is removed.  This flag
did nothing throughout 0.5, as the "proxy generation"
behavior is now automatic.
* Passing a single list of elements to eagerload(),
eagerload_all(), contains_eager(), lazyload(),
defer(), and undefer() instead of multiple positional
\*args is deprecated.
* Passing a single list of elements to query.order_by(),
query.group_by(), query.join(), or query.outerjoin()
instead of multiple positional \*args is deprecated.
* query.iterate_instances() is removed.  Use query.instances().
* Query.query_from_parent() is removed.  Use the
sqlalchemy.orm.with_parent() function to produce a
"parent" clause, or alternatively query.with_parent().
* query._from_self() is removed, use query.from_self()
instead.
* the "comparator" argument to composite() is removed.
Use "comparator_factory".
* RelationProperty._get_join() is removed.
* the 'echo_uow' flag on Session is removed.  Use
logging on the "sqlalchemy.orm.unitofwork" name.
* session.clear() is removed.  use session.expunge_all().
* session.save(), session.update(), session.save_or_update()
are removed.  Use session.add() and session.add_all().
* the "objects" flag on session.flush() remains deprecated.
* the "dont_load=True" flag on session.merge() is deprecated
in favor of "load=False".
* ScopedSession.mapper remains deprecated.  See the
usage recipe at
http://www.sqlalchemy.org/trac/wiki/UsageRecipes/SessionAwareMapper
* passing an InstanceState (internal SQLAlchemy state object) to
attributes.init_collection() or attributes.get_history() is
deprecated.  These functions are public API and normally
expect a regular mapped object instance.
* the 'engine' parameter to declarative_base() is removed.
Use the 'bind' keyword argument.

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

the "autocommit" flag on select() and text() as well
as select().autocommit() are deprecated - now call
.execution_options(autocommit=True) on either of those
constructs, also available directly on Connection and orm.Query.

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

the autoincrement flag on column now indicates the column
which should be linked to cursor.lastrowid, if that method
is used.  See the API docs for details.

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

an executemany() now requires that all bound parameter
sets require that all keys are present which are
present in the first bound parameter set.  The structure
and behavior of an insert/update statement is very much
determined by the first parameter set, including which
defaults are going to fire off, and a minimum of
guesswork is performed with all the rest so that performance
is not impacted.  For this reason defaults would otherwise
silently "fail" for missing parameters, so this is now guarded
against.

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

returning() support is native to insert(), update(),
delete(). Implementations of varying levels of
functionality exist for PostgreSQL, Firebird, MSSQL and
Oracle. returning() can be called explicitly with column
expressions which are then returned in the resultset,
usually via fetchone() or first().

insert() constructs will also use RETURNING implicitly to
get newly generated primary key values, if the database
version in use supports it (a version number check is
performed). This occurs if no end-user returning() was
specified.

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

union(), intersect(), except() and other "compound" types
of statements have more consistent behavior w.r.t.
parenthesizing.   Each compound element embedded within
another will now be grouped with parenthesis - previously,
the first compound element in the list would not be grouped,
as SQLite doesn't like a statement to start with
parenthesis.   However, PostgreSQL in particular has
precedence rules regarding INTERSECT, and it is
more consistent for parenthesis to be applied equally
to all sub-elements.   So now, the workaround for SQLite
is also what the workaround for PG was previously -
when nesting compound elements, the first one usually needs
".alias().select()" called on it to wrap it inside
of a subquery.

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

insert() and update() constructs can now embed bindparam()
objects using names that match the keys of columns.  These
bind parameters will circumvent the usual route to those
keys showing up in the VALUES or SET clause of the generated
SQL.

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

the Binary type now returns data as a Python string
(or a "bytes" type in Python 3), instead of the built-
in "buffer" type.  This allows symmetric round trips
of binary data.

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

Added a tuple_() construct, allows sets of expressions
to be compared to another set, typically with IN against
composite primary keys or similar.  Also accepts an
IN with multiple columns.   The "scalar select can
have only one column" error message is removed - will
rely upon the database to report problems with
col mismatch.

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

User-defined "default" and "onupdate" callables which
accept a context should now call upon
"context.current_parameters" to get at the dictionary
of bind parameters currently being processed.  This
dict is available in the same way regardless of
single-execute or executemany-style statement execution.

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

multi-part schema names, i.e. with dots such as
"dbo.master", are now rendered in select() labels
with underscores for dots, i.e. "dbo_master_table_column".
This is a "friendly" label that behaves better
in result sets.

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

removed needless "counter" behavior with select()
labelnames that match a column name in the table,
i.e. generates "tablename_id" for "id", instead of
"tablename_id_1" in an attempt to avoid naming
conflicts, when the table has a column actually
named "tablename_id" - this is because
the labeling logic is always applied to all columns
so a naming conflict will never occur.

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

calling expr.in_([]), i.e. with an empty list, emits a warning
before issuing the usual "expr != expr" clause.  The
"expr != expr" can be very expensive, and it's preferred
that the user not issue in_() if the list is empty,
instead simply not querying, or modifying the criterion
as appropriate for more complex situations.

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

Added "execution_options()" to select()/text(), which set the
default options for the Connection.  See the note in "engines".

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

Deprecated or removed:
* "scalar" flag on select() is removed, use
select.as_scalar().
* "shortname" attribute on bindparam() is removed.
* postgres_returning, firebird_returning flags on
insert(), update(), delete() are deprecated, use
the new returning() method.
* fold_equivalents flag on join is deprecated (will remain
until is implemented)

.. change::
:tags: engines
:tickets: 443

transaction isolation level may be specified with
create_engine(... isolation_level="..."); available on
postgresql and sqlite.

.. change::
:tags: engines
:tickets:

Connection has execution_options(), generative method
which accepts keywords that affect how the statement
is executed w.r.t. the DBAPI.   Currently supports
"stream_results", causes psycopg2 to use a server
side cursor for that statement, as well as
"autocommit", which is the new location for the "autocommit"
option from select() and text().   select() and
text() also have .execution_options() as well as
ORM Query().

.. change::
:tags: engines
:tickets: 1630

fixed the import for entrypoint-driven dialects to
not rely upon silly tb_info trick to determine import
error status.

.. change::
:tags: engines
:tickets:

added first() method to ResultProxy, returns first row and
closes result set immediately.

.. change::
:tags: engines
:tickets:

RowProxy objects are now pickleable, i.e. the object returned
by result.fetchone(), result.fetchall() etc.

.. change::
:tags: engines
:tickets:

RowProxy no longer has a close() method, as the row no longer
maintains a reference to the parent.  Call close() on
the parent ResultProxy instead, or use autoclose.

.. change::
:tags: engines
:tickets: 1586

ResultProxy internals have been overhauled to greatly reduce
method call counts when fetching columns.  Can provide a large
speed improvement (up to more than 100%) when fetching large
result sets.  The improvement is larger when fetching columns
that have no type-level processing applied and when using
results as tuples (instead of as dictionaries).  Many
thanks to Elixir's Gaëtan de Menten for this dramatic
improvement !

.. change::
:tags: engines
:tickets:

Databases which rely upon postfetch of "last inserted id"
to get at a generated sequence value (i.e. MySQL, MS-SQL)
now work correctly when there is a composite primary key
where the "autoincrement" column is not the first primary
key column in the table.

.. change::
:tags: engines
:tickets:

the last_inserted_ids() method has been renamed to the
descriptor "inserted_primary_key".

.. change::
:tags: engines
:tickets: 1554

setting echo=False on create_engine() now sets the loglevel
to WARN instead of NOTSET.  This so that logging can be
disabled for a particular engine even if logging
for "sqlalchemy.engine" is enabled overall.  Note that the
default setting of "echo" is `None`.

.. change::
:tags: engines
:tickets:

ConnectionProxy now has wrapper methods for all transaction
lifecycle events, including begin(), rollback(), commit()
begin_nested(), begin_prepared(), prepare(), release_savepoint(),
etc.

.. change::
:tags: engines
:tickets:

Connection pool logging now uses both INFO and DEBUG
log levels for logging.  INFO is for major events such
as invalidated connections, DEBUG for all the acquire/return
logging.  `echo_pool` can be False, None, True or "debug"
the same way as `echo` works.

.. change::
:tags: engines
:tickets: 1621

All pyodbc-dialects now support extra pyodbc-specific
kw arguments 'ansi', 'unicode_results', 'autocommit'.

.. change::
:tags: engines
:tickets:

the "threadlocal" engine has been rewritten and simplified
and now supports SAVEPOINT operations.

.. change::
:tags: engines
:tickets:

deprecated or removed
* result.last_inserted_ids() is deprecated.  Use
result.inserted_primary_key
* dialect.get_default_schema_name(connection) is now
public via dialect.default_schema_name.
* the "connection" argument from engine.transaction() and
engine.run_callable() is removed - Connection itself
now has those methods.   All four methods accept
\*args and \**kwargs which are passed to the given callable,
as well as the operating connection.

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

the `__contains__()` method of `MetaData` now accepts
strings or `Table` objects as arguments.  If given
a `Table`, the argument is converted to `table.key` first,
i.e. "[schemaname.]<tablename>"

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

deprecated MetaData.connect() and
ThreadLocalMetaData.connect() have been removed - send
the "bind" attribute to bind a metadata.

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

deprecated metadata.table_iterator() method removed (use
sorted_tables)

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

deprecated PassiveDefault - use DefaultClause.

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

the "metadata" argument is removed from DefaultGenerator
and subclasses, but remains locally present on Sequence,
which is a standalone construct in DDL.

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

Removed public mutability from Index and Constraint
objects:

* ForeignKeyConstraint.append_element()
* Index.append_column()
* UniqueConstraint.append_column()
* PrimaryKeyConstraint.add()
* PrimaryKeyConstraint.remove()

These should be constructed declaratively (i.e. in one
construction).

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

The "start" and "increment" attributes on Sequence now
generate "START WITH" and "INCREMENT BY" by default,
on Oracle and PostgreSQL.  Firebird doesn't support
these keywords right now.

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

UniqueConstraint, Index, PrimaryKeyConstraint all accept
lists of column names or column objects as arguments.

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

Other removed things:
- Table.key (no idea what this was for)
- Table.primary_key is not assignable - use
table.append_constraint(PrimaryKeyConstraint(...))
- Column.bind       (get via column.table.bind)
- Column.metadata   (get via column.table.metadata)
- Column.sequence   (use column.default)
- ForeignKey(constraint=some_parent) (is now private _constraint)

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

The use_alter flag on ForeignKey is now a shortcut option
for operations that can be hand-constructed using the
DDL() event system. A side effect of this refactor is
that ForeignKeyConstraint objects with use_alter=True
will *not* be emitted on SQLite, which does not support
ALTER for foreign keys.

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

ForeignKey and ForeignKeyConstraint objects now correctly
copy() all their public keyword arguments.

.. change::
:tags: reflection/inspection
:tickets:

Table reflection has been expanded and generalized into
a new API called "sqlalchemy.engine.reflection.Inspector".
The Inspector object provides fine-grained information about
a wide variety of schema information, with room for expansion,
including table names, column names, view definitions, sequences,
indexes, etc.

.. change::
:tags: reflection/inspection
:tickets:

Views are now reflectable as ordinary Table objects.  The same
Table constructor is used, with the caveat that "effective"
primary and foreign key constraints aren't part of the reflection
results; these have to be specified explicitly if desired.

.. change::
:tags: reflection/inspection
:tickets:

The existing autoload=True system now uses Inspector underneath
so that each dialect need only return "raw" data about tables
and other objects - Inspector is the single place that information
is compiled into Table objects so that consistency is at a maximum.

.. change::
:tags: ddl
:tickets:

the DDL system has been greatly expanded.  the DDL() class
now extends the more generic DDLElement(), which forms the basis
of many new constructs:

- CreateTable()
- DropTable()
- AddConstraint()
- DropConstraint()
- CreateIndex()
- DropIndex()
- CreateSequence()
- DropSequence()

These support "on" and "execute-at()" just like plain DDL()
does.  User-defined DDLElement subclasses can be created and
linked to a compiler using the sqlalchemy.ext.compiler extension.

.. change::
:tags: ddl
:tickets:

The signature of the "on" callable passed to DDL() and
DDLElement() is revised as follows:

ddl
the DDLElement object itself
event
the string event name.
target
previously "schema_item", the Table or MetaData object triggering the event.
connection
the Connection object in use for the operation.
\**kw
keyword arguments.  In the case of MetaData before/after
create/drop, the list of Table objects for which
CREATE/DROP DDL is to be issued is passed as the kw
argument "tables". This is necessary for metadata-level
DDL that is dependent on the presence of specific tables.

The "schema_item" attribute of DDL has been renamed to
"target".

.. change::
:tags: dialect, refactor
:tickets:

Dialect modules are now broken into database dialects
plus DBAPI implementations. Connect URLs are now
preferred to be specified using dialect+driver://...,
i.e. "mysql+mysqldb://scott:tigerlocalhost/test". See
the 0.6 documentation for examples.

.. change::
:tags: dialect, refactor
:tickets:

the setuptools entrypoint for external dialects is now
called "sqlalchemy.dialects".

.. change::
:tags: dialect, refactor
:tickets:

the "owner" keyword argument is removed from Table. Use
"schema" to represent any namespaces to be prepended to
the table name.

.. change::
:tags: dialect, refactor
:tickets:

server_version_info becomes a static attribute.

.. change::
:tags: dialect, refactor
:tickets:

dialects receive an initialize() event on initial
connection to determine connection properties.

.. change::
:tags: dialect, refactor
:tickets:

dialects receive a visit_pool event have an opportunity
to establish pool listeners.

.. change::
:tags: dialect, refactor
:tickets:

cached TypeEngine classes are cached per-dialect class
instead of per-dialect.

.. change::
:tags: dialect, refactor
:tickets:

new UserDefinedType should be used as a base class for
new types, which preserves the 0.5 behavior of
get_col_spec().

.. change::
:tags: dialect, refactor
:tickets:

The result_processor() method of all type classes now
accepts a second argument "coltype", which is the DBAPI
type argument from cursor.description.  This argument
can help some types decide on the most efficient processing
of result values.

.. change::
:tags: dialect, refactor
:tickets:

Deprecated Dialect.get_params() removed.

.. change::
:tags: dialect, refactor
:tickets:

Dialect.get_rowcount() has been renamed to a descriptor
"rowcount", and calls cursor.rowcount directly. Dialects
which need to hardwire a rowcount in for certain calls
should override the method to provide different behavior.

.. change::
:tags: dialect, refactor
:tickets: 1566

DefaultRunner and subclasses have been removed.  The job
of this object has been simplified and moved into
ExecutionContext.  Dialects which support sequences should
add a `fire_sequence()` method to their execution context
implementation.

.. change::
:tags: dialect, refactor
:tickets:

Functions and operators generated by the compiler now use
(almost) regular dispatch functions of the form
"visit_<opname>" and "visit_<funcname>_fn" to provide
customed processing. This replaces the need to copy the
"functions" and "operators" dictionaries in compiler
subclasses with straightforward visitor methods, and also
allows compiler subclasses complete control over
rendering, as the full _Function or _BinaryExpression
object is passed in.

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

New dialects: pg8000, zxjdbc, and pypostgresql
on py3k.

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

The "postgres" dialect is now named "postgresql" !
Connection strings look like:

postgresql://scott:tigerlocalhost/test
postgresql+pg8000://scott:tigerlocalhost/test

The "postgres" name remains for backwards compatibility
in the following ways:

- There is a "postgres.py" dummy dialect which
allows old URLs to work, i.e.
postgres://scott:tigerlocalhost/test

- The "postgres" name can be imported from the old
"databases" module, i.e. "from
sqlalchemy.databases import postgres" as well as
"dialects", "from sqlalchemy.dialects.postgres
import base as pg", will send a deprecation
warning.

- Special expression arguments are now named
"postgresql_returning" and "postgresql_where", but
the older "postgres_returning" and
"postgres_where" names still work with a
deprecation warning.

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

"postgresql_where" now accepts SQL expressions which
can also include literals, which will be quoted as needed.

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

The psycopg2 dialect now uses psycopg2's "unicode extension"
on all new connections, which allows all String/Text/etc.
types to skip the need to post-process bytestrings into
unicode (an expensive step due to its volume).  Other
dialects which return unicode natively (pg8000, zxjdbc)
also skip unicode post-processing.

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

Added new ENUM type, which exists as a schema-level
construct and extends the generic Enum type.  Automatically
associates itself with tables and their parent metadata
to issue the appropriate CREATE TYPE/DROP TYPE
commands as needed, supports unicode labels, supports
reflection.

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

INTERVAL supports an optional "precision" argument
corresponding to the argument that PG accepts.

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

using new dialect.initialize() feature to set up
version-dependent behavior.

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

somewhat better support for % signs in table/column names;
psycopg2 can't handle a bind parameter name of
%(foobar)s however and SQLA doesn't want to add overhead
just to treat that one non-existent use case.

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

Inserting NULL into a primary key + foreign key column
will allow the "not null constraint" error to raise,
not an attempt to execute a nonexistent "col_id_seq"
sequence.

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

autoincrement SELECT statements, i.e. those which
select from a procedure that modifies rows, now work
with server-side cursor mode (the named cursor isn't
used for such statements.)

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

postgresql dialect can properly detect pg "devel" version
strings, i.e. "8.5devel"

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

The psycopg2 now respects the statement option
"stream_results". This option overrides the connection setting
"server_side_cursors". If true, server side cursors will be
used for the statement. If false, they will not be used, even
if "server_side_cursors" is true on the
connection.

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

New dialects: oursql, a new native dialect,
MySQL Connector/Python, a native Python port of MySQLdb,
and of course zxjdbc on Jython.

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

VARCHAR/NVARCHAR will not render without a length, raises
an error before passing to MySQL.   Doesn't impact
CAST since VARCHAR is not allowed in MySQL CAST anyway,
the dialect renders CHAR/NCHAR in those cases.

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

all the _detect_XXX() functions now run once underneath
dialect.initialize()

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

somewhat better support for % signs in table/column names;
MySQLdb can't handle % signs in SQL when executemany() is used,
and SQLA doesn't want to add overhead just to treat that one
non-existent use case.

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

the BINARY and MSBinary types now generate "BINARY" in all
cases.  Omitting the "length" parameter will generate
"BINARY" with no length.  Use BLOB to generate an unlengthed
binary column.

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

the "quoting='quoted'" argument to MSEnum/ENUM is deprecated.
It's best to rely upon the automatic quoting.

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

ENUM now subclasses the new generic Enum type, and also handles
unicode values implicitly, if the given labelnames are unicode
objects.

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

a column of type TIMESTAMP now defaults to NULL if
"nullable=False" is not passed to Column(), and no default
is present. This is now consistent with all other types,
and in the case of TIMESTAMP explicitly renders "NULL"
due to MySQL's "switching" of default nullability
for TIMESTAMP columns.

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

unit tests pass 100% with cx_oracle !

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

support for cx_Oracle's "native unicode" mode which does
not require NLS_LANG to be set. Use the latest 5.0.2 or
later of cx_oracle.

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

an NCLOB type is added to the base types.

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

use_ansi=False won't leak into the FROM/WHERE clause of
a statement that's selecting from a subquery that also
uses JOIN/OUTERJOIN.

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

added native INTERVAL type to the dialect.  This supports
only the DAY TO SECOND interval type so far due to lack
of support in cx_oracle for YEAR TO MONTH.

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

usage of the CHAR type results in cx_oracle's
FIXED_CHAR dbapi type being bound to statements.

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

the Oracle dialect now features NUMBER which intends
to act justlike Oracle's NUMBER type.  It is the primary
numeric type returned by table reflection and attempts
to return Decimal()/float/int based on the precision/scale
parameters.

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

func.char_length is a generic function for LENGTH

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

ForeignKey() which includes onupdate=<value> will emit a
warning, not emit ON UPDATE CASCADE which is unsupported
by oracle

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

the keys() method of RowProxy() now returns the result
column names *normalized* to be SQLAlchemy case
insensitive names. This means they will be lower case for
case insensitive names, whereas the DBAPI would normally
return them as UPPERCASE names. This allows row keys() to
be compatible with further SQLAlchemy operations.

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

using new dialect.initialize() feature to set up
version-dependent behavior.

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

using types.BigInteger with Oracle will generate
NUMBER(19)

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

"case sensitivity" feature will detect an all-lowercase
case-sensitive column name during reflect and add
"quote=True" to the generated Column, so that proper
quoting is maintained.

.. change::
:tags: firebird
:tickets:

the keys() method of RowProxy() now returns the result
column names *normalized* to be SQLAlchemy case
insensitive names. This means they will be lower case for
case insensitive names, whereas the DBAPI would normally
return them as UPPERCASE names. This allows row keys() to
be compatible with further SQLAlchemy operations.

.. change::
:tags: firebird
:tickets:

using new dialect.initialize() feature to set up
version-dependent behavior.

.. change::
:tags: firebird
:tickets:

"case sensitivity" feature will detect an all-lowercase
case-sensitive column name during reflect and add
"quote=True" to the generated Column, so that proper
quoting is maintained.

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

MSSQL + Pyodbc + FreeTDS now works for the most part,
with possible exceptions regarding binary data as well as
unicode schema identifiers.

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

the "has_window_funcs" flag is removed. LIMIT/OFFSET
usage will use ROW NUMBER as always, and if on an older
version of SQL Server, the operation fails. The behavior
is exactly the same except the error is raised by SQL
server instead of the dialect, and no flag setting is
required to enable it.

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

the "auto_identity_insert" flag is removed. This feature
always takes effect when an INSERT statement overrides a
column that is known to have a sequence on it. As with
"has_window_funcs", if the underlying driver doesn't
support this, then you can't do this operation in any
case, so there's no point in having a flag.

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

using new dialect.initialize() feature to set up
version-dependent behavior.

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

removed references to sequence which is no longer used.
implicit identities in mssql work the same as implicit
sequences on any other dialects. Explicit sequences are
enabled through the use of "default=Sequence()". See
the MSSQL dialect documentation for more information.

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

DATE, TIME and DATETIME types can now take optional storage_format
and regexp argument. storage_format can be used to store those types
using a custom string format. regexp allows to use a custom regular
expression to match string values from the database.

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

Time and DateTime types now use by a default a stricter regular
expression to match strings from the database. Use the regexp
argument if you are using data stored in a legacy format.

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

__legacy_microseconds__ on SQLite Time and DateTime types is not
supported anymore. You should use the storage_format argument
instead.

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

Date, Time and DateTime types are now stricter in what they accept as
bind parameters: Date type only accepts date objects (and datetime
ones, because they inherit from date), Time only accepts time
objects, and DateTime only accepts date and datetime objects.

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

Table() supports a keyword argument "sqlite_autoincrement", which
applies the SQLite keyword "AUTOINCREMENT" to the single integer
primary key column when generating DDL. Will prevent generation of
a separate PRIMARY KEY constraint.

.. change::
:tags: types
:tickets:

The construction of types within dialects has been totally
overhauled.  Dialects now define publicly available types
as UPPERCASE names exclusively, and internal implementation
types using underscore identifiers (i.e. are private).
The system by which types are expressed in SQL and DDL
has been moved to the compiler system.  This has the
effect that there are much fewer type objects within
most dialects. A detailed document on this architecture
for dialect authors is in
lib/sqlalchemy/dialects/type_migration_guidelines.txt .

.. change::
:tags: types
:tickets:

Types no longer make any guesses as to default
parameters. In particular, Numeric, Float, NUMERIC,
FLOAT, DECIMAL don't generate any length or scale unless
specified.

.. change::
:tags: types
:tickets: 1664

types.Binary is renamed to types.LargeBinary, it only
produces BLOB, BYTEA, or a similar "long binary" type.
New base BINARY and VARBINARY
types have been added to access these MySQL/MS-SQL specific
types in an agnostic way.

.. change::
:tags: types
:tickets:

String/Text/Unicode types now skip the unicode() check
on each result column value if the dialect has
detected the DBAPI as returning Python unicode objects
natively.  This check is issued on first connect
using "SELECT CAST 'some text' AS VARCHAR(10)" or
equivalent, then checking if the returned object
is a Python unicode.   This allows vast performance
increases for native-unicode DBAPIs, including
pysqlite/sqlite3, psycopg2, and pg8000.

.. change::
:tags: types
:tickets:

Most types result processors have been checked for possible speed
improvements. Specifically, the following generic types have been
optimized, resulting in varying speed improvements:
Unicode, PickleType, Interval, TypeDecorator, Binary.
Also the following dbapi-specific implementations have been improved:
Time, Date and DateTime on Sqlite, ARRAY on PostgreSQL,
Time on MySQL, Numeric(as_decimal=False) on MySQL, oursql and
pypostgresql, DateTime on cx_oracle and LOB-based types on cx_oracle.

.. change::
:tags: types
:tickets:

Reflection of types now returns the exact UPPERCASE
type within types.py, or the UPPERCASE type within
the dialect itself if the type is not a standard SQL
type.  This means reflection now returns more accurate
information about reflected types.

.. change::
:tags: types
:tickets: 1511, 1109

Added a new Enum generic type. Enum is a schema-aware object
to support databases which require specific DDL in order to
use enum or equivalent; in the case of PG it handles the
details of `CREATE TYPE`, and on other databases without
native enum support will by generate VARCHAR + an inline CHECK
constraint to enforce the enum.

.. change::
:tags: types
:tickets: 1467

The Interval type includes a "native" flag which controls
if native INTERVAL types (postgresql + oracle) are selected
if available, or not.  "day_precision" and "second_precision"
arguments are also added which propagate as appropriately
to these native types. Related to.

.. change::
:tags: types
:tickets: 1589

The Boolean type, when used on a backend that doesn't
have native boolean support, will generate a CHECK
constraint "col IN (0, 1)" along with the int/smallint-
based column type.  This can be switched off if
desired with create_constraint=False.
Note that MySQL has no native boolean *or* CHECK constraint
support so this feature isn't available on that platform.

.. change::
:tags: types
:tickets:

PickleType now uses == for comparison of values when
mutable=True, unless the "comparator" argument with a
comparison function is specified to the type. Objects
being pickled will be compared based on identity (which
defeats the purpose of mutable=True) if __eq__() is not
overridden or a comparison function is not provided.

.. change::
:tags: types
:tickets:

The default "precision" and "scale" arguments of Numeric
and Float have been removed and now default to None.
NUMERIC and FLOAT will be rendered with no numeric
arguments by default unless these values are provided.

.. change::
:tags: types
:tickets:

AbstractType.get_search_list() is removed - the games
that was used for are no longer necessary.

.. change::
:tags: types
:tickets: 1125

Added a generic BigInteger type, compiles to
BIGINT or NUMBER(19).

.. change::
:tags: types
:tickets:

sqlsoup has been overhauled to explicitly support an 0.5 style
session, using autocommit=False, autoflush=True. Default
behavior of SQLSoup now requires the usual usage of commit()
and rollback(), which have been added to its interface. An
explicit Session or scoped_session can be passed to the
constructor, allowing these arguments to be overridden.

.. change::
:tags: types
:tickets:

sqlsoup db.<sometable>.update() and delete() now call
query(cls).update() and delete(), respectively.

.. change::
:tags: types
:tickets:

sqlsoup now has execute() and connection(), which call upon
the Session methods of those names, ensuring that the bind is
in terms of the SqlSoup object's bind.

.. change::
:tags: types
:tickets:

sqlsoup objects no longer have the 'query' attribute - it's
not needed for sqlsoup's usage paradigm and it gets in the
way of a column that is actually named 'query'.

.. change::
:tags: types
:tickets: 1259

The signature of the proxy_factory callable passed to
association_proxy is now (lazy_collection, creator,
value_attr, association_proxy), adding a fourth argument
that is the parent AssociationProxy argument.  Allows
serializability and subclassing of the built in collections.

.. change::
:tags: types
:tickets: 1372

association_proxy now has basic comparator methods .any(),
.has(), .contains(), ==, !=, thanks to Scott Torborg.



=============
0.7 Changelog
=============

.. changelog::
:version: 0.7.11

.. change::
:tags: bug, engine
:tickets: 2851
:versions: 0.8.3, 0.9.0b1

The regexp used by the :func:`~sqlalchemy.engine.url.make_url` function now parses
ipv6 addresses, e.g. surrounded by brackets.

.. change::
:tags: bug, orm
:tickets: 2807
:versions: 0.8.3, 0.9.0b1

Fixed bug where list instrumentation would fail to represent a
setslice of ``[0:0]`` correctly, which in particular could occur
when using ``insert(0, item)`` with the association proxy.  Due
to some quirk in Python collections, the issue was much more likely
with Python 3 rather than 2.

.. change::
:tags: bug, sql
:tickets: 2801
:versions: 0.8.3, 0.9.0b1

Fixed regression dating back to 0.7.9 whereby the name of a CTE might
not be properly quoted if it was referred to in multiple FROM clauses.

.. change::
:tags: mysql, bug
:tickets: 2791
:versions: 0.8.3, 0.9.0b1

Updates to MySQL reserved words for versions 5.5, 5.6, courtesy
Hanno Schlichting.

.. change::
:tags: sql, bug, cte
:tickets: 2783
:versions: 0.8.3, 0.9.0b1

Fixed bug in common table expression system where if the CTE were
used only as an ``alias()`` construct, it would not render using the
WITH keyword.

.. change::
:tags: bug, sql
:tickets: 2784
:versions: 0.8.3, 0.9.0b1

Fixed bug in :class:`.CheckConstraint` DDL where the "quote" flag from a
:class:`.Column` object would not be propagated.

.. change::
:tags: bug, orm
:tickets: 2699
:versions: 0.8.1

Fixed bug when a query of the form:
``query(SubClass).options(subqueryload(Baseclass.attrname))``,
where ``SubClass`` is a joined inh of ``BaseClass``,
would fail to apply the ``JOIN`` inside the subquery
on the attribute load, producing a cartesian product.
The populated results still tended to be correct as additional
rows are just ignored, so this issue may be present as a
performance degradation in applications that are
otherwise working correctly.

.. change::
:tags: bug, orm
:tickets: 2689
:versions: 0.8.1

Fixed bug in unit of work whereby a joined-inheritance
subclass could insert the row for the "sub" table
before the parent table, if the two tables had no
ForeignKey constraints set up between them.

.. change::
:tags: feature, postgresql
:tickets: 2676
:versions: 0.8.0

Added support for PostgreSQL's traditional SUBSTRING
function syntax, renders as "SUBSTRING(x FROM y FOR z)"
when regular ``func.substring()`` is used.
Courtesy Gunnlaugur Þór Briem.

.. change::
:tags: bug, tests
:tickets: 2669
:pullreq: 41

Fixed an import of "logging" in test_execute which was not
working on some linux platforms.

.. change::
:tags: bug, orm
:tickets: 2674

Improved the error message emitted when a "backref loop" is detected,
that is when an attribute event triggers a bidirectional
assignment between two other attributes with no end.
This condition can occur not just when an object of the wrong
type is assigned, but also when an attribute is mis-configured
to backref into an existing backref pair.

.. change::
:tags: bug, orm
:tickets: 2674

A warning is emitted when a MapperProperty is assigned to a mapper
that replaces an existing property, if the properties in question
aren't plain column-based properties.   Replacement of relationship
properties is rarely (ever?) what is intended and usually refers to a
mapper mis-configuration.   This will also warn if a backref configures
itself on top of an existing one in an inheritance relationship
(which is an error in 0.8).

.. changelog::

0.5.8

:released: Sat Jan 16 2010

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

The copy() method on Column now supports uninitialized,
unnamed Column objects. This allows easy creation of
declarative helpers which place common columns on multiple
subclasses.

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

Default generators like Sequence() translate correctly
across a copy() operation.

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

Sequence() and other DefaultGenerator objects are accepted
as the value for the "default" and "onupdate" keyword
arguments of Column, in addition to being accepted
positionally.

.. change::
:tags: sql
:tickets: 1568, 1617

Fixed a column arithmetic bug that affected column
correspondence for cloned selectables which contain
free-standing column expressions.   This bug is
generally only noticeable when exercising newer
ORM behavior only available in 0.6 via,
but is more correct at the SQL expression level
as well.

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

The extract() function, which was slightly improved in
0.5.7, needed a lot more work to generate the correct
typecast (the typecasts appear to be necessary in PG's
EXTRACT quite a lot of the time).  The typecast is
now generated using a rule dictionary based
on PG's documentation for date/time/interval arithmetic.
It also accepts text() constructs again, which was broken
in 0.5.7.

.. change::
:tags: firebird
:tickets: 1646

Recognize more errors as disconnections.

.. changelog::

0.5.7

:released: Sat Dec 26 2009

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

contains_eager() now works with the automatically
generated subquery that results when you say
"query(Parent).join(Parent.somejoinedsubclass)", i.e.
when Parent joins to a joined-table-inheritance subclass.
Previously contains_eager() would erroneously add the
subclass table to the query separately producing a
cartesian product.  An example is in the ticket
description.

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

query.options() now only propagate to loaded objects
for potential further sub-loads only for options where
such behavior is relevant, keeping
various unserializable options like those generated
by contains_eager() out of individual instance states.

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

Session.execute() now locates table- and
mapper-specific binds based on a passed
in expression which is an insert()/update()/delete()
construct.

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

Session.merge() now properly overwrites a many-to-one or
uselist=False attribute to None if the attribute
is also None in the given object to be merged.

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

Fixed a needless select which would occur when merging
transient objects that contained a null primary key
identifier.

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

Mutable collection passed to the "extension" attribute
of relation(), column_property() etc. will not be mutated
or shared among multiple instrumentation calls, preventing
duplicate extensions, such as backref populators,
from being inserted into the list.

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

Fixed the call to get_committed_value() on CompositeProperty.

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

Fixed bug where Query would crash if a join() with no clear
"left" side were called when a non-mapped column entity
appeared in the columns list.

.. change::
:tags: orm
:tickets: 1616, 1480

Fixed bug whereby composite columns wouldn't load properly
when configured on a joined-table subclass, introduced in
version 0.5.6 as a result of the fix for. thx to Scott Torborg.

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

The "use get" behavior of many-to-one relations, i.e. that a
lazy load will fallback to the possibly cached query.get()
value, now works across join conditions where the two compared
types are not exactly the same class, but share the same
"affinity" - i.e. Integer and SmallInteger.  Also allows
combinations of reflected and non-reflected types to work
with 0.5 style type reflection, such as PGText/Text (note 0.6
reflects types as their generic versions).

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

Fixed bug in query.update() when passing Cls.attribute
as keys in the value dict and using synchronize_session='expire'
('fetch' in 0.6).

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

Fixed bug in two-phase transaction whereby commit() method
didn't set the full state which allows subsequent close()
call to succeed.

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

Fixed the "numeric" paramstyle, which apparently is the
default paramstyle used by Informixdb.

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

Repeat expressions in the columns clause of a select
are deduped based on the identity of each clause element,
not the actual string.  This allows positional
elements to render correctly even if they all render
identically, such as "qmark" style bind parameters.

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

The cursor associated with connection pool connections
(i.e. _CursorFairy) now proxies `__iter__()` to the
underlying cursor correctly.

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

types now support an "affinity comparison" operation, i.e.
that an Integer/SmallInteger are "compatible", or
a Text/String, PickleType/Binary, etc.  Part of.

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

Fixed bug preventing alias() of an alias() from being
cloned or adapted (occurs frequently in ORM operations).

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

sqlite dialect properly generates CREATE INDEX for a table
that is in an alternate schema.

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

Added support for reflecting the DOUBLE PRECISION type,
via a new postgres.PGDoublePrecision object.
This is postgresql.DOUBLE_PRECISION in 0.6.

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

Added support for reflecting the INTERVAL YEAR TO MONTH
and INTERVAL DAY TO SECOND syntaxes of the INTERVAL
type.

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

Corrected the "has_sequence" query to take current schema,
or explicit sequence-stated schema, into account.

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

Fixed the behavior of extract() to apply operator
precedence rules to the "::" operator when applying
the "timestamp" cast - ensures proper parenthesization.

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

Changed the name of TrustedConnection to
Trusted_Connection when constructing pyodbc connect
arguments

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

The "table_names" dialect function, used by MetaData
.reflect(), omits "index overflow tables", a system
table generated by Oracle when "index only tables"
with overflow are used.  These tables aren't accessible
via SQL and can't be reflected.

.. change::
:tags: ext
:tickets: 1570, 1523

A column can be added to a joined-table declarative
superclass after the class has been constructed
(i.e. via class-level attribute assignment), and
the column will be propagated down to
subclasses.  This is the reverse
situation as that of, fixed in 0.5.6.

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

Fixed a slight inaccuracy in the sharding example.
Comparing equivalence of columns in the ORM is best
accomplished using col1.shares_lineage(col2).

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

Removed unused `load()` method from ShardedQuery.

.. changelog::

0.5.6

:released: Sat Sep 12 2009

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

Fixed bug whereby inheritance discriminator part of a
composite primary key would fail on updates.
Continuation of.

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

Fixed bug which disallowed one side of a many-to-many
bidirectional reference to declare itself as "viewonly"

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

Added an assertion that prevents a validates function
or other AttributeExtension from loading an unloaded
collection such that internal state may be corrupted.

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

Fixed bug which prevented two entities from mutually
replacing each other's primary key values within a single
flush() for some orderings of operations.

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

Fixed an obscure issue whereby a joined-table subclass
with a self-referential eager load on the base class
would populate the related object's "subclass" table with
data from the "subclass" table of the parent.

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

relations() now have greater ability to be "overridden",
meaning a subclass that explicitly specifies a relation()
overriding that of the parent class will be honored
during a flush.  This is currently to support
many-to-many relations from concrete inheritance setups.
Outside of that use case, YMMV.

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

Squeezed a few more unnecessary "lazy loads" out of
relation().  When a collection is mutated, many-to-one
backrefs on the other side will not fire off to load
the "old" value, unless "single_parent=True" is set.
A direct assignment of a many-to-one still loads
the "old" value in order to update backref collections
on that value, which may be present in the session
already, thus maintaining the 0.5 behavioral contract.

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

Fixed bug whereby a load/refresh of joined table
inheritance attributes which were based on
column_property() or similar would fail to evaluate.

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

Improved support for MapperProperty objects overriding
that of an inherited mapper for non-concrete
inheritance setups - attribute extensions won't randomly
collide with each other.

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

UPDATE and DELETE do not support ORDER BY, LIMIT, OFFSET,
etc. in standard SQL.  Query.update() and Query.delete()
now raise an exception if any of limit(), offset(),
order_by(), group_by(), or distinct() have been
called.

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

Added AttributeExtension to sqlalchemy.orm.__all__

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

Improved error message when query() is called with
a non-SQL /entity expression.

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

Using False or 0 as a polymorphic discriminator now
works on the base class as well as a subclass.

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

Added enable_assertions(False) to Query which disables
the usual assertions for expected state - used
by Query subclasses to engineer custom state..  See
http://www.sqlalchemy.org/trac/wiki/UsageRecipes/PreFilteredQuery
for an example.

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

Fixed recursion issue which occurred if a mapped object's
`__len__()` or `__nonzero__()` method resulted in state
changes.

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

Fixed incorrect exception raise in
Weak/StrongIdentityMap.add()

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

Fixed the error message for "could not find a FROM clause"
in query.join() which would fail to issue correctly
if the query was against a pure SQL construct.

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

Fixed a somewhat hypothetical issue which would result
in the wrong primary key being calculated for a mapper
using the old polymorphic_union function - but this
is old stuff.

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

Fixed column.copy() to copy defaults and onupdates.

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

Fixed a bug in extract() introduced in 0.5.4 whereby
the string "field" argument was getting treated as a
ClauseElement, causing various errors within more
complex SQL transformations.

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

Unary expressions such as DISTINCT propagate their
type handling to result sets, allowing conversions like
unicode and such to take place.

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

Fixed bug in Table and Column whereby passing empty
dict for "info" argument would raise an exception.

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

Backported 0.6 fix for Oracle alias names not getting
truncated.

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

The collection proxies produced by associationproxy are now
pickleable.  A user-defined proxy_factory however
is still not pickleable unless it defines __getstate__
and __setstate__.

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

Declarative will raise an informative exception if
__table_args__ is passed as a tuple with no dict argument.
Improved documentation.

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

Table objects declared in the MetaData can now be used
in string expressions sent to primaryjoin/secondaryjoin/
secondary - the name is pulled from the MetaData of the
declarative base.

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

A column can be added to a joined-table subclass after
the class has been constructed (i.e. via class-level
attribute assignment).  The column is added to the underlying
Table as always, but now the mapper will rebuild its
"join" to include the new column, instead of raising
an error about "no such column, use column_property()
instead".

.. change::
:tags: test
:tickets:

Added examples into the test suite so they get exercised
regularly and cleaned up a couple deprecation warnings.

.. changelog::

0.5.5

:released: Mon Jul 13 2009

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

unit tests have been migrated from unittest to nose.  See
README.unittests for information on how to run the tests.

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

The "foreign_keys" argument of relation() will now propagate
automatically to the backref in the same way that primaryjoin
and secondaryjoin do.  For the extremely rare use case where
the backref of a relation() has intentionally different
"foreign_keys" configured, both sides now need to be
configured explicitly (if they do in fact require this setting,
see the next note...).

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

...the only known (and really, really rare) use case where a
different foreign_keys setting was used on the
forwards/backwards side, a composite foreign key that
partially points to its own columns, has been enhanced such
that the fk->itself aspect of the relation won't be used to
determine relation direction.

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

Session.mapper is now *deprecated*.

Call session.add() if you'd like a free-standing object to be
part of your session.  Otherwise, a DIY version of
Session.mapper is now documented at
http://www.sqlalchemy.org/trac/wiki/UsageRecipes/SessionAwareMapper
The method will remain deprecated throughout 0.6.

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

Fixed Query being able to join() from individual columns of a
joined-table subclass entity, i.e.  query(SubClass.foo,
SubClass.bar).join(<anything>).  In most cases, an error
"Could not find a FROM clause to join from" would be
raised. In a few others, the result would be returned in terms
of the base class rather than the subclass - so applications
which relied on this erroneous result need to be
adjusted.

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

Fixed a bug involving contains_eager(), which would apply
itself to a secondary (i.e. lazy) load in a particular rare
case, producing cartesian products.  improved the targeting of
query.options() on secondary loads overall.

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

Fixed bug introduced in 0.5.4 whereby Composite types fail
when default-holding columns are flushed.

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

Fixed another 0.5.4 bug whereby mutable attributes
(i.e. PickleType) wouldn't be deserialized correctly when the
whole object was serialized.

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

Fixed bug whereby session.is_modified() would raise an
exception if any synonyms were in use.

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

Fixed potential memory leak whereby previously pickled objects
placed back in a session would not be fully garbage collected
unless the Session were explicitly closed out.

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

Fixed bug whereby list-based attributes, like pickletype and
PGArray, failed to be merged() properly.

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

Repaired non-working attributes.set_committed_value function.

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

Trimmed the pickle format for InstanceState which should
further reduce the memory footprint of pickled instances.  The
format should be backwards compatible with that of 0.5.4 and
previous.

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

sqlalchemy.orm.join and sqlalchemy.orm.outerjoin are now
added to __all__ in sqlalchemy.orm.*.

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

Fixed bug where Query exception raise would fail when
a too-short composite primary key value were passed to
get().

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

Removed an obscure feature of execute() (including connection,
engine, Session) whereby a bindparam() construct can be sent
as a key to the params dictionary.  This usage is undocumented
and is at the core of an issue whereby the bindparam() object
created implicitly by a text() construct may have the same
hash value as a string placed in the params dictionary and may
result in an inappropriate match when computing the final bind
parameters.  Internal checks for this condition would add
significant latency to the critical task of parameter
rendering, so the behavior is removed.  This is a backwards
incompatible change for any application that may have been
using this feature, however the feature has never been
documented.

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

Implemented recreate() for StaticPool.

.. changelog::
:version: 0.5.4p2
:released: Tue May 26 2009

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

Repaired the printing of SQL exceptions which are not
based on parameters or are not executemany() style.

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

Deprecated the hardcoded TIMESTAMP function, which when
used as func.TIMESTAMP(value) would render "TIMESTAMP value".
This breaks on some platforms as PostgreSQL doesn't allow
bind parameters to be used in this context.  The hard-coded
uppercase is also inappropriate and there's lots of other
PG casts that we'd need to support.  So instead, use
text constructs i.e. select(["timestamp '12/05/09'"]).

.. changelog::
:version: 0.5.4p1
:released: Mon May 18 2009

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

Fixed an attribute error introduced in 0.5.4 which would
occur when merge() was used with an incomplete object.

.. changelog::

0.5.4

: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::

0.5.3

: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::

0.5.2

: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::

0.5.1

: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::

0.5.0

: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::

0.5.0rc4

: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::

0.5.0rc3

:released: Fri Nov 07 2008

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

Added two new hooks to SessionExtension: after_bulk_delete()
and after_bulk_update().  after_bulk_delete() is called after
a bulk delete() operation on a query. after_bulk_update() is
called after a bulk update() operation on a query.

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

SQL compiler optimizations and complexity reduction. The call
count for compiling a typical select() construct is 20% less
versus 0.5.0rc2.

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

Dialects can now generate label names of adjustable
length. Pass in the argument "label_length=<value>" to
create_engine() to adjust how many characters max will be
present in dynamically generated column labels, i.e.
"somecolumn AS somelabel". Any value less than 6 will result
in a label of minimal size, consisting of an underscore and a
numeric counter. The compiler uses the value of
dialect.max_identifier_length as a default.

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

Added a new extension sqlalchemy.ext.serializer.  Provides
Serializer/Deserializer "classes" which mirror
Pickle/Unpickle, as well as dumps() and loads(). This
serializer implements an "external object" pickler which keeps
key context-sensitive objects, including engines, sessions,
metadata, Tables/Columns, and mappers, outside of the pickle
stream, and can later restore the pickle using any
engine/metadata/session provider. This is used not for
pickling regular object instances, which are pickleable
without any special logic, but for pickling expression objects
and full Query objects, such that all mapper/engine/session
dependencies can be restored at unpickle time.

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

Wrote a docstring for Oracle dialect. Apparently that Ohloh
"few source code comments" label is starting to sting :).

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

Removed FIRST_ROWS() optimize flag when using LIMIT/OFFSET,
can be reenabled with optimize_limits=True create_engine()
flag.

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

bugfixes and behavioral changes

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

"not equals" comparisons of simple many-to-one relation to an
instance will not drop into an EXISTS clause and will compare
foreign key columns instead.

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

Removed not-really-working use cases of comparing a collection
to an iterable. Use contains() to test for collection
membership.

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

Improved the behavior of aliased() objects such that they more
accurately adapt the expressions generated, which helps
particularly with self-referential comparisons.

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

Fixed bug involving primaryjoin/secondaryjoin conditions
constructed from class-bound attributes (as often occurs when
using declarative), which later would be inappropriately
aliased by Query, particularly with the various EXISTS based
comparators.

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

Fixed bug when using multiple query.join() with an
aliased-bound descriptor which would lose the left alias.

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

Improved weakref identity map memory management to no longer
require mutexing, resurrects garbage collected instance on a
lazy basis for an InstanceState with pending changes.

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

InstanceState object now removes circular references to itself
upon disposal to keep it outside of cyclic garbage collection.

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

relation() won't hide unrelated ForeignKey errors inside of
the "please specify primaryjoin" message when determining join
condition.

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

Fixed bug in Query involving order_by() in conjunction with
multiple aliases of the same class (will add tests in)

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

When using Query.join() with an explicit clause for the ON
clause, the clause will be aliased in terms of the left side
of the join, allowing scenarios like query(Source).
from_self().join((Dest, Source.id==Dest.source_id)) to work
properly.

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

polymorphic_union() function respects the "key" of each Column
if they differ from the column's name.

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

Repaired support for "passive-deletes" on a many-to-one
relation() with "delete" cascade.

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

Fixed bug in composite types which prevented a primary-key
composite type from being mutated.

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

Added more granularity to internal attribute access, such that
cascade and flush operations will not initialize unloaded
attributes and collections, leaving them intact for a
lazy-load later on. Backref events still initialize attributes
and collections for pending instances.

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

Simplified the check for ResultProxy "autoclose without
results" to be based solely on presence of
cursor.description. All the regexp-based guessing about
statements returning rows has been removed.

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

Direct execution of a union() construct will properly set up
result-row processing.

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

The internal notion of an "OID" or "ROWID" column has been
removed. It's basically not used by any dialect, and the
possibility of its usage with psycopg2's cursor.lastrowid is
basically gone now that INSERT..RETURNING is available.

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

Removed "default_order_by()" method on all FromClause objects.

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

Repaired the table.tometadata() method so that a passed-in
schema argument is propagated to ForeignKey constructs.

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

Slightly changed behavior of IN operator for comparing to
empty collections. Now results in inequality comparison
against self. More portable, but breaks with stored procedures
that aren't pure functions.

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

Setting the auto_convert_lobs to False on create_engine() will
also instruct the OracleBinary type to return the cx_oracle
LOB object unchanged.

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

Fixed foreign key reflection in the edge case where a Table's
explicit schema= is the same as the schema (database) the
connection is attached to.

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

No longer expects include_columns in table reflection to be
lower case.

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

Fixed bug preventing declarative-bound "column" objects from
being used in column_mapped_collection().

.. change::
:tags: misc
:tickets: 1077

util.flatten_iterator() func doesn't interpret strings with
__iter__() methods as iterators, such as in pypy.

.. changelog::

0.5.0rc2

:released: Sun Oct 12 2008

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

Fixed bug involving read/write relation()s that contain
literal or other non-column expressions within their
primaryjoin condition equated to a foreign key column.

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

"non-batch" mode in mapper(), a feature which allows mapper
extension methods to be called as each instance is
updated/inserted, now honors the insert order of the objects
given.

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

Fixed RLock-related bug in mapper which could deadlock upon
reentrant mapper compile() calls, something that occurs when
using declarative constructs inside of ForeignKey objects.

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

ScopedSession.query_property now accepts a query_cls factory,
overriding the session's configured query_cls.

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

Fixed shared state bug interfering with ScopedSession.mapper's
ability to apply default __init__ implementations on object
subclasses.

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

Fixed up slices on Query (i.e. query[x:y]) to work properly
for zero length slices, slices with None on either end.

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

Added an example illustrating Celko's "nested sets" as a
SQLA mapping.

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

contains_eager() with an alias argument works even when
the alias is embedded in a SELECT, as when sent to the
Query via query.select_from().

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

contains_eager() usage is now compatible with a Query that
also contains a regular eager load and limit/offset, in that
the columns are added to the Query-generated subquery.

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

session.execute() will execute a Sequence object passed to
it (regression from 0.4).

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

Removed the "raiseerror" keyword argument from object_mapper()
and class_mapper().  These functions raise in all cases
if the given class/instance is not mapped.

.. change::
:tags: orm
:tickets:

Fixed session.transaction.commit() on a autocommit=False
session not starting a new transaction.

.. change::
:tags: orm
:tickets:

Some adjustments to Session.identity_map's weak referencing
behavior to reduce asynchronous GC side effects.

.. change::
:tags: orm
:tickets: 1182

Adjustment to Session's post-flush accounting of newly
"clean" objects to better protect against operating on
objects as they're asynchronously gc'ed.

.. change::
:tags: sql
:tickets: 1074

column.in_(someselect) can now be used as a columns-clause
expression without the subquery bleeding into the FROM clause

.. change::
:tags: sqlite
:tickets: 968

Overhauled SQLite date/time bind/result processing to use
regular expressions and format strings, rather than
strptime/strftime, to generically support pre-1900 dates,
dates with microseconds.

.. change::
:tags: sqlite
:tickets:

String's (and Unicode's, UnicodeText's, etc.) convert_unicode
logic disabled in the sqlite dialect, to adjust for pysqlite
2.5.0's new requirement that only Python unicode objects are
accepted;
http://itsystementwicklung.de/pipermail/list-pysqlite/2008-March/000018.html

.. change::
:tags: mysql
:tickets:

Temporary tables are now reflectable.

.. change::
:tags: oracle
:tickets: 1187

Oracle will detect string-based statements which contain
comments at the front before a SELECT as SELECT statements.

.. changelog::

0.5.0rc1

:released: Thu Sep 11 2008

.. change::
:tags: orm
:tickets:

Query now has delete() and update(values) methods. This allows
to perform bulk deletes/updates with the Query object.

.. change::
:tags: orm
:tickets:

The RowTuple object returned by Query(\*cols) now features
keynames which prefer mapped attribute names over column keys,
column keys over column names, i.e.  Query(Class.foo,
Class.bar) will have names "foo" and "bar" even if those are
not the names of the underlying Column objects.  Direct Column
objects such as Query(table.c.col) will return the "key"
attribute of the Column.

.. change::
:tags: orm
:tickets:

Added scalar() and value() methods to Query, each return a
single scalar value.  scalar() takes no arguments and is
roughly equivalent to first()[0], value()
takes a single column expression and is roughly equivalent to
values(expr).next()[0].

.. change::
:tags: orm
:tickets:

Improved the determination of the FROM clause when placing SQL
expressions in the query() list of entities.  In particular
scalar subqueries should not "leak" their inner FROM objects
out into the enclosing query.

.. change::
:tags: orm
:tickets:

Joins along a relation() from a mapped class to a mapped
subclass, where the mapped subclass is configured with single
table inheritance, will include an IN clause which limits the
subtypes of the joined class to those requested, within the ON
clause of the join.  This takes effect for eager load joins as
well as query.join().  Note that in some scenarios the IN
clause will appear in the WHERE clause of the query as well
since this discrimination has multiple trigger points.

.. change::
:tags: orm
:tickets:

AttributeExtension has been refined such that the event
is fired before the mutation actually occurs.  Additionally,
the append() and set() methods must now return the given value,
which is used as the value to be used in the mutation operation.
This allows creation of validating AttributeListeners which
raise before the action actually occurs, and which can change
the given value into something else before its used.

.. change::
:tags: orm
:tickets:

column_property(), composite_property(), and relation() now
accept a single or list of AttributeExtensions using the
"extension" keyword argument.

.. change::
:tags: orm
:tickets:

query.order_by().get() silently drops the "ORDER BY" from
the query issued by GET but does not raise an exception.

.. change::
:tags: orm
:tickets:

Added a Validator AttributeExtension, as well as a
validates decorator which is used in a similar fashion
as reconstructor, and marks a method as validating
one or more mapped attributes.

.. change::
:tags: orm
:tickets: 1140

class.someprop.in_() raises NotImplementedError pending the
implementation of "in\_" for relation

.. change::
:tags: orm
:tickets: 1127

Fixed primary key update for many-to-many collections where
the collection had not been loaded yet

.. change::
:tags: orm
:tickets:

Fixed bug whereby deferred() columns with a group in conjunction
with an otherwise unrelated synonym() would produce
an AttributeError during deferred load.

.. change::
:tags: orm
:tickets: 1128

The before_flush() hook on SessionExtension takes place before
the list of new/dirty/deleted is calculated for the final
time, allowing routines within before_flush() to further
change the state of the Session before the flush proceeds.

.. change::
:tags: orm
:tickets:

The "extension" argument to Session and others can now
optionally be a list, supporting events sent to multiple
SessionExtension instances.  Session places SessionExtensions
in Session.extensions.

.. change::
:tags: orm
:tickets:

Reentrant calls to flush() raise an error.  This also serves
as a rudimentary, but not foolproof, check against concurrent
calls to Session.flush().

.. change::
:tags: orm
:tickets:

Improved the behavior of query.join() when joining to
joined-table inheritance subclasses, using explicit join
criteria (i.e. not on a relation).

.. change::
:tags: orm
:tickets:

orm.attributes.reconstitute and
MapperExtension.reconstitute have been renamed to
orm.reconstructor and MapperExtension.reconstruct_instance

.. change::
:tags: orm
:tickets: 1129

Fixed reconstructor hook for subclasses which inherit from a
base class.

.. change::
:tags: orm
:tickets: 1132

The composite() property type now supports a
__set_composite_values__() method on the composite class which
is required if the class represents state using attribute
names other than the column's keynames; default-generated
values now get populated properly upon flush.  Also,
composites with attributes set to None compare correctly.

.. change::
:tags: orm
:tickets:

The 3-tuple of iterables returned by attributes.get_history()
may now be a mix of lists and tuples.  (Previously members
were always lists.)

.. change::
:tags: orm
:tickets: 1151

Fixed bug whereby changing a primary key attribute on an
entity where the attribute's previous value had been expired
would produce an error upon flush().

.. change::
:tags: orm
:tickets:

Fixed custom instrumentation bug whereby get_instance_dict()
was not called for newly constructed instances not loaded
by the ORM.

.. change::
:tags: orm
:tickets: 1150

Session.delete() adds the given object to the session if
not already present.  This was a regression bug from 0.4.

.. change::
:tags: orm
:tickets:

The `echo_uow` flag on `Session` is deprecated, and unit-of-work
logging is now application-level only, not per-session level.

.. change::
:tags: orm
:tickets: 1153

Removed conflicting `contains()` operator from
`InstrumentedAttribute` which didn't accept `escape` kwaarg.

.. change::
:tags: declarative
:tickets: 1161

Fixed bug whereby mapper couldn't initialize if a composite
primary key referenced another table that was not defined
yet.

.. change::
:tags: declarative
:tickets:

Fixed exception throw which would occur when string-based
primaryjoin condition was used in conjunction with backref.

.. change::
:tags: schema
:tickets: 1033

Added "sorted_tables" accessor to MetaData, which returns
Table objects sorted in order of dependency as a list.
This deprecates the MetaData.table_iterator() method.
The "reverse=False" keyword argument has also been
removed from util.sort_tables(); use the Python
'reversed' function to reverse the results.

.. change::
:tags: schema
:tickets:

The 'length' argument to all Numeric types has been renamed
to 'scale'.  'length' is deprecated and is still accepted
with a warning.

.. change::
:tags: schema
:tickets:

Dropped 0.3-compatibility for user defined types
(convert_result_value, convert_bind_param).

.. change::
:tags: sql
:tickets: 1068

Temporarily rolled back the "ORDER BY" enhancement from.  This feature is on hold pending further
development.

.. change::
:tags: sql
:tickets:

The exists() construct won't "export" its contained list
of elements as FROM clauses, allowing them to be used more
effectively in the columns clause of a SELECT.

.. change::
:tags: sql
:tickets: 798

and_() and or_() now generate a ColumnElement, allowing
boolean expressions as result columns, i.e.
select([and_(1, 0)]).

.. change::
:tags: sql
:tickets:

Bind params now subclass ColumnElement which allows them to be
selectable by orm.query (they already had most ColumnElement
semantics).

.. change::
:tags: sql
:tickets:

Added select_from() method to exists() construct, which becomes
more and more compatible with a regular select().

.. change::
:tags: sql
:tickets: 1160

Added func.min(), func.max(), func.sum() as "generic functions",
which basically allows for their return type to be determined
automatically.  Helps with dates on SQLite, decimal types,
others.

.. change::
:tags: sql
:tickets:

added decimal.Decimal as an "auto-detect" type; bind parameters
and generic functions will set their type to Numeric when a
Decimal is used.

.. change::
:tags: mysql
:tickets:

The 'length' argument to MSInteger, MSBigInteger, MSTinyInteger,
MSSmallInteger and MSYear has been renamed to 'display_width'.

.. change::
:tags: mysql
:tickets: 1146

Added MSMediumInteger type.

.. change::
:tags: mysql
:tickets:

the function func.utc_timestamp() compiles to UTC_TIMESTAMP, without
the parenthesis, which seem to get in the way when using in
conjunction with executemany().

.. change::
:tags: oracle
:tickets: 536

limit/offset no longer uses ROW NUMBER OVER to limit rows,
and instead uses subqueries in conjunction with a special
Oracle optimization comment.  Allows LIMIT/OFFSET to work
in conjunction with DISTINCT.

.. change::
:tags: oracle
:tickets: 1155

has_sequence() now takes the current "schema" argument into
account

.. change::
:tags: oracle
:tickets: 1121

added BFILE to reflected type names

.. changelog::

0.5.0beta3

:released: Mon Aug 04 2008

.. change::
:tags: orm
:tickets:

The "entity_name" feature of SQLAlchemy mappers has been
removed.  For rationale, see http://tinyurl.com/6nm2ne

.. change::
:tags: orm
:tickets:

the "autoexpire" flag on Session, sessionmaker(), and
scoped_session() has been renamed to "expire_on_commit".  It
does not affect the expiration behavior of rollback().

.. change::
:tags: orm
:tickets:

fixed endless loop bug which could occur within a mapper's
deferred load of inherited attributes.

.. change::
:tags: orm
:tickets:

a legacy-support flag "_enable_transaction_accounting" flag
added to Session which when False, disables all
transaction-level object accounting, including expire on
rollback, expire on commit, new/deleted list maintenance, and
autoflush on begin.

.. change::
:tags: orm
:tickets:

The 'cascade' parameter to relation() accepts None as a value,
which is equivalent to no cascades.

.. change::
:tags: orm
:tickets:

A critical fix to dynamic relations allows the "modified"
history to be properly cleared after a flush().

.. change::
:tags: orm
:tickets:

user-defined properties on a class are detected and left in
place during mapper initialization.  This means that a
table-bound column of the same name will not be mapped at all
if a property is in the way (and the column is not remapped
to a different name), nor will an instrumented attribute from
an inherited class be applied.  The same rules apply for names
excluded using the include_properties/exclude_properties
collections.

.. change::
:tags: orm
:tickets:

Added a new SessionExtension hook called after_attach().  This
is called at the point of attachment for objects via add(),
add_all(), delete(), and merge().

.. change::
:tags: orm
:tickets: 1111

A mapper which inherits from another, when inheriting the
columns of its inherited mapper, will use any reassigned
property names specified in that inheriting mapper.
Previously, if "Base" had reassigned "base_id" to the name
"id", "SubBase(Base)" would still get an attribute called
"base_id".  This could be worked around by explicitly stating
the column in each submapper as well but this is fairly
unworkable and also impossible when using declarative.

.. change::
:tags: orm
:tickets:

Fixed a series of potential race conditions in Session whereby
asynchronous GC could remove unmodified, no longer referenced
items from the session as they were present in a list of items
to be processed, typically during session.expunge_all() and
dependent methods.

.. change::
:tags: orm
:tickets:

Some improvements to the _CompileOnAttr mechanism which should
reduce the probability of "Attribute x was not replaced during
compile" warnings. (this generally applies to SQLA hackers,
like Elixir devs).

.. change::
:tags: orm
:tickets:

Fixed bug whereby the "unsaved, pending instance" FlushError
raised for a pending orphan would not take superclass mappers
into account when generating the list of relations responsible
for the error.

.. change::
:tags: sql
:tickets:

func.count() with no arguments renders as COUNT(*), equivalent
to func.count(text('*')).

.. change::
:tags: sql
:tickets: 1068

simple label names in ORDER BY expressions render as
themselves, and not as a re-statement of their corresponding
expression.  This feature is currently enabled only for
SQLite, MySQL, and PostgreSQL.  It can be enabled on other
dialects as each is shown to support this
behavior.

.. change::
:tags: ext
:tickets:

Class-bound attributes sent as arguments to relation()'s
remote_side and foreign_keys parameters are now accepted,
allowing them to be used with declarative.  Additionally fixed
bugs involving order_by being specified as a class-bound
attribute in conjunction with eager loading.

.. change::
:tags: ext
:tickets:

declarative initialization of Columns adjusted so that
non-renamed columns initialize in the same way as a non
declarative mapper.  This allows an inheriting mapper to set
up its same-named "id" columns in particular such that the
parent "id" column is favored over the child column, reducing
database round trips when this value is requested.

.. change::
:tags: mysql
:tickets: 1110

Quoting of MSEnum values for use in CREATE TABLE is now
optional & will be quoted on demand as required.  (Quoting was
always optional for use with existing tables.)

.. changelog::

0.5.0beta2

:released: Mon Jul 14 2008

.. change::
:tags: orm
:tickets: 870

In addition to expired attributes, deferred attributes also
load if their data is present in the result set.

.. change::
:tags: orm
:tickets:

session.refresh() raises an informative error message if the
list of attributes does not include any column-based
attributes.

.. change::
:tags: orm
:tickets:

query() raises an informative error message if no columns or
mappers are specified.

.. change::
:tags: orm
:tickets:

lazy loaders now trigger autoflush before proceeding.  This
allows expire() of a collection or scalar relation to function
properly in the context of autoflush.

.. change::
:tags: orm
:tickets: 887

column_property() attributes which represent SQL expressions
or columns that are not present in the mapped tables (such as
those from views) are automatically expired after an INSERT or
UPDATE, assuming they have not been locally modified, so that
they are refreshed with the most recent data upon access.

.. change::
:tags: orm
:tickets: 1082

Fixed explicit, self-referential joins between two
joined-table inheritance mappers when using query.join(cls,
aliased=True).

.. change::
:tags: orm
:tickets:

Fixed query.join() when used in conjunction with a
columns-only clause and a SQL-expression ON clause in the
join.

.. change::
:tags: orm
:tickets:

The "allow_column_override" flag from mapper() has been
removed.  This flag is virtually always misunderstood.  Its
specific functionality is available via the
include_properties/exclude_properties mapper arguments.

.. change::
:tags: orm
:tickets: 1066

Repaired `__str__()` method on Query.

.. change::
:tags: orm
:tickets:

Session.bind gets used as a default even when table/mapper
specific binds are defined.

.. change::
:tags: schema
:tickets: 1075

Added prefixes option to `Table` that accepts a list of
strings to insert after CREATE in the CREATE TABLE statement.

.. change::
:tags: schema
:tickets:

Unicode, UnicodeText types now set "assert_unicode" and
"convert_unicode" by default, but accept overriding
\**kwargs for these values.

.. change::
:tags: sql
:tickets:

Added new match() operator that performs a full-text search.
Supported on PostgreSQL, SQLite, MySQL, MS-SQL, and Oracle
backends.

.. change::
:tags: sqlite
:tickets: 1090

Modified SQLite's representation of "microseconds" to match
the output of str(somedatetime), i.e. in that the microseconds
are represented as fractional seconds in string format.  This
makes SQLA's SQLite date type compatible with datetimes that
were saved directly using Pysqlite (which just calls str()).
Note that this is incompatible with the existing microseconds
values in a SQLA 0.4 generated SQLite database file.

To get the old behavior globally:

from sqlalchemy.databases.sqlite import DateTimeMixin
DateTimeMixin.__legacy_microseconds__ = True

To get the behavior on individual DateTime types:

t = sqlite.SLDateTime()
t.__legacy_microseconds__ = True

Then use "t" as the type on the Column.

.. change::
:tags: sqlite
:tickets:

SQLite Date, DateTime, and Time types only accept Python
datetime objects now, not strings.  If you'd like to format
dates as strings yourself with SQLite, use a String type.  If
you'd like them to return datetime objects anyway despite
their accepting strings as input, make a TypeDecorator around
String - SQLA doesn't encourage this pattern.

.. change::
:tags: extensions
:tickets: 1096

Declarative supports a __table_args__ class variable, which is
either a dictionary, or tuple of the form (arg1, arg2, ...,
{kwarg1:value, ...}) which contains positional + kw arguments
to be passed to the Table constructor.

.. changelog::

0.5.0beta1

:released: Thu Jun 12 2008

.. change::
:tags:
:tickets:

The "__init__" trigger/decorator added by mapper now attempts
to exactly mirror the argument signature of the original
__init__.  The pass-through for '_sa_session' is no longer
implicit- you must allow for this keyword argument in your
constructor.

.. change::
:tags:
:tickets:

ClassState is renamed to ClassManager.

.. change::
:tags:
:tickets:

Classes may supply their own InstrumentationManager by
providing a __sa_instrumentation_manager__ property.

.. change::
:tags:
:tickets:

Custom instrumentation may use any mechanism to associate a
ClassManager with a class and an InstanceState with an
instance.  Attributes on those objects are still the default
association mechanism used by SQLAlchemy's native
instrumentation.

.. change::
:tags:
:tickets:

Moved entity_name, _sa_session_id, and _instance_key from the
instance object to the instance state.  These values are still
available in the old way, which is now deprecated, using
descriptors attached to the class.  A deprecation warning will
be issued when accessed.

.. change::
:tags:
:tickets:

The _prepare_instrumentation alias for prepare_instrumentation
has been removed.

.. change::
:tags:
:tickets:

sqlalchemy.exceptions has been renamed to sqlalchemy.exc.  The
module may be imported under either name.

.. change::
:tags:
:tickets:

ORM-related exceptions are now defined in sqlalchemy.orm.exc.
ConcurrentModificationError, FlushError, and
UnmappedColumnError compatibility aliases are installed in
sqlalchemy.exc during the import of sqlalchemy.orm.

.. change::
:tags:
:tickets:

sqlalchemy.logging has been renamed to sqlalchemy.log.

.. change::
:tags:
:tickets:

The transitional sqlalchemy.log.SADeprecationWarning alias for
the warning's definition in sqlalchemy.exc has been removed.

.. change::
:tags:
:tickets:

exc.AssertionError has been removed and usage replaced with
Python's built-in AssertionError.

.. change::
:tags:
:tickets:

The behavior of MapperExtensions attached to multiple,
entity_name= primary mappers for a single class has been
altered.  The first mapper() defined for a class is the only
mapper eligible for the MapperExtension 'instrument_class',
'init_instance' and 'init_failed' events.  This is backwards
incompatible; previously the extensions of last mapper defined
would receive these events.

.. change::
:tags: firebird
:tickets:

Added support for returning values from inserts (2.0+ only),
updates and deletes (2.1+ only).

.. change::
:tags: general
:tickets:

global "propigate"->"propagate" change.

.. change::
:tags: orm
:tickets:

polymorphic_union() function respects the "key" of each
Column if they differ from the column's name.

.. change::
:tags: orm
:tickets: 1199

Fixed 0.4-only bug preventing composite columns
from working properly with inheriting mappers

.. change::
:tags: orm
:tickets:

Fixed RLock-related bug in mapper which could deadlock upon
reentrant mapper compile() calls, something that occurs when
using declarative constructs inside of ForeignKey objects.
Ported from 0.5.

.. change::
:tags: orm
:tickets: 1213

Fixed bug in composite types which prevented a primary-key
composite type from being mutated.

.. change::
:tags: orm
:tickets: 976

Added ScopedSession.is_active accessor.

.. change::
:tags: orm
:tickets: 939

Class-bound accessor can be used as the argument to
relation() order_by.

.. change::
:tags: orm
:tickets: 1072

Fixed shard_id argument on ShardedSession.execute().

.. change::
:tags: sql
:tickets: 1246

Connection.invalidate() checks for closed status
to avoid attribute errors.

.. change::
:tags: sql
:tickets: 1094

NullPool supports reconnect on failure behavior.

.. 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: sql
: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: postgres
:tickets: 714

Added Index reflection support to Postgres, using a
great patch we long neglected, submitted by
Ken Kuhlman.

.. change::
:tags: mysql
:tickets: 1241

Fixed bug in exception raise when FK columns not present
during reflection.

.. 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 !



=============
0.6 Changelog
=============


.. changelog::

0.4.8

:released: Sun Oct 12 2008

.. change::
:tags: orm
:tickets: 1039

Fixed bug regarding inherit_condition passed
with "A=B" versus "B=A" leading to errors

.. change::
:tags: orm
:tickets:

Changes made to new, dirty and deleted
collections in
SessionExtension.before_flush() will take
effect for that flush.

.. change::
:tags: orm
:tickets:

Added label() method to InstrumentedAttribute
to establish forwards compatibility with 0.5.

.. change::
:tags: sql
:tickets: 1074

column.in_(someselect) can now be used as
a columns-clause expression without the subquery
bleeding into the FROM clause

.. change::
:tags: mysql
:tickets: 1146

Added MSMediumInteger type.

.. change::
:tags: sqlite
:tickets: 968

Supplied a custom strftime() function which
handles dates before 1900.

.. change::
:tags: sqlite
:tickets:

String's (and Unicode's, UnicodeText's, etc.)
convert_unicode logic disabled in the sqlite dialect,
to adjust for pysqlite 2.5.0's new requirement that
only Python unicode objects are accepted;
http://itsystementwicklung.de/pipermail/list-pysqlite/2008-March/000018.html

.. change::
:tags: oracle
:tickets: 1155

has_sequence() now takes schema name into account

.. change::
:tags: oracle
:tickets: 1121

added BFILE to the list of reflected types

.. changelog::
:version: 0.4.7p1
:released: Thu Jul 31 2008

.. change::
:tags: orm
:tickets:

Added "add()" and "add_all()" to scoped_session
methods.  Workaround for 0.4.7::

from sqlalchemy.orm.scoping import ScopedSession, instrument
setattr(ScopedSession, "add", instrument("add"))
setattr(ScopedSession, "add_all", instrument("add_all"))

.. change::
:tags: orm
:tickets:

Fixed non-2.3 compatible usage of set() and generator
expression within relation().

.. changelog::

0.4.7

:released: Sat Jul 26 2008

.. change::
:tags: orm
:tickets: 1058

The contains() operator when used with many-to-many
will alias() the secondary (association) table so
that multiple contains() calls will not conflict
with each other

.. change::
:tags: orm
:tickets:

fixed bug preventing merge() from functioning in
conjunction with a comparable_property()

.. change::
:tags: orm
:tickets:

the enable_typechecks=False setting on relation()
now only allows subtypes with inheriting mappers.
Totally unrelated types, or subtypes not set up with
mapper inheritance against the target mapper are
still not allowed.

.. change::
:tags: orm
:tickets: 976

Added is_active flag to Sessions to detect when
a transaction is in progress.  This
flag is always True with a "transactional"
(in 0.5 a non-"autocommit") Session.

.. change::
:tags: sql
:tickets:

Fixed bug when calling select([literal('foo')])
or select([bindparam('foo')]).

.. change::
:tags: schema
:tickets: 571

create_all(), drop_all(), create(), drop() all raise
an error if the table name or schema name contains
more characters than that dialect's configured
character limit.  Some DB's can handle too-long
table names during usage, and SQLA can handle this
as well. But various reflection/
checkfirst-during-create scenarios fail since we are
looking for the name within the DB's catalog tables.

.. change::
:tags: schema
:tickets: 571, 820

The index name generated when you say "index=True"
on a Column is truncated to the length appropriate
for the dialect. Additionally, an Index with a too-
long name cannot be explicitly dropped with
Index.drop(), similar to.

.. change::
:tags: postgres
:tickets:

Repaired server_side_cursors to properly detect
text() clauses.

.. change::
:tags: postgres
:tickets: 1092

Added PGCidr type.

.. change::
:tags: mysql
:tickets:

Added 'CALL' to the list of SQL keywords which return
result rows.

.. change::
:tags: oracle
:tickets:

Oracle get_default_schema_name() "normalizes" the name
before returning, meaning it returns a lower-case name
when the identifier is detected as case insensitive.

.. change::
:tags: oracle
:tickets: 709

creating/dropping tables takes schema name into account
when searching for the existing table, so that tables
in other owner namespaces with the same name do not
conflict

.. change::
:tags: oracle
:tickets: 1062

Cursors now have "arraysize" set to 50 by default on
them, the value of which is configurable using the
"arraysize" argument to create_engine() with the
Oracle dialect.  This to account for cx_oracle's default
setting of "1", which has the effect of many round trips
being sent to Oracle.  This actually works well in
conjunction with BLOB/CLOB-bound cursors, of which
there are any number available but only for the life of
that row request (so BufferedColumnRow is still needed,
but less so).

.. change::
:tags: oracle
:tickets:

sqlite
- add SLFloat type, which matches the SQLite REAL
type affinity.  Previously, only SLNumeric was provided
which fulfills NUMERIC affinity, but that's not the
same as REAL.

.. changelog::

0.4.6

:released: Sat May 10 2008

.. change::
:tags: orm
:tickets:

Fix to the recent relation() refactoring which fixes
exotic viewonly relations which join between local and
remote table multiple times, with a common column shared
between the joins.

.. change::
:tags: orm
:tickets:

Also re-established viewonly relation() configurations
that join across multiple tables.

.. change::
:tags: orm
:tickets: 610

Added experimental relation() flag to help with
primaryjoins across functions, etc.,
_local_remote_pairs=[tuples].  This complements a complex
primaryjoin condition allowing you to provide the
individual column pairs which comprise the relation's
local and remote sides.  Also improved lazy load SQL
generation to handle placing bind params inside of
functions and other expressions.  (partial progress
towards)

.. change::
:tags: orm
:tickets: 1036

repaired single table inheritance such that you
can single-table inherit from a joined-table inheriting
mapper without issue.

.. change::
:tags: orm
:tickets: 1027

Fixed "concatenate tuple" bug which could occur with
Query.order_by() if clause adaption had taken place.

.. change::
:tags: orm
:tickets:

Removed ancient assertion that mapped selectables require
"alias names" - the mapper creates its own alias now if
none is present.  Though in this case you need to use the
class, not the mapped selectable, as the source of column
attributes - so a warning is still issued.

.. change::
:tags: orm
:tickets:

fixes to the "exists" function involving inheritance (any(),
has(), ~contains()); the full target join will be rendered
into the EXISTS clause for relations that link to subclasses.

.. change::
:tags: orm
:tickets:

restored usage of append_result() extension method for primary
query rows, when the extension is present and only a single-
entity result is being returned.

.. change::
:tags: orm
:tickets:

Also re-established viewonly relation() configurations that
join across multiple tables.

.. change::
:tags: orm
:tickets:

removed ancient assertion that mapped selectables require
"alias names" - the mapper creates its own alias now if
none is present.  Though in this case you need to use
the class, not the mapped selectable, as the source of
column attributes - so a warning is still issued.

.. change::
:tags: orm
:tickets: 1015

refined mapper._save_obj() which was unnecessarily calling
__ne__() on scalar values during flush

.. change::
:tags: orm
:tickets: 1019

added a feature to eager loading whereby subqueries set
as column_property() with explicit label names (which is not
necessary, btw) will have the label anonymized when
the instance is part of the eager join, to prevent
conflicts with a subquery or column of the same name
on the parent object.

.. change::
:tags: orm
:tickets:

set-based collections \|=, -=, ^= and &= are stricter about
their operands and only operate on sets, frozensets or
subclasses of the collection type. Previously, they would
accept any duck-typed set.

.. change::
:tags: orm
:tickets:

added an example dynamic_dict/dynamic_dict.py, illustrating
a simple way to place dictionary behavior on top of
a dynamic_loader.

.. change::
:tags: declarative, extension
:tickets:

Joined table inheritance mappers use a slightly relaxed
function to create the "inherit condition" to the parent
table, so that other foreign keys to not-yet-declared
Table objects don't trigger an error.

.. change::
:tags: declarative, extension
:tickets:

fixed reentrant mapper compile hang when
a declared attribute is used within ForeignKey,
ie. ForeignKey(MyOtherClass.someattribute)

.. change::
:tags: sql
:tickets:

Added COLLATE support via the .collate(<collation>)
expression operator and collate(<expr>, <collation>) sql
function.

.. change::
:tags: sql
:tickets:

Fixed bug with union() when applied to non-Table connected
select statements

.. change::
:tags: sql
:tickets: 1014

improved behavior of text() expressions when used as
FROM clauses, such as select().select_from(text("sometext"))

.. change::
:tags: sql
:tickets: 1021

Column.copy() respects the value of "autoincrement",
fixes usage with Migrate

.. change::
:tags: engines
:tickets:

Pool listeners can now be provided as a dictionary of
callables or a (possibly partial) duck-type of
PoolListener, your choice.

.. change::
:tags: engines
:tickets:

added "rollback_returned" option to Pool which will
disable the rollback() issued when connections are
returned.  This flag is only safe to use with a database
which does not support transactions (i.e. MySQL/MyISAM).

.. change::
:tags: ext
:tickets:

set-based association proxies \|=, -=, ^= and &= are
stricter about their operands and only operate on sets,
frozensets or other association proxies. Previously, they
would accept any duck-typed set.

.. change::
:tags: mssql
:tickets: 1005

Added "odbc_autotranslate" parameter to engine / dburi
parameters. Any given string will be passed through to the
ODBC connection string as:

"AutoTranslate=%s" % odbc_autotranslate

.. change::
:tags: mssql
:tickets:

Added "odbc_options" parameter to engine / dburi
parameters. The given string is simply appended to the
SQLAlchemy-generated odbc connection string.

This should obviate the need of adding a myriad of ODBC
options in the future.

.. change::
:tags: firebird
:tickets:

Handle the "SUBSTRING(:string FROM :start FOR :length)"
builtin.

.. changelog::

0.4.5

:released: Fri Apr 04 2008

.. change::
:tags: orm
:tickets:

A small change in behavior to session.merge() - existing
objects are checked for based on primary key attributes, not
necessarily _instance_key.  So the widely requested
capability, that:

x = MyObject(id=1)
x = sess.merge(x)

will in fact load MyObject with id 1 from the database if
present, is now available.  merge() still copies the state
of the given object to the persistent one, so an example
like the above would typically have copied "None" from all
attributes of "x" onto the persistent copy.  These can be
reverted using session.expire(x).

.. change::
:tags: orm
:tickets:

Also fixed behavior in merge() whereby collection elements
present on the destination but not the merged collection
were not being removed from the destination.

.. change::
:tags: orm
:tickets: 995

Added a more aggressive check for "uncompiled mappers",
helps particularly with declarative layer

.. change::
:tags: orm
:tickets:

The methodology behind "primaryjoin"/"secondaryjoin" has
been refactored.  Behavior should be slightly more
intelligent, primarily in terms of error messages which
have been pared down to be more readable.  In a slight
number of scenarios it can better resolve the correct
foreign key than before.

.. change::
:tags: orm
:tickets:

Added comparable_property(), adds query Comparator
behavior to regular, unmanaged Python properties

.. change::
:tags: orm, Company.employees.of_type(Engineer), 'machines'
:tickets:

the functionality of query.with_polymorphic() has
been added to mapper() as a configuration option.

It's set via several forms:
with_polymorphic='*'
with_polymorphic=[mappers]
with_polymorphic=('*', selectable)
with_polymorphic=([mappers], selectable)

This controls the default polymorphic loading strategy
for inherited mappers. When a selectable is not given,
outer joins are created for all joined-table inheriting
mappers requested. Note that the auto-create of joins
is not compatible with concrete table inheritance.

The existing select_table flag on mapper() is now
deprecated and is synonymous with
with_polymorphic('*', select_table).  Note that the
underlying "guts" of select_table have been
completely removed and replaced with the newer,
more flexible approach.

The new approach also automatically allows eager loads
to work for subclasses, if they are present, for
example::

sess.query(Company).options(
eagerload_all(
))

to load Company objects, their employees, and the
'machines' collection of employees who happen to be
Engineers. A "with_polymorphic" Query option should be
introduced soon as well which would allow per-Query
control of with_polymorphic() on relations.

.. change::
:tags: orm
:tickets:

added two "experimental" features to Query,
"experimental" in that their specific name/behavior
is not carved in stone just yet:  _values() and
_from_self().  We'd like feedback on these.

- _values(\*columns) is given a list of column
expressions, and returns a new Query that only
returns those columns. When evaluated, the return
value is a list of tuples just like when using
add_column() or add_entity(), the only difference is
that "entity zero", i.e. the mapped class, is not
included in the results. This means it finally makes
sense to use group_by() and having() on Query, which
have been sitting around uselessly until now.

A future change to this method may include that its
ability to join, filter and allow other options not
related to a "resultset" are removed, so the feedback
we're looking for is how people want to use
_values()...i.e. at the very end, or do people prefer
to continue generating after it's called.

- _from_self() compiles the SELECT statement for the
Query (minus any eager loaders), and returns a new
Query that selects from that SELECT. So basically you
can query from a Query without needing to extract the
SELECT statement manually. This gives meaning to
operations like query[3:5]._from_self().filter(some
criterion). There's not much controversial here
except that you can quickly create highly nested
queries that are less efficient, and we want feedback
on the naming choice.

.. change::
:tags: orm
:tickets:

query.order_by() and query.group_by() will accept
multiple arguments using \*args (like select()
already does).

.. change::
:tags: orm
:tickets:

Added some convenience descriptors to Query:
query.statement returns the full SELECT construct,
query.whereclause returns just the WHERE part of the
SELECT construct.

.. change::
:tags: orm
:tickets:

Fixed/covered case when using a False/0 value as a
polymorphic discriminator.

.. change::
:tags: orm
:tickets:

Fixed bug which was preventing synonym() attributes from
being used with inheritance

.. change::
:tags: orm
:tickets: 996

Fixed SQL function truncation of trailing underscores

.. change::
:tags: orm
:tickets:

When attributes are expired on a pending instance, an
error will not be raised when the "refresh" action is
triggered and no result is found.

.. change::
:tags: orm
:tickets:

Session.execute can now find binds from metadata

.. change::
:tags: orm
:tickets:

Adjusted the definition of "self-referential" to be any
two mappers with a common parent (this affects whether or
not aliased=True is required when joining with Query).

.. change::
:tags: orm
:tickets:

Made some fixes to the "from_joinpoint" argument to
query.join() so that if the previous join was aliased and
this one isn't, the join still happens successfully.

.. change::
:tags: orm
:tickets: 895

Assorted "cascade deletes" fixes:
- Fixed "cascade delete" operation of dynamic relations,
which had only been implemented for foreign-key
nulling behavior in 0.4.2 and not actual cascading
deletes

- Delete cascade without delete-orphan cascade on a
many-to-one will not delete orphans which were
disconnected from the parent before session.delete()
is called on the parent (one-to-many already had
this).

- Delete cascade with delete-orphan will delete orphans
whether or not it remains attached to its also-deleted
parent.

- delete-orphan cascade is properly detected on relations
that are present on superclasses when using inheritance.

.. change::
:tags: orm
:tickets:

Fixed order_by calculation in Query to properly alias
mapper-config'ed order_by when using select_from()

.. change::
:tags: orm
:tickets:

Refactored the diffing logic that kicks in when replacing
one collection with another into collections.bulk_replace,
useful to anyone building multi-level collections.

.. change::
:tags: orm
:tickets:

Cascade traversal algorithm converted from recursive to
iterative to support deep object graphs.

.. change::
:tags: sql
:tickets: 999

schema-qualified tables now will place the schemaname
ahead of the tablename in all column expressions as well
as when generating column labels.  This prevents cross-
schema name collisions in all cases

.. change::
:tags: sql
:tickets:

can now allow selects which correlate all FROM clauses
and have no FROM themselves.  These are typically
used in a scalar context, i.e. SELECT x, (SELECT x WHERE y)
FROM table.  Requires explicit correlate() call.

.. change::
:tags: sql
:tickets:

'name' is no longer a required constructor argument for
Column().  It (and .key) may now be deferred until the
column is added to a Table.

.. change::
:tags: sql
:tickets: 791, 993

like(), ilike(), contains(), startswith(), endswith() take
an optional keyword argument "escape=<somestring>", which
is set as the escape character using the syntax "x LIKE y
ESCAPE '<somestring>'".

.. change::
:tags: sql
:tickets:

random() is now a generic sql function and will compile to
the database's random implementation, if any.

.. change::
:tags: sql
:tickets:

update().values() and insert().values() take keyword
arguments.

.. change::
:tags: sql
:tickets:

Fixed an issue in select() regarding its generation of
FROM clauses, in rare circumstances two clauses could be
produced when one was intended to cancel out the other.
Some ORM queries with lots of eager loads might have seen
this symptom.

.. change::
:tags: sql
:tickets:

The case() function now also takes a dictionary as its
whens parameter.  It also interprets the "THEN"
expressions as values by default, meaning case([(x==y,
"foo")]) will interpret "foo" as a bound value, not a SQL
expression.  use text(expr) for literal SQL expressions in
this case.  For the criterion itself, these may be literal
strings only if the "value" keyword is present, otherwise
SA will force explicit usage of either text() or
literal().

.. change::
:tags: oracle
:tickets:

The "owner" keyword on Table is now deprecated, and is
exactly synonymous with the "schema" keyword.  Tables can
now be reflected with alternate "owner" attributes,
explicitly stated on the Table object or not using
"schema".

.. change::
:tags: oracle
:tickets:

All of the "magic" searching for synonyms, DBLINKs etc.
during table reflection are disabled by default unless you
specify "oracle_resolve_synonyms=True" on the Table
object.  Resolving synonyms necessarily leads to some
messy guessing which we'd rather leave off by default.
When the flag is set, tables and related tables will be
resolved against synonyms in all cases, meaning if a
synonym exists for a particular table, reflection will use
it when reflecting related tables.  This is stickier
behavior than before which is why it's off by default.

.. change::
:tags: declarative, extension
:tickets:

The "synonym" function is now directly usable with
"declarative".  Pass in the decorated property using the
"descriptor" keyword argument, e.g.: somekey =
synonym('_somekey', descriptor=property(g, s))

.. change::
:tags: declarative, extension
:tickets:

The "deferred" function is usable with "declarative".
Simplest usage is to declare deferred and Column together,
e.g.: data = deferred(Column(Text))

.. change::
:tags: declarative, extension
:tickets:

Declarative also gained synonym_for(...) and
comparable_using(...), front-ends for synonym and
comparable_property.

.. change::
:tags: declarative, extension
:tickets: 995

Improvements to mapper compilation when using declarative;
already-compiled mappers will still trigger compiles of
other uncompiled mappers when used

.. change::
:tags: declarative, extension
:tickets:

Declarative will complete setup for Columns lacking names,
allows a more DRY syntax.

class Foo(Base):
__tablename__ = 'foos'
id = Column(Integer, primary_key=True)

.. change::
:tags: declarative, extension
:tickets:

inheritance in declarative can be disabled when sending
"inherits=None" to __mapper_args__.

.. change::
:tags: declarative, extension
:tickets:

declarative_base() takes optional kwarg "mapper", which
is any callable/class/method that produces a mapper,
such as declarative_base(mapper=scopedsession.mapper).
This property can also be set on individual declarative
classes using the "__mapper_cls__" property.

.. change::
:tags: postgres
:tickets: 1001

Got PG server side cursors back into shape, added fixed
unit tests as part of the default test suite.  Added
better uniqueness to the cursor ID

.. change::
:tags: oracle
:tickets:

The "owner" keyword on Table is now deprecated, and is
exactly synonymous with the "schema" keyword.  Tables can
now be reflected with alternate "owner" attributes,
explicitly stated on the Table object or not using
"schema".

.. change::
:tags: oracle
:tickets:

All of the "magic" searching for synonyms, DBLINKs etc.
during table reflection are disabled by default unless you
specify "oracle_resolve_synonyms=True" on the Table
object.  Resolving synonyms necessarily leads to some
messy guessing which we'd rather leave off by default.
When the flag is set, tables and related tables will be
resolved against synonyms in all cases, meaning if a
synonym exists for a particular table, reflection will use
it when reflecting related tables.  This is stickier
behavior than before which is why it's off by default.

.. change::
:tags: mssql
:tickets: 979

Reflected tables will now automatically load other tables
which are referenced by Foreign keys in the auto-loaded
table,.

.. change::
:tags: mssql
:tickets: 916

Added executemany check to skip identity fetch,.

.. change::
:tags: mssql
:tickets: 884

Added stubs for small date type.

.. change::
:tags: mssql
:tickets:

Added a new 'driver' keyword parameter for the pyodbc dialect.
Will substitute into the ODBC connection string if given,
defaults to 'SQL Server'.

.. change::
:tags: mssql
:tickets:

Added a new 'max_identifier_length' keyword parameter for
the pyodbc dialect.

.. change::
:tags: mssql
:tickets:

Improvements to pyodbc + Unix. If you couldn't get that
combination to work before, please try again.

.. change::
:tags: mysql
:tickets:

The connection.info keys the dialect uses to cache server
settings have changed and are now namespaced.

.. changelog::

0.4.4

:released: Wed Mar 12 2008

.. change::
:tags: sql
:tickets: 975

Can again create aliases of selects against textual FROM
clauses.

.. change::
:tags: sql
:tickets:

The value of a bindparam() can be a callable, in which
case it's evaluated at statement execution time to get the
value.

.. change::
:tags: sql
:tickets: 978

Added exception wrapping/reconnect support to result set
fetching.  Reconnect works for those databases that raise
a catchable data error during results (i.e. doesn't work
on MySQL)

.. change::
:tags: sql
:tickets: 936

Implemented two-phase API for "threadlocal" engine, via
engine.begin_twophase(), engine.prepare()

.. change::
:tags: sql
:tickets: 986

Fixed bug which was preventing UNIONS from being
cloneable.

.. change::
:tags: sql
:tickets:

Added "bind" keyword argument to insert(), update(),
delete() and DDL(). The .bind property is now assignable
on those statements as well as on select().

.. change::
:tags: sql
:tickets:

Insert statements can now be compiled with extra "prefix"
words between INSERT and INTO, for vendor extensions like
MySQL's INSERT IGNORE INTO table.

.. change::
:tags: orm
:tickets:

any(), has(), contains(), ~contains(), attribute level ==
and != now work properly with self-referential relations -
the clause inside the EXISTS is aliased on the "remote"
side to distinguish it from the parent table.  This
applies to single table self-referential as well as
inheritance-based self-referential.

.. change::
:tags: orm
:tickets: 985

Repaired behavior of == and != operators at the relation()
level when compared against NULL for one-to-one relations

.. change::
:tags: orm
:tickets:

Fixed bug whereby session.expire() attributes were not
loading on an polymorphically-mapped instance mapped by a
select_table mapper.

.. change::
:tags: orm
:tickets:

Added query.with_polymorphic() - specifies a list of
classes which descend from the base class, which will be
added to the FROM clause of the query.  Allows subclasses
to be used within filter() criterion as well as eagerly
loads the attributes of those subclasses.

.. change::
:tags: orm
:tickets:

Your cries have been heard: removing a pending item from
an attribute or collection with delete-orphan expunges the
item from the session; no FlushError is raised.  Note that
if you session.save()'ed the pending item explicitly, the
attribute/collection removal still knocks it out.

.. change::
:tags: orm
:tickets:

session.refresh() and session.expire() raise an error when
called on instances which are not persistent within the
session

.. change::
:tags: orm
:tickets:

Fixed potential generative bug when the same Query was
used to generate multiple Query objects using join().

.. change::
:tags: orm
:tickets:

Fixed bug which was introduced in 0.4.3, whereby loading
an already-persistent instance mapped with joined table
inheritance would trigger a useless "secondary" load from
its joined table, when using the default "select"
polymorphic_fetch.  This was due to attributes being
marked as expired during its first load and not getting
unmarked from the previous "secondary" load.  Attributes
are now unexpired based on presence in __dict__ after any
load or commit operation succeeds.

.. change::
:tags: orm
:tickets:

Deprecated Query methods apply_sum(), apply_max(),
apply_min(), apply_avg().  Better methodologies are
coming....

.. change::
:tags: orm
:tickets:

relation() can accept a callable for its first argument,
which returns the class to be related.  This is in place
to assist declarative packages to define relations without
classes yet being in place.

.. change::
:tags: orm
:tickets:

Added a new "higher level" operator called "of_type()":
used in join() as well as with any() and has(), qualifies
the subclass which will be used in filter criterion, e.g.:

query.filter(Company.employees.of_type(Engineer).
any(Engineer.name=='foo'))

or

query.join(Company.employees.of_type(Engineer)).
filter(Engineer.name=='foo')

.. change::
:tags: orm
:tickets:

Preventive code against a potential lost-reference bug in
flush().

.. change::
:tags: orm
:tickets:

Expressions used in filter(), filter_by() and others, when
they make usage of a clause generated from a relation
using the identity of a child object (e.g.,
filter(Parent.child==<somechild>)), evaluate the actual
primary key value of <somechild> at execution time so that
the autoflush step of the Query can complete, thereby
populating the PK value of <somechild> in the case that
<somechild> was pending.

.. change::
:tags: orm
:tickets:

setting the relation()-level order by to a column in the
many-to-many "secondary" table will now work with eager
loading, previously the "order by" wasn't aliased against
the secondary table's alias.

.. change::
:tags: orm
:tickets:

Synonyms riding on top of existing descriptors are now
full proxies to those descriptors.

.. change::
:tags: dialects
:tickets:

Invalid SQLite connection URLs now raise an error.

.. change::
:tags: dialects
:tickets: 981

postgres TIMESTAMP renders correctly

.. change::
:tags: dialects
:tickets:

postgres PGArray is a "mutable" type by default; when used
with the ORM, mutable-style equality/ copy-on-write
techniques are used to test for changes.

.. change::
:tags: extensions
:tickets:

a new super-small "declarative" extension has been added,
which allows Table and mapper() configuration to take
place inline underneath a class declaration.  This
extension differs from ActiveMapper and Elixir in that it
does not redefine any SQLAlchemy semantics at all; literal
Column, Table and relation() constructs are used to define
the class behavior and table definition.

.. changelog::

0.4.3

:released: Thu Feb 14 2008

.. change::
:tags: sql
:tickets:

Added "schema.DDL", an executable free-form DDL statement.
DDLs can be executed in isolation or attached to Table or
MetaData instances and executed automatically when those
objects are created and/or dropped.

.. change::
:tags: sql
:tickets:

Table columns and constraints can be overridden on a an
existing table (such as a table that was already reflected)
using the 'useexisting=True' flag, which now takes into
account the arguments passed along with it.

.. change::
:tags: sql
:tickets:

Added a callable-based DDL events interface, adds hooks
before and after Tables and MetaData create and drop.

.. change::
:tags: sql
:tickets:

Added generative where(<criterion>) method to delete() and
update() constructs which return a new object with criterion
joined to existing criterion via AND, just like
select().where().

.. change::
:tags: sql
:tickets: 727

Added "ilike()" operator to column operations.  Compiles to
ILIKE on postgres, lower(x) LIKE lower(y) on all
others.

.. change::
:tags: sql
:tickets: 943

Added "now()" as a generic function; on SQLite, Oracle
and MSSQL compiles as "CURRENT_TIMESTAMP"; "now()" on
all others.

.. change::
:tags: sql
:tickets: 962

The startswith(), endswith(), and contains() operators now
concatenate the wildcard operator with the given operand in
SQL, i.e. "'%' || <bindparam>" in all cases, accept
text('something') operands properly

.. change::
:tags: sql
:tickets: 962

cast() accepts text('something') and other non-literal
operands properly

.. change::
:tags: sql
:tickets:

fixed bug in result proxy where anonymously generated
column labels would not be accessible using their straight
string name

.. change::
:tags: sql
:tickets:

Deferrable constraints can now be defined.

.. change::
:tags: sql
:tickets: 915

Added "autocommit=True" keyword argument to select() and
text(), as well as generative autocommit() method on
select(); for statements which modify the database through
some user-defined means other than the usual INSERT/UPDATE/
DELETE etc.  This flag will enable "autocommit" behavior
during execution if no transaction is in progress.

.. change::
:tags: sql
:tickets:

The '.c.' attribute on a selectable now gets an entry for
every column expression in its columns clause.  Previously,
"unnamed" columns like functions and CASE statements weren't
getting put there.  Now they will, using their full string
representation if no 'name' is available.

.. change::
:tags: sql
:tickets:

a CompositeSelect, i.e. any union(), union_all(),
intersect(), etc. now asserts that each selectable contains
the same number of columns.  This conforms to the
corresponding SQL requirement.

.. change::
:tags: sql
:tickets:

The anonymous 'label' generated for otherwise unlabeled
functions and expressions now propagates outwards at compile
time for expressions like select([select([func.foo()])]).

.. change::
:tags: sql
:tickets:

Building on the above ideas, CompositeSelects now build up
their ".c." collection based on the names present in the
first selectable only; corresponding_column() now works
fully for all embedded selectables.

.. change::
:tags: sql
:tickets:

Oracle and others properly encode SQL used for defaults like
sequences, etc., even if no unicode idents are used since
identifier preparer may return a cached unicode identifier.

.. change::
:tags: sql
:tickets:

Column and clause comparisons to datetime objects on the
left hand side of the expression now work (d < table.c.col).
(datetimes on the RHS have always worked, the LHS exception
is a quirk of the datetime implementation.)

.. change::
:tags: orm
:tickets:

Every Session.begin() must now be accompanied by a
corresponding commit() or rollback() unless the session is
closed with Session.close().  This also includes the begin()
which is implicit to a session created with
transactional=True.  The biggest change introduced here is
that when a Session created with transactional=True raises
an exception during flush(), you must call
Session.rollback() or Session.close() in order for that
Session to continue after an exception.

.. change::
:tags: orm
:tickets: 961

Fixed merge() collection-doubling bug when merging transient
entities with backref'ed collections.

.. change::
:tags: orm
:tickets:

merge(dont_load=True) does not accept transient entities,
this is in continuation with the fact that
merge(dont_load=True) does not accept any "dirty" objects
either.

.. change::
:tags: orm
:tickets:

Added standalone "query" class attribute generated by a
scoped_session.  This provides MyClass.query without using
Session.mapper.  Use via:

MyClass.query = Session.query_property()

.. change::
:tags: orm
:tickets:

The proper error message is raised when trying to access
expired instance attributes with no session present

.. change::
:tags: orm
:tickets:

dynamic_loader() / lazy="dynamic" now accepts and uses
the order_by parameter in the same way in which it works
with relation().

.. change::
:tags: orm
:tickets:

Added expire_all() method to Session.  Calls expire() for
all persistent instances.  This is handy in conjunction
with...

.. change::
:tags: orm
:tickets:

Instances which have been partially or fully expired will
have their expired attributes populated during a regular
Query operation which affects those objects, preventing a
needless second SQL statement for each instance.

.. change::
:tags: orm
:tickets: 938

Dynamic relations, when referenced, create a strong
reference to the parent object so that the query still has a
parent to call against even if the parent is only created
(and otherwise dereferenced) within the scope of a single
expression.

.. change::
:tags: orm
:tickets:

Added a mapper() flag "eager_defaults". When set to True,
defaults that are generated during an INSERT or UPDATE
operation are post-fetched immediately, instead of being
deferred until later.  This mimics the old 0.3 behavior.

.. change::
:tags: orm
:tickets:

query.join() can now accept class-mapped attributes as
arguments. These can be used in place or in any combination
with strings.  In particular this allows construction of
joins to subclasses on a polymorphic relation, i.e.:

query(Company).join(['employees', Engineer.name])

.. change::
:tags: orm, ('employees', people.join(engineer)), Engineer.name
:tickets:

query.join() can also accept tuples of attribute name/some
selectable as arguments.  This allows construction of joins
*from* subclasses of a polymorphic relation, i.e.:

query(Company).\
join(

)

.. change::
:tags: orm
:tickets:

General improvements to the behavior of join() in
conjunction with polymorphic mappers, i.e. joining from/to
polymorphic mappers and properly applying aliases.

.. change::
:tags: orm
:tickets: 933

Fixed/improved behavior when a mapper determines the natural
"primary key" of a mapped join, it will more effectively
reduce columns which are equivalent via foreign key
relation.  This affects how many arguments need to be sent
to query.get(), among other things.

.. change::
:tags: orm
:tickets: 946

The lazy loader can now handle a join condition where the
"bound" column (i.e. the one that gets the parent id sent as
a bind parameter) appears more than once in the join
condition.  Specifically this allows the common task of a
relation() which contains a parent-correlated subquery, such
as "select only the most recent child item".

.. change::
:tags: orm
:tickets:

Fixed bug in polymorphic inheritance where an incorrect
exception is raised when base polymorphic_on column does not
correspond to any columns within the local selectable of an
inheriting mapper more than one level deep

.. change::
:tags: orm
:tickets:

Fixed bug in polymorphic inheritance which made it difficult
to set a working "order_by" on a polymorphic mapper.

.. change::
:tags: orm
:tickets:

Fixed a rather expensive call in Query that was slowing down
polymorphic queries.

.. change::
:tags: orm
:tickets: 954

"Passive defaults" and other "inline" defaults can now be
loaded during a flush() call if needed; in particular, this
allows constructing relations() where a foreign key column
references a server-side-generated, non-primary-key
column.

.. change::
:tags: orm
:tickets:

Additional Session transaction fixes/changes:
- Fixed bug with session transaction management: parent
transactions weren't started on the connection when
adding a connection to a nested transaction.

- session.transaction now always refers to the innermost
active transaction, even when commit/rollback are called
directly on the session transaction object.

- Two-phase transactions can now be prepared.

- When preparing a two-phase transaction fails on one
connection, all the connections are rolled back.

- session.close() didn't close all transactions when
nested transactions were used.

- rollback() previously erroneously set the current
transaction directly to the parent of the transaction
that could be rolled back to. Now it rolls back the next
transaction up that can handle it, but sets the current
transaction to its parent and inactivates the
transactions in between. Inactive transactions can only
be rolled back or closed, any other call results in an
error.

- autoflush for commit() wasn't flushing for simple
subtransactions.

- unitofwork flush didn't close the failed transaction
when the session was not in a transaction and committing
the transaction failed.

.. change::
:tags: orm
:tickets: 964, 940

Miscellaneous tickets:

.. change::
:tags: general
:tickets:

Fixed a variety of hidden and some not-so-hidden
compatibility issues for Python 2.3, thanks to new support
for running the full test suite on 2.3.

.. change::
:tags: general
:tickets:

Warnings are now issued as type exceptions.SAWarning.

.. change::
:tags: dialects
:tickets:

Better support for schemas in SQLite (linked in by ATTACH
DATABASE ... AS name).  In some cases in the past, schema
names were omitted from generated SQL for SQLite.  This is
no longer the case.

.. change::
:tags: dialects
:tickets:

table_names on SQLite now picks up temporary tables as well.

.. change::
:tags: dialects
:tickets:

Auto-detect an unspecified MySQL ANSI_QUOTES mode during
reflection operations, support for changing the mode
midstream.  Manual mode setting is still required if no
reflection is used.

.. change::
:tags: dialects
:tickets:

Fixed reflection of TIME columns on SQLite.

.. change::
:tags: dialects
:tickets: 580

Finally added PGMacAddr type to postgres

.. change::
:tags: dialects
:tickets:

Reflect the sequence associated to a PK field (typically
with a BEFORE INSERT trigger) under Firebird

.. change::
:tags: dialects
:tickets: 941

Oracle assembles the correct columns in the result set
column mapping when generating a LIMIT/OFFSET subquery,
allows columns to map properly to result sets even if
long-name truncation kicks in

.. change::
:tags: dialects
:tickets:

MSSQL now includes EXEC in the _is_select regexp, which
should allow row-returning stored procedures to be used.

.. change::
:tags: dialects
:tickets:

MSSQL now includes an experimental implementation of
LIMIT/OFFSET using the ANSI SQL row_number() function, so it
requires MSSQL-2005 or higher. To enable the feature, add
"has_window_funcs" to the keyword arguments for connect, or
add "?has_window_funcs=1" to your dburi query arguments.

.. change::
:tags: ext
:tickets:

Changed ext.activemapper to use a non-transactional session
for the objectstore.

.. change::
:tags: ext
:tickets:

Fixed output order of "['a'] + obj.proxied" binary operation
on association-proxied lists.

.. changelog::
:version: 0.4.2p3
:released: Wed Jan 09 2008

.. change::
:tags: general
:tickets:

sub version numbering scheme changed to suite
setuptools version number rules; easy_install -u
should now get this version over 0.4.2.

.. change::
:tags: sql
:tickets: 912

Text type is properly exported now and does not
raise a warning on DDL create; String types with no
length only raise warnings during CREATE TABLE

.. change::
:tags: sql
:tickets:

new UnicodeText type is added, to specify an
encoded, unlengthed Text type

.. change::
:tags: sql
:tickets:

fixed bug in union() so that select() statements
which don't derive from FromClause objects can be
unioned

.. change::
:tags: orm
:tickets:

fixed bug with session.dirty when using "mutable
scalars" (such as PickleTypes)

.. change::
:tags: orm
:tickets:

added a more descriptive error message when flushing
on a relation() that has non-locally-mapped columns
in its primary or secondary join condition

.. change::
:tags: dialects
:tickets:

Fixed reflection of mysql empty string column
defaults.

.. change::
:tags: sql
:tickets: 912

changed name of TEXT to Text since its a "generic"
type; TEXT name is deprecated until 0.5. The
"upgrading" behavior of String to Text when no
length is present is also deprecated until 0.5; will
issue a warning when used for CREATE TABLE
statements (String with no length for SQL expression
purposes is still fine)

.. change::
:tags: sql
:tickets: 924

generative select.order_by(None) / group_by(None)
was not managing to reset order by/group by
criterion, fixed

.. change::
:tags: orm
:tickets:

suppressing *all* errors in
InstanceState.__cleanup() now.

.. change::
:tags: orm
:tickets: 922

fixed an attribute history bug whereby assigning a
new collection to a collection-based attribute which
already had pending changes would generate incorrect
history

.. change::
:tags: orm
:tickets: 925

fixed delete-orphan cascade bug whereby setting the
same object twice to a scalar attribute could log it
as an orphan

.. change::
:tags: orm
:tickets:

Fixed cascades on a += assignment to a list-based
relation.

.. change::
:tags: orm
:tickets: 919

synonyms can now be created against props that don't
exist yet, which are later added via add_property().
This commonly includes backrefs. (i.e. you can make
synonyms for backrefs without worrying about the
order of operations)

.. change::
:tags: orm
:tickets:

fixed bug which could occur with polymorphic "union"
mapper which falls back to "deferred" loading of
inheriting tables

.. change::
:tags: orm
:tickets:

the "columns" collection on a mapper/mapped class
(i.e. 'c') is against the mapped table, not the
select_table in the case of polymorphic "union"
loading (this shouldn't be noticeable).

.. change::
:tags: ext
:tickets:

'+', '*', '+=' and '\*=' support for association
proxied lists.

.. change::
:tags: dialects
:tickets: 923

mssql - narrowed down the test for "date"/"datetime"
in MSDate/ MSDateTime subclasses so that incoming
"datetime" objects don't get mis-interpreted as
"date" objects and vice versa.

.. change::
:tags: orm
:tickets:

fixed fairly critical bug whereby the same instance could be listed
more than once in the unitofwork.new collection; most typically
reproduced when using a combination of inheriting mappers and
ScopedSession.mapper, as the multiple __init__ calls per instance
could save() the object with distinct _state objects

.. change::
:tags: orm
:tickets:

added very rudimentary yielding iterator behavior to Query.  Call
query.yield_per(<number of rows>) and evaluate the Query in an
iterative context; every collection of N rows will be packaged up
and yielded.  Use this method with extreme caution since it does
not attempt to reconcile eagerly loaded collections across
result batch boundaries, nor will it behave nicely if the same
instance occurs in more than one batch.  This means that an eagerly
loaded collection will get cleared out if it's referenced in more than
one batch, and in all cases attributes will be overwritten on instances
that occur in more than one batch.

.. change::
:tags: orm
:tickets: 920

Fixed in-place set mutation operators for set collections and association
proxied sets.

.. change::
:tags: dialects
:tickets: 913

Fixed the missing call to subtype result processor for the PGArray
type.

.. changelog::

0.4.2

:released: Wed Jan 02 2008

.. change::
:tags: sql
:tickets: 615

generic functions ! we introduce a database of known SQL functions, such
as current_timestamp, coalesce, and create explicit function objects
representing them. These objects have constrained argument lists, are
type aware, and can compile in a dialect-specific fashion. So saying
func.char_length("foo", "bar") raises an error (too many args),
func.coalesce(datetime.date(2007, 10, 5), datetime.date(2005, 10, 15))
knows that its return type is a Date. We only have a few functions
represented so far but will continue to add to the system

.. change::
:tags: sql
:tickets:

auto-reconnect support improved; a Connection can now automatically
reconnect after its underlying connection is invalidated, without
needing to connect() again from the engine.  This allows an ORM session
bound to a single Connection to not need a reconnect.
Open transactions on the Connection must be rolled back after an invalidation
of the underlying connection else an error is raised.  Also fixed
bug where disconnect detect was not being called for cursor(), rollback(),
or commit().

.. change::
:tags: sql
:tickets:

added new flag to String and create_engine(),
assert_unicode=(True|False|'warn'\|None). Defaults to `False` or `None` on
create_engine() and String, `'warn'` on the Unicode type. When `True`,
results in all unicode conversion operations raising an exception when a
non-unicode bytestring is passed as a bind parameter. 'warn' results
in a warning. It is strongly advised that all unicode-aware applications
make proper use of Python unicode objects (i.e. u'hello' and not 'hello')
so that data round trips accurately.

.. change::
:tags: sql
:tickets:

generation of "unique" bind parameters has been simplified to use the same
"unique identifier" mechanisms as everything else.  This doesn't affect
user code, except any code that might have been hardcoded against the generated
names.  Generated bind params now have the form "<paramname>_<num>",
whereas before only the second bind of the same name would have this form.

.. change::
:tags: sql
:tickets:

select().as_scalar() will raise an exception if the select does not have
exactly one expression in its columns clause.

.. change::
:tags: sql
:tickets:

bindparam() objects themselves can be used as keys for execute(), i.e.
statement.execute({bind1:'foo', bind2:'bar'})

.. change::
:tags: sql
:tickets:

added new methods to TypeDecorator, process_bind_param() and
process_result_value(), which automatically take advantage of the processing
of the underlying type.  Ideal for using with Unicode or Pickletype.
TypeDecorator should now be the primary way to augment the behavior of any
existing type including other TypeDecorator subclasses such as PickleType.

.. change::
:tags: sql
:tickets:

selectables (and others) will issue a warning when two columns in
their exported columns collection conflict based on name.

.. change::
:tags: sql
:tickets: 890

tables with schemas can still be used in sqlite, firebird,
schema name just gets dropped

.. change::
:tags: sql
:tickets:

changed the various "literal" generation functions to use an anonymous
bind parameter.  not much changes here except their labels now look
like ":param_1", ":param_2" instead of ":literal"

.. change::
:tags: sql
:tickets:

column labels in the form "tablename.columname", i.e. with a dot, are now
supported.

.. change::
:tags: sql
:tickets:

from_obj keyword argument to select() can be a scalar or a list.

.. change::
:tags: orm
:tickets: 871

a major behavioral change to collection-based backrefs: they no
longer trigger lazy loads !  "reverse" adds and removes
are queued up and are merged with the collection when it is
actually read from and loaded; but do not trigger a load beforehand.
For users who have noticed this behavior, this should be much more
convenient than using dynamic relations in some cases; for those who
have not, you might notice your apps using a lot fewer queries than
before in some situations.

.. change::
:tags: orm
:tickets:

mutable primary key support is added. primary key columns can be
changed freely, and the identity of the instance will change upon
flush. In addition, update cascades of foreign key referents (primary
key or not) along relations are supported, either in tandem with the
database's ON UPDATE CASCADE (required for DB's like Postgres) or
issued directly by the ORM in the form of UPDATE statements, by setting
the flag "passive_cascades=False".

.. change::
:tags: orm
:tickets: 490

inheriting mappers now inherit the MapperExtensions of their parent
mapper directly, so that all methods for a particular MapperExtension
are called for subclasses as well.  As always, any MapperExtension
can return either EXT_CONTINUE to continue extension processing
or EXT_STOP to stop processing.  The order of mapper resolution is:
<extensions declared on the classes mapper> <extensions declared on the
classes' parent mapper> <globally declared extensions>.

Note that if you instantiate the same extension class separately
and then apply it individually for two mappers in the same inheritance
chain, the extension will be applied twice to the inheriting class,
and each method will be called twice.

To apply a mapper extension explicitly to each inheriting class but
have each method called only once per operation, use the same
instance of the extension for both mappers.

.. change::
:tags: orm
:tickets: 907

MapperExtension.before_update() and after_update() are now called
symmetrically; previously, an instance that had no modified column
attributes (but had a relation() modification) could be called with
before_update() but not after_update()

.. change::
:tags: orm
:tickets:

columns which are missing from a Query's select statement
now get automatically deferred during load.

.. change::
:tags: orm
:tickets: 908

mapped classes which extend "object" and do not provide an
__init__() method will now raise TypeError if non-empty \*args
or \**kwargs are present at instance construction time (and are
not consumed by any extensions such as the scoped_session mapper),
consistent with the behavior of normal Python classes

.. change::
:tags: orm
:tickets: 899

fixed Query bug when filter_by() compares a relation against None

.. change::
:tags: orm
:tickets:

improved support for pickling of mapped entities.  Per-instance
lazy/deferred/expired callables are now serializable so that
they serialize and deserialize with _state.

.. change::
:tags: orm
:tickets: 801

new synonym() behavior: an attribute will be placed on the mapped
class, if one does not exist already, in all cases. if a property
already exists on the class, the synonym will decorate the property
with the appropriate comparison operators so that it can be used in
column expressions just like any other mapped attribute (i.e. usable in
filter(), etc.) the "proxy=True" flag is deprecated and no longer means
anything. Additionally, the flag "map_column=True" will automatically
generate a ColumnProperty corresponding to the name of the synonym,
i.e.: 'somename':synonym('_somename', map_column=True) will map the
column named 'somename' to the attribute '_somename'. See the example
in the mapper docs.

.. change::
:tags: orm
:tickets:

Query.select_from() now replaces all existing FROM criterion with
the given argument; the previous behavior of const