SQLite 备份 API-未完纪

1. 使用 SQLite 在线备份 API

过去，SQLite 数据库的备份（副本）通常通过以下方式创建：

使用 SQLite API（例如命令行工具）在数据库文件上取得共享锁。
使用外部工具复制数据库文件，例如 Unix 的 cp 工具或 DOS 的 copy 命令。
释放第1步取得的数据库文件共享锁。

这种方法在许多场景中效果良好，而且通常很快。但它有以下不足：

创建备份期间，想要写入数据库文件的客户端必须等到共享锁释放后才能继续。
无法用它把数据复制到内存数据库，或从内存数据库复制数据。
复制数据库文件期间如果断电或操作系统发生故障，系统恢复后备份数据库可能已经损坏。

在线备份 API 就是为解决这些问题而创建的。它允许将一个数据库的内容复制到另一个数据库文件中，替换目标数据库原有的全部内容。复制可以分批进行；这样，无须在整个复制期间一直锁住源数据库，只需要在实际读取数据的短暂时间内加锁。

因此，在备份运行中的数据库时，其他数据库用户可以继续工作，而不会遭遇过长的延迟。完成整套备份调用后，目标数据库会成为源数据库在复制开始时的逐位相同副本，也就是一个“快照”。

在线备份 API 的正式说明见API 文档。本页余下部分提供两个 C 语言示例，展示 API 的常见用法并加以讨论。阅读这些示例不能替代阅读 API 文档。

1.1. 其他备份方法

在线备份 API 是为运行中的 SQLite 数据库创建备份的早期方法。后来还出现了其他可以实现同样目的的方法：

VACUUM INTO 命令可以把运行中的 SQLite 数据库复制到单独的文件中，并对副本执行清理压缩。
sqlite3_rsync 程序可以通过 SSH 连接，把运行中的 SQLite 数据库复制到远程系统，或从远程系统复制回来。

2. 示例1：加载和保存内存数据库


/*
** This function is used to load the contents of a database file on disk 
** into the "main" database of open database connection pInMemory, or
** to save the current contents of the database opened by pInMemory into
** a database file on disk. pInMemory is probably an in-memory database, 
** but this function will also work fine if it is not.
**
** Parameter zFilename points to a nul-terminated string containing the
** name of the database file on disk to load from or save to. If parameter
** isSave is non-zero, then the contents of the file zFilename are 
** overwritten with the contents of the database opened by pInMemory. If
** parameter isSave is zero, then the contents of the database opened by
** pInMemory are replaced by data loaded from the file zFilename.
**
** If the operation is successful, SQLITE_OK is returned. Otherwise, if
** an error occurs, an SQLite error code is returned.
*/
int loadOrSaveDb(sqlite3 *pInMemory, const char *zFilename, int isSave){
  int rc;                   /* Function return code */
  sqlite3 *pFile;           /* Database connection opened on zFilename */
  sqlite3_backup *pBackup;  /* Backup object used to copy data */
  sqlite3 *pTo;             /* Database to copy to (pFile or pInMemory) */
  sqlite3 *pFrom;           /* Database to copy from (pFile or pInMemory) */

  /* Open the database file identified by zFilename. Exit early if this fails
  ** for any reason. */
  rc = sqlite3_open(zFilename, &pFile);
  if( rc==SQLITE_OK ){

    /* If this is a 'load' operation (isSave==0), then data is copied
    ** from the database file just opened to database pInMemory. 
    ** Otherwise, if this is a 'save' operation (isSave==1), then data
    ** is copied from pInMemory to pFile.  Set the variables pFrom and
    ** pTo accordingly. */
    pFrom = (isSave ? pInMemory : pFile);
    pTo   = (isSave ? pFile     : pInMemory);

    /* Set up the backup procedure to copy from the "main" database of 
    ** connection pFile to the main database of connection pInMemory.
    ** If something goes wrong, pBackup will be set to NULL and an error
    ** code and message left in connection pTo.
    **
    ** If the backup object is successfully created, call backup_step()
    ** to copy data from pFile to pInMemory. Then call backup_finish()
    ** to release resources associated with the pBackup object.  If an
    ** error occurred, then an error code and message will be left in
    ** connection pTo. If no error occurred, then the error code belonging
    ** to pTo is set to SQLITE_OK.
    */
    pBackup = sqlite3_backup_init(pTo, "main", pFrom, "main");
    if( pBackup ){
      (void)sqlite3_backup_step(pBackup, -1);
      (void)sqlite3_backup_finish(pBackup);
    }
    rc = sqlite3_errcode(pTo);
  }

  /* Close the database connection opened on database file zFilename
  ** and return the result of this function. */
  (void)sqlite3_close(pFile);
  return rc;
}

上面的 C 函数展示了备份 API 最简单、也最常见的一种用法：把内存数据库的内容加载自磁盘文件，或保存到磁盘文件。示例按以下顺序使用备份 API：

调用 sqlite3_backup_init()，创建 sqlite3_backup 对象，用于在两个数据库之间复制数据。方向既可以是从文件到内存数据库，也可以相反。
调用 sqlite3_backup_step()，参数传入 -1，一次将整个源数据库复制到目标数据库。
调用 sqlite3_backup_finish()，清理 sqlite3_backup_init() 分配的资源。

2.1. 错误处理

三个主要备份 API 函数中任何一个发生错误时，错误码和错误消息都会附加到目标数据库连接上。另外，如果 sqlite3_backup_step() 遇到错误，它本身以及随后调用的 sqlite3_backup_finish() 都会返回该错误码。

因此，sqlite3_backup_finish() 不会覆盖 sqlite3_backup_step() 已存入目标数据库连接的错误码。示例利用这一特性简化了错误处理：忽略 sqlite3_backup_step() 和 sqlite3_backup_finish() 的返回值，随后从目标数据库连接读取表示复制成功或失败的错误码。

2.2. 可以改进的地方

这个函数至少可以从以下两方面改进：

处理无法获得数据库文件 zFilename 的锁的情况，即 SQLITE_BUSY 错误。
更好地处理数据库 pInMemory 与 zFilename 页大小不一致的情况。

数据库 zFilename 是磁盘上的文件，其他进程也可能访问它。因此，当 sqlite3_backup_step() 尝试读取或写入它时，可能无法取得所需的文件锁。发生这种情况时，当前实现会立即失败并返回 SQLITE_BUSY。

解决办法是在打开 pFile 数据库连接后，立即使用 sqlite3_busy_handler() 或 sqlite3_busy_timeout() 注册忙处理回调或超时。当无法立即取得所需的锁时，sqlite3_backup_step() 会像 sqlite3_step() 或 sqlite3_exec() 一样，使用已注册的忙处理回调或超时。

通常，覆盖目标数据库内容之前，源数据库与目标数据库页大小是否一致并不重要：备份操作会直接改变目标数据库的页大小。例外是目标数据库为内存数据库的情况。此时，如果备份开始时两者页大小不同，操作就会失败并返回 SQLITE_READONLY。

使用 loadOrSaveDb() 从文件向内存数据库加载数据库映像时，遗憾的是可能遇到这种情况。

不过，如果内存数据库 pInMemory 在传给 loadOrSaveDb() 之前刚刚打开，也就是仍然完全为空，则仍可通过 SQLite 的 PRAGMA page_size 命令改变其页大小。loadOrSaveDb() 可以检测这种情形，并在调用在线备份 API 之前，尝试把内存数据库的页大小设置成数据库 zFilename 的页大小。

3. 示例2：在线备份正在运行的数据库


/*
** Perform an online backup of database pDb to the database file named
** by zFilename. This function copies 5 database pages from pDb to
** zFilename, then unlocks pDb and sleeps for 250 ms, then repeats the
** process until the entire database is backed up.
** 
** The third argument passed to this function must be a pointer to a progress
** function. After each set of 5 pages is backed up, the progress function
** is invoked with two integer parameters: the number of pages left to
** copy, and the total number of pages in the source file. This information
** may be used, for example, to update a GUI progress bar.
**
** While this function is running, another thread may use the database pDb, or
** another process may access the underlying database file via a separate 
** connection.
**
** If the backup process is successfully completed, SQLITE_OK is returned.
** Otherwise, if an error occurs, an SQLite error code is returned.
*/
int backupDb(
  sqlite3 *pDb,               /* Database to back up */
  const char *zFilename,      /* Name of file to back up to */
  void(*xProgress)(int, int)  /* Progress function to invoke */     
){
  int rc;                     /* Function return code */
  sqlite3 *pFile;             /* Database connection opened on zFilename */
  sqlite3_backup *pBackup;    /* Backup handle used to copy data */

  /* Open the database file identified by zFilename. */
  rc = sqlite3_open(zFilename, &pFile);
  if( rc==SQLITE_OK ){

    /* Open the sqlite3_backup object used to accomplish the transfer */
    pBackup = sqlite3_backup_init(pFile, "main", pDb, "main");
    if( pBackup ){

      /* Each iteration of this loop copies 5 database pages from database
      ** pDb to the backup database. If the return value of backup_step()
      ** indicates that there are still further pages to copy, sleep for
      ** 250 ms before repeating. */
      do {
        rc = sqlite3_backup_step(pBackup, 5);
        xProgress(
            sqlite3_backup_remaining(pBackup),
            sqlite3_backup_pagecount(pBackup)
        );
        if( rc==SQLITE_OK || rc==SQLITE_BUSY || rc==SQLITE_LOCKED ){
          sqlite3_sleep(250);
        }
      } while( rc==SQLITE_OK || rc==SQLITE_BUSY || rc==SQLITE_LOCKED );

      /* Release resources allocated by backup_init(). */
      (void)sqlite3_backup_finish(pBackup);
    }
    rc = sqlite3_errcode(pFile);
  }
  
  /* Close the database connection opened on database file zFilename
  ** and return the result of this function. */
  (void)sqlite3_close(pFile);
  return rc;
}

前一个示例只调用一次 sqlite3_backup_step() 就复制整个源数据库。因此，整个操作期间都需要保持源数据库文件的读锁，阻止其他数据库用户写入。同时，它在整个复制期间持有 pInMemory 连接关联的互斥锁，阻止其他线程使用该连接。

本节的 C 函数适合由后台线程或进程调用，为运行中的数据库创建备份。它通过以下方式避免上述问题：

调用 sqlite3_backup_init()，创建 sqlite3_backup 对象，将数据库 pDb 的数据复制到由 zFilename 指定的备份数据库文件。
调用 sqlite3_backup_step()，参数传入 5，从数据库 pDb 复制5页到备份数据库（文件 zFilename）。
如果 pDb 还有页面未复制，则使用 sqlite3_sleep() 休眠250毫秒，然后返回第2步。
调用 sqlite3_backup_finish()，清理 sqlite3_backup_init() 分配的资源。

3.1. 文件和数据库连接的锁

在上述第3步的250毫秒休眠期间，程序不持有数据库文件的读锁，也不持有 pDb 关联的互斥锁。这使其他线程能够使用 pDb 数据库连接，也允许其他连接写入底层数据库文件。

如果其他线程或进程在休眠期间写入源数据库，SQLite 会检测到这一情况，并且通常会在下一次调用 sqlite3_backup_step() 时重新开始备份。

这条规则有一个例外：如果源数据库不是内存数据库，而且写入发生在备份操作所在的同一进程中，使用的也是同一个数据库句柄 pDb，那么目标数据库（通过 pFile 连接打开的数据库）会随源数据库一起自动更新。在 sqlite3_sleep() 返回后，备份便可以像什么也没有发生过一样继续进行。

无论中途写入是否导致备份重新开始，用户都可以确定：备份完成时，备份数据库包含原数据库一致且最新的快照。不过：

写入内存源数据库，或者由外部进程或线程通过 pDb 以外的连接写入文件型源数据库，其代价明显高于通过 pDb 写入文件型源数据库，因为前两种情况都必须重新开始整个备份操作。
如果备份重启得足够频繁，它可能永远无法完成，backupDb() 函数也可能永远不返回。

3.2. backup_remaining() 和 backup_pagecount()

backupDb() 使用 sqlite3_backup_remaining() 和 sqlite3_backup_pagecount()，通过用户提供的 xProgress() 回调报告进度。sqlite3_backup_remaining() 返回尚未复制的页数，sqlite3_backup_pagecount() 返回源数据库的总页数；这里的源数据库由 pDb 打开。因此，完成百分比可以计算为：

Completion = 100% * (pagecount() - remaining()) / pagecount()

sqlite3_backup_remaining() 与 sqlite3_backup_pagecount() 返回的是上一次调用 sqlite3_backup_step() 时保存的值，并不会实际检查源数据库文件。因此，如果其他线程或进程在 sqlite3_backup_step() 返回后、使用这两个 API 的返回值之前写入源数据库，那么这些值从严格意义上说可能已经不准确。通常这并不构成问题。

API 参考：在线备份接口 · 打开数据库连接 · 关闭数据库连接。

文章版权归作者所有，未经允许请勿转载。

THE END