SQLiteDatabase.Backup

From Xojo Documentation

Method

SQLiteDatabase.Backup(destination As SQLiteDatabase, callbackHandler As SQLiteBackupInterface = Nil, sleepTimeInMilliseconds As Integer = 10)

Supported for all project types and targets.

Backs up the database asynchronously or synchronously. You must be connected to the destination database and its original contents (if any) will be overwritten by the backup.

Notes

The backup works asynchronously by default, to receive feedback implement the SQLiteBackupInterface and supply it as the callbackHandler. The sleepTimeInMilliseconds is used to control how often chunks of data are backed up. Increase it to backup less frequently, making your app more responsive.

If you prefer this to work synchronously supply a sleepTimeInMilliseconds of -1. Your app will stop at the backup command and wait for the backup to complete.

You can also use the Backup command to copy an in-memory database to disk.

For asynchronous backups:

  • You must instantiate the callbackHandler and it must remain in scope for the duration of the backup.
  • The destination database instance must remain in scope for the duration of the backup.

Page Size Must be 4096 or Higher

In order for a backup to work with SQLite 3.12.0 (2016r3) or later, the page_size of your database must be 4096 or higher. Databases created with older versions of SQLite used a page_size of 1024. This SQL command displays the page_size:

   PRAGMA page_size;

To change the page_size of a DB, connect to the DB and set the page size before you send any other command, like this:

db.SQLExecute("PRAGMA page_size = 4096")

Examples

Back up a previously connected database synchronously. This means you app will pause and wait for the backup to finish:

Dim backupDBFile As FolderItem = GetSaveFolderItem("", "backup.sqlite")

If backupDBFile <> Nil Then
Dim backupDB As New SQLiteDatabase
backupDB.DatabaseFile = backupDBFile
If backupDB.CreateDatabaseFile Then
// db As SQLiteDatabase must be declared elsewhere
// and connected to your SQLite database.
db.Backup(backupDB, Nil, -1)
MsgBox("Backup finished!")
End If
End If

Backing up the database asynchronously requires the use of a separate class that implements SQLiteBackupInterface.

Dim backupFile As Folderitem
backupFile = GetSaveFolderItem("", "backup.sqlite")

If backupFile Is Nil Then Return

// This is a property on the Window so that it stays in scope when the method exits
mBackupDB = New SQLiteDatabase
mBackupDB.DatabaseFile = backupFile
If mBackupDB.CreateDatabaseFile Then
// This is a property on the Window so that it stays in scope when the method exits
mBackupHandler = New BackupHandler

// The window has a progress bar that is updated as the backup progresses
mBackupHandler.BackupProgressBar = BackupProgress
mDB.BackUp(mBackupDB, mBackupHandler)
End If

A class called BackupHandler implements SQLiteBackupInterface and has code in these methods:

Complete:

MsgBox("Backup Complete.")

Error:

MsgBox("There was an error during the backup: " + Str(errorCode))

Progress:

If BackupProgressBar <> Nil Then
BackupProgressBar.Maximum = 100
BackupProgressBar.Visible = True
BackupProgressBar.Value = percent*100
End If

In addition, it has a public property for the progress bar:

 BackupProgressBar As ProgressBar

Example Project

/Example Projects/Database/SQLite/SQLiteBackup

See Also

SQLiteBackupInterface