2.1.0

Released: September 24, 2026

orm

• [orm] [feature] Added _orm.composite.column_template parameter to _orm.composite(). When the composite class is a dataclass, this parameter accepts a string template such as "person_%s", containing exactly one %s placeholder, that's used to generate column names for dataclass fields that don't otherwise have an explicit name, rather than using the bare field name. This removes the need to hand-write a _orm.mapped_column() for each field when the same composite dataclass is mapped multiple times on the same class with different column-name prefixes. Pull request courtesy Leonardo Rosa.

  References: #12575

• [orm] [bug] Fixed issue where pickling an ORM object that had an instance level lazy loader established, such as when the _orm.raiseload() option is used, would emit a spurious warning regarding the loader containing additional criteria, if the object had itself been unpickled from a previous serialization. This would occur for objects that cross more than one serialization boundary, such as when using multiprocessing.

  This change is also backported to: 2.0.53

  References: #13574

• [orm] [bug] Fixed issue where calling _orm.aliased() against an existing _orm.aliased() construct, without passing an explicit selectable, would disregard the selectable of the existing construct and produce an alias of the mapped table instead, if that selectable were anything other than a table or a plain subquery, leading to incorrect results and/or non-working queries.

  This includes _orm.aliased() against a _orm.with_polymorphic() construct, which would previously produce an alias of the base mapped class only, discarding the polymorphic selectable and additional mappers. The new construct now retains these, so that criteria against subclass attributes and the innerjoin and selectable parameters of _orm.with_polymorphic() take effect, and subclass columns are loaded up front. The SQL rendered for these constructs now includes the polymorphic selectable.

  This change is also backported to: 2.0.53

  References: #13583, #13584

• [orm] [bug] Fixed issue where using _orm.aliased() with both the _orm.aliased.name and _orm.aliased.flat parameters, against an entity that is mapped to a join which includes anonymously named aliases, would embed the anonymous name symbol within the names generated for each element of the join, producing unusable SQL. An anonymously named element of the join is now aliased anonymously.

  This change is also backported to: 2.0.53

  References: #13583

sql

• [sql] [bug] Fixed issue where calling _sql.CTE.alias() on a _sql.CTE that was itself produced by _sql.CTE.alias() would render SQL that referred to the name of the intermediate alias, which is not present in the WITH clause, rather than to the name of the original CTE, producing invalid SQL.

  This change is also backported to: 2.0.53

  References: #13583

postgresql

• [postgresql] [usecase] PostgreSQL index reflection now reports so-called "invalid" indexes with postgresql_invalid=True in the Inspector's dialect_options. Reflected Index objects expose this state in the new read-only Index.reflect_only_elements mapping, separate from DDL options. Added new marker DialectKWArgConst.REFLECTED_ONLY which may be used by third party dialects for similar features within the DefaultDialect.construct_arguments registry. Pull request courtesy Max Azatian.

  References: #13577

mssql

• [mssql] [bug] Adjusted the mssql+mssqlpython dialect for mssql-python version 1.15, which now binds all Python Decimal values as SQL_NUMERIC. The conversion of very large and very small Decimal values to strings, carried over from the pyodbc dialect, is no longer applied for this version of the driver, as the string values would otherwise be converted by SQL Server to the narrower numeric type of other Decimal values in the same statement, such as within a multiple-row INSERT, raising an arithmetic overflow error.

  References: #13585

• [mssql] [bug] Fixed issue where Dialect.dbapi_version would raise AttributeError for the mssql+mssqlpython dialect, as the version was looked up using a version attribute that is not present on the mssql_python module, rather than __version__.

  References: #13585

oracle

• [oracle] [usecase] Added support for oracledb's new terminate() feature, which allows for clean termination of an Oracle database connection in an asyncio context where the connection's state has fallen out of the event loop, and needs to be garbage collected. The feature is enabled automatically when using oracledb 26.0.0 or greater.

  This change is also backported to: 2.0.53

  References: #13578