跳到正文
零到全栈 · 卷 6 · 数据与状态

事务、并发与迁移

本合集目录
本章目录

单册说明:本文件是卷 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 按编号顺序排列的脚本,一个文件一次变更
一个跑批函数 读出已执行的最大编号,把之后的脚本按顺序执行,每条记一行

三条规则,比代码更重要:

  1. 只增不改:已经执行过的迁移文件永远不回头编辑,要改就加一个新文件。别人机器上那个文件已经跑过了。
  2. 可重复执行:CREATE TABLE IF NOT EXISTS、INSERT OR IGNORE,让"跑到一半崩了再跑"不会炸。
  3. 跑前先备份:迁移失败最坏的情况是数据还在、结构半新半旧;有备份就能退回去。

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,把无状态协议补上有状态。

→ 卷6-06-状态与会话.md