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