# 第5章 · 使用数据库存储内容

对应教材第 5 章：ORM 模型定义、增删改查、高级查询、表关系、数据库迁移。

本章有两个项目 + 四个纯命令行脚本，**从“类怎么变成表”到“改表结构不丢数据”一次走完**。

| 内容 | 位置 | 形式 |
|---|---|---|
| ORM 模型与增删改查（Web 版） | `ch5/` | 浏览器操作，端口 5115 |
| 模型 → 表结构 | `ch5/orm_scripts/01_models.py` | 终端输出 |
| 增删改查（脚本版） | `ch5/orm_scripts/02_crud.py` | 终端输出 |
| 高级查询 | `ch5/orm_scripts/03_query.py` | 终端输出 |
| 表关系（一对一/一对多/多对多） | `ch5/orm_scripts/04_relationship.py` | 终端输出 |
| 数据库迁移实训 | `ch5m_lab/` | 浏览器 + 终端命令，端口 5129 |

---

## 一、Web 版：`ch5/`

```bat
cd ch05\ch5
..\..\..\venv\Scripts\python.exe app.py
```

打开 <http://127.0.0.1:5115>，可以看到学生列表（每页 5 条）、添加、删除、翻页。

| 教材知识点 | 代码位置 |
|---|---|
| 初始化扩展 | `db = SQLAlchemy(app)` |
| 模型定义 | `class Student(db.Model)`，`__tablename__`、`db.Column` |
| 主键 / 非空 / 默认值 | `primary_key=True`、`nullable=False`、`default=...` |
| 建表 | `db.create_all()`（在 `seed()` 里） |
| 增 | `db.session.add(...)` + `db.session.commit()` |
| 查 + 分页 | `db.paginate(db.select(Student), page=..., per_page=5)` |
| 删 | `db.get_or_404(Student, id)` + `db.session.delete()` |
| 通用基类 `BaseModel`（统一 `__repr__`，打印对象能看清字段） | `class BaseModel` + `class Student(BaseModel, db.Model)` |
| Shell 上下文（进 `flask shell` 就能直接用 `Student`） | `@app.shell_context_processor` |

> 教材里写的是 `Student.query.paginate(...)` / `Model.query.get(id)`，
> Flask-SQLAlchemy 3.x 已改为 `db.paginate(...)` / `db.session.get(...)`，本套代码用新写法，注释里标了对照。

---

## 二、脚本版：`ch5/orm_scripts/`

四个脚本**不需要浏览器**，纯终端运行，每个都自带“删库重建 + 灌数据”，随便跑、随便改。

公共模型在 `_models.py`：四张表 `users` / `user_infos` / `articles` / `tags` + 中间表 `article_tag`。
数据库文件 `orm_demo.db` 就生成在同目录，用 DB Browser for SQLite 可以直接打开看。

```bat
cd ch05\ch5
..\..\..\venv\Scripts\python.exe orm_scripts\01_models.py
..\..\..\venv\Scripts\python.exe orm_scripts\02_crud.py
..\..\..\venv\Scripts\python.exe orm_scripts\03_query.py
..\..\..\venv\Scripts\python.exe orm_scripts\04_relationship.py
```

### 01_models.py —— 一个类怎么变成一张表

打印数据库里真实存在的表、每张表的列与类型、外键指向，以及“同一个数据在 Python 里是对象、在数据库里是行”的对照。

**结论**：一个类 = 一张表，一个属性 = 一个字段，一个实例 = 一行。

### 02_crud.py —— 增删改查四件套

| 操作 | 代码 | 说明 |
|---|---|---|
| 增 | `db.session.add(obj)` + `commit()` | 关联对象可以在构造参数里一起给 |
| 查 | `db.session.get()` / `filter_by()` / `where(like)` / `select(指定列)` | 四种最常用取数方式 |
| 改 | 直接改属性 + `commit()` | commit 时自动生成 UPDATE |
| 删 | `db.session.delete(obj)` + `commit()` | 配了 cascade 会级联删关联数据 |
| 回滚 | `db.session.rollback()` | 撤销会话里未提交的改动 |

**最重要的一句**：没有 `commit()`，数据库什么都没发生。

### 03_query.py —— 高级查询

`filter_by` vs `where`、`like`、`between`、`in_`、`and_`/`or_`、`order_by`、`limit/offset`、`paginate`、`count`/`group_by`、`join`。

每条查询都附了等价的 SQL 语句，方便把 ORM 和 SQL 对上号。

### 04_relationship.py —— 三种表关系

| 关系 | 实现要点 |
|---|---|
| 一对多 | `ForeignKey` 在“多”那边，`relationship` 在“一”那边，两边用 `back_populates` 对上名字 |
| 一对一 | `ForeignKey` 加 `unique=True`，`relationship` 加 `uselist=False` |
| 多对多 | 多一张中间表（`db.Table`），两边都用 `secondary=中间表` |

还演示了两个实战问题：

- **N+1 查询**：懒加载时遍历 3 个用户会发 1+3 条 SQL，用 `joinedload` 合成 1 条；
- **级联删除**：`cascade='all, delete-orphan'` 让删用户时自动带走他的文章和资料。

---

## 三、迁移实训：`ch5m_lab/`

教材 5.4 的内容：**给已有的表加一列，且不能丢数据**。

```bat
cd ch05\ch5m_lab
..\..\..\venv\Scripts\python.exe app.py
```

打开 <http://127.0.0.1:5129>，现在是 3 列（id / name / score）。

### 迁移三板斧（在这个目录下执行）

```bat
..\..\..\venv\Scripts\python.exe -m flask --app app db init
..\..\..\venv\Scripts\python.exe -m flask --app app db migrate -m "init students"
..\..\..\venv\Scripts\python.exe -m flask --app app db upgrade

:: 命令行里更常见的写法是先激活虚拟环境再用 flask
..\..\..\venv\Scripts\activate
flask --app app db migrate -m "add email"
flask --app app db upgrade
```

| 命令 | 干什么 | 什么时候用 |
|---|---|---|
| `db init` | 建 `migrations/` 迁移仓库 | 整个项目只做一次 |
| `db migrate -m "说明"` | 对比模型和数据库，**生成**迁移脚本 | 每次改了模型类 |
| `db upgrade` | **执行**迁移脚本，真正改表结构 | 每次 migrate 之后 |

### 实验步骤

1. 先用当前状态跑一遍页面，记下现有数据（点几个“快速添加”）。
2. 打开 `app.py`，把这一行的注释去掉：

   ```python
   # email = db.Column(db.String(50))
   ```

3. 回到终端：

   ```bat
   flask --app app db migrate -m "add email"
   flask --app app db upgrade
   ```

4. 刷新页面 —— 表头多了一列“邮箱”，**原来的数据一条没少**。

### 为什么要用迁移，而不是 `db.create_all()`

`create_all()` 只会“建不存在的表”，**不会改已存在的表**。
给 `students` 加一列，`create_all()` 什么都不做；而 `flask db upgrade` 会生成并执行 `ALTER TABLE students ADD COLUMN email VARCHAR(50)`，数据原样保留。

`migrations/versions/` 里那几个 `.py` 文件就是“数据库结构的版本历史”，可以回滚（`db downgrade`）、可以进 Git、可以交给同事复现。

---

## 常见坑

| 现象 | 原因 | 解决 |
|---|---|---|
| `no such table: students` | 建表没执行 | 跑一次 `db.create_all()`，或 `flask db upgrade` |
| `sqlite3.OperationalError: table students already exists` | 表已存在又去 create | 不用管，或先删 `.db` 文件 |
| `flask` 命令不存在 | 没激活虚拟环境 / PATH 没配 | 用 `..\..\..\venv\Scripts\python.exe -m flask ...` |
| `Error: Could not locate a Flask application` | 不在项目目录，或没有 `--app app` | `cd` 进项目，命令带上 `--app app` |
| `Target database is not up to date` | 有迁移没 upgrade | 先 `db upgrade` |
| 迁移生成了空脚本 | 模型没真正改，或 `db migrate` 前没保存文件 | 确认改了 `app.py` 并保存 |
| 数据文件被锁 | 有另一个进程在用这个 `.db` | 关掉别的服务再试 |

---

## 练习

1. 在 `ch5m_lab` 里再加一列 `phone = db.Column(db.String(11))`，走一遍 migrate + upgrade，确认数据没丢。
2. 在 `02_crud.py` 里加一段：把所有 `is_admin=False` 的用户批量改成 `True`（提示：`db.session.execute(db.update(User)...)` 或循环改属性）。
3. 在 `04_relationship.py` 里给 `joinedload` 那段加上计时（`time.perf_counter()`），对比懒加载慢多少。
4. 给 `ch5/ch5` 的列表页加一个“按成绩排序”的链接（提示：`?sort=score`，在 `db.select()` 后接 `.order_by()`）。
