SQLite Requirement Matrix Details
backup_finish.html
Index Summary Markup Original
R-19628-13587-38733-35705-07447-40697-34819-47467 tcl slt th3 src
SQLite holds a write transaction open on the destination database file for the duration of the backup operation.
th3/req1/backup01.test:58
/* IMP: R-19628-13587 */
# EVIDENCE-OF: R-19628-13587 SQLite holds a write transaction open on # the destination database file for the duration of the backup # operation.
R-59712-18547-02212-00843-63183-21822-46730-58410 tcl slt th3 src
The source database is read-locked only while it is being read; it is not locked continuously for the entire backup operation.
th3/req1/backup01.test:78
/* IMP: R-59712-18547 */
# EVIDENCE-OF: R-59712-18547 The source database is read-locked only # while it is being read; it is not locked continuously for the entire # backup operation.
R-33315-53384-19536-00039-42426-59902-48545-24529 tcl slt th3 src
Thus, the backup may be performed on a live source database without preventing other database connections from reading or writing to the source database while the backup is underway.
th3/req1/backup01.test:82
/* IMP: R-33315-53384 */
# EVIDENCE-OF: R-33315-53384 Thus, the backup may be performed on a live # source database without preventing other database connections from # reading or writing to the source database while the backup is # underway.
R-47666-36489-24359-20436-03208-18550-24058-22275 tcl slt th3 src
To perform a backup operation:
- sqlite3_backup_init() is called once to initialize the backup,
- sqlite3_backup_step() is called one or more times to transfer the data between the two databases, and finally
- sqlite3_backup_finish() is called to release all resources associated with the backup operation.
th3/req1/backup01.test:10
/* IMP: R-47666-36489 */
# EVIDENCE-OF: R-47666-36489 To perform a backup operation: # sqlite3_backup_init() is called once to initialize the backup, # sqlite3_backup_step() is called one or more times to transfer the data # between the two databases, and finally sqlite3_backup_finish() is # called to release all resources associated with the backup operation.
R-25824-45489-43990-02774-35332-28137-18182-24527 tcl slt th3 src
The D and N arguments to sqlite3_backup_init(D,N,S,M) are the database connection associated with the destination database and the database name, respectively.
th3/req1/backup02.test:52
/* IMP: R-25824-45489 */
# EVIDENCE-OF: R-25824-45489 The D and N arguments to # sqlite3_backup_init(D,N,S,M) are the database connection associated # with the destination database and the database name, respectively.
R-03718-56652-35720-52480-53179-27141-13621-15908 tcl slt th3 src
The database name is "main" for the main database, "temp" for the temporary database, or the name specified after the AS keyword in an ATTACH statement for an attached database.
th3/req1/backup02.test:56
/* IMP: R-03718-56652 */
# EVIDENCE-OF: R-03718-56652 The database name is "main" for the main # database, "temp" for the temporary database, or the name specified # after the AS keyword in an ATTACH statement for an attached database.
R-17313-07189-19129-06928-03198-35699-51824-58751 tcl slt th3 src
The S and M arguments passed to sqlite3_backup_init(D,N,S,M) identify the database connection and database name of the source database, respectively.
th3/req1/backup02.test:60
/* IMP: R-17313-07189 */
# EVIDENCE-OF: R-17313-07189 The S and M arguments passed to # sqlite3_backup_init(D,N,S,M) identify the database connection and # database name of the source database, respectively.
R-56075-46525-28921-54400-33560-07294-24655-01890 tcl slt th3 src
The source and destination database connections (parameters S and D) must be different or else sqlite3_backup_init(D,N,S,M) will fail with an error.
th3/req1/backup02.test:119
/* IMP: R-56075-46525 */
# EVIDENCE-OF: R-56075-46525 The source and destination database # connections (parameters S and D) must be different or else # sqlite3_backup_init(D,N,S,M) will fail with an error.
R-63674-39978-56596-19929-61687-32380-54180-59144 tcl slt th3 src
A call to sqlite3_backup_init() will fail, returning NULL, if there is already a read or read-write transaction open on the destination database.
th3/cov1/backup01.test:267
/* IMP: R-63674-39978 */
# EVIDENCE-OF: R-63674-39978 A call to sqlite3_backup_init() will fail, # returning NULL, if there is already a read or read-write transaction # open on the destination database.
R-17817-46062-61072-05424-12542-62157-01447-33721 tcl slt th3 src
If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is returned and an error code and error message are stored in the destination database connection D.
th3/req1/backup02.test:123
/* IMP: R-17817-46062 */
# EVIDENCE-OF: R-17817-46062 If an error occurs within # sqlite3_backup_init(D,N,S,M), then NULL is returned and an error code # and error message are stored in the destination database connection D.
R-31338-54830-28259-56420-63783-19909-54858-57072 tcl slt th3 src
The error code and message for the failed call to sqlite3_backup_init() can be retrieved using the sqlite3_errcode(), sqlite3_errmsg(), and/or sqlite3_errmsg16() functions.
th3/req1/backup02.test:127
/* IMP: R-31338-54830 */
# EVIDENCE-OF: R-31338-54830 The error code and message for the failed # call to sqlite3_backup_init() can be retrieved using the # sqlite3_errcode(), sqlite3_errmsg(), and/or sqlite3_errmsg16() # functions.
R-18669-12610-19021-20460-56494-30622-24671-33359 tcl slt th3 src
A successful call to sqlite3_backup_init() returns a pointer to an sqlite3_backup object.
th3/req1/backup02.test:64
/* IMP: R-18669-12610 */
# EVIDENCE-OF: R-18669-12610 A successful call to sqlite3_backup_init() # returns a pointer to an sqlite3_backup object.
R-47106-26961-22018-10007-09993-39383-21640-46039 tcl slt th3 src
The sqlite3_backup object may be used with the sqlite3_backup_step() and sqlite3_backup_finish() functions to perform the specified backup operation.
th3/req1/backup02.test:67
/* IMP: R-47106-26961 */
# EVIDENCE-OF: R-47106-26961 The sqlite3_backup object may be used with # the sqlite3_backup_step() and sqlite3_backup_finish() functions to # perform the specified backup operation.
R-32172-42404-39492-45133-11034-45047-00308-58009 tcl slt th3 src
Function sqlite3_backup_step(B,N) will copy up to N pages between the source and destination databases specified by sqlite3_backup object B.
th3/req1/backup03.test:40
/* IMP: R-32172-42404 */
# EVIDENCE-OF: R-32172-42404 Function sqlite3_backup_step(B,N) will copy # up to N pages between the source and destination databases specified # by sqlite3_backup object B.
R-54272-29032-18669-23400-04748-20753-02544-31833 tcl slt th3 src
If N is negative, all remaining source pages are copied.
th3/req1/backup03.test:82
/* IMP: R-54272-29032 */
# EVIDENCE-OF: R-54272-29032 If N is negative, all remaining source # pages are copied.
R-49718-44437-53178-33073-48551-60632-45231-61036 tcl slt th3 src
If sqlite3_backup_step(B,N) successfully copies N pages and there are still more pages to be copied, then the function returns SQLITE_OK.
th3/req1/backup03.test:44
/* IMP: R-49718-44437 */
# EVIDENCE-OF: R-49718-44437 If sqlite3_backup_step(B,N) successfully # copies N pages and there are still more pages to be copied, then the # function returns SQLITE_OK.
R-53195-24238-49524-21833-03175-16230-23443-12553 tcl slt th3 src
If sqlite3_backup_step(B,N) successfully finishes copying all pages from source to destination, then it returns SQLITE_DONE.
th3/req1/backup03.test:48
/* IMP: R-53195-24238 */
# EVIDENCE-OF: R-53195-24238 If sqlite3_backup_step(B,N) successfully # finishes copying all pages from source to destination, then it returns # SQLITE_DONE.
R-62598-50665-64934-51801-32415-41213-44232-38622 tcl slt th3 src
If an error occurs while running sqlite3_backup_step(B,N), then an error code is returned.
th3/cov1/backup01.test:271
/* IMP: R-62598-50665 */
# EVIDENCE-OF: R-62598-50665 If an error occurs while running # sqlite3_backup_step(B,N), then an error code is returned.
R-06125-22327-52915-34188-45275-42271-34098-17754 tcl slt th3 src
As well as SQLITE_OK and SQLITE_DONE, a call to sqlite3_backup_step() may return SQLITE_READONLY, SQLITE_NOMEM, SQLITE_BUSY, SQLITE_LOCKED, or an SQLITE_IOERR_XXX extended error code.
/* IMP: R-06125-22327 */
# EVIDENCE-OF: R-06125-22327 As well as SQLITE_OK and SQLITE_DONE, a # call to sqlite3_backup_step() may return SQLITE_READONLY, # SQLITE_NOMEM, SQLITE_BUSY, SQLITE_LOCKED, or an SQLITE_IOERR_XXX # extended error code.
R-53520-01610-10679-40002-23178-34440-17674-23927 tcl slt th3 src
The sqlite3_backup_step() might return SQLITE_READONLY if
- the destination database was opened read-only, or
- the destination database is using write-ahead-log journaling and the destination and source page sizes differ, or
- the destination database is an in-memory database and the destination and source page sizes differ.
/* IMP: R-53520-01610 */
# EVIDENCE-OF: R-53520-01610 The sqlite3_backup_step() might return # SQLITE_READONLY if the destination database was opened read-only, or # the destination database is using write-ahead-log journaling and the # destination and source page sizes differ, or the destination database # is an in-memory database and the destination and source page sizes # differ.
R-03108-01565-06076-29544-14093-00699-65398-01477 tcl slt th3 src
If sqlite3_backup_step() cannot obtain a required file-system lock, then the busy-handler function is invoked (if one is specified).
/* IMP: R-03108-01565 */
# EVIDENCE-OF: R-03108-01565 If sqlite3_backup_step() cannot obtain a # required file-system lock, then the busy-handler function is invoked # (if one is specified).
R-06247-40710-32264-36174-63374-18082-50900-27234 tcl slt th3 src
If the busy-handler returns non-zero before the lock is available, then SQLITE_BUSY is returned to the caller.
/* IMP: R-06247-40710 */
# EVIDENCE-OF: R-06247-40710 If the busy-handler returns non-zero before # the lock is available, then SQLITE_BUSY is returned to the caller.
R-15620-41309-18590-43642-05731-59843-28363-36322 tcl slt th3 src
In this case the call to sqlite3_backup_step() can be retried later.
/* IMP: R-15620-41309 */
# EVIDENCE-OF: R-15620-41309 In this case the call to # sqlite3_backup_step() can be retried later.
R-29319-62175-31242-39109-13345-46061-10840-60903 tcl slt th3 src
If the source database connection is being used to write to the source database when sqlite3_backup_step() is called, then SQLITE_LOCKED is returned immediately.
/* IMP: R-29319-62175 */
# EVIDENCE-OF: R-29319-62175 If the source database connection is being # used to write to the source database when sqlite3_backup_step() is # called, then SQLITE_LOCKED is returned immediately.
R-12670-39947-34778-58945-43914-57818-35055-57037 tcl slt th3 src
Again, in this case the call to sqlite3_backup_step() can be retried later on.
/* IMP: R-12670-39947 */
# EVIDENCE-OF: R-12670-39947 Again, in this case the call to # sqlite3_backup_step() can be retried later on.
R-40502-12262-42819-60807-51435-51687-55446-47633 tcl slt th3 src
If SQLITE_IOERR_XXX, SQLITE_NOMEM, or SQLITE_READONLY is returned, then there is no point in retrying the call to sqlite3_backup_step(). These errors are considered fatal.
/* IMP: R-40502-12262 */
# EVIDENCE-OF: R-40502-12262 If SQLITE_IOERR_XXX, SQLITE_NOMEM, or # SQLITE_READONLY is returned, then there is no point in retrying the # call to sqlite3_backup_step(). These errors are considered fatal.
R-59866-40673-09200-10625-43441-33703-34788-06531 tcl slt th3 src
The first call to sqlite3_backup_step() obtains an exclusive lock on the destination file.
/* IMP: R-59866-40673 */
# EVIDENCE-OF: R-59866-40673 The first call to sqlite3_backup_step() # obtains an exclusive lock on the destination file.
R-45798-31769-08217-55662-19864-50738-55178-62419 tcl slt th3 src
The exclusive lock is not released until either sqlite3_backup_finish() is called or the backup operation is complete and sqlite3_backup_step() returns SQLITE_DONE.
/* IMP: R-45798-31769 */
# EVIDENCE-OF: R-45798-31769 The exclusive lock is not released until # either sqlite3_backup_finish() is called or the backup operation is # complete and sqlite3_backup_step() returns SQLITE_DONE.
R-30374-63100-15715-29897-06518-00278-46226-59168 tcl slt th3 src
Every call to sqlite3_backup_step() obtains a shared lock on the source database that lasts for the duration of the sqlite3_backup_step() call.
/* IMP: R-30374-63100 */
# EVIDENCE-OF: R-30374-63100 Every call to sqlite3_backup_step() obtains # a shared lock on the source database that lasts for the duration of # the sqlite3_backup_step() call.
R-43273-35828-43292-36541-60340-59124-40866-23243 tcl slt th3 src
Because the source database is not locked between calls to sqlite3_backup_step(), the source database may be modified mid-way through the backup process.
/* IMP: R-43273-35828 */
# EVIDENCE-OF: R-43273-35828 Because the source database is not locked # between calls to sqlite3_backup_step(), the source database may be # modified mid-way through the backup process.
R-07061-20551-45555-61970-58663-33619-01553-07889 tcl slt th3 src
If the source database is modified by an external process or via a database connection other than the one being used by the backup operation, then the backup will be automatically restarted by the next call to sqlite3_backup_step().
/* IMP: R-07061-20551 */
# EVIDENCE-OF: R-07061-20551 If the source database is modified by an # external process or via a database connection other than the one being # used by the backup operation, then the backup will be automatically # restarted by the next call to sqlite3_backup_step().
R-10964-23144-03179-07180-41128-15464-48410-22347 tcl slt th3 src
If the source database is modified by the using the same database connection as is used by the backup operation, then the backup database is automatically updated at the same time.
/* IMP: R-10964-23144 */
# EVIDENCE-OF: R-10964-23144 If the source database is modified by the # using the same database connection as is used by the backup operation, # then the backup database is automatically updated at the same time.
R-50786-24793-54635-21021-11581-63558-51983-08230 tcl slt th3 src
The sqlite3_backup_finish() interfaces releases all resources associated with the sqlite3_backup object.
/* IMP: R-50786-24793 */
# EVIDENCE-OF: R-50786-24793 The sqlite3_backup_finish() interfaces # releases all resources associated with the sqlite3_backup object.
R-44512-29500-51400-28317-41248-06688-48400-64915 tcl slt th3 src
If sqlite3_backup_step() has not yet returned SQLITE_DONE, then any active write-transaction on the destination database is rolled back.
/* IMP: R-44512-29500 */
# EVIDENCE-OF: R-44512-29500 If sqlite3_backup_step() has not yet # returned SQLITE_DONE, then any active write-transaction on the # destination database is rolled back.
R-36545-62345-61603-06376-33533-12580-59655-26356 tcl slt th3 src
The value returned by sqlite3_backup_finish is SQLITE_OK if no sqlite3_backup_step() errors occurred, regardless or whether or not sqlite3_backup_step() completed.
/* IMP: R-36545-62345 */
# EVIDENCE-OF: R-36545-62345 The value returned by sqlite3_backup_finish # is SQLITE_OK if no sqlite3_backup_step() errors occurred, regardless # or whether or not sqlite3_backup_step() completed.
R-61430-55629-14606-55181-61950-28043-41747-60450 tcl slt th3 src
If an out-of-memory condition or IO error occurred during any prior sqlite3_backup_step() call on the same sqlite3_backup object, then sqlite3_backup_finish() returns the corresponding error code.
/* IMP: R-61430-55629 */
# EVIDENCE-OF: R-61430-55629 If an out-of-memory condition or IO error # occurred during any prior sqlite3_backup_step() call on the same # sqlite3_backup object, then sqlite3_backup_finish() returns the # corresponding error code.
R-09068-40660-27195-07118-53993-03715-03215-45426 tcl slt th3 src
A return of SQLITE_BUSY or SQLITE_LOCKED from sqlite3_backup_step() is not a permanent error and does not affect the return value of sqlite3_backup_finish().
/* IMP: R-09068-40660 */
# EVIDENCE-OF: R-09068-40660 A return of SQLITE_BUSY or SQLITE_LOCKED # from sqlite3_backup_step() is not a permanent error and does not # affect the return value of sqlite3_backup_finish().
R-05475-27562-55227-25532-19767-14622-00601-03902 tcl slt th3 src
The sqlite3_backup_remaining() routine returns the number of pages still to be backed up at the conclusion of the most recent sqlite3_backup_step().
/* IMP: R-05475-27562 */
# EVIDENCE-OF: R-05475-27562 The sqlite3_backup_remaining() routine # returns the number of pages still to be backed up at the conclusion of # the most recent sqlite3_backup_step().
R-08903-51590-18062-24037-51123-18798-32019-19886 tcl slt th3 src
The sqlite3_backup_pagecount() routine returns the total number of pages in the source database at the conclusion of the most recent sqlite3_backup_step().
/* IMP: R-08903-51590 */
# EVIDENCE-OF: R-08903-51590 The sqlite3_backup_pagecount() routine # returns the total number of pages in the source database at the # conclusion of the most recent sqlite3_backup_step().
R-53666-61329-49768-59983-34751-33356-35133-56080 tcl slt th3 src
The values returned by these functions are only updated by sqlite3_backup_step(). If the source database is modified in a way that changes the size of the source database or the number of pages remaining, those changes are not reflected in the output of sqlite3_backup_pagecount() and sqlite3_backup_remaining() until after the next sqlite3_backup_step().
/* IMP: R-53666-61329 */
# EVIDENCE-OF: R-53666-61329 The values returned by these functions are # only updated by sqlite3_backup_step(). If the source database is # modified in a way that changes the size of the source database or the # number of pages remaining, those changes are not reflected in the # output of sqlite3_backup_pagecount() and sqlite3_backup_remaining() # until after the next sqlite3_backup_step().
R-29855-60809-01544-19871-54336-63942-18466-34966 tcl slt th3 src
The source database connection may be used by the application for other purposes while a backup operation is underway or being initialized.
/* IMP: R-29855-60809 */
# EVIDENCE-OF: R-29855-60809 The source database connection may be used # by the application for other purposes while a backup operation is # underway or being initialized.
R-61972-47750-14652-28694-02794-16402-15502-30377 tcl slt th3 src
If SQLite is compiled and configured to support threadsafe database connections, then the source database connection may be used concurrently from within other threads.
/* IMP: R-61972-47750 */
# EVIDENCE-OF: R-61972-47750 If SQLite is compiled and configured to # support threadsafe database connections, then the source database # connection may be used concurrently from within other threads.