Allow for SQLite online-backup restarts under concurrent writes

Test completion under realistic write activity when an application uses incremental SQLite backups.

Source facts

SQLite’s Online Backup API can copy a running database incrementally, limiting the periods during which the source is read-locked. Writes from another process or another database connection can cause the backup to restart during the next step. With sufficiently frequent restarts, an incremental backup may never finish. The page-count and remaining-page APIs report values from the previous backup step, rather than independently inspecting current source size. A progress display therefore needs interpretation as well as an eventual completion result.

Source: SQLite — Online Backup API.

Applicability

This applies to applications using SQLite’s documented Online Backup API. It concerns behavior under concurrent writes, not the validity of copying an open database file with a generic filesystem tool.

DSE recommendation

DSE recommends giving incremental backup jobs a supervised completion deadline and recording restart or progress behavior under realistic write activity. Ask the application developer to handle busy conditions and final return codes explicitly. Avoid declaring a backup healthy merely because its progress callback is still firing. If the workload prevents completion, review step sizing, scheduling, and an application-supported quiet interval. Preserve the source service’s consistency requirements rather than adding an unreviewed file-copy fallback to bypass the API.

Verification

Run the backup implementation against disposable data while a second connection performs representative writes. Observe whether it completes and how progress changes. Open the completed destination separately and check agreed records. Retain final status and elapsed time, including any run that failed to reach completion.

Official reference

SQLite — Online Backup API. Reviewed October 15, 2026.