Documentation Source Text

<title>SQLite Backup API</title>
<tcl>hd_keywords {Using the SQLite Online Backup API}</tcl>

<style>

  pre a:visited, pre a:link { text-decoration: none ; color: #40534b }
  pre {
    background: #F3F3F3;
    float: right;
    padding: 1ex 2ex;
    margin-left: 1em;
    border: solid black 1px;
  }
  h1,h2 { clear: both ; text-align: center }
</style>


<h1>Using the SQLite Online Backup API</h1>

<p>
  Historically, backups (copies) of SQLite databases have been created
  using the following method:

<ol>
................................................................................
<p>
  During the 250 ms sleep in step 3 above, no read-lock is held on the database
  file and the mutex associated with pDb is not held. This allows other threads
  to use [database connection] pDb and other connections to write to the
  underlying database file. 

<p>
  If another thread writes to database connection pDb while this function is
  sleeping, then the backup database (database connection pFile) is
  automatically updated along with pDb. The backup process is continued after 
  the xSleep() call returns as if nothing had happened. If the database file 
  underlying connection pDb is written to by a different process or thread 
  using a different database connection while this function is sleeping, then 
  SQLite detects this within the next call made to sqlite3_backup_step() and 
  restarts the backup from the beginning. Either way, 
  the backup database is kept up to date during the backup process so that 
  when the operation is complete the backup database contains a consistent 
  snapshot of the original. However:

  <ul>
    <li> Accounting for writes to the database by an external process or thread
         using a different database connection are significantly more expensive
         than accounting for writes made using pDb.
    <li> If the database is being written using a database connection other
         than pDb sufficiently often while the backupDb() function is
         running, it may never finish.






  </ul>
 
<p><b>backup_remaining() and backup_pagecount()</b>

<p>
  The backupDb() function uses the sqlite3_backup_remaining() and
  sqlite3_backup_pagecount() functions to report its progress via the

<title>SQLite Backup API</title>
<tcl>hd_keywords {Using the SQLite Online Backup API}</tcl>

<style>
  /* Formatting for the blocks containing the example code */
  pre a:visited, pre a:link { text-decoration: none ; color: #40534b }
  pre { 
    background: #F3F3F3; 
    float: right; 
    padding: 1ex 2ex; 
    margin-left: 1em;
    border: solid black 1px; 
  }
  h1,h2 { clear: both }
</style>

<div class=fancy>
<h1>Using the SQLite Online Backup API</h1>

<p>
  Historically, backups (copies) of SQLite databases have been created
  using the following method:

<ol>
................................................................................
<p>
  During the 250 ms sleep in step 3 above, no read-lock is held on the database
  file and the mutex associated with pDb is not held. This allows other threads
  to use [database connection] pDb and other connections to write to the
  underlying database file. 

<p>
  If another thread or process writes to the source database while this 
  function is sleeping, then SQLite detects this and usually restarts the 
  backup process when sqlite3_backup_step() is next called. There is one 
  exception to this rule: If the source database is not an in-memory database,
  and the write is performed from within the same process as the backup
  operation and uses the same database handle (pDb), then the destination
  database (the one opened using connection pFile) is automatically updated
  along with the source. The backup process may then be continued after the 
  xSleep() call returns as if nothing had happened. 

<p>
  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:

  <ul>
    <li> Writes to an in-memory source database, or writes to a file-based 
         source database by an external process or thread using a 
         database connection other than pDb are signficantly more expensive 
         than writes made to a file-based source database using pDb (as the
         entire backup operation must be restarted in the former two cases).

    <li> If the backup process is restarted frequently enough it may never
         run to completion and the backupDb() function may never return.
  </ul>
 
<p><b>backup_remaining() and backup_pagecount()</b>

<p>
  The backupDb() function uses the sqlite3_backup_remaining() and
  sqlite3_backup_pagecount() functions to report its progress via the