Small. Fast. Reliable.
Choose any three.
Search for:

SQLite C Interface

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

R-49787-09095:[The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint operation on database X of database connection D in mode M. Status information is written back into integers pointed to by L and C. ] R-03996-12088:[The M parameter must be a valid checkpoint mode: ]

R-16333-64433:[Checkpoint as many frames as possible without waiting for any database readers or writers to finish, then sync the database file if all frames in the log were checkpointed. ] R-62920-47450:[The busy-handler callback is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode. ] R-65499-53765:[On the other hand, passive mode might leave the checkpoint unfinished if there are concurrent readers or writers. ]

R-59171-47567:[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. ] R-29177-48281:[It then checkpoints all frames in the log file and syncs the database file. ] R-51867-44713:[This mode blocks new database writers while it is pending, but new database readers are allowed to continue unimpeded. ]

R-12410-31217:[This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition that after checkpointing the log file it blocks (calls the busy-handler callback) until all readers are reading from the database file only. ] R-11464-18362:[This ensures that the next writer will restart the log file from the beginning. ] R-47276-58266:[Like SQLITE_CHECKPOINT_FULL, this mode blocks new database writer attempts while it is pending, but does not impede readers. ]

R-44699-57140:[This mode works the same way as SQLITE_CHECKPOINT_RESTART with the addition that it also truncates the log file to zero bytes just prior to a successful return. ]

R-16642-42503:[If pnLog is not NULL, then *pnLog is set to the total number of frames in the log file or to -1 if the checkpoint could not run because of an error or because the database is not in WAL mode. ] R-10514-25250:[If pnCkpt is not NULL,then *pnCkpt is set to the total number of checkpointed frames in the log file (including any that were already checkpointed before the function was called) or to -1 if the checkpoint could not run due to an error or because the database is not in WAL mode. ] R-37257-17813:[Note that upon successful completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero. ]

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

R-59782-36818:[The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the exclusive "writer" lock on the database file. ] R-60642-04082:[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. ] R-48107-00250:[The busy-handler is also invoked while waiting for database readers as described above. ] R-49155-63541:[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. ] R-34519-06271:[SQLITE_BUSY is returned in this case. ]

R-00653-06026:[If parameter zDb is NULL or points to a zero length string, then the specified operation is attempted on all WAL databases attached to database connection db. ] In this case the values written to output parameters *pnLog and *pnCkpt are undefined. R-38578-34175:[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 at the end. ] R-38049-07913:[If any other error occurs while processing an attached database, processing is abandoned and the error code is returned to the caller immediately. ] R-41299-52117:[If no error (SQLITE_BUSY or otherwise) is encountered while processing the attached databases, SQLITE_OK is returned. ]

R-14303-42483:[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. ] R-38207-48996:[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. ]

R-60567-47780:[Unless it returns SQLITE_MISUSE, the sqlite3_wal_checkpoint_v2() interface sets the error information that is queried by sqlite3_errcode() and sqlite3_errmsg(). ]

R-36706-10507:[The PRAGMA wal_checkpoint command can be used to invoke this interface from SQL. ]

See also lists of Objects, Constants, and Functions.