数据存在哪儿
本合集目录
本章目录
单册说明:本文件是卷 6 的第 1 章,可独立阅读。前置:卷 5 第 8 章(联调收口)。本章不教语法,只回答一个问题——你的数据放在哪,那个位置还能撑多久,什么时候必须换。最后动手把卷 5 的 JSON 存储换成 SQLite。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 6 · 数据与状态(第 1 / 8 章) |
| 前置章节 | 5.8 联调收口 |
| 本章产出 | 一张存储选型对照表 · 一份"该换库了"的判断清单 · 一次 JSON → SQLite 的迁移 |
| 对应代码 | app/db.py、app/migrations/001_init.sql、scripts/import_json.py |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能说出你现在的存储由谁负责并发、持久化、备份,并指出哪一项它不管 |
6.1.1 一句话结论:存储的差别不在"能不能存",在"谁替你管三件事"
内存、JSON 文件、SQLite、服务式数据库,四个东西都能"存住数据"。真正的差别是三件事分别由谁负责:并发(两个人同时写会不会互相覆盖)、持久化(断电后还在不在)、备份(坏了能不能回到昨天)。
先说一个真实场景。你用卷 5 的 JSON 存储跑了三天,攒了四十多条摘录。第四天早上打开页面:
500 Internal Server Error
后端日志里是这一行:
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
data/notes.json 变成了 0 字节。原因不复杂:保存时用的是"打开文件 → 清空 → 重新写"这套流程,写到一半进程被 Ctrl+C 或系统更新重启打断,文件就停在"已清空、还没写回"的状态。.bak 你没做,四十条摘录全没了。
这不是运气差,是这个存储方案从来没有承诺过"写一半崩了怎么办"。选存储,本质是选"哪些麻烦交给别人"。
6.1.2 原理与方法
四层对照:谁在管什么
| 内存(dict / list) | JSON 文件 | SQLite | 服务式数据库 | |
|---|---|---|---|---|
| 谁管并发 | 没有人,靠 Python 的 GIL 侥幸活着 | 没有人,后写的覆盖先写的 | 数据库自己,用库级写锁 | 数据库自己,行级锁 + MVCC |
| 谁管持久化 | 没有人,进程一停就没 | 你自己,open + write + flush |
数据库自己,事务提交才落盘 | 数据库自己,还有副本 |
| 谁管备份 | 没有人 | 你自己 cp,且要停写 |
你发一条命令,它保证一致 | 它自己定时做,还能回滚到某个时刻 |
| 能不能按条件查 | 要自己写循环筛 | 全读进内存再筛 | SQL,可以走索引 | SQL |
| 两人同时写 | 一个覆盖一个 | 文件直接损坏或丢更新 | 排队,第二个等锁 | 排队,粒度更细 |
| 十万条数据 | 内存吃紧 | 每次请求全量解析,几十毫秒起 | 毫秒级,走索引更快 | 毫秒级 |
| 典型失效 | 重启即失 | 半截文件、编码错乱 | 锁等待、单机上限 | 网络、连接池、账单 |
这张表只说明一件事:你少管的每一件事,都要有人管;没人管,就在最坏的时刻爆发。
什么时候该换:五条判断
不要因为"SQLite 听起来低级"就换,也不要因为"JSON 还能跑"就不换。逐条问自己:
| # | 问题 | 答"是"意味着 |
|---|---|---|
| 1 | 数据丢了,用户会不会真的生气? | 需要事务与备份,JSON 出局 |
| 2 | 有没有"两条记录必须一起改"的操作? | 需要事务,文件存储做不到 |
| 3 | 数据量会不会超过"一次全读进内存"的舒适区(约几万条)? | 需要索引与分页查询 |
| 4 | 会不会有第二个写者(另一个进程、另一个部署实例)? | 需要真正的并发控制 |
| 5 | 会不会有人问"上个月这条记录是什么样"? | 需要备份与时间点恢复 |
前三条任意一条答"是",就该从 JSON 换到 SQLite。第 4、5 条答"是",SQLite 也要打问号。
SQLite 的适用与不适用
SQLite 不是"玩具数据库",它是嵌入式数据库:没有独立进程,你的程序直接读写一个文件。手机、浏览器、飞机娱乐系统里都有它。
| 场景 | 合适吗 | 原因 |
|---|---|---|
| 个人站点、单机部署、读多写少 | 很合适 | 零运维,备份就是一个文件 |
| 一次请求写几条、并发几十 | 合适 | 写锁是毫秒级持有,排队感知不到 |
| 数据分析、本地脚本、测试 | 很合适 | 不用起服务,sqlite3 标准库直接开 |
| 多台机器同时写同一个库 | 不行 | 锁依赖本地文件系统,网络盘上不可靠 |
| 每秒几百次写 | 不合适 | 全局只有一个写者,写会排队 |
| 需要按用户分配数据库权限 | 不合适 | 库是文件,权限就是文件权限 |
所以本书的部署形态是"一台服务器 + 一个进程",SQLite 正好。等到需要多机,换的是数据库,不是"SQLite 不好"。
那什么时候轮得到服务式数据库(PostgreSQL、MySQL 这类要单独起进程、单独连端口的)?三个信号:写入量到了每秒几百次以上;需要多台机器同时写同一份数据;需要按表、按列授权给不同的人。除此之外,它给你的是更多能力,也给你更多要维护的东西:连接池、用户与权限、版本升级、备份策略、监控。单机项目上它不解决任何你现有的问题,只是把"运维一个文件"换成"运维一个服务"。
迁移成本为什么主要不在 SQL
很多人以为换库的难点是"SQL 方言不一样"。实际做一次就知道,SQL 那部分占不到两成:
| 环节 | 工作量感受 | 具体是什么 |
|---|---|---|
| SQL 方言 | 小 | AUTOINCREMENT、strftime 这类函数各库写法不同 |
| 连接管理 | 中 | 文件存储没有"连接"概念,改成库之后要决定何时开、何时关、谁来关 |
| 事务边界 | 大 | 原来的代码是"一行行写文件",现在要回答"哪几条必须一起成功" |
| 查询方式 | 大 | 原来是"全读出来再 for 循环筛",现在要写成 WHERE,还要考虑分页 |
| 数据迁移 | 小 | 一次性脚本,跑完就删 |
| 并发假设 | 中 | 原来假设"只有一个请求在写",现在要假设"随时可能有第二个" |
结论:如果你的代码里到处是 open() 和 json.dump(),换库等于重写业务逻辑。 这正是第 4 章要分层的理由——把这些"到处"收进一个 storage 层,下次换库才只改一层。
6.1.3 动手:把 JSON 存储改成 sqlite3,先能读写
目标不大:能建表、能插入、能按用户列出来。接口层不动。
第一步:建表语句单独放一个文件
-- app/migrations/001_init.sql
CREATE TABLE users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
email TEXT NOT NULL UNIQUE,
password_hash TEXT NOT NULL,
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
);
CREATE TABLE notes (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
title TEXT NOT NULL,
content TEXT NOT NULL,
source_url TEXT,
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
);
这两个表本章够用。tags 与 note_tags 第 2 章再加。
时间字段为什么用 TEXT 而不是 DATETIME:SQLite 没有真正的日期类型,存成 2026-11-17T09:12:03Z 这种固定格式的字符串,排序就是字典序,跨语言也不会解析失败。
第二步:一个文件管住所有连接
# app/db.py(本章版本,第 5 章再补事务与迁移)
import sqlite3
from pathlib import Path
DB_PATH = Path(__file__).resolve().parent.parent / "data" / "dudao.db"
def connect() -> sqlite3.Connection:
con = sqlite3.connect(
DB_PATH,
timeout=5.0, # 等锁最多 5 秒
isolation_level=None, # 关掉隐式事务,后面自己发 BEGIN
)
con.row_factory = sqlite3.Row
con.execute("PRAGMA foreign_keys = ON")
con.execute("PRAGMA journal_mode = WAL")
return con
三个参数各有原因,第 3、5 章会逐个拆开讲。现在只需要记住:整个项目里只有这个文件出现 sqlite3.connect。
第三步:读写各一个函数
# 本章先放在 db.py 末尾,第 4 章会搬到 storage/notes.py
def list_notes(con, user_id: int) -> list[dict]:
rows = con.execute(
"SELECT id, title, content, source_url, created_at "
"FROM notes WHERE user_id = ? ORDER BY id DESC",
(user_id,),
).fetchall()
return [dict(r) for r in rows]
def insert_note(con, user_id: int, title: str, content: str, source_url: str | None) -> int:
cur = con.execute(
"INSERT INTO notes(user_id, title, content, source_url) VALUES (?,?,?,?)",
(user_id, title, content, source_url),
)
con.commit()
return cur.lastrowid
注意 ? 和后面的元组:值永远走参数,不拼字符串。这一条在第 3 章会用一个"删库现场"证明它有多重要。
第四步:把老数据搬进来
# scripts/import_json.py(节选)
raw = json.loads(Path("data/notes.json").read_text(encoding="utf-8"))
items = raw["notes"] if isinstance(raw, dict) else raw
owner = con.execute("SELECT id FROM users WHERE email = ?", (OWNER_EMAIL,)).fetchone()
for item in items:
note_id = store.insert_note(con, owner["id"], item["title"], item["content"], item.get("source_url"))
store.set_tags(con, owner["id"], note_id, item.get("tags", []))
真实跑一次的输出:
导入 3 条,该账号现在共 3 条
(1, 1, 'SQLite 的事务', 1)
(2, 1, 'Python 的 with', 1)
(3, 1, '读书笔记', 2)
最后一行是 LEFT JOIN note_tags 数出来的标签个数,证明多对多的关系也搬过来了。
迁移的铁律:旧文件不要删。改名成 notes.json.bak 放一周,确认线上数据对得上再删。迁移脚本跑第二遍会插重复数据,所以它只能跑一次——要么加个"已导入"标记,要么跑完就把脚本从流水线里摘掉。
第五步:验证"重启后还在"
不重启验证等于没验证。内存存储在同一个进程里也"读得到"。所以要做的动作是:
Ctrl+C停掉服务,再uvicorn app.main:app起来;- 刷新列表页,条数不变;
- 换一个终端,确认文件真的在磁盘上:
python -m sqlite3 data/dudao.db "SELECT COUNT(*) FROM notes"
Windows 上没有 sqlite3 命令也能用这条(python -m sqlite3 是标准库自带的极简命令行)。三行都对上,才叫"换成功了"。第 3 章会把这条命令的用法讲全。
6.1.4 三个坑
坑一:数据库文件"自己变空了",其实是你读错了文件
症状:迁移明明成功,重启服务后列表全空。data/ 下出现两个 dudao.db,一个 60KB 一个有内容,另一个 0 字节。
成因:连接用的是相对路径 sqlite3.connect("data/dudao.db")。相对路径相对于进程的当前工作目录。你在 backend/ 下启动是 backend/data/dudao.db,在仓库根目录用 uvicorn backend.app.main:app 启动就变成 ./data/dudao.db——新目录、新空库,SQLite 会很乐意帮你建一个。
修法:路径一律由 Path(__file__).resolve().parent 推出来,写成绝对路径。这也是 db.py 里那行的意义:配置的基准是文件位置,不是你在哪儿敲命令。
坑二:插入了,但另一个连接看不到
症状:脚本里 INSERT 成功,SELECT 也查得到;用另一个终端打开数据库,一条都没有。进程退出后再看,数据又没了。
成因:Python 的 sqlite3 默认 isolation_level="",会替你隐式开事务,close() 遇到未提交的事务是回滚而不是提交。少写一句 commit(),数据就停在事务里等着被丢弃。
修法:要么显式 con.commit(),要么用第 5 章的 with transaction(con)。本书统一选后者:把"提交"写成一个只能用对的形状,而不是靠每次记得。
坑三:把库文件放进同步盘/网络盘,锁开始随机失灵
症状:本地一切正常,部署到挂载的网络盘(或某网盘同步目录)后,偶发 sqlite3.OperationalError: database is locked,重试又好,过一会儿再犯。
成因:SQLite 的锁依赖操作系统的文件锁语义。网络文件系统(NFS、SMB)对 fcntl 锁的实现不完整,两个客户端可能都以为自己拿到了锁。SQLite 官方文档对此的措辞是"不要这么做"。
修法:库文件放本地磁盘。需要多机共享数据,答案是换成服务式数据库,不是"把 SQLite 放网上"。备份文件可以同步,正在使用的库文件不行。
本章验收
- 能画出四种存储在"并发 / 持久化 / 备份"上的责任划分
- 能用五条判断说出自己项目现在该不该换库,并给出理由
-
data/下只有一个dudao.db,且服务重启后数据还在 - 老 JSON 的数据全部导入,条数与标签数对得上
- 能在代码里指出"哪一行决定了数据库文件的位置"
自测
Q1:为什么"用 json.dump 保存"会在断电时把整个文件弄坏,而 SQLite 不会?
看答案
`json.dump` 的写法通常是先截断文件再写入,写入过程没有任何保护:断电时文件可能停在"已清空、写了一半"的中间态,而且旧内容已经被覆盖,回不去。SQLite 修改数据时先写日志(WAL 或 rollback journal),提交那一刻才把改动落到主文件;中途崩溃,下次打开会自动用日志回滚到"上一次完整提交"的状态。它保证的不是"不丢最后一次写",而是"不会留下一个自相矛盾的文件"。Q2:一个人用的小站,一天几十次写入,用 SQLite 有什么风险?
看答案
几乎没有风险,这个量级 SQLite 完全够用。要注意的是三件事:库文件必须在本地盘;只能有一个进程写(多 worker 部署要谨慎,虽然能跑,但锁竞争会变多);备份要按第 8 章的方法做,不能直接 `cp` 正在写的库文件。真正的风险来自"以后想多机部署",那是换库的信号,不是 SQLite 的缺陷。Q3:为什么说"迁移成本主要在代码结构,不在 SQL"?
看答案
因为 SQL 语句的数量是有限的,改写它们是一次性工作,半天到两天能完成。真正贵的是散落在业务代码里的假设:数据在内存里可以直接 `.append`、文件读写不需要事务、只有一个请求在写、查询就是 `for` 循环过滤。这些假设没有写在任何地方,却决定了每一处代码怎么写。把它们收进一层(第 4 章),换库才是一次替换而不是一次重写。下一步
存储选好了,接下来得会跟它说话。下一章从"表为什么这么设计"开始,把四张表建出来,再用六条查询把数据问出来。