SQLAlchemy 0.1 Changelog 深度解读:2006 年诞生初期 ORM、类型系统与多方言架构的关键演进

原创2026-09-22 16:29:501,624 阅读
文章标签:数据库关系型数据库ORM后端

SQLAlchemy 0.1 Changelog 深度解读:2006 年诞生初期 ORM、类型系统与多方言架构的关键演进

SQLAlchemy 的 doc/build/changelog/changelog_01.rst 记录了 0.1.1 至 0.1.7 共七个版本的完整变更历史,覆盖 2006 年 2 月至 5 月期间项目从原型走向可用的核心演进:Mapper/Query 重构、Session 与 Unit of Work 的定型、类型系统两次重构、version_id 乐观锁与 post_update 等至今仍在使用的重要特性,以及 Postgres、Oracle、MySQL、SQLite、MS-SQL 多方言适配。读完本文,你将理解 SQLAlchemy 现代架构的起源脉络,并能在当前仓库(lib/sqlalchemy)中逐一对照这些特性的源码级实现。

版本总览与阅读方法

版本 发布日期 主题定位
0.1.1 2006-02-23 属性/关系/EagerLoading 基础修复
0.1.2 2006-02-24 schema 递归调用性能修复
0.1.3 2006-03-02 post_update、mapper.using、sql 与 schema 解耦
0.1.4 2006-03-13 类型系统重构、convert_unicode、Oracle 反射
0.1.5 2006-03-27 SQLSession 嵌套事务、version_id、entity_name
0.1.6 2006-04-12 Query 对象分离、mods 插件系统、MS-SQL 支持
0.1.7 2006-05-05 拓扑排序修复、DISTINCT ON、多项 bug 修复

所有变更均以 .. change:: 指令记录(参见 doc/build/changelog/README.txt 中的格式规范::tags: 与 :tickets: 可逗号分隔多个元素,正文使用 reStructuredText/Sphinx 标记)。这是 SQLAlchemy 历史上最早期的一批 changelog,直接反映了 0.1 系列"先跑起来、再持续重构"的演进风格——多条记录都带有"再次修复""仍然没修好"这类坦诚的注释,例如 0.1.7 中"types types types! 仍然没修好……只好再次使用 TypeDecorator"。

Session 与 Unit of Work:现代 ORM 工作单元模型的定型

0.1.5 与 0.1.6 是两个决定性版本,它们把 SQLAlchemy 的 ORM 会话模型逐步塑造成今天的样子。

0.1.5:嵌套事务与 session 生命周期

  • SQLSession 概念:0.1.5 在 SQLEngine 上引入 SQLSession,负责从连接池获取连接并跟踪进行中的事务;引擎新增 push_session() / pop_session(),允许在既有连接上"嵌套"打开第二个连接,从而支持嵌套事务。
  • Session.nest_on:objectstore.Session 新增 nest_on 参数(单个或一组 SQLEngine),当该 Session 变为活动会话时自动执行 push_session() / pop_session(),让工作单元 Session 无需显式调用即可享受嵌套事务。
  • 职责拆分:0.1.5 将 objectstore 与 unitofwork 分离,"Session 作用域管理"与"UoW 提交重活"解耦;objectstore.Session.refresh(*obj) 无条件从数据库重载对象属性,expunge() 则彻底把对象移出当前 Session。
  • 0.1.6 的 flush 化:Session 重构后,官方保存对象的方式统一为 flush();旧的 begin/commit 行为被归入 LegacySession,作为 0.2 之前的默认行为。0.1.6 同时把 Mapper 的查询能力抽离成独立的、以 Session 为中心的 Query 对象,显著提升 mapper.using(session) 的性能。

0.1.5:version_id 乐观并发控制

0.1.5 为 mapper 新增 version_id 关键字参数:引用一张 Integer(最好非空)的 Column,用于在映射表上跟踪版本号。每次保存操作递增该数字,并把该值写入 UPDATE/DELETE 的条件中参与返回行数统计;若返回行数不符则抛出 ConcurrencyError。

这一机制完整保留至今,当前 mapper.py 中 version_id_col 的文档依然如此描述:检测到 UPDATE 未命中"最后已知版本号"时抛出 StaleDataError。默认生成器为 lambda x: (x or 0) + 1(mapper.py),传入 False 则关闭客户端版本号生成,改由服务端触发器维护。继承场景下子类 mapper 会继承父类的 version_id_col 与 version_id_generator,若显式指定不一致的列会得到警告(mapper.py)。

0.1.5:entity_name 多实体映射

同一版本新增 entity_name 关键字:mapper 通过"类对象 + 可选字符串 entity_name(默认 None)"与类关联,可为同一个类创建任意多个主 mapper,各实体在身份映射(identity map)中保持彼此独立的身份,各自的加载/保存操作都经由自己 entity_name 限定的 mapper 完成。这是"同一张表映射多个角色"场景的最早期解法。

post_update 与关系持久化:解决循环依赖的两阶段更新

0.1.1 首次加入实验性标志 use_update:关系由第二条 UPDATE 语句处理——在主 INSERT 之后、主 DELETE 之前执行,用于处理循环行依赖。0.1.3 正式完成该特性并定名为 post_update:在 INSERT 前追加第二条 UPDATE、在 DELETE 后追加第二条 UPDATE,从而在不建立依赖关系的前提下调和两个互相依赖的行。

该参数在当代 relationships.py 中依然是 relationship() 的正式参数,0.1.1 记录中"必须使用显式 aliases"的旧时代早已被 0.1.1 同版本的 EagerLoading 全面内部化所取代:eager loading 在 0.1.1 起就一律使用别名(alias)进行查询,复杂的 eager load 链不再需要任何显式别名指令。

类型系统的两次重构与 PickleType 的诞生

类型系统在 0.1 系列经历了两次方向相反的重构:

  • 0.1.4 第一次重构:采用更简单的继承模式,让任意通用类型都可被直接子类化,"不再需要 TypeDecorator"。
  • 0.1.7 打脸回退:重构后类型"仍然没修好",又不得不回到 TypeDecorator 方案。

这段波折在今天留下了清晰的痕迹:现代 PickleType 正是 TypeDecorator 的子类,而 TypeDecorator 本身已成为 SQLAlchemy 类型定制的基础设施。

同期的类型相关变更还包括:

  • 0.1.4 引入 convert_unicode=False 引擎参数,让所有 String 类型执行 Unicode 编解码("让 String 表现得像 Unicode");配套 encoding="utf8" 参数,用于 Unicode 类型以及 convert_unicode=True 时 String 的所有编解码调用。
  • 0.1.6 将类型系统绑定时机从"schema 构建时"推迟到"查询编译时",简化了类型系统与 ProxyEngine。
  • 0.1.7 修复 convert_unicode=True 时反射(reflection)失败的问题;MySQL binary 类型把数组输出转换为 buffer,从而修复 PickleType。
  • 0.1.1 修复 psycopg1 日期/时间与 None 的兼容问题;0.1.5 为 SQLite 增加绑定参数日期转换,使 pysqlite1 下日期可用。

方言支持版图:Postgres、Oracle、MySQL、SQLite、MS-SQL

0.1 系列已经形成多数据库方言的雏形(现代实现在 lib/sqlalchemy/dialects):

  • PostgreSQL:0.1.7 为 Postgres 增加 DISTINCT ON 支持,用法是 distinct=[col1, col2, ...];0.1.3 维护 ANSI 函数白名单(无参函数调用不输出括号);0.1.1 围绕"Postgres 不再提供 lastrowid、OID 已废弃"展开大量修复——主键列上的数据库侧默认值(反射为 PassiveDefault)会被显式预执行,以便获知刚插入的主键值。
  • Oracle:0.1.4 加入由 Andrija Zaric 贡献的表反射(复合主键/字典选择仍有遗留 bug);0.1.5 反射改用 ALL_* 视图而非 USER_* 以获得更大范围,并修复外键反射(ticket 105);同时有 Oracle8 兼容的 use_ansi 标志(把 JOIN 转成 = + (+) 比较)与 LIMIT/OFFSET 的反复调整。
  • MySQL:0.1.4 修正 MySQL4 自定义表引擎的 TYPE 而非 ENGINE 语法,并新增 Double、TinyInt;0.1.7 修复 binary 类型输出为 buffer 的问题;0.1.1 修复日期类型把 timedelta 转为 datetime.time。
  • SQLite:0.1.4 修复 LIMIT/OFFSET 语法;0.1.5 增加绑定参数日期转换。
  • MS-SQL:0.1.6 由 Rick Morrison、Runar Petursson 贡献支持。
  • 0.1.4 还签入了初始的 Firebird 模块("awaiting testing",即等待测试)。

SQL 表达式层的成型

0.1 系列奠定了 SQL 表达式层的基础能力:

  • 函数与运算符:0.1.4 规定 ANSI 标准函数(如 current_timestamp)不输出括号、其余函数均带括号;SQL 函数支持独立 execute() / scalar(),且接受 engine 关键字参数;0.1.5 支持多段函数名如 schema.mypkg.func();0.1.7 增加 % 运算符(__mod__)与 CAST 运算符调整,并把函数名 LOCAL_TIME/LOCAL_TIMESTAMP 修正为标准的 LOCALTIME/LOCALTIMESTAMP。
  • 子查询与列子句:0.1.4 支持以 scalar=True 标志把 SELECT 语句嵌入列子句;0.1.5 改进子查询的 FROM 子句构造;0.1.7 修复 INSERT/UPDATE 中子查询的括号问题与 ORDER BY/HAVING 的编译顺序。
  • 构造能力:0.1.4 的 sql.ClauseParameters 作为 compiled.get_params() 的结果,对绑定参数做延迟类型处理;0.1.1 修复 engine.execute_compiled 创建后被丢弃的第二个 ResultProxy;0.1.1 规定一个 Column 只能属于一张表(现已是断言)。
  • 绑定参数命名:0.1.5 修复列标签与绑定参数的两个 bug——绑定参数键名改为由列 label 生成以适配超长名称规则,并处理与 tablename_colname 命名冲突的列。

Mapper 与继承体系

继承与多态是 0.1 系列反复打磨的主题:

  • 0.1.3 大规模修复使用继承的 mapper:关系针对该 mapper 的"本地表"而非继承来的表建立,使组合模式能配合 lazy/eager loading 工作;支持父子 mapper 共用同一张表(在两者上指定相同 table 即可)。
  • 0.1.4 再次重构 EagerLoading 与继承 mapper 的组合,eager load 能正确推导别名查询;针对继承 mapper 建立的关系会 JOIN 到该 mapper 专属的表,可用自定义 primary/secondary join 覆盖。
  • 0.1.7 中 order_by mapper 属性可被继承 mapper 继承;修复 mapper UPDATES/DELETEs 时使用的列类型;支持通过关联表实现表到自身的多对多关系。
  • 0.1.3 的 translate_row 相关能力服务于 polymorphic 示例;0.1.4 增强了对 UNION 的映射支持并新增 polymorph.py 示例。
  • 0.1.5 的 MapperExtension.populate_instance() 允许扩展参与对象属性填充,甚至可调用另一 mapper 的 populate_instance() 实现属性填充的代理与行转换。
  • 0.1.7 新增 construct_new 标志:用 __new__ 而非 __init__ 创建实例(0.2 成为标准)。
  • 0.1.4 的 J.Ellis patch 使 selectone() 在查询返回多行时抛异常、selectfirst() 不抛,并新增 selectfirst_by(与 get_by 同义)和 selectone_by。
  • 0.1.4 新增 setattr_clean / append_clean 到 SmartProperty,设置属性时不触发 dirty 事件或历史记录。

引擎、连接池与默认值处理

  • 0.1.4 通用化 create_engine 参数:host/hostname、db/dbname/database、password/passwd 等在所有引擎连接上通用,让引擎 URI 更"通用"。0.1.7 中 create_engine 改用 cgi.parse_qsl 解析查询字符串(0.2 中被弃用)。当前入口 create.py 仍保持 create_engine(url, **kwargs) 的统一形态。
  • 0.1.3 sql/schema 解耦:sql 包可完全独立运行(不依赖引擎即可生成 SELECT/INSERT),基于新的 TableClause/ColumnClause 词法对象;schema 的 Table/Column 是其"物理"子类。这大幅简化了 schema/sql 关系,移除了 0.1.1 中被诟病的整套 getattr() 行为,并显著提速。schema 拓扑结构正是由 util/topological.py 的依赖排序算法支撑(该模块 0.1.7 仍被称为"拓扑排序算法"的修复对象)。
  • 连接池:0.1.5 新增 unique_connection() 方法,返回不属于线程本地上下文或当前事务的连接;invalidate() 从池中移除坏连接(当时引擎尚缺自动重连)。0.1.7 修复 schema 名导致的强制引擎连接问题。
  • 默认值:0.1.4 为 Column 增加 onupdate 参数;0.1.7 修复列默认值覆盖 INSERT 对象 VALUES 子句的 bug。0.1.4 改进 mapper 使用列默认值的支持:从语句执行前的绑定参数中取回预执行默认值填充对象属性;若触发了 PassiveDefaults 则改为从数据库回取该行。

工作单元与持久化的细节修复

  • 拓扑排序:0.1.7 修复拓扑排序算法。该算法今日仍在 util/topological.py 的 sort() / sort_as_subsets() 中用于依赖排序,并由 test/base/test_dependency.py 的 test_sort_*、test_raise_on_cycle_* 等用例持续守护。
  • 0.1.5 修复对象提交后未加载的 lazy list 被清空的属性 bug;0.1.7 修复 attributes.py 的内存泄漏("once and for all"),并修复懒加载对 = 以外比较运算符、以及 JOIN 条件中两处比较指向同一列时的支持。
  • 0.1.7 为 HistoryArraySet 增加 extend() 方法。
  • 0.1.1 两阶段 objectstore.commit(begin/commit)返回事务对象 SessionTrans,明确事务边界。
  • 0.1.5 的 ResultProxy 增加迭代器接口(for row in result: ...);engine.transaction(func) 支持 *args, **kwargs 透传,方便编写事务化装饰器。

扩展生态:mods、SelectResults、SQLSoup、ActiveMapper

0.1.5 与 0.1.6 是扩展生态的起步:

  • 0.1.5 加入 J. Ellis 的 SQLSoup 模块(扩展包),0.1.6 跟进其最新版。
  • 0.1.6 引入 mods 系统:通过 install_mods(*modnames) 安装可插拔模块来修改/增强核心功能;首个 mod 是 SelectResults,它修改 mapper 的 select 行为,把范围切片转换为 LIMIT/OFFSET 查询(作者 Jonas Borgström)。0.1.7 补交了漏掉的 selectresults.py。
  • 0.1.6 ActiveMapper(来自 TG 社区)具备初步的继承支持,0.1.4 起已支持多对多关系。

其他值得注意的变更

  • 0.1.7 的单元测试按各数据库支持能力进行资格筛选——这正是现代 test 目录中 @requirements 与方言 suite 机制(test/suite、testing/requirements.py)的最早雏形。
  • 0.1.4 增强日志:带时间戳与可配置的格式化系统。
  • 0.1.3 的 Index 对象完整实现:可独立构造,或通过 Column 的 index / unique 参数创建。
  • 0.1.3 提供模块级"默认引擎"(ProxyEngine),可用 global_connect 连接;表可在不指定引擎时创建。
  • 0.1.5 的 get_session().invalidate(*obj) 让实例在下次属性访问时自动 refresh。
  • 0.1.6 修复 backrefs 的若干问题;0.1.4 新增 backref() 函数,支持向反向引用传递关键字参数。
  • 0.1.6 为 Select 对象新增 for_update 标志。
  • 0.1.7 的 mapper 增加 always_refresh 标志(0.1.5 引入),强制刷新从数据库取回对象的全部属性,覆盖任何改动。
  • 0.1.2 修复 schema 中的递归调用——该调用此前会递归 994 次后才正常返回,"没破坏任何东西,但拖慢了所有东西"(由 jpellerin 发现)。
  • 0.1.6 文档页面基本切换为 Markdown 语法;0.1.5 对单元工作(Unit of Work)文档做了大改。

结语:从 changelog_01 看 SQLAlchemy 的"长寿基因"

changelog_01.rst 虽是 20 年前的记录,却浓缩了 SQLAlchemy 最核心的设计决策:Query 与 Session 的分离、UoW 与 Session 作用域解耦、类型系统与引擎绑定时机的后移、sql 与 schema 的层次解耦、以别名统一 eager loading、version_id 乐观锁与 post_update 解决循环依赖、以及"每版都修不完的类型系统"。这些特性大多以几乎相同的形式保留到今天(对照 lib/sqlalchemy/orm、lib/sqlalchemy/sql、lib/sqlalchemy/engine 即可逐一验证)。阅读 0.1 系列 changelog,实际上是在阅读 SQLAlchemy 现代架构的"设计说明书"。

登录后查看全文
sqlalchemy