Python 与 SQLAlchemy（Python & SQLAlchemy）

前置知识#

• 元类：建议先完成前一篇的学习

学习目标#

• 掌握「1. 历史动机与演化」的核心机制、典型用法与常见陷阱
• 掌握「2. 形式化定义」的核心机制、典型用法与常见陷阱
• 掌握「3. 理论推导与证明」的核心机制、典型用法与常见陷阱
• 掌握「4. 代码示例」的核心机制、典型用法与常见陷阱
• 掌握「5. 对比分析」的核心机制、典型用法与常见陷阱

“SQLAlchemy is not an ORM, it’s a database toolkit that happens to include an ORM.” —— Michael Bayer, SQLAlchemy Creator

1. 历史动机与演化#

1.1 SQL 与对象世界的鸿沟#

关系型数据库（RDBMS）与面向对象编程语言（OOPL）之间存在著名的”对象关系阻抗失配”（Object-Relational Impedance Mismatch）。1990 年代后期，随着 Java、Python 等 OO 语言的兴起，开发者急需一种工具弥合这一鸿沟。

阻抗失配的具体表现：

1.2 ORM 的早期探索#

1995 年：DAO（Data Access Object）模式 Sun Microsystems 在 J2EE 蓝图中提出 DAO 模式，将数据库访问封装在独立对象中，但开发者仍需手写大量 SQL 与结果集映射代码。

2001 年：Hibernate 1.0 Gavin King 发布 Hibernate，引入”透明持久化”（Transparent Persistence）概念——业务对象无需继承特定基类或实现接口即可持久化。Hibernate 采用 Active Record 模式（后由 Rails 推广）的变体：Data Mapper 模式。

2002 年：Martin Fowler《Patterns of Enterprise Application Architecture》 Fowler 系统化定义了三种数据库访问模式：

• Table Data Gateway：一个对象代表一张表，提供查询方法。
• Row Data Gateway：一个对象代表一行记录，提供 insert/update/delete。
• Data Mapper：一个独立的映射器层负责对象与表的双向转换，对象本身不感知数据库。

2003 年：Rails Active Record David Heinemeier Hansson 在 Ruby on Rails 中推广 Active Record 模式——模型类直接继承 ActiveRecord::Base，类即表，实例即行，属性即列。Active Record 简单直接，但与领域模型解耦困难。

1.3 SQLAlchemy 的诞生#

2005 年 5 月：SQLAlchemy 0.1 Michael Bayer（Twitter: @zzzeek）发布 SQLAlchemy 0.1。Bayer 的设计哲学与 Active Record 截然不同：

“SQLAlchemy’s philosophy is that the relational database is a powerful tool, and developers should not be shielded from it. Instead, SQLAlchemy provides a thin layer that makes working with SQL more Pythonic, while preserving the full power of SQL.”

核心设计决策：

1. 双层架构：Core 层提供 SQL 表达式语言，ORM 层构建于 Core 之上，开发者可自由选择抽象层级。
2. Data Mapper 模式：ORM 层采用 Data Mapper 而非 Active Record，模型类不绑定 Session，业务对象与持久化分离。
3. Unit of Work：Session 实现 Fowler 的 Unit of Work 模式，自动追踪对象变更，统一提交。
4. 显式优于隐式：查询使用显式 select 构造器，而非 Django ORM 的”链式查询管理器”。
5. 方言抽象：通过 Dialect 层抽象不同数据库的差异，支持 PostgreSQL、MySQL、SQLite、Oracle、SQL Server 等。

1.4 SQLAlchemy 的演化路径#

SQLAlchemy 1.x（2005-2020）：

• 1.0（2015）：引入新的 Query API，统一 ORM 与 Core 查询接口。
• 1.1（2016）：性能优化，引入 baked queries 缓存编译结果。
• 1.2（2017）：引入 inspect() 系统，统一模型反射与元数据查询。
• 1.3（2019）：异步支持预览（实验性），CTE 与窗口函数完善。
• 1.4（2020）：作为 2.0 的”过渡版本”，引入全新的 2.0 风格 API（select 构造器、Session.execute），同时保留 1.x 兼容。

SQLAlchemy 2.0（2023）：

2023 年 1 月发布，是一次重大架构升级，核心变化：

1. 全新查询 API：废弃 Query 对象，统一使用 select 构造器，ORM 与 Core 查询接口完全统一。
2. 类型注解优先：引入 Mapped[T] 与 mapped_column，类型注解成为模型定义的一等公民，与 mypy、Pyright 等静态类型检查器深度集成。
3. DeclarativeBase：废弃 declarative_base() 工厂函数，改用继承式 DeclarativeBase 基类。
4. Session.execute：所有查询通过 session.execute(stmt) 执行，返回 Result 对象，废弃 session.query(...).all() 风格（仍兼容）。
5. 异步一等公民：AsyncSession、AsyncEngine 与同步 API 对等，不再是实验性特性。
6. 删除 1.x 遗留：移除大量 1.x 兼容代码，包括 declarative_base()、Query 对象的链式 API、旧式字符串过滤等。

SQLAlchemy 2.1+（2024 及以后）：

• 持续完善类型注解支持。
• 性能优化，减少反射开销。
• 异步驱动生态完善（asyncpg、aiosqlite、asyncmy）。

1.5 与其他 ORM 的演化对比#

2. 形式化定义#

2.1 ORM 的形式化定义#

定义 3.1（对象关系映射）：给定对象模型 $O = (C, A, R)$（其中 $C$ 为类集合，$A$ 为属性集合，$R$ 为关系集合）与关系模型 $R = (T, F, K)$（其中 $T$ 为表集合，$F$ 为字段集合，$K$ 为键/外键集合），ORM 是一个双射函数 $\phi: O \leftrightarrow R$，满足：

$\forall c \in C, \exists t \in T, \phi(c) = t$ $\forall a \in A_c, \exists f \in F_t, \phi(a) = f$ $\forall r \in R, \exists k \in K, \phi(r) = k$

且 $\phi$ 保持以下不变量：

1. 类型不变量：$c$ 的实例类型与 $t$ 的字段类型兼容（如 str ↔ VARCHAR）。
2. 标识不变量：$c$ 的主键等于 $t$ 的主键。
3. 关系不变量：$c_1$ 引用 $c_2$ 等价于 $t_1$ 的外键引用 $t_2$ 的主键。

2.2 Unit of Work 模式的形式化定义#

定义 3.2（Unit of Work）：给定会话 $S$，对象集合 $O = \{o_1, o_2, \dots, o_n\}$，$S$ 维护以下四个映射：

• Identity Map：$\text{idmap}: (C, \text{pk}) \to o$，保证同一主键的对象在同一会话中唯一。
• New：$\text{new} \subseteq O$，待插入的对象集合。
• Dirty：$\text{dirty} \subseteq O$，已修改的对象集合。
• Deleted：$\text{deleted} \subseteq O$，待删除的对象集合。

当调用 S.commit() 时，$S$ 执行以下原子操作：

$\text{commit}(S) = \text{flush}(S.\text{new} \cup S.\text{dirty} \cup S.\text{deleted}) \land \text{transaction.commit}()$

其中 $\text{flush}$ 将变更同步到数据库（执行 INSERT/UPDATE/DELETE），$\text{transaction.commit}$ 提交事务。

2.3 Identity Map 的形式化定义#

定义 3.3（Identity Map）：给定会话 $S$ 与类 $C$，主键 $pk$，Identity Map 是一个函数：

$\text{idmap}: (C, pk) \to o \cup \{\bot\}$

满足：若 $\text{idmap}(C, pk) = o$，则 $o \in S$ 且 $o.\text{class} = C$ 且 $o.pk = pk$。

Identity Map 保证同一会话内，对同一主键的多次查询返回同一对象实例（x is y 为真）。

2.4 对象状态机的形式化定义#

定义 3.4（ORM 对象状态）：给定对象 $o$ 与会话 $S$，$o$ 的状态 $\sigma(o, S) \in \{\text{Transient}, \text{Pending}, \text{Persistent}, \text{Deleted}, \text{Detached}\}$，状态转换由以下规则定义：