The ooSQLiteBackup Class

One feature of SQLite is an online backup API. The online part means that a database can be backed up while it is in use. The backup API copies the content of the source database into the destination database, overwriting the original contents of the destination database. It is useful either for creating backups of databases or for copying in-memory databases to or from persistent files.

The copy operation may be done incrementally, in which case the source database does not need to be locked for the duration of the copy, only for the brief periods of time when it is actually being read from. This allows other database users to continue uninterrupted while a backup of an online database is made.

The ooSQLiteBackup class provides a complete interface to the SQLite backup API. The authoritive documentation for using the online backup API is the SQLite documentation. The basic process to perform a backup using the ooSQLiteBackup object is as follows:

By using a backup object, ooSQLite is able to optimize this process a little for the Rexx programmer. During the step method, when it is determined that all the pages have been copied successfully, or that a fatal error has ocurred, the finish method is invvoked automatically. This means the programmer only needs to use finish when it is determined that the backup should be abandoned before it is done.

The source database can be accessed while the backup is in progress. It is only locked while the backup is reading from the database, it is not locked continuously for the entire backup operation. This implies that the source database is more acessible when a smaller number of pages are copied during each step.

When the source database is in use while the backup is in progress, if the database is written to, the database engine may restart the backup. Whether or not the backup process is restarted as a result of writes to the source database mid-backup, the user can be sure that when the backup operation is completed the backup database contains a consistent and up-to-date snapshot of the original. However, if the source database is big and the backup gets restarted often, it is possible that the backup will never finish. This would be a case where it might be needed to abandon the backup.