Release notes from sqlalchemy

2.0.48

2026-03-02T16:07:48Z

2.0.48

Released: March 2, 2026

engine

[engine] [bug] Fixed a critical issue in Engine where connections created in
conjunction with the DialectEvents.do_connect() event listeners
would receive shared, mutable collections for the connection arguments,
leading to a variety of potential issues including unlimited growth of the
argument list as well as elements within the parameter dictionary being
shared among concurrent connection calls. In particular this could impact
do_connect routines making use of complex mutable authentication
structures.

References: #13144

2.0.47

2026-02-24T17:28:51Z

2.0.47

Released: February 24, 2026

orm

[orm] [bug] Fixed issue when using ORM mappings with Python 3.14's PEP 649 feature
that no longer requires "future annotations", where the ORM's introspection
of the __init__ method of mapped classes would fail if non-present
identifiers in annotations were present. The vendored getfullargspec()
method has been amended to use Format.FORWARDREF under Python 3.14 to
prevent resolution of names that aren't present.

References: #13104

engine

[engine] [usecase] The connection object returned by _engine.Engine.raw_connection()
now supports the context manager protocol, automatically returning the
connection to the pool when exiting the context.

References: #13116

postgresql

[postgresql] [bug] Fixed an issue in the PostgreSQL dialect where foreign key constraint
reflection would incorrectly swap or fail to capture onupdate and
ondelete values when these clauses appeared in a different order than
expected in the constraint definition. This issue primarily affected
PostgreSQL-compatible databases such as CockroachDB, which may return ON DELETE before ON UPDATE in the constraint definition string. The
reflection logic now correctly parses both clauses regardless of their
ordering.

References: #13105
[postgresql] [bug] Fixed issue in the engine_insertmanyvalues feature where using
PostgreSQL's ON CONFLICT clause with
_dml.Insert.returning.sort_by_parameter_order enabled would
generate invalid SQL when the insert used an implicit sentinel (server-side
autoincrement primary key). The generated SQL would incorrectly declare a
sentinel counter column in the imp_sen table alias without providing
corresponding values in the VALUES clause, leading to a
ProgrammingError indicating column count mismatch. The fix allows batch
execution mode when embed_values_counter is active, as the embedded
counter provides the ordering capability needed even with upsert behaviors,
rather than unnecessarily downgrading to row-at-a-time execution.

References: #13107
[postgresql] [bug] Fixed issue where _postgresql.Insert.on_conflict_do_update()
parameters were not respecting compilation options such as
literal_binds=True. Pull request courtesy Loïc Simon.

References: #13110
[postgresql] [bug] Fixed issue where _postgresql.Insert.on_conflict_do_update()
using parametrized bound parameters in the set_ clause would fail
when used with executemany batching. For dialects that use the
use_insertmanyvalues_wo_returning optimization (psycopg2),
insertmanyvalues is now disabled when there is an ON CONFLICT clause.
For cases with RETURNING, row-at-a-time mode is used when the SET
clause contains parametrized bindparams (bindparams that receive
values from the parameters dict), ensuring each row's parameters are
correctly applied. ON CONFLICT statements using expressions like
excluded.<column> continue to batch normally.

References: #13130

mysql

[mysql] [bug] Fixed issue where DDL compilation options were registered to the hard-coded
dialect name mysql. This made it awkward for MySQL-derived dialects
like MariaDB, StarRocks, etc. to work with such options when different sets
of options exist for different platforms. Options are now registered under
the actual dialect name, and a fallback was added to help avoid errors when
an option does not exist for that dialect.

To maintain backwards compatibility, when using the MariaDB dialect with
the options mysql_with_parser or mysql_using without also specifying
the corresponding mariadb_ prefixed options, a deprecation warning will
be emitted. The mysql_ prefixed options will continue to work during
the deprecation period. Users should update their code to additionally
specify mariadb_with_parser and mariadb_using when using the
mariadb:// dialect, or specify both options to support both dialects.

Pull request courtesy Tiansu Yu.

References: #13134

sqlite

[sqlite] [bug] Fixed issue where _sqlite.Insert.on_conflict_do_update()
parameters were not respecting compilation options such as
literal_binds=True. Pull request courtesy Loïc Simon.

References: #13110
[sqlite] [bug] Fixed issue where _sqlite.Insert.on_conflict_do_update()
using parametrized bound parameters in the set_ clause would fail
when used with executemany batching. Row-at-a-time mode is now used
for ON CONFLICT statements with RETURNING that contain parametrized
bindparams, ensuring each row's parameters are correctly applied. ON
CONFLICT statements using expressions like excluded.<column>
continue to batch normally.

References: #13130

2.1.0b1

2026-01-21T21:19:04Z

2.1.0b1

Released: January 21, 2026

platform

[platform] [feature] Free-threaded Python versions are now supported in wheels released on Pypi.
This integrates with overall free-threaded support added as part of
#12881 for the 2.0 and 2.1 series, which includes new test suites
as well as a few improvements to race conditions observed under
freethreading.

References: #12881
[platform] [change] The greenlet dependency used for asyncio support no longer installs
by default. This dependency does not publish wheel files for every architecture
and is not needed for applications that aren't using asyncio features.
Use the sqlalchemy[asyncio] install target to include this dependency.

References: #10197
[platform] [change] Updated the setup manifest definition to use PEP 621-compliant
pyproject.toml. Also updated the extra install dependency to comply with
PEP-685. Thanks for the help of Matt Oberle and KOLANICH on this change.
[platform] [change] Python 3.10 or above is now required; support for Python 3.9, 3.8 and 3.7
is dropped as these versions are EOL.

References: #10357, #12029, #12819

orm

[orm] [feature] The _orm.relationship.back_populates argument to
_orm.relationship() may now be passed as a Python callable, which
resolves to either the direct linked ORM attribute, or a string value as
before. ORM attributes are also accepted directly by
_orm.relationship.back_populates. This change allows type
checkers and IDEs to confirm the argument for
_orm.relationship.back_populates is valid. Thanks to Priyanshu
Parikh for the help on suggesting and helping to implement this feature.

References: #10050
[orm] [feature] Added new hybrid method hybrid_property.bulk_dml() which
works in a similar way as hybrid_property.update_expression() for
bulk ORM operations. A user-defined class method can now populate a bulk
insert mapping dictionary using the desired hybrid mechanics. New
documentation is added showing how both of these methods can be used
including in combination with the new _sql.from_dml_column()
construct.

References: #12496
[orm] [feature] Added new parameter _orm.composite.return_none_on to
_orm.composite(), which allows control over if and when this
composite attribute should resolve to None when queried or retrieved
from the object directly. By default, a composite object is always present
on the attribute, including for a pending object which is a behavioral
change since 2.0. When _orm.composite.return_none_on is
specified, a callable is passed that returns True or False to indicate if
the given arguments indicate the composite should be returned as None. This
parameter may also be set automatically when ORM Annotated Declarative is
used; if the annotation is given as Mapped[SomeClass|None], a
_orm.composite.return_none_on rule is applied that will return
None if all contained columns are themselves None.

References: #12570
[orm] [feature] Added support for per-session execution options that are merged into all
queries executed within that session. The _orm.Session,
_orm.sessionmaker, _orm.scoped_session,
_ext.asyncio.AsyncSession, and
_ext.asyncio.async_sessionmaker constructors now accept an
_orm.Session.execution_options parameter that will be applied
to all explicit query executions (e.g. using _orm.Session.execute(),
_orm.Session.get(), _orm.Session.scalars()) for that session
instance.

References: #12659
[orm] [feature] Session autoflush behavior has been simplified to unconditionally flush the
session each time an execution takes place, regardless of whether an ORM
statement or Core statement is being executed. This change eliminates the
previous conditional logic that only flushed when ORM-related statements
were detected, which had become difficult to define clearly with the unified
v2 syntax that allows both Core and ORM execution patterns. The change
provides more consistent and predictable session behavior across all types
of SQL execution.

References: #9809
[orm] [feature] Added _orm.RegistryEvents event class that allows event listeners
to be established on a _orm.registry object. The new class
provides three events: _orm.RegistryEvents.resolve_type_annotation()
which allows customization of type annotation resolution that can
supplement or replace the use of the
registry.type_annotation_map dictionary, including that it can
be helpful with custom resolution for complex types such as those of
PEP 695, as well as _orm.RegistryEvents.before_configured() and
_orm.RegistryEvents.after_configured(), which are registry-local
forms of the mapper-wide version of these hooks.

References: #9832
[orm] [usecase] The _orm.Session.flush.objects parameter is now
deprecated.

References: #10816
[orm] [usecase] Added the utility method _orm.Session.merge_all() and
_orm.Session.delete_all() that operate on a collection
of instances.

References: #11776
[orm] [usecase] Added support for using _orm.with_expression() to populate a
_orm.query_expression() attribute that is also configured as the
polymorphic_on discriminator column. The ORM now detects when a query
expression column is serving as the polymorphic discriminator and updates
it to use the column provided via _orm.with_expression(), enabling
polymorphic loading to work correctly in this scenario. This allows for
patterns such as where the discriminator value is computed from a related
table.

References: #12631
[orm] [usecase] Added default implementations of ColumnOperators.desc(),
ColumnOperators.asc(), ColumnOperators.nulls_first(),
ColumnOperators.nulls_last() to _orm.composite() attributes,
by default applying the modifier to all contained columns. Can be
overridden using a custom comparator.

References: #12769
[orm] [usecase] The _orm.aliased() object now emits warnings when an attribute is
accessed on an aliased class that cannot be located in the target
selectable, for those cases where the _orm.aliased() is against a
different FROM clause than the regular mapped table (such as a subquery).
This helps users identify cases where column names don't match between the
aliased class and the underlying selectable. When
_orm.aliased.adapt_on_names is True, the warning suggests
checking the column name; when False, it suggests using the
adapt_on_names parameter for name-based matching.

References: #12838
[orm] [usecase] Improvements to the use case of using Declarative Dataclass Mapping <orm_declarative_native_dataclasses> with intermediary classes that are
unmapped. As was the existing behavior, classes can subclass
_orm.MappedAsDataclass alone without a declarative base to act as
mixins, or along with a declarative base as well as __abstract__ = True
to define an abstract base. However, the improved behavior scans ORM
attributes like _orm.mapped_column() in this case to create correct
dataclasses.field() constructs based on their arguments, allowing for
more natural ordering of fields without dataclass errors being thrown.
Additionally, added a new _orm.unmapped_dataclass() decorator
function, which may be used to create unmapped mixins in a mapped hierarchy
that is using the _orm.mapped_dataclass() decorator to create mapped
dataclasses.

References: #12854
[orm] [usecase] Added _orm.DictBundle as a subclass of _orm.Bundle
that returns dict objects.

References: #12960
[orm] [change] A sweep through class and function names in the ORM renames many classes
and functions that have no intent of public visibility to be underscored.
This is to reduce ambiguity as to which APIs are intended to be targeted by
third party applications and extensions. Third parties are encouraged to
propose new public APIs in Discussions to the extent they are needed to
replace those that have been clarified as private.

References: #10497
[orm] [change] The first_init ORM event has been removed. This event was
non-functional throughout the 1.4 and 2.0 series and could not be invoked
without raising an internal error, so it is not expected that there is any
real-world use of this event hook.

References: #10500
[orm] [change] Removed legacy signatures dating back to 0.9 release from the
_orm.SessionEvents.after_bulk_update() and
_orm.SessionEvents.after_bulk_delete().

References: #10721
[orm] [changed] The "non primary" mapper feature, long deprecated in SQLAlchemy since
version 1.3, has been removed. The sole use case for "non primary"
mappers was that of using _orm.relationship() to link to a mapped
class against an alternative selectable; this use case is now suited by the
relationship_aliased_class feature.

References: #12437
[orm] [bug] The _orm.relationship.secondary parameter no longer uses Python
eval() to evaluate the given string. This parameter when passed a
string should resolve to a table name that's present in the local
MetaData collection only, and never needs to be any kind of
Python expression otherwise. To use a real deferred callable based on a
name that may not be locally present yet, use a lambda instead.

References: #10564
[orm] [bug] Fixed issue where joined eager loading would fail to use the "nested" form
of the query when GROUP BY or DISTINCT were present if the eager joins
being added were many-to-ones, leading to additional columns in the columns
clause which would then cause errors. The check for "nested" is tuned to
be enabled for these queries even for many-to-one joined eager loaders, and
the "only do nested if it's one to many" aspect is now localized to when
the query only has LIMIT or OFFSET added.

References: #11226
[orm] [bug] Revised the set "binary" operators for the association proxy set()
interface to correctly raise TypeError for invalid use of the |,
&, ^, and - operators, as well as the in-place mutation
versions of these methods, to match the behavior of standard Python
set() as well as SQLAlchemy ORM's "instrumented" set implementation.

References: #11349
[orm] [bug] A significant behavioral change has been made to the behavior of the
_orm.mapped_column.default and
_orm.relationship.default parameters, as well as the
_orm.relationship.default_factory parameter with
collection-based relationships, when used with SQLAlchemy's
orm_declarative_native_dataclasses feature introduced in 2.0, where
the given value (assumed to be an immutable scalar value for
_orm.mapped_column.default and a simple collection class for
_orm.relationship.default_factory) is no longer passed to the
@dataclass API as a real default, instead a token that leaves the value
un-set in the object's __dict__ is used, in conjunction with a
descriptor-level default. This prevents an un-set default value from
overriding a default that was actually set elsewhere, such as in
relationship / foreign key assignment patterns as well as in
_orm.Session.merge() scenarios. See the full writeup in the
migration_21_toplevel document which includes guidance on how to
re-enable the 2.0 version of the behavior if needed.

References: #12168
[orm] [bug] The behavior of _orm.with_polymorphic() when used with a single
inheritance mapping has been changed such that its behavior should match as
closely as possible to that of an equivalent joined inheritance mapping.
Specifically this means that the base class specified in the
_orm.with_polymorphic() construct will be the basemost class that is
loaded, as well as all descendant classes of that basemost class.
The change includes that the descendant classes named will no longer be
exclusively indicated in "WHERE polymorphic_col IN" criteria; instead, the
whole hierarchy starting with the given basemost class will be loaded. If
the query indicates that rows should only be instances of a specific
subclass within the polymorphic hierarchy, an error is raised if an
incompatible superclass is loaded in the result since it cannot be made to
match the requested class; this behavior is the same as what joined
inheritance has done for many years. The change also allows a single result
set to include column-level results from multiple sibling classes at once
which was not previously possible with single table inheritance.

References: #12395
[orm] [bug] Improved the behavior of standalone "operators" like _sql.desc(),
_sql.asc(), _sql.all_(), etc. so that they consult the given
expression object for an overriding method for that operator, even if the
object is not itself a ClauseElement, such as if it's an ORM attribute.
This allows custom comparators for things like _orm.composite() to
provide custom implementations of methods like desc(), asc(), etc.

References: #12769
[orm] [bug] ORM entities can now be involved within the SQL expressions used within
_orm.relationship.primaryjoin and
_orm.relationship.secondaryjoin parameters without the ORM
entity information being implicitly sanitized, allowing ORM-specific
features such as single-inheritance criteria in subqueries to continue
working even when used in this context. This is made possible by overall
ORM simplifications that occurred as of the 2.0 series. The changes here
also provide a performance boost (up to 20%) for certain query compilation
scenarios.

References: #12843
[orm] [bug] The _events.SessionEvents.do_orm_execute() event now allows direct
mutation or replacement of the ORMExecuteState.parameters
dictionary or list, which will take effect when the the statement is
executed. Previously, changes to this collection were not accommodated by
the event hook. Pull request courtesy Shamil.

References: #12921
[orm] [bug] A change in the mechanics of how Python dataclasses are applied to classes
that use MappedAsDataclass or
registry.mapped_as_dataclass() to apply __annotations__ that are
as identical as is possible to the original __annotations__ given,
while also adding attributes that SQLAlchemy considers to be part of
dataclass __annotations__, then restoring the previous annotations in
exactly the same format as they were, using patterns that work with
PEP 649 as closely as possible.

References: #13021
[orm] [bug] Removed the ORDER BY clause from queries generated by
_orm.selectin_polymorphic() and the
_orm.Mapper.polymorphic_load parameter set to "selectin".
The ORDER BY clause appears to have been an unnecessary implementation
artifact.

References: #13060
[orm] [bug] A significant change to the ORM mechanics involved with both
orm.with_loader_criteria() as well as single table inheritance, to
more aggressively locate WHERE criteria which should be augmented by either
the custom criteria or single-table inheritance criteria; SELECT statements
that do not include the entity within the columns clause or as an explicit
FROM, but still reference the entity within the WHERE clause, are now
covered, in particular this will allow subqueries using EXISTS (SELECT 1) such as those rendered by RelationshipProperty.Comparator.any()
and RelationshipProperty.Comparator.has().

References: #13070
[orm] The _orm.noload() relationship loader option and related
lazy='noload' setting is deprecated and will be removed in a future
release. This option was originally intended for custom loader patterns
that are no longer applicable in modern SQLAlchemy.

References: #11045
[orm] Ignore _orm.Session.join_transaction_mode in all cases when
the bind provided to the _orm.Session is an
_engine.Engine.
Previously if an event that executed before the session logic,
like _engine.ConnectionEvents.engine_connect(),
left the connection with an active transaction, the
_orm.Session.join_transaction_mode behavior took
place, leading to a surprising behavior.

References: #11163

engine

[engine] [usecase] Added new execution option
_engine.Connection.execution_options.driver_column_names. This
option disables the "name normalize" step that takes place against the
DBAPI cursor.description for uppercase-default backends like Oracle,
and will cause the keys of a result set (e.g. named tuple names, dictionary
keys in Row._mapping, etc.) to be exactly what was delivered in
cursor.description. This is mostly useful for plain textual statements
using _sql.text() or _engine.Connection.exec_driver_sql().

References: #10789
[engine] [change] An empty sequence passed to any execute() method now
raised a deprecation warning, since such an executemany
is invalid.
Pull request courtesy of Carlos Sousa.

References: #9647
[engine] [change] The private method Connection._execute_compiled is removed. This method may
have been used for some special purposes however the SQLCompiler
object has lots of special state that should be set up for an execute call,
which we don't support.
[engine] [bug] Fixed issue in "insertmanyvalues" feature where an INSERT..RETURNING
that also made use of a sentinel column to track results would fail to
filter out the additional column when Result.unique() were used
to uniquify the result set.

References: #10802
[engine] [bug] Adjusted URL parsing and stringification to apply url quoting to the
"database" portion of the URL. This allows a URL where the "database"
portion includes special characters such as question marks to be
accommodated.

References: #11234
[engine] [bug] Fixed issue in the ConnectionEvents.after_cursor_execute() method
where the SQL statement and parameter list for an "insertmanyvalues"
operation sent to the event would not be the actual SQL / parameters just
emitted on the cursor, instead being the non-batched form of the statement
that's used as a template to generate the batched statements.

References: #13018

sql

[sql] [feature] Added the ability to create custom SQL constructs that can define new
clauses within SELECT, INSERT, UPDATE, and DELETE statements without
needing to modify the construction or compilation code of of
Select, _sql.Insert, Update, or Delete
directly. Support for testing these constructs, including caching support,
is present along with an example test suite. The use case for these
constructs is expected to be third party dialects for analytical SQL
(so-called NewSQL) or other novel styles of database that introduce new
clauses to these statements. A new example suite is included which
illustrates the QUALIFY SQL construct used by several NewSQL databases
which includes a cacheable implementation as well as a test suite.

References: #12195
[sql] [feature] [core] The Core operator system now includes the matmul operator, i.e. the
@ operator in Python as an optional operator.
In addition to the __matmul__ and __rmatmul__ operator support
this change also adds the missing __rrshift__ and __rlshift__.
Pull request courtesy Aramís Segovia.

References: #12479
[sql] [feature] Added new Core feature _sql.from_dml_column() that may be used in
expressions inside of UpdateBase.values() for INSERT or UPDATE; this
construct will copy whatever SQL expression is used for the given target
column in the statement to be used with additional columns. The construct
is mostly intended to be a helper with ORM hybrid_property within
DML hooks.

References: #12496
[sql] [feature] Added support for Python 3.14+ template strings (t-strings) via the new
_sql.tstring() construct. This feature makes use of Python 3.14
template strings as defined in PEP 750, allowing for ergonomic SQL
statement construction by automatically interpolating Python values and
SQLAlchemy expressions within template strings.

References: #12548
[sql] [usecase] Added new generalized aggregate function ordering to functions via the
_functions.FunctionElement.aggregate_order_by() method, which
receives an expression and generates the appropriate embedded "ORDER BY" or
"WITHIN GROUP (ORDER BY)" phrase depending on backend database. This new
function supersedes the use of the PostgreSQL
_postgresql.aggregate_order_by() function, which remains present for
backward compatibility. To complement the new parameter, the
_functions.aggregate_strings.order_by which adds ORDER BY
capability to the _functions.aggregate_strings dialect-agnostic
function which works for all included backends. Thanks much to Reuven
Starodubski with help on this patch.

References: #12853
[sql] [usecase] Changed the query style for ORM queries emitted by Session.get() as
well as many-to-one lazy load queries to use the default labeling style,
_sql.SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY, which normally
does not apply labels to columns in a SELECT statement. Previously, the
older style _sql.SelectLabelStyle.LABEL_STYLE_TABLENAME_PLUS_COL
that labels columns as _ was used for
Session.get() to maintain compatibility with _orm.Query.
The change allows the string representation of ORM queries to be less
verbose in all cases outside of legacy _orm.Query use. Pull
request courtesy Inada Naoki.

References: #12932
[sql] [usecase] Added method TableClause.insert_column() to complement
TableClause.append_column(), which inserts the given column at a
specific index. This can be helpful for prepending primary key columns to
tables, etc.

References: #7910
[sql] [usecase] Added support for the pow operator (**), with a default SQL
implementation of the POW() function. On Oracle Database, PostgreSQL
and MSSQL it renders as POWER(). As part of this change, the operator
routes through a new first class func member _functions.pow,
which renders on Oracle Database, PostgreSQL and MSSQL as POWER().

References: #8579
[sql] [usecase] [orm] The _sql.Select.filter_by(), _sql.Update.filter_by() and
_sql.Delete.filter_by() methods now search across all entities
present in the statement, rather than limiting their search to only the
last joined entity or the first FROM entity. This allows these methods
to locate attributes unambiguously across multiple joined tables,
resolving issues where changing the order of operations such as
_sql.Select.with_only_columns() would cause the method to fail.

If an attribute name exists in more than one FROM clause entity, an
_exc.AmbiguousColumnError is now raised, indicating that
_sql.Select.filter() (or _sql.Select.where()) should be used
instead with explicit table-qualified column references.

References: #8601
[sql] [change] The .c and .columns attributes on the Select and
TextualSelect constructs, which are not instances of
FromClause, have been removed completely, in addition to the
.select() method as well as other codepaths which would implicitly
generate a subquery from a Select without the need to explicitly
call the Select.subquery() method.

In the case of .c and .columns, these attributes were never useful
in practice and have caused a great deal of confusion, hence were
deprecated back in version 1.4, and have emitted warnings since that
version. Accessing the columns that are specific to a Select
construct is done via the Select.selected_columns attribute, which
was added in version 1.4 to suit the use case that users often expected
.c to accomplish. In the larger sense, implicit production of
subqueries works against SQLAlchemy's modern practice of making SQL
structure as explicit as possible.

Note that this is not related to the usual FromClause.c and
FromClause.columns attributes, common to objects such as
Table and Subquery, which are unaffected by this
change.

References: #10236
[sql] [change] the Numeric and Float SQL types have been separated out
so that Float no longer inherits from Numeric; instead,
they both extend from a common mixin NumericCommon. This
corrects for some architectural shortcomings where numeric and float types
are typically separate, and establishes more consistency with
Integer also being a distinct type. The change should not have
any end-user implications except for code that may be using
isinstance() to test for the Numeric datatype; third party
dialects which rely upon specific implementation types for numeric and/or
float may also require adjustment to maintain compatibility.

References: #5252
[sql] [change] Added new implementation for the Select.params() method and that of
similar statements, via a new statement-only
ExecutableStatement.params() method which works more efficiently and
correctly than the previous implementations available from
ClauseElement, by associating the given parameter dictionary with
the statement overall rather than cloning the statement and rewriting its
bound parameters. The _sql.ClauseElement.params() and
_sql.ClauseElement.unique_params() methods, when called on an object
that does not implement ExecutableStatement, will continue to
work the old way of cloning the object, and will emit a deprecation
warning. This issue both resolves the architectural / performance
concerns of #7066 and also provides correct ORM compatibility for
functions like _orm.aliased(), reported by #12915.

References: #12915, #7066
[sql] [bug] The Double type is now used when a Python float value is detected
as a literal value to be sent as a bound parameter, rather than the
Float type. Double has the same implementation as
Float, but when rendered in a CAST, produces DOUBLE or
DOUBLE PRECISION rather than FLOAT. The former better matches
Python's float datatype which uses 8-byte double-precision storage.
Third party dialects which don't support the Double type directly
may need adjustment so that they render an appropriate keyword (e.g.
FLOAT) when the Double datatype is encountered.

References: #10300
[sql] [bug] Fixed issue in name normalization (e.g. "uppercase" backends like Oracle)
where using a TextualSelect would not properly maintain as
uppercase column names that were quoted as uppercase, even though
the TextualSelect includes a Column that explicitly
holds this uppercase name.

References: #10788
[sql] [bug] Enhanced the caching structure of the _expression.over.rows
and _expression.over.range so that different numerical
values for the rows /
range fields are cached on the same cache key, to the extent that the
underlying SQL does not actually change (i.e. "unbounded", "current row",
negative/positive status will still change the cache key). This prevents
the use of many different numerical range/rows value for a query that is
otherwise identical from filling up the SQL cache.

Note that the semi-private compiler method _format_frame_clause()
is removed by this fix, replaced with a new method
visit_frame_clause(). Third party dialects which may have referred
to this method will need to change the name and revise the approach to
rendering the correct SQL for that dialect.

References: #11515
[sql] [bug] Updated the _sql.over() clause to allow non integer values in
_sql.over.range_ clause. Previously, only integer values
were allowed and any other values would lead to a failure.
To specify a non-integer value, use the new _sql.FrameClause
construct along with the new _sql.FrameClauseType enum to specify
the frame boundaries. For example:

from sqlalchemy import FrameClause, FrameClauseType

select(
func.sum(table.c.value).over(
range_=FrameClause(
3.14,
2.71,
FrameClauseType.PRECEDING,
FrameClauseType.FOLLOWING,
)
)
)References: #12596
[sql] [bug] Added a new concept of "operator classes" to the SQL operators supported by
SQLAlchemy, represented within the enum OperatorClass. The
purpose of this structure is to provide an extra layer of validation when a
particular kind of SQL operation is used with a particular datatype, to
catch early the use of an operator that does not have any relevance to the
datatype in use; a simple example is an integer or numeric column used with
a "string match" operator.

References: #12736
[sql] [bug] Fixed an issue in _sql.Select.join_from() where the join condition
between the left and right tables specified in the method call could be
incorrectly determined based on an intermediate table already present in
the FROM clause, rather than matching the foreign keys between the
immediate left and right arguments. The join condition is now determined by
matching primary keys between the two tables explicitly passed to
_sql.Select.join_from(), ensuring consistent and predictable join
behavior regardless of the order of join operations or other tables present
in the query. The fix is applied to both the Core and ORM implementations
of _sql.Select.join_from().

References: #12931
[sql] [bug] Fixed issue where anonymous label generation for CTE constructs
could produce name collisions when Python's garbage collector reused memory
addresses during complex query compilation. The anonymous name generation
for CTE and other aliased constructs like Alias,
Subquery and others now use os.urandom() to generate unique
identifiers instead of relying on object id(), ensuring uniqueness even
in cases of aggressive garbage collection and memory reuse.

References: #12990
[sql] Removed the automatic coercion of executable objects, such as
_orm.Query, when passed into _orm.Session.execute().
This usage raised a deprecation warning since the 1.4 series.

References: #12218

schema

[schema] [feature] Added support for the SQL CREATE VIEW statement via the new
CreateView DDL class. The new class allows creating database
views from SELECT statements, with support for options such as
TEMPORARY, IF NOT EXISTS, and MATERIALIZED where supported by
the target database. Views defined with CreateView integrate with
MetaData for automated DDL generation and provide a
Table object for querying.

References: #181
[schema] [feature] Added support for the SQL CREATE TABLE ... AS SELECT construct via the
new _schema.CreateTableAs DDL construct and the
_sql.Select.into() method. The new construct allows creating a
table directly from the results of a SELECT statement, with support for
options such as TEMPORARY and IF NOT EXISTS where supported by the
target database. Tables defined with _schema.CreateTableAs
integrate with MetaData for automated DDL generation and provide
a Table object for querying. Pull request courtesy Greg Jarzab.

References: #4950
[schema] [usecase] The the parameter _schema.DropConstraint.isolate_from_table
was deprecated since it has no effect on the drop table behavior.
Its default values was also changed to False.

References: #13006
[schema] [bug] The Float and Numeric types are no longer automatically
considered as auto-incrementing columns when the
_schema.Column.autoincrement parameter is left at its default
of "auto" on a _schema.Column that is part of the primary key.
When the parameter is set to True, a Numeric type will be
accepted as an auto-incrementing datatype for primary key columns, but only
if its scale is explicitly given as zero; otherwise, an error is raised.
This is a change from 2.0 where all numeric types including floats were
automatically considered as "autoincrement" for primary key columns.

References: #11811
[schema] Deprecate Oracle only parameters _schema.Sequence.order,
_schema.Identity.order and _schema.Identity.on_null.
They should be configured using the dialect kwargs oracle_order and
oracle_on_null.

References: #10247

typing

[typing] [feature] The Row object now no longer makes use of an intermediary
Tuple in order to represent its individual element types; instead,
the individual element types are present directly, via new PEP 646
integration, now available in more recent versions of Mypy. Mypy
1.7 or greater is now required for statements, results and rows
to be correctly typed. Pull request courtesy Yurii Karabas.

References: #10635
[typing] The default implementation of _sql.TypeEngine.python_type now
returns object instead of NotImplementedError, since that's the
base for all types in Python3.
The python_type of _sql.JSON no longer returns dict,
but instead fallbacks to the generic implementation.

References: #10646
[typing] [orm] Removed the deprecated mypy plugin.
The plugin was non-functional with newer version of mypy and it's no
longer needed with modern SQLAlchemy declarative style.

References: #12293
[typing] [orm] Deprecated the declarative_mixin decorator since it was used only
by the now removed mypy plugin.

References: #12346

asyncio

[asyncio] [feature] The "emulated" exception hierarchies for the asyncio
drivers such as asyncpg, aiomysql, aioodbc, etc. have been standardized
on a common base EmulatedDBAPIException, which is now what's
available from the StatementException.orig attribute on a
SQLAlchemy DBAPIError object. Within EmulatedDBAPIException
and the subclasses in its hierarchy, the original driver-level exception is
also now available via the EmulatedDBAPIException.orig attribute,
and is also available from DBAPIError directly using the
DBAPIError.driver_exception attribute.

References: #8047
[asyncio] [change] Added an initialize step to the import of
sqlalchemy.ext.asyncio so that greenlet will
be imported only when the asyncio extension is first imported.
Alternatively, the greenlet library is still imported lazily on
first use to support use case that don't make direct use of the
SQLAlchemy asyncio extension.

References: #10296
[asyncio] [change] Adapted all asyncio dialects, including aiosqlite, aiomysql, asyncmy,
psycopg, asyncpg to use the generic asyncio connection adapter first added
in #6521 for the aioodbc DBAPI, allowing these dialects to take
advantage of a common framework.

References: #10415
[asyncio] [change] Removed the compatibility async_fallback mode for async dialects,
since it's no longer used by SQLAlchemy tests.
Also removed the internal function await_fallback() and renamed
the internal function await_only() to await_().
No change is expected to user code.
[asyncio] [bug] Refactored all asyncio dialects so that exceptions which occur on failed
connection attempts are appropriately wrapped with SQLAlchemy exception
objects, allowing for consistent error handling.

References: #11956

postgresql

[postgresql] [feature] Adds a new str subclass _postgresql.BitString representing
PostgreSQL bitstrings in python, that includes
functionality for converting to and from int and bytes, in
addition to implementing utility methods and operators for dealing with bits.

This new class is returned automatically by the postgresql.BIT type.

References: #10556
[postgresql] [feature] Support for storage parameters in CREATE TABLE using the WITH
clause has been added. The postgresql_with dialect option of
_schema.Table accepts a mapping of key/value options.

References: #10909
[postgresql] [feature] Added syntax extension _postgresql.distinct_on() to build DISTINCT ON clauses. The old api, that passed columns to
_sql.Select.distinct(), is now deprecated.

References: #12342
[postgresql] [feature] Support for VIRTUAL computed columns on PostgreSQL 18 and later has
been added. The default behavior when Computed.persisted is
not specified has been changed to align with PostgreSQL 18's default of
VIRTUAL. When Computed.persisted is not specified, no
keyword is rendered on PostgreSQL 18 and later; on older versions a
warning is emitted and STORED is used as the default. To explicitly
request STORED behavior on all PostgreSQL versions, specify
persisted=True.

References: #12866
[postgresql] [feature] [sql] Added support for monotonic server-side functions such as PostgreSQL 18's
uuidv7() to work with the engine_insertmanyvalues feature.
By passing monotonic=True to any Function, the function can
be used as a sentinel for tracking row order in batched INSERT operations
with RETURNING, allowing the ORM and Core to efficiently batch INSERT
statements while maintaining deterministic row ordering.

References: #13014
[postgresql] [feature] Added additional emulated error classes for the subclasses of
asyncpg.exception.IntegrityError including RestrictViolationError,
NotNullViolationError, ForeignKeyViolationError,
UniqueViolationError CheckViolationError,
ExclusionViolationError. These exceptions are not directly thrown by
SQLAlchemy's asyncio emulation, however are available from the
newly added DBAPIError.driver_exception attribute when a
IntegrityError is caught.

References: #8047
[postgresql] [usecase] Added new parameter Enum.create_type to the Core
Enum class. This parameter is automatically passed to the
corresponding _postgresql.ENUM native type during DDL operations,
allowing control over whether the PostgreSQL ENUM type is implicitly
created or dropped within DDL operations that are otherwise targeting
tables only. This provides control over the
_postgresql.ENUM.create_type behavior without requiring
explicit creation of a _postgresql.ENUM object.

References: #10604
[postgresql] [usecase] The PostgreSQL dialect now support reflection of table options, including
the storage parameters, table access method and table spaces. These options
are automatically reflected when autoloading a table, and are also
available via the _engine.Inspector.get_table_options() and
_engine.Inspector.get_multi_table_optionsmethod() methods.

References: #10909
[postgresql] [usecase] Added support for PostgreSQL 14+ HSTORE subscripting syntax. When connected
to PostgreSQL 14 or later, HSTORE columns now automatically use the native
subscript notation hstore_col['key'] instead of the arrow operator
hstore_col -> 'key' for both read and write operations. This provides
better compatibility with PostgreSQL's native HSTORE subscripting feature
while maintaining backward compatibility with older PostgreSQL versions.

Indexes in existing PostgreSQL databases which were indexed
on an HSTORE subscript expression would need to be updated in order to
match the new SQL syntax.

References: #12948
[postgresql] [usecase] The default DBAPI driver for the PostgreSQL dialect has been changed to
psycopg (psycopg version 3) instead of psycopg2. The psycopg2
driver remains fully supported and can be explicitly specified in the
connection URL using postgresql+psycopg2://.

The psycopg (version 3) driver includes improvements over psycopg2
including better performance when using C extensions and native support
for async operations.

References: #13010
[postgresql] [change] The _types.ARRAY.Comparator.any() and
_types.ARRAY.Comparator.all() methods for the _types.ARRAY
type are now deprecated for removal; these two methods along with
_postgresql.Any() and _postgresql.All() have been legacy for
some time as they are superseded by the _sql.any_() and
_sql.all_() functions, which feature more intuitive use.

References: #10821
[postgresql] [change] Named types such as _postgresql.ENUM and
_postgresql.DOMAIN (as well as the dialect-agnostic
_types.Enum version) are now more strongly associated with the
_schema.MetaData at the top of the table hierarchy and are
de-associated with any particular _schema.Table they may be a part
of. This better represents how PostgreSQL named types exist independently
of any particular table, and that they may be used across many tables
simultaneously. The change impacts the behavior of the "default schema"
for a named type, as well as the CREATE/DROP behavior in relationship to
the MetaData and Table construct. The change also
includes a new CheckFirst enumeration which allows fine grained
control over "check" queries during DDL operations, as well as that the
_types.SchemaType.inherit_schema parameter is deprecated and
will emit a deprecation warning when used. See the migration notes for
full details.

References: #10594, #12690
[postgresql] [bug] A CompileError is raised if attempting to create a PostgreSQL
_postgresql.ENUM or _postgresql.DOMAIN datatype using a
name that matches a known pg_catalog datatype name, and a default schema is
not specified. These types must be explicit within a schema in order to
be differentiated from the built-in pg_catalog type. The "public" or
otherwise default schema is not chosen by default here since the type can
only be reflected back using the explicit schema name as well (it is
otherwise not visible due to the pg_catalog name). Pull request courtesy
Kapil Dagur.

References: #12761

mysql

[mysql] [feature] Added new construct _mysql.limit() which can be applied to any
_sql.update() or _sql.delete() to provide the LIMIT keyword to
UPDATE and DELETE. This new construct supersedes the use of the
"mysql_limit" dialect keyword argument.
[mysql] [mariadb] [reflection] Updated the reflection logic for indexes in the MariaDB and MySQL
dialect to avoid setting the undocumented type key in the
_engine.ReflectedIndex dicts returned by
_engine.Inspector.get_indexes method.

References: #12240

mariadb

[mariadb] [usecase] Modified the MariaDB dialect so that when using the _sqltypes.Uuid
datatype with MariaDB >= 10.7, leaving the
_sqltypes.Uuid.native_uuid parameter at its default of True,
the native UUID datatype will be rendered in DDL and used for database
communication, rather than CHAR(32) (the non-native UUID type) as was
the case previously. This is a behavioral change since 2.0, where the
generic _sqltypes.Uuid datatype delivered CHAR(32) for all
MySQL and MariaDB variants. Support for all major DBAPIs is implemented
including support for less common "insertmanyvalues" scenarios where UUID
values are generated in different ways for primary keys. Thanks much to
Volodymyr Kochetkov for delivering the PR.

References: #10339
[mariadb] [bug] Fixes to the MySQL/MariaDB dialect so that mariadb-specific features such
as the mariadb.INET4 and mariadb.INET6 datatype may be
used with an Engine that uses a mysql:// URL, if the backend
database is actually a mariadb database. Previously, support for MariaDB
features when mysql:// URLs were used instead of mariadb:// URLs
was ad-hoc; with this issue resolution, the full set of schema / compiler /
type features are now available regardless of how the URL was presented.

References: #13076

sqlite

[sqlite] [bug] Improved the behavior of JSON accessors JSON.Comparator.as_string(),
JSON.Comparator.as_boolean(), JSON.Comparator.as_float(),
JSON.Comparator.as_integer() to use CAST in a similar way that
the PostgreSQL, MySQL and SQL Server dialects do to help enforce the
expected Python type is returned.

References: #11074

mssql

[mssql] [bug] The JSON.Comparator.as_boolean() method when used on a JSON value on
SQL Server will now force a cast to occur for values that are not simple
true/false JSON literals, forcing SQL Server to attempt to interpret
the given value as a 1/0 BIT, or raise an error if not possible. Previously
the expression would return NULL.

References: #11074
[mssql] [bug] Fix mssql+pyodbc issue where valid plus signs in an already-unquoted
odbc_connect= (raw DBAPI) connection string are replaced with spaces.

The pyodbc connector would unconditionally pass the odbc_connect value
to unquote_plus(), even if it was not required. So, if the (unquoted)
odbc_connect value contained PWD=pass+word that would get changed to
PWD=pass word, and the login would fail. One workaround was to quote
just the plus sign — PWD=pass%2Bword — which would then get unquoted
to PWD=pass+word.

References: #11250

oracle

[oracle] [feature] Added support for native BOOLEAN support in Oracle Database 23c and above.
The Oracle dialect now renders BOOLEAN automatically when
Boolean is used in DDL, and also now supports direct use of the
BOOLEAN datatype, when 23c and above is in use. For Oracle
versions prior to 23c, boolean values continue to be emulated using
SMALLINT as before. Special case handling is also present to ensure a
SMALLINT that's interpreted with the Boolean datatype on Oracle
Database 23c and above continues to return bool values. Pull request
courtesy Yeongbae Jeon.

References: #11633
[oracle] [usecase] The default DBAPI driver for the Oracle Database dialect has been changed
to oracledb instead of cx_oracle. The cx_oracle driver remains
fully supported and can be explicitly specified in the connection URL
using oracle+cx_oracle://.

The oracledb driver is a modernized version of cx_oracle with
better performance characteristics and ongoing active development from
Oracle.

References: #13010

tests

[tests] [change] The top-level test runner has been changed to use nox, adding a
noxfile.py as well as some included modules. The tox.ini file
remains in place so that tox runs will continue to function in the near
term, however it will be eventually removed and improvements and
maintenance going forward will be only towards noxfile.py.

misc

[misc] [changed] Removed multiple api that were deprecated in the 1.3 series and earlier.
The list of removed features includes:

-   The `force` parameter of `IdentifierPreparer.quote` and
    `IdentifierPreparer.quote_schema`;

-   The `threaded` parameter of the cx-Oracle dialect;

-   The `_json_serializer` and `_json_deserializer` parameters of the
    SQLite dialect;

-   The `collection.converter` decorator;

-   The `Mapper.mapped_table` property;

-   The `Session.close_all` method;

-   Support for multiple arguments in `_orm.defer()` and
    `_orm.undefer()`.

References: #12441

2.0.46

2026-01-21T19:05:46Z

2.0.46

Released: January 21, 2026

typing

[typing] [bug] Fixed typing issues where ORM mapped classes and aliased entities could not
be used as keys in result row mappings or as join targets in select
statements. Patterns such as row._mapping[User],
row._mapping[aliased(User)], row._mapping[with_polymorphic(...)]
(rejected by both mypy and Pylance), and .join(aliased(User))
(rejected by Pylance) are documented and fully supported at runtime but
were previously rejected by type checkers. The type definitions for
_KeyType and _FromClauseArgument have been updated to
accept these ORM entity types.

References: #13075

postgresql

[postgresql] [bug] Fixed issue where PostgreSQL JSONB operators
_postgresql.JSONB.Comparator.path_match() and
_postgresql.JSONB.Comparator.path_exists() were applying incorrect
VARCHAR casts to the right-hand side operand when used with newer
PostgreSQL drivers such as psycopg. The operators now indicate the
right-hand type as JSONPATH, which currently results in no casting
taking place, but is also compatible with explicit casts if the
implementation were require it at a later point.

References: #13059
[postgresql] [bug] Fixed regression in PostgreSQL dialect where JSONB subscription syntax
would generate incorrect SQL for cast() expressions returning JSONB,
causing syntax errors. The dialect now properly wraps cast expressions in
parentheses when using the [] subscription syntax, generating
(CAST(...))[index] instead of CAST(...)[index] to comply with
PostgreSQL syntax requirements. This extends the fix from #12778
which addressed the same issue for function calls.

References: #13067
[postgresql] [bug] Improved the foreign key reflection regular expression pattern used by the
PostgreSQL dialect to be more permissive in matching identifier characters,
allowing it to correctly handle unicode characters in table and column
names. This change improves compatibility with PostgreSQL variants such as
CockroachDB that may use different quoting patterns in combination with
unicode characters in their identifiers. Pull request courtesy Gord
Thompson.

mariadb

[mariadb] [bug] Fixed the SQL compilation for the mariadb sequence "NOCYCLE" keyword that
is to be emitted when the Sequence.cycle parameter is set to
False on a Sequence. Pull request courtesy Diego Dupin.

References: #13070

sqlite

[sqlite] [bug] Fixed issue in the aiosqlite driver where SQLAlchemy's setting of
aiosqlite's worker thread to "daemon" stopped working because the aiosqlite
architecture moved the location of the worker thread in version 0.22.0.
This "daemon" flag is necessary so that a program is able to exit if the
SQLite connection itself was not explicitly closed, which is particularly
likely with SQLAlchemy as it maintains SQLite connections in a connection
pool. While it's perfectly fine to call AsyncEngine.dispose()
before program exit, this is not historically or technically necessary for
any driver of any known backend, since a primary feature of relational
databases is durability. The change also implements support for
"terminate" with aiosqlite when using version version 0.22.1 or greater,
which implements a sync .stop() method.

References: #13039

mssql

[mssql] [usecase] Added support for the IF EXISTS clause when dropping indexes on SQL
Server 2016 (13.x) and later versions. The DropIndex.if_exists
parameter is now honored by the SQL Server dialect, allowing conditional
index drops that will not raise an error if the index does not exist.
Pull request courtesy Edgar Ramírez Mondragón.

References: #13045

2.0.45

2025-12-10T20:14:51Z

2.0.45

Released: December 9, 2025

orm

[orm] [bug] Fixed issue where calling Mapper.add_property() within mapper event
hooks such as MapperEvents.instrument_class(),
MapperEvents.after_mapper_constructed(), or
MapperEvents.before_mapper_configured() would raise an
AttributeError because the mapper's internal property collections were
not yet initialized. The Mapper.add_property() method now handles
early-stage property additions correctly, allowing properties including
column properties, deferred columns, and relationships to be added during
mapper initialization events. Pull request courtesy G Allajmi.

References: #12858
[orm] [bug] Fixed issue in Python 3.14 where dataclass transformation would fail when
a mapped class using MappedAsDataclass included a
relationship() referencing a class that was not available at
runtime (e.g., within a TYPE_CHECKING block). This occurred when using
Python 3.14's PEP 649 deferred annotations feature, which is the
default behavior without a from __future__ import annotations
directive.

References: #12952

examples

[examples] [bug] Fixed the "short_selects" performance example where the cache was being
used in all the examples, making it impossible to compare performance with
and without the cache. Less important comparisons like "lambdas" and
"baked queries" have been removed.

sql

[sql] [bug] Some improvements to the _sql.ClauseElement.params() method to
replace bound parameters in a query were made, however the ultimate issue
in #12915 involving ORM _orm.aliased() cannot be fixed fully
until 2.1, where the method is being rewritten to work without relying on
Core cloned traversal.

References: #12915
[sql] [bug] Fixed issue where using the ColumnOperators.in_() operator with a
nested CompoundSelect statement (e.g. an INTERSECT of
UNION queries) would raise a NotImplementedError when the
nested compound select was the first argument to the outer compound select.
The _scalar_type() internal method now properly handles nested compound
selects.

References: #12987

typing

[typing] [bug] Fixed typing issue where Select.with_for_update() would not support
lists of ORM entities or other FROM clauses in the
Select.with_for_update.of parameter. Pull request courtesy
Shamil.

References: #12730
[typing] [bug] Fixed typing issue where coalesce would not return the correct
return type when a nullable form of that argument were passed, even though
this function is meant to select the non-null entry among possibly null
arguments. Pull request courtesy Yannick PÉROUX.

postgresql

[postgresql] [usecase] Added support for reflection of collation in types for PostgreSQL.
The collation will be set only if different from the default
one for the type.
Pull request courtesy Denis Laxalde.

References: #6511
[postgresql] [bug] Fixed issue where PostgreSQL dialect options such as postgresql_include
on PrimaryKeyConstraint and UniqueConstraint were
rendered in the wrong position when combined with constraint deferrability
options like deferrable=True. Pull request courtesy G Allajmi.

References: #12867
[postgresql] [bug] Fixed the structure of the SQL string used for the
engine_insertmanyvalues feature when an explicit sequence with
nextval() is used. The SQL function invocation for the sequence has
been moved from being rendered inline within each tuple inside of VALUES to
being rendered once in the SELECT that reads from VALUES. This change
ensures the function is invoked in the correct order as rows are processed,
rather than assuming PostgreSQL will execute inline function calls within
VALUES in a particular order. While current PostgreSQL versions appear to
handle the previous approach correctly, the database does not guarantee
this behavior for future versions.

References: #13015

mysql

[mysql] [usecase] Added support for MySQL 8.0.1 + FOR SHARE to be emitted for the
Select.with_for_update() method, which offers compatibility with
NOWAIT and SKIP LOCKED. The new syntax is used only for MySQL when
version 8.0.1 or higher is detected. Pull request courtesy JetDrag.

References: #12964

sqlite

[sqlite] [bug] [reflection] A series of improvements have been made for reflection of CHECK constraints
on SQLite. The reflection logic now correctly handles table names
containing the strings "CHECK" or "CONSTRAINT", properly supports all four
SQLite identifier quoting styles (double quotes, single quotes, brackets,
and backticks) for constraint names, and accurately parses CHECK constraint
expressions containing parentheses within string literals using balanced
parenthesis matching with string context tracking. Big thanks to
GruzdevAV for new test cases and implementation ideas.

References: #12924
[sqlite] [bug] Fixed issue where SQLite dialect would fail to reflect constraint names
that contained uppercase letters or other characters requiring quoting. The
regular expressions used to parse primary key, foreign key, and unique
constraint names from the CREATE TABLE statement have been updated to
properly handle both quoted and unquoted constraint names.

References: #12954

tests

[tests] [change] A noxfile.py has been added to allow testing with nox. This is a direct
port of 2.1's move to nox, however leaves the tox.ini file in place and
retains all test documentation in terms of tox. Version 2.1 will move to
nox fully, including deprecation warnings for tox and new testing
documentation.

2.0.44

2025-10-10T16:20:28Z

2.0.44

Released: October 10, 2025

platform

[platform] [bug] Unblocked automatic greenlet installation for Python 3.14 now that
there are greenlet wheels on pypi for python 3.14.

orm

[orm] [usecase] The way ORM Annotated Declarative interprets Python PEP 695 type aliases
in Mapped[] annotations has been refined to expand the lookup scheme. A
PEP 695 type can now be resolved based on either its direct presence in
_orm.registry.type_annotation_map or its immediate resolved
value, as long as a recursive lookup across multiple PEP 695 types is
not required for it to resolve. This change reverses part of the
restrictions introduced in 2.0.37 as part of #11955, which
deprecated (and disallowed in 2.1) the ability to resolve any PEP 695
type that was not explicitly present in
_orm.registry.type_annotation_map. Recursive lookups of
PEP 695 types remains deprecated in 2.0 and disallowed in version 2.1,
as do implicit lookups of NewType types without an entry in
_orm.registry.type_annotation_map.

Additionally, new support has been added for generic PEP 695 aliases that
refer to PEP 593 Annotated constructs containing
_orm.mapped_column() configurations. See the sections below for
examples.

References: #12829
[orm] [bug] Fixed a caching issue where _orm.with_loader_criteria() would
incorrectly reuse cached bound parameter values when used with
_sql.CompoundSelect constructs such as _sql.union(). The
issue was caused by the cache key for compound selects not including the
execution options that are part of the _sql.Executable base class,
which _orm.with_loader_criteria() uses to apply its criteria
dynamically. The fix ensures that compound selects and other executable
constructs properly include execution options in their cache key traversal.

References: #12905

engine

[engine] [bug] Implemented initial support for free-threaded Python by adding new tests
and reworking the test harness to include Python 3.13t and Python 3.14t in
test runs. Two concurrency issues have been identified and fixed: the first
involves initialization of the .c collection on a FromClause, a
continuation of #12302, where an optional mutex under
free-threading is added; the second involves synchronization of the pool
"first_connect" event, which first received thread synchronization in
#2964, however under free-threading the creation of the mutex
itself runs under the same free-threading mutex. Support for free-threaded
wheels on Pypi is implemented as well within the 2.1 series only. Initial
pull request and test suite courtesy Lysandros Nikolaou.

References: #12881

sql

[sql] [bug] Improved the implementation of UpdateBase.returning() to use more
robust logic in setting up the .c collection of a derived statement
such as a CTE. This fixes issues related to RETURNING clauses that feature
expressions based on returned columns with or without qualifying labels.

References: #12271

schema

[schema] [bug] Fixed issue where _schema.MetaData.reflect() did not forward
dialect-specific keyword arguments to the _engine.Inspector
methods, causing options like oracle_resolve_synonyms to be ignored
during reflection. The method now ensures that all extra kwargs passed to
_schema.MetaData.reflect() are forwarded to
_engine.Inspector.get_table_names() and related reflection methods.
Pull request courtesy Lukáš Kožušník.

References: #12884

typing

[typing] [bug] Fixed typing bug where the Session.execute() method advertised that
it would return a CursorResult if given an insert/update/delete
statement. This is not the general case as several flavors of ORM
insert/update do not actually yield a CursorResult which cannot
be differentiated at the typing overload level, so the method now yields
Result in all cases. For those cases where
CursorResult is known to be returned and the .rowcount
attribute is required, please use typing.cast().

References: #12813
[typing] [bug] Added new decorator _orm.mapped_as_dataclass(), which is a function
based form of _orm.registry.mapped_as_dataclass(); the method form
_orm.registry.mapped_as_dataclass() does not seem to be correctly
recognized within the scope of PEP 681 in recent mypy versions.

References: #12855

asyncio

[asyncio] [usecase] Generalize the terminate logic employed by the asyncpg dialect to reuse
it in the aiomysql and asyncmy dialect implementation.

References: #12273

postgresql

[postgresql] [bug] Fixed issue where selecting an enum array column containing NULL values
would fail to parse properly in the PostgreSQL dialect. The
_split_enum_values() function now correctly handles NULL entries by
converting them to Python None values.

References: #12847
[postgresql] [bug] Fixed issue where the _sql.any_() and _sql.all_() aggregation
operators would not correctly coerce the datatype of the compared value, in
those cases where the compared value were not a simple int/str etc., such
as a Python Enum or other custom value. This would lead to execution
time errors for these values. This issue is essentially the same as
#6515 which was for the now-legacy ARRAY.any() and
ARRAY.all() methods.

References: #12874

sqlite

[sqlite] [bug] Fixed issue where SQLite table reflection would fail for tables using
WITHOUT ROWID and/or STRICT table options when the table contained
generated columns. The regular expression used to parse CREATE TABLE
statements for generated column detection has been updated to properly
handle these SQLite table options that appear after the column definitions.
Pull request courtesy Tip ten Brink.

References: #12864

mssql

[mssql] [bug] Improved the base implementation of the asyncio cursor such that it
includes the option for the underlying driver's cursor to be actively
closed in those cases where it requires await in order to complete the
close sequence, rather than relying on garbage collection to "close" it,
when a plain Result is returned that does not use await for
any of its methods. The previous approach of relying on gc was fine for
MySQL and SQLite dialects but has caused problems with the aioodbc
implementation on top of SQL Server. The new option is enabled
for those dialects which have an "awaitable" cursor.close(), which
includes the aioodbc, aiomysql, and asyncmy dialects (aiosqlite is also
modified for 2.1 only).

References: #12798
[mssql] [bug] Fixed issue where the index reflection for SQL Server would
not correctly return the order of the column inside an index
when the order of the columns in the index did not match the
order of the columns in the table.
Pull request courtesy of Allen Chen.

References: #12894
[mssql] [bug] [reflection] Fixed issue in the MSSQL dialect's foreign key reflection query where
duplicate rows could be returned when a foreign key column and its
referenced primary key column have the same name, and both the referencing
and referenced tables have indexes with the same name. This resulted in an
"ForeignKeyConstraint with duplicate source column references are not
supported" error when attempting to reflect such tables. The query has been
corrected to exclude indexes on the child table when looking for unique
indexes referenced by foreign keys.

References: #12907

misc

[bug] [ext] Fixed issue caused by an unwanted functional change while typing
the MutableList class.
This change also reverts all other functional changes done in
the same change.

References: #12802

2.0.43

2025-08-11T16:07:16Z

2.0.43

Released: August 11, 2025

orm

[orm] [bug] Fixed issue where using the post_update feature would apply incorrect
"pre-fetched" values to the ORM objects after a multi-row UPDATE process
completed. These "pre-fetched" values would come from any column that had
an Column.onupdate callable or a version id generator used by
orm.Mapper.version_id_generator; for a version id generator
that delivered random identifiers like timestamps or UUIDs, this incorrect
data would lead to a DELETE statement against those same rows to fail in
the next step.

References: #12748
[orm] [bug] Fixed issue where _orm.mapped_column.use_existing_column
parameter in _orm.mapped_column() would not work when the
_orm.mapped_column() is used inside of an Annotated type alias in
polymorphic inheritance scenarios. The parameter is now properly recognized
and processed during declarative mapping configuration.

References: #12787
[orm] [bug] Improved the implementation of the _orm.selectin_polymorphic()
inheritance loader strategy to properly render the IN expressions using
chunks of 500 records each, in the same manner as that of the
_orm.selectinload() relationship loader strategy. Previously, the IN
expression would be arbitrarily large, leading to failures on databases
that have limits on the size of IN expressions including Oracle Database.

References: #12790

engine

[engine] [usecase] Added new parameter create_engine.skip_autocommit_rollback
which provides for a per-dialect feature of preventing the DBAPI
.rollback() from being called under any circumstances, if the
connection is detected as being in "autocommit" mode. This improves upon
a critical performance issue identified in MySQL dialects where the network
overhead of the .rollback() call remains prohibitive even if autocommit
mode is set.

References: #12784

postgresql

[postgresql] [bug] Fixed regression in PostgreSQL dialect where JSONB subscription syntax
would generate incorrect SQL for JSONB-returning functions, causing syntax
errors. The dialect now properly wraps function calls and expressions in
parentheses when using the [] subscription syntax, generating
(function_call)[index] instead of function_call[index] to comply
with PostgreSQL syntax requirements.

References: #12778

oracle

[oracle] [usecase] Extended _oracle.VECTOR to support sparse vectors. This update
introduces _oracle.VectorStorageType to specify sparse or dense
storage and added _oracle.SparseVector. Pull request courtesy
Suraj Shaw.

References: #12711

2.0.42

2025-07-29T13:39:32Z

2.0.42

Released: July 29, 2025

orm

[orm] [usecase] Added dataclass_metadata argument to all ORM attribute constructors
that accept dataclasses parameters, e.g. mapped_column.dataclass_metadata,
relationship.dataclass_metadata, etc.
It's passed to the underlying dataclass metadata attribute
of the dataclass field. Pull request courtesy Sigmund Lahn.

References: #10674
[orm] [bug] Implemented the _orm.defer(), _orm.undefer() and
_orm.load_only() loader options to work for composite attributes, a
use case that had never been supported previously.

References: #12593
[orm] [bug] Fixed bug where the ORM would pull in the wrong column into an UPDATE when
a key name inside of the ValuesBase.values() method could be located
from an ORM entity mentioned in the statement, but where that ORM entity
was not the actual table that the statement was inserting or updating. An
extra check for this edge case is added to avoid this problem.

References: #12692

engine

[engine] Improved validation of execution parameters passed to the
_engine.Connection.execute() and similar methods to
provided a better error when tuples are passed in.
Previously the execution would fail with a difficult to
understand error message.

sql

[sql] [usecase] The _sql.values() construct gains a new method _sql.Values.cte(),
which allows creation of a named, explicit-columns CTE against an
unnamed VALUES expression, producing a syntax that allows column-oriented
selection from a VALUES construct on modern versions of PostgreSQL, SQLite,
and MariaDB.

References: #12734
[sql] [bug] Fixed issue where select() of a free-standing scalar expression that
has a unary operator applied, such as negation, would not apply result
processors to the selected column even though the correct type remains in
place for the unary expression.

References: #12681
[sql] [bug] Hardening of the compiler's actions for UPDATE statements that access
multiple tables to report more specifically when tables or aliases are
referenced in the SET clause; on cases where the backend does not support
secondary tables in the SET clause, an explicit error is raised, and on the
MySQL or similar backends that support such a SET clause, more specific
checking for not-properly-included tables is performed. Overall the change
is preventing these erroneous forms of UPDATE statements from being
compiled, whereas previously it was relied on the database to raise an
error, which was not always guaranteed to happen, or to be non-ambiguous,
due to cases where the parent table included the same column name as the
secondary table column being updated.

References: #12692

postgresql

[postgresql] [usecase] Added support for PostgreSQL 14+ JSONB subscripting syntax. When connected
to PostgreSQL 14 or later, JSONB columns now automatically use the native
subscript notation jsonb_col['key'] instead of the arrow operator
jsonb_col -> 'key' for both read and write operations. This provides
better compatibility with PostgreSQL's native JSONB subscripting feature
while maintaining backward compatibility with older PostgreSQL versions.
JSON columns continue to use the traditional arrow syntax regardless of
PostgreSQL version.

References: #10927
[postgresql] [usecase] Added postgresql_ops key to the dialect_options entry in reflected
dictionary. This maps names of columns used in the index to respective
operator class, if distinct from the default one for column's data type.
Pull request courtesy Denis Laxalde.

References: #8664
[postgresql] [bug] [reflection] Fixed regression caused by #10665 where the newly modified
constraint reflection query would fail on older versions of PostgreSQL
such as version 9.6. Pull request courtesy Denis Laxalde.

References: #12600
[postgresql] [bug] Re-raise catched CancelledError in the terminate method of the
asyncpg dialect to avoid possible hangs of the code execution.

References: #12728
[postgresql] [bug] [reflection] Fixes bug that would mistakenly interpret a domain or enum type
with name starting in interval as an INTERVAL type while
reflecting a table.

References: #12744

mysql

[mysql] [bug] Fixed yet another regression caused by by the DEFAULT rendering changes in
2.0.40 #12425, similar to #12488, this time where using a
CURRENT_TIMESTAMP function with a fractional seconds portion inside a
textual default value would also fail to be recognized as a
non-parenthesized server default.

References: #12648

mssql

[mssql] [bug] Reworked SQL Server column reflection to be based on the sys.columns
table rather than information_schema.columns view. By correctly using
the SQL Server object_id() function as a lead and joining to related
tables on object_id rather than names, this repairs a variety of issues in
SQL Server reflection, including:

-   Issue where reflected column comments would not correctly line up
    with the columns themselves in the case that the table had been ALTERed

-   Correctly targets tables with awkward names such as names with brackets,
    when reflecting not just the basic table / columns but also extended
    information including IDENTITY, computed columns, comments which
    did not work previously

-   Correctly targets IDENTITY, computed status from temporary tables
    which did not work previously

References: #12654

2.0.41

2025-05-14T18:01:24Z

2.0.41

Released: May 14, 2025

platform

[platform] [bug] Adjusted the test suite as well as the ORM's method of scanning classes for
annotations to work under current beta releases of Python 3.14 (currently
3.14.0b1) as part of an ongoing effort to support the production release of
this Python release. Further changes to Python's means of working with
annotations is expected in subsequent beta releases for which SQLAlchemy's
test suite will need further adjustments.

References: #12405

engine

[engine] [bug] The error message that is emitted when a URL cannot be parsed no longer
includes the URL itself within the error message.

References: #12579

typing

[typing] [bug] Removed __getattr__() rule from sqlalchemy/__init__.py that
appeared to be trying to correct for a previous typographical error in the
imports. This rule interferes with type checking and is removed.

References: #12588

postgresql

[postgresql] [usecase] Added support for postgresql_include keyword argument to
_schema.UniqueConstraint and _schema.PrimaryKeyConstraint.
Pull request courtesy Denis Laxalde.

References: #10665

mysql

[mysql] [bug] Fixed regression caused by the DEFAULT rendering changes in version 2.0.40
via #12425 where using lowercase on update in a MySQL server
default would incorrectly apply parenthesis, leading to errors when MySQL
interpreted the rendered DDL. Pull request courtesy Alexander Ruehe.

References: #12488

sqlite

[sqlite] [bug] Fixed and added test support for some SQLite SQL functions hardcoded into
the compiler, most notably the localtimestamp function which rendered
with incorrect internal quoting.

References: #12566

oracle

[oracle] [usecase] Added new datatype _oracle.VECTOR and accompanying DDL and DQL
support to fully support this type for Oracle Database. This change
includes the base _oracle.VECTOR type that adds new type-specific
methods l2_distance, cosine_distance, inner_product as well as
new parameters oracle_vector for the Index construct,
allowing vector indexes to be configured, and oracle_fetch_approximate
for the Select.fetch() clause. Pull request courtesy Suraj Shaw.

References: #12317, #12341

misc

[bug] [installation] Removed the "license classifier" from setup.cfg for SQLAlchemy 2.0, which
eliminates loud deprecation warnings when building the package. SQLAlchemy
2.1 will use a full PEP 639 configuration in pyproject.toml while
SQLAlchemy 2.0 remains using setup.cfg for setup.

2.0.40

2025-03-27T18:55:27Z

2.0.40

Released: March 27, 2025

orm

[orm] [bug] Fixed regression which occurred as of 2.0.37 where the checked
ArgumentError that's raised when an inappropriate type or object
is used inside of a Mapped annotation would raise TypeError
with "boolean value of this clause is not defined" if the object resolved
into a SQL expression in a boolean context, for programs where future
annotations mode was not enabled. This case is now handled explicitly and
a new error message has also been tailored for this case. In addition, as
there are at least half a dozen distinct error scenarios for intepretation
of the Mapped construct, these scenarios have all been unified
under a new subclass of ArgumentError called
MappedAnnotationError, to provide some continuity between these
different scenarios, even though specific messaging remains distinct.

References: #12329
[orm] [bug] Fixed regression in ORM Annotated Declarative class interpretation caused
by typing_extension==4.13.0 that introduced a different implementation
for TypeAliasType while SQLAlchemy assumed that it would be equivalent
to the typing version, leading to pep-695 type annotations not
resolving to SQL types as expected.

References: #12473

sql

[sql] [usecase] Implemented support for the GROUPS frame specification in window functions
by adding _sql.over.groups option to _sql.over()
and FunctionElement.over(). Pull request courtesy Kaan Dikmen.

References: #12450
[sql] [bug] Fixed issue in CTE constructs involving multiple DDL
_sql.Insert statements with multiple VALUES parameter sets where the
bound parameter names generated for these parameter sets would conflict,
generating a compile time error.

References: #12363
[sql] [bug] Fixed regression caused by #7471 leading to a SQL compilation
issue where name disambiguation for two same-named FROM clauses with table
aliasing in use at the same time would produce invalid SQL in the FROM
clause with two "AS" clauses for the aliased table, due to double aliasing.

References: #12451

asyncio

[asyncio] [bug] Fixed issue where AsyncSession.get_transaction() and
AsyncSession.get_nested_transaction() would fail with
NotImplementedError if the "proxy transaction" used by
AsyncSession were garbage collected and needed regeneration.

References: #12471

postgresql

[postgresql] [usecase] Added support for specifying a list of columns for SET NULL and SET DEFAULT actions of ON DELETE clause of foreign key definition on
PostgreSQL. Pull request courtesy Denis Laxalde.

References: #11595
[postgresql] [usecase] When building a PostgreSQL ARRAY literal using
_postgresql.array with an empty clauses argument, the
_postgresql.array.type_ parameter is now significant in that it
will be used to render the resulting ARRAY[] SQL expression with a
cast, such as ARRAY[]::INTEGER. Pull request courtesy Denis Laxalde.

References: #12432

mysql

[mysql] [bug] Support has been re-added for the MySQL-Connector/Python DBAPI using the
mysql+mysqlconnector:// URL scheme. The DBAPI now works against
modern MySQL versions as well as MariaDB versions (in the latter case it's
required to pass charset/collation explicitly). Note however that
server side cursor support is disabled due to unresolved issues with this
driver.

References: #12332
[mysql] [bug] Fixed issue in MySQL server default reflection where a default that has
spaces would not be correctly reflected. Additionally, expanded the rules
for when to apply parenthesis to a server default in DDL to suit the
general case of a default string that contains non-word characters such as
spaces or operators and is not a string literal.

References: #12425

sqlite

[sqlite] [bug] Expanded the rules for when to apply parenthesis to a server default in DDL
to suit the general case of a default string that contains non-word
characters such as spaces or operators and is not a string literal.

References: #12425