SQLite数据库文件通常只有一个独立文件，但内部结构并不简单，它由多个B-tree、页链表和自由页组成。任何一次写入中断、磁盘坏道或程序逻辑错误都可能导致某个数据页没有被正确落盘，进而破坏整个库的一致性。PRAGMA integrity_check正是为了应对这类问题而提供的诊断工具。它不会修复任何错误，但能准确告诉你数据库是否处于健康状态，以及具体哪些部分出了问题。

执行该命令最简单的方式是通过SQLite命令行工具。打开目标数据库后直接输入PRAGMA integrity_check;即可。如果数据库完全正常，输出只有一行ok。如果存在损坏，则会返回多行错误信息，每行描述一个不一致的问题。例如row 123 missing from index idx_name表示某个索引条目丢失，或者Page 456: btreeInitPage() returns error code 11表示页头校验失败。开发者应当把integrity_check纳入日常维护流程，尤其是那些频繁写入、运行在嵌入式设备或断电风险较高的场景。

PRAGMA integrity_check 的基本用法与输出解读

在命令行中执行检查非常简单，也可以指定要检查的表或索引来缩小范围。完整检查整库的命令如下：

PRAGMA integrity_check;

这条命令会扫描主数据库的所有表和索引。如果想检查附加数据库，可以使用PRAGMA integrity_check(1);，参数表示数据库编号，0代表main，1代表第一个附加数据库。还可以指定具体的表名，例如PRAGMA integrity_check('users');。指定对象的检查速度更快，适合在怀疑某个表损坏时做定向排查。

输出为ok时代表所有结构和内容都通过了校验。但要注意，ok只说明数据库文件在逻辑上是自洽的，并不能说明数据本身是否有业务错误。例如所有行都在索引中存在、页链表完整，但某些记录的实际值可能是垃圾数据。因此完整性检查关注的是存储层一致性，而非应用层数据正确性。如果输出错误信息，每条错误的第一部分通常是页号或行号，帮助定位到具体损坏位置。日志中如果出现database disk image is malformed，往往就是查询过程中触发了底层读取失败，此时再跑integrity_check可能会得到更多细节。

integrity_check 的检查机制与常见错误类型

该命令在内部会执行一系列校验步骤。它会遍历所有表的B-tree结构，确认每个内部节点和叶子节点的父子关系正确无误；检查每个页的头部信息，包括页类型、页号、哈希校验和（如果启用）等；验证所有记录格式符合SQLite的编码规范，比如变长整数、溢出页链等；最后还会校验所有索引与对应的表内容是否完全匹配。这些校验步骤共享同一套只读事务，不会修改数据库文件。

常见的错误类型大致可以归为几类。第一类是页级损坏，例如Page X: invalid page number或Page X: btreeInitPage() returns error code 11，说明某个页的头部信息损坏或者页类型标记错误。第二类是结构不一致，比如row N missing from index idx_x或wrong # of entries in index idx_x，表明表和索引之间出现偏差。第三类是记录格式问题，例如malformed record starting at offset，可能是写入时被截断或部分覆盖。第四类是与WAL文件相关的问题，例如WAL文件头损坏或无法回放。理解错误类型有助于决定恢复策略：有些错误可以通过REINDEX或VACUUM修复，有些则需要从备份恢复。

需要特别注意的是，integrity_check并不会修改任何数据，也不会尝试修复错误。如果检查发现错误，用户需要根据错误类型和严重程度决定下一步。对于索引不一致，可以尝试REINDEX命令重建索引；对于页损坏，通常只能使用.recover命令（在命令行工具中）或者依赖SQLite的恢复API去尽可能提取数据。不要直接在损坏的数据库上执行大量写操作，因为可能破坏更多页。

自动化执行与性能优化策略

在生产环境中，手动执行integrity_check并不现实，最好将检查逻辑集成到应用启动流程或定时任务中。以Python为例，可以在建立连接后执行一次快速检查：

import sqlite3
conn = sqlite3.connect('app.db')
cursor = conn.cursor()
result = cursor.execute('PRAGMA integrity_check').fetchone()
if result[0] != 'ok':
    print('数据库损坏，请立即处理:', result[0])
    # 触发告警或切换只读模式
else:
    print('数据库完整性检查通过')
conn.close()

对于较大的数据库，全量integrity_check可能需要几秒甚至几分钟，因为它会扫描所有页面。为了减少对业务的影响，可以选择在低峰期执行，或者只检查关键表。SQLite还提供了PRAGMA quick_check;，它跳过了一些较为耗时的深度校验，比如不验证索引内容与表的完全一致性，只做更基础的B-tree结构检查，速度更快但可能漏掉某些错误。如果只想检查索引一致性，可以对单个索引执行PRAGMA integrity_check('index_name');。

另一个常见的优化点是控制WAL文件大小。在WAL模式下，integrity_check需要读取WAL中的最新数据，如果WAL文件非常巨大，检查时间会显著增加。定期执行PRAGMA wal_checkpoint(TRUNCATE);可以清理已提交的WAL数据，降低后续检查的读取量。此外，将数据库放在本地SSD上运行检查比在机械硬盘或网络文件系统上快很多，因为随机读是完整性检查的主要瓶颈。如果应用使用只读连接打开数据库，integrity_check仍然可以执行，但在WAL模式下可能无法创建必要的检查点，此时需要临时以读写模式重新打开或者先执行checkpoint。

总结一下，PRAGMA integrity_check是SQLite自带的低开销、高可信度的完整性检测工具。它不能防止数据损坏，但可以在损坏发生后第一时间发现并定位问题。建议在应用启动时执行一次quick_check做快速体检，在每日维护窗口执行完整integrity_check，并配合备份策略和WAL checkpoints，能够极大降低数据丢失的风险。对于关键业务数据库，把这条命令的输出记录到日志中，也有助于事后追溯故障原因。