SQLAlchemy 0.1 Changelog 深度解读:2006 年诞生初期 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_bymapper 属性可被继承 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 现代架构的"设计说明书"。