SQLite 踩坑记录

1. 问题背景#

最近在实习中排查了一个相当棘手的 Bug，这里记录一下。这个Bug的表象是一个模块将 JSON 数据存入 SQLite 数据库后，再次读取出来时会发生数据损坏。

排查记录：

检查日志：首先查看了模块的日志，很快定位到了错误，程序在解析从数据库中读出的 JSON 字符串时抛出了异常。
打印原始数据：然后我直接打印了从数据库读出的原始字符串，发现内容要么是乱码，要么干脆是空的。
检查写入过程：我转头去检查数据写入时的日志，却发现一切正常，没有任何错误或警告信息。程序似乎认为它已经成功地将数据写入了数据库。
直击数据库：既然日志无法提供更多线索，我便使用命令行工具直接查询数据库。真相大白——数据库里存储的数据本身就是有问题的。这说明问题出在写入阶段，而不是读取或解析阶段。

经过层层排查，我最终锁定了一个在使用 SQLite C++ API 时非常经典、但也极易被忽视的“坑”。

2. 问题根源#

最后排查出来的问题是sqlite3_bind_text()这个API使用错误。API的函数原型如下：

int sqlite3_bind_text(
  sqlite3_stmt *pStmt,
  int i,
  const char *zData,
  int nData,
  void (*xDel)(void*)
);

cpp

参数解释：

pStmt: 语句句柄。
i: 参数索引 (从1开始)。
zData: 要绑定的字符串数据。
nData: 字符串长度 (-1 表示自动计算)。
xDel: 这是一个析构函数指针，用于指定字符串 zData 的生命周期类型。

xDel 参数可以传入两个特殊的宏：

SQLITE_STATIC:
1. 含义: 向 SQLite 保证，传入的这个字符串 (zData) 的内存是静态的、全局的、或者至少在 sqlite3_stmt 整个生命周期内（直到 sqlite3_finalize 被调用）都是有效且不会改变的。
2. SQLite 的行为: 既然做了这个保证，SQLite 为了追求极致的性能，会直接使用传入的指针，而不会自己复制一份字符串数据。它只是持有了这个指针。
3. 风险: 如果传入了一个局部变量（比如一个函数内的 std::string.c_str() 或者一个栈上的字符数组），当函数返回后，这个局部变量被销毁，内存被释放。但 SQLite 里的语句句柄 stmt 还傻傻地存着那个已经无效的野指针。后面调用 sqlite3_step() 去执行它时，它会尝试读取一个无效的内存地址，从而导致未定义行为，通常表现为程序崩溃、数据损坏或奇怪的错误。
SQLITE_TRANSIENT:
1. 含义: 这个宏告诉 SQLite，传入的这个字符串 (zData) 是临时的、短暂的 (transient)，它的生命周期可能很短，在 sqlite3_bind_text 函数调用返回后可能就失效了。
2. SQLite 的行为: 收到这个信号后，SQLite 会变得很谨慎。它会在函数内部立即将字符串数据完整地复制一份，并由自己来管理这份拷贝的内存。这样，即使原始的字符串变量超出了作用域被销毁，也完全没关系，因为 SQLite 使用的是它自己的安全拷贝。
3. 代价: 需要一次额外的内存分配和数据拷贝，相比 SQLITE_STATIC 会有微小的性能开销。但它换来的是安全和省心。

3. 总结#

在使用这个API的时候，应该根据数据的声明周期来选择正确的宏。

对于局部变量、临时拼接的字符串、std::string 对象等，它们的生命周期很短，必须使用 SQLITE_TRANSIENT。

std::string user_name = "Alice";
// 正确的做法：告诉 SQLite 这是临时数据，请它自己复制
sqlite3_bind_text(stmt, 1, user_name.c_str(), -1, SQLITE_TRANSIENT);

cpp

对于字符串字面量、全局变量、或能确保其生命周期超过 stmt 的数据，可以使用 SQLITE_STATIC 来获得一点性能优势。

// 字符串字面量是静态存储的，整个程序运行期间都有效
sqlite3_bind_text(stmt, 1, "Alice", -1, SQLITE_STATIC); // 这是安全的

cpp

4. 拓展#

深入探究会发现，SQLite 的 sqlite3_bind_* 系列 API 在设计上体现了 C/C++ 核心的数据传递思想，主要分为两类：

传值
- sqlite3_bind_int()
- sqlite3_bind_double()
- sqlite3_bind_int64()
传指针
- sqlite3_bind_text()
- sqlite3_bind_blob()

对于传值，SQLite 接收到的是这个数字的副本。它会立即将这个副本存放到它自己管理的内存中（通常是 sqlite3_stmt 对象内部的某个字段）。这个过程非常快，因为整数和浮点数都是固定大小的、很小的数据类型。一旦函数调用完成，SQLite 已经拿到了它需要的值的拷贝。原来的变量之后是超出作用域被销毁，还是被修改，都与 SQLite 毫无关系了。SQLite 内部已经有了一个安全、独立的副本，所以不存在野指针或数据失效的风险。

对于传指针，SQLite 拿到的只是一个地址，它并不知道这个地址指向的内存能有效多久。这段内存是由调用者管理的。这就带来了我们之前讨论的问题：如果 SQLite 不复制，它就需要你保证这个地址在未来（sqlite3_step 执行时）依然有效。这就是 SQLITE_STATIC 的含义。如果 SQLite 自己复制，它就需要分配内存，然后把指针指向的数据拷贝过来。这样就安全了，但有性能开销。这就是 SQLITE_TRANSIENT 的含义。生命周期参数是必需的: 因为 C API 无法自动判断指针的生命周期，所以 SQLite 的设计者选择将这个决定权通过最后一个参数交还给开发者，让你明确告知它应该如何处理这个指针。