检查点数据库

小巧、快速、可靠。
三者选其二。

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 执行检查点操作。状态信息写入 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 将设置为日志文件中的总帧数，或者设置为 -1（如果检查点由于错误或数据库不在 WAL 模式下而无法运行）。如果 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 调用此接口。

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