sqlite::backup

Incremental backup wrapper

Represents an in-flight SQLite incremental backup. The object owns the sqlite3_backup* handle and automatically finalizes it when destroyed, so backups complete even if exceptions propagate.

Use cases

  • Ideal for online backups—run it while the source stays writable and copy a fixed number of pages per loop to reduce I/O spikes.
  • Accepts separate sqlite::connection instances, so you can back up from a live file to an in-memory connection (or vice versa).
  • Throws sqlite::database_exception when SQLite reports an error; no need to handle sqlite3_backup_step return codes manually.
  • Pairs well with sqlite::snapshot or sqlite::transaction when you need to guarantee a consistent read view.

Example usage

sqlite::connection live{"/srv/data/live.db"};
sqlite::connection staging{"/srv/data/staging.db",
                           sqlite::open_mode::always_create};

sqlite::backup copier{staging, live};
while (copier.step(256)) {
    std::this_thread::sleep_for(std::chrono::milliseconds(10));
}
copier.finish();

Copying in batches like this gives the writer breathing room; if you truly need “copy everything now”, call step(-1) once.

Public API

MemberDescription
backup(connection& dst, connection& src) Begins copying pages from the source connection to the destination connection.
backup(backup const&)=delete, backup& operator=(backup const&)=delete Backups are non-copyable because they own a unique SQLite handle.
~backup() Finishes the backup automatically if the caller did not explicitly call finish().
bool step(int nPage = -1) Copies up to nPage pages; pass a negative value to copy every remaining page. Returns true while work remains.
void finish() Finalizes the backup immediately. After calling this method, the object becomes inert.