检查点数据库

SQLite C 接口

int sqlite3_wal_checkpoint_v2(
  sqlite3 *db,                    /* Database handle */
  const char *zDb,                /* Name of attached database (or NULL) */
  int eMode,                      /* SQLITE_CHECKPOINT_* value */
  int *pnLog,                     /* OUT: Size of WAL log in frames */
  int *pnCkpt                     /* OUT: Total number of frames checkpointed */
);

sqlite3_wal_checkpoint_v2(D,X,M,L,C)接口以M方式对数据库连接D的数据库X进行checkpoint操作，状态信息回写成L和C指向的整数，M参数必须是有效的检查点模式：

SQLITE_CHECKPOINT_PASSIVE

在不等待任何数据库读取器或写入器完成的情况下检查尽可能多的帧，如果日志中的所有帧都已检查点，则同步数据库文件。在 SQLITE_CHECKPOINT_PASSIVE 模式下永远不会调用繁忙处理程序回调。另一方面，如果有并发的读者或作者，被动模式可能会使检查点未完成。

SQLITE_CHECKPOINT_FULL

此模式会阻塞（它调用忙处理程序回调），直到没有数据库编写器并且所有读取器都从最新的数据库快照中读取。然后它检查日志文件中的所有帧并同步数据库文件。此模式在挂起时阻止新的数据库写入者，但允许新的数据库读取者继续畅通无阻。

SQLITE_CHECKPOINT_RESTART

此模式与 SQLITE_CHECKPOINT_FULL 的工作方式相同，此外，在检查点日志文件后，它会阻塞（调用忙处理程序回调），直到所有读者都只从数据库文件中读取。这确保了下一个写入器将从头开始重新启动日志文件。与 SQLITE_CHECKPOINT_FULL 一样，此模式在挂起时阻止新的数据库写入器尝试，但不会阻止读取器。

SQLITE_CHECKPOINT_TRUNCATE

此模式的工作方式与 SQLITE_CHECKPOINT_RESTART 相同，此外它还会在成功返回之前将日志文件截断为零字节。

如果 pnLog 不为 NULL，则 *pnLog 设置为日志文件中的总帧数，如果检查点由于错误或数据库未处于WAL 模式而无法运行，则设置为 -1 。如果 pnCkpt 不为 NULL，则 *pnCkpt 设置为日志文件中检查点帧的总数（包括在调用函数之前已经设置的任何帧）或 -1 如果检查点由于错误而无法运行或因为数据库不是WAL模式。请注意，成功完成 SQLITE_CHECKPOINT_TRUNCATE 后，日志文件将被截断为零字节，因此 *pnLog 和 *pnCkpt 都将设置为零。

所有调用都在数据库文件上获得独占的“检查点”锁。如果有任何其他进程同时在运行检查点操作，则无法获取锁并返回 SQLITE_BUSY。即使配置了繁忙处理程序，在这种情况下也不会调用它。

SQLITE_CHECKPOINT_FULL、RESTART 和 TRUNCATE 模式还获得了数据库文件上的独占“写入器”锁。如果无法立即获得写锁，并且配置了忙处理程序，则会调用它并重试写锁，直到忙处理程序返回 0 或成功获得锁。如上所述，在等待数据库读取器时也会调用繁忙处理程序。如果繁忙处理程序在获得写入器锁之前或在等待数据库读取器时返回 0，则检查点操作从该点开始以与 SQLITE_CHECKPOINT_PASSIVE 相同的方式进行 - 检查点尽可能多的帧，而不会进一步阻塞。在这种情况下返回 SQLITE_BUSY。

如果参数 zDb 为 NULL 或指向零长度字符串，则将在所有附加到数据库连接db 的 WAL 数据库上尝试指定的操作。在这种情况下，写入输出参数 *pnLog 和 *pnCkpt 的值是未定义的。如果在处理一个或多个附加的 WAL 数据库时遇到 SQLITE_BUSY 错误，则仍会尝试对任何剩余的附加数据库执行该操作，并在最后返回 SQLITE_BUSY。如果在处理附加数据库时发生任何其他错误，则放弃处理并立即将错误代码返回给调用者。如果在处理附加数据库时没有遇到错误（SQLITE_BUSY 或其他），则返回 SQLITE_OK。

如果数据库 zDb 是未处于 WAL 模式的附加数据库的名称，则返回 SQLITE_OK 并且 *pnLog 和 *pnCkpt 都设置为 -1。如果 zDb 不是 NULL（或零长度字符串）并且不是任何附加数据库的名称，则 SQLITE_ERROR 返回给调用者。

除非它返回 SQLITE_MISUSE，否则 sqlite3_wal_checkpoint_v2() 接口设置由sqlite3_errcode()和sqlite3_errmsg()查询的错误信息。

PRAGMA wal_checkpoint命令可用于从 SQL 调用此接口。

另请参阅对象、常量和函数的列表。