SQLAlchemy 2.0 文档
变更和迁移
- SQLAlchemy 2.0 - 主要迁移指南
- SQLAlchemy 2.0 的新特性？
- 2.0 更新日志
- 1.4 更新日志
- 1.3 更新日志¶
- 1.2 更新日志
- 1.1 更新日志
- 1.0 更新日志
- 0.9 更新日志
- 0.8 更新日志
- 0.7 更新日志
- 0.6 更新日志
- 0.5 更新日志
- 0.4 更新日志
- 0.3 更新日志
- 0.2 更新日志
- 0.1 更新日志
- SQLAlchemy 1.4 的新特性？
- SQLAlchemy 1.3 的新特性？
- SQLAlchemy 1.2 的新特性？
- SQLAlchemy 1.1 的新特性？
- SQLAlchemy 1.0 的新特性？
- SQLAlchemy 0.9 的新特性？
- SQLAlchemy 0.8 的新特性？
- SQLAlchemy 0.7 的新特性？
- SQLAlchemy 0.6 的新特性？
- SQLAlchemy 0.5 的新特性？
- SQLAlchemy 0.4 的新特性？
项目版本
1.3 更新日志¶
1.3.25¶
无发布日期orm¶
[orm] [bug] ¶
修复了当与持久对象一起使用时，
Session.bulk_save_objects()中的问题，该问题会导致在主键列名与属性名不同的映射中无法跟踪主键。参考: #6392
schema¶
[schema] [bug] ¶
Table对象现在会在实例化时，如果没有以位置参数至少传递Table.name和Table.metadata参数，则会引发信息丰富的错误消息。 以前，如果这些参数作为关键字参数传递，则对象会静默地初始化失败。参考: #6135
postgresql¶
mysql¶
[mysql] [bug] [mariadb] ¶
修复了以适应 MariaDB 10.6 系列，包括 mariadb-connector Python 驱动程序（仅在 SQLAlchemy 1.4 上支持）以及本机 10.6 客户端库中的向后不兼容的更改，mysqlclient DBAPI 会自动使用这些库（适用于 1.3 和 1.4）。 当编码声明为 “utf8” 时，“utf8mb3” 编码符号现在由这些客户端库报告，从而导致 MySQL 方言中出现查找和编码错误，而 MySQL 方言不希望出现此符号。 更新了 MySQL 基础库以适应报告的 utf8mb3 符号以及测试套件。 感谢 Georg Richter 的支持。
sqlite¶
1.3.24¶
发布日期: 2021年3月30日orm¶
[orm] [bug] ¶
删除了非常旧的警告，该警告声明 passive_deletes 不适用于多对一关系。 虽然在许多情况下将此参数放在多对一关系上可能不是预期的目的，但在某些用例中，可能需要禁止从此类关系进行的删除级联。
参考: #5983
[orm] [bug] ¶
修复了当其中一个表具有不相关的、无法解析的外键约束时，连接两个表的过程可能会失败的问题，该约束会在连接过程中引发
NoReferenceError，但可以绕过该错误以允许连接完成。 在此过程中测试异常重要性的逻辑会对将失败的构造做出假设。参考: #5952
[orm] [bug] ¶
修复了当父对象已加载，然后被后续查询覆盖时，
MutableComposite构造可能会置于无效状态的问题，这是由于复合属性的刷新处理程序将对象替换为新的对象，而该对象未由可变扩展处理。参考: #6001
engine¶
[engine] [bug] ¶
修复了 “schema_translate_map” 功能在直接执行
DefaultGenerator对象（例如序列）的用例中未能考虑的问题，其中包括为了在禁用 implicit_returning 时生成主键值而“预先执行”的情况。参考: #5929
schema¶
[schema] [bug] ¶
修复了最初在 #2892、#2919 和 #3832 的某些组合中引入的错误，其中
TypeDecorator的附件事件将针对 “impl” 类重复，如果 “impl” 也是SchemaType。 实际情况是，任何针对Enum或Boolean的TypeDecorator将在设置create_constraint=True标志时获得双重CheckConstraint。参考: #6152
[schema] [bug] [sqlite] ¶
修复了由
Boolean或Enum生成的 CHECK 约束在首次编译后将无法正确呈现命名约定的问题，这是由于赋予约束的名称中状态的意外更改所致。 此问题最初是在 0.9 中为修复问题 #3067 而引入的，并且此修复修改了当时采取的方法，该方法似乎比需要的更复杂。参考: #6007
[schema] [bug] ¶
修复/实现了对主键约束命名约定的支持，该约定使用列名/键/等作为约定的一部分。 特别是，这包括自动与
Table关联的PrimaryKeyConstraint对象将在新的主键Column对象添加到表，然后再添加到约束时更新其名称。 现在可以容纳与此约束构造过程相关的内部故障模式，包括不存在列、不存在名称或存在空白名称。参考: #5919
[schema] [bug] ¶
调整了为多个表的删除发出
Sequence对象的 DROP 语句的逻辑，以便在所有表之后删除所有Sequence对象，即使给定的Sequence仅与Table对象相关，而不直接与整个MetaData对象相关。 此用例支持一次将相同的Sequence与多个Table关联。参考: #6071
postgresql¶
[postgresql] [bug] ¶
修复了在某些条件下使用
aggregate_order_by会返回 ARRAY(NullType) 的问题，从而干扰了结果对象正确返回数据的能力。参考: #5989
[postgresql] [bug] [reflection] ¶
修复了 PostgreSQL 反射中的问题，其中表达 “NOT NULL” 的列将取代相应域的可空性。
参考: #6161
[postgresql] [bug] [types] ¶
调整了 psycopg2 方言，以便为包含 ARRAY 元素的绑定参数发出显式的 PostgreSQL 样式强制转换。 这允许全范围的数据类型在数组中正常工作。 asyncpg 方言已经在最终语句中生成了这些内部强制转换。 这还包括对数组切片更新以及 PostgreSQL 特定的
ARRAY.contains()方法的支持。参考: #6023
mssql¶
1.3.23¶
发布日期: 2021年2月1日sql¶
[sql] [bug] ¶
修复了在
TypeDecorator类型上使用TypeEngine.with_variant()方法将无法考虑正在使用的方言特定映射的错误，这是由于TypeDecorator中的规则试图检查TypeDecorator实例链。参考: #5816
postgresql¶
[postgresql] [bug] ¶
仅对于 SQLAlchemy 1.3，setup.py 将 pg8000 锁定到低于 1.16.6 的版本。 SQLAlchemy 1.4 支持 1.16.6 及更高版本。 Pull request 由 Giuseppe Lumia 提供。
参考: #5645
[postgresql] [bug] ¶
修复了将
Table.to_metadata()(在 1.3 中称为Table.tometadata()) 与 PostgreSQLExcludeConstraint结合使用的问题，该约束使用了临时的列表达式，这将导致复制失败。参考: #5850
mysql¶
[mysql] [usecase] ¶
MySQL >= (8, 0, 17) 和 MariaDb >= (10, 4, 5) 现在支持强制转换为
FLOAT。参考: #5808
[mysql] [bug] [reflection] ¶
修复了 MySQL 服务器默认反射在存在否定符号的情况下将对数值失败的错误。
参考: #5860
[mysql] [bug] ¶
修复了 MySQL 方言中长期存在的错误，其中 255 的最大标识符长度对于所有类型的约束名称来说都太长了，而不仅仅是索引，所有这些索引的尺寸限制为 64。 由于元数据命名约定可能会在此区域中创建过长的名称，因此将限制应用于 DDL 编译器中的标识符生成器。
参考: #5898
[mysql] [bug] ¶
修复了由于 PyMySQL 1.0 的发布而引起的弃用警告，包括现在被 “database” 和 “password” 替换的 “db” 和 “passwd” 参数的弃用警告。
参考: #5821
[mysql] [bug] ¶
修复了由 #5462 的修复引起的 SQLAlchemy 1.3.20 的回归问题，该修复为索引中的 MySQL 功能表达式添加了双括号，这是后端所要求的，但这无意中扩展为包括任意
text()表达式以及 Alembic 的内部文本组件，Alembic 需要它们用于不暗示双括号的任意索引表达式。 该检查已缩小范围，仅直接包括二进制/一元/功能表达式。参考: #5800
oracle¶
[oracle] [bug] ¶
修复了由 SQLAlchemy 1.3.11 中的 #4894 引起的 Oracle 方言中的回归问题，其中在 UPDATE 的 RETURNING 中使用 SQL 表达式将无法编译，这是由于检查 “server_default” 时，任意 SQL 表达式不是列。
参考: #5813
[oracle] [bug] ¶
修复了 Oracle 方言中的错误，其中通过
Insert.returning()检索 CLOB/BLOB 列将失败，因为需要在返回时读取 LOB 值； 此外，修复了在 Python 2 下通过 RETURNING 检索 Unicode 值的支持。参考: #5812
misc¶
[bug] [ext] ¶
修复了当尝试为 selectable 上的
.c集合生成 “key” 时，有时调用的字符串化操作会在列是使用sqlalchemy.ext.compiler扩展的未标记自定义 SQL 构造，并且未提供默认编译形式时失败的问题； 虽然这似乎是不寻常的情况，但对于某些 ORM 场景（例如，当表达式与连接的急切加载结合在 “order by” 中使用时）可能会调用它。 问题在于缺少默认编译器函数引发了CompileError而不是UnsupportedCompilationError。参考: #5836
1.3.22¶
发布日期: 2020年12月18日oracle¶
[oracle] [bug] ¶
修复了由于 #5755 而发生的回归问题，该问题为 Oracle 实现了隔离级别支持。 据报告，许多 Oracle 帐户实际上没有查询
v$transaction视图的权限，因此此功能已更改为在数据库连接失败时优雅地回退，在这种情况下，方言将假定 “READ COMMITTED” 是默认隔离级别，就像 SQLAlchemy 1.3.21 之前的情况一样。 但是，显式使用Connection.get_isolation_level()方法现在必须必然引发异常，因为具有此限制的 Oracle 数据库明确禁止用户读取当前隔离级别。参考: #5784
1.3.21¶
发布日期: 2020年12月17日orm¶
[orm] [bug] ¶
为映射类或字符串映射类名称传递给
relationship.secondary的情况添加了全面的检查和信息丰富的错误消息。 这是一个极其常见的错误，需要明确的消息。此外，为类注册表解析添加了一条新规则，以便在
relationship.secondary参数方面，如果映射类及其表的字符串名称相同，则在解析此参数时将优先选择Table。 在所有其他情况下，如果类和表共享相同的名称，则类将继续优先。参考: #5774
[orm] [bug] ¶
修复了
Query.update()中的错误，其中_ormsession.Session中已过期的对象在通过 “evaluate” 同步策略刷新时将被不必要地单独 SELECT。参考: #5664
[orm] [bug] ¶
修复了涉及 ORM 事件（例如
InstanceEvents.load()）的restore_load_context选项的错误。此错误曾导致该标志无法传递给在事件处理程序首次建立后才映射的子类。参考链接: #5737
sql¶
[sql] [bug] ¶
如果多次调用 `returning()` 方法（例如
Insert.returning()`），则会发出警告，因为当前版本尚不支持累加操作。 版本 1.4 将会支持此操作的累加。 此外，现在如果同时使用 `Insert.returning()` 和 `ValuesBase.return_defaults()` 方法，将会引发错误，因为这两种方法是互斥的。 此前，这种操作会静默失败。参考链接: #5691
[sql] [bug] ¶
修复了结构编译器问题，该问题导致某些构造（例如 MySQL / PostgreSQL “on conflict / on duplicate key”）依赖于 `
Compiler` 对象的状态，该状态被固定为顶级语句。当这些语句从不同的上下文（例如链接到 SQL 语句的 DDL 构造）分支出来时，这会导致失败。参考链接: #5656
postgresql¶
[postgresql] [usecase] ¶
为 `
ExcludeConstraint` 对象添加了新的参数 `ExcludeConstraint.ops`，以支持此约束中的运算符类规范。 此拉取请求由 Alon Menczer 提供。参考链接: #5604
[postgresql] [bug] [mysql] ¶
修复了 1.3.2 版本中 PostgreSQL 方言引入的回归问题，该问题也复制到了 1.3.18 版本中 MySQL 方言的功能中。当使用非 `
Table` 构造（例如 `text()`）作为 `Select.with_for_update.of` 的参数时，PostgreSQL 或 MySQL 编译器无法正确处理。参考链接: #5729
mysql¶
sqlite¶
mssql¶
oracle¶
[oracle] [usecase] ¶
实现了对 Oracle 数据库 SERIALIZABLE 隔离级别的支持，以及对
Connection.get_isolation_level()的实际实现。另请参阅
参考链接: #5755
1.3.20¶
发布日期：2020 年 10 月 12 日orm¶
[orm] [bug] ¶
如果 `
Query.join()` 的 target 参数设置为未映射的对象，则现在会引发更详细的 `ArgumentError` 错误。 在此更改之前，会引发不太详细的 `AttributeError` 错误。 此拉取请求由 Ramon Williams 提供。参考链接: #4428
[orm] [bug] ¶
修复了以下问题：对实际上不是映射属性的字符串属性名称（例如纯 Python 描述符）使用加载器选项会引发信息量不足的 AttributeError 错误； 现在会引发描述性错误。
参考链接: #4589
engine¶
[engine] [bug] ¶
修复了将非字符串对象发送到 `
SQLAlchemyError` 或子类（某些第三方方言会发生这种情况）时，无法正确字符串化的问题。 此拉取请求由 Andrzej Bartosiński 提供。参考链接: #5599
[engine] [bug] ¶
修复了 sqlalchemy.exc 模块中未使用 SQLAlchemy 标准延迟导入系统的函数级导入。
参考链接: #5632
sql¶
postgresql¶
[postgresql] [usecase] ¶
psycopg2 方言现在通过将主机/端口组合传递给查询字符串来支持 PostgreSQL 多主机连接。 此拉取请求由 Ramon Williams 提供。
另请参阅
参考链接: #4392
[postgresql] [bug] ¶
调整了 `
Comparator.any()` 和 `Comparator.all()` 方法，以实现直接的 “NOT” 运算来进行否定，而不是否定比较运算符。参考链接: #5518
[postgresql] [bug] ¶
修复了以下问题：当在测试期间发出 CREATE TYPE 或 DROP TYPE 以查看类型是否存在时，`
ENUM` 类型不会查询模式转换映射。 此外，修复了如果在单个 DDL 序列中多次遇到相同的枚举，则“检查”查询会重复运行而不是依赖缓存值的问题。参考链接: #5520
mysql¶
[mysql] [usecase] ¶
调整了 MySQL 方言，以正确地将函数索引表达式括在括号中，MySQL 8 接受这种表达式。 此拉取请求由 Ramon Williams 提供。
参考链接: #5462
[mysql] [change] ¶
添加了新的 MySQL 保留字：`
cube` 和 `lateral`，分别在 MySQL 8.0.1 和 8.0.14 中添加； 这表示如果这些术语用作表名或列标识符名称，则将被引用。参考链接: #5539
[mysql] [bug] ¶
在 MariaDB 后端使用 `
with_for_update()` 的 “skip_locked” 关键字时，将发出警告，然后将被忽略。 这是已弃用的行为，将在 SQLAlchemy 1.4 中引发错误，因为请求 “skip locked” 的应用程序正在寻找那些后端不可用的非阻塞操作。参考链接: #5568
[mysql] [bug] ¶
修复了以下错误：如果 UPDATE 语句对使用 MySQL 多表格式的 JOIN 没有 WHERE 子句，则会无法包含目标表的表前缀，因为仅扫描 WHERE 子句以在该特定点检测 “多表更新”。 现在，如果目标是 JOIN，也会扫描目标以获取最左边的表作为主表，并将其他条目作为额外的 FROM 条目。
参考链接: #5617
mssql¶
tests¶
misc¶
1.3.19¶
发布日期：2020 年 8 月 17 日orm¶
[orm] [usecase] ¶
调整了 `
Mapper.all_orm_descriptors()` 访问器的工作方式，以确定性的方式表示属性的顺序，前提是使用 Python 3.6 或更高版本，该版本维护了基于类属性声明方式的排序顺序。 但是，不能保证此排序在所有情况下都与属性的声明顺序匹配； 请参阅方法文档以获取确切的方案。参考链接: #5494
orm declarative¶
[orm] [declarative] [usecase] ¶
现在可以自定义使用 `
AbstractConcreteBase` 和 `ConcreteBase` 类时使用的虚拟列的名称，以允许模型具有实际名为 `type` 的列。 此拉取请求由 Jesse-Bakker 提供。参考链接: #5513
sql¶
[sql] [bug] ¶
修复了以下问题：如果表达式在某些情况下包含在带括号的分组中，则 “ORDER BY” 子句呈现标签名称而不是完整表达式（对于 SQL Server 尤其重要）将无法发生。 此案例已添加到测试支持中。 此更改还调整了 ORM 查询的 “当 DISTINCT 存在时自动添加 ORDER BY 列” 行为（在 1.4 中已弃用），以更准确地检测已存在的列表达式。
参考链接: #5470
[sql] [bug] [datatypes] ¶
`
LookupError` 消息现在将为用户提供最多四个可能的值，这些值通过 `Enum` 约束列。 长度超过 11 个字符的值将被截断并替换为省略号。 此拉取请求由 Ramon Williams 提供。参考链接: #4733
[sql] [bug] ¶
修复了以下问题：当在 `
Column.server_default` 参数中使用 `Sequence.next_value()` 函数（用于 `Sequence）并且发出了 create table DDL 时，`Connection.execution_options.schema_translate_map` 功能不起作用。参考链接: #5500
postgresql¶
[postgresql] [bug] ¶
修复了以下问题：各种 RANGE 比较运算符的返回类型本身将是相同的 RANGE 类型，而不是 BOOLEAN，这会在使用定义了结果处理行为的 `
TypeDecorator时导致不良结果。 此拉取请求由 Jim Bosch 提供。参考链接: #5476
mysql¶
[mysql] [usecase] ¶
对于没有 FROM 子句但有 WHERE 子句的 SELECT 语句，MySQL 方言将呈现 FROM DUAL。 这允许使用诸如 “SELECT 1 WHERE EXISTS (subquery)” 之类的查询以及其他用例。
参考链接: #5481
[mysql] [bug] ¶
修复了 CREATE TABLE 语句未正确指定 COLLATE 关键字的问题。
参考链接: #5411
[mysql] [bug] ¶
将 MariaDB 代码 1927 添加到 “disconnect” 代码列表中，因为最近的 MariaDB 版本显然在数据库服务器停止时使用此代码。
参考链接: #5493
sqlite¶
mssql¶
misc¶
1.3.18¶
发布日期：2020 年 6 月 25 日orm¶
[orm] [usecase] ¶
改进了在查询中使用 `
Query.filter_by()` 且第一个实体不是映射类时的错误消息。参考链接: #5326
[orm] [usecase] ¶
为 `
query_expression()` 构造添加了新的参数 `query_expression.default_expr`，如果未使用 `with_expression()` 选项，则该参数将自动应用于查询。 此拉取请求由 Haoyu Sun 提供。参考链接: #5198
examples¶
[examples] [change] ¶
为 examples.performance 套件添加了新的选项 `
--raw`，该选项将转储原始配置文件测试，以供任何数量的配置文件可视化工具使用。 移除了 “runsnake” 选项，因为 runsnake 在此时很难构建；
engine¶
sql¶
[sql] [usecase] ¶
为 `
table()` 构造添加了 “.schema” 参数，允许临时表表达式也包含模式名称。 此拉取请求由 Dylan Modesitt 提供。参考链接: #5309
[sql] [change] [sybase] ¶
为 sybase 方言添加了 `
.offset` 支持。 此拉取请求由 Alan D. Snow 提供。参考链接: #5294
[sql] [bug] ¶
在 type_coerce 元素中正确应用 self_group。
当在表达式中使用时，类型强制元素未正确应用分组规则
参考链接: #5344
[sql] [bug] ¶
将 `
Select.with_hint()` 输出添加到在语句上调用 `str()` 时生成的通用 SQL 字符串中。 以前，此子句将被省略，因为假定它是特定于方言的。 提示文本显示在方括号内，以指示此类提示的呈现方式在后端之间有所不同。参考链接: #5353
[sql] [schema] ¶
引入 `
IdentityOptions` 以存储序列和标识列的通用参数。参考链接: #5324
schema¶
mysql¶
sqlite¶
mssql¶
[mssql] [变更] ¶
将
supports_sane_rowcount_returning = False要求从PyODBCConnector级别移至MSDialect_pyodbc，因为 pyodbc 在某些情况下可以正常工作。参考链接：#5321
[mssql] [缺陷] ¶
改进了 SQL Server 方言用于解释包含多个点号的多部分模式名称的逻辑，即使名称没有使用括号或引号，也不会实际丢失任何点号，并且还支持包含多个部分的 “dbname” 令牌，包括可能包含多个独立加括号的部分。
[mssql] [缺陷] [pyodbc] ¶
修复了 pyodbc 连接器中的一个问题，即当使用完全空的 URL 时，会发出关于 pyodbc “drivername” 的警告。当生成未连接的方言对象或使用 “creator” 参数创建 create_engine() 时，空 URL 是正常的。现在，只有当驱动程序名称丢失但其他参数仍然存在时，才会发出警告。
参考链接：#5346
[mssql] [缺陷] ¶
修复了为 pyodbc DBAPI 组装 ODBC 连接字符串的问题。包含分号和/或大括号 “{}” 的令牌未被正确转义，导致 ODBC 驱动程序错误地解释连接字符串属性。
参考链接：#5373
[mssql] [缺陷] ¶
修复了
datetime.time参数被转换为datetime.datetime的问题，导致它们与针对实际TIME列的>=等比较不兼容。参考链接：#5339
[mssql] [缺陷] ¶
修复了 SQL Server pyodbc 方言中的
is_disconnect函数在异常消息中包含与 SQL Server ODBC 错误代码匹配的子字符串时，错误报告断开连接状态的问题。参考链接：#5359
oracle¶
1.3.17¶
发布日期：2020 年 5 月 13 日orm¶
[orm] [用例] ¶
添加了一个访问器
Comparator.expressions，它提供了对多列ColumnProperty属性下映射的列组的访问。参考链接：#5262
[orm] [用例] ¶
在关系中引入
relationship.sync_backref标志，以控制是否添加改变 Python 属性的同步事件。这取代了之前的更改 #5149，该更改警告说，back_populates 或 backref 配置的viewonly=True关系目标将被禁止。参考链接：#5237
[orm] [缺陷] ¶
修复了当使用
with_polymorphic()作为通过RelationshipComparator.of_type()连接的目标时，在已经具有子查询的 with_polymorphic 设置的映射器上，如果请求的设置与之等效，则不会正确别名连接中的 ON 子句的错误。参考链接：#5288
[orm] [缺陷] ¶
修复了加载器选项（如 selectinload()）与 baked 查询系统交互的区域中的问题，即如果加载器选项本身包含 with_polymorphic() 对象等当前与缓存不兼容的元素，则不应发生查询缓存。在某些情况下，baked 加载器有时无法完全使其自身失效，从而导致错过预加载。
参考链接：#5303
[orm] [缺陷] ¶
修改了内部 “身份集合” 实现，该实现是一个根据对象的 id() 而不是其哈希值来哈希对象的集合，以实际不调用对象的
__hash__()方法，这些对象通常是用户映射的对象。某些方法在实现过程中会作为副作用调用此方法。参考链接：#5304
[orm] [缺陷] ¶
当尝试对不是实际映射实例的对象进行 ORM 多对一比较时，会引发信息丰富的错误消息。不支持与标量子查询的比较；与子查询的广义比较最好使用
Comparator.has()来实现。参考链接：#5269
engine¶
schema¶
[schema] [缺陷] ¶
修复了
Index在与表关联时被延迟的问题，例如当它包含一个Column时，该Column尚未与任何Table关联，如果它还包含非面向表的表达式，则会无法正确附加。参考链接：#5298
[schema] [缺陷] ¶
当使用
MetaData.sorted_tables属性以及sort_tables()函数时，如果给定的表由于外键约束之间的循环依赖关系而无法正确排序，则会发出警告。在这种情况下，这些函数将不再按外键对外键循环涉及的表进行排序，并且将发出警告。不属于循环的其他表仍将按依赖顺序返回。以前，当检测到循环时，sorted_table 例程将返回一个无条件省略所有外键的集合，并且不会发出警告。参考链接：#5316
[schema] ¶
向
Column__repr__方法添加comment属性。参考链接：#4138
postgresql¶
[postgresql] [用例] ¶
添加了对 PostgreSQL 中
ARRAY类型的列或类型为Enum、JSON或JSONB的支持。以前在这些用例中需要变通方法。参考链接：#5265
[postgresql] [用例] ¶
当添加具有
ARRAY类型的列，且该列的Enum配置为Enum.native_enum设置为False，并且Enum.create_constraint未设置为False时，引发显式的CompileError。参考链接：#5266
mssql¶
oracle¶
[oracle] [缺陷] ¶
对 cx_oracle 方言如何为 LOB 和数值数据类型设置每列 outputtype 处理程序进行了一些修改，以适应 cx_Oracle 8 中即将到来的潜在更改。
参考链接：#5246
[oracle] [缺陷] [性能] ¶
更改了获取 CLOB 和 BLOB 对象的实现，以使用 cx_Oracle 的原生实现，该实现将 CLOB/BLOB 对象与其他结果列内联获取，而不是执行单独的提取。与往常一样，可以通过将 auto_convert_lobs 设置为 False 来禁用此功能。
作为此更改的一部分，在 INSERT 上给出空字符串的 CLOB 的行为现在在 SELECT 上返回 None，这现在与 Oracle 上 VARCHAR 的行为一致。
参考链接：#5314
misc¶
1.3.16¶
发布日期：2020 年 4 月 7 日orm¶
[orm] [性能] ¶
修改了 subqueryload 和 selectinload 使用的查询，不再按父实体的主键进行 ORDER BY 排序；此排序是为了允许将传入的行直接复制到列表中，并尽量减少 Python 端的整理级别。但是，这些 ORDER BY 子句可能会对查询的性能产生负面影响，因为在许多情况下，这些列是从子查询派生的，或者不是实际的主键列，因此 SQL 规划器无法使用索引。Python 端的整理使用原生 itertools.group_by() 来整理传入的行，并且已进行修改，以允许使用 list.extend() 将每个父行的多个行组组装在一起，这仍然应该允许相对较快的 Python 端性能。对于包含显式 order_by 参数的关系，仍然会存在 ORDER BY，但这将是添加到查询中的唯一 ORDER BY，适用于两种加载类型。
参考链接：#5162
[orm] [缺陷] ¶
修复了
selectinload()加载选项中的一个错误，其中两个或多个加载器，它们表示与单个with_polymorphic()构造（具有多个子类映射器）引用的相同字符串键名称的不同关系，将无法单独调用每个子查询加载，而是使用单个基于字符串的槽，这将阻止其他加载器被调用。参考链接：#5228
[orm] [缺陷] ¶
修复了一个问题，即对目标多对一关系使用会话本地 “get” 的延迟加载，其中存在具有正确主键的对象，但它是同级类的实例，不会像延迟加载器实际为该行发出加载时那样正确返回 None。
参考链接：#5210
orm declarative¶
[orm] [声明式] [缺陷] ¶
当使用声明式 API 时，
relationship()函数接受的字符串参数作为第一个位置参数，不再使用 Pythoneval()函数进行解释；相反，名称是点分隔的，并且名称直接在名称解析字典中查找，而不会将值视为 Python 表达式。但是，将字符串参数传递给其他必须接受 Python 表达式的relationship()参数仍然会使用eval()；文档已得到澄清，以确保对此用法没有歧义。另请参阅
关系参数的求值 - 有关字符串求值的详细信息
参考链接：#5238
sql¶
schema¶
[schema] [reflection] ¶
添加了对 “计算列” 反射的支持，计算列现在作为
Inspector.get_columns()返回的结构的一部分返回。当反射完整的Table对象时，计算列将使用Computed构造来表示。参考链接：#5063
postgresql¶
mysql¶
sqlite¶
mssql¶
[mssql] [用例] [mysql] [oracle] ¶
为 SQL Server、MySQL 和 Oracle 添加了对
ColumnOperators.is_distinct_from()和ColumnOperators.isnot_distinct_from()的支持。参考链接：#5137
oracle¶
tests¶
misc¶
[enum] [类型] ¶
Enum类型现在支持参数Enum.length，用于在使用非原生枚举时，通过将Enum.native_enum设置为False来指定要创建的 VARCHAR 列的长度。参考链接：#5183
[installer] ¶
确保 “pyproject.toml” 文件不包含在构建中，因为此文件的存在向 pip 指示应使用 pep-517 安装过程。由于这种操作模式似乎没有得到当前工具/发行版的良好支持，因此在 SQLAlchemy 安装范围内通过省略该文件来避免这些问题。
参考链接：#5207
1.3.15¶
发布日期：2020 年 3 月 11 日orm¶
[orm] [缺陷] ¶
调整了
Query.join()在无法找到左侧时发出的错误消息，Query.select_from()方法是解决此问题的最佳方法。此外，在 1.3 系列中，在确定从传递给Query的给定列实体中的 FROM 子句时，使用了确定性排序，以便每次都确定相同的表达式。参考链接：#5194
[orm] [缺陷] ¶
修复了 1.3.14 中由于 #4849 导致的回归，其中当发生 flush 错误时，sys.exc_info() 调用未能正确调用。已为此异常情况添加了测试覆盖率。
参考链接：#5196
1.3.14¶
发布日期：2020 年 3 月 10 日general¶
orm¶
[orm] [用例] ¶
添加了一个新的标志
InstanceEvents.restore_load_context和SessionEvents.restore_load_context，它们应用于InstanceEvents.load()、InstanceEvents.refresh()和SessionEvents.loaded_as_persistent()事件，当设置这些标志时，将在事件钩子被调用后恢复对象的 “加载上下文”。这确保了对象保留在已在进行的加载操作的 “加载上下文” 中，而不是由于事件中可能发生的刷新操作而将对象转移到新的加载上下文。当发生这种情况时，现在会发出警告，建议使用该标志来解决此问题。该标志是 “选择加入” 的，因此不会对现有应用程序引入风险。此更改还添加了对会话生命周期事件的
raw=True标志的支持。参考链接：#5129
[orm] [缺陷] ¶
修复了 1.3.13 版本中由 #5056 引起的回归问题。该问题是由于 ORM 路径注册系统的重构导致路径无法再与空元组进行比较，这种情况可能发生在某种特定的连接迫切加载路径中。“空元组”用例已得到解决，现在路径注册表在所有情况下都与路径注册表进行比较；
PathRegistry对象本身现在实现了__eq__()和__ne__()方法，这些方法将用于所有相等性比较，并在未预料到的情况下继续成功执行，即与非PathRegistry对象进行比较，同时发出警告，提示该对象不应作为比较的主题。参考：#5110
[orm] [bug] ¶
现在，将关系设置为 viewonly=True，并且该关系也是 back_populates 或 backref 配置的目标时，将发出警告，并最终被禁止。back_populates 专门指属性或集合的修改，当属性受 viewonly=True 约束时，这是不允许的。viewonly 属性不受持久性行为的影响，这意味着当它在本地修改时，它不会反映正确的结果。
参考：#5149
[orm] [bug] ¶
修复了与 #5080 相同区域的另一个回归问题，该问题是在 1.3.0b3 版本中通过 #4468 引入的。该问题导致无法跨越
with_polymorphic()创建连接选项，进入与 with_polymorphic 的基类相关的关系，然后进一步进入常规映射关系时会失败，因为基类组件不会以加载策略可以定位的方式将自身添加到加载路径中。#5080 中应用更改已进一步完善，以适应这种情况。参考：#5121
engine¶
sql¶
postgresql¶
[postgresql] [bug] ¶
修复了“schema_translate_map”功能无法与 PostgreSQL 原生枚举类型（即
Enum,ENUM）一起使用的问题，因为虽然“CREATE TYPE”语句会使用正确的 schema 发出，但 schema 不会在引用枚举的 CREATE TABLE 语句中呈现。参考：#5158
[postgresql] [bug] [reflection] ¶
修复了 PostgreSQL 反射 CHECK 约束在 SQL 文本包含换行符时解析约束失败的错误。正则表达式已调整以适应这种情况。感谢 Eric Borczuk 提供 pull request。
参考：#5170
mysql¶
[mysql] [bug] ¶
修复了 MySQL
Insert.on_duplicate_key_update()构造中的问题，其中对列参数使用 SQL 函数或其他组合表达式时，不会正确呈现包围列本身的VALUES关键字。参考：#5173
mssql¶
[mssql] [bug] ¶
修复了
DATETIMEOFFSET类型无法容纳None值的问题，该问题是作为 #4983, #5045 中首次引入的此类型的一系列修复的一部分引入的。此外，还添加了对此类型传递后端特定的日期格式字符串的支持，这通常在大多数其他 DBAPI 上的日期/时间类型中是允许的。参考：#5132
oracle¶
misc¶
[usecase] [ext] ¶
为
MutableList.sort()函数添加了关键字参数，以便可以提供键函数以及“reverse”关键字参数。参考：#5114
[bug] [performance] ¶
修订了作为 #5085 的结果添加到测试系统的内部更改，其中每个方言的测试相关模块将在使用该方言时无条件加载，从而将 SQLAlchemy 的测试框架以及 ORM 拉入模块导入空间。这只会对初始启动时间和内存产生适度的影响，但最好这些额外的模块不要反向依赖于直接 Core 用法。
参考：#5180
[bug] [installation] ¶
在
sqlalchemy.util.compat内部 vendor 了inspect.formatannotation函数，这是 vendor 版本的inspect.formatargspec所需要的。该函数未在 cPython 中记录，并且不能保证在未来的 Python 版本中可用。参考：#5138
1.3.13¶
发布日期：2020 年 1 月 22 日orm¶
[orm] [performance] ¶
识别了基于映射关系构建连接的系统中的性能问题。子句适配系统将用于大多数连接表达式，包括在不需要适配的常见情况下。已经改进了发生此适配的条件，以便沿简单关系且没有“secondary”表的平均非别名连接使用大约减少 70% 的函数调用。
[orm] [bug] [engine] ¶
添加了测试支持并修复了为短生命周期对象创建的各种不必要的引用循环，主要是在 ORM 查询领域。非常感谢 Carson Ip 在这方面的帮助。
[orm] [bug] ¶
修复了在 1.3.0b3 版本中通过 #4468 引入的加载器选项回归问题，其中使用
PropComparator.of_type()定位别名实体（该实体是先前关系引用的实体的继承子类）创建加载器选项的能力将无法生成匹配路径。另请参阅在此版本中修复的 #5082，其中涉及类似类型的问题。参考：#5107
[orm] [bug] ¶
修复了在 1.3.0b3 版本中通过 #4468 引入的连接迫切加载回归问题，其中跨越
with_polymorphic()创建连接选项的能力，进入使用RelationshipProperty.of_type()的多态子类，然后进一步沿着常规映射关系将失败，因为多态子类不会以加载策略可以定位的方式将自身添加到加载路径中。已进行调整以解决这种情况。参考：#5082
[orm] [bug] ¶
修复了 ORM flush 进程中的一个警告，当删除使用“version_id”功能的对象时，测试覆盖率未涵盖该警告。除非使用将“supports_sane_rowcount”标志设置为 False 的方言，否则通常无法访问此警告，但通常情况并非如此，但对于某些 MySQL 配置以及较旧的 Firebird 驱动程序以及可能的某些第三方方言，这种情况是可能的。
参考：#5068
[orm] [bug] ¶
修复了当
Query.group_by()用于查询时，连接迫切加载无法正确地将查询包装在子查询中的错误。当使用任何类型的限制结果方法（例如 DISTINCT、LIMIT、OFFSET）时，连接迫切加载会将行限制查询嵌入到子查询中，以便集合结果不受影响。由于某种原因，GROUP BY 的存在从未包含在此标准中，即使它具有与使用 DISTINCT 类似的效果。此外，此错误会阻止对大多数数据库平台的连接迫切加载查询完全使用 GROUP BY，这些平台禁止在查询中使用非聚合、非分组的列，因为连接迫切加载的附加列将不被数据库接受。参考：#5065
engine¶
sql¶
[sql] [usecase] ¶
使用
GenericFunction创建的函数现在可以通过将quoted_name构造分配给对象的 .name 元素来指定是否应使用或不使用引号呈现函数名称。在 1.3.4 之前，引号从未使用于函数名称，并且在 #4467 中引入了一些引号，但没有可用于强制混合大小写名称使用引号的方法。此外，当quoted_name构造用作名称时，它将在函数注册表中正确注册其小写名称，以便该名称继续通过func.注册表可用。另请参阅
参考：#5079
postgresql¶
mssql¶
[mssql] [bug] ¶
修复了时区感知
datetime值转换为字符串以用作DATETIMEOFFSET列的参数值时，会省略小数秒的问题。参考：#5045
tests¶
misc¶
[bug] [ext] ¶
修复了 sqlalchemy.ext.serializer 中的错误，如果唯一的
BindParameter对象同时存在于映射本身和查询的过滤器条件中，则它可能会与自身冲突，因为一侧将用于非反序列化版本，而另一侧将使用反序列化版本。在BindParameter中添加了类似于其“clone”方法的逻辑，该逻辑将在反序列化时唯一化参数名称，使其不会与其原始名称冲突。参考：#5086
1.3.12¶
发布日期：2019 年 12 月 16 日orm¶
[orm] [bug] ¶
修复了涉及
lazy="raise"策略的问题，其中 ORM 删除对象会为配置了 lazy="raise" 的简单“use-get”样式多对一关系引发异常。这与 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] ¶
修复了如果在 Core engine/connection 级别事务的“begin”失败（例如由于网络错误或数据库因某些事务性配方而被锁定），在
Session从连接池获取该连接并立即返回它的上下文中，ORMSession不会关闭连接，尽管此连接未存储在该Session的状态中。这将导致连接在垃圾回收中由连接池 weakref 处理程序清理，这是一个不首选的代码路径，在某些特殊配置中可能会在标准错误中发出错误。参考：#5034
sql¶
sqlite¶
[sqlite] [bug] ¶
修复了解决 SQLite 将 “numeric” affinity 分配给 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添加了访问器Query.is_single_entity()，它将指示此Query返回的结果将是 ORM 实体列表，还是实体或列表达式的元组。SQLAlchemy 希望在未来的版本中改进单个实体/元组的行为，以便该行为在前台明确，但此属性应有助于当前行为。感谢 Patrick Hayes 提供 pull request。参考：#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 错误，其中引用可选择项的 “secondary” 表将以某种方式引用本地主表，当关系相关的连接（通过
Query.join()或joinedload()生成）生成时，将别名应用于连接条件的双方。“本地”侧现在被排除在外。参考：#4974
engine¶
[engine] [bug] ¶
修复了在日志记录和错误报告中使用的参数 repr 的错误，该错误需要额外的上下文信息，以便区分针对单个语句的参数列表和参数列表的列表。这是因为“列表的列表”结构也可能表示单个参数列表，其中第一个参数本身就是一个列表，例如数组参数。引擎/连接现在会传入一个额外的布尔值，指明参数应该如何被解读。唯一期望使用数组作为参数的 SQLAlchemy 后端是 psycopg2，它使用 pyformat 参数，因此这个问题之前不太明显。然而，随着其他使用位置参数的驱动程序获得更多特性，支持这种区分就变得非常重要。此外，这也消除了 `parameter repr` 函数需要根据传入的参数结构进行猜测的需求。
参考链接： #4902
[engine] [bug] [postgresql] ¶
修复了
Inspector中的一个错误，该错误导致缓存键生成没有考虑以元组形式传入的参数，例如用于返回 PostgreSQL 方言的视图名称样式的元组。这会导致 inspector 为更具体的标准缓存过于通用。逻辑已调整为在缓存中包含每个关键字元素，因为每个参数都应适用于缓存，否则方言应绕过缓存装饰器。参考链接： #4955
sql¶
[sql] [usecase] ¶
为
JSON类型的表达式添加了新的访问器，以允许特定的数据类型访问和比较，涵盖字符串、整数、数值、布尔元素。这修订了在比较值时将值 CAST 为字符串的文档化方法，而是向 PostgreSQL、SQlite、MySQL 方言添加了特定功能，以便在所有情况下可靠地传递这些基本类型。另请参阅
参考链接： #4276
[sql] [usecase] ¶
text()构造现在支持“唯一”绑定参数，这些参数将在编译时动态地使其自身唯一化，从而允许多个具有相同绑定参数名称的text()构造组合在一起。参考链接： #4933
[sql] [bug] [py3k] ¶
更改了 Python 3 下
quoted_name构造的repr()以使用常规字符串 repr()，而不是通过 “backslashreplace” 转义运行它，这可能会产生误导。参考链接： #4931
schema¶
[schema] [usecase] ¶
添加了对“计算列”的 DDL 支持；这些是用于具有服务器计算值的列的 DDL 列规范，计算值可以在 SELECT 时（称为“虚拟”列）或在 INSERT 或 UPDATE 时（称为“存储”列）计算。为 Postgresql、MySQL、Oracle SQL Server 和 Firebird 建立了支持。感谢 Federico Caselli 在这方面做了大量工作。
参考链接： #4894
[schema] [bug] ¶
修复了一个错误，该错误发生在当表具有与普通列名重叠的列标签时，例如 “foo.id AS foo_id” 与 “foo.foo_id”，由于使用了
index=True或unique=True标志与"column_0_label"的默认命名约定结合使用，会导致提前为列生成._label属性，从而在检测到此重叠之前。当稍后使用._label生成绑定参数名称时，尤其是在 ORM 生成 UPDATE 语句的 WHERE 子句时，这将导致失败。通过使用备用的._label访问器进行 DDL 生成，修复了此问题，该访问器不会影响Column的状态。该访问器还绕过了键去重步骤，因为它对于 DDL 不是必需的，命名现在始终是"<tablename>_<columnname>"，在 DDL 中使用时没有任何后续的数字符号。参考链接： #4911
mysql¶
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 版本中，即当前的 master 开发分支，此问题不存在，这既是因为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 方言的“名称规范化”方法，该方法将这些方言的大小写不敏感的 UPPERCASE 约定转换为 SQLAlchemy 的大小写不敏感的 lowercase，使其不会自动将
quoted_name构造应用于在大小写转换下与其自身匹配的名称，许多非欧洲字符都是这种情况。无论如何，元数据结构中使用的所有名称都转换为quoted_name对象；此处的更改只会影响某些检查函数的输出。参考链接： #4931
[oracle] [bug] ¶
当在绑定参数中使用时，
NCHAR数据类型现在将绑定到cx_Oracle.FIXED_NCHARDBAPI 数据绑定，这提供了针对可变长度字符串的适当比较行为。以前，NCHAR数据类型将绑定到cx_oracle.NCHAR，这不是固定长度的；CHAR数据类型已经绑定到cx_Oracle.FIXED_CHAR，因此现在NCHAR绑定到cx_Oracle.FIXED_NCHAR是一致的。参考链接： #4913
tests¶
misc¶
1.3.10¶
发布日期：2019 年 10 月 9 日mssql¶
oracle¶
1.3.9¶
发布日期：2019 年 10 月 4 日orm¶
[orm] [bug] ¶
修复了 selectinload 加载器策略中的回归，该回归由 #4775（在 1.3.6 版本中发布）引起，其中 None 的多对一属性将不再由加载器填充。虽然由于 lazyloader 在 get 时填充 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] [usecase] ¶
为传递给
Table的对象不是SchemaItem对象的情况添加了显式错误消息，而不是解析为属性错误。参考链接： #4847
[sql] [bug] ¶
干扰绑定参数中 “pyformat” 或 “named” 格式的字符，即
%, (, )和空格字符，以及其他一些通常不希望出现的字符，对于使用匿名名称的bindparam()会被提前剥离，匿名名称通常是从命名列自动生成的，命名列本身在其名称中包含这些字符，并且不使用.key，因此它们不会干扰 SQLAlchemy 编译器对字符串格式化的使用或驱动程序级别对参数的解析，这两者都可以在修复之前得到证明。此更改仅适用于内部生成和使用的匿名参数名称，而不适用于最终用户定义的名称，因此此更改应该对任何现有代码都没有影响。尤其适用于 psycopg2 驱动程序，该驱动程序不会引用特殊参数名称，但也会剥离前导下划线以适应 Oracle（但尚未剥离前导数字，因为某些匿名参数当前完全基于数字/下划线）；在任何情况下，Oracle 都会继续引用包含特殊字符的参数名称。参考链接： #4837
sqlite¶
mssql¶
[mssql] [bug] ¶
为应用于 “use” 语句的模式名称添加了标识符引号，当在
Table中使用 SQL Server 多部分模式名称（该表正在被反射）以及Inspector方法（例如Inspector.get_table_names()）时会调用该语句；这适用于数据库名称中的特殊字符或空格。此外，如果当前数据库与正在传递的目标所有者数据库名称匹配，则不会发出 “use” 语句。参考链接： #4883
oracle¶
[oracle] [usecase] ¶
如果使用 Oracle 12.2 或更高版本，并且未设置
create_engine.max_identifier_length参数，则 Oracle 方言现在会发出警告。在这种特定情况下，版本默认为 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¶
1.3.8¶
发布日期：2019 年 8 月 27 日orm¶
[orm] [usecase] ¶
添加了对使用 Python pep-435 枚举对象作为值的
Enum数据类型的支持，以用作 ORM 映射的主键列。由于这些值本质上是不可排序的（ORM 对主键的要求），因此在类型系统中添加了一个新的TypeEngine.sort_key_function属性，该属性允许任何 SQL 类型为其类型的 Python 对象实现排序，工作单元会查询该排序。Enum类型然后使用给定枚举的数据库值来定义此属性。排序方案也可以通过将可调用对象传递给Enum.sort_key_function参数来重新定义。拉取请求由 Nicolas Caniart 提供。参考链接： #4285
[orm] [bug] ¶
修复了由于内部上下文字典中的 mapper/relationship 状态，导致
Load对象不可 pickle 化的错误。这些对象现在使用与加载器选项系统中其他长期可序列化的元素类似的技术转换为可 pickle 化的对象。参考链接： #4823
engine¶
[engine] [feature] ¶
添加了新参数
create_engine.hide_parameters，当设置为 True 时，将导致不再记录 SQL 参数，也不会在StatementError对象的字符串表示形式中呈现 SQL 参数。参考链接： #4815
[engine] [bug] ¶
修复了一个问题，即如果首次连接时发生的方言 “初始化” 过程遇到意外异常，则初始化过程将无法完成，并且在后续连接尝试中不再尝试，从而使方言在未初始化或部分初始化的状态下，处于需要根据实时连接检查建立的参数范围内。事件系统中的 “invoke once” 逻辑已重新设计，以使用新的私有 API 功能来适应这种情况，这些功能建立了一个 “exec once” 钩子，该钩子将继续允许初始化程序在后续连接上触发，直到它完成而没有引发异常。这不会影响事件系统中现有
once=True标志的行为。参考链接： #4807
postgresql¶
[postgresql] [usecase] ¶
添加了对 CHECK 约束反射的支持，该约束包含特殊的 PostgreSQL 限定符 “NOT VALID”，该限定符可能存在于添加到现有表的 CHECK 约束中，并指示它们不应用于表中的现有数据。
Inspector.get_check_constraints()返回的 CHECK 约束的 PostgreSQL 字典可能包含一个额外的条目dialect_options，如果检测到此符号，则该条目中将包含一个条目"not_valid": True。拉取请求由 Bill Finn 提供。参考链接： #4824
[postgresql] [bug] ¶
修改了刚刚添加的对 1.3.7 中为 #4623 添加的 psycopg2 “execute_values()” 功能的支持方法。该方法依赖于一个正则表达式，该正则表达式无法匹配更复杂的 INSERT 语句，例如包含子查询的语句。新方法完全匹配呈现为 VALUES 子句的字符串。
参考链接： #4623
[postgresql] [bug] ¶
修复了当对
array对象使用时，Postgresql 运算符（例如Comparator.contains()和Comparator.contained_by()）对于非整数值无法正常运行的错误，这是由于错误的 assert 语句导致的。参考链接： #4822
sqlite¶
1.3.7¶
发布日期：2019 年 8 月 14 日orm¶
[orm] [bug] ¶
修复了由多对一逻辑的新 selectinload 引起的回归，其中如果父对象上给定键值不存在相关对象，则不基于真实外键的 primaryjoin 条件将导致 KeyError。
参考链接： #4777
[orm] [bug] ¶
修复了当查询结合使用基于表达式的 “offset” 时，使用
Query.first()或切片表达式会引发 TypeError 错误的 bug，这是因为针对 “offset” 的 “or” 条件判断预期它是一个整数或 None，而不是 SQL 表达式。参考链接: #4803
sql¶
[sql] [错误] ¶
修复了
Index对象在包含无法解析为特定列的功能性表达式，并结合基于字符串的列名时，会无法正确初始化其内部状态，从而导致 DDL 编译失败的问题。参考链接: #4778
[sql] [错误] ¶
修复了
TypeEngine.column_expression()方法不会应用于 UNION 或其他_selectable.CompoundSelect内部的后续 SELECT 语句的 bug，即使这些 SELECT 语句是在语句的最顶层渲染的。新的逻辑现在区分了渲染列表达式（列表中所有 SELECT 都需要）与收集结果行返回的数据类型（只有第一个 SELECT 需要），这两者之间的区别。参考链接: #4787
[sql] [错误] ¶
修复了当 SELECT 构造的副本更改其状态，导致其列列表发生变化时，内部克隆 SELECT 构造可能导致键错误的问题。观察到这种情况发生在某些 ORM 场景中，这些场景可能是 1.3 及以上版本独有的，因此部分是回归修复。
参考链接: #4780
postgresql¶
mysql¶
[mysql] [用例] ¶
将保留字 ARRAY 和 MEMBER 添加到 MySQL 保留字列表中，因为 MySQL 8.0 现在已将它们设为保留字。
参考链接: #4783
[mysql] [错误] ¶
当为 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] [错误] ¶
为上游 MySQL 8 问题添加了另一个修复，其中外键约束反射中错误地报告了区分大小写的表名，这是为 #4344 首次添加的修复的扩展，该修复影响了区分大小写的列名。新问题出现在 MySQL 8.0.17 中，因此 88718 修复的通用逻辑仍然有效。
另请参阅
参考链接: #4751
sqlite¶
[sqlite] [错误] ¶
支持 json 的方言本应在 create_engine() 级别接受参数
json_serializer和json_deserializer，但是 SQLite 方言将其称为_json_serializer和_json_deserilalizer。名称已更正，旧名称将被接受并发出更改警告，并且这些参数现在被记录为create_engine.json_serializer和create_engine.json_deserializer。参考链接: #4798
[sqlite] [错误] ¶
修复了 SQLite 方言中使用 “PRAGMA table_info” 意味着当未给出模式名称且表在基本模式中不存在时，用于检测表存在、表列列表和外键列表的反射功能将默认为任何附加数据库中的任何表的 bug。该修复显式地为 ‘main’ 模式运行 PRAGMA，然后在 ‘main’ 返回无行时为 ‘temp’ 模式运行 PRAGMA，以维护 “无模式” 命名空间中表 + 临时表的行为，以及 “模式” 命名空间中仅附加表的行为。
参考链接: #4793
mssql¶
[mssql] [用例] ¶
为 SQL Server 添加了新的
try_cast()构造，它发出 “TRY_CAST” 语法。Pull request 由 Leonel Atencio 提供。参考链接: #4782
misc¶
1.3.6¶
发布日期：2019年7月21日orm¶
[orm] [特性] ¶
添加了新的加载器选项方法
Load.options()，它允许分层构建加载器选项，以便可以将许多子选项应用于特定路径，而无需多次调用defaultload()。感谢 Alessio Bogon 的想法。参考链接: #4736
[orm] [性能] ¶
在 #4340 中应用于 selectin 加载的优化，即不需要 JOIN 来急切加载相关项，现在也应用于多对一关系，以便仅查询相关表以获得简单的连接条件。在这种情况下，相关项是根据父对象集合中外键列的值查询的；如果这些列被延迟加载或未加载到任何父对象上，则加载器将回退到 JOIN 方法。
参考链接: #4775
[orm] [错误] ¶
修复了由 #4365 引起的回归，其中从实体到自身的连接在不使用别名的情况下不再引发信息丰富的错误消息，而是断言失败。信息丰富的错误条件已恢复。
参考链接: #4773
[orm] [错误] ¶
修复了
_ORMJoin.join()方法（这是一个未在内部使用的 ORM 级别方法，它公开了Query.join()的内部处理过程）没有正确传播full和outerjoin关键字参数的问题。Pull request 由 Denis Kataev 提供。参考链接: #4713
[orm] [错误] ¶
修复了指定
uselist=True的多对一关系在主键更改期间，当需要更改相关列时，无法正确更新的 bug。参考链接: #4772
[orm] [错误] ¶
修复了对于与 “dynamic” 关系一起使用的多对一或一对一检测（这是一种无效配置），如果该关系配置了
uselist=True，则检测会失败，无法引发异常的 bug。当前的修复方案是发出警告，而不是引发异常，因为否则会向后不兼容，但是在未来的版本中，它将引发异常。参考链接: #4772
[orm] [错误] ¶
修复了针对尚未存在的映射属性创建的同义词（当它在映射器配置之前引用 backref 时就是这种情况），在尝试测试其上最终不存在的属性时（当类通过 Sphinx autodoc 运行时会发生这种情况）会引发递归错误的 bug，因为同义词的未配置状态会使其陷入找不到属性的循环中。
参考链接: #4767
engine¶
[engine] [错误] ¶
修复了使用反射函数（如
MetaData.reflect()）和应用了执行选项的Engine对象会失败的 bug，因为生成的OptionEngine代理对象未能包含反射例程中使用的.engine属性。参考链接: #4754
sql¶
[sql] [错误] ¶
调整了
Enum的初始化，以最大限度地减少它调用给定 PEP-435 枚举对象的.__members__属性的频率，以适应此属性调用成本高昂的情况，例如某些流行的第三方枚举库的情况。参考链接: #4758
[sql] [错误] [postgresql] ¶
修复了
array_agg构造与FunctionElement.filter()结合使用时，不会产生与数组索引运算符结合使用的正确运算符优先级的问题。参考链接: #4760
[sql] [错误] ¶
修复了一个不太可能发生的问题，即 unions 和其他
_selectable.CompoundSelect对象的 “相应列” 例程在某些重叠列的情况下可能会返回错误的列，因此如果底层select()构造以前在其他类似类型的例程中使用过，则可能会影响某些正在使用集合操作的 ORM 操作，原因是缓存值未被清除。参考链接: #4747
postgresql¶
mysql¶
[mysql] [错误] ¶
修复了当
nullable=True时，为TIMESTAMP数据类型渲染 “NULL” 的特殊逻辑在列的数据类型为TypeDecorator或Variant时不起作用的 bug。该逻辑现在确保它可以解包到原始的TIMESTAMP，以便在请求时正确渲染此特殊情况的 NULL 关键字。参考链接: #4743
[mysql] [错误] ¶
增强了 MySQL/MariaDB 版本字符串解析，以适应 “MariaDB” 一词嵌入在其他字母数字字符（如 “MariaDBV1”）中的异构 MariaDB 版本字符串。此检测对于正确适应 MySQL 和 MariaDB 之间拆分的 API 功能（如 “transaction_isolation” 系统变量）至关重要。
参考链接: #4624
sqlite¶
mssql¶
1.3.5¶
发布日期：2019年6月17日orm¶
[orm] [错误] ¶
修复了一系列与超过两层深度的连接表继承相关的 bug，这些 bug 与主键值的修改相结合，其中这些主键列也以外键关系链接在一起，这在连接表继承中很常见。三层继承层次结构中的中间表现在将获得其 UPDATE，如果只有主键值已更改且 passive_updates=False（例如，外键约束未被强制执行），而在之前它将被跳过；类似地，对于 passive_updates=True（例如，ON UPDATE CASCADE 生效），第三层表将不会收到 UPDATE 语句，就像之前的情况一样，因为 CASCADE 已经修改了它，这将导致失败。在一个相关的问题中，当父对象的主键被修改时，即使该父对象是链接父类的子类，链接到连接继承层次结构的中间表的主键上的三层继承层次结构的关系，也会正确地更新其外键列，而在之前这些类不会被计算在内。
参考链接: #4723
[orm] [错误] ¶
修复了
Mapper.all_orm_descriptors访问器会为声明式__mapper__键下的Mapper本身返回条目的 bug，而这并不是描述符。InspectionAttr对象上存在的.is_attribute标志现在被咨询，该标志也已被修改为对于关联代理为True，因为它之前错误地设置为 False。参考链接: #4729
[orm] [错误] ¶
修复了
Query.join()中的回归，其中如果先前已对同一实体进行连接，则aliased=True标志将无法正确地将子句适配应用于过滤器条件。这是因为适配器放置的顺序错误。顺序已颠倒，以便最近的aliased=True调用的适配器优先，就像在 1.2 及更早版本中一样。这破坏了 “elementtree” 示例以及其他内容。参考链接: #4704
[orm] [错误] [py3k] ¶
将
getfullargspec()的 Python 兼容性例程替换为 Python 3.3 中的完全供应商版本。最初，Python 在 Python 3.8 alpha 版本中为此函数发出了弃用警告。虽然此更改已被还原，但观察到 Python 3 中getfullargspec()的实现速度要慢一个数量级，从 3.4 系列开始，它已针对Signature重写。虽然 Python 计划改进这种情况，但 SQLAlchemy 项目目前正在使用简单的替换来避免任何未来的问题。参考链接: #4674
[orm] [错误] ¶
重做了
AliasedClass使用的属性机制，不再依赖于在包装类的 MRO 上调用__getattribute__，而是改为在包装类上使用 getattr() 正常解析属性，然后解包/适配该属性。这允许映射类上更广泛的属性样式，包括特殊的__getattr__()方案；但它也使代码更简单，更具弹性。参考链接: #4694
sql¶
[sql] [错误] ¶
解决了一系列由使用
literal_column`()构造引起的引号问题。当此构造通过子查询 “代理” 并通过与其文本匹配的标签引用时，即使Label中的字符串是使用quoted_name`构造设置的，标签也不会应用引号规则。不将引号应用于Label的文本是一个 bug，因为此文本严格来说是 SQL 标识符名称，而不是 SQL 表达式，并且与literal_column()不同，字符串不应已嵌入引号，它可能会应用于后者。非标签literal_column()的现有行为在子查询外部按原样传播，以便帮助手动引号方案，尽管尚不清楚是否可以在任何情况下为此类构造生成有效的 SQL。参考链接: #4730
postgresql¶
[postgresql] [用例] ¶
增加了在反射 PostgreSQL 索引时对列排序标志的支持，包括 ASC、DESC、NULLSFIRST、NULLSLAST。还为反射系统添加了此功能，该功能可以在未来的版本中应用于其他方言。Pull request 由 Eli Collins 提供。
参考链接: #4717
[postgresql] [错误] ¶
修复了 PostgreSQL 方言无法正确反射没有成员的 ENUM 数据类型的 bug，为
get_enums()调用返回包含None的列表，并在反射具有此类数据类型的列时引发 TypeError。检查现在返回一个空列表。参考链接: #4701
mysql¶
1.3.4¶
发布日期：2019年5月27日orm¶
[orm] [错误] ¶
修复了
AttributeEvents.active_history标志不会为通过AttributeEvents.propagate标志传播到子类的事件监听器设置的问题。此 bug 一直存在于AttributeEvents系统的整个生命周期中。参考链接: #4695
[orm] [错误] ¶
修复了回归，其中新的关联代理系统在混合属性使用
@hybrid_property.expression装饰器返回备用 SQL 表达式，或者当混合属性在表达式级别返回任意PropComparator时，仍然不会代理这些混合属性。这涉及到进一步概括用于检测QueryableAttribute级别代理的对象类型的启发式方法，以更好地检测描述符最终是服务于映射类还是列表达式。参考链接: #4690
[orm] [错误] ¶
对声明式类映射过程应用了映射器 “configure mutex”，以防止在动态模块导入方案仍在配置相关类的映射器时使用映射器可能发生的竞争。这并不能防止所有可能的竞争条件，例如，如果并发导入尚未遇到依赖类，但它可以防止 SQLAlchemy 声明式过程中的尽可能多的竞争条件。
参考链接: #4686
[orm] [错误] ¶
现在，对于瞬态对象在
Session中已经瞬态的情况下，使用Session.merge()合并到会话中的情况，会发出警告。这会警告对象通常会被双重插入的情况。参考链接: #4647
[orm] [错误] ¶
修复了新的关系 m2o 比较逻辑在与持久化为 NULL 并且在映射实例中处于未获取状态的属性进行比较时，在 改进多对一查询表达式的行为 中首次引入的回归。由于该属性没有显式默认值，因此在持久设置中访问时，它需要默认为 NULL。
参考链接: #4676
引擎¶
sql¶
[sql] [错误] ¶
修复了
GenericFunction类不经意地将自己注册为命名函数之一的问题。感谢 Adrien Berchet 提交的 Pull Request。参考链接: #4653
[sql] [错误] ¶
修复了布尔列的双重否定无法重置 “NOT” 运算符的问题。
参考链接: #4618
[sql] [错误] ¶
正在迁移
GenericFunction命名空间，以便以不区分大小写的方式查找函数名称，因为 SQL 函数不会因大小写差异而冲突，用户定义的函数或存储过程也不会发生这种情况。现在使用不区分大小写的方案查找使用GenericFunction声明的函数，但是支持弃用情况，允许存在两个或多个具有相同名称但大小写不同的GenericFunction对象，这将导致对该特定名称进行区分大小写的查找，同时在函数注册时发出警告。感谢 Adrien Berchet 在这个复杂功能上所做的大量工作。参考链接: #4569
postgresql¶
mysql¶
mssql¶
misc¶
1.3.3¶
发布日期: 2019 年 4 月 15 日orm¶
[orm] [错误] ¶
修复了 1.3 版本中引入的新 “ambiguous FROMs” 查询逻辑中的回归问题，该问题在 Query.join() handles ambiguity in deciding the “left” side more explicitly 中有描述，其中
Query使用Query.select_from()显式地将实体放置在 FROM 子句中，并且还使用Query.join()连接到该实体，如果该实体在额外的连接中使用，则稍后会引起 “ambiguous FROM” 错误，因为该实体在Query的 “from” 列表中出现两次。此修复通过将独立实体折叠到它已参与的连接中来解决此歧义，其方式与最终在呈现 SELECT 语句时发生的方式相同。参考链接: #4584
[orm] [错误] ¶
调整了
Query.filter_by()方法，使其不对多个条件内部调用and()，而是将其作为一系列条件传递给Query.filter()，而不是单个条件。这允许Query.filter_by()遵循Query.filter()对可变数量子句的处理，包括列表为空的情况。在这种情况下，Query对象将没有.whereclause，这允许后续的 “no whereclause” 方法（如Query.select_from()）表现一致。参考链接: #4606
postgresql¶
mssql¶
misc¶
[错误] [连接池] ¶
修复了由于弃用
Pool的 “use_threadlocal” 标志而导致的行为回归，其中SingletonThreadPool不再使用此选项，这会导致当在事务上下文中多次使用同一个Engine进行连接或隐式执行时，会发生 “return 时回滚” 逻辑，从而取消事务。虽然这不是使用引擎和连接的推荐方式，但这仍然是一个令人困惑的行为更改，因为当使用SingletonThreadPool时，无论在同一线程中的同一引擎上执行了其他什么操作，事务都应保持打开状态。use_threadlocal标志仍然被弃用，但是SingletonThreadPool现在实现了其自身版本的相同逻辑。参考链接: #4585
[错误] [ext] ¶
修复了在使用
copy.copy()或copy.deepcopy()在MutableList上时，由于 Python pickle 和 copy 在__getstate__()和__setstate__()关于列表的使用方式上的不一致，会导致列表中的项目被复制的问题。为了解决这个问题，必须向MutableList添加__reduce_ex__方法。为了保持与基于__getstate__()的现有 pickles 的向后兼容性，__setstate__()方法也保留了下来；测试套件断言针对旧版本的类制作的 pickles 仍然可以被 pickle 模块反序列化。参考链接: #4603
1.3.2¶
发布日期: 2019 年 4 月 2 日orm¶
[orm] [错误] [ext] ¶
恢复了对普通 Python 描述符（例如
@property对象）的实例级别支持，结合关联代理，如果代理对象完全不在 ORM 范围内，则将其归类为 “ambiguous”，但直接代理。对于类级别访问，基本的类级别 ``__get__()`` 现在直接返回AmbiguousAssociationProxyInstance，而不是引发其异常，这是对之前返回AssociationProxy本身的行为的最接近的近似。还改进了这些对象的字符串化，使其更能描述当前状态。[orm] [错误] ¶
修复了当别名目标用作
Select.correlate_except()子查询的目标，并在column_property()内部使用时，使用with_polymorphic()或其他别名构造不会正确适配的错误。这需要修复子句适配机制，以正确处理出现在 “correlate except” 列表中的 selectable，其方式与出现在 “correlate” 列表中的 selectable 类似。这最终是一个相当根本的错误，已经存在很长时间了，但很难遇到它。参考链接: #4537
[orm] [错误] ¶
修复了回归问题，当尝试将关系选项链接到 AliasedClass 而不使用
PropComparator.of_type()时，本应引发新的错误消息，但实际上却引发了AttributeError。请注意，在 1.3 版本中，不再允许从普通 mapper 关系创建到AliasedClass的选项路径，而不使用PropComparator.of_type()。参考链接: #4566
sql¶
[sql] [错误] [文档] ¶
感谢 TypeEngine methods bind_expression, column_expression work with Variant, type-specific types，我们不再需要依赖直接子类化方言特定类型的配方，
TypeDecorator现在可以处理所有情况。此外，上述更改使直接子类化基本 SQLAlchemy 类型不太可能按预期工作，这可能会产生误导。文档已更新为使用TypeDecorator来处理这些示例，包括 PostgreSQL “ArrayOfEnum” 示例数据类型，并且已删除了对 “直接子类化类型” 的直接支持。参考链接: #4580
postgresql¶
[postgresql] [功能] ¶
为 psycopg2 方言添加了对无参数连接 URL 的支持，这意味着可以将 URL 作为
"postgresql+psycopg2://"传递给create_engine()，而无需其他参数来指示传递给 libpq 的空 DSN，这表示连接到 “localhost”，不提供用户名、密码或数据库。感谢 Julian Mehnle 提交的 Pull Request。参考链接: #4562
[postgresql] [错误] ¶
修改了
Select.with_for_update.of参数，以便在传递 join 或其他组合 selectable 时，将从中筛选出单独的Table对象，从而允许将 join() 对象传递给该参数，这通常在使用 ORM 的连接表继承时发生。感谢 Raymond Lu 提交的 Pull Request。参考链接: #4550
1.3.1¶
发布日期: 2019 年 3 月 9 日orm¶
mssql¶
1.3.0¶
发布日期: 2019 年 3 月 4 日orm¶
[orm] [功能] ¶
Query.get()方法现在可以接受属性键和值的字典，作为指示要加载的主键值的方法；对于复合主键尤其有用。感谢 Sanjana S. 提交的 Pull Request。参考链接: #4316
[orm] [功能] ¶
现在可以将 SQL 表达式分配给 ORM flush 的主键属性，其方式与 Embedding SQL Insert/Update Expressions into a Flush 中描述的普通属性相同，其中表达式将被评估，然后使用 RETURNING 返回给 ORM，或者在 pysqlite 的情况下，使用 cursor.lastrowid 属性工作。需要支持 RETURNING 的数据库（例如 Postgresql、Oracle、SQL Server）或 pysqlite。
参考链接: #3133
engine¶
[引擎] [功能] ¶
修改了
StatementError在字符串化时的格式。每个错误详细信息都分布在多个换行符上，而不是在单行上隔开。此外，SQL 表示现在字符串化 SQL 语句，而不是使用repr()，以便换行符按原样呈现。感谢 Nate Clark 提交的 Pull Request。参考链接: #4500
sql¶
schema¶
[schema] [功能] ¶
添加了新的参数
Table.resolve_fks和MetaData.reflect.resolve_fks，当设置为 False 时，将禁用在ForeignKey对象中遇到的相关表的自动反射，这既可以减少省略表的 SQL 开销，又可以避免由于数据库特定原因而无法反射的表。即使两个表的反射是单独发生的，同一MetaData集合中存在的两个Table对象仍然可以相互引用。参考链接: #4517
1.3.0b3¶
发布日期: 2019 年 2 月 8 日orm¶
[orm] [错误] ¶
改进了
with_polymorphic()与加载器选项结合使用时的行为，特别是通配符操作以及load_only()。将更准确地定位多态对象，以便实体上的列级选项能够正确生效。此问题是 #4468 中修复的同类问题的延续。参考链接: #4469
orm declarative¶
[orm] [声明式] [错误] ¶
添加了一些辅助异常，当基于
AbstractConcreteBase、DeferredReflection或AutoMap的映射在使用前尚未准备就绪时，将调用这些异常，其中包含关于类的描述性信息，而不是陷入其他信息量较少的故障模式。参考链接: #4470
sql¶
[sql] [错误] ¶
完全移除了直接作为
select()或Query对象组件传递的字符串被自动强制转换为text()构造的行为；现在发出的警告是 ArgumentError，或者在 order_by() / group_by() 的情况下是 CompileError。自 1.0 版本以来，这已经发出了警告，但是它的存在继续引起人们对误用此行为的担忧。请注意，已经发布了关于 order_by() / group_by() 的公共 CVE，这些 CVE 已通过此提交解决：CVE-2019-7164 CVE-2019-7548
参考链接: #4481
[sql] [错误] ¶
如果
Function名称（通常但不一定从sqlalchemy.sql.expression.func构造生成）在编译时包含非法字符（例如空格或标点符号），则会对其应用引号。名称仍然像以前一样被视为不区分大小写，这意味着如果名称包含大写或混合大小写字符，仅凭这一点不会触发引号。为了向后兼容性，目前保持了不区分大小写。参考链接: #4467
[sql] [错误] ¶
为关键 DDL 短语添加了 “SQL 短语验证”，这些短语被接受为纯字符串，包括
ForeignKeyConstraint.on_delete、ForeignKeyConstraint.on_update、ExcludeConstraint.using、ForeignKeyConstraint.initially，这些区域仅期望一系列 SQL 关键字。任何暗示短语需要加引号的非空格字符都将引发CompileError。此更改与作为 #4481 一部分提交的一系列更改相关。参考链接: #4481
postgresql¶
tests¶
misc¶
1.3.0b2¶
发布日期: 2019 年 1 月 25 日general¶
[general] [更改] ¶
整个库进行了一项重大更改，确保所有被标记为已弃用或过时的对象、参数和行为在被调用时都会发出
DeprecationWarning警告。由于 Python 3 解释器现在默认显示弃用警告，并且基于 tox 和 pytest 等工具的现代测试套件也倾向于显示弃用警告，因此此更改应使注意哪些 API 功能已过时变得更容易。此项更改的主要理由是，以便最终能够在不久的将来移除那些长期弃用但仍在实际应用中使用的功能；其中最明显的例子是SessionExtension和MapperExtension类，以及一些其他的预事件扩展钩子，它们自 0.7 版本以来已被弃用，但仍保留在库中。另一个原因是，几个主要的长期行为也将被弃用，包括 threadlocal 引擎策略、convert_unicode 标志和非主映射器。参考链接: #4393
orm¶
[orm] [feature] ¶
实现了一项新功能，
AliasedClass构造现在可以用作relationship()的目标。这使得“非主映射器”的概念不再必要，因为AliasedClass更容易配置，并自动继承映射类的所有关系，并保留加载器选项正常工作的功能。参考链接: #4423
[orm] [feature] ¶
添加了新的
MapperEvents.before_mapper_configured()事件。此事件通过每个映射器的事件来补充其他“配置”阶段的映射器事件，该事件在每个Mapper对象配置步骤之前接收它，并且还可以使用新的返回值interfaces.EXT_SKIP来阻止或延迟特定Mapper对象的配置。请参阅文档链接以获取示例。参考链接: #4397
[orm] [change] ¶
添加了一个新函数
close_all_sessions()，它接管了Session.close_all()方法的任务，该方法现在已被弃用，因为它作为类方法容易引起混淆。感谢 Augustin Trancart 提供的拉取请求。参考链接: #4412
[orm] [bug] ¶
修复了长期存在的问题，即当删除重复项之一时（这是在一个语句中交换两个对象的副作用），重复的集合成员会导致反向引用删除成员与其父对象之间的关联。
参考链接: #1103
[orm] [bug] ¶
扩展了作为 #3287 的一部分首次进行的修复，其中针对使用通配符的子类进行的加载器选项会扩展自身，以包括将通配符应用于超类上的属性，以及应用于“绑定”加载器选项，例如在
Load(SomeSubClass).load_only('foo')这样的表达式中。作为SomeSubClass父类一部分的列也将以与使用未绑定选项load_only('foo')相同的方式排除。参考链接: #4373
[orm] [bug] ¶
改进了 ORM 在加载器选项遍历区域发出的错误消息。这包括提前检测到不匹配的加载器策略，以及更清晰地解释这些策略为何不匹配。
参考链接: #4433
[orm] [bug] ¶
现在，集合的“remove”事件在通过
collection.remove()方法移除项目的情况下，在项目被移除之前调用，这与大多数其他形式的集合项目移除（例如__delitem__、__setitem__下的替换）的行为一致。对于pop()方法，remove 事件仍然在操作之后触发。[orm] [bug] [engine] ¶
通过
Query.get_execution_options()、Connection.get_execution_options()、Engine.get_execution_options()和Executable.get_execution_options()，为 Core 和 ORM 添加了执行选项的访问器。感谢 Daniel Lister 提供的 PR。参考链接: #4464
[orm] [bug] ¶
修复了由于 #3423 导致的关联代理中的问题，该问题导致在关联代理中无法使用带有混合属性的自定义
PropComparator对象，例如dictlike-polymorphic示例中演示的对象。#3423 中添加的严格性已放宽，并添加了额外的逻辑来适应链接到自定义混合的关联代理。参考链接: #4446
[orm] [bug] ¶
为
synonym()属性实现了.get_history()方法，这也意味着AttributeState.history的可用性。以前，尝试通过同义词访问属性历史记录会引发AttributeError。参考链接: #3777
orm declarative¶
[bug] [orm declarative] ¶
为
ColumnProperty添加了__clause_element__()方法，当在类声明中的约束或其他面向列的场景中使用尚未完全声明的列或延迟属性时，它可以使声明式映射类稍微友好一些，但这仍然不能在开放式表达式中工作；如果收到TypeError，请优先调用ColumnProperty.expression属性。参考链接: #4372
engine¶
sql¶
[sql] [feature] ¶
修改了
AnsiFunction类，即常见 SQL 函数（如CURRENT_TIMESTAMP）的基础类，以接受像常规即席函数一样的位置参数。这是为了适应某些特定后端上的许多此类函数接受诸如“小数秒”精度之类的参数的情况。如果函数是使用参数创建的，则它会呈现括号和参数。如果没有参数，则编译器会生成非括号形式。参考链接: #4386
[sql] [change] ¶
create_engine.convert_unicode和String.convert_unicode参数已被弃用。这些参数是在大多数 Python DBAPI 对 Python Unicode 对象几乎没有支持的时候构建的，并且 SQLAlchemy 需要承担起在整个系统中以高性能的方式在 Unicode 和字节串之间编组数据和 SQL 字符串的非常复杂的任务。得益于 Python 3，DBAPI 被迫适应 Unicode 感知的 API，如今 SQLAlchemy 支持的所有 DBAPI 都原生支持 Unicode，包括在 Python 2 上，从而使这个长期存在且非常复杂的功能最终（大部分）被移除。当然，在 Python 2 的边缘情况下，SQLAlchemy 仍然需要处理 Unicode，但这些都是自动处理的；在现代使用中，应该不需要最终用户与这些标志进行交互。参考链接: #4393
mssql¶
[mssql] [bug] ¶
Unicode和UnicodeText数据类型的literal_processor现在在字面字符串表达式前面呈现一个N字符，这是 SQL Server 在 SQL 表达式中呈现 Unicode 字符串值时所要求的。参考链接: #4442
misc¶
1.3.0b1¶
发布日期：2018 年 11 月 16 日orm¶
[orm] [feature] ¶
添加了新功能
Query.only_return_tuples()。使Query对象无条件地返回键控元组对象，即使查询是针对单个实体也是如此。感谢 Eric Atkin 提供的拉取请求。此更改也已向后移植到：1.2.5
[orm] [feature] ¶
为
Session.bulk_save_objects()方法添加了新标志Session.bulk_save_objects.preserve_order，默认为 True。当设置为 False 时，给定的映射将按每个对象类型分组为插入和更新，以便有更多机会批量处理常见操作。感谢 Alessandro Cucci 提供的拉取请求。[orm] [feature] ¶
“selectin”加载策略现在在简单的一对多加载的情况下省略 JOIN，在这种情况下，它改为仅从相关表加载，依靠相关表的外键列来匹配父表中的主键。可以通过将
relationship.omit_join标志设置为 False 来禁用此优化。非常感谢 Jayson Reis 为此付出的努力。参考链接: #4340
[orm] [feature] ¶
为
InstanceState类添加了.info字典，该类是通过在映射对象上调用inspect()得到的对象。参考链接: #4257
[orm] [bug] ¶
修复了在
Query.join()以及Query.select_entity_from()中使用Lateral构造时，不会将子句适配应用于连接右侧的错误。“lateral”引入了连接右侧可关联的用例。以前，未考虑对此子句的适配。请注意，仅在 1.2 版本中，由Query.subquery()引入的可选对象仍然由于 #4304 而未被适配；可选对象需要由select()函数生成，才能作为“lateral”连接的右侧。此更改也已向后移植到：1.2.12
参考链接: #4334
[orm] [bug] ¶
修复了关于 passive_deletes=”all” 的问题，其中即使在从其父集合中删除对象后，对象的外键属性仍保留其值。以前，即使 passive_deletes 指示不应修改，工作单元也会将其设置为 NULL。
参考链接: #3844
[orm] [bug] ¶
改进了关系绑定的多对一对象表达式的行为，使得对相关对象上的列值的检索现在可以抵抗对象从其父
Session分离，即使属性已过期。InstanceState中的新功能用于记忆特定列属性在其过期之前的最后一个已知值，以便表达式在对象同时分离和过期时仍可以评估。还使用现代属性状态功能改进了错误条件，以便根据需要生成更具体的消息。另请参阅
参考链接: #4359
[orm] [bug] [mysql] [postgresql] ¶
ORM 现在在某些情况下，在与连接的迫切加载结合呈现的子查询中，将“FOR UPDATE”子句加倍，因为已观察到 MySQL 不会锁定来自子查询的行。这意味着查询呈现了两个 FOR UPDATE 子句；请注意，在某些后端（如 Oracle）上，子查询上的 FOR UPDATE 子句会被默默忽略，因为它们是不必要的。此外，在使用主要用于 PostgreSQL 的“OF”子句的情况下，FOR UPDATE 仅在内部子查询中使用时呈现，以便可以选择目标为 SELECT 语句中的表。
参考链接: #4246
[orm] [bug] ¶
重构了
Query.join()，以进一步阐明构建连接的各个组件。此重构为Query.join()添加了能力，以便在 FROM 列表中有多个元素或查询针对多个实体时，确定最合适的连接“左侧”。如果多个 FROM/实体匹配，则会引发错误，要求指定 ON 子句以解决歧义。特别是，这针对了我们在 #4363 中看到的回归问题，但它也具有普遍用途。Query.join()中的代码路径现在更容易理解，并且错误情况在操作的早期阶段就更具体地确定了。参考链接: #4365
[orm] [bug] ¶
修复了
Query中的长期存在的问题，其中标量子查询（例如由Query.exists()、Query.as_scalar()和来自Query.statement的其他派生项生成）在新Query中使用时无法正确适配，而新Query需要实体适配，例如当查询被转换为联合或 from_self() 等时。此更改从select()对象中删除了“no adaptation”注释，该对象由Query.statement访问器生成。参考链接: #4304
[orm] [bug] ¶
当主键值在 Python 3 下的 ORM 刷新期间在 Python 中不可排序时，例如没有
__lt__()方法的Enum；通常 Python 3 在这种情况下会引发TypeError。刷新过程按 Python 中的主键对持久对象进行排序，因此值必须是可排序的。参考链接: #4232
[orm] [bug] ¶
删除了
MappedCollection类使用的集合转换器。此转换器仅用于断言传入的字典键与其相应的对象匹配，并且仅在批量设置操作期间使用。转换器可能会干扰自定义验证器或AttributeEvents.bulk_replace()监听器，该监听器想要进一步转换传入的值。删除了当传入键与值不匹配时此转换器将引发的TypeError；批量赋值期间的传入值将键入到其值生成的键，而不是字典中显式存在的键。总体而言，@converter 已被作为
AttributeEvents.bulk_replace()事件处理程序取代，该处理程序作为 #3896 的一部分添加。参考链接：#3604
[orm] [bug] ¶
为在检索多对一关系的“旧”值时发生的延迟加载添加了新行为，以便跳过由于
lazy="raise"或分离会话错误而引发的异常。参考链接：#4353
[orm] [bug] ¶
ORM 中长期存在的疏忽，多对一关系的
__delete__方法是非功能性的，例如对于诸如del a.b的操作。现在已实现此功能，并且等效于将属性设置为None。另请参阅
参考链接：#4354
orm declarative¶
engine¶
[engine] [feature] ¶
为
QueuePool添加了新的 “lifo” 模式，通常通过将标志create_engine.pool_use_lifo设置为 True 来启用。“lifo” 模式意味着刚刚检入的同一连接将是第一个被检出的连接，从而允许在连接池仅部分利用期间从服务器端清除多余的连接。拉取请求由 Taem Park 提供。另请参阅
sql¶
[sql] [feature] ¶
重构了
SQLCompiler以公开SQLCompiler.group_by_clause()方法，类似于SQLCompiler.order_by_clause()和SQLCompiler.limit_clause()方法，方言可以重写这些方法以自定义 GROUP BY 的呈现方式。拉取请求由 Samuel Chou 提供。此更改也已向后移植到：1.2.13
[sql] [feature] ¶
将
Sequence添加到 “string SQL” 系统，当字符串化不带方言的语句（包含 “sequence nextvalue” 表达式）时，将呈现有意义的字符串表达式（"<next sequence value: my_sequence>"），而不是引发编译错误。参考链接：#4144
[sql] [feature] ¶
添加了新的命名约定标记
column_0N_name、column_0_N_name等，这些标记将呈现特定约束引用的所有列的名称/键/标签（按顺序）。为了适应此类命名约定的长度，SQL 编译器自动截断功能现在也应用于约束名称，这将为约束创建缩短的、确定性生成的名称，该名称将应用于目标后端，而不会超过该后端的字符限制。此更改还修复了另外两个问题。一个是即使记录了
column_0_key标记，该标记也无法使用，另一个是如果referred_column_0_name标记的.key和.name这两个值不同，则会错误地呈现.key而不是.name。另请参阅
参考链接：#3989
[sql] [feature] ¶
为 “expanding IN” 绑定参数功能添加了新逻辑，由此，如果给定的列表为空，则会生成特定于不同后端的特殊 “空集” 表达式，从而允许 IN 表达式完全动态，包括空的 IN 表达式。
参考链接：#4271
[sql] [feature] ¶
Python 内置的
dir()现在支持 SQLAlchemy “properties” 对象，例如 Core 列集合的对象（例如.c）、mapper.attrs等。允许 iPython 自动完成也正常工作。拉取请求由 Uwe Korn 提供。[sql] [feature] ¶
添加了新功能
FunctionElement.as_comparison()，它允许 SQL 函数充当可在 ORM 中使用的二元比较操作。另请参阅
参考链接：#3831
[sql] [bug] ¶
将基于 “like” 的运算符添加为 “comparison” 运算符，包括
ColumnOperators.startswith()ColumnOperators.endswith()ColumnOperators.ilike()ColumnOperators.notilike()以及许多其他运算符，以便所有这些运算符都可以作为 ORM “primaryjoin” 条件的基础。参考链接：#4302
[sql] [bug] ¶
修复了
TypeEngine.bind_expression()和TypeEngine.column_expression()方法的问题，如果目标类型是Variant或TypeDecorator的其他目标类型的一部分，这些方法将无法工作。此外，SQL 编译器现在在呈现这些方法时会调用方言级别的实现，以便方言现在可以为内置类型提供 SQL 级别的处理。参考链接：#3981
postgresql¶
mysql¶
[mysql] [feature] ¶
添加了对 MySQL 中 CREATE FULLTEXT INDEX 的 “WITH PARSER” 语法支持，使用
mysql_with_parser关键字参数。还支持反射，这适应了 MySQL 用于报告此选项的特殊注释格式。此外，“FULLTEXT” 和 “SPATIAL” 索引前缀现在被反射回mysql_prefix索引选项中。参考链接：#4219
[mysql] [feature] ¶
添加了对 MySQL 上 ON DUPLICATE KEY UPDATE 语句中参数排序的支持，因为 MySQL UPDATE 子句中的参数顺序很重要，类似于 参数排序更新 中描述的方式。拉取请求由 Maxim Bublis 提供。
[mysql] [feature] ¶
在 mysqlclient、PyMySQL 和 mysql-connector-python 的情况下，连接池的 “pre-ping” 功能现在使用 DBAPI 连接的
ping()方法。拉取请求由 Maxim Bublis 提供。
sqlite¶
mssql¶
[mssql] [feature] ¶
为 SQL Server pyodbc 方言添加了
fast_executemany=True参数，当使用 Microsoft ODBC 驱动程序时，可以使用 pyodbc 的同名新性能功能。参考链接：#4158
[mssql] [bug] ¶
为了影响 IDENTITY 值的 “start” 和 “increment”，弃用了将
Sequence与 SQL Server 一起使用，转而使用新的参数mssql_identity_start和mssql_identity_increment，它们直接设置这些参数。 在未来的版本中，Sequence将用于生成带有 SQL Server 的真实CREATE SEQUENCEDDL。参考链接：#4362
oracle¶
[oracle] [feature] ¶
添加了一个目前仅由 cx_Oracle 方言使用的新事件
DialectEvents.setiputsizes()。该事件将BindParameter对象的字典传递给 DBAPI 特定的类型对象，这些类型对象在转换为参数名称后，将传递给 cx_Oraclecursor.setinputsizes()方法。这既可以查看 setinputsizes 过程，也可以更改传递给此方法的数据类型的行为。此更改也已向后移植到：1.2.9
参考链接：#4290
[oracle] [bug] ¶
更新了可以发送到 cx_Oracle DBAPI 的参数，既允许所有当前参数，也允许尚未添加的未来参数。此外，删除了 1.2 版本中已弃用的未使用参数，并且我们现在默认将 “threaded” 设置为 False。
参考链接：#4369
[oracle] [bug] ¶
Oracle 方言将不再使用 NCHAR/NCLOB 数据类型来表示与
Unicode和UnicodeText结合使用的通用 unicode 字符串或 clob 字段，除非将标志use_nchar_for_unicode=True传递给create_engine()- 这包括 CREATE TABLE 行为以及绑定参数的setinputsizes()。在读取方面，Python 2 下的 CHAR/VARCHAR/CLOB 结果行已添加自动 Unicode 转换，以匹配 Python 3 下 cx_Oracle 的行为。为了减轻 Python 2 下的性能损失，SQLAlchemy 非常高效（当构建 C 扩展时）的本机 Unicode 处理程序在 Python 2 下使用。参考链接：#4242
misc¶
[feature] [ext] ¶
添加了新的属性
Query.lazy_loaded_from，它填充了InstanceState，该状态使用此Query为了延迟加载关系。 这样做的理由是，它可以作为水平分片功能使用的提示，以便状态的身份令牌可以用作 id_chooser() 中查询使用的默认身份令牌。此更改也已向后移植到：1.2.9
参考链接：#4243
[feature] [ext] ¶
添加了新功能
BakedQuery.to_query()，它提供了一种使用一个BakedQuery作为另一个BakedQuery内的子查询的简洁方法，而无需显式引用Session。参考链接：#4318
[feature] [ext] ¶
AssociationProxy现在具有标准的列比较操作，例如ColumnOperators.like()和ColumnOperators.startswith()，当目标属性是普通列时可用 - 连接到目标表的 EXISTS 表达式像往常一样呈现，但列表达式随后在 EXISTS 的 WHERE 条件中使用。 请注意，这会改变关联代理上.contains()方法的行为，以便在使用基于列的属性时使用ColumnOperators.contains()。参考链接：#4351
[feature] [ext] ¶
为水平分片扩展中的
ShardedQuery类添加了对批量Query.update()和Query.delete()的支持。 这也为批量更新/删除方法Query._execute_crud()添加了一个额外的扩展钩子。另请参阅
参考链接：#4196
[bug] [ext] ¶
重做了
AssociationProxy以在一个单独的对象中存储特定于父类的状态，以便单个AssociationProxy可以用于多个父类（这对于继承是固有的），而不会导致其返回的状态出现任何歧义。 添加了一个新方法AssociationProxy.for_class()以允许检查类特定的状态。参考链接：#3423
[bug] [ext] ¶
恢复了关联代理集合仅维护对父对象的弱引用的长期行为；现在，只要代理集合本身也在内存中，代理将维护对父对象的强引用，从而消除 “陈旧的关联代理” 错误。 正在以实验性为基础进行此更改，以查看是否会出现任何导致副作用的用例。
另请参阅
参考链接：#4268
[bug] [ext] ¶
修复了关于使用关联代理取消关联标量对象的多个问题。
del现在可以工作，并且还添加了一个新标志AssociationProxy.cascade_scalar_deletes，当设置为 True 时，表示将标量属性设置为None或通过del删除也会将源关联设置为None。参考链接：#4308
flambé! 龙和 The Alchemist 图像设计由 Rotem Yaari 创作并慷慨捐赠。
使用 Sphinx 7.2.6 创建。文档上次生成时间：Tue 11 Mar 2025 02:40:17 PM EDT