Python 与 SQLAlchemy（Python & SQLAlchemy）

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

1. 学习目标（基于 Bloom 分类法）

本节按 Bloom 认知层次（Bloom’s Taxonomy）逐级给出可观察、可测量的学习目标。完成本节后，学习者应能：

1.1 记忆层（Remember）

• R1：准确陈述 SQLAlchemy 的双层架构——Core（SQL 表达式语言）与 ORM（对象关系映射），并说明二者的依赖关系（ORM 构建于 Core 之上）。
• R2：列出 SQLAlchemy 2.0 的核心组件：Engine、Connection、Session、DeclarativeBase、Mapped、mapped_column、MetaData、Table、select、Result，并能说明每个组件的职责。
• R3：背诵 Unit of Work（工作单元）模式的三个核心要素：Identity Map（身份映射）、Change Tracking（变更追踪）、Transaction Coordination（事务协调）。

1.2 理解层（Understand）

• U1：解释 Engine 与 Connection 的区别——Engine 是连接池与方言（Dialect）的持有者，Connection 是单次数据库会话的执行上下文。
• U2：阐述 Session 与 Connection 的关系——Session 是 ORM 层的工作单元，内部持有一个或多个 Connection，自动管理对象状态与数据库同步。
• U3：说明 ORM 对象的四种状态——Transient（瞬态）、Pending（待持久化）、Persistent（持久化）、Detached（游离），并能画出状态转换图。

1.3 应用层（Apply）

• A1：使用 SQLAlchemy 2.0 声明式映射（DeclarativeBase + Mapped + mapped_column）定义一对多、多对多关系模型，正确配置 relationship 与 back_populates。
• A2：使用 select 构造器编写复杂查询：JOIN、子查询、聚合、窗口函数、CTE（Common Table Expression）、EXISTS 子查询。
• A3：使用 selectinload、joinedload、subqueryload、raiseload 解决 N+1 查询问题，并能说明四种加载策略的 SQL 生成机制。

1.4 分析层（Analyze）

• An1：分析 Lazy Loading（懒加载）在异步 ORM（AsyncSession）下的致命问题——await 语义与同步描述符冲突，必须改用 selectinload 或显式 await session.refresh(..., attribute_names=[...])。
• An2：解构 Session 的”事务边界”——session.begin() vs session.commit() vs session.flush() vs session.rollback() 的语义差异与典型误用。
• An3：剖析 Detached 实例的陷阱——DetachedInstanceError 的触发条件、expire_on_commit 的影响、session.merge() 的重新附着机制。

1.5 评价层（Evaluate）

• E1：评价”何时用 Core、何时用 ORM、何时混用”的决策矩阵，考虑查询复杂度、性能要求、可维护性、团队熟悉度等维度。
• E2：审查一段使用 SQLAlchemy 的生产代码，识别潜在的 N+1 查询、Session 泄漏、Detached 实例、事务嵌套、连接池耗尽等问题。
• E3：对比 SQLAlchemy ORM 与 Django ORM、Peewee、Tortoise ORM、SQLModel、Prisma（Python 绑定）在架构、性能、生态、类型安全上的优劣。

1.6 创造层（Create）

• C1：设计一个支持多租户（multi-tenant）的 SQLAlchemy 会话工厂，根据请求上下文动态切换数据库连接（schema-level 或 database-level 隔离）。
• C2：实现一个基于 SQLAlchemy 事件系统（event.listen）的审计日志中间件，自动记录所有 INSERT/UPDATE/DELETE 操作的前后状态。
• C3：构建一个”软删除 + 版本控制”混入（mixin），通过 where 子句过滤已删除记录，并通过 transaction 表记录每次修改的历史快照。

2. 历史动机与演化

2.1 SQL 与对象世界的鸿沟

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

阻抗失配的具体表现：

2.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 简单直接，但与领域模型解耦困难。

2.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 等。

2.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）。

2.5 与其他 ORM 的演化对比

3. 形式化定义

3.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$ 的主键。

3.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}$ 提交事务。

3.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 为真）。

3.4 对象状态机的形式化定义

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