Checkpoint a database

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 */
);

Run a checkpoint operation on WAL database zDb attached to database handle db. The specific operation is determined by the value of the eMode parameter:

SQLITE_CHECKPOINT_PASSIVE

Checkpoint as many frames as possible without waiting for any database readers or writers to finish. Sync the db file if all frames in the log are checkpointed. This mode is the same as calling sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.

SQLITE_CHECKPOINT_FULL

This mode blocks (it invokes the busy-handler callback) until there is no database writer and all readers are reading from the most recent database snapshot. It then checkpoints all frames in the log file and syncs the database file. This call blocks database writers while it is running, but not database readers.

SQLITE_CHECKPOINT_RESTART

This mode works the same way as SQLITE_CHECKPOINT_FULL, except after checkpointing the log file it blocks (calls the busy-handler callback) until all readers are reading from the database file only. This ensures that the next client to write to the database file restarts the log file from the beginning. This call blocks database writers while it is running, but not database readers.

If pnLog is not NULL, then *pnLog is set to the total number of frames in the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to the total number of checkpointed frames (including any that were already checkpointed when this function is called). *pnLog and *pnCkpt may be populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK. If no values are available because of an error, they are both set to -1 before returning to communicate this to the caller.

All calls obtain an exclusive "checkpoint" lock on the database file. If any other process is running a checkpoint operation at the same time, the lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a busy-handler configured, it will not be invoked in this case.

The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive "writer" lock on the database file. If the writer lock cannot be obtained immediately, and a busy-handler is configured, it is invoked and the writer lock retried until either the busy-handler returns 0 or the lock is successfully obtained. The busy-handler is also invoked while waiting for database readers as described above. If the busy-handler returns 0 before the writer lock is obtained or while waiting for database readers, the checkpoint operation proceeds from that point in the same way as SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible without blocking any further. SQLITE_BUSY is returned in this case.

If parameter zDb is NULL or points to a zero length string, then the specified operation is attempted on all WAL databases. In this case the values written to output parameters *pnLog and *pnCkpt are undefined. If an SQLITE_BUSY error is encountered when processing one or more of the attached WAL databases, the operation is still attempted on any remaining attached databases and SQLITE_BUSY is returned to the caller. If any other error occurs while processing an attached database, processing is abandoned and the error code returned to the caller immediately. If no error (SQLITE_BUSY or otherwise) is encountered while processing the attached databases, SQLITE_OK is returned.

If database zDb is the name of an attached database that is not in WAL mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If zDb is not NULL (or a zero length string) and is not the name of any attached database, SQLITE_ERROR is returned to the caller.

See also lists of Objects, Constants, and Functions.