Documentation Source Text

Hex Artifact Content
Login

Artifact 76e8b5e552ba765896ea7bd8956eafcc5536d77d:


0000: 3c 74 69 74 6c 65 3e 53 51 4c 69 74 65 20 42 61  <title>SQLite Ba
0010: 63 6b 75 70 20 41 50 49 3c 2f 74 69 74 6c 65 3e  ckup API</title>
0020: 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79 77 6f 72 64  .<tcl>hd_keyword
0030: 73 20 7b 55 73 69 6e 67 20 74 68 65 20 53 51 4c  s {Using the SQL
0040: 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63 6b 75  ite Online Backu
0050: 70 20 41 50 49 7d 20 7b 62 61 63 6b 75 70 20 41  p API} {backup A
0060: 50 49 7d 3c 2f 74 63 6c 3e 0a 0a 3c 73 74 79 6c  PI}</tcl>..<styl
0070: 65 3e 0a 20 20 2f 2a 20 46 6f 72 6d 61 74 74 69  e>.  /* Formatti
0080: 6e 67 20 66 6f 72 20 74 68 65 20 62 6c 6f 63 6b  ng for the block
0090: 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  s containing the
00a0: 20 65 78 61 6d 70 6c 65 20 63 6f 64 65 20 2a 2f   example code */
00b0: 0a 20 20 70 72 65 20 61 3a 76 69 73 69 74 65 64  .  pre a:visited
00c0: 2c 20 70 72 65 20 61 3a 6c 69 6e 6b 20 7b 20 74  , pre a:link { t
00d0: 65 78 74 2d 64 65 63 6f 72 61 74 69 6f 6e 3a 20  ext-decoration: 
00e0: 6e 6f 6e 65 20 3b 20 63 6f 6c 6f 72 3a 20 23 34  none ; color: #4
00f0: 30 35 33 34 62 20 7d 0a 20 20 70 72 65 20 7b 20  0534b }.  pre { 
0100: 0a 20 20 20 20 62 61 63 6b 67 72 6f 75 6e 64 3a  .    background:
0110: 20 23 46 33 46 33 46 33 3b 20 0a 20 20 20 20 66   #F3F3F3; .    f
0120: 6c 6f 61 74 3a 20 72 69 67 68 74 3b 20 0a 20 20  loat: right; .  
0130: 20 20 70 61 64 64 69 6e 67 3a 20 31 65 78 20 32    padding: 1ex 2
0140: 65 78 3b 20 0a 20 20 20 20 6d 61 72 67 69 6e 2d  ex; .    margin-
0150: 6c 65 66 74 3a 20 31 65 6d 3b 0a 20 20 20 20 62  left: 1em;.    b
0160: 6f 72 64 65 72 3a 20 73 6f 6c 69 64 20 62 6c 61  order: solid bla
0170: 63 6b 20 31 70 78 3b 20 0a 20 20 7d 0a 20 20 68  ck 1px; .  }.  h
0180: 31 2c 68 32 20 7b 20 63 6c 65 61 72 3a 20 62 6f  1,h2 { clear: bo
0190: 74 68 20 7d 0a 3c 2f 73 74 79 6c 65 3e 0a 0a 3c  th }.</style>..<
01a0: 64 69 76 20 63 6c 61 73 73 3d 66 61 6e 63 79 3e  div class=fancy>
01b0: 0a 3c 68 31 3e 55 73 69 6e 67 20 74 68 65 20 53  .<h1>Using the S
01c0: 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63  QLite Online Bac
01d0: 6b 75 70 20 41 50 49 3c 2f 68 31 3e 0a 0a 3c 70  kup API</h1>..<p
01e0: 3e 0a 20 20 48 69 73 74 6f 72 69 63 61 6c 6c 79  >.  Historically
01f0: 2c 20 62 61 63 6b 75 70 73 20 28 63 6f 70 69 65  , backups (copie
0200: 73 29 20 6f 66 20 53 51 4c 69 74 65 20 64 61 74  s) of SQLite dat
0210: 61 62 61 73 65 73 20 68 61 76 65 20 62 65 65 6e  abases have been
0220: 20 63 72 65 61 74 65 64 0a 20 20 75 73 69 6e 67   created.  using
0230: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d   the following m
0240: 65 74 68 6f 64 3a 0a 0a 3c 6f 6c 3e 0a 20 20 3c  ethod:..<ol>.  <
0250: 6c 69 3e 20 45 73 74 61 62 6c 69 73 68 20 61 20  li> Establish a 
0260: 73 68 61 72 65 64 20 6c 6f 63 6b 20 6f 6e 20 74  shared lock on t
0270: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
0280: 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 69 74   using the SQLit
0290: 65 20 41 50 49 20 28 69 2e 65 2e 0a 20 20 20 20  e API (i.e..    
02a0: 20 20 20 74 68 65 20 73 68 65 6c 6c 20 74 6f 6f     the shell too
02b0: 6c 29 2e 0a 20 20 3c 6c 69 3e 20 43 6f 70 79 20  l)..  <li> Copy 
02c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
02d0: 65 20 75 73 69 6e 67 20 61 6e 20 65 78 74 65 72  e using an exter
02e0: 6e 61 6c 20 74 6f 6f 6c 20 28 66 6f 72 20 65 78  nal tool (for ex
02f0: 61 6d 70 6c 65 20 74 68 65 20 75 6e 69 78 20 27  ample the unix '
0300: 63 70 27 0a 20 20 20 20 20 20 20 75 74 69 6c 69  cp'.       utili
0310: 74 79 20 6f 72 20 74 68 65 20 44 4f 53 20 27 63  ty or the DOS 'c
0320: 6f 70 79 27 20 63 6f 6d 6d 61 6e 64 29 2e 0a 20  opy' command).. 
0330: 20 3c 6c 69 3e 20 52 65 6c 69 6e 71 75 69 73 68   <li> Relinquish
0340: 20 74 68 65 20 73 68 61 72 65 64 20 6c 6f 63 6b   the shared lock
0350: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
0360: 20 66 69 6c 65 20 6f 62 74 61 69 6e 65 64 20 69   file obtained i
0370: 6e 20 73 74 65 70 20 31 2e 0a 3c 2f 6f 6c 3e 0a  n step 1..</ol>.
0380: 0a 3c 70 3e 0a 20 20 54 68 69 73 20 70 72 6f 63  .<p>.  This proc
0390: 65 64 75 72 65 20 77 6f 72 6b 73 20 77 65 6c 6c  edure works well
03a0: 20 69 6e 20 6d 61 6e 79 20 73 63 65 6e 61 72 69   in many scenari
03b0: 6f 73 20 61 6e 64 20 69 73 20 75 73 75 61 6c 6c  os and is usuall
03c0: 79 20 76 65 72 79 0a 20 20 66 61 73 74 2e 20 48  y very.  fast. H
03d0: 6f 77 65 76 65 72 2c 20 74 68 69 73 20 74 65 63  owever, this tec
03e0: 68 6e 69 71 75 65 20 68 61 73 20 74 68 65 20 66  hnique has the f
03f0: 6f 6c 6c 6f 77 69 6e 67 20 73 68 6f 72 74 63 6f  ollowing shortco
0400: 6d 69 6e 67 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c  mings:..<ul>.  <
0410: 6c 69 3e 20 41 6e 79 20 64 61 74 61 62 61 73 65  li> Any database
0420: 20 63 6c 69 65 6e 74 73 20 77 69 73 68 69 6e 67   clients wishing
0430: 20 74 6f 20 77 72 69 74 65 20 74 6f 20 74 68 65   to write to the
0440: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
0450: 68 69 6c 65 20 61 0a 20 20 20 20 20 20 20 62 61  hile a.       ba
0460: 63 6b 75 70 20 69 73 20 62 65 69 6e 67 20 63 72  ckup is being cr
0470: 65 61 74 65 64 20 6d 75 73 74 20 77 61 69 74 20  eated must wait 
0480: 75 6e 74 69 6c 20 74 68 65 20 73 68 61 72 65 64  until the shared
0490: 20 6c 6f 63 6b 20 69 73 0a 20 20 20 20 20 20 20   lock is.       
04a0: 72 65 6c 69 6e 71 75 69 73 68 65 64 2e 0a 0a 20  relinquished... 
04b0: 20 3c 6c 69 3e 20 49 74 20 63 61 6e 6e 6f 74 20   <li> It cannot 
04c0: 62 65 20 75 73 65 64 20 74 6f 20 63 6f 70 79 20  be used to copy 
04d0: 64 61 74 61 20 74 6f 20 6f 72 20 66 72 6f 6d 20  data to or from 
04e0: 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
04f0: 73 65 73 2e 0a 0a 20 20 3c 6c 69 3e 20 49 66 20  ses...  <li> If 
0500: 61 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65 20  a power failure 
0510: 6f 72 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  or operating sys
0520: 74 65 6d 20 66 61 69 6c 75 72 65 20 6f 63 63 75  tem failure occu
0530: 72 73 20 77 68 69 6c 65 20 63 6f 70 79 69 6e 67  rs while copying
0540: 0a 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61  .       the data
0550: 62 61 73 65 20 66 69 6c 65 20 74 68 65 20 62 61  base file the ba
0560: 63 6b 75 70 20 64 61 74 61 62 61 73 65 20 6d 61  ckup database ma
0570: 79 20 62 65 20 63 6f 72 72 75 70 74 65 64 20 66  y be corrupted f
0580: 6f 6c 6c 6f 77 69 6e 67 0a 20 20 20 20 20 20 20  ollowing.       
0590: 73 79 73 74 65 6d 20 72 65 63 6f 76 65 72 79 2e  system recovery.
05a0: 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 0a 20 20 54 68  .</ul>..<p>.  Th
05b0: 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  e [sqlite3_backu
05c0: 70 5f 69 6e 69 74 20 7c 20 4f 6e 6c 69 6e 65 20  p_init | Online 
05d0: 42 61 63 6b 75 70 20 41 50 49 5d 20 77 61 73 20  Backup API] was 
05e0: 63 72 65 61 74 65 64 20 74 6f 20 0a 20 20 61 64  created to .  ad
05f0: 64 72 65 73 73 20 74 68 65 73 65 20 63 6f 6e 63  dress these conc
0600: 65 72 6e 73 2e 20 54 68 65 20 6f 6e 6c 69 6e 65  erns. The online
0610: 20 62 61 63 6b 75 70 20 41 50 49 20 61 6c 6c 6f   backup API allo
0620: 77 73 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  ws the contents 
0630: 6f 66 0a 20 20 6f 6e 65 20 64 61 74 61 62 61 73  of.  one databas
0640: 65 20 74 6f 20 62 65 20 63 6f 70 69 65 64 20 69  e to be copied i
0650: 6e 74 6f 20 61 6e 6f 74 68 65 72 20 64 61 74 61  nto another data
0660: 62 61 73 65 2c 20 6f 76 65 72 77 72 69 74 69 6e  base, overwritin
0670: 67 20 74 68 65 20 0a 20 20 6f 72 69 67 69 6e 61  g the .  origina
0680: 6c 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68  l contents of th
0690: 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73  e target databas
06a0: 65 2e 20 54 68 65 20 63 6f 70 79 20 6f 70 65 72  e. The copy oper
06b0: 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 0a 20 20  ation may be .  
06c0: 64 6f 6e 65 20 69 6e 63 72 65 6d 65 6e 74 61 6c  done incremental
06d0: 6c 79 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ly, in which cas
06e0: 65 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 74  e the source dat
06f0: 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 20 6e  abase does not n
0700: 65 65 64 0a 20 20 74 6f 20 62 65 20 6c 6f 63 6b  eed.  to be lock
0710: 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  ed for the durat
0720: 69 6f 6e 20 6f 66 20 74 68 65 20 63 6f 70 79 2c  ion of the copy,
0730: 20 6f 6e 6c 79 20 66 6f 72 20 74 68 65 20 62 72   only for the br
0740: 69 65 66 20 70 65 72 69 6f 64 73 0a 20 20 6f 66  ief periods.  of
0750: 20 74 69 6d 65 20 77 68 65 6e 20 69 74 20 69 73   time when it is
0760: 20 61 63 74 75 61 6c 6c 79 20 62 65 69 6e 67 20   actually being 
0770: 72 65 61 64 20 66 72 6f 6d 2e 20 54 68 69 73 20  read from. This 
0780: 61 6c 6c 6f 77 73 20 6f 74 68 65 72 20 64 61 74  allows other dat
0790: 61 62 61 73 65 0a 20 20 75 73 65 72 73 20 74 6f  abase.  users to
07a0: 20 63 6f 6e 74 69 6e 75 65 20 75 6e 69 6e 74 65   continue uninte
07b0: 72 72 75 70 74 65 64 20 77 68 69 6c 65 20 61 20  rrupted while a 
07c0: 62 61 63 6b 75 70 20 6f 66 20 61 6e 20 6f 6e 6c  backup of an onl
07d0: 69 6e 65 20 64 61 74 61 62 61 73 65 20 69 73 0a  ine database is.
07e0: 20 20 6d 61 64 65 2e 0a 0a 3c 70 3e 0a 20 20 54    made...<p>.  T
07f0: 68 65 20 6f 6e 6c 69 6e 65 20 62 61 63 6b 75 70  he online backup
0800: 20 41 50 49 20 69 73 20 5b 73 71 6c 69 74 65 33   API is [sqlite3
0810: 5f 62 61 63 6b 75 70 5f 69 6e 69 74 20 7c 20 64  _backup_init | d
0820: 6f 63 75 6d 65 6e 74 65 64 20 68 65 72 65 5d 2e  ocumented here].
0830: 0a 20 20 54 68 65 20 72 65 6d 61 69 6e 64 65 72  .  The remainder
0840: 20 6f 66 20 74 68 69 73 20 70 61 67 65 20 63 6f   of this page co
0850: 6e 74 61 69 6e 73 20 74 77 6f 20 43 20 6c 61 6e  ntains two C lan
0860: 67 75 61 67 65 20 65 78 61 6d 70 6c 65 73 20 69  guage examples i
0870: 6c 6c 75 73 74 72 61 74 69 6e 67 20 0a 20 20 63  llustrating .  c
0880: 6f 6d 6d 6f 6e 20 75 73 65 73 20 6f 66 20 74 68  ommon uses of th
0890: 65 20 41 50 49 20 61 6e 64 20 64 69 73 63 75 73  e API and discus
08a0: 73 69 6f 6e 73 20 74 68 65 72 65 6f 66 2e 20 52  sions thereof. R
08b0: 65 61 64 69 6e 67 20 74 68 65 73 65 20 65 78 61  eading these exa
08c0: 6d 70 6c 65 73 0a 20 20 69 73 20 6e 6f 20 73 75  mples.  is no su
08d0: 62 73 74 69 74 75 74 65 20 66 6f 72 20 72 65 61  bstitute for rea
08e0: 64 69 6e 67 20 74 68 65 20 41 50 49 20 64 6f 63  ding the API doc
08f0: 75 6d 65 6e 74 61 74 69 6f 6e 21 0a 0a 3c 68 32  umentation!..<h2
0900: 3e 45 78 61 6d 70 6c 65 20 31 3a 20 4c 6f 61 64  >Example 1: Load
0910: 69 6e 67 20 61 6e 64 20 53 61 76 69 6e 67 20 49  ing and Saving I
0920: 6e 2d 4d 65 6d 6f 72 79 20 44 61 74 61 62 61 73  n-Memory Databas
0930: 65 73 3c 2f 68 32 3e 0a 0a 3c 74 63 6c 3e 0a 0a  es</h2>..<tcl>..
0940: 70 72 6f 63 20 43 5f 43 6f 64 65 20 7b 74 65 78  proc C_Code {tex
0950: 74 7d 20 7b 0a 20 20 68 64 5f 70 75 74 73 20 22  t} {.  hd_puts "
0960: 3c 70 72 65 3e 5c 6e 22 0a 20 20 73 65 74 20 69  <pre>\n".  set i
0970: 4c 69 6e 65 20 30 0a 20 20 66 6f 72 65 61 63 68  Line 0.  foreach
0980: 20 7a 4c 69 6e 65 20 5b 73 70 6c 69 74 20 5b 73   zLine [split [s
0990: 74 72 69 6e 67 20 74 72 69 6d 20 24 74 65 78 74  tring trim $text
09a0: 20 22 5c 6e 22 5d 20 22 5c 6e 22 5d 20 7b 0a 20   "\n"] "\n"] {. 
09b0: 20 20 20 72 65 67 73 75 62 20 7b 5e 20 20 7d 20     regsub {^  } 
09c0: 24 7a 4c 69 6e 65 20 7b 7d 20 7a 4c 69 6e 65 20  $zLine {} zLine 
09d0: 0a 20 20 20 20 73 65 74 20 7a 53 75 62 73 70 65  .    set zSubspe
09e0: 63 20 7b 3c 73 70 61 6e 20 73 74 79 6c 65 3d 22  c {<span style="
09f0: 63 6f 6c 6f 72 3a 62 6c 75 65 3b 66 6f 6e 74 2d  color:blue;font-
0a00: 73 74 79 6c 65 3a 69 74 61 6c 69 63 22 3e 26 3c  style:italic">&<
0a10: 2f 73 70 61 6e 3e 7d 0a 20 20 20 20 72 65 67 73  /span>}.    regs
0a20: 75 62 20 7b 28 2f 5c 2a 7c 5c 2a 5c 2a 7c 5c 2a  ub {(/\*|\*\*|\*
0a30: 2f 29 2e 2a 7d 20 24 7a 4c 69 6e 65 20 24 7a 53  /).*} $zLine $zS
0a40: 75 62 73 70 65 63 20 7a 4c 69 6e 65 20 0a 20 20  ubspec zLine .  
0a50: 20 20 69 66 20 7b 5b 72 65 67 65 78 70 20 7b 28    if {[regexp {(
0a60: 2e 2a 29 28 73 71 6c 69 74 65 33 5b 61 2d 7a 30  .*)(sqlite3[a-z0
0a70: 2d 39 5f 5d 2a 29 28 2e 2a 29 7d 20 24 7a 4c 69  -9_]*)(.*)} $zLi
0a80: 6e 65 20 2d 3e 20 6f 6e 65 20 74 77 6f 20 74 68  ne -> one two th
0a90: 72 65 65 5d 7d 20 7b 0a 20 20 20 20 20 20 68 64  ree]} {.      hd
0aa0: 5f 70 75 74 73 20 24 6f 6e 65 0a 20 20 20 20 20  _puts $one.     
0ab0: 20 68 64 5f 72 65 73 6f 6c 76 65 20 22 5c 5b 24   hd_resolve "\[$
0ac0: 74 77 6f 5c 5d 22 0a 20 20 20 20 20 20 68 64 5f  two\]".      hd_
0ad0: 70 75 74 73 20 24 74 68 72 65 65 0a 20 20 20 20  puts $three.    
0ae0: 7d 20 65 6c 73 65 20 7b 0a 20 20 20 20 20 20 68  } else {.      h
0af0: 64 5f 70 75 74 73 20 24 7a 4c 69 6e 65 0a 20 20  d_puts $zLine.  
0b00: 20 20 7d 0a 20 20 20 20 68 64 5f 70 75 74 73 20    }.    hd_puts 
0b10: 22 5c 6e 22 0a 20 20 7d 0a 20 20 68 64 5f 70 75  "\n".  }.  hd_pu
0b20: 74 73 20 22 3c 2f 70 72 65 3e 5c 6e 22 0a 7d 0a  ts "</pre>\n".}.
0b30: 0a 43 5f 43 6f 64 65 20 7b 0a 20 20 2f 2a 0a 20  .C_Code {.  /*. 
0b40: 20 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f   ** This functio
0b50: 6e 20 69 73 20 75 73 65 64 20 74 6f 20 6c 6f 61  n is used to loa
0b60: 64 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f  d the contents o
0b70: 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
0b80: 65 20 6f 6e 20 64 69 73 6b 20 0a 20 20 2a 2a 20  e on disk .  ** 
0b90: 69 6e 74 6f 20 74 68 65 20 22 6d 61 69 6e 22 20  into the "main" 
0ba0: 64 61 74 61 62 61 73 65 20 6f 66 20 6f 70 65 6e  database of open
0bb0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
0bc0: 74 69 6f 6e 20 70 49 6e 4d 65 6d 6f 72 79 2c 20  tion pInMemory, 
0bd0: 6f 72 0a 20 20 2a 2a 20 74 6f 20 73 61 76 65 20  or.  ** to save 
0be0: 74 68 65 20 63 75 72 72 65 6e 74 20 63 6f 6e 74  the current cont
0bf0: 65 6e 74 73 20 6f 66 20 74 68 65 20 64 61 74 61  ents of the data
0c00: 62 61 73 65 20 6f 70 65 6e 65 64 20 62 79 20 70  base opened by p
0c10: 49 6e 4d 65 6d 6f 72 79 20 69 6e 74 6f 0a 20 20  InMemory into.  
0c20: 2a 2a 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ** a database fi
0c30: 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 70 49 6e 4d  le on disk. pInM
0c40: 65 6d 6f 72 79 20 69 73 20 70 72 6f 62 61 62 6c  emory is probabl
0c50: 79 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  y an in-memory d
0c60: 61 74 61 62 61 73 65 2c 20 0a 20 20 2a 2a 20 62  atabase, .  ** b
0c70: 75 74 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ut this function
0c80: 20 77 69 6c 6c 20 61 6c 73 6f 20 77 6f 72 6b 20   will also work 
0c90: 66 69 6e 65 20 69 66 20 69 74 20 69 73 20 6e 6f  fine if it is no
0ca0: 74 2e 0a 20 20 2a 2a 0a 20 20 2a 2a 20 50 61 72  t..  **.  ** Par
0cb0: 61 6d 65 74 65 72 20 7a 46 69 6c 65 6e 61 6d 65  ameter zFilename
0cc0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
0cd0: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
0ce0: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
0cf0: 65 0a 20 20 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  e.  ** name of t
0d00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
0d10: 20 6f 6e 20 64 69 73 6b 20 74 6f 20 6c 6f 61 64   on disk to load
0d20: 20 66 72 6f 6d 20 6f 72 20 73 61 76 65 20 74 6f   from or save to
0d30: 2e 20 49 66 20 70 61 72 61 6d 65 74 65 72 0a 20  . If parameter. 
0d40: 20 2a 2a 20 69 73 53 61 76 65 20 69 73 20 6e 6f   ** isSave is no
0d50: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
0d60: 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65   contents of the
0d70: 20 66 69 6c 65 20 7a 46 69 6c 65 6e 61 6d 65 20   file zFilename 
0d80: 61 72 65 20 0a 20 20 2a 2a 20 6f 76 65 72 77 72  are .  ** overwr
0d90: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
0da0: 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 64  ontents of the d
0db0: 61 74 61 62 61 73 65 20 6f 70 65 6e 65 64 20 62  atabase opened b
0dc0: 79 20 70 49 6e 4d 65 6d 6f 72 79 2e 20 49 66 0a  y pInMemory. If.
0dd0: 20 20 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69    ** parameter i
0de0: 73 53 61 76 65 20 69 73 20 7a 65 72 6f 2c 20 74  sSave is zero, t
0df0: 68 65 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  hen the contents
0e00: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
0e10: 20 6f 70 65 6e 65 64 20 62 79 0a 20 20 2a 2a 20   opened by.  ** 
0e20: 70 49 6e 4d 65 6d 6f 72 79 20 61 72 65 20 72 65  pInMemory are re
0e30: 70 6c 61 63 65 64 20 62 79 20 64 61 74 61 20 6c  placed by data l
0e40: 6f 61 64 65 64 20 66 72 6f 6d 20 74 68 65 20 66  oaded from the f
0e50: 69 6c 65 20 7a 46 69 6c 65 6e 61 6d 65 2e 0a 20  ile zFilename.. 
0e60: 20 2a 2a 0a 20 20 2a 2a 20 49 66 20 74 68 65 20   **.  ** If the 
0e70: 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 73 75 63  operation is suc
0e80: 63 65 73 73 66 75 6c 2c 20 53 51 4c 49 54 45 5f  cessful, SQLITE_
0e90: 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OK is returned. 
0ea0: 4f 74 68 65 72 77 69 73 65 2c 20 69 66 0a 20 20  Otherwise, if.  
0eb0: 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ** an error occu
0ec0: 72 73 2c 20 61 6e 20 53 51 4c 69 74 65 20 65 72  rs, an SQLite er
0ed0: 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
0ee0: 72 6e 65 64 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  rned..  */.  int
0ef0: 20 6c 6f 61 64 4f 72 53 61 76 65 44 62 28 73 71   loadOrSaveDb(sq
0f00: 6c 69 74 65 33 20 2a 70 49 6e 4d 65 6d 6f 72 79  lite3 *pInMemory
0f10: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
0f20: 69 6c 65 6e 61 6d 65 2c 20 69 6e 74 20 69 73 53  ilename, int isS
0f30: 61 76 65 29 7b 0a 20 20 20 20 69 6e 74 20 72 63  ave){.    int rc
0f40: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
0f50: 20 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20      /* Function 
0f60: 72 65 74 75 72 6e 20 63 6f 64 65 20 2a 2f 0a 20  return code */. 
0f70: 20 20 20 73 71 6c 69 74 65 33 20 2a 70 46 69 6c     sqlite3 *pFil
0f80: 65 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  e;           /* 
0f90: 44 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  Database connect
0fa0: 69 6f 6e 20 6f 70 65 6e 65 64 20 6f 6e 20 7a 46  ion opened on zF
0fb0: 69 6c 65 6e 61 6d 65 20 2a 2f 0a 20 20 20 20 73  ilename */.    s
0fc0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 70  qlite3_backup *p
0fd0: 42 61 63 6b 75 70 3b 20 20 2f 2a 20 42 61 63 6b  Backup;  /* Back
0fe0: 75 70 20 6f 62 6a 65 63 74 20 75 73 65 64 20 74  up object used t
0ff0: 6f 20 63 6f 70 79 20 64 61 74 61 20 2a 2f 0a 20  o copy data */. 
1000: 20 20 20 73 71 6c 69 74 65 33 20 2a 70 54 6f 3b     sqlite3 *pTo;
1010: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1020: 44 61 74 61 62 61 73 65 20 74 6f 20 63 6f 70 79  Database to copy
1030: 20 74 6f 20 28 70 46 69 6c 65 20 6f 72 20 70 49   to (pFile or pI
1040: 6e 4d 65 6d 6f 72 79 29 20 2a 2f 0a 20 20 20 20  nMemory) */.    
1050: 73 71 6c 69 74 65 33 20 2a 70 46 72 6f 6d 3b 20  sqlite3 *pFrom; 
1060: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1070: 61 62 61 73 65 20 74 6f 20 63 6f 70 79 20 66 72  abase to copy fr
1080: 6f 6d 20 28 70 46 69 6c 65 20 6f 72 20 70 49 6e  om (pFile or pIn
1090: 4d 65 6d 6f 72 79 29 20 2a 2f 0a 0a 20 20 20 20  Memory) */..    
10a0: 2f 2a 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61  /* Open the data
10b0: 62 61 73 65 20 66 69 6c 65 20 69 64 65 6e 74 69  base file identi
10c0: 66 69 65 64 20 62 79 20 7a 46 69 6c 65 6e 61 6d  fied by zFilenam
10d0: 65 2e 20 45 78 69 74 20 65 61 72 6c 79 20 69 66  e. Exit early if
10e0: 20 74 68 69 73 20 66 61 69 6c 73 0a 20 20 20 20   this fails.    
10f0: 2a 2a 20 66 6f 72 20 61 6e 79 20 72 65 61 73 6f  ** for any reaso
1100: 6e 2e 20 2a 2f 0a 20 20 20 20 72 63 20 3d 20 73  n. */.    rc = s
1110: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 7a 46 69 6c  qlite3_open(zFil
1120: 65 6e 61 6d 65 2c 20 26 70 46 69 6c 65 29 3b 0a  ename, &pFile);.
1130: 20 20 20 20 69 66 28 20 72 63 3d 3d 53 51 4c 49      if( rc==SQLI
1140: 54 45 5f 4f 4b 20 29 7b 0a 20 20 0a 20 20 20 20  TE_OK ){.  .    
1150: 20 20 2f 2a 20 49 66 20 74 68 69 73 20 69 73 20    /* If this is 
1160: 61 20 27 6c 6f 61 64 27 20 6f 70 65 72 61 74 69  a 'load' operati
1170: 6f 6e 20 28 69 73 53 61 76 65 3d 3d 30 29 2c 20  on (isSave==0), 
1180: 74 68 65 6e 20 64 61 74 61 20 69 73 20 63 6f 70  then data is cop
1190: 69 65 64 0a 20 20 20 20 20 20 2a 2a 20 66 72 6f  ied.      ** fro
11a0: 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  m the database f
11b0: 69 6c 65 20 6a 75 73 74 20 6f 70 65 6e 65 64 20  ile just opened 
11c0: 74 6f 20 64 61 74 61 62 61 73 65 20 70 49 6e 4d  to database pInM
11d0: 65 6d 6f 72 79 2e 20 0a 20 20 20 20 20 20 2a 2a  emory. .      **
11e0: 20 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20 74   Otherwise, if t
11f0: 68 69 73 20 69 73 20 61 20 27 73 61 76 65 27 20  his is a 'save' 
1200: 6f 70 65 72 61 74 69 6f 6e 20 28 69 73 53 61 76  operation (isSav
1210: 65 3d 3d 31 29 2c 20 74 68 65 6e 20 64 61 74 61  e==1), then data
1220: 0a 20 20 20 20 20 20 2a 2a 20 69 73 20 63 6f 70  .      ** is cop
1230: 69 65 64 20 66 72 6f 6d 20 70 49 6e 4d 65 6d 6f  ied from pInMemo
1240: 72 79 20 74 6f 20 70 46 69 6c 65 2e 20 20 53 65  ry to pFile.  Se
1250: 74 20 74 68 65 20 76 61 72 69 61 62 6c 65 73 20  t the variables 
1260: 70 46 72 6f 6d 20 61 6e 64 0a 20 20 20 20 20 20  pFrom and.      
1270: 2a 2a 20 70 54 6f 20 61 63 63 6f 72 64 69 6e 67  ** pTo according
1280: 6c 79 2e 20 2a 2f 0a 20 20 20 20 20 20 70 46 72  ly. */.      pFr
1290: 6f 6d 20 3d 20 28 69 73 53 61 76 65 20 3f 20 70  om = (isSave ? p
12a0: 49 6e 4d 65 6d 6f 72 79 20 3a 20 70 46 69 6c 65  InMemory : pFile
12b0: 29 3b 0a 20 20 20 20 20 20 70 54 6f 20 20 20 3d  );.      pTo   =
12c0: 20 28 69 73 53 61 76 65 20 3f 20 70 46 69 6c 65   (isSave ? pFile
12d0: 20 20 20 20 20 3a 20 70 49 6e 4d 65 6d 6f 72 79       : pInMemory
12e0: 29 3b 0a 20 20 0a 20 20 20 20 20 20 2f 2a 20 53  );.  .      /* S
12f0: 65 74 20 75 70 20 74 68 65 20 62 61 63 6b 75 70  et up the backup
1300: 20 70 72 6f 63 65 64 75 72 65 20 74 6f 20 63 6f   procedure to co
1310: 70 79 20 66 72 6f 6d 20 74 68 65 20 22 6d 61 69  py from the "mai
1320: 6e 22 20 64 61 74 61 62 61 73 65 20 6f 66 20 0a  n" database of .
1330: 20 20 20 20 20 20 2a 2a 20 63 6f 6e 6e 65 63 74        ** connect
1340: 69 6f 6e 20 70 46 69 6c 65 20 74 6f 20 74 68 65  ion pFile to the
1350: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 6f   main database o
1360: 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 49 6e  f connection pIn
1370: 4d 65 6d 6f 72 79 2e 0a 20 20 20 20 20 20 2a 2a  Memory..      **
1380: 20 49 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f   If something go
1390: 65 73 20 77 72 6f 6e 67 2c 20 70 42 61 63 6b 75  es wrong, pBacku
13a0: 70 20 77 69 6c 6c 20 62 65 20 73 65 74 20 74 6f  p will be set to
13b0: 20 4e 55 4c 4c 20 61 6e 64 20 61 6e 20 65 72 72   NULL and an err
13c0: 6f 72 0a 20 20 20 20 20 20 2a 2a 20 63 6f 64 65  or.      ** code
13d0: 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6c 65 66   and message lef
13e0: 74 20 69 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t in connection 
13f0: 70 54 6f 2e 0a 20 20 20 20 20 20 2a 2a 0a 20 20  pTo..      **.  
1400: 20 20 20 20 2a 2a 20 49 66 20 74 68 65 20 62 61      ** If the ba
1410: 63 6b 75 70 20 6f 62 6a 65 63 74 20 69 73 20 73  ckup object is s
1420: 75 63 63 65 73 73 66 75 6c 6c 79 20 63 72 65 61  uccessfully crea
1430: 74 65 64 2c 20 63 61 6c 6c 20 62 61 63 6b 75 70  ted, call backup
1440: 5f 73 74 65 70 28 29 0a 20 20 20 20 20 20 2a 2a  _step().      **
1450: 20 74 6f 20 63 6f 70 79 20 64 61 74 61 20 66 72   to copy data fr
1460: 6f 6d 20 70 46 69 6c 65 20 74 6f 20 70 49 6e 4d  om pFile to pInM
1470: 65 6d 6f 72 79 2e 20 54 68 65 6e 20 63 61 6c 6c  emory. Then call
1480: 20 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29   backup_finish()
1490: 0a 20 20 20 20 20 20 2a 2a 20 74 6f 20 72 65 6c  .      ** to rel
14a0: 65 61 73 65 20 72 65 73 6f 75 72 63 65 73 20 61  ease resources a
14b0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
14c0: 68 65 20 70 42 61 63 6b 75 70 20 6f 62 6a 65 63  he pBackup objec
14d0: 74 2e 20 20 49 66 20 61 6e 0a 20 20 20 20 20 20  t.  If an.      
14e0: 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65  ** error occurre
14f0: 64 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72  d, then an error
1500: 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
1510: 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
1520: 6e 0a 20 20 20 20 20 20 2a 2a 20 63 6f 6e 6e 65  n.      ** conne
1530: 63 74 69 6f 6e 20 70 54 6f 2e 20 49 66 20 6e 6f  ction pTo. If no
1540: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 2c   error occurred,
1550: 20 74 68 65 6e 20 74 68 65 20 65 72 72 6f 72 20   then the error 
1560: 63 6f 64 65 20 62 65 6c 6f 6e 67 69 6e 67 0a 20  code belonging. 
1570: 20 20 20 20 20 2a 2a 20 74 6f 20 70 54 6f 20 69       ** to pTo i
1580: 73 20 73 65 74 20 74 6f 20 53 51 4c 49 54 45 5f  s set to SQLITE_
1590: 4f 4b 2e 0a 20 20 20 20 20 20 2a 2f 0a 20 20 20  OK..      */.   
15a0: 20 20 20 70 42 61 63 6b 75 70 20 3d 20 73 71 6c     pBackup = sql
15b0: 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74  ite3_backup_init
15c0: 28 70 54 6f 2c 20 22 6d 61 69 6e 22 2c 20 70 46  (pTo, "main", pF
15d0: 72 6f 6d 2c 20 22 6d 61 69 6e 22 29 3b 0a 20 20  rom, "main");.  
15e0: 20 20 20 20 69 66 28 20 70 42 61 63 6b 75 70 20      if( pBackup 
15f0: 29 7b 0a 20 20 20 20 20 20 20 20 28 76 6f 69 64  ){.        (void
1600: 29 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  )sqlite3_backup_
1610: 73 74 65 70 28 70 42 61 63 6b 75 70 2c 20 2d 31  step(pBackup, -1
1620: 29 3b 0a 20 20 20 20 20 20 20 20 28 76 6f 69 64  );.        (void
1630: 29 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  )sqlite3_backup_
1640: 66 69 6e 69 73 68 28 70 42 61 63 6b 75 70 29 3b  finish(pBackup);
1650: 0a 20 20 20 20 20 20 7d 0a 20 20 20 20 20 20 72  .      }.      r
1660: 63 20 3d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  c = sqlite3_errc
1670: 6f 64 65 28 70 54 6f 29 3b 0a 20 20 20 20 7d 0a  ode(pTo);.    }.
1680: 0a 20 20 20 20 2f 2a 20 43 6c 6f 73 65 20 74 68  .    /* Close th
1690: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
16a0: 63 74 69 6f 6e 20 6f 70 65 6e 65 64 20 6f 6e 20  ction opened on 
16b0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 7a 46  database file zF
16c0: 69 6c 65 6e 61 6d 65 0a 20 20 20 20 2a 2a 20 61  ilename.    ** a
16d0: 6e 64 20 72 65 74 75 72 6e 20 74 68 65 20 72 65  nd return the re
16e0: 73 75 6c 74 20 6f 66 20 74 68 69 73 20 66 75 6e  sult of this fun
16f0: 63 74 69 6f 6e 2e 20 2a 2f 0a 20 20 20 20 28 76  ction. */.    (v
1700: 6f 69 64 29 73 71 6c 69 74 65 33 5f 63 6c 6f 73  oid)sqlite3_clos
1710: 65 28 70 46 69 6c 65 29 3b 0a 20 20 20 20 72 65  e(pFile);.    re
1720: 74 75 72 6e 20 72 63 3b 0a 20 20 7d 0a 7d 0a 3c  turn rc;.  }.}.<
1730: 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65  /tcl>..<p>.  The
1740: 20 43 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74   C function to t
1750: 68 65 20 72 69 67 68 74 20 64 65 6d 6f 6e 73 74  he right demonst
1760: 72 61 74 65 73 20 6f 6e 65 20 6f 66 20 74 68 65  rates one of the
1770: 20 73 69 6d 70 6c 65 73 74 2c 0a 20 20 61 6e 64   simplest,.  and
1780: 20 6d 6f 73 74 20 63 6f 6d 6d 6f 6e 2c 20 75 73   most common, us
1790: 65 73 20 6f 66 20 74 68 65 20 62 61 63 6b 75 70  es of the backup
17a0: 20 41 50 49 3a 20 6c 6f 61 64 69 6e 67 20 61 6e   API: loading an
17b0: 64 20 73 61 76 69 6e 67 20 74 68 65 20 63 6f 6e  d saving the con
17c0: 74 65 6e 74 73 0a 20 20 6f 66 20 61 6e 20 69 6e  tents.  of an in
17d0: 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
17e0: 20 74 6f 20 61 20 66 69 6c 65 20 6f 6e 20 64 69   to a file on di
17f0: 73 6b 2e 20 54 68 65 20 62 61 63 6b 75 70 20 41  sk. The backup A
1800: 50 49 20 69 73 20 75 73 65 64 20 61 73 0a 20 20  PI is used as.  
1810: 66 6f 6c 6c 6f 77 73 20 69 6e 20 74 68 69 73 20  follows in this 
1820: 65 78 61 6d 70 6c 65 3a 0a 0a 20 20 3c 6f 6c 3e  example:..  <ol>
1830: 0a 20 20 20 20 3c 6c 69 3e 46 75 6e 63 74 69 6f  .    <li>Functio
1840: 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  n [sqlite3_backu
1850: 70 5f 69 6e 69 74 28 29 5d 20 69 73 20 63 61 6c  p_init()] is cal
1860: 6c 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 6e  led to create an
1870: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
1880: 5d 0a 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74  ].        object
1890: 20 74 6f 20 63 6f 70 79 20 64 61 74 61 20 62 65   to copy data be
18a0: 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 64 61  tween the two da
18b0: 74 61 62 61 73 65 73 20 28 65 69 74 68 65 72 20  tabases (either 
18c0: 66 72 6f 6d 20 61 20 66 69 6c 65 20 61 6e 64 0a  from a file and.
18d0: 20 20 20 20 20 20 20 20 69 6e 74 6f 20 74 68 65          into the
18e0: 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
18f0: 61 73 65 2c 20 6f 72 20 76 69 63 65 2d 76 65 72  ase, or vice-ver
1900: 73 61 29 2e 0a 20 20 20 20 3c 6c 69 3e 46 75 6e  sa)..    <li>Fun
1910: 63 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 62  ction [sqlite3_b
1920: 61 63 6b 75 70 5f 73 74 65 70 28 29 5d 20 69 73  ackup_step()] is
1930: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 70   called with a p
1940: 61 72 61 6d 65 74 65 72 20 6f 66 20 0a 20 20 20  arameter of .   
1950: 20 20 20 20 20 3c 74 74 3e 2d 31 3c 2f 74 74 3e       <tt>-1</tt>
1960: 20 74 6f 20 63 6f 70 79 20 74 68 65 20 65 6e 74   to copy the ent
1970: 69 72 65 20 73 6f 75 72 63 65 20 64 61 74 61 62  ire source datab
1980: 61 73 65 20 74 6f 20 74 68 65 20 64 65 73 74 69  ase to the desti
1990: 6e 61 74 69 6f 6e 2e 0a 20 20 20 20 3c 6c 69 3e  nation..    <li>
19a0: 46 75 6e 63 74 69 6f 6e 20 5b 73 71 6c 69 74 65  Function [sqlite
19b0: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28  3_backup_finish(
19c0: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  )] is called to 
19d0: 63 6c 65 61 6e 20 75 70 20 72 65 73 6f 75 72 63  clean up resourc
19e0: 65 73 0a 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  es.        alloc
19f0: 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
1a00: 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 5d 2e  _backup_init()].
1a10: 0a 20 20 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 3c 62 3e  .  </ol>..<p><b>
1a20: 45 72 72 6f 72 20 68 61 6e 64 6c 69 6e 67 3c 2f  Error handling</
1a30: 62 3e 0a 0a 3c 70 3e 0a 20 20 49 66 20 61 6e 20  b>..<p>.  If an 
1a40: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 69 6e 20  error occurs in 
1a50: 61 6e 79 20 6f 66 20 74 68 65 20 74 68 72 65 65  any of the three
1a60: 20 6d 61 69 6e 20 62 61 63 6b 75 70 20 41 50 49   main backup API
1a70: 20 72 6f 75 74 69 6e 65 73 0a 20 20 74 68 65 6e   routines.  then
1a80: 20 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64 65   the [error code
1a90: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
1aa0: 72 72 6d 73 67 20 7c 20 6d 65 73 73 61 67 65 5d  rrmsg | message]
1ab0: 20 61 72 65 20 61 74 74 61 63 68 65 64 20 74 6f   are attached to
1ac0: 0a 20 20 74 68 65 20 64 65 73 74 69 6e 61 74 69  .  the destinati
1ad0: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
1ae0: 6e 65 63 74 69 6f 6e 5d 2e 0a 20 20 41 64 64 69  nection]..  Addi
1af0: 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 0a 20 20 5b  tionally, if.  [
1b00: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73  sqlite3_backup_s
1b10: 74 65 70 28 29 5d 20 65 6e 63 6f 75 6e 74 65 72  tep()] encounter
1b20: 73 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  s an error, then
1b30: 20 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64 65   the [error code
1b40: 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 20 20  ] is returned.  
1b50: 62 79 20 62 6f 74 68 20 74 68 65 20 5b 73 71 6c  by both the [sql
1b60: 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70  ite3_backup_step
1b70: 28 29 5d 20 63 61 6c 6c 20 69 74 73 65 6c 66 2c  ()] call itself,
1b80: 20 61 6e 64 20 62 79 20 74 68 65 20 73 75 62 73   and by the subs
1b90: 65 71 75 65 6e 74 20 63 61 6c 6c 0a 20 20 74 6f  equent call.  to
1ba0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
1bb0: 5f 66 69 6e 69 73 68 28 29 5d 2e 20 53 6f 20 61  _finish()]. So a
1bc0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1bd0: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28  3_backup_finish(
1be0: 29 5d 0a 20 20 64 6f 65 73 20 6e 6f 74 20 6f 76  )].  does not ov
1bf0: 65 72 77 72 69 74 65 20 61 6e 20 5b 65 72 72 6f  erwrite an [erro
1c00: 72 20 63 6f 64 65 5d 20 73 74 6f 72 65 64 20 69  r code] stored i
1c10: 6e 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f  n the destinatio
1c20: 6e 0a 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n.  [database co
1c30: 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 5b 73 71  nnection] by [sq
1c40: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65  lite3_backup_ste
1c50: 70 28 29 5d 2e 20 20 54 68 69 73 20 66 65 61 74  p()].  This feat
1c60: 75 72 65 0a 20 20 69 73 20 75 73 65 64 20 69 6e  ure.  is used in
1c70: 20 74 68 65 20 65 78 61 6d 70 6c 65 20 63 6f 64   the example cod
1c80: 65 20 74 6f 20 72 65 64 75 63 65 20 61 6d 6f 75  e to reduce amou
1c90: 6e 74 20 6f 66 20 65 72 72 6f 72 20 68 61 6e 64  nt of error hand
1ca0: 6c 69 6e 67 20 72 65 71 75 69 72 65 64 2e 0a 20  ling required.. 
1cb0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
1cc0: 65 73 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  es of the [sqlit
1cd0: 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29  e3_backup_step()
1ce0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
1cf0: 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 5d 0a  ackup_finish()].
1d00: 20 20 63 61 6c 6c 73 20 61 72 65 20 69 67 6e 6f    calls are igno
1d10: 72 65 64 20 61 6e 64 20 74 68 65 20 65 72 72 6f  red and the erro
1d20: 72 20 63 6f 64 65 20 69 6e 64 69 63 61 74 69 6e  r code indicatin
1d30: 67 20 74 68 65 20 73 75 63 63 65 73 73 20 6f 72  g the success or
1d40: 20 66 61 69 6c 75 72 65 20 6f 66 0a 20 20 74 68   failure of.  th
1d50: 65 20 63 6f 70 79 20 6f 70 65 72 61 74 69 6f 6e  e copy operation
1d60: 20 63 6f 6c 6c 65 63 74 65 64 20 66 72 6f 6d 20   collected from 
1d70: 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20  the destination 
1d80: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1d90: 74 69 6f 6e 5d 0a 20 20 61 66 74 65 72 77 61 72  tion].  afterwar
1da0: 64 2e 0a 0a 3c 70 3e 3c 62 3e 50 6f 73 73 69 62  d...<p><b>Possib
1db0: 6c 65 20 45 6e 68 61 6e 63 65 6d 65 6e 74 73 3c  le Enhancements<
1dc0: 2f 62 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 69  /b>..<p>.  The i
1dd0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1de0: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63   this function c
1df0: 6f 75 6c 64 20 62 65 20 65 6e 68 61 6e 63 65 64  ould be enhanced
1e00: 20 69 6e 20 61 74 20 6c 65 61 73 74 20 74 77 6f   in at least two
1e10: 20 77 61 79 73 3a 0a 0a 20 20 3c 6f 6c 3e 0a 20   ways:..  <ol>. 
1e20: 20 20 20 3c 6c 69 3e 20 46 61 69 6c 69 6e 67 20     <li> Failing 
1e30: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6c 6f  to obtain the lo
1e40: 63 6b 20 6f 6e 20 64 61 74 61 62 61 73 65 20 66  ck on database f
1e50: 69 6c 65 20 7a 46 69 6c 65 6e 61 6d 65 20 28 61  ile zFilename (a
1e60: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1e70: 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 29 20           error) 
1e80: 63 6f 75 6c 64 20 62 65 20 68 61 6e 64 6c 65 64  could be handled
1e90: 2c 20 61 6e 64 0a 20 20 20 20 3c 6c 69 3e 20 43  , and.    <li> C
1ea0: 61 73 65 73 20 77 68 65 72 65 20 74 68 65 20 70  ases where the p
1eb0: 61 67 65 2d 73 69 7a 65 73 20 6f 66 20 64 61 74  age-sizes of dat
1ec0: 61 62 61 73 65 20 70 49 6e 4d 65 6d 6f 72 79 20  abase pInMemory 
1ed0: 61 6e 64 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72  and zFilename ar
1ee0: 65 0a 20 20 20 20 20 20 20 20 20 64 69 66 66 65  e.         diffe
1ef0: 72 65 6e 74 20 63 6f 75 6c 64 20 62 65 20 68 61  rent could be ha
1f00: 6e 64 6c 65 64 20 62 65 74 74 65 72 2e 0a 20 20  ndled better..  
1f10: 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 0a 20 20 53 69 6e  </ol>..<p>.  Sin
1f20: 63 65 20 64 61 74 61 62 61 73 65 20 7a 46 69 6c  ce database zFil
1f30: 65 6e 61 6d 65 20 69 73 20 61 20 66 69 6c 65 20  ename is a file 
1f40: 6f 6e 20 64 69 73 6b 2c 20 74 68 65 6e 20 69 74  on disk, then it
1f50: 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
1f60: 20 0a 20 20 65 78 74 65 72 6e 61 6c 6c 79 20 62   .  externally b
1f70: 79 20 61 6e 6f 74 68 65 72 20 70 72 6f 63 65 73  y another proces
1f80: 73 2e 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  s. This means th
1f90: 61 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  at when the call
1fa0: 20 74 6f 0a 20 20 73 71 6c 69 74 65 33 5f 62 61   to.  sqlite3_ba
1fb0: 63 6b 75 70 5f 73 74 65 70 28 29 20 61 74 74 65  ckup_step() atte
1fc0: 6d 70 74 73 20 74 6f 20 72 65 61 64 20 66 72 6f  mpts to read fro
1fd0: 6d 20 6f 72 20 77 72 69 74 65 20 64 61 74 61 20  m or write data 
1fe0: 74 6f 20 69 74 2c 20 69 74 20 6d 61 79 0a 20 20  to it, it may.  
1ff0: 66 61 69 6c 20 74 6f 20 6f 62 74 61 69 6e 20 74  fail to obtain t
2000: 68 65 20 72 65 71 75 69 72 65 64 20 66 69 6c 65  he required file
2010: 20 6c 6f 63 6b 2e 20 49 66 20 74 68 69 73 20 68   lock. If this h
2020: 61 70 70 65 6e 73 2c 20 74 68 69 73 20 69 6d 70  appens, this imp
2030: 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 20 20 77 69  lementation.  wi
2040: 6c 6c 20 66 61 69 6c 2c 20 72 65 74 75 72 6e 69  ll fail, returni
2050: 6e 67 20 53 51 4c 49 54 45 5f 42 55 53 59 20 69  ng SQLITE_BUSY i
2060: 6d 6d 65 64 69 61 74 65 6c 79 2e 20 54 68 65 20  mmediately. The 
2070: 73 6f 6c 75 74 69 6f 6e 20 77 6f 75 6c 64 20 62  solution would b
2080: 65 20 74 6f 0a 20 20 72 65 67 69 73 74 65 72 20  e to.  register 
2090: 61 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63  a busy-handler c
20a0: 61 6c 6c 62 61 63 6b 20 6f 72 20 0a 20 20 74 69  allback or .  ti
20b0: 6d 65 6f 75 74 20 77 69 74 68 20 5b 64 61 74 61  meout with [data
20c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
20d0: 20 70 46 69 6c 65 20 0a 20 20 75 73 69 6e 67 20   pFile .  using 
20e0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
20f0: 6e 64 6c 65 72 28 29 5d 20 6f 72 20 5b 73 71 6c  ndler()] or [sql
2100: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2110: 74 28 29 5d 0a 20 20 61 73 20 73 6f 6f 6e 20 61  t()].  as soon a
2120: 73 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2e 20  s it is opened. 
2130: 49 66 20 69 74 20 66 61 69 6c 73 20 74 6f 20 6f  If it fails to o
2140: 62 74 61 69 6e 20 61 20 72 65 71 75 69 72 65 64  btain a required
2150: 20 6c 6f 63 6b 20 69 6d 6d 65 64 69 61 74 65 6c   lock immediatel
2160: 79 2c 0a 20 20 5b 73 71 6c 69 74 65 33 5f 62 61  y,.  [sqlite3_ba
2170: 63 6b 75 70 5f 73 74 65 70 28 29 5d 20 75 73 65  ckup_step()] use
2180: 73 20 61 6e 79 20 72 65 67 69 73 74 65 72 65 64  s any registered
2190: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
21a0: 6c 6c 62 61 63 6b 20 6f 72 20 74 69 6d 65 6f 75  llback or timeou
21b0: 74 0a 20 20 69 6e 20 74 68 65 20 73 61 6d 65 20  t.  in the same 
21c0: 77 61 79 20 61 73 20 5b 73 71 6c 69 74 65 33 5f  way as [sqlite3_
21d0: 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
21e0: 74 65 33 5f 65 78 65 63 28 29 5d 20 64 6f 65 73  te3_exec()] does
21f0: 2e 0a 0a 3c 70 3e 0a 20 20 55 73 75 61 6c 6c 79  ...<p>.  Usually
2200: 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6d 61  , it does not ma
2210: 74 74 65 72 20 69 66 20 74 68 65 20 70 61 67 65  tter if the page
2220: 2d 73 69 7a 65 73 20 6f 66 20 74 68 65 20 73 6f  -sizes of the so
2230: 75 72 63 65 20 64 61 74 61 62 61 73 65 20 61 6e  urce database an
2240: 64 20 74 68 65 0a 20 20 64 65 73 74 69 6e 61 74  d the.  destinat
2250: 69 6f 6e 20 64 61 74 61 62 61 73 65 20 61 72 65  ion database are
2260: 20 64 69 66 66 65 72 65 6e 74 20 62 65 66 6f 72   different befor
2270: 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f  e the contents o
2280: 66 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f  f the destinatio
2290: 6e 0a 20 20 61 72 65 20 6f 76 65 72 77 72 69 74  n.  are overwrit
22a0: 74 65 6e 2e 20 54 68 65 20 70 61 67 65 2d 73 69  ten. The page-si
22b0: 7a 65 20 6f 66 20 74 68 65 20 64 65 73 74 69 6e  ze of the destin
22c0: 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 69  ation database i
22d0: 73 20 73 69 6d 70 6c 79 20 63 68 61 6e 67 65 64  s simply changed
22e0: 0a 20 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  .  as part of th
22f0: 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69  e backup operati
2300: 6f 6e 2e 20 54 68 65 20 65 78 63 65 70 74 69 6f  on. The exceptio
2310: 6e 20 69 73 20 69 66 20 74 68 65 20 64 65 73 74  n is if the dest
2320: 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65  ination database
2330: 0a 20 20 68 61 70 70 65 6e 73 20 74 6f 20 62 65  .  happens to be
2340: 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61   an in-memory da
2350: 74 61 62 61 73 65 2e 20 49 6e 20 74 68 69 73 20  tabase. In this 
2360: 63 61 73 65 2c 20 69 66 20 74 68 65 20 70 61 67  case, if the pag
2370: 65 20 73 69 7a 65 73 0a 20 20 61 72 65 20 6e 6f  e sizes.  are no
2380: 74 20 74 68 65 20 73 61 6d 65 20 61 74 20 74 68  t the same at th
2390: 65 20 73 74 61 72 74 20 6f 66 20 74 68 65 20 62  e start of the b
23a0: 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2c  ackup operation,
23b0: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
23c0: 69 6f 6e 0a 20 20 66 61 69 6c 73 20 77 69 74 68  ion.  fails with
23d0: 20 61 6e 20 53 51 4c 49 54 45 5f 52 45 41 44 4f   an SQLITE_READO
23e0: 4e 4c 59 20 65 72 72 6f 72 2e 20 55 6e 66 6f 72  NLY error. Unfor
23f0: 74 75 6e 61 74 65 6c 79 2c 20 74 68 69 73 20 63  tunately, this c
2400: 6f 75 6c 64 20 6f 63 63 75 72 20 77 68 65 6e 0a  ould occur when.
2410: 20 20 6c 6f 61 64 69 6e 67 20 61 20 64 61 74 61    loading a data
2420: 62 61 73 65 20 69 6d 61 67 65 20 66 72 6f 6d 20  base image from 
2430: 61 20 66 69 6c 65 20 69 6e 74 6f 20 61 6e 20 69  a file into an i
2440: 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
2450: 65 20 75 73 69 6e 67 0a 20 20 66 75 6e 63 74 69  e using.  functi
2460: 6f 6e 20 6c 6f 61 64 4f 72 53 61 76 65 44 62 28  on loadOrSaveDb(
2470: 29 2e 0a 0a 3c 70 3e 0a 20 20 48 6f 77 65 76 65  )...<p>.  Howeve
2480: 72 2c 20 69 66 20 69 6e 2d 6d 65 6d 6f 72 79 20  r, if in-memory 
2490: 64 61 74 61 62 61 73 65 20 70 49 6e 4d 65 6d 6f  database pInMemo
24a0: 72 79 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  ry has just been
24b0: 20 6f 70 65 6e 65 64 20 28 61 6e 64 20 69 73 20   opened (and is 
24c0: 0a 20 20 74 68 65 72 65 66 6f 72 65 20 63 6f 6d  .  therefore com
24d0: 70 6c 65 74 65 6c 79 20 65 6d 70 74 79 29 20 62  pletely empty) b
24e0: 65 66 6f 72 65 20 62 65 69 6e 67 20 70 61 73 73  efore being pass
24f0: 65 64 20 74 6f 20 66 75 6e 63 74 69 6f 6e 20 6c  ed to function l
2500: 6f 61 64 4f 72 53 61 76 65 44 62 28 29 2c 20 0a  oadOrSaveDb(), .
2510: 20 20 74 68 65 6e 20 69 74 20 69 73 20 73 74 69    then it is sti
2520: 6c 6c 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ll possible to c
2530: 68 61 6e 67 65 20 69 74 73 20 70 61 67 65 20 73  hange its page s
2540: 69 7a 65 20 75 73 69 6e 67 20 61 6e 20 53 51 4c  ize using an SQL
2550: 69 74 65 20 22 50 52 41 47 4d 41 0a 20 20 70 61  ite "PRAGMA.  pa
2560: 67 65 5f 73 69 7a 65 22 20 63 6f 6d 6d 61 6e 64  ge_size" command
2570: 2e 20 46 75 6e 63 74 69 6f 6e 20 6c 6f 61 64 4f  . Function loadO
2580: 72 53 61 76 65 44 62 28 29 20 63 6f 75 6c 64 20  rSaveDb() could 
2590: 64 65 74 65 63 74 20 74 68 69 73 20 63 61 73 65  detect this case
25a0: 2c 20 61 6e 64 0a 20 20 61 74 74 65 6d 70 74 20  , and.  attempt 
25b0: 74 6f 20 73 65 74 20 74 68 65 20 70 61 67 65 2d  to set the page-
25c0: 73 69 7a 65 20 6f 66 20 74 68 65 20 69 6e 2d 6d  size of the in-m
25d0: 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 74  emory database t
25e0: 6f 20 74 68 65 20 70 61 67 65 2d 73 69 7a 65 0a  o the page-size.
25f0: 20 20 6f 66 20 64 61 74 61 62 61 73 65 20 7a 46    of database zF
2600: 69 6c 65 6e 61 6d 65 20 62 65 66 6f 72 65 20 69  ilename before i
2610: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 6f 6e 6c 69  nvoking the onli
2620: 6e 65 20 62 61 63 6b 75 70 20 41 50 49 20 66 75  ne backup API fu
2630: 6e 63 74 69 6f 6e 73 2e 0a 20 20 0a 3c 68 32 3e  nctions..  .<h2>
2640: 45 78 61 6d 70 6c 65 20 32 3a 20 4f 6e 6c 69 6e  Example 2: Onlin
2650: 65 20 42 61 63 6b 75 70 20 6f 66 20 61 20 52 75  e Backup of a Ru
2660: 6e 6e 69 6e 67 20 44 61 74 61 62 61 73 65 3c 2f  nning Database</
2670: 68 32 3e 0a 0a 3c 74 63 6c 3e 0a 43 5f 43 6f 64  h2>..<tcl>.C_Cod
2680: 65 20 7b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 50 65  e {.  /*.  ** Pe
2690: 72 66 6f 72 6d 20 61 6e 20 6f 6e 6c 69 6e 65 20  rform an online 
26a0: 62 61 63 6b 75 70 20 6f 66 20 64 61 74 61 62 61  backup of databa
26b0: 73 65 20 70 44 62 20 74 6f 20 74 68 65 20 64 61  se pDb to the da
26c0: 74 61 62 61 73 65 20 66 69 6c 65 20 6e 61 6d 65  tabase file name
26d0: 64 0a 20 20 2a 2a 20 62 79 20 7a 46 69 6c 65 6e  d.  ** by zFilen
26e0: 61 6d 65 2e 20 54 68 69 73 20 66 75 6e 63 74 69  ame. This functi
26f0: 6f 6e 20 63 6f 70 69 65 73 20 35 20 64 61 74 61  on copies 5 data
2700: 62 61 73 65 20 70 61 67 65 73 20 66 72 6f 6d 20  base pages from 
2710: 70 44 62 20 74 6f 0a 20 20 2a 2a 20 7a 46 69 6c  pDb to.  ** zFil
2720: 65 6e 61 6d 65 2c 20 74 68 65 6e 20 75 6e 6c 6f  ename, then unlo
2730: 63 6b 73 20 70 44 62 20 61 6e 64 20 73 6c 65 65  cks pDb and slee
2740: 70 73 20 66 6f 72 20 32 35 30 20 6d 73 2c 20 74  ps for 250 ms, t
2750: 68 65 6e 20 72 65 70 65 61 74 73 20 74 68 65 0a  hen repeats the.
2760: 20 20 2a 2a 20 70 72 6f 63 65 73 73 20 75 6e 74    ** process unt
2770: 69 6c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  il the entire da
2780: 74 61 62 61 73 65 20 69 73 20 62 61 63 6b 65 64  tabase is backed
2790: 20 75 70 2e 0a 20 20 2a 2a 20 0a 20 20 2a 2a 20   up..  ** .  ** 
27a0: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
27b0: 6e 74 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  nt passed to thi
27c0: 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  s function must 
27d0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
27e0: 61 20 70 72 6f 67 72 65 73 73 0a 20 20 2a 2a 20  a progress.  ** 
27f0: 66 75 6e 63 74 69 6f 6e 2e 20 41 66 74 65 72 20  function. After 
2800: 65 61 63 68 20 73 65 74 20 6f 66 20 35 20 70 61  each set of 5 pa
2810: 67 65 73 20 69 73 20 62 61 63 6b 65 64 20 75 70  ges is backed up
2820: 2c 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 66  , the progress f
2830: 75 6e 63 74 69 6f 6e 0a 20 20 2a 2a 20 69 73 20  unction.  ** is 
2840: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
2850: 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65 74   integer paramet
2860: 65 72 73 3a 20 74 68 65 20 6e 75 6d 62 65 72 20  ers: the number 
2870: 6f 66 20 70 61 67 65 73 20 6c 65 66 74 20 74 6f  of pages left to
2880: 0a 20 20 2a 2a 20 63 6f 70 79 2c 20 61 6e 64 20  .  ** copy, and 
2890: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
28a0: 20 6f 66 20 70 61 67 65 73 20 69 6e 20 74 68 65   of pages in the
28b0: 20 73 6f 75 72 63 65 20 66 69 6c 65 2e 20 54 68   source file. Th
28c0: 69 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 20  is information. 
28d0: 20 2a 2a 20 6d 61 79 20 62 65 20 75 73 65 64 2c   ** may be used,
28e0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
28f0: 20 75 70 64 61 74 65 20 61 20 47 55 49 20 70 72   update a GUI pr
2900: 6f 67 72 65 73 73 20 62 61 72 2e 0a 20 20 2a 2a  ogress bar..  **
2910: 0a 20 20 2a 2a 20 57 68 69 6c 65 20 74 68 69 73  .  ** While this
2920: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2930: 6e 69 6e 67 2c 20 61 6e 6f 74 68 65 72 20 74 68  ning, another th
2940: 72 65 61 64 20 6d 61 79 20 75 73 65 20 74 68 65  read may use the
2950: 20 64 61 74 61 62 61 73 65 20 70 44 62 2c 20 6f   database pDb, o
2960: 72 0a 20 20 2a 2a 20 61 6e 6f 74 68 65 72 20 70  r.  ** another p
2970: 72 6f 63 65 73 73 20 6d 61 79 20 61 63 63 65 73  rocess may acces
2980: 73 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  s the underlying
2990: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 76   database file v
29a0: 69 61 20 61 20 73 65 70 61 72 61 74 65 20 0a 20  ia a separate . 
29b0: 20 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a   ** connection..
29c0: 20 20 2a 2a 0a 20 20 2a 2a 20 49 66 20 74 68 65    **.  ** If the
29d0: 20 62 61 63 6b 75 70 20 70 72 6f 63 65 73 73 20   backup process 
29e0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  is successfully 
29f0: 63 6f 6d 70 6c 65 74 65 64 2c 20 53 51 4c 49 54  completed, SQLIT
2a00: 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
2a10: 2e 0a 20 20 2a 2a 20 4f 74 68 65 72 77 69 73 65  ..  ** Otherwise
2a20: 2c 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  , if an error oc
2a30: 63 75 72 73 2c 20 61 6e 20 53 51 4c 69 74 65 20  curs, an SQLite 
2a40: 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
2a50: 74 75 72 6e 65 64 2e 0a 20 20 2a 2f 0a 20 20 69  turned..  */.  i
2a60: 6e 74 20 62 61 63 6b 75 70 44 62 28 0a 20 20 20  nt backupDb(.   
2a70: 20 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 20   sqlite3 *pDb,  
2a80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2a90: 44 61 74 61 62 61 73 65 20 74 6f 20 62 61 63 6b  Database to back
2aa0: 20 75 70 20 2a 2f 0a 20 20 20 20 63 6f 6e 73 74   up */.    const
2ab0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
2ac0: 2c 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  ,      /* Name o
2ad0: 66 20 66 69 6c 65 20 74 6f 20 62 61 63 6b 20 75  f file to back u
2ae0: 70 20 74 6f 20 2a 2f 0a 20 20 20 20 76 6f 69 64  p to */.    void
2af0: 28 2a 78 50 72 6f 67 72 65 73 73 29 28 69 6e 74  (*xProgress)(int
2b00: 2c 20 69 6e 74 29 20 20 2f 2a 20 50 72 6f 67 72  , int)  /* Progr
2b10: 65 73 73 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ess function to 
2b20: 69 6e 76 6f 6b 65 20 2a 2f 20 20 20 20 20 0a 20  invoke */     . 
2b30: 20 29 7b 0a 20 20 20 20 69 6e 74 20 72 63 3b 20   ){.    int rc; 
2b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b50: 20 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20      /* Function 
2b60: 72 65 74 75 72 6e 20 63 6f 64 65 20 2a 2f 0a 20  return code */. 
2b70: 20 20 20 73 71 6c 69 74 65 33 20 2a 70 46 69 6c     sqlite3 *pFil
2b80: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  e;             /
2b90: 2a 20 44 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * Database conne
2ba0: 63 74 69 6f 6e 20 6f 70 65 6e 65 64 20 6f 6e 20  ction opened on 
2bb0: 7a 46 69 6c 65 6e 61 6d 65 20 2a 2f 0a 20 20 20  zFilename */.   
2bc0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2bd0: 2a 70 42 61 63 6b 75 70 3b 20 20 20 20 2f 2a 20  *pBackup;    /* 
2be0: 42 61 63 6b 75 70 20 68 61 6e 64 6c 65 20 75 73  Backup handle us
2bf0: 65 64 20 74 6f 20 63 6f 70 79 20 64 61 74 61 20  ed to copy data 
2c00: 2a 2f 0a 0a 20 20 20 20 2f 2a 20 4f 70 65 6e 20  */..    /* Open 
2c10: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2c20: 65 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  e identified by 
2c30: 7a 46 69 6c 65 6e 61 6d 65 2e 20 2a 2f 0a 20 20  zFilename. */.  
2c40: 20 20 72 63 20 3d 20 73 71 6c 69 74 65 33 5f 6f    rc = sqlite3_o
2c50: 70 65 6e 28 7a 46 69 6c 65 6e 61 6d 65 2c 20 26  pen(zFilename, &
2c60: 70 46 69 6c 65 29 3b 0a 20 20 20 20 69 66 28 20  pFile);.    if( 
2c70: 72 63 3d 3d 53 51 4c 49 54 45 5f 4f 4b 20 29 7b  rc==SQLITE_OK ){
2c80: 0a 0a 20 20 20 20 20 20 2f 2a 20 4f 70 65 6e 20  ..      /* Open 
2c90: 74 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  the sqlite3_back
2ca0: 75 70 20 6f 62 6a 65 63 74 20 75 73 65 64 20 74  up object used t
2cb0: 6f 20 61 63 63 6f 6d 70 6c 69 73 68 20 74 68 65  o accomplish the
2cc0: 20 74 72 61 6e 73 66 65 72 20 2a 2f 0a 20 20 20   transfer */.   
2cd0: 20 20 20 70 42 61 63 6b 75 70 20 3d 20 73 71 6c     pBackup = sql
2ce0: 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74  ite3_backup_init
2cf0: 28 70 46 69 6c 65 2c 20 22 6d 61 69 6e 22 2c 20  (pFile, "main", 
2d00: 70 44 62 2c 20 22 6d 61 69 6e 22 29 3b 0a 20 20  pDb, "main");.  
2d10: 20 20 20 20 69 66 28 20 70 42 61 63 6b 75 70 20      if( pBackup 
2d20: 29 7b 0a 20 20 0a 20 20 20 20 20 20 20 20 2f 2a  ){.  .        /*
2d30: 20 45 61 63 68 20 69 74 65 72 61 74 69 6f 6e 20   Each iteration 
2d40: 6f 66 20 74 68 69 73 20 6c 6f 6f 70 20 63 6f 70  of this loop cop
2d50: 69 65 73 20 35 20 64 61 74 61 62 61 73 65 20 70  ies 5 database p
2d60: 61 67 65 73 20 66 72 6f 6d 20 64 61 74 61 62 61  ages from databa
2d70: 73 65 0a 20 20 20 20 20 20 20 20 2a 2a 20 70 44  se.        ** pD
2d80: 62 20 74 6f 20 74 68 65 20 62 61 63 6b 75 70 20  b to the backup 
2d90: 64 61 74 61 62 61 73 65 2e 20 49 66 20 74 68 65  database. If the
2da0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2db0: 20 62 61 63 6b 75 70 5f 73 74 65 70 28 29 0a 20   backup_step(). 
2dc0: 20 20 20 20 20 20 20 2a 2a 20 69 6e 64 69 63 61         ** indica
2dd0: 74 65 73 20 74 68 61 74 20 74 68 65 72 65 20 61  tes that there a
2de0: 72 65 20 73 74 69 6c 6c 20 66 75 72 74 68 65 72  re still further
2df0: 20 70 61 67 65 73 20 74 6f 20 63 6f 70 79 2c 20   pages to copy, 
2e00: 73 6c 65 65 70 20 66 6f 72 0a 20 20 20 20 20 20  sleep for.      
2e10: 20 20 2a 2a 20 32 35 30 20 6d 73 20 62 65 66 6f    ** 250 ms befo
2e20: 72 65 20 72 65 70 65 61 74 69 6e 67 2e 20 2a 2f  re repeating. */
2e30: 0a 20 20 20 20 20 20 20 20 64 6f 20 7b 0a 20 20  .        do {.  
2e40: 20 20 20 20 20 20 20 20 72 63 20 3d 20 73 71 6c          rc = sql
2e50: 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70  ite3_backup_step
2e60: 28 70 42 61 63 6b 75 70 2c 20 35 29 3b 0a 20 20  (pBackup, 5);.  
2e70: 20 20 20 20 20 20 20 20 78 50 72 6f 67 72 65 73          xProgres
2e80: 73 28 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  s(.             
2e90: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f   sqlite3_backup_
2ea0: 72 65 6d 61 69 6e 69 6e 67 28 70 42 61 63 6b 75  remaining(pBacku
2eb0: 70 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  p),.            
2ec0: 20 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70    sqlite3_backup
2ed0: 5f 70 61 67 65 63 6f 75 6e 74 28 70 42 61 63 6b  _pagecount(pBack
2ee0: 75 70 29 0a 20 20 20 20 20 20 20 20 20 20 29 3b  up).          );
2ef0: 0a 20 20 20 20 20 20 20 20 20 20 69 66 28 20 72  .          if( r
2f00: 63 3d 3d 53 51 4c 49 54 45 5f 4f 4b 20 7c 7c 20  c==SQLITE_OK || 
2f10: 72 63 3d 3d 53 51 4c 49 54 45 5f 42 55 53 59 20  rc==SQLITE_BUSY 
2f20: 7c 7c 20 72 63 3d 3d 53 51 4c 49 54 45 5f 4c 4f  || rc==SQLITE_LO
2f30: 43 4b 45 44 20 29 7b 0a 20 20 20 20 20 20 20 20  CKED ){.        
2f40: 20 20 20 20 73 71 6c 69 74 65 33 5f 73 6c 65 65      sqlite3_slee
2f50: 70 28 32 35 30 29 3b 0a 20 20 20 20 20 20 20 20  p(250);.        
2f60: 20 20 7d 0a 20 20 20 20 20 20 20 20 7d 20 77 68    }.        } wh
2f70: 69 6c 65 28 20 72 63 3d 3d 53 51 4c 49 54 45 5f  ile( rc==SQLITE_
2f80: 4f 4b 20 7c 7c 20 72 63 3d 3d 53 51 4c 49 54 45  OK || rc==SQLITE
2f90: 5f 42 55 53 59 20 7c 7c 20 72 63 3d 3d 53 51 4c  _BUSY || rc==SQL
2fa0: 49 54 45 5f 4c 4f 43 4b 45 44 20 29 3b 0a 20 20  ITE_LOCKED );.  
2fb0: 0a 20 20 20 20 20 20 20 20 2f 2a 20 52 65 6c 65  .        /* Rele
2fc0: 61 73 65 20 72 65 73 6f 75 72 63 65 73 20 61 6c  ase resources al
2fd0: 6c 6f 63 61 74 65 64 20 62 79 20 62 61 63 6b 75  located by backu
2fe0: 70 5f 69 6e 69 74 28 29 2e 20 2a 2f 0a 20 20 20  p_init(). */.   
2ff0: 20 20 20 20 20 28 76 6f 69 64 29 73 71 6c 69 74       (void)sqlit
3000: 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68  e3_backup_finish
3010: 28 70 42 61 63 6b 75 70 29 3b 0a 20 20 20 20 20  (pBackup);.     
3020: 20 7d 0a 20 20 20 20 20 20 72 63 20 3d 20 73 71   }.      rc = sq
3030: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 70 46  lite3_errcode(pF
3040: 69 6c 65 29 3b 0a 20 20 20 20 7d 0a 20 20 20 20  ile);.    }.    
3050: 0a 20 20 20 20 2f 2a 20 43 6c 6f 73 65 20 74 68  .    /* Close th
3060: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
3070: 63 74 69 6f 6e 20 6f 70 65 6e 65 64 20 6f 6e 20  ction opened on 
3080: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 7a 46  database file zF
3090: 69 6c 65 6e 61 6d 65 0a 20 20 20 20 2a 2a 20 61  ilename.    ** a
30a0: 6e 64 20 72 65 74 75 72 6e 20 74 68 65 20 72 65  nd return the re
30b0: 73 75 6c 74 20 6f 66 20 74 68 69 73 20 66 75 6e  sult of this fun
30c0: 63 74 69 6f 6e 2e 20 2a 2f 0a 20 20 20 20 28 76  ction. */.    (v
30d0: 6f 69 64 29 73 71 6c 69 74 65 33 5f 63 6c 6f 73  oid)sqlite3_clos
30e0: 65 28 70 46 69 6c 65 29 3b 0a 20 20 20 20 72 65  e(pFile);.    re
30f0: 74 75 72 6e 20 72 63 3b 0a 20 20 7d 0a 7d 0a 3c  turn rc;.  }.}.<
3100: 2f 74 63 6c 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65  /tcl>..<p>.  The
3110: 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 73 65 6e   function presen
3120: 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
3130: 6f 75 73 20 65 78 61 6d 70 6c 65 20 63 6f 70 69  ous example copi
3140: 65 73 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f  es the entire so
3150: 75 72 63 65 0a 20 20 64 61 74 61 62 61 73 65 20  urce.  database 
3160: 69 6e 20 6f 6e 65 20 63 61 6c 6c 20 74 6f 20 5b  in one call to [
3170: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73  sqlite3_backup_s
3180: 74 65 70 28 29 5d 2e 20 54 68 69 73 20 72 65 71  tep()]. This req
3190: 75 69 72 65 73 20 68 6f 6c 64 69 6e 67 20 61 20  uires holding a 
31a0: 0a 20 20 72 65 61 64 2d 6c 6f 63 6b 20 6f 6e 20  .  read-lock on 
31b0: 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62  the source datab
31c0: 61 73 65 20 66 69 6c 65 20 66 6f 72 20 74 68 65  ase file for the
31d0: 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 65   duration of the
31e0: 20 6f 70 65 72 61 74 69 6f 6e 2c 0a 20 20 70 72   operation,.  pr
31f0: 65 76 65 6e 74 69 6e 67 20 61 6e 79 20 6f 74 68  eventing any oth
3200: 65 72 20 64 61 74 61 62 61 73 65 20 75 73 65 72  er database user
3210: 20 66 72 6f 6d 20 77 72 69 74 69 6e 67 20 74 6f   from writing to
3220: 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49   the database. I
3230: 74 20 61 6c 73 6f 0a 20 20 68 6f 6c 64 73 20 74  t also.  holds t
3240: 68 65 20 6d 75 74 65 78 20 61 73 73 6f 63 69 61  he mutex associa
3250: 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73  ted with databas
3260: 65 20 70 49 6e 4d 65 6d 6f 72 79 20 74 68 72 6f  e pInMemory thro
3270: 75 67 68 6f 75 74 20 74 68 65 20 63 6f 70 79 2c  ughout the copy,
3280: 0a 20 20 70 72 65 76 65 6e 74 69 6e 67 20 61 6e  .  preventing an
3290: 79 20 6f 74 68 65 72 20 74 68 72 65 61 64 20 66  y other thread f
32a0: 72 6f 6d 20 75 73 69 6e 67 20 69 74 2e 20 54 68  rom using it. Th
32b0: 65 20 43 20 66 75 6e 63 74 69 6f 6e 20 69 6e 20  e C function in 
32c0: 74 68 69 73 20 73 65 63 74 69 6f 6e 2c 0a 20 20  this section,.  
32d0: 64 65 73 69 67 6e 65 64 20 74 6f 20 62 65 20 63  designed to be c
32e0: 61 6c 6c 65 64 20 62 79 20 61 20 62 61 63 6b 67  alled by a backg
32f0: 72 6f 75 6e 64 20 74 68 72 65 61 64 20 6f 72 20  round thread or 
3300: 70 72 6f 63 65 73 73 20 66 6f 72 20 63 72 65 61  process for crea
3310: 74 69 6e 67 20 61 20 0a 20 20 62 61 63 6b 75 70  ting a .  backup
3320: 20 6f 66 20 61 6e 20 6f 6e 6c 69 6e 65 20 64 61   of an online da
3330: 74 61 62 61 73 65 2c 20 61 76 6f 69 64 73 20 74  tabase, avoids t
3340: 68 65 73 65 20 70 72 6f 62 6c 65 6d 73 20 75 73  hese problems us
3350: 69 6e 67 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ing the followin
3360: 67 20 0a 20 20 61 70 70 72 6f 61 63 68 3a 0a 0a  g .  approach:..
3370: 20 20 3c 6f 6c 3e 0a 20 20 20 20 3c 6c 69 3e 46    <ol>.    <li>F
3380: 75 6e 63 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  unction [sqlite3
3390: 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 5d 20  _backup_init()] 
33a0: 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 63 72 65  is called to cre
33b0: 61 74 65 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  ate an [sqlite3_
33c0: 62 61 63 6b 75 70 5d 0a 20 20 20 20 20 20 20 20  backup].        
33d0: 6f 62 6a 65 63 74 20 74 6f 20 63 6f 70 79 20 64  object to copy d
33e0: 61 74 61 20 66 72 6f 6d 20 64 61 74 61 62 61 73  ata from databas
33f0: 65 20 70 44 62 20 74 6f 20 74 68 65 20 62 61 63  e pDb to the bac
3400: 6b 75 70 20 64 61 74 61 62 61 73 65 20 66 69 6c  kup database fil
3410: 65 20 0a 20 20 20 20 20 20 20 20 69 64 65 6e 74  e .        ident
3420: 69 66 69 65 64 20 62 79 20 7a 46 69 6c 65 6e 61  ified by zFilena
3430: 6d 65 2e 0a 20 20 20 20 3c 6c 69 3e 46 75 6e 63  me..    <li>Func
3440: 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61  tion [sqlite3_ba
3450: 63 6b 75 70 5f 73 74 65 70 28 29 5d 20 69 73 20  ckup_step()] is 
3460: 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 70 61  called with a pa
3470: 72 61 6d 65 74 65 72 20 6f 66 20 35 20 74 6f 0a  rameter of 5 to.
3480: 20 20 20 20 20 20 20 20 63 6f 70 79 20 35 20 70          copy 5 p
3490: 61 67 65 73 20 6f 66 20 64 61 74 61 62 61 73 65  ages of database
34a0: 20 70 44 62 20 74 6f 20 74 68 65 20 62 61 63 6b   pDb to the back
34b0: 75 70 20 64 61 74 61 62 61 73 65 20 28 66 69 6c  up database (fil
34c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 29 2e 0a 20 20  e zFilename)..  
34d0: 20 20 3c 6c 69 3e 49 66 20 74 68 65 72 65 20 61    <li>If there a
34e0: 72 65 20 73 74 69 6c 6c 20 6d 6f 72 65 20 70 61  re still more pa
34f0: 67 65 73 20 74 6f 20 63 6f 70 79 20 66 72 6f 6d  ges to copy from
3500: 20 64 61 74 61 62 61 73 65 20 70 44 62 2c 20 74   database pDb, t
3510: 68 65 6e 20 74 68 65 0a 20 20 20 20 20 20 20 20  hen the.        
3520: 66 75 6e 63 74 69 6f 6e 20 73 6c 65 65 70 73 20  function sleeps 
3530: 66 6f 72 20 32 35 30 20 6d 69 6c 6c 69 73 65 63  for 250 millisec
3540: 6f 6e 64 73 20 28 75 73 69 6e 67 20 74 68 65 20  onds (using the 
3550: 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29  [sqlite3_sleep()
3560: 5d 0a 20 20 20 20 20 20 20 20 75 74 69 6c 69 74  ].        utilit
3570: 79 29 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  y) and then retu
3580: 72 6e 73 20 74 6f 20 73 74 65 70 20 32 2e 0a 20  rns to step 2.. 
3590: 20 20 20 3c 6c 69 3e 46 75 6e 63 74 69 6f 6e 20     <li>Function 
35a0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
35b0: 66 69 6e 69 73 68 28 29 5d 20 69 73 20 63 61 6c  finish()] is cal
35c0: 6c 65 64 20 74 6f 20 63 6c 65 61 6e 20 75 70 20  led to clean up 
35d0: 72 65 73 6f 75 72 63 65 73 0a 20 20 20 20 20 20  resources.      
35e0: 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b    allocated by [
35f0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69  sqlite3_backup_i
3600: 6e 69 74 28 29 5d 2e 0a 20 20 3c 2f 6f 6c 3e 0a  nit()]..  </ol>.
3610: 0a 3c 70 3e 3c 62 3e 46 69 6c 65 20 61 6e 64 20  .<p><b>File and 
3620: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
3630: 69 6f 6e 20 4c 6f 63 6b 69 6e 67 3c 2f 62 3e 0a  ion Locking</b>.
3640: 0a 3c 70 3e 0a 20 20 44 75 72 69 6e 67 20 74 68  .<p>.  During th
3650: 65 20 32 35 30 20 6d 73 20 73 6c 65 65 70 20 69  e 250 ms sleep i
3660: 6e 20 73 74 65 70 20 33 20 61 62 6f 76 65 2c 20  n step 3 above, 
3670: 6e 6f 20 72 65 61 64 2d 6c 6f 63 6b 20 69 73 20  no read-lock is 
3680: 68 65 6c 64 20 6f 6e 20 74 68 65 20 64 61 74 61  held on the data
3690: 62 61 73 65 0a 20 20 66 69 6c 65 20 61 6e 64 20  base.  file and 
36a0: 74 68 65 20 6d 75 74 65 78 20 61 73 73 6f 63 69  the mutex associ
36b0: 61 74 65 64 20 77 69 74 68 20 70 44 62 20 69 73  ated with pDb is
36c0: 20 6e 6f 74 20 68 65 6c 64 2e 20 54 68 69 73 20   not held. This 
36d0: 61 6c 6c 6f 77 73 20 6f 74 68 65 72 20 74 68 72  allows other thr
36e0: 65 61 64 73 0a 20 20 74 6f 20 75 73 65 20 5b 64  eads.  to use [d
36f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3700: 6f 6e 5d 20 70 44 62 20 61 6e 64 20 6f 74 68 65  on] pDb and othe
3710: 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f  r connections to
3720: 20 77 72 69 74 65 20 74 6f 20 74 68 65 0a 20 20   write to the.  
3730: 75 6e 64 65 72 6c 79 69 6e 67 20 64 61 74 61 62  underlying datab
3740: 61 73 65 20 66 69 6c 65 2e 20 0a 0a 3c 70 3e 0a  ase file. ..<p>.
3750: 20 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72    If another thr
3760: 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73 20 77  ead or process w
3770: 72 69 74 65 73 20 74 6f 20 74 68 65 20 73 6f 75  rites to the sou
3780: 72 63 65 20 64 61 74 61 62 61 73 65 20 77 68 69  rce database whi
3790: 6c 65 20 74 68 69 73 20 0a 20 20 66 75 6e 63 74  le this .  funct
37a0: 69 6f 6e 20 69 73 20 73 6c 65 65 70 69 6e 67 2c  ion is sleeping,
37b0: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64 65 74   then SQLite det
37c0: 65 63 74 73 20 74 68 69 73 20 61 6e 64 20 75 73  ects this and us
37d0: 75 61 6c 6c 79 20 72 65 73 74 61 72 74 73 20 74  ually restarts t
37e0: 68 65 20 0a 20 20 62 61 63 6b 75 70 20 70 72 6f  he .  backup pro
37f0: 63 65 73 73 20 77 68 65 6e 20 73 71 6c 69 74 65  cess when sqlite
3800: 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20  3_backup_step() 
3810: 69 73 20 6e 65 78 74 20 63 61 6c 6c 65 64 2e 20  is next called. 
3820: 54 68 65 72 65 20 69 73 20 6f 6e 65 20 0a 20 20  There is one .  
3830: 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 74 68 69  exception to thi
3840: 73 20 72 75 6c 65 3a 20 49 66 20 74 68 65 20 73  s rule: If the s
3850: 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 69  ource database i
3860: 73 20 6e 6f 74 20 61 6e 20 69 6e 2d 6d 65 6d 6f  s not an in-memo
3870: 72 79 20 64 61 74 61 62 61 73 65 2c 0a 20 20 61  ry database,.  a
3880: 6e 64 20 74 68 65 20 77 72 69 74 65 20 69 73 20  nd the write is 
3890: 70 65 72 66 6f 72 6d 65 64 20 66 72 6f 6d 20 77  performed from w
38a0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
38b0: 72 6f 63 65 73 73 20 61 73 20 74 68 65 20 62 61  rocess as the ba
38c0: 63 6b 75 70 0a 20 20 6f 70 65 72 61 74 69 6f 6e  ckup.  operation
38d0: 20 61 6e 64 20 75 73 65 73 20 74 68 65 20 73 61   and uses the sa
38e0: 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  me database hand
38f0: 6c 65 20 28 70 44 62 29 2c 20 74 68 65 6e 20 74  le (pDb), then t
3900: 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 0a 20  he destination. 
3910: 20 64 61 74 61 62 61 73 65 20 28 74 68 65 20 6f   database (the o
3920: 6e 65 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20  ne opened using 
3930: 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 46 69 6c 65  connection pFile
3940: 29 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  ) is automatical
3950: 6c 79 20 75 70 64 61 74 65 64 0a 20 20 61 6c 6f  ly updated.  alo
3960: 6e 67 20 77 69 74 68 20 74 68 65 20 73 6f 75 72  ng with the sour
3970: 63 65 2e 20 54 68 65 20 62 61 63 6b 75 70 20 70  ce. The backup p
3980: 72 6f 63 65 73 73 20 6d 61 79 20 74 68 65 6e 20  rocess may then 
3990: 62 65 20 63 6f 6e 74 69 6e 75 65 64 20 61 66 74  be continued aft
39a0: 65 72 20 74 68 65 20 0a 20 20 73 71 6c 69 74 65  er the .  sqlite
39b0: 33 5f 73 6c 65 65 70 28 29 20 63 61 6c 6c 20 72  3_sleep() call r
39c0: 65 74 75 72 6e 73 20 61 73 20 69 66 20 6e 6f 74  eturns as if not
39d0: 68 69 6e 67 20 68 61 64 20 68 61 70 70 65 6e 65  hing had happene
39e0: 64 2e 20 0a 0a 3c 70 3e 0a 20 20 57 68 65 74 68  d. ..<p>.  Wheth
39f0: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 62 61  er or not the ba
3a00: 63 6b 75 70 20 70 72 6f 63 65 73 73 20 69 73 20  ckup process is 
3a10: 72 65 73 74 61 72 74 65 64 20 61 73 20 61 20 72  restarted as a r
3a20: 65 73 75 6c 74 20 6f 66 20 77 72 69 74 65 73 20  esult of writes 
3a30: 74 6f 0a 20 20 74 68 65 20 73 6f 75 72 63 65 20  to.  the source 
3a40: 64 61 74 61 62 61 73 65 20 6d 69 64 2d 62 61 63  database mid-bac
3a50: 6b 75 70 2c 20 74 68 65 20 75 73 65 72 20 63 61  kup, the user ca
3a60: 6e 20 62 65 20 73 75 72 65 20 74 68 61 74 20 77  n be sure that w
3a70: 68 65 6e 20 74 68 65 20 62 61 63 6b 75 70 0a 20  hen the backup. 
3a80: 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 63 6f   operation is co
3a90: 6d 70 6c 65 74 65 64 20 74 68 65 20 62 61 63 6b  mpleted the back
3aa0: 75 70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 74  up database cont
3ab0: 61 69 6e 73 20 61 20 63 6f 6e 73 69 73 74 65 6e  ains a consisten
3ac0: 74 20 61 6e 64 20 0a 20 20 75 70 2d 74 6f 2d 64  t and .  up-to-d
3ad0: 61 74 65 20 73 6e 61 70 73 68 6f 74 20 6f 66 20  ate snapshot of 
3ae0: 74 68 65 20 6f 72 69 67 69 6e 61 6c 2e 20 48 6f  the original. Ho
3af0: 77 65 76 65 72 3a 0a 0a 20 20 3c 75 6c 3e 0a 20  wever:..  <ul>. 
3b00: 20 20 20 3c 6c 69 3e 20 57 72 69 74 65 73 20 74     <li> Writes t
3b10: 6f 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20 73  o an in-memory s
3b20: 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 2c 20  ource database, 
3b30: 6f 72 20 77 72 69 74 65 73 20 74 6f 20 61 20 66  or writes to a f
3b40: 69 6c 65 2d 62 61 73 65 64 20 0a 20 20 20 20 20  ile-based .     
3b50: 20 20 20 20 73 6f 75 72 63 65 20 64 61 74 61 62      source datab
3b60: 61 73 65 20 62 79 20 61 6e 20 65 78 74 65 72 6e  ase by an extern
3b70: 61 6c 20 70 72 6f 63 65 73 73 20 6f 72 20 74 68  al process or th
3b80: 72 65 61 64 20 75 73 69 6e 67 20 61 20 0a 20 20  read using a .  
3b90: 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
3ba0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 74 68 65 72  connection other
3bb0: 20 74 68 61 6e 20 70 44 62 20 61 72 65 20 73 69   than pDb are si
3bc0: 67 6e 69 66 69 63 61 6e 74 6c 79 20 6d 6f 72 65  gnificantly more
3bd0: 20 65 78 70 65 6e 73 69 76 65 20 0a 20 20 20 20   expensive .    
3be0: 20 20 20 20 20 74 68 61 6e 20 77 72 69 74 65 73       than writes
3bf0: 20 6d 61 64 65 20 74 6f 20 61 20 66 69 6c 65 2d   made to a file-
3c00: 62 61 73 65 64 20 73 6f 75 72 63 65 20 64 61 74  based source dat
3c10: 61 62 61 73 65 20 75 73 69 6e 67 20 70 44 62 20  abase using pDb 
3c20: 28 61 73 20 74 68 65 0a 20 20 20 20 20 20 20 20  (as the.        
3c30: 20 65 6e 74 69 72 65 20 62 61 63 6b 75 70 20 6f   entire backup o
3c40: 70 65 72 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  peration must be
3c50: 20 72 65 73 74 61 72 74 65 64 20 69 6e 20 74 68   restarted in th
3c60: 65 20 66 6f 72 6d 65 72 20 74 77 6f 20 63 61 73  e former two cas
3c70: 65 73 29 2e 0a 0a 20 20 20 20 3c 6c 69 3e 20 49  es)...    <li> I
3c80: 66 20 74 68 65 20 62 61 63 6b 75 70 20 70 72 6f  f the backup pro
3c90: 63 65 73 73 20 69 73 20 72 65 73 74 61 72 74 65  cess is restarte
3ca0: 64 20 66 72 65 71 75 65 6e 74 6c 79 20 65 6e 6f  d frequently eno
3cb0: 75 67 68 20 69 74 20 6d 61 79 20 6e 65 76 65 72  ugh it may never
3cc0: 0a 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 6f  .         run to
3cd0: 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 20   completion and 
3ce0: 74 68 65 20 62 61 63 6b 75 70 44 62 28 29 20 66  the backupDb() f
3cf0: 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6e 65 76 65  unction may neve
3d00: 72 20 72 65 74 75 72 6e 2e 0a 20 20 3c 2f 75 6c  r return..  </ul
3d10: 3e 0a 20 0a 3c 70 3e 3c 62 3e 62 61 63 6b 75 70  >. .<p><b>backup
3d20: 5f 72 65 6d 61 69 6e 69 6e 67 28 29 20 61 6e 64  _remaining() and
3d30: 20 62 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e   backup_pagecoun
3d40: 74 28 29 3c 2f 62 3e 0a 0a 3c 70 3e 0a 20 20 54  t()</b>..<p>.  T
3d50: 68 65 20 62 61 63 6b 75 70 44 62 28 29 20 66 75  he backupDb() fu
3d60: 6e 63 74 69 6f 6e 20 75 73 65 73 20 74 68 65 20  nction uses the 
3d70: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72  sqlite3_backup_r
3d80: 65 6d 61 69 6e 69 6e 67 28 29 20 61 6e 64 0a 20  emaining() and. 
3d90: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f   sqlite3_backup_
3da0: 70 61 67 65 63 6f 75 6e 74 28 29 20 66 75 6e 63  pagecount() func
3db0: 74 69 6f 6e 73 20 74 6f 20 72 65 70 6f 72 74 20  tions to report 
3dc0: 69 74 73 20 70 72 6f 67 72 65 73 73 20 76 69 61  its progress via
3dd0: 20 74 68 65 0a 20 20 75 73 65 72 2d 73 75 70 70   the.  user-supp
3de0: 6c 69 65 64 20 78 50 72 6f 67 72 65 73 73 28 29  lied xProgress()
3df0: 20 63 61 6c 6c 62 61 63 6b 2e 20 46 75 6e 63 74   callback. Funct
3e00: 69 6f 6e 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ion sqlite3_back
3e10: 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 0a 20  up_remaining(). 
3e20: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
3e30: 62 65 72 20 6f 66 20 70 61 67 65 73 20 6c 65 66  ber of pages lef
3e40: 74 20 74 6f 20 63 6f 70 79 20 61 6e 64 20 73 71  t to copy and sq
3e50: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67  lite3_backup_pag
3e60: 65 63 6f 75 6e 74 28 29 0a 20 20 72 65 74 75 72  ecount().  retur
3e70: 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
3e80: 62 65 72 20 6f 66 20 70 61 67 65 73 20 69 6e 20  ber of pages in 
3e90: 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62  the source datab
3ea0: 61 73 65 20 28 69 6e 20 74 68 69 73 20 63 61 73  ase (in this cas
3eb0: 65 20 0a 20 20 74 68 65 20 64 61 74 61 62 61 73  e .  the databas
3ec0: 65 20 6f 70 65 6e 65 64 20 62 79 20 70 44 62 29  e opened by pDb)
3ed0: 2e 20 53 6f 20 74 68 65 20 70 65 72 63 65 6e 74  . So the percent
3ee0: 61 67 65 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  age completion o
3ef0: 66 20 74 68 65 20 70 72 6f 63 65 73 73 0a 20 20  f the process.  
3f00: 6d 61 79 20 62 65 20 63 61 6c 63 75 6c 61 74 65  may be calculate
3f10: 64 20 61 73 3a 0a 0a 3c 70 20 73 74 79 6c 65 3d  d as:..<p style=
3f20: 22 66 6f 6e 74 2d 66 61 6d 69 6c 79 3a 66 69 78  "font-family:fix
3f30: 65 64 3b 6d 61 72 67 69 6e 2d 6c 65 66 74 3a 35  ed;margin-left:5
3f40: 65 6d 22 3e 0a 20 20 43 6f 6d 70 6c 65 74 69 6f  em">.  Completio
3f50: 6e 20 3d 20 31 30 30 25 20 2a 20 28 70 61 67 65  n = 100% * (page
3f60: 63 6f 75 6e 74 28 29 20 2d 20 72 65 6d 61 69 6e  count() - remain
3f70: 69 6e 67 28 29 29 20 2f 20 70 61 67 65 63 6f 75  ing()) / pagecou
3f80: 6e 74 28 29 0a 0a 3c 70 3e 0a 20 20 54 68 65 20  nt()..<p>.  The 
3f90: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72  sqlite3_backup_r
3fa0: 65 6d 61 69 6e 69 6e 67 28 29 20 61 6e 64 20 73  emaining() and s
3fb0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61  qlite3_backup_pa
3fc0: 67 65 63 6f 75 6e 74 28 29 20 41 50 49 73 20 72  gecount() APIs r
3fd0: 65 70 6f 72 74 0a 20 20 76 61 6c 75 65 73 20 73  eport.  values s
3fe0: 74 6f 72 65 64 20 62 79 20 74 68 65 20 70 72 65  tored by the pre
3ff0: 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
4000: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65  lite3_backup_ste
4010: 70 28 29 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  p(), they do not
4020: 0a 20 20 61 63 74 75 61 6c 6c 79 20 69 6e 73 70  .  actually insp
4030: 65 63 74 20 74 68 65 20 73 6f 75 72 63 65 20 64  ect the source d
4040: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 54 68  atabase file. Th
4050: 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
4060: 20 74 68 65 20 73 6f 75 72 63 65 0a 20 20 64 61   the source.  da
4070: 74 61 62 61 73 65 20 69 73 20 77 72 69 74 74 65  tabase is writte
4080: 6e 20 74 6f 20 62 79 20 61 6e 6f 74 68 65 72 20  n to by another 
4090: 74 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73  thread or proces
40a0: 73 20 61 66 74 65 72 20 74 68 65 20 63 61 6c 6c  s after the call
40b0: 20 74 6f 0a 20 20 73 71 6c 69 74 65 33 5f 62 61   to.  sqlite3_ba
40c0: 63 6b 75 70 5f 73 74 65 70 28 29 20 72 65 74 75  ckup_step() retu
40d0: 72 6e 73 20 62 75 74 20 62 65 66 6f 72 65 20 74  rns but before t
40e0: 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
40f0: 65 64 20 62 79 0a 20 20 73 71 6c 69 74 65 33 5f  ed by.  sqlite3_
4100: 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e 69 6e 67  backup_remaining
4110: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 62  () and sqlite3_b
4120: 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 28  ackup_pagecount(
4130: 29 20 61 72 65 20 75 73 65 64 2c 20 74 68 65 20  ) are used, the 
4140: 0a 20 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  .  values may be
4150: 20 74 65 63 68 6e 69 63 61 6c 6c 79 20 69 6e 63   technically inc
4160: 6f 72 72 65 63 74 2e 20 54 68 69 73 20 69 73 20  orrect. This is 
4170: 6e 6f 74 20 75 73 75 61 6c 6c 79 20 61 20 70 72  not usually a pr
4180: 6f 62 6c 65 6d 2e 0a 0a 0a 3c 64 69 76 20 73 74  oblem....<div st
4190: 79 6c 65 3d 22 63 6c 65 61 72 3a 62 6f 74 68 22  yle="clear:both"
41a0: 3e 3c 2f 64 69 76 3e 0a                          ></div>.