Small. Fast. Reliable.
Choose any three.

SQLite Requirement Matrix Details
wal_checkpoint_v2.html

Index Summary Markup Original


R-49787-09095-59828-21873-59722-58007-44874-49615 tcl slt th3 src

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.

tcl/e_walckpt.test:150

/* IMP: R-49787-09095 */
# EVIDENCE-OF: 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-12971-06129-31814-44621-38881-57299 tcl slt th3 src

The M parameter must be a valid checkpoint mode:

src/main.c:2092   tcl/e_walckpt.test:600

/* IMP: R-03996-12088 */
# EVIDENCE-OF: R-03996-12088 The M parameter must be a valid checkpoint
# mode:

R-16333-64433-39289-13667-32304-47493-49006-13545 tcl slt th3 src

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.

tcl/e_walckpt.test:423   th3/req1/checkpoint01.test:175

/* IMP: R-16333-64433 */
# EVIDENCE-OF: 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-51194-26975-01851-13117-37430-41623 tcl slt th3 src

The busy-handler callback is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.

src/wal.c:1756   src/wal.c:3301   tcl/e_walckpt.test:437   th3/req1/checkpoint01.test:169

/* IMP: R-62920-47450 */
# EVIDENCE-OF: R-62920-47450 The busy-handler callback is never invoked
# in the SQLITE_CHECKPOINT_PASSIVE mode.

R-65499-53765-60887-64265-16155-35530-39670-45020 tcl slt th3 src

On the other hand, passive mode might leave the checkpoint unfinished if there are concurrent readers or writers.

tcl/e_walckpt.test:454   th3/req1/checkpoint01.test:195

/* IMP: R-65499-53765 */
# EVIDENCE-OF: R-65499-53765 On the other hand, passive mode might leave
# the checkpoint unfinished if there are concurrent readers or writers.

R-59171-47567-19370-12985-34134-25393-49439-38591 tcl slt th3 src

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.

tcl/e_walckpt.test:490   th3/req1/checkpoint01.test:320

/* IMP: R-59171-47567 */
# EVIDENCE-OF: 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-29998-61012-25413-14806-58383-44850 tcl slt th3 src

It then checkpoints all frames in the log file and syncs the database file.

tcl/e_walckpt.test:517   th3/req1/checkpoint01.test:327

/* IMP: R-29177-48281 */
# EVIDENCE-OF: R-29177-48281 It then checkpoints all frames in the log
# file and syncs the database file.

R-51867-44713-01499-65438-22037-17014-32940-19082 tcl slt th3 src

This mode blocks new database writers while it is pending, but new database readers are allowed to continue unimpeded.

tcl/e_walckpt.test:528

/* IMP: R-51867-44713 */
# EVIDENCE-OF: 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-15113-45152-04874-52421-25880-35478 tcl slt th3 src

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.

tcl/e_walckpt.test:543   th3/req1/checkpoint01.test:374

/* IMP: R-12410-31217 */
# EVIDENCE-OF: 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-31752-52659-04390-24092-43500-36484 tcl slt th3 src

This ensures that the next writer will restart the log file from the beginning.

/* IMP: R-11464-18362 */
# EVIDENCE-OF: R-11464-18362 This ensures that the next writer will
# restart the log file from the beginning.

R-47276-58266-57990-47507-55397-12547-44122-03404 tcl slt th3 src

Like SQLITE_CHECKPOINT_FULL, this mode blocks new database writer attempts while it is pending, but does not impede readers.

tcl/e_walckpt.test:532

/* IMP: R-47276-58266 */
# EVIDENCE-OF: 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-60647-60895-26603-26594-01750-63577 tcl slt th3 src

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.

src/wal.c:1880   tcl/e_walckpt.test:557   th3/req1/checkpoint01.test:428

/* IMP: R-44699-57140 */
# EVIDENCE-OF: 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-02054-10937-29863-20492-60012-48807 tcl slt th3 src

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.

tcl/e_walckpt.test:727

/* IMP: R-16642-42503 */
# EVIDENCE-OF: 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-42695-33540-35883-31325-38548-55570 tcl slt th3 src

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.

tcl/e_walckpt.test:732

/* IMP: R-10514-25250 */
# EVIDENCE-OF: 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-38895-36946-60878-55344-03990-64044 tcl slt th3 src

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.

tcl/e_walckpt.test:742   th3/req1/checkpoint01.test:435

/* IMP: R-37257-17813 */
# EVIDENCE-OF: 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-10324-26388-32955-09019-38502-43412 tcl slt th3 src

All calls obtain an exclusive "checkpoint" lock on the database file.

src/wal.c:3308   tcl/e_walckpt.test:210

/* IMP: R-62028-47212 */
# EVIDENCE-OF: R-62028-47212 All calls obtain an exclusive "checkpoint"
# lock on the database file.

R-10421-19736-31829-13989-20506-40409-64205-24100 tcl slt th3 src

If any other process is running a checkpoint operation at the same time, the lock cannot be obtained and SQLITE_BUSY is returned.

src/wal.c:3312   tcl/e_walckpt.test:236

/* IMP: R-10421-19736 */
# EVIDENCE-OF: 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-43817-17457-29508-48288-48051-25287 tcl slt th3 src

Even if there is a busy-handler configured, it will not be invoked in this case.

src/wal.c:3315   tcl/e_walckpt.test:240

/* IMP: R-53820-33897 */
# EVIDENCE-OF: R-53820-33897 Even if there is a busy-handler configured,
# it will not be invoked in this case.

R-59782-36818-22157-37925-40398-63566-64063-39784 tcl slt th3 src

The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the exclusive "writer" lock on the database file.

src/wal.c:3324   tcl/e_walckpt.test:479

/* IMP: R-59782-36818 */
# EVIDENCE-OF: R-59782-36818 The SQLITE_CHECKPOINT_FULL, RESTART and
# TRUNCATE modes also obtain the exclusive "writer" lock on the database
# file.

R-60642-04082-57988-56847-11396-02756-59286-18214 tcl slt th3 src

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.

src/wal.c:3328   tcl/e_walckpt.test:502

/* IMP: R-60642-04082 */
# EVIDENCE-OF: 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-26810-18282-01790-21926-12239-51218 tcl slt th3 src

The busy-handler is also invoked while waiting for database readers as described above.

tcl/e_walckpt.test:507

/* IMP: R-48107-00250 */
# EVIDENCE-OF: R-48107-00250 The busy-handler is also invoked while
# waiting for database readers as described above.

R-49155-63541-44229-54839-02572-16362-28643-16859 tcl slt th3 src

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.

tcl/e_walckpt.test:573

/* IMP: R-49155-63541 */
# EVIDENCE-OF: 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-04461-63947-59293-07505-45589-19404 tcl slt th3 src

SQLITE_BUSY is returned in this case.

tcl/e_walckpt.test:567

/* IMP: R-34519-06271 */
# EVIDENCE-OF: R-34519-06271 SQLITE_BUSY is returned in this case.

R-00653-06026-13288-58570-29830-10892-52076-06124 tcl slt th3 src

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.

tcl/e_walckpt.test:158

/* IMP: R-00653-06026 */
# EVIDENCE-OF: 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.

R-38578-34175-46775-59738-25546-18239-05883-23898 tcl slt th3 src

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.

tcl/e_walckpt.test:661

/* IMP: R-38578-34175 */
# EVIDENCE-OF: 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-57133-40179-27689-18844-57300-61225 tcl slt th3 src

If any other error occurs while processing an attached database, processing is abandoned and the error code is returned to the caller immediately.

tcl/e_walckpt.test:678

/* IMP: R-38049-07913 */
# EVIDENCE-OF: 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-33031-60403-48286-21515-32111-27387 tcl slt th3 src

If no error (SQLITE_BUSY or otherwise) is encountered while processing the attached databases, SQLITE_OK is returned.

tcl/e_walckpt.test:647

/* IMP: R-41299-52117 */
# EVIDENCE-OF: R-41299-52117 If no error (SQLITE_BUSY or otherwise) is
# encountered while processing the attached databases, SQLITE_OK is
# returned.

R-14303-42483-31616-40850-13979-44263-42291-56182 tcl slt th3 src

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.

tcl/e_walckpt.test:197

/* IMP: R-14303-42483 */
# EVIDENCE-OF: 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-22949-56982-35182-46285-03543-37900 tcl slt th3 src

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.

tcl/e_walckpt.test:190

/* IMP: R-38207-48996 */
# EVIDENCE-OF: 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-15259-20158-13854-20870-19515-07838 tcl slt th3 src

Unless it returns SQLITE_MISUSE, the sqlite3_wal_checkpoint_v2() interface sets the error information that is queried by sqlite3_errcode() and sqlite3_errmsg().

tcl/e_walckpt.test:50

/* IMP: R-60567-47780 */
# EVIDENCE-OF: 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-15107-19022-47834-34931-59903-48809 tcl slt th3 src

The PRAGMA wal_checkpoint command can be used to invoke this interface from SQL.

tcl/e_walckpt.test:88

/* IMP: R-36706-10507 */
# EVIDENCE-OF: R-36706-10507 The PRAGMA wal_checkpoint command can be
# used to invoke this interface from SQL.