事务、并发与迁移
本合集目录
本章目录
单册说明:本文件是卷 6 的第 5 章,可独立阅读。前置:第 4 章(三层重构)。本章讲清"要么全成要么全不成",把
database is locked的成因摊开,再用schema_version做一次会失败、能回滚的迁移。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 6 · 数据与状态(第 5 / 8 章) |
| 前置章节 | 6.4 分层重构 |
| 本章产出 | 一个 transaction() 上下文管理器 · 一次回滚实验 · 一次锁冲突实验 · 一套最小迁移机制 |
| 对应代码 | app/db.py、app/migrations/*.sql、app/services/notes.py |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 拿到一段写库代码,能指出它的"事务从哪开始、到哪结束",以及失败时哪些行会回滚 |
6.5.1 一句话结论:一组必须一起成立的写,必须包在一个事务里
事务要解决的问题只有一句话:中途失败时,前面已经写进去的东西要不要撤回来。
看一个真实后果。create_note 原来写成两步,没有事务:
note_id = store.insert_note(con, user_id, title, content, source_url)
store.set_tags(con, user_id, note_id, tags) # 这一步抛异常
比如挂标签那一步撞上写锁等待超时,抛 sqlite3.OperationalError。接口返回 500,用户看到"保存失败",重试两次,三次都失败。但数据库里已经躺了三条摘录:
id | title | 标签数
8 | 读书笔记 | 0
9 | 读书笔记 | 0
10 | 读书笔记 | 0
用户看到的是"保存失败"和"列表里多了三条空记录"。"失败"这个动作本身写进去了,这是事务缺失最典型的症状:状态停在半路。
这里的异常换成任何一种都一样——校验没通过、外键不满足、写锁等不到、进程被杀,只要它发生在"插主表之后、挂标签之前",结果都是同一种半成品。
其中最常撞见的一种,是锁:
sqlite3.OperationalError: database is locked
SQLite 一次只允许一个写者。这不是配置问题,是设计:它用"整个库一把写锁"换来了"零配置、零运维"。所以"半成品"和"锁"往往是同一个故事的两面——锁超时发生在两步之间,就留下半成品;发生在第一步之前,就只是一次干净的失败。
6.5.2 原理与方法
四个保证,用大白话讲
| 名字 | 人话 | 在本项目里的体现 |
|---|---|---|
| 原子性 Atomicity | 要么全成,要么全不成 | 插摘录和挂标签绑在一起,任一失败全撤 |
| 一致性 Consistency | 写完的数据满足所有约束 | 外键、UNIQUE、NOT NULL 在提交时统一检查,不合格就整体失败 |
| 隔离性 Isolation | 别人看不到你还没提交的中间状态 | 你的 INSERT 提交前,别的连接查不到它 |
| 持久性 Durability | 提交之后断电也在 | COMMIT 返回时,日志已经落盘 |
四个里最容易忽略的是隔离性。它不是"防止别人捣乱",而是"防止别人看到你的半成品"——上面那个"三条空记录",如果有事务,别人根本看不到中间态,因为它们从未被提交。
事务边界怎么定
| 原则 | 具体做法 | 违反的后果 |
|---|---|---|
| 一个业务动作 = 一个事务 | "新建摘录"包含插主表和挂标签,一个事务 | 半成品数据 |
| 事务里不做慢操作 | 不发 HTTP、不发邮件、不写大文件 | 写锁被长时间持有,全站排队 |
| 越短越好 | 先算好、先校验完,再 BEGIN |
锁等待上升,database is locked 变多 |
| 读也放进事务(需要一致读时) | "先查余额再扣"必须同事务 | 别人在这两步之间改掉,扣错 |
最后一条常被漏掉。"读-改-写"如果读在事务外,读到的是旧值:
row = con.execute("SELECT balance FROM accounts WHERE id = 1").fetchone() # 事务外
con.execute("BEGIN IMMEDIATE")
con.execute("UPDATE accounts SET balance = ? WHERE id = 1", (row[0] - 30,))
con.execute("COMMIT")
两个请求都读到 100,都扣 30,最后余额 70 而不是 40——丢了 30 块,还不报错。
BEGIN 的三种模式
SQLite 的 BEGIN 有三种拿锁时机,选错会死锁:
| 写法 | 什么时候拿写锁 | 适合 |
|---|---|---|
BEGIN(= DEFERRED) |
第一条写语句才拿 | 只读事务,或"先读后写且能接受重试" |
BEGIN IMMEDIATE |
语句执行时立刻拿 | 写事务的默认选择 |
BEGIN EXCLUSIVE |
立刻拿,且挡住所有读 | 极少用,比如离线维护 |
为什么写事务要用 IMMEDIATE:DEFERRED 模式下你先读(拿读锁)、再写(要把读锁升级成写锁),如果此时别人也在升级,两个都等对方释放,SQLite 会直接判死锁并返回 database is locked。IMMEDIATE 一上来就排队拿写锁,把"升级"这个动作消灭了。
还有一个新手常撞的错:事务不能嵌套。service 里已经 with transaction(con),再调一个内部也开了事务的函数,会得到:
sqlite3.OperationalError: cannot start a transaction within a transaction
SQLite 没有 SAVEPOINT 之外的嵌套事务。解法不是"改成内层不开事务",而是让事务的所有权只落在一层:service 开,storage 不开;storage 的函数假定"调用我的人已经开了事务"。这条约定写进代码注释,比事后排查便宜得多。
Python 里三种写法,只有一种推荐
| 写法 | 提交时机 | 回滚时机 | 问题 |
|---|---|---|---|
默认 isolation_level="" |
你手动 commit() |
close() 时未提交则回滚 |
隐式开事务,CREATE INDEX 会被卷进去(第 3 章坑三) |
with con: |
块正常结束 | 块抛异常 | 不会发 BEGIN IMMEDIATE,写锁时机不可控 |
自定义 transaction(con) |
块正常结束 | 块抛异常 | 没有,本书用它 |
@contextmanager
def transaction(con):
con.execute("BEGIN IMMEDIATE")
try:
yield con
except Exception:
con.execute("ROLLBACK")
raise
else:
con.execute("COMMIT")
raise 那一行不能省。省了它,异常被吞掉,上层以为成功了,用户看到 200,数据却没写——比报错难查十倍。
写锁、WAL 与 database is locked
| 默认的 DELETE 模式 | WAL 模式 | |
|---|---|---|
| 写的时候能不能读 | 能读(写者持 RESERVED 锁) | 能读,读的是旧快照 |
| 提交那一刻 | 需要 EXCLUSIVE,短暂的"谁都别动" | 只追加日志,读完全不受影响 |
| 读的时候能不能写 | 不能,要等读完 | 能 |
| 同时几个写者 | 1 个 | 1 个 |
| 额外文件 | -journal |
-wal 和 -shm |
WAL 让"读不挡写、写不挡读",但写者仍然只有一个。所以 database is locked 的成因永远是这四类之一:
| 成因 | 现场 | 修法 |
|---|---|---|
| 两个写事务撞上,没等 | 第二个立刻报错 | 设 timeout / PRAGMA busy_timeout |
| 有事务开着没提交 | 某个请求卡住,锁一直不放 | 缩短事务,检查异常路径有没有漏 ROLLBACK |
| 连接被别的线程用 | SQLite objects created in a thread... |
一请求一连接,不跨线程 |
| 库在网络盘/同步盘 | 偶发、重启就好 | 换本地磁盘 |
timeout=5.0 的意思是"等锁最多 5 秒",等不到才抛错。这个参数不是越大越好:5 秒已经能让用户感觉到卡;真需要等更久,说明写太频繁,该考虑减少写入或换库。
迁移:表结构一定会变
第一版四张表不够用了,你要加 is_favorite。手工在服务器上 ALTER TABLE 是最常见的错误:本地库改了、线上没改,或者反过来,代码一跑就 no such column。
最小可用的迁移机制只有三样东西:
| 组成部分 | 作用 |
|---|---|
schema_version 表 |
记着"已经执行到第几号" |
migrations/00N_xxx.sql |
按编号顺序排列的脚本,一个文件一次变更 |
| 一个跑批函数 | 读出已执行的最大编号,把之后的脚本按顺序执行,每条记一行 |
三条规则,比代码更重要:
- 只增不改:已经执行过的迁移文件永远不回头编辑,要改就加一个新文件。别人机器上那个文件已经跑过了。
- 可重复执行:
CREATE TABLE IF NOT EXISTS、INSERT OR IGNORE,让"跑到一半崩了再跑"不会炸。 - 跑前先备份:迁移失败最坏的情况是数据还在、结构半新半旧;有备份就能退回去。
SQLite 的 ALTER TABLE 只支持"加列、改名、删列"这几种,改类型、改约束都得走"重建表":
| 想改什么 | 能不能直接 ALTER | 做法 |
|---|---|---|
| 加一列(可带默认值) | 能 | ALTER TABLE notes ADD COLUMN is_favorite INTEGER NOT NULL DEFAULT 0 |
| 删一列 | 能(较新版本) | ALTER TABLE notes DROP COLUMN x |
| 改列类型 / 改 NOT NULL / 加 CHECK | 不能 | 建新表 → 拷数据 → 删旧表 → 改名 |
| 改表名 | 能 | ALTER TABLE old RENAME TO new |
重建表的顺序有讲究:关外键 → 开事务 → 建新表 → INSERT INTO new SELECT ... FROM old → 删旧表 → 改名 → 提交 → 开外键 → PRAGMA foreign_key_check。少一步"关外键",DROP TABLE 会按 ON DELETE CASCADE 把子表数据一起带走。
6.5.3 动手:让失败真的发生三次
第一次:转账中途失败
def transfer(con, src, dst, amount, fail=False):
con.execute("BEGIN IMMEDIATE")
try:
row = con.execute("SELECT balance FROM accounts WHERE id = ?", (src,)).fetchone()
if row[0] < amount:
raise ValueError("余额不足")
con.execute("UPDATE accounts SET balance = balance - ? WHERE id = ?", (amount, src))
if fail:
raise RuntimeError("中途出错:目标账户冻结")
con.execute("UPDATE accounts SET balance = balance + ? WHERE id = ?", (amount, dst))
con.execute("COMMIT")
except Exception:
con.execute("ROLLBACK")
raise
两次调用,一次故意失败,一次正常:
捕获: 中途出错:目标账户冻结
回滚后余额: [(1, 100), (2, 100)]
成功后余额: [(1, 70), (2, 130)]
第一行证明"扣款已经执行了"——UPDATE 确实跑过;第二行证明它被撤回了。这就是原子性:不是"没执行",是"执行了但不算数"。
第二次:八个线程同时写
con = sqlite3.connect(DB, timeout=0.0, isolation_level=None) # 不等锁
8 个线程各写 20 次,共 160 次:
timeout=0 成功= 20 冲突= 140 最终值= 20
只有 20 次成功,140 次撞在锁上。把 timeout 改成 0.2 再跑:
retry=False 成功=160 冲突=0 最终值=160
160 次全成功,最终值不多不少。差别只有一行参数:等锁,还是立刻放弃。 生产里用 5 秒,够等一次正常的写完成。
第三次:一个会失败的迁移
# app/db.py
for path in sorted(MIGRATIONS_DIR.glob("*.sql")):
version = int(path.name.split("_", 1)[0])
if version in done:
continue
with transaction(con):
for stmt in _split_sql(path.read_text(encoding="utf-8")):
con.execute(stmt)
con.execute("INSERT INTO schema_version(version) VALUES (?)", (version,))
造一个坏文件 003_bad.sql,里面故意写两条一样的建表语句:
迁移失败: OperationalError table t3 already exists
t3 是否存在: 0
schema_version: [(1,), (2,)]
三行输出合起来说明:迁移失败时,那条已经成功的 CREATE TABLE 被回滚了,版本号也没动。 修好文件重跑,从 003 继续,不需要手工清理。
再跑一次正常的 migrate(),输出是空的——已经执行过的版本会被跳过。这就是"幂等":跑一次和跑十次,结果一样。
6.5.4 三个坑
坑一:事务里发 HTTP 请求,全站开始 503
症状:加了一个"保存摘录时顺便调大模型做摘要"的功能,上线后并发一高,所有接口间歇性 503,日志里 database is locked 密集出现。
成因:BEGIN IMMEDIATE 之后发出了一个 3 秒的网络请求。这 3 秒里写锁一直被这个请求持有,其他所有写请求都在排队,排满 5 秒后集体超时。
修法:把外部调用挪到事务外。先请求、拿到结果,再开事务写库;或者先写库(事务短),再异步补摘要。判断标准:事务体内只允许出现内存计算和数据库操作,出现 requests.、httpx.、open( 就该警惕。
坑二:executescript 悄悄提交了,回滚只回滚了一半
症状:迁移脚本里用了 con.executescript(sql),其中第三条语句报错,你以为事务会回滚,结果前两条已经生效,库里半新半旧。
成因:executescript 在开始前会隐式提交挂起的事务。实测:
executescript 之后 in_transaction = False
ROLLBACK 报错: cannot rollback - no transaction is active
表还在吗: ['a', 'b']
你精心写的 BEGIN 被它自己提交掉了,之后的 ROLLBACK 无事务可回。
修法:迁移脚本按分号拆成单条语句逐条 execute(本书 _split_sql() 做的就是这件事),全部包在一个事务里。或者接受"每个文件是一个原子单位"的粗粒度,但那就得保证脚本本身可重复执行。
坑三:重建表时忘了关外键,子表被清空
症状:为了给 notes.title 加一个 CHECK 约束,按"建新表 → 拷数据 → 删旧表"操作。执行完发现 note_tags 空了,所有标签关系全没了。
成因:DROP TABLE notes 时外键是开着的,note_tags.note_id 上的 ON DELETE CASCADE 被触发,子表跟着删。整个过程还在一个事务里,提交后无法撤销。
修法:重建前 PRAGMA foreign_keys=OFF,重建后 ON,并且用 PRAGMA foreign_key_check 验证一遍(返回空列表才算干净)。注意这个 PRAGMA 不能在事务中间切换,必须放在 BEGIN 之前和 COMMIT 之后。
本章验收
- 转账实验跑通:失败后余额回到 100/100,成功后为 70/130
- 能把
timeout从 0 改成 0.2,看 160 次写从"成功 20"变成"成功 160" - 能用坏迁移文件复现"整体回滚 + 版本号不变"
- 能说出
BEGIN IMMEDIATE与BEGIN的区别,以及为什么写事务选前者 - 能在自己的代码里指出每处事务的起止行,并说明为什么这么划
自测
Q1:为什么"先查余额,再扣款"必须放在同一个事务里?
看答案
因为这两步之间存在一个时间窗口。读在事务外,读到的是某一刻的快照;写的时候别人可能已经改过了。两个请求都读到 100、都扣 30,最终余额是 70 而不是 40,钱凭空多出来 30,而且没有任何报错。放进同一个 `BEGIN IMMEDIATE` 之后,第二个请求拿不到写锁,只能在第一个提交后重新读,读到 70 再扣,结果才对。Q2:database is locked 出现了,第一反应该是什么?
看答案
先分清是"等得不够"还是"有人不放手"。看有没有长事务(事务里做了慢操作)、有没有异常路径漏了 `ROLLBACK`、有没有连接跨线程共用。如果这些都没有,只是并发写密集,先调 `busy_timeout` 缓解,再考虑减少写入次数或换库。直接加 `timeout=60` 是最差的选择——它把"报错"变成了"卡住一分钟",用户体验更糟。Q3:为什么迁移文件执行过之后就不能再改?
看答案
因为 `schema_version` 记的是"这个编号执行过了",不是"这个编号的内容是什么"。你本地改了文件内容,版本号还是 002,跑批时会被跳过;而别人的机器上那个 002 还是旧内容。两台机器的表结构从此不同,之后所有 `no such column` 都从这里来。要改结构就加 003,让所有人的执行历史一致。下一步
数据能存住了,也不再半途而废。接下来的问题是:HTTP 本身不记得你是谁,那"登录状态"到底存在哪?下一章从 cookie 讲到 session,把无状态协议补上有状态。