# 第4-3课：SQLAlchemy基础

## 一、本课定位

前两课直接使用Psycopg，已经理解连接、游标、参数化SQL、事务和Repository分层。本课开始使用SQLAlchemy 2.x，将生产项目常用的连接池、SQL工具和对象关系映射（Object Relational Mapping，ORM）引入课程。

本课不会隐藏底层原理。SQLAlchemy最终仍通过Psycopg连接PostgreSQL：

```text
业务代码
  ↓
SQLAlchemy ORM和Session
  ↓
SQLAlchemy Engine与连接池
  ↓
Psycopg
  ↓
PostgreSQL
```

本课示例会创建`course_orm_book`表，只重置`ORM-`前缀课程数据；练习创建`course_orm_product`表，只操作`ORM-P-`前缀数据。不要连接生产数据库。

## 二、本课目标

完成本课后，你将能够：

1. 解释SQLAlchemy Core和ORM的关系；
2. 使用`Engine`统一管理数据库方言和连接池；
3. 使用声明式模型映射Python类与数据库表；
4. 使用`Session`管理ORM对象和事务；
5. 使用SQLAlchemy 2.x的`select()`查询对象；
6. 完成ORM新增、查询、修改和删除；
7. 区分`flush()`、`commit()`、`rollback()`和`close()`；
8. 理解Session的工作单元和身份映射；
9. 对照JDBC、MyBatis-Plus和JPA/Hibernate理解SQLAlchemy。

## 三、SQLAlchemy解决什么问题

直接使用Psycopg时，需要自行处理：

- 创建数据库连接；
- 复用或关闭连接；
- 手写SQL；
- 把查询元组转换为对象；
- 跟踪对象修改；
- 组织提交和回滚。

SQLAlchemy提供两个主要层次：

| 层次 | 作用 |
|---|---|
| SQLAlchemy Core | Engine、连接池、SQL表达式、表元数据、方言适配 |
| SQLAlchemy ORM | 类表映射、Session、对象查询、关系和工作单元 |

ORM建立在Core之上。使用ORM并不意味着不再需要理解SQL、事务和索引。

## 四、与Java技术体系对照

| Java常见技术 | SQLAlchemy中的相近概念 | 说明 |
|---|---|---|
| JDBC Driver | Psycopg | PostgreSQL底层驱动 |
| `DataSource`和HikariCP | `Engine`和连接池 | 管理连接获取、复用和归还 |
| JPA实体 | 声明式ORM模型 | 类和表之间的映射 |
| `EntityManager` | `Session` | 管理持久化对象和事务 |
| Persistence Context | Session身份映射 | 同一Session内按主键维护对象身份 |
| Dirty Checking | Session变更跟踪 | 修改对象属性后生成UPDATE |
| JPQL/Criteria | `select()`表达式 | 用Python表达式构造查询 |
| `@Transactional` | `Session.begin()`上下文 | 正常提交、异常回滚 |

SQLAlchemy ORM总体更接近JPA/Hibernate。它也能简化常规增删改查，使用体验部分接近MyBatis-Plus，但不是以Mapper接口和SQL模板为中心。

## 五、Engine和连接池

创建Engine：

```python
engine = create_engine(
    database_url,
    connect_args={"connect_timeout": 10},
    pool_size=5,
    max_overflow=5,
    pool_pre_ping=True,
    echo=False,
)
```

Engine不是一条固定连接，而是数据库访问入口。它组合了：

- 数据库URL；
- PostgreSQL方言；
- Psycopg驱动；
- 连接池；
- SQL执行和事件机制。

### 5.1 常用连接池参数

| 参数 | 含义 |
|---|---|
| `pool_size=5` | 池中长期保留的连接数量上限 |
| `max_overflow=5` | 池满时允许临时增加的连接数 |
| `pool_pre_ping=True` | 取出连接时先检查连接是否仍可用 |
| `pool_timeout` | 连接池耗尽时最多等待多少秒 |
| `pool_recycle` | 连接存活超过指定秒数后回收更新 |

`connect_args`会把驱动专用参数交给Psycopg。本课将TOML中的`connect_timeout`传入，避免网络异常时无限等待。

`pool_size=5`不代表程序启动时立即创建5条连接。Engine通常按需创建连接。

生产应用通常在启动时创建一个Engine，不应在每个Repository方法或循环中重复`create_engine()`。

### 5.2 为什么使用URL.create()

本课使用：

```python
database_url = URL.create(
    drivername="postgresql+psycopg",
    username=database_config["user"],
    password=database_config["password"],
    host=database_config["host"],
    port=database_config["port"],
    database=database_config["dbname"],
)
```

`postgresql+psycopg`表示：

```text
数据库方言：PostgreSQL
DB-API驱动：Psycopg 3
```

结构化创建URL可以避免手工拼接连接串，也不用自己处理密码中的`@`、`:`等特殊字符。

## 六、声明式模型

先定义共同基类：

```python
class Base(DeclarativeBase):
    pass
```

再定义映射模型：

```python
class Book(Base):
    __tablename__ = "course_orm_book"

    id: Mapped[int] = mapped_column(primary_key=True)
    isbn: Mapped[str] = mapped_column(String(30), unique=True, nullable=False)
    title: Mapped[str] = mapped_column(String(100), nullable=False)
```

拆开理解：

- `Book`是可以正常创建和使用的Python类；
- `__tablename__`指定数据库表名；
- `Mapped[str]`说明ORM属性映射的Python类型；
- `mapped_column()`描述数据库列和约束；
- `Base.metadata`收集所有模型的表元数据。

调用：

```python
Base.metadata.create_all(engine)
```

会创建缺失的表，但它不是完整的数据库迁移工具，不能可靠地把已有表自动升级成新结构。后续FastAPI阶段会学习数据库迁移。

## 七、Session是什么

Session不是数据库连接本身，也不是线程安全的全局单例。它主要负责：

- 从Engine申请连接；
- 开始和结束数据库事务；
- 保存当前持久化上下文中的ORM对象；
- 跟踪新增、修改和删除；
- 在合适时机把变化同步到数据库；
- 提交或回滚事务；
- 把连接归还连接池。

创建Session工厂：

```python
session_factory = sessionmaker(
    engine,
    expire_on_commit=False,
)
```

`sessionmaker`类似统一配置后的Session工厂。生产代码让每个请求或业务任务创建自己的Session，而不是让多个并发请求共享同一个Session。

### 7.1 身份映射

Session内部维护身份映射（Identity Map）。在同一个Session中，以相同主键加载同一行时，通常会得到同一个Python对象实例：

```python
first = session.get(Book, 1)
second = session.get(Book, 1)

print(first is second)  # 通常为True
```

这与JPA持久化上下文中的实体身份概念相近。

### 7.2 工作单元

工作单元（Unit of Work）表示Session收集一组对象变化，再统一生成SQL：

```python
book = session.scalar(select(Book).where(Book.isbn == "ORM-001"))
book.price = Decimal("72.00")
```

这里只修改了Python属性，没有手写`UPDATE`。Session会识别变化，在`flush()`或提交时发送UPDATE。

## 八、Session事务写法

写操作推荐使用：

```python
with session_factory.begin() as session:
    session.add(book)
```

其行为是：

```text
创建Session
→ 开始事务
→ 执行业务
→ 正常结束时flush并commit
→ 异常时rollback
→ 关闭Session
→ 连接归还连接池
```

只读查询可以使用：

```python
with session_factory() as session:
    books = session.scalars(select(Book)).all()
```

离开Session的`with`会关闭Session并释放连接资源，但不会替你提交尚未提交的写操作。不要把“关闭Session”误认为“提交事务”。

## 九、flush与commit的区别

### 9.1 flush

```python
session.add(book)
session.flush()
print(book.id)
```

`flush()`把Session内待处理变化发送给数据库，例如执行INSERT并取得数据库生成的主键。但是：

- 当前事务仍未提交；
- 其他事务通常还看不到结果；
- 后续发生异常仍可以回滚。

### 9.2 commit

`commit()`先执行必要的`flush()`，然后提交数据库事务。提交成功后，本事务的修改成为持久结果。

### 9.3 rollback

`rollback()`撤销当前事务中未提交的数据库变化，并调整Session中的对象状态。事务失败后必须回滚或关闭Session，才能安全开始后续工作。

一句话记忆：

```text
flush：把变化发给数据库，但还可以回滚。
commit：确认事务结果，完成持久化。
```

## 十、ORM增删改查

### 10.1 新增

```python
book = Book(isbn="ORM-001", title="Python数据库编程", ...)
session.add(book)
```

多个对象使用：

```python
session.add_all([first_book, second_book])
```

### 10.2 查询

SQLAlchemy 2.x使用`select()`：

```python
statement = (
    select(Book)
    .where(Book.isbn.like("ORM-%"))
    .order_by(Book.isbn)
)
books = session.scalars(statement).all()
```

不要在本课程中使用旧式：

```python
session.query(Book).filter(...)
```

`session.scalars()`适合只需要ORM对象的查询。`session.execute()`返回更通用的结果行。

### 10.3 修改

```python
book = session.scalar(select(Book).where(Book.isbn == "ORM-001"))
book.price = Decimal("72.00")
```

Session跟踪属性变化，在flush时生成UPDATE。

### 10.4 删除

```python
session.delete(book)
```

对象会被标记为删除，DELETE在flush时发送。

## 十一、expire_on_commit

SQLAlchemy默认`expire_on_commit=True`。事务提交后，Session中的对象属性会被标记为过期；下一次访问时，Session可能重新查询数据库获取最新值。

本课使用：

```python
sessionmaker(engine, expire_on_commit=False)
```

这样提交后对象仍可读取已经加载的值，适合当前命令行示例，也常用于Web响应层。但它不代表对象永远是数据库最新状态；如果其他事务修改了数据，需要重新查询或刷新。

## 十二、完整示例

运行[sqlalchemy_crud_example.py](./sqlalchemy_crud_example.py)，会依次演示：

1. 创建Engine和连接池；
2. 创建Session工厂；
3. 根据模型创建缺失表；
4. 重置并新增课程图书；
5. `flush()`后读取数据库生成的ID；
6. 使用`select()`查询；
7. 修改对象属性并删除对象；
8. 主动抛出异常验证事务回滚；
9. 使用新Session回查最终数据。

## 十三、安装与配置

激活课程环境，在本课目录安装：

```powershell
python -m pip install -r .\requirements.txt
```

如果使用Conda管理SQLAlchemy：

```powershell
conda install -c conda-forge sqlalchemy
```

Psycopg已经在前两课安装完成。然后复制配置：

```powershell
Copy-Item .\config.example.toml .\config.toml
```

填写专用练习数据库信息。真实`config.toml`已被项目`.gitignore`排除。

## 十四、运行方法与预期结果

```powershell
python .\sqlalchemy_crud_example.py
```

关键输出类似：

```text
flush后第一本书ID：实际ID
新增后：
ORM-001｜Python数据库编程｜作者：小明｜价格：68.00
ORM-002｜SQLAlchemy实践｜作者：小红｜价格：88.00
修改并删除后：
ORM-001｜Python数据库编程｜作者：小明｜价格：72.00
失败事务已回滚：模拟后续业务失败。
失败事务回滚后：
ORM-001｜Python数据库编程｜作者：小明｜价格：72.00
```

数据库生成的ID不要求固定。重复运行会先清理`ORM-`前缀示例数据。

## 十五、常见错误

### 15.1 每个方法都创建Engine

Engine应当是应用级长生命周期对象。反复创建Engine会反复创建连接池，失去连接复用价值。

### 15.2 多个请求共享同一个Session

Session不是供多个线程或并发任务共享的全局对象。常见原则是每个线程一个Session，异步场景每个任务一个AsyncSession。

### 15.3 关闭Session却没有提交

```python
with session_factory() as session:
    session.add(book)
```

离开时Session关闭，未提交写入会被回滚。写事务使用`session_factory.begin()`或明确调用`session.commit()`。

### 15.4 把flush当成commit

`flush()`只把SQL发送到当前事务，后续异常仍会回滚。

### 15.5 提交后访问过期对象

默认配置下，提交会使对象属性过期。Session已关闭后访问需要重新加载的属性，可能出现对象已脱离Session的错误。本课通过`expire_on_commit=False`降低入门干扰。

### 15.6 使用旧式Session.query()

当前课程统一使用SQLAlchemy 2.x的`select()`、`Session.scalar()`和`Session.scalars()`。

### 15.7 把create_all当作迁移工具

`create_all()`适合创建缺失表，不负责完整版本化迁移。生产项目修改表结构通常使用Alembic等迁移工具。

## 十六、课堂练习

打开[practice.py](./practice.py)，完成商品ORM练习。题目按以下顺序组织：

1. 创建配置和声明式基类；
2. 定义Product模型；
3. 创建并初始化课程数据；
4. 使用`select()`查询；
5. 修改和删除ORM对象；
6. 验证`flush()`后的异常回滚；
7. 组织Engine、Session工厂和完整输出。

## 十七、本课小结

- Engine统一管理方言、驱动和连接池；
- Engine不是一条固定数据库连接；
- 声明式模型把Python类映射到数据库表；
- Session管理事务、身份映射和工作单元；
- `select()`是SQLAlchemy 2.x查询入口；
- 修改ORM对象属性后，Session能够跟踪变化；
- `flush()`发送SQL但不提交，`commit()`确认事务；
- Session的生命周期应位于业务函数之外；
- SQLAlchemy ORM更接近JPA/Hibernate，而不是MyBatis-Plus的直接复制。

## 十八、验收标准

- 能说明Psycopg、Engine、连接池和Session的调用层次；
- 能说明Engine为什么通常只创建一次；
- 能使用声明式模型完成类表映射；
- 能使用SQLAlchemy 2.x方式完成增删改查；
- 能解释身份映射和工作单元；
- 能区分`flush()`、`commit()`、`rollback()`和`close()`；
- 标准示例和练习的失败事务均能正确回滚；
- 未提交真实`config.toml`。