Documentation Source Text

Check-in [f5ee14345e]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update backup.in to explain that writing to an in-memory source database mid-backup causes the entire backup operation to be restarted in the next call to backup_step().
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: f5ee14345ebcc05ea58be354ed7f2a23b9c8193a
User & Date: dan 2010-01-14 09:56:11.000
Context
2010-01-14
11:43
Fix an error in the matchinfo example in fts3.html. (check-in: ceff4c1d37 user: dan tags: trunk)
09:56
Update backup.in to explain that writing to an in-memory source database mid-backup causes the entire backup operation to be restarted in the next call to backup_step(). (check-in: f5ee14345e user: dan tags: trunk)
2010-01-13
22:15
Add fragments to headings of longer documents. (check-in: ad70832674 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/backup.in. 
1
2
3
4

5
6
7
8
9
10
11
12
13
14
15

16
17
18
19
20
21
22

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





>

|
|
|
|

|

|


>








1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

<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>
︙︙
325
326
327
328
329
330
331
332





333
334
335
336
337
338

339
340
341
342
343
344

345
346
347

348

349
350
351
352
353
354
355
356
357

<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








|
>
>
>
>
>
|
|
|
|
<
<
>
|
|
|
|


>
|
|
|
>
|
>
|
<








327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343


344
345
346
347
348
349
350
351
352
353
354
355
356
357
358

359
360
361
362
363
364
365

<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
︙︙