SqlAlchemy 2.0 中文文档（六十）（4）

SqlAlchemy 2.0 中文文档（六十）（3）https://developer.aliyun.com/article/1560730

1.3.13

发布日期：2020 年 1 月 22 日

orm

• [orm] [performance]
  发现了一个性能问题，即基于映射关系构建连接的系统。子句适配系统将用于大多数连接表达式，包括在常见情况下不需要适配的情况。已经对发生适配的条件进行了优化，以便在简单关系中的平均非别名连接中，没有“secondary”表使用约 70%的函数调用。
  
• [orm] [bug] [engine]
  添加了测试支持，并修复了在 ORM 查询领域中为短暂对象创建的大量不必要的引用循环，这主要是在 ORM 查询领域。非常感谢 Carson Ip 的帮助。
  参考：#5050，#5056，#5071
  
• [orm] [bug]
  修复了在 1.3.0b3 版本中引入的加载器选项中的回归问题，通过 #4468，其中使用PropComparator.of_type()创建加载器选项，针对的是一个继承自前一个关系引用的实体的别名实体，将无法生成匹配路径。另请参见在此相同版本中修复的 #5082，涉及类似类型的问题。
  参考：#5107
  
• [orm] [bug]
  修复了在 1.3.0b3 版本中引入的连接式贪婪加载中的回归问题，通过 #4468，在使用RelationshipProperty.of_type()创建跨越with_polymorphic()到一个多态子类的连接选项，然后沿着常规映射关系进一步失败的情况，因为多态子类不会以可以被加载策略定位的方式将自身添加到加载路径中。已进行调整以解决此场景。
  参考：#5082
  
• [orm] [bug]
  修复了在  ORM  刷新过程中的警告，当删除使用“version_id”功能的对象时，该警告未被测试覆盖。通常情况下，此警告是无法触及的，除非使用的方言将“supports_sane_rowcount”标志设置为  False，这在一些 MySQL 配置以及较旧的 Firebird 驱动程序以及可能一些第三方方言中可能发生。
  参考：#5068
  
• [orm] [bug]
  修复了使用连接式懒加载时，当针对查询使用Query.group_by()时，查询未正确包装在子查询中的错误。当使用任何形式的结果限制方法时，例如  DISTINCT、LIMIT、OFFSET，连接式懒加载将行限制查询嵌入到子查询中，以便不影响集合结果。由于某种原因，GROUP BY  的存在从未包含在这个标准中，即使它具有与使用 DISTINCT 相似的效果。此外，该 bug 将阻止在大多数数据库平台上使用 GROUP BY  作为连接式懒加载查询的所有部分，因为这些平台禁止在查询中存在非聚合、非分组的列，而连接式懒加载的附加列将不被数据库接受。
  参考：#5065
  

引擎

• [engine] [bug]
  当使用具有绑定值处理器的数据类型（例如“扩展 IN”参数）时，修复了在Compiled对象上收集的值处理器集合会发生变异的问题；特别地，这意味着当使用语句缓存和/或烘焙查询时，同一  compiled._bind_processors  集合将同时发生变异。由于这些处理器对于给定的绑定参数命名空间每次都是相同的函数，因此这个问题实际上没有负面影响，然而，Compiled对象的执行绝不能导致其状态发生任何更改，特别是考虑到它们被设计为一旦完全构建就是线程安全和可重复使用的。
  参考：#5048
  

sql

• [sql] [usecase]
  使用GenericFunction创建的函数现在可以通过将quoted_name结构分配给对象的.name 元素来指定函数名称是否应该用引号括起来。在 1.3.4 之前，从不将引号应用于函数名称，并且在#4467中引入了一些引号，但没有一种方法来强制对一个混合大小写名称进行引用。此外，当用作名称时，quoted_name结构将正确地在函数注册表中注册其小写名称，以便该名称继续通过func.注册表可用。
  另请参阅
  GenericFunction
  参考：#5079
  

postgresql

• [postgresql] [usecase]
  添加了对CTE构造的前缀支持，以支持 Postgresql 12 的“MATERIALIZED”和“NOT MATERIALIZED”短语。感谢 Marat Sharafutdinov 的拉取请求。
  另请参阅
  HasCTE.cte()
  参考：#5040
  
• [postgresql] [bug]
  修复了 PostgreSQL 方言无法解析反射的 CHECK 约束的问题，该约束是一个布尔值函数（而不是布尔值表达式）。
  参考：#5039
  

mssql

• [mssql] [bug]
  修复了将时区感知的datetime值转换为字符串以用作DATETIMEOFFSET列的参数值时，省略了小数秒的问题。
  参考：#5045
  

tests

• [tests] [bug]
  修复了一些测试失败的问题，这些问题可能是由于 SQLite 文件锁定问题在 Windows 上发生，以及连接池相关测试中的一些时间问题；感谢 Federico Caselli 的拉取请求。
  参考：#4946
  
• [tests] [postgresql]
  通过测试确保了 PostgreSQL 数据库对两阶段事务需求的改进，测试 max_prepared_transactions 是否设置为大于 0 的值。感谢 Federico Caselli 的拉取请求。
  参考：#5057
  

misc

• [bug] [ext]
  修复了 sqlalchemy.ext.serializer 中的错误，其中一个唯一的BindParameter对象可能会与自身冲突，如果它同时存在于映射本身和查询的过滤条件中，其中一侧将用于与未反序列化版本对比，另一侧将使用反序列化版本。在BindParameter中添加了类似于其“clone”方法的逻辑，该方法在反序列化时将参数名称唯一化，以避免与原始名称冲突。
  参考：#5086
  

orm

• [orm] [performance]
  通过系统发现了一个性能问题，即基于映射关系构建连接的问题。子句适配系统将用于大多数连接表达式，包括在常见情况下不需要适配的情况。已经对发生适配的条件进行了优化，以便平均非别名连接沿着简单关系使用约 70%的函数调用。
  
• [orm] [bug] [engine]
  添加了测试支持，并修复了在 ORM 查询中为短暂对象创建的大量不必要的引用循环。非常感谢 Carson Ip 在此方面的帮助。
  参考：#5050，#5056，#5071
  
• [orm] [bug]
  修复了在 1.3.0b3 中引入的加载器选项回归，通过#4468，使用PropComparator.of_type()创建一个针对前一个关系引用的实体的继承子类的别名实体的加载器选项将无法生成匹配路径。另请参见#5082，在此相同版本中修复了类似类型的问题。
  参考：#5107
  
• [orm] [bug]
  修复了在 1.3.0b3 中引入的连接急加载中的回归，通过#4468，使用RelationshipProperty.of_type()创建跨with_polymorphic()到多态子类的连接选项，然后沿着常规映射关系进一步失败，因为多态子类不会以可以被加载策略定位的方式将自身添加到加载路径中。已进行微调以解决此场景。
  参考：#5082
  
• [orm] [bug]
  修复了在  ORM  刷新过程中的警告，当删除使用“version_id”功能的对象时，该警告未被测试覆盖。通常情况下，除非使用的方言将“supports_sane_rowcount”标志设置为  False，否则无法到达此警告，尽管对于一些 MySQL 配置以及较旧的 Firebird 驱动程序以及可能的一些第三方方言来说，这是可能的。
  参考：#5068
  
• [orm] [bug]
  修复了一个错误，即使用连接的急加载时，当针对查询使用Query.group_by()时，查询不会正确地包装在子查询中。当使用任何种类的结果限制方法时，例如  DISTINCT、LIMIT、OFFSET，连接的急加载将行限制的查询嵌入到子查询中，以便不影响集合结果。出于某种原因，GROUP BY  的存在从未包含在此标准中，即使它具有与使用 DISTINCT 相同的效果。此外，该错误将阻止对大多数数据库平台的连接急加载查询使用 GROUP  BY，这些平台禁止在查询中存在非聚合、非分组的列，因为连接的急加载的附加列不会被数据库接受。
  参考：#5065
  

engine

• [engine] [bug]
  修复了一个问题，当使用具有绑定值处理器的数据类型与“展开 IN”参数一起使用时，Compiled对象上的值处理器集合会发生变异；特别是，这意味着当使用语句缓存和/或烘焙查询时，同一  compiled._bind_processors  集合会同时发生变异。由于这些处理器对于给定的绑定参数命名空间每次都是相同的函数，因此这个问题实际上没有任何负面影响，但是，Compiled对象的执行绝不应该导致其状态发生任何更改，特别是考虑到它们旨在在完全构造后是线程安全和可重复使用的。
  参考：#5048
  

sql

• [sql] [usecase]
  使用GenericFunction创建的函数现在可以通过将quoted_name构造分配给对象的.name 元素来指定函数的名称是否应该带引号或不带引号。在 1.3.4 之前，函数名称从不应用引号，#4467中引入了一些引号，但没有一种方法可以强制对混合大小写名称进行引号。此外，当作为名称使用quoted_name构造时，将正确在函数注册表中注册其小写名称，以便名称继续通过func.注册表可用。
  另请参阅
  GenericFunction
  参考：#5079
  

postgresql

• [postgresql] [usecase]
  为 CTE 构造添加了前缀支持，以支持 Postgresql 12 的“MATERIALIZED”和“NOT MATERIALIZED”短语。感谢 Marat Sharafutdinov 提供的拉取请求。
  参见
  HasCTE.cte()
  参考：#5040
  
• [postgresql] [bug]
  修复了 PostgreSQL 方言无法解析反射的 CHECK 约束的问题，该约束是布尔值函数（而不是布尔值表达式）。
  参考：#5039
  

mssql

• [mssql] [bug]
  修复了将时区感知的 datetime 值转换为字符串以用作 DATETIMEOFFSET 列的参数值时，省略了小数秒的问题。
  参考：#5045
  

测试

• [tests] [bug]
  修复了一些在 Windows 上由于 SQLite 文件锁定问题导致的测试失败，以及连接池相关测试中的一些时间问题；感谢 Federico Caselli 提供的拉取请求。
  参考：#4946
  
• [tests] [postgresql]
  通过测试检测到 PostgreSQL 数据库的两阶段事务要求的改进，测试 max_prepared_transactions 设置为大于 0 的值。感谢 Federico Caselli 提供的拉取请求。
  参考：#5057
  

杂项

• [bug] [ext]
  修复了 sqlalchemy.ext.serializer 中的错误，其中唯一的 BindParameter 对象可能会与自身冲突，如果它存在于映射本身以及查询的筛选条件中，则一侧将用于与非反序列化版本一起使用，另一侧将使用序列化版本。类似于其 “clone” 方法的逻辑被添加到 BindParameter 中，该方法将在反序列化时使参数名称唯一化，以避免与其原始名称冲突。
  参考：#5086
  

1.3.12

发布日期：2019 年 12 月 16 日

orm

• [orm] [bug]
  修复了涉及lazy="raise"策略的问题，其中 ORM 删除对象会为一个简单的“use-get”样式的多对一关系引发异常，该关系配置了 lazy=”raise”。这与 1.3 版本中作为#4353的一部分引入的更改不一致，其中已经确定了一个不期望发出 SQL 的历史操作应绕过lazy="raise"检查，并且对于这种情况实际上将其视为lazy="raise_on_sql"。修复调整了懒加载器策略，以便在懒加载指示不应在对象不存在时发出 SQL 时不引发异常。
  参考：#4997
  
• [orm] [bug]
  修复了 1.3.0 中引入的与关联代理重构相关的回归问题，该问题阻止了composite()属性在引用它们的关联代理方面的工作。
  参考：#5000
  
• [orm] [bug]
  在设置relationship()上的持久性相关标志时，同时设置  viewonly=True 将会发出常规警告，因为这些标志对于 viewonly=True  关系没有意义。特别是，“cascade”设置有自己的警告，根据各个值生成，例如“delete, delete-orphan”，这些值不应适用于  viewonly 关系。然而需要注意的是，在“cascade”情况下，这些设置仍然错误地生效，即使关系设置为“viewonly”。在 1.4  版本中，将禁止在 viewonly=True 关系上设置所有与持久性相关的级联设置，以解决此问题。
  参考：#4993
  
• [orm] [bug] [py3k]
  修复了将集合分配给自身作为切片时出现的问题，变异操作会失败，因为它首先无意中擦除了分配的集合。由于不改变内容的赋值不应生成事件，因此该操作现在是一个无操作。需要注意的是，修复仅适用于 Python 3；在 Python 2 中，在这种情况下不会调用__setitem__钩子；而是使用__setslice__，它会逐个项目地重新创建列表项。
  参考：#4990
  
• [orm] [bug]
  修复了一个问题，即如果 Core 引擎/连接级别的“begin”失败，例如由于网络错误或数据库由于某些事务配方而被锁定，Session在从连接池获取该连接并立即返回它的上下文中，ORM Session尽管该连接未存储在该Session的状态中，但不会关闭连接。这将导致连接被连接池弱引用处理程序在垃圾回收中清除，这是一个不受欢迎的代码路径，在某些特殊配置中可能会在标准错误中发出错误。
  参考：#5034
  

sql

• [sql] [bug]
  修复了将“distinct”关键字传递给select()时不会像select.distinct()一样将字符串值视为“标签引用”的错误，而是会无条件引发异常。这些关键字参数和传递给select()的其他参数最终将在 SQLAlchemy 2.0 中被弃用。
  参考：#5028
  
• [sql] [bug]
  将“无法解析标签引用”异常的文本更改为包括其他类型的标签强制转换，即“DISTINCT”也属于 PostgreSQL 方言下的此类别。
  

sqlite

• [sqlite] [bug]
  修复了解决 SQLite  将“numeric”亲和性分配给 JSON 数据类型的行为问题，首次描述在添加对 SQLite JSON 的支持中，该行为将标量数值 JSON  值返回为数字而不是可以进行 JSON 反序列化的字符串。SQLite 特定的 JSON  反序列化器现在对这种情况进行了优雅降级处理，作为异常并且对于单个数值值绕过反序列化，因为从 JSON 的角度来看，它们已经被反序列化。
  参考：#5014
  

mssql

• [mssql] [bug]
  通过在 PyODBC 中添加 PyODBC 级别的结果处理程序修复了对DATETIMEOFFSET数据类型的支持，因为它不包含对此数据类型的原生支持。这包括使用 Python 3 的“timezone” tzinfo 子类来设置时区，在 Python 2 中使用了 SQLAlchemy.util 中“timezone”的最小回退。
  参考：#4983
  

orm

• [orm] [bug]
  修复了涉及lazy="raise"策略的问题，其中对一个对象进行 ORM 删除操作会在一个简单的“使用获取”风格的多对一关系上引发异常，而该关系配置了lazy="raise"。这与在 1.3 版本中引入的更改不一致，作为#4353的一部分，已经确定不希望发出 SQL 的历史操作应绕过lazy="raise"检查，而是在这种情况下有效地将其视为lazy="raise_on_sql"。修复调整了懒加载器策略，以便在懒加载指示不应在对象不存在时发出 SQL 的情况下不引发异常。
  参考：#4997
  
• [orm] [bug]
  修复了 1.3.0 中与#4351中的关联代理重构相关的回归，该回归阻止了composite()属性在引用它们的关联代理方面的工作。
  参考：#5000
  
• [orm] [bug]
  在设置relationship()上的与持久性相关的标志的同时设置viewonly=True现在会发出常规警告，因为这些标志对于viewonly=True关系没有意义。特别是，“cascade”设置有自己的警告，根据各个值生成，例如“delete, delete-orphan”，不应适用于viewonly关系。但请注意，在“cascade”情况下，这些设置仍然错误地生效，即使关系设置为“viewonly”。在 1.4 版本中，将禁止在viewonly=True关系上设置所有与持久性相关的级联设置，以解决此问题。
  参考：#4993
  
• [orm] [bug] [py3k]
  修复了将集合分配给自身作为切片时出现的问题，由于首先无意中擦除了分配的集合，因此变异操作将失败。由于不改变内容的赋值不应生成事件，因此该操作现在是一个无操作。请注意，修复仅适用于 Python 3；在 Python 2 中，这种情况下不会调用__setitem__钩子；而是使用__setslice__，它会逐个项目地重新创建列表项。
  参考：#4990
  
• [orm] [bug]
  修复了一个问题，即如果事务的“begin”在 Core 引擎/连接级别失败，比如由于网络错误或数据库被锁定导致某些事务配方失败，在Session的上下文中从连接池获取该连接然后立即返回它，ORM Session尽管该连接未存储在该Session的状态中，但不会关闭该连接。这将导致连接被连接池中的弱引用处理程序在垃圾回收中清除，这是一个不受欢迎的代码路径，在某些特殊配置中可能会在标准错误中发出错误。
  参考：#5034
  

sql

• [sql] [bug]
  修复了将“distinct”关键字传递给select()时不会像select.distinct()那样将字符串值视为“标签引用”的错误，而是会无条件引发异常。这个关键字参数和其他传递给select()的参数最终将在 SQLAlchemy 2.0 中被弃用。
  参考：#5028
  
• [sql] [bug]
  更改了“无法解析标签引用”异常的文本，包括其他类型的标签强制转换，即“DISTINCT”也属于 PostgreSQL 方言下的这一类别。
  

sqlite

• [sqlite] [bug]
  修复了解决 SQLite  将“numeric”亲和性分配给 JSON 数据类型的行为的问题，首次描述在添加对 SQLite JSON 的支持中，它将标量数值 JSON  值作为数字返回，而不是作为可以进行 JSON 反序列化的字符串。现在，SQLite 特定的 JSON  反序列化器对于这种情况会优雅地降级为异常，并且对于单个数值值，从 JSON 的角度来看，它们已经被反序列化。
  参考：#5014
  

mssql

• [mssql] [bug]
  修复了对 PyODBC 上的DATETIMEOFFSET数据类型的支持，通过添加  PyODBC 级别的结果处理程序，因为它不包含对这种数据类型的原生支持。这包括在 Python 3 中使用“timezone” tzinfo  子类来设置时区，而在 Python 2 中则利用了 SQLAlchemy.util 中“timezone”的最小回退。
  参考：#4983
  

1.3.11

发布日期：2019 年 11 月 11 日

orm

• [orm] [usecase]
  添加了访问器 Query.is_single_entity() 到 Query，该访问器将指示此 Query 返回的结果是 ORM 实体列表，还是实体或列表达式的元组。SQLAlchemy 希望在未来的版本中改进单个实体/元组的行为，以便行为在前期就是明确的，但此属性应有助于当前行为。感谢 Patrick Hayes 提供的拉取请求。
  引用：#4934
  
• [orm] [bug]
  relationship.omit_join 标志并非意在手动设置为 True，当发生此情况时将会发出警告。omit_join 优化会被自动检测到，omit_join 标志仅用于在假设优化可能干扰正确结果的情况下禁用优化，但在现代版本的此功能中尚未观察到这种情况。当未自动检测到该标志时将其设置为 True 可能导致在使用非默认主连接条件时 selectin 加载功能无法正常工作。
  引用：#4954
  
• [orm] [bug]
  如果将主键值传递给 Query.get()，并且所有主键列位置都为 None，则会发出警告。以前，传递单个 None 会在元组之外引发 TypeError，传递复合 None（包含 None 值的元组）会静默通过。现在的修复将单个 None 强制转换为元组，以便与其他 None 条件一致处理。感谢 Lev Izraelit 对此的帮助。
  引用：#4915
  
• [orm] [bug]
  BakedQuery 不会缓存通过 QueryEvents.before_compile() 事件修改的查询，因此可能对查询应用临时修改的编译钩子将在每次运行时生效。特别是对于修改在惰性加载和急切加载中使用的查询的事件非常有帮助，比如“select in” 加载。为了重新启用通过此事件修改的查询的缓存，添加了一个新标志 bake_ok；请参阅使用 before_compile 事件了解详情。
  提供一种新形式的 SQL 缓存的长期计划应更全��地解决这种问题。
  参考：#4947
  
• [orm] [bug]
  修复了 ORM 中的一个 bug，其中一个“secondary”表引用了一个可选择的表，该表在某种程度上会引用本地主表，当通过关系相关的连接生成关系相关的连接时，无论是通过Query.join()还是通过joinedload()，都会将连接条件的两侧都应用别名。现在“local”一侧被排除在外。
  参考：#4974
  

engine

• [engine] [bug]
  修复了一个  bug，其中在日志记录和错误报告中使用的参数 repr  需要额外的上下文以区分单个语句的参数列表和参数列表的列表，因为“列表的列表”结构也可能表示第一个参数本身是一个列表，比如对于数组参数。引擎/连接现在传入一个额外的布尔值，指示参数应如何考虑。唯一期望数组作为参数的  SQLAlchemy 后端是使用 pyformat 参数的  psycopg2，因此这个问题并不太明显，但随着其他使用位置参数的驱动程序获得更多功能，支持这一点变得重要。它还消除了参数 repr  函数根据传递的参数结构猜测的需要。
  参考：#4902
  
• [engine] [bug] [postgresql]
  修复了Inspector中的  bug，其中缓存键生成没有考虑以元组形式传递的参数，比如要返回给 PostgreSQL  方言的视图名称样式元组。这会导致检查器对更具体的一组条件进行了过于普遍的缓存。逻辑已经调整，以包含缓存中的每个关键字元素，因为每个参数都应适用于缓存，否则方言应该绕过缓存装饰器。
  参考：#4955
  

sql

• [sql] [usecase]
  为JSON类型的表达式添加了新的访问器，以允许特定数据类型的访问和比较，包括字符串、整数、数字、布尔元素。这修改了将值转换为字符串进行比较的文档化方法，而是在  PostgreSQL、SQlite、MySQL 方言中添加了特定功能，以可靠地在所有情况下提供这些基本类型。
  另请参阅
  JSON
Comparator.as_string()
Comparator.as_boolean()
Comparator.as_float()
Comparator.as_integer()
  参考：#4276
  
• [sql] [usecase]
  text() 构造现在支持“unique”绑定参数，这将在编译时动态地使自己唯一，从而允许多个具有相同绑定参数名称的text()构造组合在一起。
  参考：#4933
  
• [sql] [bug] [py3k]
  更改了quoted_name构造的repr()，在 Python 3 下使用常规字符串 repr()，而不是通过“backslashreplace”转义，这可能会产生误导。
  参考：#4931
  

模式

• [schema] [usecase]
  增加了对“计算列”DDL  的支持；这些是 DDL 列规范，用于具有服务器计算值的列，无论是在 SELECT 时（称为“虚拟”）还是在它们被 INSERT 或 UPDATE  时（称为“存储”）。支持已建立在 Postgresql、MySQL、Oracle SQL Server 和 Firebird 上。感谢  Federico Caselli 在这方面的大量工作。
  另请参阅
  计算列（GENERATED ALWAYS AS）
  参考：#4894
  
• [schema] [bug]
  修复了一个 bug，即一个表的列标签与普通列名重叠，例如“foo.id AS foo_id”与“foo.foo_id”，将在检测到此重叠之前生成._label属性，因为在列上使用index=True或unique=True标志与默认命名约定"column_0_label"一起。然后，当稍后使用._label生成绑定参数名称时，特别是 ORM 在为 UPDATE 语句生成 WHERE 子句时使用的那些参数时，将导致失败。通过使用一个不影响Column状态的 DDL 生成的替代._label访问器来修复此问题。该访问器还绕过了关键去重步骤，因为对于 DDL 是不必要的，命名现在在 DDL 中一致地是"_"，在 DDL 中使用时没有任何后续的数字符号。
  参考：#4911
  

mysql

• [mysql] [bug]
  添加了从基本 pymysql.Error 类解释的“连接被终止”消息，以便检测关闭的连接，根据报告，此消息通过一个指示 pymysql 未正确处理的 pymysql.InternalError()对象到达。
  参考：#4945
  

mssql

• [mssql] [bug]
  修复了 MSSQL 方言中的问题，其中 SELECT 中的基于表达式的 OFFSET 值将被拒绝，尽管方言可以在 ROW NUMBER 定向的 LIMIT/OFFSET 结构内呈现此表达式。
  参考：#4973
  
• [mssql] [bug]
  修复了Engine.table_names()方法中的问题，该方法会将方言的默认模式名称反馈到方言级别的表函数中，在 SQL Server 的情况下，它会将其解释为由 mssql 方言查看的点令牌化模式名称，这将导致在数据库用户名实际上包含点的情况下该方法失败。在 1.3 中，此方法仍然被MetaData.reflect()函数使用，因此是一个重要的代码路径。在 1.4 中，这是当前主开发分支，这个问题不存在，因为MetaData.reflect()既不使用这个方法，也不显式传递默认模式名称。尽管如此，修复仍然通过将其包装在 quoted_name()中防止方言返回的默认服务器名称值在任何情况下被解释为点令牌化名称。
  参考：#4923
  

oracle

• [oracle] [usecase]
  在 cx_Oracle 方言中添加了方言级别的标志 encoding_errors，可以作为 create_engine() 的一部分指定。在 Python 2 下，将其传递给 SQLAlchemy 的 Unicode 解码转换器，在 Python 3 下，将其传递给 cx_Oracle 的 cursor.var() 对象作为 encodingErrors 参数，以处理目标数据库中存在破损编码的非常罕见情况，除非放宽错误处理，否则无法获取。该值最终是传递给 decode() 的 Python “编码错误”参数之一。
  参考：#4799
  
• [oracle] [bug] [firebird]
  修改了 Oracle 和 Firebird 方言的 “名称规范化” 方法，将这些方言的大写作为不区分大小写的约定转换为 SQLAlchemy 中的小写作为不区分大小写的约定，以不自动将符合大写或小写转换的名称应用于 quoted_name 构造，正如许多非欧洲字符所示。在元数据结构中使用的所有名称都转换为 quoted_name 对象；此处的更改只会影响一些检查函数的输出。
  参考：#4931
  
• [oracle] [bug]
  当在绑定参数中使用时，NCHAR 数据类型现在将绑定到 cx_Oracle.FIXED_NCHAR 的 DBAPI 数据绑定，这为变长字符串提供了正确的比较行为。以前，NCHAR 数据类型将绑定到非固定长度的 cx_oracle.NCHAR，而 CHAR 数据类型已经绑定到 cx_Oracle.FIXED_CHAR，因此现在一致性是 NCHAR 绑定到 cx_Oracle.FIXED_NCHAR。
  参考：#4913
  

测试

• [tests] [bug]
  修复了在新版本 SQLite（3.30 或更高版本）中会出现的测试失败，因为它们增加了空值排序语法以及对聚合函数的新限制。感谢 Nils Philippsen 的拉取请求。
  参考：#4920
  

杂项

• [bug] [installation] [windows]
  添加了一个解决方案，用于解决在 Windows 安装中观察到的 setuptools 相关失败，其中 setuptools 在未正确安装 MSVC 构建依赖项时未正确报告构建错误，因此不允许优雅地降级为非 C 扩展构建。
  参考：#4967
  
• [bug] [firebird]
  向 Firebird 断开连接检测添加了额外的“断开连接”消息“写入数据到连接时出错”。感谢 lukens 提供的拉取请求。
  参考：#4903
  

orm

• [orm] [usecase]
  在Query中添加了访问器Query.is_single_entity()，该访问器将指示此Query返回的结果是 ORM 实体列表还是实体或列表达式的元组。SQLAlchemy 希望在未来的版本中改进单个实体/元组的行为，以便行为在一开始就是明确的，但是这个属性应该有助于当前的行为。感谢 Patrick Hayes 提供的拉取请求。
  参考：#4934
  
• [orm] [bug]
  relationship.omit_join标志并不打算手动设置为 True，当发生这种情况时将会发出警告。omit_join优化会被自动检测到，omit_join标志只打算在假设优化可能干扰正确结果的情况下禁用优化，但在这个特性的现代版本中并没有观察到这种情况。当非默认主要连接条件在使用时，将omit_join标志设置为 True 可能会导致 selectin 加载特性无法正确工作。
  参考：#4954
  
• [orm] [bug]
  如果向Query.get()传递的主键值在所有主键列位置上都是 None，则会发出警告。以前，传递单个 None 会引发TypeError，传递复合 None（None 值的元组）会静默通过。现在的修复方法是将单个 None 强制转换为元组，以便与其他 None 条件一致处理。感谢 Lev Izraelit 的帮助。
  参考：#4915
  
• [orm] [bug]
  BakedQuery不会缓存通过QueryEvents.before_compile()事件修改的查询，因此可能会对查询应用临时修改的编译钩子将在每次运行时生效。特别是对于修改用于延迟加载和急加载的查询的事件非常有帮助，比如“select in”加载。为了重新启用通过此事件修改的查询的缓存，添加了一个新标志bake_ok；详细信息请参见使用 before_compile 事件。
  提供一种新形式的 SQL 缓存的长期计划应该更全面地解决这种问题。
  参考：#4947
  
• [orm] [bug]
  修复了一个 ORM bug，其中引用了一个与本地主表在某种方式上引用的可选择的“secondary”表，在生成关系相关的连接条件时，无论是通过Query.join()还是通过joinedload()，都会对连接条件的两侧应用别名。现在排除了“本地”一侧。
  参考：#4974
  

engine

• [engine] [bug]
  修复了一个  bug，在日志记录和错误报告中使用的参数 repr  需要额外的上下文来区分单个语句的参数列表和参数列表的列表，因为“列表的列表”结构也可能表示第一个参数本身是一个列表的单个参数列表，比如数组参数。引擎/连接现在传入一个额外的布尔值，指示参数应如何考虑。唯一期望数组作为参数的  SQLAlchemy 后端是使用 pyformat 参数的  psycopg2，因此这个问题并不太明显，但随着其他使用位置的驱动程序获得更多功能，支持这一点很重要。它还消除了参数 repr  函数根据传递的参数结构猜测的需要。
  参考：#4902
  
• [engine] [bug] [postgresql]
  修复了Inspector中的错误，其中缓存键生成未考虑以元组形式传递的参数，例如要为 PostgreSQL 方言返回的视图名称样式元组。这将导致检查器对更具体的条件进行缓存过于普遍。逻辑已调整为在缓存中包含每个关键字元素，因为每个参数都应适用于缓存，否则应通过方言绕过缓存装饰器。
  参考：#4955
  

sql

• [sql] [用例]
  为JSON类型的表达式添加了新的访问器，以允许特定数据类型的访问和比较，包括字符串、整数、数字、布尔元素。这修改了将值转换为字符串进行比较的文档方法，而是在 PostgreSQL、SQlite、MySQL 方言中添加了特定功能，以可靠地在所有情况下提供这些基本类型。
  参见
  JSON
Comparator.as_string()
Comparator.as_boolean()
Comparator.as_float()
Comparator.as_integer()
  参考：#4276
  
• [sql] [用例]
  text()构造现在支持“unique”绑定参数，这将在编译时动态使它们唯一，从而允许多个具有相同绑定参数名称的text()构造组合在一起。
  参考：#4933
  
• [sql] [bug] [py3k]
  更改了quoted_name构造的repr()，在 Python 3 下使用常规字符串repr()，而不是通过“backslashreplace”转义，这可能会产生误导。
  参考：#4931
  

模式

• [模式] [用例]
  为“计算列”添加了 DDL  支持；这些是用于具有服务器计算值的列的 DDL 列规范，无论是在 SELECT 时（称为“虚拟”）还是在它们被 INSERT 或 UPDATE  时（称为“存储”）。已为 Postgresql、MySQL、Oracle SQL Server 和 Firebird 建立了支持。感谢  Federico Caselli 在这方面的大量工作。
  另请参阅
  计算列（GENERATED ALWAYS AS）
  参考：#4894
  
• [schema] [bug]
  修复了一个 bug，即表中的列标签与普通列名重叠，例如“foo.id AS foo_id”与“foo.foo_id”，将在能够检测到此重叠之前为列生成._label属性，因为在列上使用index=True或unique=True标志与默认命名约定"column_0_label"相结合。然后，当稍后使用._label生成绑定参数名称时，特别是在 ORM 生成 UPDATE 语句的 WHERE 子句时使用的那些参数时，将导致失败。通过使用一个不影响Column状态的 DDL 生成的替代._label访问器来修复此问题。该访问器还绕过了键去重步骤，因为对于 DDL 是不必要的，当在 DDL 中使用时，命名现在始终是"_"，没有任何后续的数字符号。
  参考：#4911
  

mysql

• [mysql] [bug]
  添加了从基本 pymysql.Error 类解释的“连接已关闭”消息，以便检测到关闭的连接，根据报告，此消息通过一个指示 pymysql 未正确处理的 pymysql.InternalError()对象到达。
  参考：#4945
  

mssql

• [mssql] [bug]
  修复了 MSSQL 方言中的问题，在 SELECT 中基于表达式的 OFFSET 值将被拒绝，即使方言可以在 ROW NUMBER 定向的 LIMIT/OFFSET 结构内呈现此表达式。
  参考：#4973
  
• [mssql] [bug]
  修复了 Engine.table_names() 方法中的问题，该方法会将方言的默认模式名称反馈给方言级别的表函数，在 SQL Server 的情况下，它会将其解释为 mssql 方言视图中的点标记模式名称，这将导致在数据库用户名实际上包含点的情况下该方法失败。在 1.3 版本中，此方法仍然被 MetaData.reflect() 函数使用，因此是一个重要的代码路径。在当前主开发分支 1.4 中，这个问题不存在，因为 MetaData.reflect() 没有使用这个方法，也不会显式传递默认模式名称。尽管如此，修复仍然防止方言返回的默认服务器名称值在任何情况下被解释为点标记名称，通过将其包装在 quoted_name() 中。
  参考：#4923
  

oracle

• [oracle] [usecase]
  在 cx_Oracle 方言中添加了方言级别标志 encoding_errors，可以作为 create_engine() 的一部分指定。在 Python 2 下，这将传递给 SQLAlchemy 的 unicode 解码转换器，而在 Python 3 下，这将传递给 cx_Oracle 的 cursor.var() 对象作为 encodingErrors 参数，用于处理目标数据库中存在破损编码的非常罕见情况，除非放宽错误处理，否则无法获取。该值最终是传递给 decode() 的 Python “编码错误” 参数之一。
  参考：#4799
  
• [oracle] [bug] [firebird]
  修改了 Oracle 和 Firebird 方言的“名称规范化”方法，将这些方言的大写作为不区分大小写的约定转换为 SQLAlchemy 的小写作为不区分大小写的约定，以避免自动将 quoted_name 构造应用于在大写或小写转换下匹配自身的名称，就像许多非欧洲字符一样。在元数据结构中使用的所有名称都会在任何情况下转换为 quoted_name 对象；这里的更改只会影响一些检查函数的输出。
  参考：#4931
  
• [oracle] [bug]
  当在绑定参数中使用时，NCHAR数据类型现在将绑定到cx_Oracle.FIXED_NCHAR DBAPI 数据绑定，从而提供与可变长度字符串的正确比较行为。以前，NCHAR数据类型会绑定到cx_oracle.NCHAR，这不是固定长度；CHAR数据类型已经绑定到cx_Oracle.FIXED_CHAR，因此现在一致的是NCHAR绑定到cx_Oracle.FIXED_NCHAR。
  参考：#4913
  

测试

• [tests] [bug]
  修复了在新的 SQLite 版本（3.30 或更高版本）中会发生的测试失败，这是由于它们添加了空值排序语法以及对聚合函数的新限制。感谢 Nils Philippsen 的拉取请求。
  参考：#4920
  

杂项

• [bug] [installation] [windows]
  添加了一个解决方案，用于解决在 Windows 安装中观察到的与 setuptools 相关的故障，其中 setuptools 在未安装 MSVC 构建依赖项时未正确报告构建错误，因此不允许优雅地降级为非 C 扩展构建。
  参考：#4967
  
• [bug] [firebird]
  添加了额外的“disconnect”消息“Error writing data to the connection”以用于 Firebird 断开检测。感谢 lukens 的拉取请求。
  参考：#4903
  

1.3.10

发布日期：2019 年 10 月 9 日

mssql

• [mssql] [bug]
  修复了 SQL Server 方言中的一个 bug，该 bug 涉及新的“max_identifier_length”功能，其中 mssql 方言已经具有此标志，但实现未正确适应新的初始化挂钩。
  参考：#4857
  

oracle

• [oracle] [bug]
  修复了 Oracle  方言中的一个回归问题，该问题在 Oracle 服务器 12.2 及更高版本上无意中使用了 128 个字符的最大标识符长度，尽管 1.3  系列的其余部分的规定是此值保持在 30，直到 SQLAlchemy 1.4  版本。还修复了关于“compatibility”版本检索的问题，并删除了当“v$parameter”视图不可访问时发出的警告，因为这导致用户困惑。
  参考：#4857，#4898
  

mssql

• [mssql] [bug]
  修复了 SQL Server 方言中的一个 bug，该 bug 涉及新的“max_identifier_length”功能，其中 mssql 方言已经具有此标志，但实现未正确适应新的初始化挂钩。
  参考：#4857
  

oracle

• [oracle] [bug]
  修复了 Oracle  方言中的回归问题，该问题在 Oracle 服务器 12.2 及更高版本中无意中使用了 128 个字符的最大标识符长度，尽管 1.3  系列的其余部分的规定是该值保持在 30，直到 SQLAlchemy 1.4  版本。还修复了检索“兼容性”版本的问题，并删除了当“v$parameter”视图不可访问时发出的警告，因为这导致用户混淆。
  参考：#4857, #4898
  

1.3.9

发布日期：2019 年 10 月 4 日

orm

• [orm] [bug]
  修复了由#4775引起的 selectinload 加载策略中的回归问题（在版本 1.3.6 中发布），其中 None 的多对一属性将不再由加载器填充。虽然这通常不会被注意到，因为懒加载器在获取时会填充 None，但如果对象被分离，这将导致分离实例错误。
  参考：#4872
  
• [orm] [bug]
  将纯字符串表达式传递给Session.query()已被弃用，因为所有字符串强制转换在#4481中已被移除，而这个应该已经包含在内。可以使用literal_column()函数生成文本列表达式。
  参考：#4873
  
• [orm] [bug]
  在Session可能会在SessionEvents.after_flush()钩子中发生的加载操作中，隐式地将一个对象与具有相同主键的另一个对象交换出标识映射，从而分离旧对象，这可能是一个观察到的结果。警告旨在通知用户，某些特殊条件导致此情况发生，并且先前的对象可能不处于预期状态。
  参考：#4890
  

引擎

• [engine] [usecase]
  添加了新的 create_engine() 参数 create_engine.max_identifier_length。这将覆盖方言编码的“最大标识符长度”，以适应最近更改了此长度的数据库，而 SQLAlchemy 方言尚未调整以检测该版本。该参数与现有的 create_engine.label_length 参数交互，它建立了匿名生成标签的最大（和默认）值。此外，已将最大标识符长度的后连接检测添加到方言系统中。此功能首先由 Oracle 方言使用。
  请参见
  最大标识符长度 - Oracle 方言文档中
  参考：#4857
  

sql

• [sql] [用例]
  当传递给 Table 的对象不是 SchemaItem 对象时，为此情况添加了显式错误消息，而不是解析为属性错误。
  参考：#4847
  
• [sql] [错误]
  对于使用匿名化名称的 bindparam()，这些字符会在早期被剥离，匿名化名称通常是从一个使用这些字符的命名列自动生成的，它不使用 .key，这样它们既不会干扰  SQLAlchemy  编译器对字符串格式化的使用，也不会干扰参数的驱动级解析，这两者在修复之前都可能被演示出来。该更改仅适用于内部生成和消耗的匿名化参数名称，并不适用于终端用户定义的名称，因此该更改不应影响任何现有代码。特别适用于不以引号引用特殊参数名称的  psycopg2 驱动程序，但也会剥离前导下划线以适应  Oracle（但尚未剥离前导数字，因为一些匿名参数当前完全基于数字/下划线）；在任何情况下，Oracle 继续引用包含特殊字符的参数名称。
  参考：#4837
  

sqlite

• [sqlite] [用例]
  添加了对 sqlite “URI” 连接的支持，允许在查询字符串中传递 sqlite 特定标志，例如对于支持此功能的 Python sqlite3 驱动程序，“只读”。
  另请参阅
  URI 连接
  参考：#4863
  

mssql

• [mssql] [bug]
  将标识符引用添加到了模式名称上，在反映时使用了 “use” 语句，当使用 Table 中使用了 SQL Server 的多部分模式名称时，以及对 Inspector 方法（如 Inspector.get_table_names()）；这适用于数据库名称中的特殊字符或空格。此外，如果当前数据库与传递的目标所有者数据库名称匹配，则不会发出 “use” 语句。
  参考：#4883
  

oracle

• [oracle] [用例]
  Oracle 方言现在在使用 Oracle 版本 12.2 或更高版本时会发出警告，且未设置 create_engine.max_identifier_length 参数。在这种特定情况下，默认版本为 Oracle 服务器配置中设置的“兼容性”版本，而不是实际服务器版本。在版本 1.4 中，对于 12.2  或更高版本，默认的 max_identifier_length 将移动到 128 个字符。为了保持向前兼容性，应用程序应将 create_engine.max_identifier_length 设置为 30 以保持相同的长度行为，或者设置为 128 以测试即将到来的行为。此长度决定了诸如 CREATE CONSTRAINT 和 DROP CONSTRAINT 之类的语句中生成的约束名称的截断方式，这意味着新长度可能会导致与使用旧长度生成的名称不匹配，影响数据库迁移。
  另请参阅
  最大标识符长度 - 在 Oracle 方言文档中
  参考：#4857
  
• [oracle] [bug]
  当使用 SQLAlchemy 的Date、DateTime或Time数据类型时，恢复了将 cx_Oracle.DATETIME 添加到 setinputsizes()调用中的操作，因为一些复杂查询需要它存在。这在 1.2 系列中由于任意原因被移除。
  参考：#4886
  

tests

• [tests] [bug]
  修复了在 1.3.8 版本中发布的单元测试回归，该回归会导致 Oracle、SQL Server 和其他非本地 ENUM 平台失败，因为作为#4285枚举可排序性的一部分添加了新的枚举测试；创建的枚举会在名称上重复约束。
  参考：#4285
  

orm

• [orm] [bug]
  修复了由#4775（在 1.3.6 版本中发布）引起的 selectinload 加载策略中的回归，其中 None 的多对一属性将不再被加载器填充。虽然这通常不会被注意到，因为懒加载器在获取时会填充 None，但如果对象被分离，它将导致一个分离的实例错误。
  参考：#4872
  
• [orm] [bug]
  将纯字符串表达式传递给Session.query()已被弃用，因为所有字符串强制转换在#4481中被移除，而这个应该被包含在内。可以使用literal_column()函数生成文本列表达式。
  参考：#4873
  
• [orm] [bug]
  当Session可能会在SessionEvents.after_flush()钩子中发生的加载操作中，隐式地将一个对象与另一个具有相同主键的对象交换出标识映射，从而分离旧对象时，会发出警告。该警告旨在通知用户某些特殊条件导致此情况发生，并且先前的对象可能不处于预期状态。
  参考：#4890
  

engine

• [engine] [usecase]
  添加了新的create_engine()参数create_engine.max_identifier_length。这将覆盖方言编码的“最大标识符长度”，以适应最近更改了此长度但 SQLAlchemy 方言尚未调整以检测该版本的数据库。此参数与现有的create_engine.label_length参数交互，它建立了匿名生成标签的最大（和默认）值。此外，方言系统中已添加了关于最大标识符长度的连接后检测。此功能首次由 Oracle 方言使用。
  另请参阅
  最大标识符长度 - 在 Oracle 方言文档中
  参考：#4857
  

sql

• [sql] [用例]
  添加了一个明确的错误消息，用于处理传递给Table的对象不是SchemaItem对象的情况，而不是解析为属性错误。
  参考：#4847
  
• [sql] [错误]
  在绑定参数中干扰“pyformat”或“named”格式的字符，即%， (, )和空格字符，以及一些其他通常不希望的字符，会在使用匿名化名称的bindparam()时提前剥离，这通常是从一个包含这些字符的命名列自动生成的，该列本身不包含.key，以便它们既不干扰  SQLAlchemy  编译器对字符串格式化的使用，也不干扰参数的驱动程序级解析，这两者在修复之前可能会被演示。此更改仅适用于内部生成和使用的匿名化参数名称，而不适用于最终用户定义的名称，因此该更改不应对任何现有代码产生影响。特别适用于不引用特殊参数名称的  psycopg2 驱动程序，但也会剥离前导下划线以适应  Oracle（但尚未剥离前导数字，因为某些匿名参数当前完全基于数字/下划线）；无论如何，Oracle 继续引用包含特殊字符的参数名称。
  参考：#4837
  

sqlite

• [sqlite] [用例]
  增加了对 sqlite “URI” 连接的支持，允许在查询字符串中传递特定于 sqlite 的标志，例如对于支持此功能的 Python sqlite3 驱动程序，“只读”。
  另请参阅
  URI 连接
  参考：#4863
  

mssql

• [mssql] [错误]
  在被反射的 Table 中使用 SQL Server 多部分模式名称时，将标识符引用添加到“use”语句中，以及用于 Inspector 方法，例如 Inspector.get_table_names()；这样可以容纳数据库名称中的特殊字符或空格。此外，如果当前数据库与传递的目标所有者数据库名称匹配，则不会发出“use”语句。
  参考：#4883
  

oracle

• [oracle] [用例]
  Oracle 方言现在在使用 Oracle 版本 12.2 或更高版本时会发出警告，并且未设置 create_engine.max_identifier_length 参数。在这种特定情况下，默认版本为 Oracle 服务器配置中设置的“兼容性”版本，而不是实际服务器版本。在版本 1.4 中，12.2  或更高版本的默认 max_identifier_length 将移至 128 个字符。为了保持向前兼容性，应用程序应将 create_engine.max_identifier_length 设置为 30，以保持相同的长度行为，或者设置为 128 以测试即将到来的行为。此长度决定了生成的约束名称在诸如 CREATE CONSTRAINT 和 DROP CONSTRAINT 等语句中被截断的方式，这意味着新长度可能会导致与使用旧长度生成的名称不匹配，影响数据库迁移。
  另请参阅
  最大标识符长度 - 在 Oracle 方言文档中
  参考：#4857
  
• [oracle] [错误]
  恢复了在使用 SQLAlchemy 的Date、DateTime或Time数据类型时将 cx_Oracle.DATETIME 添加到 setinputsizes()调用中的功能，因为一些复杂查询需要这个功能。这在 1.2 系列中由于任意原因被移除。
  参考：#4886
  

测试

• [测试] [bug]
  修复了 1.3.8 版本中发布的单元测试回归，该回归会导致 Oracle、SQL Server 和其他非本地 ENUM 平台失败，因为作为#4285枚举可排序性的一部分添加了新的枚举测试；这些枚举创建了重复的名称约束。
  参考：#4285
  

1.3.8

发布日期：2019 年 8 月 27 日

ORM

• [ORM] [用例]
  增加了对使用 Python pep-435 枚举对象作为 ORM 映射的主键列值的Enum数据类型的支持。由于这些值本身并不可排序，而 ORM 对主键要求可排序，因此在类型系统中添加了一个新的TypeEngine.sort_key_function属性，允许任何 SQL 类型实现其类型的 Python 对象排序，这将被工作单元所使用。Enum类型通过使用给定枚举的数据库值来定义这一点。排序方案也可以通过将可调用对象传递给Enum.sort_key_function参数来重新定义。感谢 Nicolas Caniart 的拉取请求。
  参考：#4285
  
• [ORM] [bug]
  修复了一个 bug，Load对象由于内部上下文字典中的映射器/关系状态而无法被 pickle 化。现在，这些对象已经通过与加载器选项系统中其他元素类似的技术转换为可 pickle 化。
  参考：#4823
  

引擎

• [引擎] [特性]
  添加了新参数create_engine.hide_parameters，当设置为 True 时，将导致不再记录 SQL 参数，也不会在StatementError对象的字符串表示中呈现。
  参考：#4815
  
• [engine] [bug]
  修复了一个问题，即如果在首次连接时发生的“初始化”过程遇到意外异常，初始化过程将无法完成，然后在后续连接尝试中不再尝试，导致方言处于未初始化或部分初始化状态，在需要根据对现有连接的检查来建立参数的范围内。事件系统中的“仅调用一次”逻辑已经重新设计，以适应这种情况，使用新的私有  API 功能建立了一个“仅执行一次”钩子，将继续允许初始化程序在后续连接中触发，直到完成而不引发异常。这不会影响事件系统中现有once=True标志的行为。
  参考：#4807
  

postgresql

• [postgresql] [usecase]
  增加了对包含特殊 PostgreSQL 修饰符“NOT VALID”的 CHECK 约束的反射支持，该修饰符可能存在于已添加到现有表中的 CHECK 约束中，指示它们不应用于表中的现有数据。由Inspector.get_check_constraints()返回的 CHECK 约束的 PostgreSQL 字典可能包含一个额外的条目dialect_options，其中将包含一个条目"not_valid": True，如果检测到此符号。拉取请求由 Bill Finn 提供。
  参考：#4824
  
• [postgresql] [bug]
  修订了刚刚添加的对 psycopg2“execute_values()”功能的支持的方法，该功能在 1.3.7 中添加了对#4623的支持。该方法依赖于一个正则表达式，该正则表达式无法匹配更复杂的 INSERT 语句，例如涉及子查询的语句。新方法完全匹配作为 VALUES 子句呈现的字符串。
  参考：#4623
  
• [postgresql] [bug]
  修复了一个错误，即 Postgresql 运算符（例如Comparator.contains()和Comparator.contained_by()）在针对array对象使用非整数值时无法正确运行，这是由于错误的断言语句。
  参考：#4822
  

sqlite

• [sqlite] [bug] [reflection]
  修复了一个  bug，其中一个外键被设置为仅通过表名而不是列名引用父表时，由于 SQLite 的 PRAGMA  没有报告这些列（如果它们没有被明确给出），因此“引用列”不会正确反映。由于某种原因，这是硬编码为假定本地列的名称，这对某些情况可能有效，但是不正确。新方法反映了被引用表的主键，并将约束列列表用作被引用列列表，如果远程列在反映的  PRAGMA 中不存在。
  参考：#4810
  

orm

• [orm] [usecase]
  增加了对使用 Python pep-435 枚举对象作为 ORM 映射的主键列值的Enum数据类型的支持。由于这些值本身不可排序，这是 ORM 对主键所需的，因此在类型系统中添加了一个新的TypeEngine.sort_key_function属性，允许任何 SQL 类型实现其类型的 Python 对象的排序，该排序由工作单元查询。然后，Enum类型使用给定枚举的数据库值定义这一点。通过将可调用对象传递给Enum.sort_key_function参数，还可以重新定义排序方案。感谢 Nicolas Caniart 的拉取请求。
  参考：#4285
  
• [orm] [bug]
  修复了一个 bug，其中Load对象由于内部上下文字典中的映射器/关系状态而无法被 pickle 化。现在，这些对象通过类似于加载器选项系统中其他元素长期以来可序列化的技术进行转换为可 pickle 化。
  参考：#4823
  

engine

• [engine] [feature]
  增加了新参数create_engine.hide_parameters，当设置为 True 时，将导致不再记录 SQL 参数，也不会在StatementError对象的字符串表示中呈现。
  参考：#4815
  
• [engine] [bug]
  修复了一个问题，即如果在首次连接时发生“初始化”过程的方言遇到意外异常，初始化过程将无法完成，然后在后续连接尝试中不再尝试，导致方言处于未初始化或部分初始化状态，在需要根据实时连接检查来建立参数的范围内。事件系统中的“仅调用一次”逻辑已经重新设计，以适应这种情况，使用新的私有  API 功能建立了一个“仅执行一次”钩子，将继续允许初始化程序在后续连接中触发，直到完成而不引发异常。这不会影响事件系统中现有的once=True标志的行为。
  参考：#4807
  

postgresql

• [postgresql] [usecase]
  增加了对包含特殊的 PostgreSQL 限定词“NOT VALID”的 CHECK 约束的反射支持，该限定词可能存在于已向现有表添加的 CHECK 约束中，指示不将其应用于表中现有数据。由Inspector.get_check_constraints()返回的 CHECK 约束的 PostgreSQL 字典可能包含一个额外的条目dialect_options，其中将包含一个条目"not_valid": True，如果检测到此符号。拉取请求由 Bill Finn 提供。
  参考：#4824
  
• [postgresql] [bug]
  修订了对于在 1.3.7 中添加的对 psycopg2“execute_values()”功能的支持的方法，该功能添加在#4623中。该方法依赖于一个正则表达式，该正则表达式无法匹配更复杂的 INSERT 语句，例如涉及子查询的语句。新方法完全匹配作为 VALUES 子句呈现的字符串。
  参考：#4623
  
• [postgresql] [bug]
  修复了一个错误，即 Postgresql 运算符（例如Comparator.contains()和Comparator.contained_by()）在针对array对象使用时，对非整数值的功能无法正确运行，这是由于错误的断言语句。
  参考：#4822
  

sqlite

• [sqlite] [bug] [reflection]
  修复了一个  bug，即设置为仅通过表名而不是列名引用父表的 FOREIGN KEY 不会正确地反映为设置“referred  columns”，因为如果没有显式给出，SQLite 的 PRAGMA  不会报告这些列。出于某种原因，这被硬编码为假设本地列的名称，这对某些情况可能有效，但不正确。新方法反映了被引用表的主键，并使用约束列列表作为被引用列列表，如果远程列不直接在反映的  PRAGMA 中存在。
  参考：#4810
  

1.3.7

发布日期：2019 年 8 月 14 日

orm

• [orm] [bug]
  修复了由新的 many-to-one 逻辑的 selectinload 引起的回归，其中一个基于非真实外键的 primaryjoin 条件会导致如果父对象上给定键值的相关对象不存在，则会引发 KeyError。
  参考：#4777
  
• [orm] [bug]
  修复了一个 bug，即在与应用了基于表达式的“offset”的查询一起使用Query.first()或切片表达式时，会引发 TypeError，因为“offset”的“or”条件不希望它是 SQL 表达式而不是整数或 None。
  参考：#4803
  

sql

• [sql] [bug]
  修复了一个问题，即包含一些无法解析为特定列的函数表达式的Index对象，与基于字符串的列名混合，将无法正确初始化其内部状态，导致 DDL 编译期间失败。
  参考：#4778
  
• [sql] [bug]
  修复了一个 bug，即TypeEngine.column_expression()方法在 UNION 或其他_selectable.CompoundSelect内的后续 SELECT 语句中不会被应用，尽管 SELECT 语句在语句的最顶层被渲染。新逻辑现在区分了渲染列表达式（对于列表中的所有 SELECT 都需要）与收集结果行的返回数据类型，后者仅对第一个 SELECT 需要。
  参考：#4787
  
• [sql] [bug]
  修复了内部克隆 SELECT 结构可能导致键错误的问题，如果 SELECT 的副本更改其状态，使其列列表发生变化。这在一些 ORM 场景中观察到，可能是 1.3 及以上版本独有的问题，因此部分是一个回归修复。
  参考：#4780
  

postgresql

• [postgresql] [usecase]
  为 psycopg2 方言添加了新的方言标志 executemany_mode，它取代了之前的实验性 use_batch_mode 标志。executemany_mode 支持 psycopg2 提供的“execute batch”和“execute values”函数，后者用于编译的 insert() 构造。感谢 Yuval Dinari 的拉取请求。
  另请参阅
  Psycopg2 快速执行助手
  参考：#4623
  

mysql

• [mysql] [usecase]
  将 ARRAY 和 MEMBER 添加到 MySQL 保留字列表中，因为 MySQL 8.0 现在将它们视为保留字。
  参考：#4783
  
• [mysql] [bug]
  当  MySQL 方言给出字符集时，MySQL 方言将在连接开始时发出“SET NAMES”以满足 MySQL 8.0 中观察到的一个明显行为，当  UNION 包含字符串列与形式为 CAST(NULL AS CHAR(…)) 的列联合时会引发一个排序错误，这是 SQLAlchemy 的  polymorphic_union 函数所做的。这个问题似乎至少影响了 PyMySQL 一年，然而最近在基于 mysqlclient 1.4.4  的更改中出现。由于这个指令的存在影响了三个不同的 MySQL 字符集设置，每个设置根据其存在的情况有复杂的影响，因此 SQLAlchemy  现在会在新连接上发出该指令以确保正确的行为。
  参考：#4804
  
• [mysql] [bug]
  为上游 MySQL 8 问题添加了另一个修复，其中一个区分大小写的表名在外键约束反射中被错误报告，这是对首次为 #4344 添加的修复的扩展，影响一个区分大小写的列名。新问题发生在 MySQL 8.0.17 中，因此 88718 修复的一般逻辑仍然有效。
  另请参阅
  bugs.mysql.com/bug.php?id=96365 - 上游 bug
  参考：#4751
  

sqlite

• [sqlite] [bug]
  支持 json 的方言应该在 create_engine() 级别接受参数 json_serializer 和 json_deserializer，然而 SQLite 方言将它们称为 _json_serializer 和 _json_deserilalizer。这些名称已经被更正，旧名称会有更改警告，这些参数现在被记录为 create_engine.json_serializer 和 create_engine.json_deserializer。
  参考：#4798
  
• [sqlite] [bug]
  修复了在  SQLite 方言中使用“PRAGMA table_info”时引发的  bug，这意味着检测表存在性、列出表列和表外键列表的反射功能会默认为任何附加数据库中的任何表，当未给出模式名称并且表不存在于基本模式中时。修复显式地对“main”模式运行  PRAGMA，然后如果“main”返回零行，则对“temp”模式运行  PRAGMA，以维护“无模式”命名空间中的表和临时表的行为，仅在“模式”命名空间中附加表。
  参考：#4793
  

mssql

• [mssql] [usecase]
  添加了适用于 SQL Server 的新 try_cast() 构造，使用“TRY_CAST” 语法。感谢 Leonel Atencio 的 Pull 请求。
  参考：#4782
  

misc

• [bug] [events]
  修复了事件系统中的问题，即在使用 once=True 标志与动态生成的监听器函数时，如果这些监听器函数在使用后被垃圾收集，未来事件的事件注册将失败，因为假设监听函数被强引用。现在，“once”包装已修改为持久性地强引用内部函数，并且文档已更新，使用“once”不意味着自动取消注册监听器函数。
  参考：#4794
  

orm

• [orm] [bug]
  修复了由于新的一对多逻辑的 selectinload 导致的回归，其中基于真实外键的主要联接条件会导致 KeyError，如果父对象的给定键值上不存在相关对象，则会出现此问题。
  参考：#4777
  
• [orm] [bug]
  修复了一个 bug，即在与应用了基于表达式的“偏移量”的查询结合使用时，使用 Query.first() 或切片表达式将引发 TypeError，因为“偏移量”被视为 SQL 表达式而不是整数或 None。
  参考：#4803
  

sql

• [sql] [bug]
  修复了一个问题，即包含一组功能表达式且无法解析为特定列的 Index 对象，与基于字符串的列名组合使用时，将无法正确初始化其内部状态，导致在 DDL 编译过程中失败。
  参考：#4778
  
• [sql] [bug]
  修复了一个 bug，即 TypeEngine.column_expression() 方法不会应用于 UNION 或其他 _selectable.CompoundSelect 中的后续 SELECT 语句，即使 SELECT 语句在语句的最顶层渲染。现在的新逻辑区分了渲染列表达式（对列表中的所有 SELECT 都需要）与收集结果行的返回数据类型（仅对第一个 SELECT 需要）。
  参考文献：#4787
  
• [sql] [bug]
  修复了内部克隆 SELECT 结构可能导致键错误的问题，如果 SELECT 的副本改变了其状态，使得其列列表发生了变化。这在一些 ORM 场景中被观察到，可能是独特于 1.3 及以上版本的，因此部分是一个回归修复。
  参考文献：#4780
  

postgresql

• [postgresql] [usecase]
  为 psycopg2 方言添加了新的方言标志 executemany_mode，它取代了先前的实验性 use_batch_mode 标志。executemany_mode 支持 psycopg2 提供的“execute batch”和“execute values”函数，后者用于编译的 insert() 构造。感谢 Yuval Dinari 提交的拉取请求。
  另请参阅
  Psycopg2 快速执行助手
  参考文献：#4623
  

mysql

• [mysql] [usecase]
  将 ARRAY 和 MEMBER 添加到 MySQL 保留字列表中，因为 MySQL 8.0 现在已将这些保留字。
  参考文献：#4783
  
• [mysql] [bug]
  当  MySQL 方言给出字符集时，MySQL 方言将在连接开始时发出“SET NAMES”，以满足 MySQL 8.0 中观察到的明显行为，当一个  UNION 包含字符串列与形式为 CAST(NULL AS CHAR(…)) 的列时，会引发排序错误，这是 SQLAlchemy 的  polymorphic_union 函数所做的。该问题似乎已经影响了 PyMySQL 至少一年，然而最近出现了 mysqlclient  1.4.4，基于这个 DBAPI 如何创建连接的变化。由于该指令的存在影响了三个不同的 MySQL  字符集设置，每个设置都根据其存在的方式产生复杂的影响，因此 SQLAlchemy 现在将在新连接上发出该指令以确保正确的行为。
  参考文献：#4804
  
• [mysql] [bug]
  为上游 MySQL 8 问题添加了另一个修复，其中对于大小写敏感的表名在外键约束反射中报告不正确，这是首次为 #4344 添加的修复的扩展，影响到大小写敏感的列名。新问题发生在 MySQL 8.0.17 中，因此 88718 修复的一般逻辑仍然有效。
  另请参阅
  bugs.mysql.com/bug.php?id=96365 - 上游 bug
  参考：#4751
  

sqlite

• [sqlite] [bug]
  支持 json 的方言应在 create_engine() 级别接受参数 json_serializer 和 json_deserializer，然而 SQLite 方言将它们称为 _json_serializer 和 _json_deserilalizer。这些名称已经更正，旧名称将带有更改警告接受，并且这些参数现在被记录为 create_engine.json_serializer 和 create_engine.json_deserializer。
  参考：#4798
  
• [sqlite] [bug]
  修复了在  SQLite 方言中使用 “PRAGMA table_info”  导致反射功能默认为任何附加数据库中的任何表，当未给出模式名称且表在基本模式中不存在时，用于检测表存在性、表列列表和外键列表的反射功能。修复明确地为  ‘main’ 模式运行 PRAGMA，然后如果 ‘main’ 返回没有行，则运行 ‘temp’ 模式，以保持“无模式”命名空间中的表 +  临时表的行为，仅在“模式”命名空间中附加表。
  参考：#4793
  

mssql

• [mssql] [usecase]
  为 SQL Server 添加了新的 try_cast() 构造，它发出“TRY_CAST”语法。感谢 Leonel Atencio 的拉取请求。
  参考：#4782
  

杂项

• [bug] [events]
  修复了事件系统中的问题，其中使用 once=True 标志与动态生成的监听器函数会导致未来事件的事件注册失败，如果这些监听器函数在使用后被垃圾回收，因为假设监听函数被强引用。现在，“once” 包装已被修改为持久性地强引用内部函数，并且更新了文档，使用 “once” 不意味着自动注销监听器函数。
  参考：#4794
  

1.3.6

发布日期：2019 年 7 月 21 日

orm

• [orm] [feature]
  添加了新的加载器选项方法Load.options()，允许按层次结构构建加载器选项，因此可以在不需要多次调用defaultload()的情况下，将许多子选项应用于特定路径。感谢 Alessio Bogon 提出的想法。
  参考：#4736
  
• [orm] [performance]
  应用于选择加载中的优化，在#4340中，不需要 JOIN 即可急切加载相关项目，现在也应用于多对一关系，因此仅查询相关表以进行简单的连接条件。在这种情况下，相关项目基于父级的外键列的值进行查询；如果这些列被延迟加载或其他方式未加载到集合中的任何父对象上，则加载器将退回到 JOIN 方法。
  参考：#4775
  
• [orm] [bug]
  由#4365引起的回归错误已修复，即从一个实体到自身的连接没有使用别名时不再引发信息性错误消息，而是在断言失败时失败。已恢复信息性错误条件。
  参考：#4773
  
• [orm] [bug]
  修复了一个问题，即_ORMJoin.join()方法，这是一个未内部使用的 ORM 级方法，公开了通常是内部过程的Query.join()，未正确传播full和outerjoin关键字参数。感谢 Denis Kataev 提供的拉取请求。
  参考：#4713
  
• [orm] [bug]
  修复了一个错误，即指定uselist=True的多对一关系在主键更改时无法正确更新的问题，其中相关列需要更改。
  参考：#4772
  
• [orm] [bug]
  修复了一个错误，即检测到与“动态”关系一起使用的多对一或一对一关系的用法，这是一个无效的配置，如果关系配置为uselist=True，则不会引发错误。当前修复是发出警告，而不是引发错误，因为否则将是向后不兼容的，但在将来的版本中将引发错误。
  参考：#4772
  
• [orm] [bug]
  修复了一个 bug，即针对尚不存在的映射属性创建的同义词（例如在映射器配置之前引用 backref 时）在尝试测试最终不存在的属性时会引发递归错误（例如当类通过 Sphinx autodoc 运行时），因为同义词的未配置状态会将其置于找不到属性的循环中。
  参考：#4767
  

engine

• [engine] [bug]
  修复了一个 bug，即使用反射函数（如MetaData.reflect()）与应用了执行选项的Engine对象会失败的情况，因为生成的OptionEngine代理对象未包含在反射例程中使用的.engine属性。
  参考：#4754
  

sql

• [sql] [bug]
  调整了对Enum的初始化，以减少调用给定 PEP-435 枚举对象的.__members__属性的频率，以适应某些流行的第三方枚举库中这一属性调用昂贵的情况。
  参考：#4758
  
• [sql] [bug] [postgresql]
  修复了一个问题，即array_agg构造与FunctionElement.filter()结合使用时，与数组索引操作符结合时未能产生正确的运算符优先级。
  参考：#4760
  
• [sql] [bug]
  修复了一个不太可能的问题，即对于联合和其他_selectable.CompoundSelect对象的“对应列”例程在某些重叠列情况下可能返回错误的列，从而在使用集合操作时可能影响一些 ORM 操作，如果底层的select()构造之前在其他类似例程中使用过，则由于未清除缓存值而可能出现问题。
  参考：#4747
  

postgresql

• [postgresql] [usecase]
  增加了对 PostgreSQL 分区表上索引的反射支持，这在 PostgreSQL 11 版本中添加。
  参考：#4771
  
• [postgresql] [usecase]
  添加了对多维 Postgresql 数组文字的支持，通过将 array 对象嵌套在另一个对象中。多维数组类型会被自动检测。
  另请参阅
  array
  参考：#4756
  

mysql

• [mysql] [bug]
  修复了一个 bug，在 nullable=True 时渲染 TIMESTAMP 数据类型时，特殊逻辑将无法工作，如果列的数据类型是 TypeDecorator 或 Variant。现在的逻辑确保将其解包到原始的 TIMESTAMP，以便在请求时正确渲染此特殊情况的 NULL 关键字。
  参考：#4743
  
• [mysql] [bug]
  增强了对  MySQL/MariaDB 版本字符串的解析，以适应复杂的 MariaDB 版本字符串，其中 “MariaDB”  一词嵌入在其他字母数字字符中，例如 “MariaDBV1”。这种检测对于正确适应在 MySQL 和 MariaDB 之间拆分的 API  功能至关重要，例如 “transaction_isolation” 系统变量。
  参考：#4624
  

sqlite

• [sqlite] [usecase]
  添加了对 SQLite 的复合（元组）IN 操作符的支持，通过为此后端渲染 VALUES 关键字。由于其他后端（如 DB2）已知使用相同的语法，因此使用方言级别的标志 tuple_in_values 在基础编译器中启用了此语法。此更改还包括对 SQLite 的 “empty IN tuple” 表达式的支持，当使用 “in_()`” 在元组值和空集之间时。
  参考：#4766
  

mssql

• [mssql] [bug]
  确保用于反映索引和视图定义的查询将字符串参数明确转换为  NVARCHAR，因为许多 SQL Server 驱动程序经常将字符串值，特别是具有非 ASCII 字符或较大字符串值的值，视为  TEXT，这通常不会与 SQL Server 的信息模式表中的 VARCHAR 字符正确比较。原因之一。这些 CAST 操作已经在反射查询针对  SQL Server 的 information_schema. 表时发生，但缺少了另外三个针对 sys. 表的查询。
  参考：#4745
  

orm

• [orm] [feature]
  添加了新的加载器选项方法Load.options()，允许按层次结构构建加载器选项，因此可以在不需要多次调用defaultload()的情况下，将许多子选项应用于特定路径。感谢 Alessio Bogon 提出的想法。
  参考：#4736
  
• [orm] [performance]
  在#4340中应用的选择加载优化，即在不需要  JOIN  即可急切加载相关项目时，现在也应用于多对一关系，因此只查询相关表以进行简单的连接条件。在这种情况下，相关项目是基于父对象上的外键列的值进行查询；如果这些列被延迟加载或其他方式未加载到集合中的任何父对象上，则加载器将退回到  JOIN 方法。
  参考：#4775
  
• [orm] [bug]
  修复了由#4365引起的回归，即从一个实体到自身的连接没有使用别名时不再引发信息性错误消息，而是在断言失败。已恢复信息性错误条件。
  参考：#4773
  
• [orm] [bug]
  修复了一个问题，即_ORMJoin.join()方法，这是一个未在内部使用的 ORM 级方法，公开了通常是内部过程的Query.join()，未正确传播full和outerjoin关键字参数。感谢 Denis Kataev 提供的拉取请求。
  参考：#4713
  
• [orm] [bug]
  修复了一个 bug，即指定了uselist=True的多对一关系在主键更改时无法正确更新，需要更改相关列。
  参考：#4772
  
• [orm] [bug]
  修复了一个 bug，即检测到“动态”关系与uselist=True配置的多对一或一对一使用是无效配置时，如果关系配置为uselist=True，则不会引发错误。当前的修复是发出警告，而不是引发错误，因为否则将是向后不兼容的，但在将来的版本中将引发错误。
  参考：#4772
  
• [orm] [bug]
  修复了一个  bug，即针对尚不存在的映射属性创建的同义词，例如在它引用 backref  之前，当尝试测试其上的属性时会引发递归错误，最终这些属性不存在（当类通过 Sphinx autodoc  运行时会发生），因为同义词的未配置状态会将其置于找不到属性的循环中。
  参考：#4767
  

engine

• [engine] [bug]
  修复了一个 bug，即使用反射函数（如 MetaData.reflect()）与应用了执行选项的 Engine 对象一起使用时会失败，因为生成的 OptionEngine 代理对象未包含在反射例程中使用的 .engine 属性。
  参考：#4754
  

sql

• [sql] [bug]
  调整了 Enum 的初始化，以最大程度地减少调用给定 PEP-435 枚举对象的 .__members__ 属性的频率，以适应某些流行的第三方枚举库中调用此属性的昂贵情况。
  参考：#4758
  
• [sql] [bug] [postgresql]
  修复了一个问题，即 array_agg 结构与 FunctionElement.filter() 结合使用时，与数组索引运算符结合时不会产生正确的运算符优先级。
  参考：#4760
  
• [sql] [bug]
  修复了一个不太可能的问题，即对于联合和其他 _selectable.CompoundSelect 对象的“对应列”例程在某些重叠列情况下可能返回错误的列，从而在使用集合操作时可能影响一些 ORM 操作，如果之前在其他类似的例程中使用了底层的 select() 构造，由于缓存值未被清除。
  参考：#4747
  

postgresql

• [postgresql] [usecase]
  增加了对 PostgreSQL 分区表上索引的反射支持，这在 PostgreSQL 11 版本中添加。
  参考：#4771
  
• [postgresql] [usecase]
  通过将 array 对象嵌套在另一个对象中，增加了对多维 Postgresql 数组文字的支持。多维数组类型会自动检测���
  另请参阅
  array
  参考：#4756
  

mysql

• [mysql] [bug]
  修复了一个 bug，即当列的数据类型为 TypeDecorator 或 Variant 时，为 nullable=True 渲染“NULL”特殊逻辑不起作用。现在的逻辑确保将其解包到原始的 TIMESTAMP，以便在请求时正确呈现此特殊情况的 NULL 关键字。
  参考：#4743
  
• [mysql] [bug]
  增强了对  MySQL/MariaDB 版本字符串的解析，以适应奇异的 MariaDB 版本字符串，其中“MariaDB”  一词嵌入在其他字母数字字符中，如“MariaDBV1”。这种检测对于正确适应已在 MySQL 和 MariaDB 之间拆分的 API  功能至关重要，例如“transaction_isolation” 系统变量。
  参考：#4624
  

sqlite

• [sqlite] [usecase]
  增加了对 SQLite 的复合（元组）IN 操作符的支持，通过在此后端渲染 VALUES 关键字来实现。由于其他后端（如 DB2）已知使用相同的语法，因此在基本编译器中使用方言级标志 tuple_in_values 启用了该语法。该更改还包括在使用“in_()”时支持 SQLite 的“空 IN 元组”表达式，介于元组值和空集之间。
  参考：#4766
  

mssql

• [mssql] [bug]
  确保用于反射索引和视图定义的查询将字符串参数明确转换为  NVARCHAR，因为许多 SQL Server 驱动程序经常将字符串值（特别是具有非 ASCII 字符或较大字符串值的值）视为  TEXT，这些值通常无法与 SQL Server 的信息模式表中的 VARCHAR 字符正确比较。这些 CAST 操作已经在反射查询针对 SQL  Server information_schema. 表时发生，但缺少了针对针对 sys. 表的另外三个查询。
  参考：#4745

SqlAlchemy 2.0 中文文档（六十）（5）https://developer.aliyun.com/article/1560733