SQLiteDatabase.Backup

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:

Var backupDBFile As FolderItem = FolderItem.ShowSaveFileDialog("", "backup.sqlite")

If backupDBFile <> Nil Then
Var backupDB As New SQLiteDatabase
backupDB.DatabaseFile = backupDBFile
Try
backupDB.CreateDatabase
// db As SQLiteDatabase must be declared elsewhere
// and connected to your SQLite database.
db.Backup(backupDB, Nil, -1)
MsgBox("Backup finished!")
Catch error As IOException
MsgBox("Failed to create backup database. Error: " + error.Message)
End Try
End If

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

Var backupFile As Folderitem
backupFile = FolderItem.ShowSaveFileDialog("", "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
Try
mBackupDB.CreateDatabase 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)
Catch error As IOException
MsgBox("Backup Database could not be created. Error: " + error.Message)
End Try
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