SQLAlchemy rel_2_1_0rc1

Released: August 31, 2026

platform

• [platform] [change] Python 3.11 or above is now required; support for Python 3.10 is dropped, in addition to the drop of versions Python 3.9, 3.8 and 3.7 introduced in 2.1.0b1. Python 3.10 reaches EOL in October of 2026, so dropping support now gives the SQLAlchemy 2.1 series an extra year of space to remain on current Python versions.

• [platform] [bug] Python 3.15 support has been added and tested, including minimal changes for full compatibility.

  This change is also backported to: 2.0.52

  References: #13477

orm

• [orm] [usecase] Improved the error message raised when a Session is used inside a context manager after the transaction has been rolled back due to an exception. The InvalidRequestError now includes the original exception that triggered the rollback, making it clearer why the transaction is no longer active. Pull request courtesy Ilan Keshet.

  References: #11297

• [orm] [usecase] Improved error messages raised when ORM loader strategy options cannot be applied to a query. Messages now render the offending option in a user-friendly form such as joinedload(User.orders) rather than exposing internal class and path representations, and the "does not apply to root entities" message now includes the option that triggered the error. The same user-friendly rendering is also applied to the "conflicting loader strategy" message and to the of_type() representation in "does not link" messages. Originating pull request courtesy Jan Vollmer.

  References: #12398

• [orm] [usecase] Python source generated at runtime is now compiled against a descriptive filename which is registered with the linecache module, so that generated functions appearing on a stack trace render with their source rather than as an opaque File "<string>" frame. This allows tools like pdb and inspect.getsource() to work with these generated source blocks as well. The new feature is applied to the instrumentation applied to an ORM object's __init__ method, as well as throughout SQLAlchemy functions that are internally instrumented.

  References: #13505

• [orm] [usecase] When a subclass overrides a _orm.validates() method using the same method name as the parent class, only the subclass validator is now invoked for instances of the subclass. The subclass validator may call super() to also invoke the parent class validator. Previously, the parent validator was always used regardless of whether the subclass provided an override. Pull request courtesy Indivar Mishra.

  References: #2943

• [orm] [bug] Fixed a result-column misalignment bug in ORM-enabled UPDATE statements where synchronize_session="fetch" is in use, either explicitly or because the statement uses constructs such as CTEs that implicitly select for it. Columns in rows returned by .returning() could be returned under incorrect keys (e.g. row[SomeClass.a] returning the value of a different column), a problem most likely to manifest under concurrent workloads. ORM DELETE statements were not affected.

  This change is also backported to: 2.0.52

  References: #13439

• [orm] [bug] Fixed bug where a failed _orm.Session.bulk_insert_mappings(), _orm.Session.bulk_update_mappings() or _orm.Session.bulk_save_objects() call could leave the _orm.Session permanently in a "flushing" state, such as when the transaction could not be begun because a previous flush had left it needing a rollback. Unlike _orm.Session.flush(), the bulk methods set the internal flushing flag and began the transaction outside of the try/finally block that resets it, so that neither _orm.Session.rollback() nor _orm.Session.close() would clear it, and every subsequent flush would raise InvalidRequestError: Session is already flushing. Pull request courtesy Hamody We.

  This change is also backported to: 2.0.52

  References: #13485

• [orm] [bug] Fixed issue where unpickling an ORM object that were loaded using loader options making use of wildcard tokens, such as _orm.load_only() or _orm.raiseload() with "*", would fail with KeyError or IndexError if the process doing the unpickling had not yet constructed a loader path making use of that same token. This would typically be observed when the object were unpickled in a separate process, such as with the spawn or forkserver multiprocessing start methods, the latter of which became the default on POSIX platforms as of Python 3.14. The internal collection of these tokens is now established up front, so that it is identical in every process.

  This change is also backported to: 2.0.52

  References: #13493

• [orm] [bug] Fixed issue where a string ending in "*" passed to a _orm.Load strategy method, such as Load(A).joinedload("bs.*"), would bypass the check which rejects string attribute names in loader options, silently producing a loader path that matched nothing. Such a string now raises ArgumentError with the same message given for any other string attribute name. The bare wildcard "*", as in Load(A).lazyload("*"), continues to be accepted.

  This change is also backported to: 2.0.52

  References: #13493

• [orm] [bug] Calling _orm.aliased() against a _sql.select() or _sql.union() / _sql.CompoundSelect construct, which previously failed with an obscure AttributeError regarding a missing .mapper attribute, now raises when using SQLAlchemy 2.1, and emits a deprecation warning under SQLAlchemy 2.0 as it coerces the construct into a subquery instead. This matches the behavior of other similar implicit SELECT-to-FROM coercions. Pull request courtesy Rens Groothuijsen.

  This change is also backported to: 2.0.52

  References: #6274

• [orm] [bug] [regression] Fixed regression caused by the dataclasses change in #12168 where passing _orm.relationship.default_factory as list to a relationship that used the _orm.WriteOnlyMapped or _orm.DynamicMapped annotation would raise an error at mapper configuration time, as these relationships have no collection_class. list is now accepted for these relationships, which behave the same as ordinary collections in this regard; the factory itself is never invoked, and a newly constructed object begins with an empty collection. Documentation is added at write_only_dataclasses illustrating the use of write only and dynamic relationships with ORM mapped dataclasses.

  References: #13227

• [orm] [bug] Fixed long-standing issue where an object that was loaded at more than one path within a single query, such as when a chain of _orm.joinedload() options leads back to an entity that was also loaded at the top level of the query, would retain the loader options of whichever path the query happened to see last, which varied with the loader strategy in use. The options an object retains are applied to all forms of :term:lazy loading for that object, so an otherwise identical set of options could behave differently depending on the loader strategy. The shallowest path is now favored, which is deterministic.

  Unknown interpreted text role "term".

  References: #13507

engine

• [engine] [bug] [asyncio] [pool] Fixed issue where a DBAPI connection would be left open and unreachable if an exception were raised within the _events.PoolEvents.connect() or _events.PoolEvents.first_connect() event handlers, which is where Dialect.initialize() runs. The connection had been created but not yet associated with anything that could close it, so it was neither returned to the pool nor closed. For an asyncio driver in particular this could leak a server-side session for the life of the process, as the garbage collector is not able to close a connection that requires the event loop.

  This change is also backported to: 2.0.53

  References: #13548

sql

• [sql] [usecase] Added new methods _sql.Exists.with_hint() and _sql.Exists.with_statement_hint(), which apply a table hint or a statement hint to the SELECT statement that's enclosed by the EXISTS expression, in the same way as _sql.Select.with_hint() and _sql.Select.with_statement_hint(). As ORM constructs such as _orm.PropComparator.any() and _orm.PropComparator.has() produce an _sql.Exists object, hints may now be applied to the subqueries which these constructs generate. Pull request courtesy Abhinav Gorrepati.

  References: #8311

• [sql] [performance] Improved the performance of SQL cache key generation by moving the traversal into the Cython extension modules. The set of attributes that participate in the cache key for a particular construct, along with the handler that applies to each one, is now resolved once at class setup time into a structure that the compiled traversal consumes directly, so that the chain of identity comparisons that formerly rediscovered this per attribute, per cache key is no longer run at all. Benchmarks against a range of Core and ORM statements show cache key generation running approximately 1.5 to 2.2 times faster in a build with the Cython extensions compiled, and approximately 1.05 to 1.2 times faster in a pure Python build, with the generated cache keys themselves unchanged.

  References: #13506

• [sql] [bug] Fixed an issue in Numeric where the Numeric.decimal_return_scale parameter was ignored when the DBAPI does not support native decimal objects (i.e. dialect.supports_native_decimal is False). In this path the result processor was computing the conversion scale from Numeric.scale directly, bypassing Numeric.decimal_return_scale entirely. The behavior now matches Float, which already used the correct _effective_decimal_return_scale property. Pull request courtesy Kadir Can Ozden.

  This change is also backported to: 2.0.52

  References: #13424

• [sql] [bug] Added auditing to the test suite which exercises the literal execute processors across all datatypes and dialects to ensure that string input is either appropriately rejected or correctly escaped. Literal execute processors are invoked when the bindparam.literal_execute parameter is used with an explicit bindparam() object, which overrides DBAPI-native bind handling to render the value inline with the statement instead. Datatypes that were updated include the originally reported SQL Server Uuid / UNIQUEIDENTIFIER rendering which now escapes properly, the JSONPATH type that's currently PostgreSQL-only, and a full family of numeric types stemming from the _types.Float and _types.Numeric bases which now coerce the value to a number, rejecting non-numeric input. Thanks to Javid Khan for helping to identify the issue.

  This change is also backported to: 2.0.52

  References: #13448

• [sql] [bug] Fixed issue where two bound parameters whose names differ only in the characters listed in SQLCompiler.bindname_escape_characters, such as those generated for columns named "a.b" and "a_b", would be rendered using the same name in the compiled statement, as those characters are escaped only as the parameter is rendered. The value for one of the two parameters was then silently used for both, affecting SELECT criteria as well as the VALUES and SET clauses of INSERT and UPDATE statements, where a value could be written to the wrong column. Escaped parameter names are now disambiguated against the names already in use. The .key of each BindParameter is unaffected, so parameter dictionaries passed by the caller continue to be keyed as before.

  References: #13534

• [sql] [bug] Fixed issue where an empty string passed to IdentifierPreparer.quote(), such as the name of a Table constructed with a blank name, would raise IndexError rather than being rendered. An empty identifier is now always quoted. While a blank name is not a legal identifier on most backends, SQLite accepts one, so such a table may be delivered by reflection; a table with a blank name can now be used in SELECT, INSERT, UPDATE, DELETE and DDL statements.

  References: #13535

schema

• [schema] [usecase] ForeignKeyConstraint now accepts a constraint which names the same local column more than once, such as FOREIGN KEY (a, a) REFERENCES r (b, c). This form is valid SQL and constrains the referenced row so that two of its columns are equal; it previously raised ArgumentError. Such a constraint now emits and reflects like any other composite foreign key; the workaround added in 2.0 for #13525, which skipped such a constraint during reflection, is removed as it is no longer needed. As part of this change, the check that the number of constrained columns matches the number of referenced columns no longer counts distinct column names, so that a genuine mismatch such as ForeignKeyConstraint(["x", "x"], ["r.b"]), which was formerly accepted and silently dropped a column, is now rejected.

  References: #13526

• [schema] [usecase] Added new _schema.ForeignKey accessors _schema.ForeignKey.target_tokens, _schema.ForeignKey.target_column and _schema.ForeignKey.target_table_key, as well as new ForeignKey-related datastructure _schema.ForeignKeyTarget. _schema.ForeignKeyTarget is now accepted as a constructor argument as well. See _schema.ForeignKey for new datamembers and usage patterns.

  References: #13538

• [schema] [usecase] Added Dialect.dbapi_version, a standardized accessor for the version of the DBAPI module in use by a dialect, in contrast to Dialect.server_version_info which refers to the database server. The implementation on DefaultDialect makes use of a new per-dialect method Dialect.retrieve_dbapi_version() in order to retrieve the version from the DBAPI module and return it as a VersionInfo object, which is a tuple subclass with additional properties; third-party dialects should also implement the Dialect.retrieve_dbapi_version() method.

• [schema] [performance] Created new reflection method _reflection.Inspector.has_multi_table() to check the existence of multiple tables at once, allowing for better performance when checking many tables. Like the other "multi" reflection methods, the default dialect offers a default implementation that just call the single method in a loop. Backends that wish to take advantage of this new method can implement it in their dialects. The PostgreSQL, Oracle and SQL Server dialects have been updated to use this new method. The implementation of _schema.MetaData.create_all() has been updated to make use of this new method to check the existence of the tables, reducing the number of round trips to the database when creating many tables.

  References: #13311

• [schema] [bug] Fixed an issue where _schema.Table.to_metadata() reused column default and on-update objects, causing the defaults on the original columns to refer to the copied columns. Default generators, including sequences, and server-side defaults are now copied and remain associated with their respective columns and metadata collections. Applications that inspected these objects will now see distinct defaults on the copied table instead of the objects owned by the original table. Pull request courtesy Goutam Adwant.

  This change is also backported to: 2.0.52

  References: #13481

• [schema] [bug] Fixed issue where a _schema.ForeignKey which refers to a table or column whose name contains a dot would be interpreted incorrectly, as the dotted string form of the target could not be told apart from the separator between a schema, table and column name. Foreign key targets are now tracked as their individual schema, table and column names throughout, and are no longer derived by splitting a dotted string.

  References: #13538

• [schema] [deprecated] _schema.ForeignKey.target_fullname is now a legacy accessor, and raises InvalidRequestError when the target has no unambiguous dotted string form, which is the case when the target table or column name contains a dot, or when a schema name is present with no column name. No SQLAlchemy internals make use of the attribute any longer; new code should use _schema.ForeignKey.target_tokens.

  References: #13538

postgresql

• [postgresql] [usecase] Added postgresql_with support to CreateView for specifying PostgreSQL view options such as security_invoker, security_barrier, and check_option, rendered as a WITH (...) clause between the view name and the AS keyword. Additionally, the postgresql_with parameter accepted by _schema.Table and _schema.Index now correctly renders Python boolean values as true/false (lowercase), and None values as the parameter name alone without an = value portion. Pull request courtesy alphavector.

  References: #11122, #13432

• [postgresql] [usecase] The PostgreSQL dialect now reflects the schema of a schema-qualified column or _postgresql.DOMAIN collation, populating the new String.collation_schema / _postgresql.DOMAIN.collation_schema parameters so that reflected DDL round-trips exactly. The schema is omitted from the reflected value when the collation is visible on the current search_path without qualification.

  References: #6511

• [postgresql] [usecase] Added a new parameter String.collation_schema, as well as _postgresql.DOMAIN.collation_schema and ColumnOperators.collate.collation_schema, allowing a PostgreSQL schema-qualified collation name to be specified explicitly, rather than embedding the schema name within the collation string itself, which previously rendered incorrectly. As part of this change, collation name rendering across DDL and the _sql.collate() construct now consistently uses the dialect's identifier preparer for quoting, rather than several separate, inconsistent hand-quoting code paths; as a side effect, simple lowercase collation names such as "utf8" are no longer unconditionally quoted in generated DDL.

  References: #9693

• [postgresql] [bug] Fixed bug in _reflection.Inspector.get_schema_names() for PostgreSQL where the query used to exclude system schemas relied on NOT LIKE 'pg_%', which treats the underscore as a SQL LIKE wildcard rather than a literal character. This caused user-created schemas that happen to start with "pg" followed by any other character, such as pgsql or pgstats, to be silently excluded along with actual system schemas like pg_catalog. Pull request courtesy Evan Rusackas.

  This change is also backported to: 2.0.53

  References: #13472

• [postgresql] [bug] [reflection] Fixed reflection of PostgreSQL CHECK constraints where an expression made up of multiple parenthesized sub-expressions, such as (x IS NULL OR y IS NULL) AND (x IS NULL OR y IS NULL), would have its leading and trailing parentheses incorrectly stripped, producing an unbalanced and syntactically invalid reflected expression. Pull request courtesy Shaurya Singh.

  This change is also backported to: 2.0.52

  References: #13157

• [postgresql] [bug] Fixed bug in the PostgreSQL dialect where a single quote in a sequence, table, or schema name, such as one supplied via a schema_translate_map or an explicit Sequence, could result in a malformed nextval() statement. The quote is now properly escaped. Pull request courtesy dxbjavid.

  This change is also backported to: 2.0.52

  References: #13429

• [postgresql] [bug] Fixed issue in the asyncpg dialect where the version of the asyncpg DBAPI would always be reported as (99, 99, 99), as the version was looked up on the dialect's DBAPI wrapper module rather than on the asyncpg module itself.

mysql

• [mysql] [bug] Ensure that CREATE TABLE DDL statements for MySQL and MariaDB dialects render the table options in a deterministic order. Previously the order could change depending on the Python seed.

  This change is also backported to: 2.0.53

  References: #13523

• [mysql] [bug] Fixed issue where the version of the DBAPI reported by the mysqldb and pymysql dialects was incorrect. Current mysqlclient releases publish MySQLdb.version_info and no version string at all, so no version was reported; pymysql publishes __version__ and version_info as mysqlclient compatibility values, so the version reported for pymysql was that of the mysqlclient release it emulates, e.g. (2, 2, 8) rather than (1, 2, 0).

sqlite

• [sqlite] [usecase] Added support for multiple ON CONFLICT clauses within a single statement for the SQLite _sqlite.insert() construct; the _sqlite.Insert.on_conflict_do_update() and _sqlite.Insert.on_conflict_do_nothing() methods may now each be invoked more than once against the same construct, where the clauses render in the order in which they were established and are evaluated by SQLite in that order. As SQLite allows only the last ON CONFLICT clause to omit its conflict target, a _sqlite.Insert.on_conflict_do_nothing() call that omits _sqlite.Insert.on_conflict_do_nothing.index_elements must be the last clause established. Documentation is added at sqlite_on_conflict_multiple. Pull request courtesy Diemid Berozkin.

  References: #13113

• [sqlite] [bug] [reflection] Fixed issue in SQLite reflection where the name of a PRIMARY KEY, UNIQUE or FOREIGN KEY constraint would be reflected as None if the CONSTRAINT <name> clause were separated from the keyword that follows it by a newline rather than by spaces. As SQLite stores the CREATE TABLE statement as it was originally typed, this affected tables created from hand-written DDL that spans multiple lines. The regular expressions used to recover constraint names, as well as the ON UPDATE / ON DELETE, DEFERRABLE and INITIALLY options of a foreign key constraint, now accept any whitespace between tokens.

  This change is also backported to: 2.0.53

  References: #13528

• [sqlite] [bug] Reworked the regular expression that detects inline UNIQUE column constraints during SQLite CREATE TABLE reflection so that the whitespace separating a column's type from a following clause is matched unambiguously. The previous pattern had three overlapping quantifiers that could each consume a space character, so a column definition carrying a long run of whitespace in the stored schema made _reflection.Inspector.get_unique_constraints() spend cubic time backtracking before returning. Fix courtesy of Javid Khan.

  This change is also backported to: 2.0.52

  References: #13419

• [sqlite] [bug] Added a warning for query string arguments that are passed to a SQLite URL without the uri=true argument also being present, and which are not accepted by the sqlite3 driver itself. SQLite URI arguments such as mode or cache take effect only when URI mode is in use; without it they were previously discarded silently, so that a URL such as sqlite:///file:mydb?mode=memory would connect to a file on disk named file:mydb. Arguments intended for the driver itself may be passed using the _sa.create_engine.connect_args parameter.

  References: #13433

• [sqlite] [bug] [documentation] Corrected the SQLite documentation regarding shared cache memory databases, which incorrectly indicated that the named form sqlite:///file:mydb?mode=memory&cache=shared&uri=true makes use of QueuePool; a single-connection pool is used for this form. Documentation has also been added noting that a shared cache database exists only for as long as at least one connection to it remains open, so that ordinary pool operations such as _engine.Engine.dispose() or use of _sa.create_engine.pool_recycle will discard its contents.

  References: #13433

• [sqlite] [deprecated] Deprecated the selection of a single-connection pool class, i.e. SingletonThreadPool for pysqlite or StaticPool for aiosqlite, based on the presence of the mode=memory query string argument in a SQLite URL. Pool selection for SQLite is intended to be based on the database name alone, where only :memory: or an empty database name indicate a memory database; interpreting the query string additionally requires that assumptions be made regarding whether or not the resulting database can be shared among multiple connections. In a future release, such URLs will make use of QueuePool or AsyncAdaptedQueuePool as would any other URL. This notably includes the shared cache form sqlite:///file:mydb?mode=memory&cache=shared&uri=true, for which a queue pool is in fact the appropriate class, as a shared cache database supports multiple concurrent connections, whereas a single-connection pool causes such connections to share one transaction state. Applications that rely upon the present behavior should indicate the intended pool using the _sa.create_engine.poolclass parameter. Pull request courtesy Itachi-0xAI.

  References: #13433

mssql

• [mssql] [bug] [reflection] Fixed issue in SQL Server reflection where TEXT and NTEXT columns would be reflected with a spurious length of 16 and 8, respectively. These are unlengthed LOB datatypes; the value originates from the sys.columns.max_length column, which reports the size of the in-row LOB pointer rather than a character length for these types. The reflected _mssql.TEXT and _mssql.NTEXT types now have a length of None, so that a reflected table emits valid DDL when re-created, which previously failed with "Cannot specify a column width on data type text". Pull request courtesy Sam Debruyn.

  This change is also backported to: 2.0.53

  References: #13451

• [mssql] [bug] Improved disconnect detection for the mssql+mssqlpython dialect. Connection-level failures such as a dropped or reset network connection are now recognized by consulting the driver_error attribute of the exception, in addition to the message-based checks that were already in place, so that the affected connection is invalidated and the pool "pre ping" feature is able to recycle it. Pull request courtesy Sam Debruyn.

  References: #13441

oracle

• [oracle] [bug] Updated the oracledb async dialect where the async cursor adapter invoked __enter__() rather than __aenter__() on the underlying cursor. While these are equivalent in oracledb itself, the correct async form is now used for correctness. As AsyncCursor.__aenter__() was added in oracledb 2.0.1, the minimum supported oracledb version is now 2.0.1, declared via the oracle-oracledb extra. Pull request courtesy AVRC26.

  References: #13420

• [oracle] [bug] Fixed issue in the Oracle dialects where a _types.JSON value would be returned as an undecoded string for any JSON expression that is not a JSON column, such as a bound parameter, as well as for textual constructs with positional columns, such as _expression.text() combined with _expression.TextClause.columns().

  References: #13479

tests

• [tests] [usecase] The version specifications used by testing exclusions such as testing.fails_if("+asyncmy<0.2.13") now support a driver name, in which case the comparison is against the version of the DBAPI rather than that of the database server. Previously this form raised AssertionError: DBAPI version specs not supported yet.

• [tests] [bug] Altered the dialect reflection test test_check_constraint_parenthesized_expressions() so that it does not convert the reflected constraint to lowercase, which interferes with some third party dialect's representation of reflected check constraints.

  This change is also backported to: 2.0.53

  References: #13521

misc

• [bug] [installation] Added the AUTHORS file to the set of license files included in the built wheel, where previously only the LICENSE file was present. As the text of LICENSE refers to AUTHORS for the list of copyright holders, the reference would not resolve for tools that inspect an installed distribution.

  This change is also backported to: 2.0.53

  References: #13518

• [misc] [bug] Allowed the inspection registry to replace an existing registration with a reloaded callable from the same module and name. This avoids an assertion failure for tooling that unloads and reloads SQLAlchemy modules while still rejecting conflicting registrations. Pull request courtersy w-Jessamine.

  References: #10748