資料庫檢查點

小巧、快速、可靠。
選擇其中三項。

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) 介面會對資料庫連線 D 的資料庫 X 以模式 M 執行檢查點操作。狀態資訊會寫回到 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 會設定為日誌檔中已檢查點的總框架數（包括在呼叫函式之前已檢查點的任何框架），如果檢查點因為錯誤或資料庫未處於 WAL 模式而無法執行，則設定為 -1。請注意，在 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 給呼叫者。

除非 sqlite3_wal_checkpoint_v2() 介面返回 SQLITE_MISUSE，否則它會設定可透過 sqlite3_errcode() 和 sqlite3_errmsg() 查詢的錯誤資訊。

可以使用 PRAGMA wal_checkpoint 命令從 SQL 呼叫此介面。

另請參閱物件、常數和函式列表。