# 【AI 工作流手记 #7】只拷一个 .db 文件做离线分析，结果连表都没有：SQLite WAL 模式的复制陷阱与只读三道锁

## 起因：拷个数据库文件，怎么就"查无此表"了

事情很小：我要给一个桌面应用的本地 SQLite 库做离线分析——统计它自己记录的用量数据。约束很明确：**不能登录它的账号，更不能在原库上写一个字节**。

第一反应谁都有：把 `.db` 文件复制一份，拿副本慢慢研究。结果副本一打开，连表都查不到——`no such table: t`。原库里明明有数据，文件也确实拷过来了，几 KB 的文件躺在那儿，内容是空的。

这就是本文要讲的第一件事：**在 WAL 模式下，"把 .db 文件拷走"约等于"把账本只拿走了封面"**。下面全部结论都是当天在本机复现实测的，附完整可运行脚本。

## 关键发现 1：WAL 模式下，主库文件可能是空壳

SQLite 常见的日志模式有两种：默认的回滚日志（delete），以及 `journal_mode=WAL`。WAL（Write-Ahead Logging）的意思是：**写入先落到旁边的 `-wal` 文件里，积累到一定条件再"合并"（checkpoint）回主库文件**。

对单机应用来说这很快很好用；对"拷文件做备份/分析"的人来说是灾难：

> **只要应用还开着（或上次没正常退出），最新写入就还没进主库文件。**

我的实测复现（全部数字为当天真实运行结果）：

| 时刻 | 主库 `t.db` | `-wal` 文件 |
|---|---|---|
| 连接保持打开、已提交 2 行 | **4096 字节**（空壳） | **16512 字节**（数据都在这） |
| 执行 `wal_checkpoint(TRUNCATE)` 后 | 数据完整并入 | 截断为 0，但文件还在 |

此时只拷主库文件，副本打开直接报 `no such table: t`——**不是我丢了最近几行，而是整个库在副本眼里就是空的**（建表语句本身也还在 WAL 里没合并）。

一个容易误会的细节：执行 `wal_checkpoint(TRUNCATE)` 之后 `-wal` 文件**并不会消失**，只是被截成 0 字节；等**最后一个连接正常关闭**时 SQLite 才会做最终 checkpoint 并删掉 `-wal` / `-shm`。所以"看到 -wal 文件还在"不等于"没合并"，"看不到 -wal"也不等于"可以随便拷"——判断标准是**有没有活跃连接**。

## 关键发现 2：正确拷贝姿势，二选一

**姿势 A（推荐）：让应用正常退出后再拷。** 最后一个连接关闭时 SQLite 自动 checkpoint，主库文件完整，这时拷 `.db` 一个文件就够了。

**姿势 B（应用关不掉时）：三件套一起拷**——`.db` + `-wal` + `-shm` 一起拿走，保持三个文件的相对状态。SQLite 打开副本时会自己把 WAL 里的内容恢复出来。今天这个例子里的应用是常驻进程，等它退出不现实，走的就是这条路。

应急的第三种：如果能对**原库**执行 `PRAGMA wal_checkpoint(TRUNCATE)`（只读分析场景下通常做不到，也违背"不碰原库"），返回值 0 表示成功，之后再拷主库也行——实测这一步后拷出的副本 2 行数据完整。

## 关键发现 3：只读打开不是"我小心点"，是两道锁

分析不属于自己的库，"我会很小心不写它"是不可靠的承诺——第三方封装、ORM、甚至某些 PRAGMA 都可能在背后触发写。正确做法是把只读做进连接配置里，两道锁一起上：

```python
import sqlite3

# 第一道锁：URI 的 mode=ro，操作系统/文件层面只读
conn = sqlite3.connect("file:/path/to/data.db?mode=ro", uri=True)

# 第二道锁：会话级只读，连 SQL 层面的写入意图也一并拒绝
conn.execute("PRAGMA query_only=1")
```

实测往这两道锁里写数据，都会被同一句话顶回来：

```
sqlite3.OperationalError: attempt to write a readonly database
```

两道锁不是重复建设：`mode=ro` 在连接层就切断了写路径；`query_only=1` 是 SQL 会话层的第二道闸，防御的是"同一个连接后续被别的代码拿来执行写语句"这类意外。这种"分析工具一律只读打开、不联网、输出写进独立目录"的纪律，自从固化下来之后，我再也没有为"手滑改了别人的数据"写过道歉复盘。

## 关键发现 4：静态副本还有一个 `immutable=1` 快捷方式

如果拷出来的是**确认不再变化的静态副本**，可以再进一步：

```python
conn = sqlite3.connect("file:/path/to/copy.db?immutable=1", uri=True)
```

`immutable=1` 告诉 SQLite"这个文件永远不会变"，于是它跳过全部锁检查和 WAL 恢复逻辑，只管读。实测静态副本打开读取一切正常。但边界要说清楚：**它假设没有任何并发写入，也完全忽略 `-wal` 文件里未合并的内容**——如果你拷贝姿势不对（没带三件套），它只会安静地给你读那份"空壳"，连错误都不报。所以 `immutable` 是"姿势 A/B 做对之后"的提速优化，不是替代品。

## 实现：完整复现脚本

把上面的四个发现合并成一个 40 行脚本，任何有 Python 的机器都能跑通（用临时目录，不碰真实数据）：

```python
import sqlite3, os, shutil, tempfile

d = tempfile.mkdtemp()
db = os.path.join(d, "t.db")
c = sqlite3.connect(db)
c.execute("PRAGMA journal_mode=WAL")            # 切到 WAL（桌面应用最常见的配置）
c.execute("CREATE TABLE t(id INTEGER PRIMARY KEY, v TEXT)")
c.execute("INSERT INTO t VALUES(1,'a')"); c.commit()

c2 = sqlite3.connect(db)                        # 模拟"应用还开着"
c2.execute("INSERT INTO t VALUES(2,'b')"); c2.commit(); c2.close()

print("主库字节:", os.path.getsize(db), "| WAL 字节:", os.path.getsize(db + "-wal"))

shutil.copy(db, db + ".copy1")                  # 只拷主库
try:
    print("副本行数:", sqlite3.connect(db + ".copy1").execute("SELECT count(*) FROM t").fetchone())
except Exception as e:
    print("副本打开失败:", e)                    # no such table: t

c.execute("PRAGMA wal_checkpoint(TRUNCATE)")    # 合并 WAL（应急姿势）
shutil.copy(db, db + ".copy2")
print("合并后副本行数:", sqlite3.connect(db + ".copy2").execute("SELECT count(*) FROM t").fetchone())

c.close()
ro = sqlite3.connect("file:" + db.replace("\\", "/") + "?mode=ro", uri=True)
ro.execute("PRAGMA query_only=1")
try:
    ro.execute("INSERT INTO t VALUES(3,'c')")
except Exception as e:
    print("只读锁生效:", e)                      # attempt to write a readonly database
ro.close()
shutil.rmtree(d, ignore_errors=True)
```

另外两个顺手的分析基本功，一并附上。看表结构别拆文件，用 PRAGMA：

```python
# 列出所有表 + 每张表的字段（只读连接下均可执行）
tables = [r[0] for r in ro.execute("SELECT name FROM sqlite_master WHERE type='table'")]
for t in tables:
    print(t, [(r[1], r[2]) for r in ro.execute("PRAGMA table_info(%s)" % t)])
```

## 踩坑表

| 坑 | 现象 | 解法 |
|---|---|---|
| WAL 模式只拷主库 | 副本 `no such table`，或丢最近几行数据 | 应用正常退出后再拷；或三件套（.db/-wal/-shm）一起拷 |
| 只拷了主库还想读 | 数据看着是空的，误判"库被清了" | 先看主库文件大小是否远小于 -wal；带 WAL 恢复后重看 |
| checkpoint 后 -wal 还在 | 以为没合并成功，反复执行 | TRUNCATE 只是截成 0 字节；最后连接关闭才删除文件 |
| `mode=ro` 就以为安全 | 第三方代码在同一连接里偷偷写 | 加 `PRAGMA query_only=1` 双保险 |
| 静态副本直接 `immutable=1` | 拷贝姿势不对时安静读到空数据 | 先确认副本完整（行数/大小对得上），再上 immutable 提速 |

## 效果与适用边界

同一套流程跑通之后，分析这类"不归我管"的本地库变成三步：**确认日志模式 → 按 WAL 规则取到完整副本 → 只读连接上做 schema 自省和抽样验证**。原库全程零写入，副本随便折腾。

适用边界也直说：这套方法针对的是 SQLite 单文件库的离线分析。如果目标库用的是 MySQL/PostgreSQL 这类服务端数据库，正确的姿势是建一个只有 SELECT 权限的账号去连，思路（只读 + 口径验证先行）一样，手段不同。

## 你可以怎么用

- **备份/迁移桌面应用的本地数据**：先查 `PRAGMA journal_mode`，是 WAL 就带上三件套，或等应用退出；
- **给任何"只许看不许碰"的库写分析脚本**：`mode=ro` + `query_only=1` 两行配置打底；
- **验证字段口径再写统计**：`PRAGMA table_info` 自省 + 抽样几行人工核对，比直接 SUM 可靠——字段名会撒谎，抽样不会；
- **做只读数据快照工具**：静态副本上加 `immutable=1`，省掉锁开销。

---

> **关于作者**：10 年跨境电商老兵，拥抱 AI 时代。这里记录我踩过的坑和跑通的方法。

---

事情很小：我要给一个桌面应用的本地 SQLite 库做离线分析——统计它自己记录的用量数据。约束很明确：不能登录它的账号，更不能在原库上写一个字节。

【AI 工作流手记 #7】只拷一个 .db 文件做离线分析，结果连表都没有：SQLite WAL 模式的复制陷阱与只读三道锁

WAL 模式下只拷主库文件，可能连表都查不到。实测复制丢数据的完整复现、checkpoint 补救、mode=ro + query_only 只读双保险与 immutable 的适用边界，附可运行脚本。

数据库

开发工具

安全

SQLite WAL模式下仅复制.db主文件会导致数据丢失，需连-wal和-shm文件一起拷贝。只读分析应使用mode=ro加query_only=1双锁防护，静态副本可用immutable=1提速。文章提供完整复现脚本，解析拷贝陷阱、只读锁机制及正确操作流程。

代码解释

PostgreSQL

SQLite

Python

MySQL

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【AI 工作流手记 #7】只拷一个 .db 文件做离线分析，结果连表都没有：SQLite WAL 模式的复制陷阱与只读三道锁-腾讯云开发者社区-腾讯云

【AI 工作流手记 #7】只拷一个 .db 文件做离线分析，结果连表都没有：SQLite WAL 模式的复制陷阱与只读三道锁

【AI 工作流手记 #7】只拷一个 .db 文件做离线分析，结果连表都没有：SQLite WAL 模式的复制陷阱与只读三道锁

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐