sql.backupInit - Core4 Lua Commands

SYNOPSIS

handle = sql.backupInit(dstdb, srcdb)
handle = sql.backupInit(dstdb, dstname, srcdb, srcname)
status = handle:backupStep(pagecount)
status = handle:backupFinish()
count = handle:backupRemaining()
count = handle:backupPageCount()
handle:close()

DESCRIPTION

These functions are a lightweight wrapper around Sqlite3's built in backup feature.

A backup is performed by copying the contents of one database file into another. To avoid blocking the CPU for too long, the backup is done in small steps on the side, while the application can continue using the source database.

At the end of the backup, the destination file contains the state of the database at that exact point in time when the backup has finished.

For further details, also refer to the official Sqlite3 documentation.

sql.backupInit() prepares a backup. After acquiring a backup handle, no other code must access the destination database until the backup has finished. Failing to do so may cause the backup to produce incorrect data.

To run the backup, call handle:backupStep() periodically until it signals completion. The parameter pagecount determines how much data is copied each step. The larger this value, the more time each step takes, but the faster the overall performance. This value should be tuned to keep the main application responsive.

At the end of the backup, call handle:backupFinish() to clean up, then drop the handle with handle:close(). The close() call does an implicit finish if the finish call was not made, but then it is impossible to check for errors of the finish call.

If any of the database handles is closed while there is an active backup handle, the backup is aborted, the backup handle becomes stale (unusable) and the contents of the backup file are undefined.

RETURN VALUE

sql.backupInit() returns a handle to manage the backup. This handle is used to make further calls into the backup API. On failure, the method returns nil.

handle:backupStep() returns true if more calls to handle:backupStep() are necessary. It returns false when all data was copied. The return value nil indicates an error.

handle:backupFinish() must be called after the last call to handle:backupStep(). It returns true on success and nil on error.

For any error, detailed information is acquired by calling sql:lastError() on the destination database handle.

EXAMPLE

dbsrc = sql.open("exampledata.sqlite") dbdst = sql.open("/tmp/backup.sqlite") handle = sql.backupInit(dbdst, dbsrc) local stepresult while true do stepresult = handle:backupStep(20) if (not stepresult) then break end end if (stepresult == nil) then -- STEP FAILED end local finresult = handle:backupFinish() if (not finresult) then -- FINISH FAILED end handle:close()