SqlAlchemy 2.0 中文文档（五十八）（5）

SqlAlchemy 2.0 中文文档（五十八）（4）https://developer.aliyun.com/article/1563136

2.0.29

发布日期：2024 年 3 月 23 日

orm

• [orm] [usecase]
  添加了对PEP 695 TypeAliasType 构造的支持，以及与 python 3.12 本地 type 关键字配合使用 ORM 注释声明形式时，当使用这些构造将链接到 PEP 593 Annotated 容器时，允许解析Annotated的过程。
  参考文献：#11130
  
• [orm] [bug]
  修复了声明性问题，其中使用Relationship而不是 Mapped 来对关系进行类型化，会无意中为该属性引入“动态”关系加载器策略。
  参考文献：#10611
  
• [orm] [bug]
  修复了在 ORM 注释声明中使用mapped_column()时出现的问题，其中使用mapped_column.index或mapped_column.unique设置为False的情况将被一个具有该参数设置为True的传入Annotated元素覆盖，即使直接mapped_column()元素更具体且应该优先。增强了协调布尔值的逻辑，以适应本地值为False仍优先于来自注释元素的传入True值的情况。
  参考文献：#11091
  
• [orm] [bug] [regression]
  修复了从版本 2.0.28 引入的回归，该回归是由于修复了#11085中新方法调整后缓存的参数值，该方法会干扰到subqueryload()加载器选项的实现，当使用此加载器选项与此加载器选项一起使用时，会使用一些更多的旧模式。
  参考文献：#11173
  

engine

• [engine] [bug]
  修复了“INSERT 语句的“Insert Many Values”行为功能中的问题，其中使用具有“内联执行”默认生成器的主键列，例如显式Sequence和显式架构名称，同时使用Connection.execution_options.schema_translate_map功能将无法正确呈现序列或参数，导致错误。
  参考：#11157
  
• [engine] [错误]
  在版本 2.0.10 中对#9618所做的调整进行了更改，该版本添加了批量  INSERT 的 RETURNING 行协调到传递给它的参数的行为。此行为包括已转换为 DB 的绑定参数值与返回的行值的比较，并不总是对于  SQL 列类型（例如 UUID）“对称”，具体取决于不同 DBAPI  接收此类值的方式与它们返回的方式，因此需要在这些列类型上增加额外的“哨兵值解析器”方法。不幸的是，这破坏了第三方列类型，如 SQLModel  中未实现此特殊方法的 UUID/GUID  类型，引发了错误“无法将结果集中的哨兵值与参数集匹配”。与其尝试进一步解释和文档化此“insertmanyvalues”特性的实现细节，包括新方法的公共版本，不如修改方法以不再需要此额外的转换步骤，并且进行比较的逻辑现在作用于预转换的绑定参数值与后处理值相比，后者应始终是匹配的数据类型。在罕见情况下，如果自定义  SQL 列类型也恰好用于批量 INSERT  的“哨兵”列，并且未接收和返回相同的值类型，则将引发“无法匹配”错误，但是缓解方法很简单，即传递与返回的相同 Python 数据类型。
  参考：#11160
  

sql

• [sql] [错误] [回归]
  修复了 1.4 系列中的回归问题，在 TypeEngine.with_variant() 方法的重构中引入的问题，该方法在 “with_variant()” 克隆原始 TypeEngine 而不是更改类型 中未能考虑到 .copy() 方法，这将丢失设置的变体映射。对于“schema”类型的非常特定情况，这会成为一个问题，其中包括 Enum 和 ARRAY 等类型，当它们在 ORM Declarative 映射中与 mixin 一起使用时，类型的复制就会发挥作用。现在也复制了变体映射。
  参考：#11176
  

typing

• [typing] [bug]
  修复了允许 asyncio 的 run_sync() 方法正确对参数进行类型标记的问题，根据传递的可调用对象使用 PEP 612 ParamSpec 变量。感谢 Francisco R. Del Roio 提供的拉取请求。
  参考：#11055
  

postgresql

• [postgresql] [usecase]
  PostgreSQL 方言现在在反射具有域作为类型的列时返回 DOMAIN 实例。之前，返回的是域数据类型。作为此更改的一部分，改进了域反射以同时返回文本类型的排序规则。感谢 Thomas Stephenson 提供的拉取请求。
  参考：#10693
  

测试

• [tests] [bug]
  已将改进后的测试套件应用于 SQLAlchemy 2.0，改进了与 asyncio 相关的测试运行方式，现在使用更新的 Python 3.11 asyncio.Runner 或其等价物，而不是依赖于先前基于 asyncio.get_running_loop() 的实现。这应该能够在 CPU 负载硬件上运行大量套件时防止事件循环出现故障，导致级联失败。
  参考：#11187
  

orm

• [orm] [usecase]
  增加了对 PEP 695 TypeAliasType 构造的支持，以及与 Python 3.12 本地 type 关键字一起使用 ORM Annotated Declarative 形式时的支持，当使用这些构造链接到 PEP 593 Annotated 容器时，允许解析 Annotated 时继续进行。
  参考：#11130
  
• [orm] [bug]
  修复了声明式中的问题，其中使用 Relationship 而不是 Mapped 来定义关系会无意中引入该属性的“动态”关系加载器策略。
  引用：#10611
  
• [orm] [bug]
  修复了使用 ORM 注释的声明式时，使用带有 mapped_column.index 或 mapped_column.unique 设置为 False 的 mapped_column() 会被传入的 Annotated 元素覆盖，即使直接的 mapped_column() 元素更具体且应该优先。调解布尔值的逻辑已经得到增强，以适应本地值为 False 的情况，仍然优先于注释元素传入的 True 值。
  引用：#11091
  
• [orm] [bug] [regression]
  修复了从版本 2.0.28 开始由于对#11085的修复而引起的回归，新的方法调整后缓存的参数值会干扰subqueryload()加载器选项的实现，当使用额外的加载器条件特性与此加载器选项一起使用时，内部使用了一些更传统的模式。
  引用：#11173
  

engine

• [engine] [bug]
  修复了在 “Insert Many Values” Behavior for INSERT statements 功能中的问题，其中使用主键列与“内联执行”默认生成器（如显式的 Sequence 并带有显式模式名称），同时使用 Connection.execution_options.schema_translate_map 功能将无法正确渲染序列或参数，导致错误。
  引用：#11157
  
• [engine] [bug]
  对版本 2.0.10 中对 #9618 进行的调整进行了更改，该版本增加了从批量插入中协调 RETURNING  行到传递给它的参数的行为。此行为包括将已经转换为数据库绑定参数值与返回的行值进行比较，对于 SQL 列类型如 UUID，不同的 DBAPI  接收这些值的方式与它们返回的方式具体取决于细节，因此需要对这些列类型进行额外的“哨兵值解析器”方法。不幸的是，这破坏了第三方列类型，如  SQLModel 中没有实现此特殊方法的 UUID/GUID  类型，引发错误“无法将结果集中的哨兵值与参数集匹配”。与其尝试进一步解释和文档化“insertmanyvalues”功能的这一实现细节，包括新方法的公共版本，不如将方法改进为不再需要这个额外的转换步骤，现在进行比较的逻辑是对预先转换的绑定参数值与后处理的值进行比较，后者应始终是匹配的数据类型。在不寻常的情况下，如果一个自定义的  SQL 列类型也碰巧用作批量插入的“哨兵”列，并且不接收和返回相同的值类型，将引发“无法匹配”错误，但是减轻措施很简单，应传递与返回相同的  Python 数据类型。
  参考：#11160
  

sql

• [sql] [错误] [回归]
  修复了 1.4 系列中的回归，该系列中对 TypeEngine.with_variant() 方法的重构，引入了“with_variant()”克隆原始 TypeEngine 而不是更改类型，未能适应 .copy() 方法，这将丢失设置的变体映射。对于非常特定的“模式”类型，这成为问题，该类型包括在 ORM Declarative 映射中与混合使用时的类型，其中类型的复制变得重要。现在也复制了变体映射。
  参考：#11176
  

输入

• [输入] [错误]
  修复了允许 asyncio run_sync() 方法正确对参数进行类型标记的输入问题，根据传递的可调用对象，使用了PEP 612 ParamSpec 变量。感谢 Francisco R. Del Roio 提交的拉取请求。
  参考：#11055
  

postgresql

• [postgresql] [用例]
  当反射一个具有域类型的列时，PostgreSQL 方言现在返回 DOMAIN 实例。以前，会返回域数据类型。作为这一改变的一部分，域反射还改进了以返回文本类型的排序规则。感谢 Thomas Stephenson 提交的拉取请求。
  参考：#10693
  

测试

• [tests] [bug]
  对于与 asyncio 相关的测试，对 SQLAlchemy 2.0 进行了改进，现在使用了更新的 Python 3.11 asyncio.Runner 或等价的后移版，而不是依赖于基于 asyncio.get_running_loop() 的先前实现。这样做希望能够防止在 CPU 负载硬件上运行大量测试时出现问题，其中事件循环似乎会变得损坏，导致级联故障。
  参考：#11187
  

2.0.28

发布日期：2024 年 3 月 4 日

orm

• [orm] [performance] [bug] [regression]
  调整了在 2.0.23 版中发布的 #10570 中进行的修复，其中添加了新逻辑来协调可能在 with_expression() 构造中使用的缓存键生成过程中可能变化的绑定参数值。新逻辑改变了将新绑定参数值与语句关联的方法，避免了需要深度复制语句的情况，这可能会对非常深/复杂的 SQL 构造造成显著的性能损耗。新方法不再需要这个深复制步骤。
  参考：#11085
  
• [orm] [bug] [regression]
  修复了由 #9779 引起的回归，其中在关系的 and_() 表达式中使用“secondary”表会失败，无法将其别名为与 Select.join() 表达式中“secondary”表的正常渲染相匹配，导致查询无效。
  参考：#11010
  

引擎

• [engine] [usecase]
  添加了新的核心执行选项Connection.execution_options.preserve_rowcount。设置后，DBAPI 游标的cursor.rowcount属性将在语句执行时无条件地被记忆化，因此无论 DBAPI 为任何类型的语句提供的值是什么，都可以使用CursorResult.rowcount属性从CursorResult中获取。这允许访问像 INSERT 和 SELECT 这样的语句的 rowcount，程度取决于所使用的 DBAPI 的支持。INSERT语句的“插入多个值”行为也支持此选项，并在设置时将确保为批量插入行时正确设置CursorResult.rowcount。
  参考：#10974
  

asyncio

• [asyncio] [错误]
  如果将QueuePool或其他非异步池类传递给create_async_engine()，则会引发错误。此引擎仅接受包括AsyncAdaptedQueuePool在内的符合 asyncio 的池类。其他池类，如NullPool，与同步和异步引擎兼容，因为它们不执行任何锁定。
  另请参阅
  API 文档 - 可用的池实现
  参考：#8771
  

测试

• [测试] [更改]
  tox.ini 文件中的 pytest 支持已更新以支持 pytest 8.1。
  

orm

• [orm] [性能] [错误] [回归]
  调整了在#10570中进行的修复，发布于 2.0.23，其中添加了新逻辑，用于协调可能在with_expression()构造中使用的缓存键生成过程中可能更改的绑定参数值。新逻辑改变了将新绑定参数值与语句关联的方法，避免了需要深度复制语句的需求，这可能会对非常深/复杂的 SQL 结构造成显著的性能损耗。新方法不再需要这个深度复制步骤。
  参考：#11085
  
• [orm] [bug] [regression]
  修复了由 #9779 引起的回归问题，其中在关系 and_() 表达式中使用 “secondary” 表会无法被别名化，以匹配 “secondary” 表在 Select.join() 表达式中通常的呈现方式，导致查询无效。
  参考：#11010
  

engine

• [engine] [usecase]
  添加了新的核心执行选项 Connection.execution_options.preserve_rowcount。当设置时，DBAPI 游标的 cursor.rowcount 属性将在语句执行时无条件地被存储，以便无论语句的任何种类，都可以使用 CursorResult.rowcount 属性从 CursorResult 获取 DBAPI 提供的任何值。这允许访问像 INSERT 和 SELECT 这样的语句的 rowcount，以 DBAPI 使用的程度支持。“INSERT 语句的插入多个值”行为 也支持此选项，并将确保在设置时对行进行批量插入时正确设置 CursorResult.rowcount。
  参考：#10974
  

asyncio

• [asyncio] [bug]
  如果将 QueuePool 或其他非 asyncio 连接池类传递给 create_async_engine()，则会引发错误。此引擎仅接受与 asyncio 兼容的连接池类，包括 AsyncAdaptedQueuePool。其他连接池类，如 NullPool，与同步和异步引擎均兼容，因为它们不执行任何锁定。
  另请参见
  API 文档 - 可用的连接池实现
  参考：#8771
  

测试

• [tests] [change]
  tox.ini 文件中的 pytest 支持已更新以支持 pytest 8.1。
  

2.0.27

发布日期：2024 年 2 月 13 日

postgresql

• [postgresql] [bug] [regression]
  由于刚发布的修复导致的回归，修复了#10863中一个无效的异常类被添加到“except”块的问题，除非确实发生了这样的捕获，否则不会被执行。已添加了一个模拟式测试以确保这种捕获在单元测试中被执行。
  参考：#11005
  

postgresql

• [postgresql] [bug] [regression]
  由于刚发布的修复导致的回归，修复了#10863中一个无效的异常类被添加到“except”块的问题，除非确实发生了这样的捕获，否则不会被执行。已添加了一个模拟式测试以确保这种捕获在单元测试中被执行。
  参考：#11005
  

2.0.26

发布日期：2024 年 2 月 11 日

orm

• [orm] [bug]
  使用缓存徽章替换了“加载器深度过深”的警告，对于  ORM 由于加载器选项链过于深而禁用缓存的那些语句，向 SQL 日志中添加了一个较短的消息。此警告突出显示的条件难以解决，并且通常只是 ORM  在应用 SQL 缓存时的限制。未来的功能可能包括调整禁用缓存的阈值的能力，但目前这个警告将不再是一个麻烦。
  参考：#10896
  
• [orm] [bug]
  修复了一个问题，即如果该类型在类体内部局部声明，则无法在Mapped容器类型中使用类型（例如枚举）。现在，用于评估的本地变量范围包括类体本身的范围。此外，如果以字符串形式或使用将来的注释模式，Mapped中的表达式也可以引用类名本身。
  参考：#10899
  
• [orm] [bug]
  修复了一个问题，即在使用 Session.delete() 与 Mapper.version_id_col 功能时，如果由于对象上的 relationship.post_update 的使用导致针对目标对象的附加 UPDATE，则使用正确的版本标识符将失败。这个问题类似于版本 2.0.25 中刚刚修复的 #10800 的情况，仅对更新情况进行了修复。
  参考：#10967
  
• [orm] [bug]
  修复了在实现with_expression()时，如果使用不可缓存的 SQL 表达式，则会引发断言错误的问题；这是自 1.4 以来的 2.0 回归。
  参考：#10990
  

examples

• [examples] [bug]
  修复了历史元示例中的回归，使用MetaData.to_metadata()复制历史表时也会复制索引（这是一件好事），但无论用于这些索引的命名方案如何，都会导致索引命名冲突。现在这些索引都添加了“_history”后缀，方式与表名相同。
  参考：#10920
  
• [examples] [bug]
  通过在所有表中添加Identity构造，并允许在此后端上进行主键生成，修复了 examples/performance 中性能示例脚本在 Oracle 数据库中大部分情况下的运行问题。仍有一些“原始 DBAPI”情况与 Oracle 不兼容。
  

sql

• [sql] [bug]
  修复了case()中确定表达式类型的逻辑问题，可能导致如果“whens”中的最后一个元素没有类型，则结果为NullType，或者在其他情况下，类型可能解析为None。逻辑已更新为扫描所有给定表达式，以便使用第一个非空类型，并始终确保存在类型。拉取请求由 David Evans 提供。
  参考：#10843
  

typing

• [typing] [bug]
  修复了PoolEvents.checkin()事件的类型签名，指示给定的DBAPIConnection参数在连接被无效化的情况下可能为None。
  

postgresql

• [postgresql] [usecase] [reflection]
  添加了对带有“NO INHERIT”标记的 PostgreSQL CHECK 约束的反射支持，设置反射数据中的关键字 no_inherit=True。拉取请求由 Ellis Valentiner 提供。
  参考：#10777
  
• [postgresql] [usecase]
  支持 PostgreSQL CREATE TABLE 的 USING 选项，以指定用于存储新表内容的访问方法。拉取请求由 Edgar Ramírez-Mondragón 提供。
  另请参阅
  PostgreSQL 表选项
  参考：#10904
  
• [postgresql] [usecase]
  正确地将 PostgreSQL 的 RANGE 和 MULTIRANGE 类型类型化为 Range[T] 和 Sequence[Range[T]]。引入了实用序列 MultiRange，以便更好地支持 MULTIRANGE 类型的互操作性。
  参考：#9736
  
• [postgresql] [usecase]
  在从 Range 或 MultiRange 实例推断数据库类型时，区分 INT4 和 INT8 范围和多范围类型，如果值适合 INT4，则优先选择 INT4。
  
• [postgresql] [bug] [regression]
  在发布 2.0.24 版本中由于 #10717 导致 asyncpg 方言中的回归问题，现在尝试在终止之前优雅地关闭 asyncpg 连接的更改不会对除超时错误之外的其他潜在连接相关异常回退到 terminate()，没有考虑到优雅的 .close() 尝试由于其他原因（如连接错误）失败的情况。
  参考：#10863
  
• [postgresql] [bug]
  修复了在使用 PostgreSQL 方言时，使用 Uuid 数据类型且将 Uuid.as_uuid 参数设置为 False 时出现的问题，ORM 优化的 INSERT 语句（例如“insertmanyvalues”功能）将无法正确对齐批量 INSERT 语句的主键 UUID 值，导致错误。类似的问题也已经为 pymssql 驱动程序修复。
  

mysql

• [mysql] [bug]
  修复了在 MySQL 列中未正确反映 NULL/NOT NULL 的问题，该列还指定了 VIRTUAL 或 STORED 指令。感谢 Georg Wicke-Arndt 的拉取请求。
  参考：#10850
  
• [mysql] [bug]
  修复了 asyncio 方言 asyncmy 和 aiomysql 中的问题，其中它们的 .close() 方法显然不是一个优雅的关闭。替换为非标准的 .ensure_closed() 方法，该方法是可等待的，并将 .close() 移动到所谓的“终止”情况。
  参考：#10893
  

mssql

• [mssql] [bug]
  修复了在使用 pymssql 方言时，当使用Uuid数据类型且Uuid.as_uuid参数设置为 False 时的问题。ORM 优化的 INSERT 语句（例如“insertmanyvalues”功能）将无法正确对齐用于批量 INSERT 语句的主键 UUID 值，导致错误。类似的问题也已针对 PostgreSQL 驱动程序进行了修复。
  

oracle

• [oracle] [performance] [bug]
  更改了  Oracle 方言的默认 arraysize，以使用驱动程序设置的值，即在撰写本文时，cx_oracle 和 oracledb 均为  100。以前默认值为 50。将值设置为 50 可能会导致与仅使用 cx_oracle/oracledb  在较慢的网络上获取许多行时相比，性能显着下降。
  参考：#10877
  

orm

• [orm] [bug]
  用更短的消息替换了“加载器深度过深”的警告，该消息添加到  SQL 日志中的缓存徽章中，对于那些由于 ORM 禁用缓存而导致的加载器选项链过深的语句。此警告突出显示的条件很难解决，通常只是 ORM  在应用 SQL 缓存时的一个限制。未来的功能可能包括调整禁用缓存的阈值的能力，但目前该警告将不再成为一个麻烦。
  参考：#10896
  
• [orm] [bug]
  修复了在类体内部声明本地类型（例如枚举）时无法在Mapped容器类型中使用该类型的问题。现在，用于 eval 的本地变量范围包括类体本身。此外，Mapped中的表达式也可以引用类名本身，如果作为字符串或使用未来注释模式。
  参考：#10899
  
• [orm] [bug]
  修复了使用Session.delete()与Mapper.version_id_col功能一起时，如果由于对象上的relationship.post_update的使用导致针对目标对象发出额外的 UPDATE，则会失败使用正确的版本标识符的问题。该问题类似于#10800，只是在仅有更新的情况下在版本 2.0.25 中修复了。
  参考：#10967
  
• [orm] [错误]
  修复了在 with_expression() 实现中，如果使用的 SQL 表达式不可缓存，则会引发断言错误的问题；这是自 1.4 版以来的 2.0 版本的退化。
  参考：#10990
  

示例

• [示例] [错误]
  修复了 history_meta 示例中的退化问题，其中使用 MetaData.to_metadata() 来复制历史表也会复制索引（这是好事），但无论使用的索引命名方案如何，都会导致索引命名冲突。现在为这些索引添加了“_history”后缀，方式与为表名添加后缀相同。
  参考：#10920
  
• [示例] [错误]
  通过向所有表添加 Identity 结构并允许主键在此后端上生成，修复了 examples/performance 中性能示例脚本在 Oracle 数据库中的大部分兼容性问题。一些“原始 DBAPI” 情况仍不兼容 Oracle。
  

sql

• [sql] [错误]
  修正了 case() 中确定表达式类型的逻辑问题，如果“whens”中的最后一个元素没有类型或在其他情况下类型可能解析为 None，则可能导致 NullType。逻辑已更新以扫描所有给定表达式，以使用第一个非空类型，并始终确保存在类型。感谢 David Evans 提交的拉取请求。
  参考：#10843
  

类型

• [类型] [错误]
  修正了 PoolEvents.checkin() 事件的类型签名，指示给定的 DBAPIConnection 参数在连接被失效的情况下可能为 None。
  

postgresql

• [postgresql] [用例] [反射]
  增加了对 PostgreSQL CHECK 约束的反射支持，标记为“NO INHERIT”，在反射数据中设置键 no_inherit=True。感谢 Ellis Valentiner 提交的拉取请求。
  参考：#10777
  
• [postgresql] [用例]
  为了支持 PostgreSQL 的 CREATE TABLE 中的 USING 选项，以指定用于存储新表内容的访问方法。感谢 Edgar Ramírez-Mondragón 提交的拉取请求。
  另请参阅
  PostgreSQL 表选项
  参考：#10904
  
• [postgresql] [usecase]
  正确地将 PostgreSQL RANGE 和 MULTIRANGE 类型类型化为Range[T]和Sequence[Range[T]]。引入了实用程序序列MultiRange，以更好地支持 MULTIRANGE 类型的互操作性。
  参考：#9736
  
• [postgresql] [usecase]
  当从Range或MultiRange实例推断数据库类型时，区分 INT4 和 INT8 范围和多范围类型，如果值适合 INT4，则优先使用 INT4。
  
• [postgresql] [bug] [regression]
  在 2.0.24 版本中由于#10717导致的 asyncpg 方言中的回归问题修复，该变更现在在终止之前尝试优雅地关闭 asyncpg 连接，不会为除超时错误之外的其他潜在连接相关异常回退到terminate()，没有考虑到当优雅的.close()尝试由于其他原因（如连接错误）失败时的情况。
  参考：#10863
  
• [postgresql] [bug]
  修复了在使用 PostgreSQL 方言时，当使用Uuid数据类型且Uuid.as_uuid参数设置为 False 时的问题。ORM 优化的 INSERT 语句（例如“insertmanyvalues”功能）不会正确对齐批量 INSERT 语句的主键 UUID 值，导致错误。pymssql 驱动程序也修复了类似的问题。
  

mysql

• [mysql] [bug]
  修复了一个问题，即当 MySQL 列还指定了 VIRTUAL 或 STORED 指令时，NULL/NOT NULL 未能正确反映。感谢 Georg Wicke-Arndt 的拉取请求。
  参考：#10850
  
• [mysql] [bug]
  修复了 asyncio 方言 asyncmy 和 aiomysql 中的一个问题，即它们的.close()方法显然不是一个优雅的关闭。将其替换为非标准的.ensure_closed()方法，该方法可等待，并将.close()移到所谓的“终止”情况。
  参考：#10893
  

mssql

• [mssql] [bug]
  修复了使用Uuid数据类型以及设置Uuid.as_uuid参数为  False 时的问题，当使用 pymssql 方言时，ORM 优化的 INSERT  语句（例如“insertmanyvalues”功能）将不正确地对齐批量 INSERT 语句的主键 UUID 值，导致错误。类似的问题也已在  PostgreSQL 驱动程序中修复。
  

oracle

• [oracle] [performance] [bug]
  更改了  Oracle 方言的默认 arraysize，以使用驱动程序设置的值，在撰写本文时，cx_oracle 和 oracledb 的值均为  100。先前，默认值设置为 50。默认值为 50 可能导致与仅使用 cx_oracle/oracledb  在较慢的网络上获取数百行时相比出现显着的性能回退。
  参考：#10877
  

2.0.25

发布日期：2024 年 1 月 2 日

orm

• [orm] [usecase]
  添加了对 Python 3.12 pep-695 类型别名结构的初步支持，用于解析 ORM 注释声明映射的自定义类型映射。
  参考：#10807
  
• [orm] [bug]
  修复了在同时使用relationship.post_update特性和使用映射器 version_id_col 时可能导致第二个 UPDATE 语句未能使用正确的版本标识符的问题，假设在该 flush 中已经发出了一个已经增加了版本计数器的 UPDATE。
  参考：#10800
  
• [orm] [bug]
  修复了 ORM 注释声明会错误解释没有指定集合为 uselist=True 的关系左侧的问题，如果左侧类型被给定为类而不是字符串，并且没有使用 future-style 注释。
  参考：#10815
  

sql

• [sql] [bug]
  在布尔比较的否定情况下改进了any_() / all_() 的编译，现在将呈现NOT (expr)而不是将等式操作符反转为不等号，允许对这些非典型操作符进行更精细的否定控制。
  参考：#10817
  

typing

• [typing] [bug]修复了在版本 2.0.24 中向sqlalchemy.sql.functions模块添加了类型后引起的回归问题，作为#6810的一部分：

• 进一步增强了 pep-484 类型提示，以便从 sqlalchemy.sql.expression.func 派生的元素更有效地与 ORM 映射属性一起使用（#10801）
  
• 修复了传递给函数的参数类型，以便再次正确解释文本表达式，如字符串和整数（#10818）
  

• 引用：#10801，#10818
  

asyncio

• [asyncio] [错误]
  修复了 asyncio 版本的连接池中的关键问题，调用 AsyncEngine.dispose() 会生成一个新的连接池，该连接池未完全重新建立对 asyncio 兼容互斥锁的使用，导致在使用像 asyncio.gather() 这样的并发特性时，在 asyncio 上下文中发生死锁时使用了普通的 threading.Lock()。
  此更改也 回溯 到：1.4.51
  引用：#10813
  

oracle

• [oracle] [asyncio]
  在 asyncio 模式下添加了对 python-oracledb 的支持，使用了新发布的支持 asyncio 的 oracledb DBAPI 版本。 对于 2.0 系列，这是一个预览版本，当前实现尚未包括对 AsyncConnection.stream() 的支持。 改进的支持计划在 SQLAlchemy 的 2.1 发布中实现。
  引用：#10679
  

orm

• [orm] [使用情况]
  在为 ORM 注释性声明映射解析自定义类型映射时，添加了对 Python 3.12 pep-695 类型别名结构的初步支持。
  引用：#10807
  
• [orm] [错误]
  修复了同时使用 relationship.post_update 功能和使用 mapper version_id_col 时可能导致的问题，在这种情况下，后续更新功能发出的第二个 UPDATE 语句可能无法使用正确的版本标识符，假设在该刷新中已经发出了一个已经增加了版本计数器的 UPDATE。
  引用：#10800
  
• [orm] [错误]
  修复了 ORM 注释性声明在没有指定任何集合的情况下误解释关系左侧的问题，如果左侧类型是作为类而不是字符串给出的，并且没有使用未来样式注释。
  引用：#10815
  

sql

• [sql] [错误]
  改进了在布尔比较的否定上下文中any_() / all_()的编译，现在将呈现NOT (expr)而不是将等式运算符反转为不等于，允许更精细地控制这些非典型运算符的否定。
  参考：#10817
  

输入

• [输入] [错误]修复了在版本 2.0.24 中添加到sqlalchemy.sql.functions模块的类型提示引起的回归，作为#6810的一部分：

• 进一步增强了 pep-484 类型提示，以允许从sqlalchemy.sql.expression.func派生的元素更有效地与 ORM 映射的属性一起使用（#10801）
  
• 修复了传递给函数的参数类型，以便像字符串和整数这样的文字表达式再次被正确解释（#10818）
  

• 参考：#10801, #10818
  

asyncio

• [asyncio] [错误]
  修复了在连接池的 asyncio 版本中的关键问题，调用AsyncEngine.dispose()会产生一个未完全重新建立使用 asyncio 兼容互斥锁的新连接池，导致在使用并发功能时（如asyncio.gather()）在 asyncio 上下文中使用普通的threading.Lock()会导致死锁。
  此更改也回溯到：1.4.51
  参考：#10813
  

oracle

• [oracle] [asyncio]
  在 asyncio 模式下添加了对 python-oracledb 的支持，使用包含 asyncio 支持的新发布版本的oracledb DBAPI。对于 2.0 系列，这是一个预览版本，当前实现尚未包括对AsyncConnection.stream()的支持。改进的支持计划在 SQLAlchemy 的 2.1 版本中实现。
  参考：#10679
  

2.0.24

发布日期：2023 年 12 月 28 日

orm

• [orm] [错误]
  改进了首次在版本 0.9.8 中发布的用于#3208的修复，其中声明内部使用的类注册表可能会受到竞争条件的影响，即在个别映射类同时被垃圾回收时，同时正在构建新的映射类，这可能发生在某些测试套件配置或动态类创建环境中。除了已添加的弱引用检查外，还首先复制正在迭代的项目列表，以避免“在迭代时更改列表”错误。拉取请求由  Yilei Yang 提供。
  此更改也回溯到：1.4.51
  参考：#10782
  
• [orm] [bug]
  修复了在未对非初始化的mapped_column()构造上使用foreign()注释会产生一个没有类型的表达式的问题，然后在实际列初始化时未更新，导致关系未适当确定use_get的问题。
  参考：#10597
  
• [orm] [bug]
  改进了当工作单元过程将主键列的值设置为 NULL 时产生的错误消息，原因是具有对该列的依赖规则的相关对象被删除，包括不仅目标对象和列名，还包括源列，从中 NULL 值起源。拉取请求由 Jan Vollmer 提供。
  参考：#10668
  
• [orm] [bug]
  修改了MappedAsDataclass、DeclarativeBase和DeclarativeBaseNoMeta使用的__init_subclass__()方法，以接受任意的**kw并将其传播到super()调用，允许更大的灵活性安排使用__init_subclass__()关键字参数的自定义超类和混入。拉取请求由 Michael Oliver 提供。
  参考：#10732
  
• [orm] [bug]
  确保在 ORM 启用的 INSERT、UPDATE 和 DELETE 语句的returning()部分中使用的Bundle对象的用例经过测试并完全可用。这在以前从未明确实现或测试过，并且在 1.4 系列中无法正常工作；在 2.0 系列中，带有 WHERE 条件的 ORM UPDATE/DELETE 缺少实现方法，导致无法使用Bundle对象。
  参考：#10776
  
• [orm] [bug]
  修复了 2.0 版本中MutableList的回归问题，其中检测序列的例程未能正确过滤字符串或字节实例，导致无法将字符串值分配给特定索引（而非序列值将正常工作）。
  参考：#10784
  

engine

• [engine] [bug]
  修复了在将URL对象转换为字符串时，使用URL.render_as_string()方法对用户名和密码组件进行 URL 编码的问题，通过使用 Python 标准库urllib.parse.quote，同时允许加号和空格保持不变，以支持 SQLAlchemy 的非标准 URL 解析，而不是多年前的传统自制例程。感谢 Xavier NUNN 的拉取请求。
  参考：#10662
  

sql

• [sql] [bug]
  修复了 SQL 元素的字符串化问题，在没有传递特定方言的情况下，遇到特定方言元素（如 PostgreSQL 的“on conflict do update”构造）时，未能提供适当状态以渲染构造，导致内部错误。
  参考：#10753
  
• [sql] [bug]
  修复了针对 DML 构造（如insert()构造）的CTE的字符串化或编译失败的问题，由于错误地检���到语句整体为 INSERT，导致内部错误。
  

schema

• [schema] [bug]
  修复了在创建像Table这样的对象时，当参数本身作为元组传递时，错误报告对意外模式项的处理不正确，导致格式错误。错误消息已经更新为使用 f-strings。
  参考：#10654
  

typing

• [typing] [bug]
  为 sqlalchemy.sql.functions 模块完成了 pep-484 类型注解。针对 func 元素进行的 select() 构造现在应该具有填充的返回类型。
  参考：#6810
  

asyncio

• [asyncio] [change]
  async_fallback 方言参数现已弃用，并将在 SQLAlchemy 2.1 中移除。这个标志在 SQLAlchemy 的测试套件中已经有一段时间没有使用了。通过使用 greenlet_spawn() 在 greenlet 中运行代码，asyncio 方言仍然可以以同步方式运行。
  

postgresql

• [postgresql] [bug]
  调整了 asyncpg 方言，使得当使用 terminate() 方法丢弃一个无效的连接时，方言将首先尝试使用带有超时的 .close() 优雅地关闭连接，如果操作仅在异步事件循环上下文中进行。这允许 asyncpg 驱动程序处理最终化 TimeoutError，包括能够关闭长时间运行的查询服务器端，否则该查询可能会在程序退出后继续运行。
  参考：#10717
  

mysql

• [mysql] [bug]
  修复了使用旧于 1.0 版本的 PyMySQL 进行池预先检查时由修复票号 #10492 引入的回归。
  此更改也已回溯至：1.4.51
  参考：#10650
  

tests

• [tests] [bug]
  对测试套件进行了改进，进一步加固了在未安装 Python greenlet 时运行的能力。现在有一个 tox 目标，其中包含标记“nogreenlet”，将在未安装 greenlet 的情况下运行测试套件（请注意，它仍然会在 tox 配置中临时安装 greenlet）。
  参考：#10747
  

orm

• [orm] [bug]
  改进了首次在版本 0.9.8 中发布的针对 #3208 实施的修复，其中 declarative  内部使用的类注册表可能会在同时进行垃圾回收的个别映射类与新映射类构造时发生竞争条件，这可能会在某些测试套件配置或动态类创建环境中发生。除了已添加的  weakref 检查外，还首先复制正在迭代的项目列表，以避免“在迭代时更改列表”错误。感谢 Yilei Yang 提交的拉取请求。
  此更改也已回溯至：1.4.51
  参考：#10782
  
• [orm] [bug]
  修复了在非初始化的 mapped_column() 构造上使用 foreign() 注释会产生没有类型的表达式的问题，然后在实际列的初始化时不会更新，导致关系无法适当地确定 use_get 等问题的问题。
  参考：#10597
  
• [orm] [bug]
  改进了工作单元过程生成的错误消息，当由于相关对象对该列具有依赖规则并且被删除时，工作单元过程将主键列的值设置为 NULL 时，不仅包括目标对象和列名，还包括源列的列名，从而使 NULL 值起源于哪里。拉取请求由 Jan Vollmer 提供。
  参考：#10668
  
• [orm] [bug]
  修改了 MappedAsDataclass、DeclarativeBase 和 DeclarativeBaseNoMeta 使用的 __init_subclass__() 方法，接受任意的 **kw 并将它们传播到 super() 调用，允许更灵活地安排使用 __init_subclass__() 关键字参数的自定义超类和混入。拉取请求由 Michael Oliver 提供。
  参考：#10732
  
• [orm] [bug]
  确保在 ORM 启用的 INSERT、UPDATE 和 DELETE 语句的 returning() 部分中使用的 Bundle 对象的用例经过测试并且完全可用。这在之前从未明确实现或测试过，在 1.4 系列中没有正常工作；在 2.0 系列中，具有 WHERE 条件的 ORM UPDATE/DELETE 缺少实现方法，阻止了 Bundle 对象的正常工作。
  参考：#10776
  
• [orm] [bug]
  修复了在 2.0 中的 MutableList 中的回归，其中检测序列的例程不会正确地过滤出字符串或字节实例，使得无法将字符串值分配给特定索引（而非序列值则正常工作）。
  参考：#10784
  

引擎

• [engine] [bug]
  修复了在使用URL.render_as_string()方法将用户名和密码组件进行 URL 编码时的问题，通过使用 Python 标准库urllib.parse.quote，同时允许加号和空格保持不变，以支持 SQLAlchemy 的非标准 URL 解析，而不是多年前的传统自制程序。感谢 Xavier NUNN 的拉取请求。
  参考：#10662
  

sql

• [sql] [bug]
  修复了 SQL 元素的字符串化问题，其中未传递特定方言时，遇到特定方言元素（如 PostgreSQL 的“on conflict do update”构造），然后未提供适当状态以呈现构造的字符串化方言，导致内部错误。
  参考：#10753
  
• [sql] [bug]
  修复了针对 DML 构造（如insert()）的CTE进行字符串化或编译时失败的问题，由于错误地检测到语句整体是一个 INSERT，导致内部错误。
  

模式

• [schema] [bug]
  修复了在创建对象（如Table）时，对于意外模式项的错误报告处理不正确的问题，该参数本身被传递为元组，导致格式化错误。错误消息已经更新为使用 f-strings。
  参考：#10654
  

类型注释

• [typing] [bug]
  完成了sqlalchemy.sql.functions模块的 pep-484 类型注释。针对func元素进行的select()构造现在应该具有填充的返回类型。
  参考：#6810
  

asyncio

• [asyncio] [change]
  async_fallback方言参数现已弃用，并将在 SQLAlchemy 2.1 中删除。这个标志已经有一段时间没有在 SQLAlchemy 的测试套件中使用了。通过使用greenlet_spawn()在 greenlet 中运行代码，asyncio 方言仍然可以以同步方式运行。
  

postgresql

• [postgresql] [bug]
  调整了 asyncpg 方言，使得当使用 terminate() 方法丢弃一个无效的连接时，方言将首先尝试使用带有超时的 .close() 优雅地关闭连接，仅在异步事件循环上下文中进行该操作时。这允许 asyncpg 驱动程序处理最终化 TimeoutError，包括能够在程序退出后继续运行的长时间运行的查询服务器端。
  参考：#10717
  

mysql

• [mysql] [bug]
  修复了使用旧于 1.0 版本的 PyMySQL 与池预先 PING 时由修复票证 #10492 引入的回归问题。
  此更改还回溯到：1.4.51
  参考：#10650
  

测试

• [tests] [bug]
  对测试套件进行改进，以进一步加强在未安装 Python greenlet 时运行的能力。现在有一个 tox 目标包含标记“nogreenlet”，将以未安装 greenlet 的方式运行测试套件（注意，它仍然在 tox 配置中临时安装 greenlet）。
  参考：#10747

SqlAlchemy 2.0 中文文档（五十八）（6）https://developer.aliyun.com/article/1563138