1.Dd December 19, 2018 2.Dt SQLITE3_WAL_CHECKPOINT_V2 3 3.Os 4.Sh NAME 5.Nm sqlite3_wal_checkpoint_v2 6.Nd Checkpoint a database 7.Sh SYNOPSIS 8.Ft int 9.Fo sqlite3_wal_checkpoint_v2 10.Fa "sqlite3 *db" 11.Fa "const char *zDb" 12.Fa "int eMode" 13.Fa "int *pnLog" 14.Fa "int *pnCkpt " 15.Fc 16.Sh DESCRIPTION 17The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint 18operation on database X of database connection D 19in mode M. 20Status information is written back into integers pointed to by L and 21C. 22The M parameter must be a valid checkpoint mode: 23.Bl -tag -width Ds 24.It SQLITE_CHECKPOINT_PASSIVECheckpoint as many frames as possible without 25waiting for any database readers or writers to finish, then sync the 26database file if all frames in the log were checkpointed. 27The busy-handler callback is never invoked in 28the SQLITE_CHECKPOINT_PASSIVE mode. 29On the other hand, passive mode might leave the checkpoint unfinished 30if there are concurrent readers or writers. 31.It SQLITE_CHECKPOINT_FULLThis mode blocks (it invokes the busy-handler callback) 32until there is no database writer and all readers are reading from 33the most recent database snapshot. 34It then checkpoints all frames in the log file and syncs the database 35file. 36This mode blocks new database writers while it is pending, but new 37database readers are allowed to continue unimpeded. 38.It SQLITE_CHECKPOINT_RESTARTThis mode works the same way as SQLITE_CHECKPOINT_FULL 39with the addition that after checkpointing the log file it blocks (calls 40the busy-handler callback) until all readers are 41reading from the database file only. 42This ensures that the next writer will restart the log file from the 43beginning. 44Like SQLITE_CHECKPOINT_FULL, this mode blocks new database writer attempts 45while it is pending, but does not impede readers. 46.It SQLITE_CHECKPOINT_TRUNCATEThis mode works the same way as SQLITE_CHECKPOINT_RESTART 47with the addition that it also truncates the log file to zero bytes 48just prior to a successful return. 49.El 50.Pp 51If pnLog is not NULL, then *pnLog is set to the total number of frames 52in the log file or to -1 if the checkpoint could not run because of 53an error or because the database is not in WAL mode. 54If pnCkpt is not NULL,then *pnCkpt is set to the total number of checkpointed 55frames in the log file (including any that were already checkpointed 56before the function was called) or to -1 if the checkpoint could not 57run due to an error or because the database is not in WAL mode. 58Note that upon successful completion of an SQLITE_CHECKPOINT_TRUNCATE, 59the log file will have been truncated to zero bytes and so both *pnLog 60and *pnCkpt will be set to zero. 61.Pp 62All calls obtain an exclusive "checkpoint" lock on the database file. 63If any other process is running a checkpoint operation at the same 64time, the lock cannot be obtained and SQLITE_BUSY is returned. 65Even if there is a busy-handler configured, it will not be invoked 66in this case. 67.Pp 68The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain 69the exclusive "writer" lock on the database file. 70If the writer lock cannot be obtained immediately, and a busy-handler 71is configured, it is invoked and the writer lock retried until either 72the busy-handler returns 0 or the lock is successfully obtained. 73The busy-handler is also invoked while waiting for database readers 74as described above. 75If the busy-handler returns 0 before the writer lock is obtained or 76while waiting for database readers, the checkpoint operation proceeds 77from that point in the same way as SQLITE_CHECKPOINT_PASSIVE - checkpointing 78as many frames as possible without blocking any further. 79SQLITE_BUSY is returned in this case. 80.Pp 81If parameter zDb is NULL or points to a zero length string, then the 82specified operation is attempted on all WAL databases attached 83to database connection db. 84In this case the values written to output parameters *pnLog and *pnCkpt 85are undefined. 86If an SQLITE_BUSY error is encountered when processing one or more 87of the attached WAL databases, the operation is still attempted on 88any remaining attached databases and SQLITE_BUSY is returned at the 89end. 90If any other error occurs while processing an attached database, processing 91is abandoned and the error code is returned to the caller immediately. 92If no error (SQLITE_BUSY or otherwise) is encountered while processing 93the attached databases, SQLITE_OK is returned. 94.Pp 95If database zDb is the name of an attached database that is not in 96WAL mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to 97-1. 98If zDb is not NULL (or a zero length string) and is not the name of 99any attached database, SQLITE_ERROR is returned to the caller. 100.Pp 101Unless it returns SQLITE_MISUSE, the sqlite3_wal_checkpoint_v2() interface 102sets the error information that is queried by sqlite3_errcode() 103and sqlite3_errmsg(). 104.Pp 105The PRAGMA wal_checkpoint command can be used 106to invoke this interface from SQL. 107.Sh SEE ALSO 108.Xr sqlite3_busy_handler 3 , 109.Xr SQLITE_CHECKPOINT_PASSIVE 3 , 110.Xr sqlite3 3 , 111.Xr sqlite3_busy_handler 3 , 112.Xr sqlite3_errcode 3 113