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 的新特性？
项目版本
0.2 变更日志¶
0.2.8¶
发布日期: 2006 年 9 月 5 日星期二[no_tags] ¶
清理连接方法 + 文档。在查询字符串中指定的自定义 DBAPI 参数、“connect_args”参数到“create_engine”，或通过“creator”函数到“create_engine”的自定义创建函数。
[no_tags] ¶
添加到 Pool 的“recycle”参数，是 create_engine 上的“pool_recycle”，默认为 3600 秒；在此时间之后，连接将被关闭并替换为新的连接，以处理自动关闭陈旧连接的数据库
参考: #274
[no_tags] ¶
更改了池连接的“invalidate”语义；将指示底层连接记录在下次调用时重新连接。“invalidate”也将在底层调用 connection.cursor() 中抛出任何错误时自动调用。这有望允许连接池重新连接到已停止并启动但未重新启动连接应用程序的数据库
参考: #121
[no_tags] ¶
哎呀！教程 doctest 已经损坏很长时间了。
[no_tags] ¶
mapper 上的 add_property() 方法执行“编译所有映射器”步骤，以防给定的属性引用未编译的映射器（就像教程中那样！）
[no_tags] ¶
在创建之前检查 pg 序列是否已存在
参考: #277
[no_tags] ¶
如果通过 MapperExtension.get_session（就像使用 sessioncontext 插件等一样）建立上下文会话，则如果父对象尚未持久化到会话中，则延迟加载操作将默认使用该会话。
[no_tags] ¶
延迟加载不会为没有数据库标识的对象触发（为什么？请参阅 https://sqlalchemy.org.cn/trac/wiki/WhyDontForeignKeysLoadData）
[no_tags] ¶
单元工作在“delete-orphan”级联的一部分的“孤立”对象上进行了更好的检查，对于父级不可用于级联的某些情况。
[no_tags] ¶
映射器可以根据与属性包的交互来判断其对象之一是否为“孤立”。此检查基于在对象彼此连接和分离时为每个关系维护的状态标志。
[no_tags] ¶
现在声明带有“delete-orphan”的自引用关系是无效的（因为上述检查会使它们无法保存）
[no_tags] ¶
改进了对象作为关系的一部分在单元工作尝试 flush() 它们时检查对象是否为会话一部分的检查。
[no_tags] ¶
语句执行支持在一个表达式中多次使用相同的 BindParam 对象；简化了位置参数的处理。Bill Noon 提出了基本思路，做得很好。
参考: #280
[no_tags] ¶
Postgres 反射已移至使用 pg_schema 表，可以使用 use_information_schema=True 参数覆盖 create_engine。
[no_tags] ¶
向 MetaData、Table、Column 添加了 case_sensitive 参数，根据父 schemaitem 是否具有该标志的非 None 设置自动确定自身，或者如果不是，则根据标识符名称是否全为小写字母。当设置为 True 时，引号将应用于具有混合或大写字母标识符的标识符。引号也自动应用于所有情况下已知为保留字或包含其他非标准字符的标识符。各种数据库方言可以覆盖所有这些行为，但目前它们都使用默认行为。已使用 postgres、mysql、sqlite、oracle 进行测试。需要使用 firebird、ms-sql 进行更多测试。作为持续工作的一部分
参考: #155
[no_tags] ¶
单元测试已更新为在未安装任何 pysqlite 的情况下运行；池测试使用模拟 DBAPI
[no_tags] ¶
URL 支持密码中的转义字符
参考: #281
[no_tags] ¶
向 UNION 查询添加了 limit/offset（尽管在 oracle 中尚不可用）
[no_tags] ¶
向 DateTime 和 Time 类型添加了“timezone=True”标志。到目前为止，Postgres 会将其转换为“TIME[STAMP] (WITH|WITHOUT) TIME ZONE”，以便可以更好地控制时区存在（psycopg2 在可用时返回带有 tzinfo 的日期时间，这可能会对不包含日期时间的日期时间造成混淆）。
[no_tags] ¶
修复了将 query.count() 与 distinct、**kwargs 与 SelectResults count() 一起使用的问题
参考: #287
[no_tags] ¶
当自动加载失败时，从 MetaData 中注销 Table；
参考: #289
[no_tags] ¶
导入 py2.5s sqlite3
参考: #293
[no_tags] ¶
startswith()/endswith() 的 Unicode 修复
参考: #296
0.2.7¶
发布日期: 2006 年 8 月 12 日星期六[no_tags] ¶
设置了引用工具，以便在所有查询/创建/删除中使用时，可以为单个表、架构和列标识符启用特定于数据库的引用。通过 Table 或 Column 中的“quote=True”以及 Table 中的“quote_schema=True”启用。感谢 Aaron Spike 的出色努力。
[no_tags] ¶
assignmapper 设置了 is_primary=True，导致在设置冗余映射器时未引发错误，已修复
[no_tags] ¶
向 Mapper 添加了 allow_null_pks 选项，允许某些主键列为空的行（即，当映射到外连接等时）
[no_tags] ¶
修改 unitofwork，不在“new”列表或 UOWTask “objects”列表中维护排序；相反，新对象在注册为会话的新对象时会标记排序标识符，然后在映射器 save_obj 中对 INSERT 语句进行排序。INSERT 排序基本上已完全推送到刷新周期的末尾。这样，UOWTask 中发生的各种排序和组织（特别是循环任务排序）不必担心维护顺序（反正它们也不是）
[no_tags] ¶
修复了外键的反射，以自动加载引用的表（如果尚未加载）
[no_tags] ¶
将 URL 查询字符串参数传递给 connect() 函数
参考: #256
[no_tags] ¶
Oracle Boolean 类型
参考: #257
[no_tags] ¶
关系中的自定义 primary/secondary join 条件将默认传播到 backrefs。指定 backref() 将覆盖此行为。
[no_tags] ¶
更好地检查 sql.Join 中的歧义连接条件；当无法合理确定连接条件时，传播到 PropertyLoader（即 relation()/backref()）中更好的错误消息。
[no_tags] ¶
sqlite 在表反射时正确创建 ForeignKeyConstraint 对象。
[no_tags] ¶
对池的调整源于所做的更改。仅当连接实际成功时，才应递减溢出计数器。添加了一个测试脚本来尝试测试这一点。
参考: #224
[no_tags] ¶
修复了 mysql 反射默认值为 PassiveDefault
[no_tags] ¶
向 MS-SQL 添加了反射的“tinyint”、“mediumint”类型。
[no_tags] ¶
SingletonThreadPool 具有大小并进行清理传递，以便仅保留给定数量的线程本地连接（sqlite 应用程序需要丢弃大量线程）
[no_tags] ¶
修复了延迟加载器中的小 pickle 错误
[no_tags] ¶
修复了 mysql 反射中的可能错误，其中某些版本返回数组而不是字符串以用于 SHOW CREATE TABLE 调用
[no_tags] ¶
修复了映射到连接时的延迟加载
参考: #1770
[no_tags] ¶
所有 create()/drop() 调用都有一个关键字参数“connectable”。“engine”已弃用。
[no_tags] ¶
修复了 ms-sql connect() 以使用 adodbapi
[no_tags] ¶
向 Select() 添加了“nowait”标志
[no_tags] ¶
继承检查使用 issubclass() 而不是直接 __mro__ 检查来确保类 A 继承自 B，从而允许映射器继承更灵活地对应于类继承
参考: #271
[no_tags] ¶
当在具有 ORDER BY 子句的 SelectResults 上调用聚合函数（即 max、min 等）时，SelectResults 将使用子选择
参考: #252
[no_tags] ¶
修复了类型，以便更轻松地使用特定于数据库的类型；修复了 mysql 文本类型以使用此方法
参考: #269
[no_tags] ¶
对 sqlite 日期类型组织的一些修复
[no_tags] ¶
向 MS-SQL 添加了 MSTinyInteger
参考: #263
0.2.6¶
发布日期: 2006 年 7 月 20 日星期四[no_tags] ¶
对架构进行重大修改，以允许通过新的 ForeignKeyConstraint 和 PrimaryKeyConstraint 对象实现真正的复合主键和外键约束。主键/外键创建的现有方法没有更改，但在幕后使用了这些新对象。表创建和反射现在更多地以表为导向，而不是以列为导向。
参考: #76
[no_tags] ¶
MapperExtension 调用方案的修改，以前效果不佳
[no_tags] ¶
调整 ActiveMapper，支持自引用关系
[no_tags] ¶
对 objectstore（在 activemapper/threadlocal 中）进行轻微的重新排列，以便 SessionContext 由“.context”引用，而不是直接子类化。
[no_tags] ¶
如果在导入 activemapper 时激活了 mod，则 activemapper 将使用 threadlocal 的 objectstore
[no_tags] ¶
URL regexp 的小修复，以允许文件名中包含“@”
[no_tags] ¶
修复了 Session expunge/update/etc...需要更多清理。
[no_tags] ¶
select_table 映射器仍然并非总是编译
[no_tags] ¶
修复了 Boolean 数据类型
[no_tags] ¶
将 count()/count_by() 添加到 assignmapper 代理的方法列表中；这也将它们添加到 activemapper
[no_tags] ¶
连接异常包装在 DBAPIError 中
[no_tags] ¶
ActiveMapper 现在支持从数据库自动加载列定义，如果您在映射内部类中提供 __autoload__ = True 属性。目前，这不支持反映任何关系。
[no_tags] ¶
延迟列加载可能会在某些情况下搞砸 flush() 中的连接状态，这已修复
[no_tags] ¶
expunge() 在级联中不起作用，已修复。
[no_tags] ¶
级联操作中潜在的无限循环已修复。
[no_tags] ¶
添加了“synonym()”函数，应用于属性以使 propname 与另一个相同，用于覆盖属性并允许原始 propname 在 select_by() 中可访问。
[no_tags] ¶
修复了子句构造中的类型，这特别有助于 polymorphic_union 的类型问题（CAST/ColumnClause 将其类型传播到代理列）
[no_tags] ¶
映射器编译工作正在进行中，总有一天它会工作……移动了 MapperProperty 对象的初始化，使其在创建所有映射器之后进行，以便更好地处理循环编译。现在在所有属性上调用 do_init() 方法，这些属性如果存在，则更清楚地了解其“继承”状态。
[no_tags] ¶
显式禁止在自引用关系或与继承映射器的关系（也是自引用）上进行急切加载
[no_tags] ¶
减小了 query._get 中的绑定参数大小，以安抚挑剔的 oracle
参考: #244
[no_tags] ¶
向 table.create()/table.drop() 以及 table.exists() 添加了“checkfirst”参数
参考: #234
[no_tags] ¶
对继承的一些其他正在进行的修复
参考: #245
[no_tags] ¶
属性/backref/孤立/历史记录跟踪调整和往常一样……
0.2.5¶
发布日期: 2006 年 7 月 8 日星期六[no_tags] ¶
修复了 select_by() 中的无限循环错误，如果遍历命中两个相互引用的映射器
[no_tags] ¶
升级了所有单元测试，将“./lib/”插入到 sys.path 中，绕过了新的 setuptools PYTHONPATH 终止行为
[no_tags] ¶
属性/依赖项等的进一步修复……
[no_tags] ¶
改进了 DynamicMetaData 未连接时的错误处理
[no_tags] ¶
MS-SQL 支持大部分工作正常（已使用 pymssql 测试）
[no_tags] ¶
组内 UPDATE 和 DELETE 语句的排序现在按主键值排序，以获得更具确定性的排序
[no_tags] ¶
after_insert/delete/update 映射器扩展现在按对象调用，而不是按对象-按表调用
[no_tags] ¶
对映射器编译的进一步修复/重构
0.2.4¶
发布日期: 2006 年 6 月 27 日星期二[no_tags] ¶
当映射器在映射类上设置 init.__name__ 时，try/except，支持 python 2.3
[no_tags] ¶
修复了 threadlocal 引擎在事务进行中仍然自动提交的错误
[no_tags] ¶
延迟加载和延迟加载操作需要父对象位于会话中才能执行操作；而在此之前，操作只会返回空白列表或 None，现在会引发异常。
[no_tags] ¶
如果给定对象先前附加到的会话已被垃圾回收，则 Session.update() 会稍微宽松一些；否则仍然需要您显式地从先前的 Session 中删除实例。
[no_tags] ¶
修复了映射器编译，检查了更多错误条件
[no_tags] ¶
对与排序/limit/offset 结合使用的急切加载的小修复
[no_tags] ¶
非常了不起：在“CREATE TABLE”和“(<the rest of it>”之间添加了一个空格，因为这就是 MySQL 指示非保留字表名的方式……
参考: #206
[no_tags] ¶
更多继承方面的修复，与多对多关系正确保存有关
[no_tags] ¶
修复了为 mysql 方言指定显式模块时的错误
[no_tags] ¶
当 QueuePool 超时时，它会引发 TimeoutError 而不是错误地建立另一个连接
[no_tags] ¶
池中的 Queue.Queue 用法已替换为本地修改的版本（在 py2.3/2.4 中工作！），该版本使用 threading.RLock 作为互斥锁。这是为了修复报告的案例，其中 ConnectionFairy 的 __del__() 方法在 Queue 的 get() 方法中被调用，然后通过 put() 方法将其连接返回到 Queue，除非使用 threading.RLock，否则会导致重入挂起。
[no_tags] ¶
如果 postgres 的主键列具有外键约束，则不会在其上放置 SERIAL 关键字
[no_tags] ¶
ConnectionFairy 上的 cursor() 方法允许传播特定于数据库的扩展参数
参考: #221
[no_tags] ¶
延迟加载绑定参数正确传播列类型
参考: #225
[no_tags] ¶
新的 MySQL 类型：MSEnum、MSTinyText、MSMediumText、MSLongText 等。对数字类型补丁的 MS 特定长度/精度参数的更多支持，由 Mike Bernson 提供
[no_tags] ¶
对连接池 invalidate() 的一些修复
参考: #224
0.2.3¶
发布日期: 2006 年 6 月 17 日星期六[no_tags] ¶
修改映射器编译以进行延迟。这允许以任何顺序构造映射器，并且它们的相互关系在首次使用映射器时进行编译。
[no_tags] ¶
修复了级联行为中的一个相当大的速度瓶颈，尤其是在使用 backrefs 时
[no_tags] ¶
属性 instrumentation 模块已完全重写；现在它在很大程度上更简单明了，速度稍快。属性的“历史记录”不再在每次更改时进行微观管理，而是实例首次加载时创建的“CommittedState”对象的一部分。HistoryArraySet 已消失，列表属性的行为现在更加开放（即，它们不再是集合）。
[no_tags] ¶
py2.4 “set” 构造在内部使用，当“set”不可用/需要排序时，回退到 sets.Set。
[no_tags] ¶
修复了事务控制，以便重复的 rollback() 调用不会失败（当 flush() 会在较大的 try/except 事务块中引发异常时，会严重失败）
[no_tags] ¶
relation() 的“foreignkey”参数也可以是列表。修复了自动外键检测
参考: #151
[no_tags] ¶
修复了架构名称的表未在 MetaData 对象中正确索引的错误
[no_tags] ¶
修复了重新定义了“key”属性的 Column 未在 ResultProxy 中发生类型转换的错误
参考: #207
[no_tags] ¶
修复了 URL 的“port”属性，如果存在，则为整数
[no_tags] ¶
修复了旧错误，如果映射为“secondary”的多对多表具有额外的列，则删除操作不起作用
[no_tags] ¶
针对 UNION 查询进行映射的错误修复
[no_tags] ¶
修复了在没有 DB 驱动程序时抛出的错误异常类
[no_tags] ¶
添加了 NonExistentTable 异常，在反射不存在的表时抛出
参考: #138
[no_tags] ¶
关于一对一 backrefs 的 ActiveMapper 的小修复，其他重构
[no_tags] ¶
映射类中重写的构造函数从原始类获取 __name__ 和 __doc__
[no_tags] ¶
修复了 selectresult.py 中关于映射器扩展的小错误
参考: #200
[no_tags] ¶
对 cascade_mappers 的小调整，目前不是很强烈支持的函数
[no_tags] ¶
对 between()、column.between() 的一些修复，以更好地传播类型信息
参考: #202
[no_tags] ¶
如果对象构造失败，则不会添加到会话中
参考: #203
[no_tags] ¶
CAST 函数已成为其自己的子句对象，并在 ansicompiler 中具有自己的编译函数；允许 MySQL 静默忽略大多数 CAST 调用，因为 MySQL 似乎仅支持带有 Date 类型的标准 CAST 语法。MySQL 兼容的字符串、整数等的 CAST 支持是一个 TODO
0.2.2¶
发布日期：周一 6月 05 2006[no_tags] ¶
对多态继承行为的重大改进，使其能够与邻接列表表结构一起工作
参考： #190
[no_tags] ¶
对整体继承关系的重大修复和重构，更多单元测试
[no_tags] ¶
修复了 create_engine() 上的 “echo_pool” 标志
[no_tags] ¶
文档修复，移除了关于 close() 与 threadlocal 策略一起使用是不安全的错误信息（它完全安全！）
[no_tags] ¶
create_engine() 可以接受字符串或 unicode 类型的 URL
参考： #188
[no_tags] ¶
Firebird 支持部分完成；感谢 James Ralston 和 Brad Clements 的努力。
[no_tags] ¶
Oracle url 转换已损坏，已修复，如果存在 ‘database’ 字段，则会将 host/port/sid 馈送到 cx_oracle makedsn() 中，否则使用来自 ‘host’ 字段的直接 TNS 名称
[no_tags] ¶
修复了对 query.get()/query.load() 使用 unicode 标准的问题
[no_tags] ¶
selectables 上的 count() 函数现在使用表主键或第一列而不是 “1” 作为标准，并且使用标签 “rowcount” 而不是 “count”。
[no_tags] ¶
清理了基本的 “映射到多表” 功能，并进行了更正确的文档记录
[no_tags] ¶
恢复了 global_connect() 函数，附加到名为 “default_metadata” 的 DynamicMetaData 实例。将 MetaData 参数从 Table 中省略将使用默认元数据。
[no_tags] ¶
修复了会话级联行为、entity_name 传播
[no_tags] ¶
将单元测试重组为子目录
[no_tags] ¶
更多修复线程本地连接嵌套模式
0.2.1¶
发布日期：周一 5月 29 2006[no_tags] ¶
create_engine() 的 “pool” 参数正确传播
[no_tags] ¶
修复了 URL，如果未解析则引发异常，不会将空白字段传递给 DB 连接字符串（诸如 user:host@/db 之类的字符串在 postgres 上会中断）
[no_tags] ¶
Mapper 在插入并尝试取回新的主键值时的小修复
[no_tags] ¶
重写了一半的 TLEngine，即与 ‘strategy=”threadlocal”’ 一起使用的 ComposedSQLEngine。它现在正确实现了 engine.begin()/ engine.commit()，它们与 connection.begin()/trans.commit() 完全嵌套。添加了大约六个单元测试。
[no_tags] ¶
pool.Pool 中的重大 “duh”，忘记放回 WeakValueDictionary。本应检查此项的单元测试也静默地遗漏了它。修复了单元测试以确保 ConnectionFairy 正确超出作用域。
[no_tags] ¶
占位符 dispose() 方法已添加到 SingletonThreadPool，但尚无任何作用
[no_tags] ¶
当引发异常时，会自动调用 rollback()，但仅当没有正在进行的事务时（即，更像自动提交）。
[no_tags] ¶
修复了如果不存在 sqlite 模块，sqlite 中的异常引发
[no_tags] ¶
为关联对象文档添加了额外的示例细节
[no_tags] ¶
Connection 添加了对已关闭状态的检查
0.2.0¶
发布日期：周六 5月 27 2006[no_tags] ¶
对 Engine 系统进行全面修改，以前的 SQLEngine 现在是一个 ComposedSQLEngine，它由各种组件组成，包括 Dialect、ConnectionProvider 等。这影响了所有 db 模块以及 Session 和 Mapper。
[no_tags] ¶
create_engine 现在仅接受 RFC-1738 样式的字符串：
driver://user:password@host:port/database更新 此格式通常但不完全是 RFC-1738，包括在 “scheme” 部分接受下划线而不是破折号或句点。
[no_tags] ¶
连接作用域方法论的完全重写，Connection 对象现在可以直接执行 clause 元素，添加了显式的 “close”，并在整个 Engine/ORM 中提供支持以正确处理关闭，不再依赖内部 __del__ 将连接返回到池。
参考： #152
[no_tags] ¶
Session 接口和作用域的全面修改。使用 Hibernate 风格的方法，包括 query(class)、save()、save_or_update() 等。默认情况下不安装 threadlocal 作用域。提供到特定 Engine 和/或 Connection 的绑定接口，以便底层 Schema 对象不需要绑定到 Engine。添加了一个基本的 SessionTransaction 对象，可以简单地聚合跨多个引擎的事务。
[no_tags] ¶
mapper 的依赖和 “cascade” 行为的全面修改；依赖逻辑从 properties.py 中分解出来，放入单独的模块 “dependency.py”。“cascade” 行为现在是显式可控的，正确实现了 “delete”、“delete-orphan” 等。依赖系统现在可以在刷新时确定子对象是否具有父对象，以便更好地决定如何在 DB 中更新该子对象，关于删除。
[no_tags] ¶
Schema 的全面修改，以构建在 MetaData 对象而不是 Engine 之上。整个 SQL/Schema 系统可以在没有任何 Engine 的情况下使用，仅通过显式的 Connection 对象执行。“bound” 方法通过 Schema 对象的 BoundMetaData 存在。ProxyEngine 通常不再需要，并被 DynamicMetaData 替换。
[no_tags] ¶
实现了真正的多态行为，修复
参考： #167
[no_tags] ¶
“oid” 系统已完全移至编译时行为；如果在 order_by 中使用它们但不可用，则 order_by 不会被编译，修复
参考： #147
[no_tags] ¶
打包的全面修改；“mapping” 现在是 “orm”，“objectstore” 现在是 “session”，如果使用，旧的 “objectstore” 命名空间通过 “threadlocal” 模块加载
[no_tags] ¶
模块现在通过 “import <modname>” 调用。扩展优先于模块，因为模块是全局猴子补丁
[no_tags] ¶
修复了 add_property，以便将其属性传播到继承的映射器
参考： #154
[no_tags] ¶
反向引用针对其原始属性的主映射器创建自身，可以指定主/次连接参数来覆盖。有助于它们在多态映射器中的使用
[no_tags] ¶
“表存在” 功能已实现
参考： #31
[no_tags] ¶
“create_all/drop_all” 添加到 MetaData 对象
参考： #98
[no_tags] ¶
改进和修复了拓扑排序算法，以及更多单元测试
[no_tags] ¶
教程页面已添加到文档中，该页面也可以与自定义 doctest 运行器一起运行，以确保其正常工作。文档通常进行了全面修改，以处理新的代码模式
[no_tags] ¶
更多修复，重构。
[no_tags] ¶
迁移指南可在 Wiki 上找到：https://sqlalchemy.org.cn/trac/wiki/02Migration
flambé! 龙和 The Alchemist 图像设计由 Rotem Yaari 创建并慷慨捐赠。
使用 Sphinx 7.2.6 创建。文档最后生成时间：周二 11 3月 2025 02:40:17 下午 EDT