SQLiteC/C++接口详细介绍之sqlite3类（十八）

返回目录：SQLite—免费开源数据库系列文章目录

上一篇：SQLiteC/C++接口详细介绍之sqlite3类（十七）

下一篇：SQLiteC/C++接口详细介绍sqlite3_stmt类（一）

56.sqlite3_update_hook

函数功能：向应用程序通知每一个 INSERT、UPDATE 或 DELETE 语句。

当INSERT、UPDATE或DELETE语句执行时，SQLite3将检测表或触发器并执行任何相关的操作。最后，SQLite3将调用与sqlite3_update_hook关联的回调函数以通知应用程序。

sqlite3_update_hook函数原型如下：

void sqlite3_update_hook(
  sqlite3 *db,
  void (*callback)(void *, int, char const *, char const *, sqlite3_int64),
  void *arg
);

参数说明：

- db：一个由sqlite3_open或sqlite3_open_v2返回的数据库句柄。
- callback：一个指向回调函数的指针。此回调函数由SQLite3调用以通知应用程序每次执行了INSERT、UPDATE或DELETE语句。该回调函数的声明应该匹配如下：

  void (*callback)(void *, int, char const *, char const *, sqlite3_int64)

回调函数的第一个参数为表达了被改变的各种值，是由用户提供的Void指针arg决定的。
第二个参数是SQL语句的类型,即SQLITE_INSERT、SQLITE_UPDATE或SQLITE_DELETE。
第三个和第四个参数表明哪个数据库和表被修改了。
第五个参数是被修改记录的行ID。

- arg：在调用回调函数时，作为其中一个参数把它传递回去的任意类的指针。

下面是一个示例程序，演示了如何使用sqlite3_update_hook函数：

#include <sqlite3.h>
#include <stdio.h>
static void update_callback(
    void *pArg,
    int iCmd,
    char const *zDb,
    char const *zTableName,
    sqlite3_int64 rowid
) {
    printf("UPDATE hook: %s %s id=%lld\n", zDb, zTableName, rowid);
}
int main() {
    sqlite3 *db;
    sqlite3_open_v2(":memory:", &db, SQLITE_OPEN_CREATE | SQLITE_OPEN_READWRITE, NULL);
    sqlite3_exec(db, "CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)", NULL, NULL, NULL);
    sqlite3_update_hook(db, update_callback, NULL);
    sqlite3_exec(db, "INSERT INTO test (id, value) VALUES (1, 'hello')", NULL, NULL, NULL);
    sqlite3_exec(db, "UPDATE test SET value = 'world' WHERE id = 1", NULL, NULL, NULL);
    sqlite3_exec(db, "DELETE FROM test WHERE id = 1", NULL, NULL, NULL);
    sqlite3_close(db);
    return 0;
}

该示例中，我们创建了一个名为“test”的表，然后在sqlite3_update_hook中注册了一个回调函数。我们随后在表格中插入一行，更新这一行的记录，再将这一行的记录删除。在每一次执行修改操作时，SQLite3都会调用我们注册的回调函数，它将记录当前执行的操作并输出相关信息。

程序输出的结果为：

UPDATE hook: main test id=1
UPDATE hook: main test id=1
UPDATE hook: main test id=1
可以看到，程序成功使用sqlite3_update_hook函数注册了一个回调函数，然后在每一次执行修改操作时，都会输出钩子的相应信息。

57.sqlite3_wal_autocheckpoint

函数功能:自动调度WAL模式下的日志文件检查点。

在WAL模式下，混合使用事务和独立表锁，事务使用WAL日志文件，在 WAL 模式下，删除语句不再真正执行删除，而仅在 WAL 日志文件中形成删除记录。WAL记录将在另外的线程或进程读取和删除。当WAL日志文件变得非常大时，它将占用大量磁盘空间，这将影响性能。

SQLite3允许通过自动检查点机制来控制WAL日志文件的增长。当应用程序不再使用WAL日志文件时，可以让SQLite3自动检查点。在自动检查点机制的帮助下，SQLite3将创建一个新的数据库文件，将WAL日志文件中的相关内容复制到新的数据库文件中，并将WAL日志文件重命名为删除状态。由于复制数据到新文件和删除旧的WAL日志文件都是涉及磁盘I / O的操作，因此要小心进行自动检查点机制的配置。

sqlite3_wal_autocheckpoint函数用于设置WAL文件的自动检查点算法。它将一个整数值设置为一个逻辑步骤数。在WAL模式下，每当写日志文件达到nSize个逻辑步骤时，将自动运行检查点。

sqlite3_wal_autocheckpoint函数原型如下：

int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);

参数说明：

- db：由sqlite3_open或sqlite3_open_v2打开的数据库连接句柄。
- N：表示WAL日志文件中的逻辑步骤数。

返回值：设置和清除自动检查点提醒程序的SQLITE_OK，或一个错误代码。

下面是一个示例程序，演示了如何使用sqlite3_wal_autocheckpoint函数。该程序使用WAL模式编写“test”表中的几个条目，然后在自动检查点机制的帮助下设置检查点。在程序退出之前，它还回滚了最后一个此插入操作。注意，设置的逻辑步骤数只是一个量级，实际值取决于数据库的大小和预计的WAL日志文件大小。

#include <sqlite3.h>
#include <stdio.h>
int main() {
    sqlite3 *db;
    char *zErrMsg = 0;
    sqlite3_open_v2(":memory:", &db, SQLITE_OPEN_CREATE | SQLITE_OPEN_READWRITE | SQLITE_OPEN_URI, NULL);
    sqlite3_exec(db, "PRAGMA journal_mode=WAL;", NULL, NULL, NULL);
    sqlite3_exec(db, "CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT);", NULL, NULL, &zErrMsg);
    char *sql_insert = "INSERT INTO test VALUES (null, 'Hello World!');";
    sqlite3_stmt *stmt;
    sqlite3_prepare_v2(db, sql_insert, -1, &stmt, NULL);
    for (int i = 0; i < 100; i++) {
        sqlite3_step(stmt);
        sqlite3_reset(stmt);
        if (i == 50) {
            sqlite3_wal_checkpoint_v2(db, NULL, SQLITE_CHECKPOINT_TRUNCATE, NULL, NULL);
            printf("Automatically set checkpoint\n");
        }
    }
    sqlite3_finalize(stmt);
    sqlite3_exec(db, "ROLLBACK TO savepoint1;", NULL, NULL, &zErrMsg);
    printf("Rolled back transaction\n");
    sqlite3_close(db);
    return 0;
}

以上程序会创建一个名为“test”的表，使用WAL模式编写数百个条目。然后，当编写WAL日志时，程序将设置一个自动检查点，该检查点会在30个事务步骤后运行。有趣的是，我们将会回滚最后一次插入操作。在自动检查点触发之前，程序将移动到"savepoint1"保存点。

程序输出的结果如下：

Automatically set checkpoint
Rolled back transaction
可以看到，在程序的自动检查点算法处顺利地运行。执行WAL日志会在某些时候具有显著的性能和稳定性优势。如果在许多并发连接到相同的数据库时，可以使用WAL日志来避免数据库连接争用的情况。

58.sqlite3_wal_checkpoint与sqlite3_wal_checkpoint_v2

函数功能：在WAL模式下手动调用日志文件检查点。这些函数在WAL模式时可以调用。调用这些函数不是必需的，因为SQLite3会定期自动运行检查点以降低WAL日志文件的大小。但是，如果您的应用程序将使用WAL模式长时间运行，建议使用这些函数。手动调用日志文件检查点可以确保日志文件保持足够小，从而提高应用程序的性能。

sqlite3_wal_checkpoint函数适用于SQLite3 version 3.7.4 至 3.7.14.2 和 3.8.0 至 3.8.1之间的版本。sqlite3_wal_checkpoint_v2函数是3.7.14.2版本之后的版本引入的。两个函数在功能上非常相似，都可以用于手动触发WAL检查点，但sqlite3_wal_checkpoint_v2中加入了一些新的标志供选择使用。

sqlite3_wal_checkpoint_v2函数原型如下：

int sqlite3_wal_checkpoint_v2(
  sqlite3 *db,
  const char *zDb,
  int eMode,
  int *pnLog,
  int *pnCkpt
);

参数说明：

- db：由sqlite3_open或sqlite3_open_v2函数打开的一个数据库连接实例。
- zDb：将连接到 WAL 文件的数据库名称。如果为NULL，则连接到所有数据库。如果不是NULL，则只连接到指定数据库的 WAL 文件。
- eMode：当此参数设置为 SQLITE_CHECKPOINT_PASSIVE 时，在 WAL 文件中找到所有活动的奇偶交错帧并将它们排序交错以便将单个帧作为 SQLite 数据库中的单个页面写入。否则，如果设置为 SQLITE_CHECKPOINT_RESTART 或 SQLITE_CHECKPOINT_TRUNCATE，则在 WAL 文件中找到所有活动的奇偶交错帧并将它们写入 SQLite 数据库中。如果它设置为 SQLITE_CHECKPOINT_FULL，则查找所有WAL文件，并找出其中活动的奇偶交错帧并将其写入SQLite数据库。
- pnLog：指向一个int的指针，如果不想接收WAL文件的大小，则传递NULL。
- pnCkpt：指向一个int的指针，如果不需要接收检查点的总页数，则传递NULL。

sqlite3_wal_checkpoint函数原型如下：

int sqlite3_wal_checkpoint(
  sqlite3 *db,
  const char *zDb
);

参数说明：

- db：由sqlite3_open或sqlite3_open_v2函数打开的一个数据库连接实例。
- zDb：将连接到 WAL 文件的数据库名称。如果为NULL，则连接到所有数据库。如果不是NULL，则只连接到指定数据库的 WAL 文件。

示例程序演示了如何使用sqlite3_wal_checkpoint_v2函数手动触发WAL检查点。

#include <sqlite3.h>
#include <stdio.h>
int main() {
    sqlite3 *db;
    char *err_msg = 0;
    sqlite3_open(":memory:", &db);
    sqlite3_exec(db, "PRAGMA journal_mode=WAL;", NULL, NULL, &err_msg);
    sqlite3_exec(db, "CREATE TABLE test (a, b, PRIMARY KEY(a, b));", NULL, NULL, &err_msg);
    sqlite3_exec(db, "BEGIN;", NULL, NULL, &err_msg);
    for (int i = 0; i < 10; i++) {
        char sql_insert[100];
        sprintf(sql_insert, "INSERT INTO test VALUES (%d, %d);", i, i);
        sqlite3_exec(db, sql_insert, NULL, NULL, &err_msg);
    }
    printf("WAL file size before: %d bytes\n", sqlite3_wal_checkpoint_v2(db, NULL, SQLITE_CHECKPOINT_FULL, NULL, NULL));
    sqlite3_exec(db, "COMMIT;", NULL, NULL, &err_msg);
    printf("WAL file size after: %d bytes\n", sqlite3_wal_checkpoint_v2(db, NULL, SQLITE_CHECKPOINT_FULL, NULL, NULL));
    sqlite3_close(db);
    return 0;
}

以上程序首先使用“PRAGMA journal_mode=WAL;”指令开启WAL模式，然后创建一个表“test”，并在其中添加一些数据。然后，通过sqlite3_wal_checkpoint_v2函数使用SQLITE_CHECKPOINT_FULL标志触发了一个手动检查点，并记录WAL日志文件的大小。最后提交事务并再次记录WAL日志文件大小。

程序输出的结果为：

WAL file size before: 12288 bytes
WAL file size after: 4096 bytes

可以看到，手动调用日志文件检查点已将WAL文件的大小从12288字节缩小到4096字节。这是一种有效节省空间的方法。

59.sqlite3_wal_hook

函数功能：可以在WAL模式下注册一个回调函数。当需要在WAL文件中写入数据时，该回调函数将被调用。

在WAL模式下，数据更改是在WAL文件中记录的。sqlite3_wal_hook回调函数允许应用程序检测正在写入到WAL日志文件的数据，可以自定义要写入到WAL日志文件的内容。这可以用于记录应用程序相关的元数据或其他一些额外的信息。

sqlite3_wal_hook函数原型如下：

void (*sqlite3_wal_hook)(
  sqlite3*, 
  int(*)(void *,sqlite3*,const char*,int),
  void*
);

参数说明：

- db：一个打开的数据库连接。
- xCallback：一个回调函数，由SQLite3调用以在WAL文件中写入数据。
- pArg：回调函数的第3个参数是指向此指针的。它是对回调函数的额外自定义数据，当回调函数被调用时，它作为第3个参数（完全解释由回调函数协议确定的额外数据）的值传递给回调函数。

其中，xCallback参数为回调函数的指针。

回调函数原型如下：

int (*xCallback)(void *pArg, sqlite3 *db, const char *zWal, int n)

参数说明：

- pArg：由sqlite3_wal_hook函数传递的第3个参数。
- db：数据库连接句柄。
- zWal：指向写入的数据的指针。
- n：写入的数据的长度。

该回调函数可以返回零或一个非零值。如果它返回非零，则将导致WAL日志文件上的写入被撤消，不会写入磁盘。

以下示例程序演示了在WAL文件中注册回调函数sqlite3_wal_hook。

#include <sqlite3.h>
#include <string.h>
#include <stdio.h>
static int wal_write_callback(void *pArg, sqlite3 *db, const char *zWal, int n) {
    printf("WAL write callback: %s (size=%d)\n", zWal, n);
    // 将二进制数据解析为int类型并输出
    if (n == sizeof(int)) {
        int data = 0;
        memcpy(&data, zWal, sizeof(int));
        printf("Data: %d\n", data);
    }
    return 0;
}
int main() {
    sqlite3 *db;
    sqlite3_open(":memory:", &db);
    sqlite3_wal_hook(db, wal_write_callback, NULL);
    // 将数据写入WAL文件中
    int data = rand();
    printf("Write data to WAL file: %d\n", data);
    sqlite3_wal_hook(db, NULL, NULL);  // 禁用回调以避免死循环
    sqlite3_wal_write(db, &data, sizeof(int));
    sqlite3_wal_hook(db, wal_write_callback, NULL);
    sqlite3_close(db);
    return 0;
}

以上程序打开一个in-memory数据库，使用sqlite3_wal_hook函数注册回调函数“wal_write_callback”，然后随机生成一个整数并使用sqlite3_wal_write函数将该整数写入WAL文件中。使用memcpy函数将二进制数据解析为int类型并输出。

运行该程序，输出如下：

Write data to WAL file: 1710216883
WAL write callback: �4� (size=4)
Data: 1710216883
以上程序通过调用sqlite3_wal_hook函数为WAL文件注册回调函数“wal_write_callback”，该函数在数据写入到WAL文件时会被调用。该函数被调用时，输出写入WAL文件的数据。

注意：回调函数中执行的操作不应太耗时，否则可能会影响系统的性能。

至此sqlite3类的所有函数介绍完成了，本类是sqlite数据库的核心，也是最重要的函数后续将陆续介绍其他的类与成员函数相关内容。敬请期待《我很快会回来的》。