Small. Fast. Reliable.
Choose any three.

SQLite C Interface

Online Backup API.

sqlite3_backup *sqlite3_backup_init(
  sqlite3 *pDest,                        /* Destination database handle */
  const char *zDestName,                 /* Destination database name */
  sqlite3 *pSource,                      /* Source database handle */
  const char *zSourceName                /* Source database name */
);
int sqlite3_backup_step(sqlite3_backup *p, int nPage);
int sqlite3_backup_finish(sqlite3_backup *p);
int sqlite3_backup_remaining(sqlite3_backup *p);
int sqlite3_backup_pagecount(sqlite3_backup *p);

Important: This interface is experimental and is subject to change without notice.

This API is used to overwrite the contents of one database with that of another. It is useful either for creating backups of databases or for copying in-memory databases to or from persistent files.

See Also: Using the SQLite Online Backup API

Exclusive access is required to the destination database for the duration of the operation. However the source database is only read-locked while it is actually being read, it is not locked continuously for the entire operation. Thus, the backup may be performed on a live database without preventing other users from writing to the database for an extended period of time.

To perform a backup operation:

  1. sqlite3_backup_init() is called once to initialize the backup,
  2. sqlite3_backup_step() is called one or more times to transfer the data between the two databases, and finally
  3. sqlite3_backup_finish() is called to release all resources associated with the backup operation.
There should be exactly one call to sqlite3_backup_finish() for each successful call to sqlite3_backup_init().

sqlite3_backup_init()

The first two arguments passed to sqlite3_backup_init() are the database handle associated with the destination database and the database name used to attach the destination database to the handle. The database name is "main" for the main database, "temp" for the temporary database, or the name specified as part of the ATTACH statement if the destination is an attached database. The third and fourth arguments passed to sqlite3_backup_init() identify the database connection and database name used to access the source database. The values passed for the source and destination database connection parameters must not be the same.

If an error occurs within sqlite3_backup_init(), then NULL is returned and an error code and error message written into the database connection passed as the first argument. They may be retrieved using the sqlite3_errcode(), sqlite3_errmsg(), and sqlite3_errmsg16() functions. Otherwise, if successful, a pointer to an sqlite3_backup object is returned. This pointer may be used with the sqlite3_backup_step() and sqlite3_backup_finish() functions to perform the specified backup operation.

sqlite3_backup_step()

Function sqlite3_backup_step() is used to copy up to nPage pages between the source and destination databases, where nPage is the value of the second parameter passed to sqlite3_backup_step(). If nPage is a negative value, all remaining source pages are copied. If the required pages are succesfully copied, but there are still more pages to copy before the backup is complete, it returns SQLITE_OK. If no error occured and there are no more pages to copy, then SQLITE_DONE is returned. If an error occurs, then an SQLite error code is returned. As well as SQLITE_OK and SQLITE_DONE, a call to sqlite3_backup_step() may return SQLITE_READONLY, SQLITE_NOMEM, SQLITE_BUSY, SQLITE_LOCKED, or an SQLITE_IOERR_XXX extended error code.

As well as the case where the destination database file was opened for read-only access, sqlite3_backup_step() may return SQLITE_READONLY if the destination is an in-memory database with a different page size from the source database.

If sqlite3_backup_step() cannot obtain a required file-system lock, then the busy-handler function is invoked (if one is specified). If the busy-handler returns non-zero before the lock is available, then SQLITE_BUSY is returned to the caller. In this case the call to sqlite3_backup_step() can be retried later. If the source database connection is being used to write to the source database when sqlite3_backup_step() is called, then SQLITE_LOCKED is returned immediately. Again, in this case the call to sqlite3_backup_step() can be retried later on. If SQLITE_IOERR_XXX, SQLITE_NOMEM, or SQLITE_READONLY is returned, then there is no point in retrying the call to sqlite3_backup_step(). These errors are considered fatal. At this point the application must accept that the backup operation has failed and pass the backup operation handle to the sqlite3_backup_finish() to release associated resources.

Following the first call to sqlite3_backup_step(), an exclusive lock is obtained on the destination file. It is not released until either sqlite3_backup_finish() is called or the backup operation is complete and sqlite3_backup_step() returns SQLITE_DONE. Additionally, each time a call to sqlite3_backup_step() is made a shared lock is obtained on the source database file. This lock is released before the sqlite3_backup_step() call returns. Because the source database is not locked between calls to sqlite3_backup_step(), it may be modified mid-way through the backup procedure. If the source database is modified by an external process or via a database connection other than the one being used by the backup operation, then the backup will be transparently restarted by the next call to sqlite3_backup_step(). If the source database is modified by the using the same database connection as is used by the backup operation, then the backup database is transparently updated at the same time.

sqlite3_backup_finish()

Once sqlite3_backup_step() has returned SQLITE_DONE, or when the application wishes to abandon the backup operation, the sqlite3_backup object should be passed to sqlite3_backup_finish(). This releases all resources associated with the backup operation. If sqlite3_backup_step() has not yet returned SQLITE_DONE, then any active write-transaction on the destination database is rolled back. The sqlite3_backup object is invalid and may not be used following a call to sqlite3_backup_finish().

The value returned by sqlite3_backup_finish is SQLITE_OK if no error occurred, regardless or whether or not sqlite3_backup_step() was called a sufficient number of times to complete the backup operation. Or, if an out-of-memory condition or IO error occured during a call to sqlite3_backup_step() then SQLITE_NOMEM or an SQLITE_IOERR_XXX error code is returned. In this case the error code and an error message are written to the destination database connection.

A return of SQLITE_BUSY or SQLITE_LOCKED from sqlite3_backup_step() is not a permanent error and does not affect the return value of sqlite3_backup_finish().

sqlite3_backup_remaining(), sqlite3_backup_pagecount()

Each call to sqlite3_backup_step() sets two values stored internally by an sqlite3_backup object. The number of pages still to be backed up, which may be queried by sqlite3_backup_remaining(), and the total number of pages in the source database file, which may be queried by sqlite3_backup_pagecount().

The values returned by these functions are only updated by sqlite3_backup_step(). If the source database is modified during a backup operation, then the values are not updated to account for any extra pages that need to be updated or the size of the source database file changing.

Concurrent Usage of Database Handles

The source database connection may be used by the application for other purposes while a backup operation is underway or being initialized. If SQLite is compiled and configured to support threadsafe database connections, then the source database connection may be used concurrently from within other threads.

However, the application must guarantee that the destination database connection handle is not passed to any other API (by any thread) after sqlite3_backup_init() is called and before the corresponding call to sqlite3_backup_finish(). Unfortunately SQLite does not currently check for this, if the application does use the destination database connection for some other purpose during a backup operation, things may appear to work correctly but in fact be subtly malfunctioning. Use of the destination database connection while a backup is in progress might also cause a mutex deadlock.

Furthermore, if running in shared cache mode, the application must guarantee that the shared cache used by the destination database is not accessed while the backup is running. In practice this means that the application must guarantee that the file-system file being backed up to is not accessed by any connection within the process, not just the specific connection that was passed to sqlite3_backup_init().

The sqlite3_backup object itself is partially threadsafe. Multiple threads may safely make multiple concurrent calls to sqlite3_backup_step(). However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() APIs are not strictly speaking threadsafe. If they are invoked at the same time as another thread is invoking sqlite3_backup_step() it is possible that they return invalid values.

See also lists of Objects, Constants, and Functions.


This page last modified 2009/07/31 12:35:28 UTC