Struct Backup

pub struct Backup<'a, 'b> { /* private fields */ }

Available on crate feature backup only.

A handle to an online backup.

Implementations

impl Backup<'_, '_>

pub fn new<'a, 'b>( from: &'a Connection, to: &'b mut Connection, ) -> Result<Backup<'a, 'b>>

Attempt to create a new handle that will allow backups from from to to. Note that to is a &mut - this is because SQLite forbids any API calls on the destination of a backup while the backup is taking place.

Failure

Will return Err if the underlying sqlite3_backup_init call returns NULL.

pub fn new_with_names<'a, 'b>( from: &'a Connection, from_name: DatabaseName<'_>, to: &'b mut Connection, to_name: DatabaseName<'_>, ) -> Result<Backup<'a, 'b>>

Attempt to create a new handle that will allow backups from the from_name database of from to the to_name database of to. Note that to is a &mut - this is because SQLite forbids any API calls on the destination of a backup while the backup is taking place.

Failure

Will return Err if the underlying sqlite3_backup_init call returns NULL.

pub fn progress(&self) -> Progress

Gets the progress of the backup as of the last call to step.

pub fn step(&self, num_pages: c_int) -> Result<StepResult>

Attempts to back up the given number of pages. If num_pages is negative, will attempt to back up all remaining pages. This will hold a lock on the source database for the duration, so it is probably not what you want for databases that are currently active (see run_to_completion for a better alternative).

Failure

Will return Err if the underlying sqlite3_backup_step call returns an error code other than DONE, OK, BUSY, or LOCKED. BUSY and LOCKED are transient errors and are therefore returned as possible Ok values.

pub fn run_to_completion( &self, pages_per_step: c_int, pause_between_pages: Duration, progress: Option<fn(Progress)>, ) -> Result<()>

Attempts to run the entire backup. Will call step(pages_per_step) as many times as necessary, sleeping for pause_between_pages between each call to give the source database time to process any pending queries. This is a direct implementation of “Example 2: Online Backup of a Running Database” from SQLite’s Online Backup API documentation.

If progress is not None, it will be called after each step with the current progress of the backup. Note that is possible the progress may not change if the step returns Busy or Locked even though the backup is still running.

Failure

Will return Err if any of the calls to step return Err.

Trait Implementations

impl Drop for Backup<'_, '_>

fn drop(&mut self)

Executes the destructor for this type.