/ Hex Artifact Content
Login

Artifact 6fb6294c34a9ca93b5894a33bca530c6f08decba:


0000: 2f 2a 0a 2a 2a 20 32 30 31 34 20 41 75 67 75 73  /*.** 2014 Augus
0010: 74 20 33 30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  t 30.**.** The a
0020: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
0030: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
0040: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
0050: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
0060: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
0070: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
0080: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
0090: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
00a0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
00b0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
00c0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
00d0: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
00e0: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
00f0: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
0100: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
0110: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
0120: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ***.**.** This f
0180: 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ile contains the
0190: 20 70 75 62 6c 69 63 20 69 6e 74 65 72 66 61 63   public interfac
01a0: 65 20 66 6f 72 20 74 68 65 20 52 42 55 20 65 78  e for the RBU ex
01b0: 74 65 6e 73 69 6f 6e 2e 20 0a 2a 2f 0a 0a 2f 2a  tension. .*/../*
01c0: 0a 2a 2a 20 53 55 4d 4d 41 52 59 0a 2a 2a 0a 2a  .** SUMMARY.**.*
01d0: 2a 20 57 72 69 74 69 6e 67 20 61 20 74 72 61 6e  * Writing a tran
01e0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 69  saction containi
01f0: 6e 67 20 61 20 6c 61 72 67 65 20 6e 75 6d 62 65  ng a large numbe
0200: 72 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 73 20  r of operations 
0210: 6f 6e 20 0a 2a 2a 20 62 2d 74 72 65 65 20 69 6e  on .** b-tree in
0220: 64 65 78 65 73 20 74 68 61 74 20 61 72 65 20 63  dexes that are c
0230: 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6c 61 72 67  ollectively larg
0240: 65 72 20 74 68 61 6e 20 74 68 65 20 61 76 61 69  er than the avai
0250: 6c 61 62 6c 65 20 63 61 63 68 65 0a 2a 2a 20 6d  lable cache.** m
0260: 65 6d 6f 72 79 20 63 61 6e 20 62 65 20 76 65 72  emory can be ver
0270: 79 20 69 6e 65 66 66 69 63 69 65 6e 74 2e 20 0a  y inefficient. .
0280: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 62 6c 65  **.** The proble
0290: 6d 20 69 73 20 74 68 61 74 20 69 6e 20 6f 72 64  m is that in ord
02a0: 65 72 20 74 6f 20 75 70 64 61 74 65 20 61 20 62  er to update a b
02b0: 2d 74 72 65 65 2c 20 74 68 65 20 6c 65 61 66 20  -tree, the leaf 
02c0: 70 61 67 65 20 28 61 74 20 6c 65 61 73 74 29 0a  page (at least).
02d0: 2a 2a 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ** containing th
02e0: 65 20 65 6e 74 72 79 20 62 65 69 6e 67 20 69 6e  e entry being in
02f0: 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
0300: 64 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69  d must be modifi
0310: 65 64 2e 20 49 66 20 74 68 65 0a 2a 2a 20 77 6f  ed. If the.** wo
0320: 72 6b 69 6e 67 20 73 65 74 20 6f 66 20 6c 65 61  rking set of lea
0330: 76 65 73 20 69 73 20 6c 61 72 67 65 72 20 74 68  ves is larger th
0340: 61 6e 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  an the available
0350: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 2c 20 74   cache memory, t
0360: 68 65 6e 20 61 20 0a 2a 2a 20 73 69 6e 67 6c 65  hen a .** single
0370: 20 6c 65 61 66 20 74 68 61 74 20 69 73 20 6d 6f   leaf that is mo
0380: 64 69 66 69 65 64 20 6d 6f 72 65 20 74 68 61 6e  dified more than
0390: 20 6f 6e 63 65 20 61 73 20 70 61 72 74 20 6f 66   once as part of
03a0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
03b0: 20 0a 2a 2a 20 6d 61 79 20 62 65 20 6c 6f 61 64   .** may be load
03c0: 65 64 20 66 72 6f 6d 20 6f 72 20 77 72 69 74 74  ed from or writt
03d0: 65 6e 20 74 6f 20 74 68 65 20 70 65 72 73 69 73  en to the persis
03e0: 74 65 6e 74 20 6d 65 64 69 61 20 6d 75 6c 74 69  tent media multi
03f0: 70 6c 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 41 64  ple times..** Ad
0400: 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 62 65 63 61  ditionally, beca
0410: 75 73 65 20 74 68 65 20 69 6e 64 65 78 20 75 70  use the index up
0420: 64 61 74 65 73 20 61 72 65 20 6c 69 6b 65 6c 79  dates are likely
0430: 20 74 6f 20 62 65 20 61 70 70 6c 69 65 64 20 69   to be applied i
0440: 6e 0a 2a 2a 20 72 61 6e 64 6f 6d 20 6f 72 64 65  n.** random orde
0450: 72 2c 20 61 63 63 65 73 73 20 74 6f 20 70 61 67  r, access to pag
0460: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 64 61  es within the da
0470: 74 61 62 61 73 65 20 69 73 20 61 6c 73 6f 20 6c  tabase is also l
0480: 69 6b 65 6c 79 20 74 6f 20 62 65 20 69 6e 20 0a  ikely to be in .
0490: 2a 2a 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72 2c  ** random order,
04a0: 20 77 68 69 63 68 20 69 73 20 69 74 73 65 6c 66   which is itself
04b0: 20 71 75 69 74 65 20 69 6e 65 66 66 69 63 69 65   quite inefficie
04c0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 77 61  nt..**.** One wa
04d0: 79 20 74 6f 20 69 6d 70 72 6f 76 65 20 74 68 65  y to improve the
04e0: 20 73 69 74 75 61 74 69 6f 6e 20 69 73 20 74 6f   situation is to
04f0: 20 73 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74   sort the operat
0500: 69 6f 6e 73 20 6f 6e 20 65 61 63 68 20 69 6e 64  ions on each ind
0510: 65 78 0a 2a 2a 20 62 79 20 69 6e 64 65 78 20 6b  ex.** by index k
0520: 65 79 20 62 65 66 6f 72 65 20 61 70 70 6c 79 69  ey before applyi
0530: 6e 67 20 74 68 65 6d 20 74 6f 20 74 68 65 20 62  ng them to the b
0540: 2d 74 72 65 65 2e 20 54 68 69 73 20 6c 65 61 64  -tree. This lead
0550: 73 20 74 6f 20 61 6e 20 49 4f 0a 2a 2a 20 70 61  s to an IO.** pa
0560: 74 74 65 72 6e 20 74 68 61 74 20 72 65 73 65 6d  ttern that resem
0570: 62 6c 65 73 20 61 20 73 69 6e 67 6c 65 20 6c 69  bles a single li
0580: 6e 65 61 72 20 73 63 61 6e 20 74 68 72 6f 75 67  near scan throug
0590: 68 20 74 68 65 20 69 6e 64 65 78 20 62 2d 74 72  h the index b-tr
05a0: 65 65 2c 0a 2a 2a 20 61 6e 64 20 61 6c 6c 20 62  ee,.** and all b
05b0: 75 74 20 67 75 61 72 61 6e 74 65 65 73 20 65 61  ut guarantees ea
05c0: 63 68 20 6d 6f 64 69 66 69 65 64 20 6c 65 61 66  ch modified leaf
05d0: 20 70 61 67 65 20 69 73 20 6c 6f 61 64 65 64 20   page is loaded 
05e0: 61 6e 64 20 73 74 6f 72 65 64 20 0a 2a 2a 20 65  and stored .** e
05f0: 78 61 63 74 6c 79 20 6f 6e 63 65 2e 20 53 51 4c  xactly once. SQL
0600: 69 74 65 20 75 73 65 73 20 74 68 69 73 20 74 72  ite uses this tr
0610: 69 63 6b 20 74 6f 20 69 6d 70 72 6f 76 65 20 74  ick to improve t
0620: 68 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  he performance o
0630: 66 0a 2a 2a 20 43 52 45 41 54 45 20 49 4e 44 45  f.** CREATE INDE
0640: 58 20 63 6f 6d 6d 61 6e 64 73 2e 20 54 68 69 73  X commands. This
0650: 20 65 78 74 65 6e 73 69 6f 6e 20 61 6c 6c 6f 77   extension allow
0660: 73 20 69 74 20 74 6f 20 62 65 20 75 73 65 64 20  s it to be used 
0670: 74 6f 20 69 6d 70 72 6f 76 65 0a 2a 2a 20 74 68  to improve.** th
0680: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 66  e performance of
0690: 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
06a0: 6f 6e 73 20 6f 6e 20 65 78 69 73 74 69 6e 67 20  ons on existing 
06b0: 64 61 74 61 62 61 73 65 73 2e 0a 2a 2a 0a 2a 2a  databases..**.**
06c0: 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 74   Additionally, t
06d0: 68 69 73 20 65 78 74 65 6e 73 69 6f 6e 20 61 6c  his extension al
06e0: 6c 6f 77 73 20 74 68 65 20 77 6f 72 6b 20 69 6e  lows the work in
06f0: 76 6f 6c 76 65 64 20 69 6e 20 77 72 69 74 69 6e  volved in writin
0700: 67 20 74 68 65 20 0a 2a 2a 20 6c 61 72 67 65 20  g the .** large 
0710: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 62  transaction to b
0720: 65 20 62 72 6f 6b 65 6e 20 64 6f 77 6e 20 69 6e  e broken down in
0730: 74 6f 20 73 75 62 2d 74 72 61 6e 73 61 63 74 69  to sub-transacti
0740: 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 0a 2a  ons performed .*
0750: 2a 20 73 65 71 75 65 6e 74 69 61 6c 6c 79 20 62  * sequentially b
0760: 79 20 73 65 70 61 72 61 74 65 20 70 72 6f 63 65  y separate proce
0770: 73 73 65 73 2e 20 54 68 69 73 20 69 73 20 75 73  sses. This is us
0780: 65 66 75 6c 20 69 66 20 74 68 65 20 73 79 73 74  eful if the syst
0790: 65 6d 20 63 61 6e 6e 6f 74 20 0a 2a 2a 20 67 75  em cannot .** gu
07a0: 61 72 61 6e 74 65 65 20 74 68 61 74 20 61 20 73  arantee that a s
07b0: 69 6e 67 6c 65 20 75 70 64 61 74 65 20 70 72 6f  ingle update pro
07c0: 63 65 73 73 20 77 69 6c 6c 20 72 75 6e 20 66 6f  cess will run fo
07d0: 72 20 6c 6f 6e 67 20 65 6e 6f 75 67 68 20 74 6f  r long enough to
07e0: 20 61 70 70 6c 79 20 0a 2a 2a 20 74 68 65 20 65   apply .** the e
07f0: 6e 74 69 72 65 20 75 70 64 61 74 65 2c 20 66 6f  ntire update, fo
0800: 72 20 65 78 61 6d 70 6c 65 20 62 65 63 61 75 73  r example becaus
0810: 65 20 74 68 65 20 75 70 64 61 74 65 20 69 73 20  e the update is 
0820: 62 65 69 6e 67 20 61 70 70 6c 69 65 64 20 6f 6e  being applied on
0830: 20 61 20 0a 2a 2a 20 6d 6f 62 69 6c 65 20 64 65   a .** mobile de
0840: 76 69 63 65 20 74 68 61 74 20 69 73 20 66 72 65  vice that is fre
0850: 71 75 65 6e 74 6c 79 20 72 65 62 6f 6f 74 65 64  quently rebooted
0860: 2e 20 45 76 65 6e 20 61 66 74 65 72 20 74 68 65  . Even after the
0870: 20 77 72 69 74 65 72 20 70 72 6f 63 65 73 73 20   writer process 
0880: 0a 2a 2a 20 68 61 73 20 63 6f 6d 6d 69 74 74 65  .** has committe
0890: 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 75  d one or more su
08a0: 62 2d 74 72 61 6e 73 61 63 74 69 6f 6e 73 2c 20  b-transactions, 
08b0: 6f 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63  other database c
08c0: 6c 69 65 6e 74 73 20 63 6f 6e 74 69 6e 75 65 0a  lients continue.
08d0: 2a 2a 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20  ** to read from 
08e0: 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 64 61 74  the original dat
08f0: 61 62 61 73 65 20 73 6e 61 70 73 68 6f 74 2e 20  abase snapshot. 
0900: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
0910: 70 61 72 74 69 61 6c 6c 79 20 0a 2a 2a 20 61 70  partially .** ap
0920: 70 6c 69 65 64 20 74 72 61 6e 73 61 63 74 69 6f  plied transactio
0930: 6e 73 20 61 72 65 20 6e 6f 74 20 76 69 73 69 62  ns are not visib
0940: 6c 65 20 74 6f 20 6f 74 68 65 72 20 63 6c 69 65  le to other clie
0950: 6e 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 22 52 42 55  nts. .**.** "RBU
0960: 22 20 73 74 61 6e 64 73 20 66 6f 72 20 22 52 65  " stands for "Re
0970: 73 75 6d 61 62 6c 65 20 42 75 6c 6b 20 55 70 64  sumable Bulk Upd
0980: 61 74 65 22 2e 20 41 73 20 69 6e 20 61 20 6c 61  ate". As in a la
0990: 72 67 65 20 64 61 74 61 62 61 73 65 20 75 70 64  rge database upd
09a0: 61 74 65 0a 2a 2a 20 74 72 61 6e 73 6d 69 74 74  ate.** transmitt
09b0: 65 64 20 76 69 61 20 61 20 77 69 72 65 6c 65 73  ed via a wireles
09c0: 73 20 6e 65 74 77 6f 72 6b 20 74 6f 20 61 20 6d  s network to a m
09d0: 6f 62 69 6c 65 20 64 65 76 69 63 65 2e 20 41 20  obile device. A 
09e0: 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 61  transaction.** a
09f0: 70 70 6c 69 65 64 20 75 73 69 6e 67 20 74 68 69  pplied using thi
0a00: 73 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68  s extension is h
0a10: 65 6e 63 65 20 72 65 66 65 72 65 64 20 74 6f 20  ence refered to 
0a20: 61 73 20 61 6e 20 22 52 42 55 20 75 70 64 61 74  as an "RBU updat
0a30: 65 22 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 4c 49 4d  e"..**.**.** LIM
0a40: 49 54 41 54 49 4f 4e 53 0a 2a 2a 0a 2a 2a 20 41  ITATIONS.**.** A
0a50: 6e 20 22 52 42 55 20 75 70 64 61 74 65 22 20 74  n "RBU update" t
0a60: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 75  ransaction is su
0a70: 62 6a 65 63 74 20 74 6f 20 74 68 65 20 66 6f 6c  bject to the fol
0a80: 6c 6f 77 69 6e 67 20 6c 69 6d 69 74 61 74 69 6f  lowing limitatio
0a90: 6e 73 3a 0a 2a 2a 0a 2a 2a 20 20 20 2a 20 54 68  ns:.**.**   * Th
0aa0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 75  e transaction mu
0ab0: 73 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 49 4e  st consist of IN
0ac0: 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
0ad0: 20 44 45 4c 45 54 45 20 6f 70 65 72 61 74 69 6f   DELETE operatio
0ae0: 6e 73 0a 2a 2a 20 20 20 20 20 6f 6e 6c 79 2e 0a  ns.**     only..
0af0: 2a 2a 0a 2a 2a 20 20 20 2a 20 49 4e 53 45 52 54  **.**   * INSERT
0b00: 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 61 79 20   statements may 
0b10: 6e 6f 74 20 75 73 65 20 61 6e 79 20 64 65 66 61  not use any defa
0b20: 75 6c 74 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  ult values..**.*
0b30: 2a 20 20 20 2a 20 55 50 44 41 54 45 20 61 6e 64  *   * UPDATE and
0b40: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
0b50: 74 73 20 6d 75 73 74 20 69 64 65 6e 74 69 66 79  ts must identify
0b60: 20 74 68 65 69 72 20 74 61 72 67 65 74 20 72 6f   their target ro
0b70: 77 73 20 62 79 20 0a 2a 2a 20 20 20 20 20 6e 6f  ws by .**     no
0b80: 6e 2d 4e 55 4c 4c 20 50 52 49 4d 41 52 59 20 4b  n-NULL PRIMARY K
0b90: 45 59 20 76 61 6c 75 65 73 2e 20 52 6f 77 73 20  EY values. Rows 
0ba0: 77 69 74 68 20 4e 55 4c 4c 20 76 61 6c 75 65 73  with NULL values
0bb0: 20 73 74 6f 72 65 64 20 69 6e 20 50 52 49 4d 41   stored in PRIMA
0bc0: 52 59 0a 2a 2a 20 20 20 20 20 4b 45 59 20 66 69  RY.**     KEY fi
0bd0: 65 6c 64 73 20 6d 61 79 20 6e 6f 74 20 62 65 20  elds may not be 
0be0: 75 70 64 61 74 65 64 20 6f 72 20 64 65 6c 65 74  updated or delet
0bf0: 65 64 2e 20 49 66 20 74 68 65 20 74 61 62 6c 65  ed. If the table
0c00: 20 62 65 69 6e 67 20 77 72 69 74 74 65 6e 20 0a   being written .
0c10: 2a 2a 20 20 20 20 20 68 61 73 20 6e 6f 20 50 52  **     has no PR
0c20: 49 4d 41 52 59 20 4b 45 59 2c 20 61 66 66 65 63  IMARY KEY, affec
0c30: 74 65 64 20 72 6f 77 73 20 6d 75 73 74 20 62 65  ted rows must be
0c40: 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 72   identified by r
0c50: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 20 20 2a 20  owid..**.**   * 
0c60: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
0c70: 73 20 6d 61 79 20 6e 6f 74 20 6d 6f 64 69 66 79  s may not modify
0c80: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c   PRIMARY KEY col
0c90: 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 20 20 2a 20  umns..**.**   * 
0ca0: 4e 6f 20 74 72 69 67 67 65 72 73 20 77 69 6c 6c  No triggers will
0cb0: 20 62 65 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   be fired..**.**
0cc0: 20 20 20 2a 20 4e 6f 20 66 6f 72 65 69 67 6e 20     * No foreign 
0cd0: 6b 65 79 20 76 69 6f 6c 61 74 69 6f 6e 73 20 61  key violations a
0ce0: 72 65 20 64 65 74 65 63 74 65 64 20 6f 72 20 72  re detected or r
0cf0: 65 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 20  eported..**.**  
0d00: 20 2a 20 43 48 45 43 4b 20 63 6f 6e 73 74 72 61   * CHECK constra
0d10: 69 6e 74 73 20 61 72 65 20 6e 6f 74 20 65 6e 66  ints are not enf
0d20: 6f 72 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 20 20 2a  orced..**.**   *
0d30: 20 4e 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 68   No constraint h
0d40: 61 6e 64 6c 69 6e 67 20 6d 6f 64 65 20 65 78 63  andling mode exc
0d50: 65 70 74 20 66 6f 72 20 22 4f 52 20 52 4f 4c 4c  ept for "OR ROLL
0d60: 42 41 43 4b 22 20 69 73 20 73 75 70 70 6f 72 74  BACK" is support
0d70: 65 64 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 50 52 45  ed..**.**.** PRE
0d80: 50 41 52 41 54 49 4f 4e 0a 2a 2a 0a 2a 2a 20 41  PARATION.**.** A
0d90: 6e 20 22 52 42 55 20 75 70 64 61 74 65 22 20 69  n "RBU update" i
0da0: 73 20 73 74 6f 72 65 64 20 61 73 20 61 20 73 65  s stored as a se
0db0: 70 61 72 61 74 65 20 53 51 4c 69 74 65 20 64 61  parate SQLite da
0dc0: 74 61 62 61 73 65 2e 20 41 20 64 61 74 61 62 61  tabase. A databa
0dd0: 73 65 0a 2a 2a 20 63 6f 6e 74 61 69 6e 69 6e 67  se.** containing
0de0: 20 61 6e 20 52 42 55 20 75 70 64 61 74 65 20 69   an RBU update i
0df0: 73 20 61 6e 20 22 52 42 55 20 64 61 74 61 62 61  s an "RBU databa
0e00: 73 65 22 2e 20 46 6f 72 20 65 61 63 68 20 74 61  se". For each ta
0e10: 62 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 74  ble in the .** t
0e20: 61 72 67 65 74 20 64 61 74 61 62 61 73 65 20 74  arget database t
0e30: 6f 20 62 65 20 75 70 64 61 74 65 64 2c 20 74 68  o be updated, th
0e40: 65 20 52 42 55 20 64 61 74 61 62 61 73 65 20 73  e RBU database s
0e50: 68 6f 75 6c 64 20 63 6f 6e 74 61 69 6e 20 61 20  hould contain a 
0e60: 74 61 62 6c 65 0a 2a 2a 20 6e 61 6d 65 64 20 22  table.** named "
0e70: 64 61 74 61 5f 3c 74 61 72 67 65 74 20 6e 61 6d  data_<target nam
0e80: 65 3e 22 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  e>" containing t
0e90: 68 65 20 73 61 6d 65 20 73 65 74 20 6f 66 20 63  he same set of c
0ea0: 6f 6c 75 6d 6e 73 20 61 73 20 74 68 65 0a 2a 2a  olumns as the.**
0eb0: 20 74 61 72 67 65 74 20 74 61 62 6c 65 2c 20 61   target table, a
0ec0: 6e 64 20 6f 6e 65 20 6d 6f 72 65 20 2d 20 22 72  nd one more - "r
0ed0: 62 75 5f 63 6f 6e 74 72 6f 6c 22 2e 20 54 68 65  bu_control". The
0ee0: 20 64 61 74 61 5f 25 20 74 61 62 6c 65 20 73 68   data_% table sh
0ef0: 6f 75 6c 64 20 0a 2a 2a 20 68 61 76 65 20 6e 6f  ould .** have no
0f00: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 6f 72 20   PRIMARY KEY or 
0f10: 55 4e 49 51 55 45 20 63 6f 6e 73 74 72 61 69 6e  UNIQUE constrain
0f20: 74 73 2c 20 62 75 74 20 65 61 63 68 20 63 6f 6c  ts, but each col
0f30: 75 6d 6e 20 73 68 6f 75 6c 64 20 68 61 76 65 0a  umn should have.
0f40: 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65  ** the same type
0f50: 20 61 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f   as the correspo
0f60: 6e 64 69 6e 67 20 63 6f 6c 75 6d 6e 20 69 6e 20  nding column in 
0f70: 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62  the target datab
0f80: 61 73 65 2e 0a 2a 2a 20 54 68 65 20 22 72 62 75  ase..** The "rbu
0f90: 5f 63 6f 6e 74 72 6f 6c 22 20 63 6f 6c 75 6d 6e  _control" column
0fa0: 20 73 68 6f 75 6c 64 20 68 61 76 65 20 6e 6f 20   should have no 
0fb0: 74 79 70 65 20 61 74 20 61 6c 6c 2e 20 46 6f 72  type at all. For
0fc0: 20 65 78 61 6d 70 6c 65 2c 20 69 66 0a 2a 2a 20   example, if.** 
0fd0: 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62  the target datab
0fe0: 61 73 65 20 63 6f 6e 74 61 69 6e 73 3a 0a 2a 2a  ase contains:.**
0ff0: 0a 2a 2a 20 20 20 43 52 45 41 54 45 20 54 41 42  .**   CREATE TAB
1000: 4c 45 20 74 31 28 61 20 49 4e 54 45 47 45 52 20  LE t1(a INTEGER 
1010: 50 52 49 4d 41 52 59 20 4b 45 59 2c 20 62 20 54  PRIMARY KEY, b T
1020: 45 58 54 2c 20 63 20 55 4e 49 51 55 45 29 3b 0a  EXT, c UNIQUE);.
1030: 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 65 20 52  **.** Then the R
1040: 42 55 20 64 61 74 61 62 61 73 65 20 73 68 6f 75  BU database shou
1050: 6c 64 20 63 6f 6e 74 61 69 6e 3a 0a 2a 2a 0a 2a  ld contain:.**.*
1060: 2a 20 20 20 43 52 45 41 54 45 20 54 41 42 4c 45  *   CREATE TABLE
1070: 20 64 61 74 61 5f 74 31 28 61 20 49 4e 54 45 47   data_t1(a INTEG
1080: 45 52 2c 20 62 20 54 45 58 54 2c 20 63 2c 20 72  ER, b TEXT, c, r
1090: 62 75 5f 63 6f 6e 74 72 6f 6c 29 3b 0a 2a 2a 0a  bu_control);.**.
10a0: 2a 2a 20 54 68 65 20 6f 72 64 65 72 20 6f 66 20  ** The order of 
10b0: 74 68 65 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74  the columns in t
10c0: 68 65 20 64 61 74 61 5f 25 20 74 61 62 6c 65 20  he data_% table 
10d0: 64 6f 65 73 20 6e 6f 74 20 6d 61 74 74 65 72 2e  does not matter.
10e0: 0a 2a 2a 0a 2a 2a 20 49 6e 73 74 65 61 64 20 6f  .**.** Instead o
10f0: 66 20 61 20 72 65 67 75 6c 61 72 20 74 61 62 6c  f a regular tabl
1100: 65 2c 20 74 68 65 20 52 42 55 20 64 61 74 61 62  e, the RBU datab
1110: 61 73 65 20 6d 61 79 20 61 6c 73 6f 20 63 6f 6e  ase may also con
1120: 74 61 69 6e 20 76 69 72 74 75 61 6c 0a 2a 2a 20  tain virtual.** 
1130: 74 61 62 6c 65 73 20 6f 72 20 76 69 65 77 20 6e  tables or view n
1140: 61 6d 65 64 20 75 73 69 6e 67 20 74 68 65 20 64  amed using the d
1150: 61 74 61 5f 3c 74 61 72 67 65 74 3e 20 6e 61 6d  ata_<target> nam
1160: 69 6e 67 20 73 63 68 65 6d 65 2e 20 0a 2a 2a 0a  ing scheme. .**.
1170: 2a 2a 20 49 6e 73 74 65 61 64 20 6f 66 20 74 68  ** Instead of th
1180: 65 20 70 6c 61 69 6e 20 64 61 74 61 5f 3c 74 61  e plain data_<ta
1190: 72 67 65 74 3e 20 6e 61 6d 69 6e 67 20 73 63 68  rget> naming sch
11a0: 65 6d 65 2c 20 52 42 55 20 64 61 74 61 62 61 73  eme, RBU databas
11b0: 65 20 74 61 62 6c 65 73 20 0a 2a 2a 20 6d 61 79  e tables .** may
11c0: 20 61 6c 73 6f 20 62 65 20 6e 61 6d 65 64 20 64   also be named d
11d0: 61 74 61 3c 69 6e 74 65 67 65 72 3e 5f 3c 74 61  ata<integer>_<ta
11e0: 72 67 65 74 3e 2c 20 77 68 65 72 65 20 3c 69 6e  rget>, where <in
11f0: 74 65 67 65 72 3e 20 69 73 20 61 6e 79 20 73 65  teger> is any se
1200: 71 75 65 6e 63 65 0a 2a 2a 20 6f 66 20 7a 65 72  quence.** of zer
1210: 6f 20 6f 72 20 6d 6f 72 65 20 6e 75 6d 65 72 69  o or more numeri
1220: 63 20 63 68 61 72 61 63 74 65 72 73 20 28 30 2d  c characters (0-
1230: 39 29 2e 20 54 68 69 73 20 63 61 6e 20 62 65 20  9). This can be 
1240: 73 69 67 6e 69 66 69 63 61 6e 74 20 62 65 63 61  significant beca
1250: 75 73 65 0a 2a 2a 20 74 61 62 6c 65 73 20 77 69  use.** tables wi
1260: 74 68 69 6e 20 74 68 65 20 52 42 55 20 64 61 74  thin the RBU dat
1270: 61 62 61 73 65 20 61 72 65 20 61 6c 77 61 79 73  abase are always
1280: 20 70 72 6f 63 65 73 73 65 64 20 69 6e 20 6f 72   processed in or
1290: 64 65 72 20 73 6f 72 74 65 64 20 62 79 20 0a 2a  der sorted by .*
12a0: 2a 20 6e 61 6d 65 2e 20 42 79 20 6a 75 64 69 63  * name. By judic
12b0: 69 6f 75 73 20 73 65 6c 65 63 74 69 6f 6e 20 6f  ious selection o
12c0: 66 20 74 68 65 20 3c 69 6e 74 65 67 65 72 3e 20  f the <integer> 
12d0: 70 6f 72 74 69 6f 6e 20 6f 66 20 74 68 65 20 6e  portion of the n
12e0: 61 6d 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 52  ames.** of the R
12f0: 42 55 20 74 61 62 6c 65 73 20 74 68 65 20 75 73  BU tables the us
1300: 65 72 20 63 61 6e 20 74 68 65 72 65 66 6f 72 65  er can therefore
1310: 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6f 72 64   control the ord
1320: 65 72 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  er in which they
1330: 0a 2a 2a 20 61 72 65 20 70 72 6f 63 65 73 73 65  .** are processe
1340: 64 2e 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  d. This can be u
1350: 73 65 66 75 6c 2c 20 66 6f 72 20 65 78 61 6d 70  seful, for examp
1360: 6c 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  le, to ensure th
1370: 61 74 20 22 65 78 74 65 72 6e 61 6c 0a 2a 2a 20  at "external.** 
1380: 63 6f 6e 74 65 6e 74 22 20 46 54 53 34 20 74 61  content" FTS4 ta
1390: 62 6c 65 73 20 61 72 65 20 75 70 64 61 74 65 64  bles are updated
13a0: 20 62 65 66 6f 72 65 20 74 68 65 69 72 20 75 6e   before their un
13b0: 64 65 72 6c 79 69 6e 67 20 63 6f 6e 74 65 6e 74  derlying content
13c0: 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 49   tables..**.** I
13d0: 66 20 74 68 65 20 74 61 72 67 65 74 20 64 61 74  f the target dat
13e0: 61 62 61 73 65 20 74 61 62 6c 65 20 69 73 20 61  abase table is a
13f0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f   virtual table o
1400: 72 20 61 20 74 61 62 6c 65 20 74 68 61 74 20 68  r a table that h
1410: 61 73 20 6e 6f 0a 2a 2a 20 50 52 49 4d 41 52 59  as no.** PRIMARY
1420: 20 4b 45 59 20 64 65 63 6c 61 72 61 74 69 6f 6e   KEY declaration
1430: 2c 20 74 68 65 20 64 61 74 61 5f 25 20 74 61 62  , the data_% tab
1440: 6c 65 20 6d 75 73 74 20 61 6c 73 6f 20 63 6f 6e  le must also con
1450: 74 61 69 6e 20 61 20 63 6f 6c 75 6d 6e 20 0a 2a  tain a column .*
1460: 2a 20 6e 61 6d 65 64 20 22 72 62 75 5f 72 6f 77  * named "rbu_row
1470: 69 64 22 2e 20 54 68 69 73 20 63 6f 6c 75 6d 6e  id". This column
1480: 20 69 73 20 6d 61 70 70 65 64 20 74 6f 20 74 68   is mapped to th
1490: 65 20 74 61 62 6c 65 73 20 69 6d 70 6c 69 63 69  e tables implici
14a0: 74 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65  t primary .** ke
14b0: 79 20 63 6f 6c 75 6d 6e 20 2d 20 22 72 6f 77 69  y column - "rowi
14c0: 64 22 2e 20 56 69 72 74 75 61 6c 20 74 61 62 6c  d". Virtual tabl
14d0: 65 73 20 66 6f 72 20 77 68 69 63 68 20 74 68 65  es for which the
14e0: 20 22 72 6f 77 69 64 22 20 63 6f 6c 75 6d 6e 20   "rowid" column 
14f0: 64 6f 65 73 20 0a 2a 2a 20 6e 6f 74 20 66 75 6e  does .** not fun
1500: 63 74 69 6f 6e 20 6c 69 6b 65 20 61 20 70 72 69  ction like a pri
1510: 6d 61 72 79 20 6b 65 79 20 76 61 6c 75 65 20 63  mary key value c
1520: 61 6e 6e 6f 74 20 62 65 20 75 70 64 61 74 65 64  annot be updated
1530: 20 75 73 69 6e 67 20 52 42 55 2e 20 46 6f 72 20   using RBU. For 
1540: 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
1550: 74 68 65 20 74 61 72 67 65 74 20 64 62 20 63 6f  the target db co
1560: 6e 74 61 69 6e 73 20 65 69 74 68 65 72 20 6f 66  ntains either of
1570: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a   the following:.
1580: 2a 2a 0a 2a 2a 20 20 20 43 52 45 41 54 45 20 56  **.**   CREATE V
1590: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 78 31 20  IRTUAL TABLE x1 
15a0: 55 53 49 4e 47 20 66 74 73 33 28 61 2c 20 62 29  USING fts3(a, b)
15b0: 3b 0a 2a 2a 20 20 20 43 52 45 41 54 45 20 54 41  ;.**   CREATE TA
15c0: 42 4c 45 20 78 31 28 61 2c 20 62 29 0a 2a 2a 0a  BLE x1(a, b).**.
15d0: 2a 2a 20 74 68 65 6e 20 74 68 65 20 52 42 55 20  ** then the RBU 
15e0: 64 61 74 61 62 61 73 65 20 73 68 6f 75 6c 64 20  database should 
15f0: 63 6f 6e 74 61 69 6e 3a 0a 2a 2a 0a 2a 2a 20 20  contain:.**.**  
1600: 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 64 61   CREATE TABLE da
1610: 74 61 5f 78 31 28 61 2c 20 62 2c 20 72 62 75 5f  ta_x1(a, b, rbu_
1620: 72 6f 77 69 64 2c 20 72 62 75 5f 63 6f 6e 74 72  rowid, rbu_contr
1630: 6f 6c 29 3b 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 6e  ol);.**.** All n
1640: 6f 6e 2d 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e  on-hidden column
1650: 73 20 28 69 2e 65 2e 20 61 6c 6c 20 63 6f 6c 75  s (i.e. all colu
1660: 6d 6e 73 20 6d 61 74 63 68 65 64 20 62 79 20 22  mns matched by "
1670: 53 45 4c 45 43 54 20 2a 22 29 20 6f 66 20 74 68  SELECT *") of th
1680: 65 0a 2a 2a 20 74 61 72 67 65 74 20 74 61 62 6c  e.** target tabl
1690: 65 20 6d 75 73 74 20 62 65 20 70 72 65 73 65 6e  e must be presen
16a0: 74 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 74  t in the input t
16b0: 61 62 6c 65 2e 20 46 6f 72 20 76 69 72 74 75 61  able. For virtua
16c0: 6c 20 74 61 62 6c 65 73 2c 0a 2a 2a 20 68 69 64  l tables,.** hid
16d0: 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20  den columns are 
16e0: 6f 70 74 69 6f 6e 61 6c 20 2d 20 74 68 65 79 20  optional - they 
16f0: 61 72 65 20 75 70 64 61 74 65 64 20 62 79 20 52  are updated by R
1700: 42 55 20 69 66 20 70 72 65 73 65 6e 74 20 69 6e  BU if present in
1710: 0a 2a 2a 20 74 68 65 20 69 6e 70 75 74 20 74 61  .** the input ta
1720: 62 6c 65 2c 20 6f 72 20 6e 6f 74 20 6f 74 68 65  ble, or not othe
1730: 72 77 69 73 65 2e 20 46 6f 72 20 65 78 61 6d 70  rwise. For examp
1740: 6c 65 2c 20 74 6f 20 77 72 69 74 65 20 74 6f 20  le, to write to 
1750: 61 6e 20 66 74 73 34 0a 2a 2a 20 74 61 62 6c 65  an fts4.** table
1760: 20 77 69 74 68 20 61 20 68 69 64 64 65 6e 20 6c   with a hidden l
1770: 61 6e 67 75 61 67 65 69 64 20 63 6f 6c 75 6d 6e  anguageid column
1780: 20 73 75 63 68 20 61 73 3a 0a 2a 2a 0a 2a 2a 20   such as:.**.** 
1790: 20 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c    CREATE VIRTUAL
17a0: 20 54 41 42 4c 45 20 66 74 31 20 55 53 49 4e 47   TABLE ft1 USING
17b0: 20 66 74 73 34 28 61 2c 20 62 2c 20 6c 61 6e 67   fts4(a, b, lang
17c0: 75 61 67 65 69 64 3d 27 6c 61 6e 67 69 64 27 29  uageid='langid')
17d0: 3b 0a 2a 2a 0a 2a 2a 20 45 69 74 68 65 72 20 6f  ;.**.** Either o
17e0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
17f0: 69 6e 70 75 74 20 74 61 62 6c 65 20 73 63 68 65  input table sche
1800: 6d 61 73 20 6d 61 79 20 62 65 20 75 73 65 64 3a  mas may be used:
1810: 0a 2a 2a 0a 2a 2a 20 20 20 43 52 45 41 54 45 20  .**.**   CREATE 
1820: 54 41 42 4c 45 20 64 61 74 61 5f 66 74 31 28 61  TABLE data_ft1(a
1830: 2c 20 62 2c 20 6c 61 6e 67 69 64 2c 20 72 62 75  , b, langid, rbu
1840: 5f 72 6f 77 69 64 2c 20 72 62 75 5f 63 6f 6e 74  _rowid, rbu_cont
1850: 72 6f 6c 29 3b 0a 2a 2a 20 20 20 43 52 45 41 54  rol);.**   CREAT
1860: 45 20 54 41 42 4c 45 20 64 61 74 61 5f 66 74 31  E TABLE data_ft1
1870: 28 61 2c 20 62 2c 20 72 62 75 5f 72 6f 77 69 64  (a, b, rbu_rowid
1880: 2c 20 72 62 75 5f 63 6f 6e 74 72 6f 6c 29 3b 0a  , rbu_control);.
1890: 2a 2a 0a 2a 2a 20 46 6f 72 20 65 61 63 68 20 72  **.** For each r
18a0: 6f 77 20 74 6f 20 49 4e 53 45 52 54 20 69 6e 74  ow to INSERT int
18b0: 6f 20 74 68 65 20 74 61 72 67 65 74 20 64 61 74  o the target dat
18c0: 61 62 61 73 65 20 61 73 20 70 61 72 74 20 6f 66  abase as part of
18d0: 20 74 68 65 20 52 42 55 20 0a 2a 2a 20 75 70 64   the RBU .** upd
18e0: 61 74 65 2c 20 74 68 65 20 63 6f 72 72 65 73 70  ate, the corresp
18f0: 6f 6e 64 69 6e 67 20 64 61 74 61 5f 25 20 74 61  onding data_% ta
1900: 62 6c 65 20 73 68 6f 75 6c 64 20 63 6f 6e 74 61  ble should conta
1910: 69 6e 20 61 20 73 69 6e 67 6c 65 20 72 65 63 6f  in a single reco
1920: 72 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  rd.** with the "
1930: 72 62 75 5f 63 6f 6e 74 72 6f 6c 22 20 63 6f 6c  rbu_control" col
1940: 75 6d 6e 20 73 65 74 20 74 6f 20 63 6f 6e 74 61  umn set to conta
1950: 69 6e 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  in integer value
1960: 20 30 2e 20 54 68 65 0a 2a 2a 20 6f 74 68 65 72   0. The.** other
1970: 20 63 6f 6c 75 6d 6e 73 20 73 68 6f 75 6c 64 20   columns should 
1980: 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 76 61  be set to the va
1990: 6c 75 65 73 20 74 68 61 74 20 6d 61 6b 65 20 75  lues that make u
19a0: 70 20 74 68 65 20 6e 65 77 20 72 65 63 6f 72 64  p the new record
19b0: 20 0a 2a 2a 20 74 6f 20 69 6e 73 65 72 74 2e 20   .** to insert. 
19c0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 74 61  .**.** If the ta
19d0: 72 67 65 74 20 64 61 74 61 62 61 73 65 20 74 61  rget database ta
19e0: 62 6c 65 20 68 61 73 20 61 6e 20 49 4e 54 45 47  ble has an INTEG
19f0: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 2c 20  ER PRIMARY KEY, 
1a00: 69 74 20 69 73 20 6e 6f 74 20 0a 2a 2a 20 70 6f  it is not .** po
1a10: 73 73 69 62 6c 65 20 74 6f 20 69 6e 73 65 72 74  ssible to insert
1a20: 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
1a30: 74 6f 20 74 68 65 20 49 50 4b 20 63 6f 6c 75 6d  to the IPK colum
1a40: 6e 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  n. Attempting to
1a50: 20 0a 2a 2a 20 64 6f 20 73 6f 20 72 65 73 75 6c   .** do so resul
1a60: 74 73 20 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f  ts in an SQLITE_
1a70: 4d 49 53 4d 41 54 43 48 20 65 72 72 6f 72 2e 0a  MISMATCH error..
1a80: 2a 2a 0a 2a 2a 20 46 6f 72 20 65 61 63 68 20 72  **.** For each r
1a90: 6f 77 20 74 6f 20 44 45 4c 45 54 45 20 66 72 6f  ow to DELETE fro
1aa0: 6d 20 74 68 65 20 74 61 72 67 65 74 20 64 61 74  m the target dat
1ab0: 61 62 61 73 65 20 61 73 20 70 61 72 74 20 6f 66  abase as part of
1ac0: 20 74 68 65 20 52 42 55 20 0a 2a 2a 20 75 70 64   the RBU .** upd
1ad0: 61 74 65 2c 20 74 68 65 20 63 6f 72 72 65 73 70  ate, the corresp
1ae0: 6f 6e 64 69 6e 67 20 64 61 74 61 5f 25 20 74 61  onding data_% ta
1af0: 62 6c 65 20 73 68 6f 75 6c 64 20 63 6f 6e 74 61  ble should conta
1b00: 69 6e 20 61 20 73 69 6e 67 6c 65 20 72 65 63 6f  in a single reco
1b10: 72 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  rd.** with the "
1b20: 72 62 75 5f 63 6f 6e 74 72 6f 6c 22 20 63 6f 6c  rbu_control" col
1b30: 75 6d 6e 20 73 65 74 20 74 6f 20 63 6f 6e 74 61  umn set to conta
1b40: 69 6e 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  in integer value
1b50: 20 31 2e 20 54 68 65 0a 2a 2a 20 72 65 61 6c 20   1. The.** real 
1b60: 70 72 69 6d 61 72 79 20 6b 65 79 20 76 61 6c 75  primary key valu
1b70: 65 73 20 6f 66 20 74 68 65 20 72 6f 77 20 74 6f  es of the row to
1b80: 20 64 65 6c 65 74 65 20 73 68 6f 75 6c 64 20 62   delete should b
1b90: 65 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a  e stored in the.
1ba0: 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
1bb0: 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 74 68 65 20   columns of the 
1bc0: 64 61 74 61 5f 25 20 74 61 62 6c 65 2e 20 54 68  data_% table. Th
1bd0: 65 20 76 61 6c 75 65 73 20 73 74 6f 72 65 64 20  e values stored 
1be0: 69 6e 20 74 68 65 0a 2a 2a 20 6f 74 68 65 72 20  in the.** other 
1bf0: 63 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20  columns are not 
1c00: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  used..**.** For 
1c10: 65 61 63 68 20 72 6f 77 20 74 6f 20 55 50 44 41  each row to UPDA
1c20: 54 45 20 66 72 6f 6d 20 74 68 65 20 74 61 72 67  TE from the targ
1c30: 65 74 20 64 61 74 61 62 61 73 65 20 61 73 20 70  et database as p
1c40: 61 72 74 20 6f 66 20 74 68 65 20 52 42 55 20 0a  art of the RBU .
1c50: 2a 2a 20 75 70 64 61 74 65 2c 20 74 68 65 20 63  ** update, the c
1c60: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74  orresponding dat
1c70: 61 5f 25 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  a_% table should
1c80: 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c   contain a singl
1c90: 65 20 72 65 63 6f 72 64 0a 2a 2a 20 77 69 74 68  e record.** with
1ca0: 20 74 68 65 20 22 72 62 75 5f 63 6f 6e 74 72 6f   the "rbu_contro
1cb0: 6c 22 20 63 6f 6c 75 6d 6e 20 73 65 74 20 74 6f  l" column set to
1cc0: 20 63 6f 6e 74 61 69 6e 20 61 20 76 61 6c 75 65   contain a value
1cd0: 20 6f 66 20 74 79 70 65 20 74 65 78 74 2e 0a 2a   of type text..*
1ce0: 2a 20 54 68 65 20 72 65 61 6c 20 70 72 69 6d 61  * The real prima
1cf0: 72 79 20 6b 65 79 20 76 61 6c 75 65 73 20 69 64  ry key values id
1d00: 65 6e 74 69 66 79 69 6e 67 20 74 68 65 20 72 6f  entifying the ro
1d10: 77 20 74 6f 20 75 70 64 61 74 65 20 73 68 6f 75  w to update shou
1d20: 6c 64 20 62 65 20 0a 2a 2a 20 73 74 6f 72 65 64  ld be .** stored
1d30: 20 69 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   in the correspo
1d40: 6e 64 69 6e 67 20 63 6f 6c 75 6d 6e 73 20 6f 66  nding columns of
1d50: 20 74 68 65 20 64 61 74 61 5f 25 20 74 61 62 6c   the data_% tabl
1d60: 65 20 72 6f 77 2c 20 61 73 20 73 68 6f 75 6c 64  e row, as should
1d70: 0a 2a 2a 20 74 68 65 20 6e 65 77 20 76 61 6c 75  .** the new valu
1d80: 65 73 20 6f 66 20 61 6c 6c 20 63 6f 6c 75 6d 6e  es of all column
1d90: 73 20 62 65 69 6e 67 20 75 70 64 61 74 65 2e 20  s being update. 
1da0: 54 68 65 20 74 65 78 74 20 76 61 6c 75 65 20 69  The text value i
1db0: 6e 20 74 68 65 20 0a 2a 2a 20 22 72 62 75 5f 63  n the .** "rbu_c
1dc0: 6f 6e 74 72 6f 6c 22 20 63 6f 6c 75 6d 6e 20 6d  ontrol" column m
1dd0: 75 73 74 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  ust contain the 
1de0: 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  same number of c
1df0: 68 61 72 61 63 74 65 72 73 20 61 73 0a 2a 2a 20  haracters as.** 
1e00: 74 68 65 72 65 20 61 72 65 20 63 6f 6c 75 6d 6e  there are column
1e10: 73 20 69 6e 20 74 68 65 20 74 61 72 67 65 74 20  s in the target 
1e20: 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2c 20  database table, 
1e30: 61 6e 64 20 6d 75 73 74 20 63 6f 6e 73 69 73 74  and must consist
1e40: 20 65 6e 74 69 72 65 6c 79 0a 2a 2a 20 6f 66 20   entirely.** of 
1e50: 27 78 27 20 61 6e 64 20 27 2e 27 20 63 68 61 72  'x' and '.' char
1e60: 61 63 74 65 72 73 20 28 6f 72 20 69 6e 20 73 6f  acters (or in so
1e70: 6d 65 20 73 70 65 63 69 61 6c 20 63 61 73 65 73  me special cases
1e80: 20 27 64 27 20 2d 20 73 65 65 20 62 65 6c 6f 77   'd' - see below
1e90: 29 2e 20 46 6f 72 20 0a 2a 2a 20 65 61 63 68 20  ). For .** each 
1ea0: 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 62  column that is b
1eb0: 65 69 6e 67 20 75 70 64 61 74 65 64 2c 20 74 68  eing updated, th
1ec0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
1ed0: 63 68 61 72 61 63 74 65 72 20 69 73 20 73 65 74  character is set
1ee0: 20 74 6f 0a 2a 2a 20 27 78 27 2e 20 46 6f 72 20   to.** 'x'. For 
1ef0: 74 68 6f 73 65 20 74 68 61 74 20 72 65 6d 61 69  those that remai
1f00: 6e 20 61 73 20 74 68 65 79 20 61 72 65 2c 20 74  n as they are, t
1f10: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
1f20: 20 63 68 61 72 61 63 74 65 72 20 6f 66 20 74 68   character of th
1f30: 65 0a 2a 2a 20 72 62 75 5f 63 6f 6e 74 72 6f 6c  e.** rbu_control
1f40: 20 76 61 6c 75 65 20 73 68 6f 75 6c 64 20 62 65   value should be
1f50: 20 73 65 74 20 74 6f 20 27 2e 27 2e 20 46 6f 72   set to '.'. For
1f60: 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
1f70: 74 68 65 20 74 61 62 6c 65 73 20 0a 2a 2a 20 61  the tables .** a
1f80: 62 6f 76 65 2c 20 74 68 65 20 75 70 64 61 74 65  bove, the update
1f90: 20 73 74 61 74 65 6d 65 6e 74 3a 0a 2a 2a 0a 2a   statement:.**.*
1fa0: 2a 20 20 20 55 50 44 41 54 45 20 74 31 20 53 45  *   UPDATE t1 SE
1fb0: 54 20 63 20 3d 20 27 75 73 61 27 20 57 48 45 52  T c = 'usa' WHER
1fc0: 45 20 61 20 3d 20 34 3b 0a 2a 2a 0a 2a 2a 20 69  E a = 4;.**.** i
1fd0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
1fe0: 20 74 68 65 20 64 61 74 61 5f 74 31 20 72 6f 77   the data_t1 row
1ff0: 20 63 72 65 61 74 65 64 20 62 79 3a 0a 2a 2a 0a   created by:.**.
2000: 2a 2a 20 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  **   INSERT INTO
2010: 20 64 61 74 61 5f 74 31 28 61 2c 20 62 2c 20 63   data_t1(a, b, c
2020: 2c 20 72 62 75 5f 63 6f 6e 74 72 6f 6c 29 20 56  , rbu_control) V
2030: 41 4c 55 45 53 28 34 2c 20 4e 55 4c 4c 2c 20 27  ALUES(4, NULL, '
2040: 75 73 61 27 2c 20 27 2e 2e 78 27 29 3b 0a 2a 2a  usa', '..x');.**
2050: 0a 2a 2a 20 49 6e 73 74 65 61 64 20 6f 66 20 61  .** Instead of a
2060: 6e 20 27 78 27 20 63 68 61 72 61 63 74 65 72 2c  n 'x' character,
2070: 20 63 68 61 72 61 63 74 65 72 73 20 6f 66 20 74   characters of t
2080: 68 65 20 72 62 75 5f 63 6f 6e 74 72 6f 6c 20 76  he rbu_control v
2090: 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
20a0: 2a 20 66 6f 72 20 55 50 44 41 54 45 73 20 6d 61  * for UPDATEs ma
20b0: 79 20 61 6c 73 6f 20 62 65 20 73 65 74 20 74 6f  y also be set to
20c0: 20 27 64 27 2e 20 49 6e 20 74 68 69 73 20 63 61   'd'. In this ca
20d0: 73 65 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 75  se, instead of u
20e0: 70 64 61 74 69 6e 67 20 74 68 65 0a 2a 2a 20 74  pdating the.** t
20f0: 61 72 67 65 74 20 74 61 62 6c 65 20 77 69 74 68  arget table with
2100: 20 74 68 65 20 76 61 6c 75 65 20 73 74 6f 72 65   the value store
2110: 64 20 69 6e 20 74 68 65 20 63 6f 72 72 65 73 70  d in the corresp
2120: 6f 6e 64 69 6e 67 20 64 61 74 61 5f 25 20 63 6f  onding data_% co
2130: 6c 75 6d 6e 2c 20 74 68 65 0a 2a 2a 20 75 73 65  lumn, the.** use
2140: 72 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  r-defined SQL fu
2150: 6e 63 74 69 6f 6e 20 22 72 62 75 5f 64 65 6c 74  nction "rbu_delt
2160: 61 28 29 22 20 69 73 20 69 6e 76 6f 6b 65 64 20  a()" is invoked 
2170: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 73  and the result s
2180: 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 74 68 65 20  tored in.** the 
2190: 74 61 72 67 65 74 20 74 61 62 6c 65 20 63 6f 6c  target table col
21a0: 75 6d 6e 2e 20 72 62 75 5f 64 65 6c 74 61 28 29  umn. rbu_delta()
21b0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
21c0: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 2d   two arguments -
21d0: 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
21e0: 20 76 61 6c 75 65 20 63 75 72 72 65 6e 74 6c 79   value currently
21f0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 74   stored in the t
2200: 61 72 67 65 74 20 74 61 62 6c 65 20 63 6f 6c 75  arget table colu
2210: 6d 6e 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 76  mn and the .** v
2220: 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 69  alue specified i
2230: 6e 20 74 68 65 20 64 61 74 61 5f 78 78 78 20 74  n the data_xxx t
2240: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  able..**.** For 
2250: 65 78 61 6d 70 6c 65 2c 20 74 68 69 73 20 72 6f  example, this ro
2260: 77 3a 0a 2a 2a 0a 2a 2a 20 20 20 49 4e 53 45 52  w:.**.**   INSER
2270: 54 20 49 4e 54 4f 20 64 61 74 61 5f 74 31 28 61  T INTO data_t1(a
2280: 2c 20 62 2c 20 63 2c 20 72 62 75 5f 63 6f 6e 74  , b, c, rbu_cont
2290: 72 6f 6c 29 20 56 41 4c 55 45 53 28 34 2c 20 4e  rol) VALUES(4, N
22a0: 55 4c 4c 2c 20 27 75 73 61 27 2c 20 27 2e 2e 64  ULL, 'usa', '..d
22b0: 27 29 3b 0a 2a 2a 0a 2a 2a 20 69 73 20 73 69 6d  ');.**.** is sim
22c0: 69 6c 61 72 20 74 6f 20 61 6e 20 55 50 44 41 54  ilar to an UPDAT
22d0: 45 20 73 74 61 74 65 6d 65 6e 74 20 73 75 63 68  E statement such
22e0: 20 61 73 3a 20 0a 2a 2a 0a 2a 2a 20 20 20 55 50   as: .**.**   UP
22f0: 44 41 54 45 20 74 31 20 53 45 54 20 63 20 3d 20  DATE t1 SET c = 
2300: 72 62 75 5f 64 65 6c 74 61 28 63 2c 20 27 75 73  rbu_delta(c, 'us
2310: 61 27 29 20 57 48 45 52 45 20 61 20 3d 20 34 3b  a') WHERE a = 4;
2320: 0a 2a 2a 0a 2a 2a 20 46 69 6e 61 6c 6c 79 2c 20  .**.** Finally, 
2330: 69 66 20 61 6e 20 27 66 27 20 63 68 61 72 61 63  if an 'f' charac
2340: 74 65 72 20 61 70 70 65 61 72 73 20 69 6e 20 70  ter appears in p
2350: 6c 61 63 65 20 6f 66 20 61 20 27 64 27 20 6f 72  lace of a 'd' or
2360: 20 27 73 27 20 69 6e 20 61 6e 20 0a 2a 2a 20 6f   's' in an .** o
2370: 74 61 5f 63 6f 6e 74 72 6f 6c 20 73 74 72 69 6e  ta_control strin
2380: 67 2c 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  g, the contents 
2390: 6f 66 20 74 68 65 20 64 61 74 61 5f 78 78 78 20  of the data_xxx 
23a0: 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 69 73 20  table column is 
23b0: 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65  assumed.** to be
23c0: 20 61 20 22 66 6f 73 73 69 6c 20 64 65 6c 74 61   a "fossil delta
23d0: 22 20 2d 20 61 20 70 61 74 63 68 20 74 6f 20 62  " - a patch to b
23e0: 65 20 61 70 70 6c 69 65 64 20 74 6f 20 61 20 62  e applied to a b
23f0: 6c 6f 62 20 76 61 6c 75 65 20 69 6e 20 74 68 65  lob value in the
2400: 0a 2a 2a 20 66 6f 72 6d 61 74 20 75 73 65 64 20  .** format used 
2410: 62 79 20 74 68 65 20 66 6f 73 73 69 6c 20 73 6f  by the fossil so
2420: 75 72 63 65 2d 63 6f 64 65 20 6d 61 6e 61 67 65  urce-code manage
2430: 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 49 6e 20  ment system. In 
2440: 74 68 69 73 20 63 61 73 65 0a 2a 2a 20 74 68 65  this case.** the
2450: 20 65 78 69 73 74 69 6e 67 20 76 61 6c 75 65 20   existing value 
2460: 77 69 74 68 69 6e 20 74 68 65 20 74 61 72 67 65  within the targe
2470: 74 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  t database table
2480: 20 6d 75 73 74 20 62 65 20 6f 66 20 74 79 70 65   must be of type
2490: 20 42 4c 4f 42 2e 20 0a 2a 2a 20 49 74 20 69 73   BLOB. .** It is
24a0: 20 72 65 70 6c 61 63 65 64 20 62 79 20 74 68 65   replaced by the
24b0: 20 72 65 73 75 6c 74 20 6f 66 20 61 70 70 6c 79   result of apply
24c0: 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
24d0: 64 20 66 6f 73 73 69 6c 20 64 65 6c 74 61 20 74  d fossil delta t
24e0: 6f 0a 2a 2a 20 69 74 73 65 6c 66 2e 0a 2a 2a 0a  o.** itself..**.
24f0: 2a 2a 20 49 66 20 74 68 65 20 74 61 72 67 65 74  ** If the target
2500: 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
2510: 69 73 20 61 20 76 69 72 74 75 61 6c 20 74 61 62  is a virtual tab
2520: 6c 65 20 6f 72 20 61 20 74 61 62 6c 65 20 77 69  le or a table wi
2530: 74 68 20 6e 6f 20 50 52 49 4d 41 52 59 0a 2a 2a  th no PRIMARY.**
2540: 20 4b 45 59 2c 20 74 68 65 20 72 62 75 5f 63 6f   KEY, the rbu_co
2550: 6e 74 72 6f 6c 20 76 61 6c 75 65 20 73 68 6f 75  ntrol value shou
2560: 6c 64 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 61  ld not include a
2570: 20 63 68 61 72 61 63 74 65 72 20 63 6f 72 72 65   character corre
2580: 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 74 6f 20  sponding .** to 
2590: 74 68 65 20 72 62 75 5f 72 6f 77 69 64 20 76 61  the rbu_rowid va
25a0: 6c 75 65 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  lue. For example
25b0: 2c 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 20 20  , this:.**.**   
25c0: 49 4e 53 45 52 54 20 49 4e 54 4f 20 64 61 74 61  INSERT INTO data
25d0: 5f 66 74 31 28 61 2c 20 62 2c 20 72 62 75 5f 72  _ft1(a, b, rbu_r
25e0: 6f 77 69 64 2c 20 72 62 75 5f 63 6f 6e 74 72 6f  owid, rbu_contro
25f0: 6c 29 20 0a 2a 2a 20 20 20 20 20 20 20 56 41 4c  l) .**       VAL
2600: 55 45 53 28 4e 55 4c 4c 2c 20 27 75 73 61 27 2c  UES(NULL, 'usa',
2610: 20 31 32 2c 20 27 2e 78 27 29 3b 0a 2a 2a 0a 2a   12, '.x');.**.*
2620: 2a 20 63 61 75 73 65 73 20 61 20 72 65 73 75 6c  * causes a resul
2630: 74 20 73 69 6d 69 6c 61 72 20 74 6f 3a 0a 2a 2a  t similar to:.**
2640: 0a 2a 2a 20 20 20 55 50 44 41 54 45 20 66 74 31  .**   UPDATE ft1
2650: 20 53 45 54 20 62 20 3d 20 27 75 73 61 27 20 57   SET b = 'usa' W
2660: 48 45 52 45 20 72 6f 77 69 64 20 3d 20 31 32 3b  HERE rowid = 12;
2670: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 5f  .**.** The data_
2680: 78 78 78 20 74 61 62 6c 65 73 20 74 68 65 6d 73  xxx tables thems
2690: 65 6c 76 65 73 20 73 68 6f 75 6c 64 20 68 61 76  elves should hav
26a0: 65 20 6e 6f 20 50 52 49 4d 41 52 59 20 4b 45 59  e no PRIMARY KEY
26b0: 20 64 65 63 6c 61 72 61 74 69 6f 6e 73 2e 0a 2a   declarations..*
26c0: 2a 20 48 6f 77 65 76 65 72 2c 20 52 42 55 20 69  * However, RBU i
26d0: 73 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  s more efficient
26e0: 20 69 66 20 72 65 61 64 69 6e 67 20 74 68 65 20   if reading the 
26f0: 72 6f 77 73 20 69 6e 20 66 72 6f 6d 20 65 61 63  rows in from eac
2700: 68 20 64 61 74 61 5f 78 78 78 0a 2a 2a 20 74 61  h data_xxx.** ta
2710: 62 6c 65 20 69 6e 20 22 72 6f 77 69 64 22 20 6f  ble in "rowid" o
2720: 72 64 65 72 20 69 73 20 72 6f 75 67 68 6c 79 20  rder is roughly 
2730: 74 68 65 20 73 61 6d 65 20 61 73 20 72 65 61 64  the same as read
2740: 69 6e 67 20 74 68 65 6d 20 73 6f 72 74 65 64 20  ing them sorted 
2750: 62 79 0a 2a 2a 20 74 68 65 20 50 52 49 4d 41 52  by.** the PRIMAR
2760: 59 20 4b 45 59 20 6f 66 20 74 68 65 20 63 6f 72  Y KEY of the cor
2770: 72 65 73 70 6f 6e 64 69 6e 67 20 74 61 72 67 65  responding targe
2780: 74 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  t database table
2790: 2e 20 49 6e 20 6f 74 68 65 72 20 0a 2a 2a 20 77  . In other .** w
27a0: 6f 72 64 73 2c 20 72 6f 77 73 20 73 68 6f 75 6c  ords, rows shoul
27b0: 64 20 62 65 20 73 6f 72 74 65 64 20 75 73 69 6e  d be sorted usin
27c0: 67 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f  g the destinatio
27d0: 6e 20 74 61 62 6c 65 20 50 52 49 4d 41 52 59 20  n table PRIMARY 
27e0: 4b 45 59 20 0a 2a 2a 20 66 69 65 6c 64 73 20 62  KEY .** fields b
27f0: 65 66 6f 72 65 20 74 68 65 79 20 61 72 65 20 69  efore they are i
2800: 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 74 68 65  nserted into the
2810: 20 64 61 74 61 5f 78 78 78 20 74 61 62 6c 65 73   data_xxx tables
2820: 2e 0a 2a 2a 0a 2a 2a 20 55 53 41 47 45 0a 2a 2a  ..**.** USAGE.**
2830: 0a 2a 2a 20 54 68 65 20 41 50 49 20 64 65 63 6c  .** The API decl
2840: 61 72 65 64 20 62 65 6c 6f 77 20 61 6c 6c 6f 77  ared below allow
2850: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
2860: 20 74 6f 20 61 70 70 6c 79 20 61 6e 20 52 42 55   to apply an RBU
2870: 20 75 70 64 61 74 65 20 0a 2a 2a 20 73 74 6f 72   update .** stor
2880: 65 64 20 6f 6e 20 64 69 73 6b 20 74 6f 20 61 6e  ed on disk to an
2890: 20 65 78 69 73 74 69 6e 67 20 74 61 72 67 65 74   existing target
28a0: 20 64 61 74 61 62 61 73 65 2e 20 45 73 73 65 6e   database. Essen
28b0: 74 69 61 6c 6c 79 2c 20 74 68 65 20 0a 2a 2a 20  tially, the .** 
28c0: 61 70 70 6c 69 63 61 74 69 6f 6e 3a 0a 2a 2a 0a  application:.**.
28d0: 2a 2a 20 20 20 20 20 31 29 20 4f 70 65 6e 73 20  **     1) Opens 
28e0: 61 6e 20 52 42 55 20 68 61 6e 64 6c 65 20 75 73  an RBU handle us
28f0: 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 72  ing the sqlite3r
2900: 62 75 5f 6f 70 65 6e 28 29 20 66 75 6e 63 74 69  bu_open() functi
2910: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 20 20 20 20 32 29  on..**.**     2)
2920: 20 52 65 67 69 73 74 65 72 73 20 61 6e 79 20 72   Registers any r
2930: 65 71 75 69 72 65 64 20 76 69 72 74 75 61 6c 20  equired virtual 
2940: 74 61 62 6c 65 20 6d 6f 64 75 6c 65 73 20 77 69  table modules wi
2950: 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  th the database.
2960: 2a 2a 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65  **        handle
2970: 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2980: 69 74 65 33 72 62 75 5f 64 62 28 29 2e 20 41 6c  ite3rbu_db(). Al
2990: 73 6f 2c 20 69 66 20 72 65 71 75 69 72 65 64 2c  so, if required,
29a0: 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 20 20 20   register.**    
29b0: 20 20 20 20 74 68 65 20 72 62 75 5f 64 65 6c 74      the rbu_delt
29c0: 61 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  a() implementati
29d0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 20 20 20 20 33 29  on..**.**     3)
29e0: 20 43 61 6c 6c 73 20 74 68 65 20 73 71 6c 69 74   Calls the sqlit
29f0: 65 33 72 62 75 5f 73 74 65 70 28 29 20 66 75 6e  e3rbu_step() fun
2a00: 63 74 69 6f 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72  ction one or mor
2a10: 65 20 74 69 6d 65 73 20 6f 6e 0a 2a 2a 20 20 20  e times on.**   
2a20: 20 20 20 20 20 74 68 65 20 6e 65 77 20 68 61 6e       the new han
2a30: 64 6c 65 2e 20 45 61 63 68 20 63 61 6c 6c 20 74  dle. Each call t
2a40: 6f 20 73 71 6c 69 74 65 33 72 62 75 5f 73 74 65  o sqlite3rbu_ste
2a50: 70 28 29 20 70 65 72 66 6f 72 6d 73 20 61 20 73  p() performs a s
2a60: 69 6e 67 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  ingle.**        
2a70: 62 2d 74 72 65 65 20 6f 70 65 72 61 74 69 6f 6e  b-tree operation
2a80: 2c 20 73 6f 20 74 68 6f 75 73 61 6e 64 73 20 6f  , so thousands o
2a90: 66 20 63 61 6c 6c 73 20 6d 61 79 20 62 65 20 72  f calls may be r
2aa0: 65 71 75 69 72 65 64 20 74 6f 20 61 70 70 6c 79  equired to apply
2ab0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 20 63 6f   .**        a co
2ac0: 6d 70 6c 65 74 65 20 75 70 64 61 74 65 2e 0a 2a  mplete update..*
2ad0: 2a 0a 2a 2a 20 20 20 20 20 34 29 20 43 61 6c 6c  *.**     4) Call
2ae0: 73 20 73 71 6c 69 74 65 33 72 62 75 5f 63 6c 6f  s sqlite3rbu_clo
2af0: 73 65 28 29 20 74 6f 20 63 6c 6f 73 65 20 74 68  se() to close th
2b00: 65 20 52 42 55 20 75 70 64 61 74 65 20 68 61 6e  e RBU update han
2b10: 64 6c 65 2e 20 49 66 0a 2a 2a 20 20 20 20 20 20  dle. If.**      
2b20: 20 20 73 71 6c 69 74 65 33 72 62 75 5f 73 74 65    sqlite3rbu_ste
2b30: 70 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c  p() has been cal
2b40: 6c 65 64 20 65 6e 6f 75 67 68 20 74 69 6d 65 73  led enough times
2b50: 20 74 6f 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   to completely.*
2b60: 2a 20 20 20 20 20 20 20 20 61 70 70 6c 79 20 74  *        apply t
2b70: 68 65 20 75 70 64 61 74 65 20 74 6f 20 74 68 65  he update to the
2b80: 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73 65   target database
2b90: 2c 20 74 68 65 6e 20 74 68 65 20 52 42 55 20 64  , then the RBU d
2ba0: 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20  atabase.**      
2bb0: 20 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 66    is marked as f
2bc0: 75 6c 6c 79 20 61 70 70 6c 69 65 64 2e 20 4f 74  ully applied. Ot
2bd0: 68 65 72 77 69 73 65 2c 20 74 68 65 20 73 74 61  herwise, the sta
2be0: 74 65 20 6f 66 20 74 68 65 20 52 42 55 20 0a 2a  te of the RBU .*
2bf0: 2a 20 20 20 20 20 20 20 20 75 70 64 61 74 65 20  *        update 
2c00: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 73  application is s
2c10: 61 76 65 64 20 69 6e 20 74 68 65 20 52 42 55 20  aved in the RBU 
2c20: 64 61 74 61 62 61 73 65 20 66 6f 72 20 6c 61 74  database for lat
2c30: 65 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 72 65  er .**        re
2c40: 73 75 6d 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  sumption..**.** 
2c50: 53 65 65 20 63 6f 6d 6d 65 6e 74 73 20 62 65 6c  See comments bel
2c60: 6f 77 20 66 6f 72 20 6d 6f 72 65 20 64 65 74 61  ow for more deta
2c70: 69 6c 20 6f 6e 20 41 50 49 73 2e 0a 2a 2a 0a 2a  il on APIs..**.*
2c80: 2a 20 49 66 20 61 6e 20 75 70 64 61 74 65 20 69  * If an update i
2c90: 73 20 6f 6e 6c 79 20 70 61 72 74 69 61 6c 6c 79  s only partially
2ca0: 20 61 70 70 6c 69 65 64 20 74 6f 20 74 68 65 20   applied to the 
2cb0: 74 61 72 67 65 74 20 64 61 74 61 62 61 73 65 20  target database 
2cc0: 62 79 20 74 68 65 0a 2a 2a 20 74 69 6d 65 20 73  by the.** time s
2cd0: 71 6c 69 74 65 33 72 62 75 5f 63 6c 6f 73 65 28  qlite3rbu_close(
2ce0: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 76 61 72  ) is called, var
2cf0: 69 6f 75 73 20 73 74 61 74 65 20 69 6e 66 6f 72  ious state infor
2d00: 6d 61 74 69 6f 6e 20 69 73 20 73 61 76 65 64 20  mation is saved 
2d10: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 52  .** within the R
2d20: 42 55 20 64 61 74 61 62 61 73 65 2e 20 54 68 69  BU database. Thi
2d30: 73 20 61 6c 6c 6f 77 73 20 73 75 62 73 65 71 75  s allows subsequ
2d40: 65 6e 74 20 70 72 6f 63 65 73 73 65 73 20 74 6f  ent processes to
2d50: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2d60: 2a 20 72 65 73 75 6d 65 20 74 68 65 20 52 42 55  * resume the RBU
2d70: 20 75 70 64 61 74 65 20 66 72 6f 6d 20 77 68 65   update from whe
2d80: 72 65 20 69 74 20 6c 65 66 74 20 6f 66 66 2e 0a  re it left off..
2d90: 2a 2a 0a 2a 2a 20 54 6f 20 72 65 6d 6f 76 65 20  **.** To remove 
2da0: 61 6c 6c 20 52 42 55 20 65 78 74 65 6e 73 69 6f  all RBU extensio
2db0: 6e 20 73 74 61 74 65 20 69 6e 66 6f 72 6d 61 74  n state informat
2dc0: 69 6f 6e 2c 20 72 65 74 75 72 6e 69 6e 67 20 61  ion, returning a
2dd0: 6e 20 52 42 55 20 64 61 74 61 62 61 73 65 20 0a  n RBU database .
2de0: 2a 2a 20 74 6f 20 69 74 73 20 6f 72 69 67 69 6e  ** to its origin
2df0: 61 6c 20 63 6f 6e 74 65 6e 74 73 2c 20 69 74 20  al contents, it 
2e00: 69 73 20 73 75 66 66 69 63 69 65 6e 74 20 74 6f  is sufficient to
2e10: 20 64 72 6f 70 20 61 6c 6c 20 74 61 62 6c 65 73   drop all tables
2e20: 20 74 68 61 74 20 62 65 67 69 6e 0a 2a 2a 20 77   that begin.** w
2e30: 69 74 68 20 74 68 65 20 70 72 65 66 69 78 20 22  ith the prefix "
2e40: 72 62 75 5f 22 0a 2a 2a 0a 2a 2a 20 44 41 54 41  rbu_".**.** DATA
2e50: 42 41 53 45 20 4c 4f 43 4b 49 4e 47 0a 2a 2a 0a  BASE LOCKING.**.
2e60: 2a 2a 20 41 6e 20 52 42 55 20 75 70 64 61 74 65  ** An RBU update
2e70: 20 6d 61 79 20 6e 6f 74 20 62 65 20 61 70 70 6c   may not be appl
2e80: 69 65 64 20 74 6f 20 61 20 64 61 74 61 62 61 73  ied to a databas
2e90: 65 20 69 6e 20 57 41 4c 20 6d 6f 64 65 2e 20 41  e in WAL mode. A
2ea0: 74 74 65 6d 70 74 69 6e 67 0a 2a 2a 20 74 6f 20  ttempting.** to 
2eb0: 64 6f 20 73 6f 20 69 73 20 61 6e 20 65 72 72 6f  do so is an erro
2ec0: 72 20 28 53 51 4c 49 54 45 5f 45 52 52 4f 52 29  r (SQLITE_ERROR)
2ed0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 69 6c 65 20 61 6e  ..**.** While an
2ee0: 20 52 42 55 20 68 61 6e 64 6c 65 20 69 73 20 6f   RBU handle is o
2ef0: 70 65 6e 2c 20 61 20 53 48 41 52 45 44 20 6c 6f  pen, a SHARED lo
2f00: 63 6b 20 6d 61 79 20 62 65 20 68 65 6c 64 20 6f  ck may be held o
2f10: 6e 20 74 68 65 20 74 61 72 67 65 74 0a 2a 2a 20  n the target.** 
2f20: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 54  database file. T
2f30: 68 69 73 20 6d 65 61 6e 73 20 69 74 20 69 73 20  his means it is 
2f40: 70 6f 73 73 69 62 6c 65 20 66 6f 72 20 6f 74 68  possible for oth
2f50: 65 72 20 63 6c 69 65 6e 74 73 20 74 6f 20 72 65  er clients to re
2f60: 61 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  ad the.** databa
2f70: 73 65 2c 20 62 75 74 20 6e 6f 74 20 74 6f 20 77  se, but not to w
2f80: 72 69 74 65 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 49  rite it..**.** I
2f90: 66 20 61 6e 20 52 42 55 20 75 70 64 61 74 65 20  f an RBU update 
2fa0: 69 73 20 73 74 61 72 74 65 64 20 61 6e 64 20 74  is started and t
2fb0: 68 65 6e 20 73 75 73 70 65 6e 64 65 64 20 62 65  hen suspended be
2fc0: 66 6f 72 65 20 69 74 20 69 73 20 63 6f 6d 70 6c  fore it is compl
2fd0: 65 74 65 64 2c 0a 2a 2a 20 74 68 65 6e 20 61 6e  eted,.** then an
2fe0: 20 65 78 74 65 72 6e 61 6c 20 63 6c 69 65 6e 74   external client
2ff0: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
3000: 61 74 61 62 61 73 65 2c 20 74 68 65 6e 20 61 74  atabase, then at
3010: 74 65 6d 70 74 69 6e 67 20 74 6f 20 72 65 73 75  tempting to resu
3020: 6d 65 0a 2a 2a 20 74 68 65 20 73 75 73 70 65 6e  me.** the suspen
3030: 64 65 64 20 52 42 55 20 75 70 64 61 74 65 20 69  ded RBU update i
3040: 73 20 61 6c 73 6f 20 61 6e 20 65 72 72 6f 72 20  s also an error 
3050: 28 53 51 4c 49 54 45 5f 42 55 53 59 29 2e 0a 2a  (SQLITE_BUSY)..*
3060: 2f 0a 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  /..#ifndef _SQLI
3070: 54 45 33 52 42 55 5f 48 0a 23 64 65 66 69 6e 65  TE3RBU_H.#define
3080: 20 5f 53 51 4c 49 54 45 33 52 42 55 5f 48 0a 0a   _SQLITE3RBU_H..
3090: 23 69 6e 63 6c 75 64 65 20 22 73 71 6c 69 74 65  #include "sqlite
30a0: 33 2e 68 22 20 20 20 20 20 20 20 20 20 20 20 20  3.h"            
30b0: 20 20 2f 2a 20 52 65 71 75 69 72 65 64 20 66 6f    /* Required fo
30c0: 72 20 65 72 72 6f 72 20 63 6f 64 65 20 64 65 66  r error code def
30d0: 69 6e 69 74 69 6f 6e 73 20 2a 2f 0a 0a 23 69 66  initions */..#if
30e0: 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a  def __cplusplus.
30f0: 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e  extern "C" {.#en
3100: 64 69 66 0a 0a 74 79 70 65 64 65 66 20 73 74 72  dif..typedef str
3110: 75 63 74 20 73 71 6c 69 74 65 33 72 62 75 20 73  uct sqlite3rbu s
3120: 71 6c 69 74 65 33 72 62 75 3b 0a 0a 2f 2a 0a 2a  qlite3rbu;../*.*
3130: 2a 20 4f 70 65 6e 20 61 6e 20 52 42 55 20 68 61  * Open an RBU ha
3140: 6e 64 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 72 67 75  ndle..**.** Argu
3150: 6d 65 6e 74 20 7a 54 61 72 67 65 74 20 69 73 20  ment zTarget is 
3160: 74 68 65 20 70 61 74 68 20 74 6f 20 74 68 65 20  the path to the 
3170: 74 61 72 67 65 74 20 64 61 74 61 62 61 73 65 2e  target database.
3180: 20 41 72 67 75 6d 65 6e 74 20 7a 52 62 75 20 69   Argument zRbu i
3190: 73 0a 2a 2a 20 74 68 65 20 70 61 74 68 20 74 6f  s.** the path to
31a0: 20 74 68 65 20 52 42 55 20 64 61 74 61 62 61 73   the RBU databas
31b0: 65 2e 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  e. Each call to 
31c0: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75  this function mu
31d0: 73 74 20 62 65 20 6d 61 74 63 68 65 64 0a 2a 2a  st be matched.**
31e0: 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 73 71   by a call to sq
31f0: 6c 69 74 65 33 72 62 75 5f 63 6c 6f 73 65 28 29  lite3rbu_close()
3200: 2e 20 57 68 65 6e 20 6f 70 65 6e 69 6e 67 20 74  . When opening t
3210: 68 65 20 64 61 74 61 62 61 73 65 73 2c 20 52 42  he databases, RB
3220: 55 20 70 61 73 73 65 73 0a 2a 2a 20 74 68 65 20  U passes.** the 
3230: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
3240: 49 20 66 6c 61 67 20 74 6f 20 73 71 6c 69 74 65  I flag to sqlite
3250: 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 53 6f 20  3_open_v2(). So 
3260: 69 66 20 65 69 74 68 65 72 20 7a 54 61 72 67 65  if either zTarge
3270: 74 0a 2a 2a 20 6f 72 20 7a 52 62 75 20 62 65 67  t.** or zRbu beg
3280: 69 6e 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  in with "file:",
3290: 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 74 65   it will be inte
32a0: 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 53 51  rpreted as an SQ
32b0: 4c 69 74 65 20 0a 2a 2a 20 64 61 74 61 62 61 73  Lite .** databas
32c0: 65 20 55 52 49 2c 20 6e 6f 74 20 61 20 72 65 67  e URI, not a reg
32d0: 75 6c 61 72 20 66 69 6c 65 20 6e 61 6d 65 2e 0a  ular file name..
32e0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 7a 53 74  **.** If the zSt
32f0: 61 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ate argument is 
3300: 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 76 61  passed a NULL va
3310: 6c 75 65 2c 20 74 68 65 20 52 42 55 20 65 78 74  lue, the RBU ext
3320: 65 6e 73 69 6f 6e 20 73 74 6f 72 65 73 20 0a 2a  ension stores .*
3330: 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  * the current st
3340: 61 74 65 20 6f 66 20 74 68 65 20 75 70 64 61 74  ate of the updat
3350: 65 20 28 68 6f 77 20 6d 61 6e 79 20 72 6f 77 73  e (how many rows
3360: 20 68 61 76 65 20 62 65 65 6e 20 75 70 64 61 74   have been updat
3370: 65 64 2c 20 77 68 69 63 68 20 0a 2a 2a 20 69 6e  ed, which .** in
3380: 64 65 78 65 73 20 61 72 65 20 79 65 74 20 74 6f  dexes are yet to
3390: 20 62 65 20 75 70 64 61 74 65 64 20 65 74 63 2e   be updated etc.
33a0: 29 20 77 69 74 68 69 6e 20 74 68 65 20 52 42 55  ) within the RBU
33b0: 20 64 61 74 61 62 61 73 65 20 69 74 73 65 6c 66   database itself
33c0: 2e 20 54 68 69 73 0a 2a 2a 20 63 61 6e 20 62 65  . This.** can be
33d0: 20 63 6f 6e 76 65 6e 69 65 6e 74 2c 20 61 73 20   convenient, as 
33e0: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
33f0: 65 20 52 42 55 20 61 70 70 6c 69 63 61 74 69 6f  e RBU applicatio
3400: 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
3410: 74 6f 0a 2a 2a 20 6f 72 67 61 6e 69 7a 65 20 72  to.** organize r
3420: 65 6d 6f 76 69 6e 67 20 61 20 73 65 70 61 72 61  emoving a separa
3430: 74 65 20 73 74 61 74 65 20 66 69 6c 65 20 61 66  te state file af
3440: 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 69  ter the update i
3450: 73 20 63 6f 6e 63 6c 75 64 65 64 2e 20 0a 2a 2a  s concluded. .**
3460: 20 4f 72 2c 20 69 66 20 7a 53 74 61 74 65 20 69   Or, if zState i
3470: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2c 20 69 74 20 6d  s non-NULL, it m
3480: 75 73 74 20 62 65 20 61 20 70 61 74 68 20 74 6f  ust be a path to
3490: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
34a0: 20 69 6e 20 77 68 69 63 68 20 0a 2a 2a 20 74 68   in which .** th
34b0: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
34c0: 63 61 6e 20 73 74 6f 72 65 20 74 68 65 20 73 74  can store the st
34d0: 61 74 65 20 6f 66 20 74 68 65 20 75 70 64 61 74  ate of the updat
34e0: 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 72 65  e..**.** When re
34f0: 73 75 6d 69 6e 67 20 61 6e 20 52 42 55 20 75 70  suming an RBU up
3500: 64 61 74 65 2c 20 74 68 65 20 7a 53 74 61 74 65  date, the zState
3510: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
3520: 65 20 70 61 73 73 65 64 20 74 68 65 20 73 61 6d  e passed the sam
3530: 65 0a 2a 2a 20 76 61 6c 75 65 20 61 73 20 77 68  e.** value as wh
3540: 65 6e 20 74 68 65 20 52 42 55 20 75 70 64 61 74  en the RBU updat
3550: 65 20 77 61 73 20 73 74 61 72 74 65 64 2e 0a 2a  e was started..*
3560: 2a 0a 2a 2a 20 4f 6e 63 65 20 74 68 65 20 52 42  *.** Once the RB
3570: 55 20 75 70 64 61 74 65 20 69 73 20 66 69 6e 69  U update is fini
3580: 73 68 65 64 2c 20 74 68 65 20 52 42 55 20 65 78  shed, the RBU ex
3590: 74 65 6e 73 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  tension does not
35a0: 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c   .** automatical
35b0: 6c 79 20 72 65 6d 6f 76 65 20 61 6e 79 20 7a 53  ly remove any zS
35c0: 74 61 74 65 20 64 61 74 61 62 61 73 65 20 66 69  tate database fi
35d0: 6c 65 2c 20 65 76 65 6e 20 69 66 20 69 74 20 63  le, even if it c
35e0: 72 65 61 74 65 64 20 69 74 2e 0a 2a 2a 0a 2a 2a  reated it..**.**
35f0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 52 42 55   By default, RBU
3600: 20 75 73 65 73 20 74 68 65 20 64 65 66 61 75 6c   uses the defaul
3610: 74 20 56 46 53 20 74 6f 20 61 63 63 65 73 73 20  t VFS to access 
3620: 74 68 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  the files on dis
3630: 6b 2e 20 54 6f 0a 2a 2a 20 75 73 65 20 61 20 56  k. To.** use a V
3640: 46 53 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68  FS other than th
3650: 65 20 64 65 66 61 75 6c 74 2c 20 61 6e 20 53 51  e default, an SQ
3660: 4c 69 74 65 20 22 66 69 6c 65 3a 22 20 55 52 49  Lite "file:" URI
3670: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 0a 2a 2a   containing a.**
3680: 20 22 76 66 73 3d 2e 2e 2e 22 20 6f 70 74 69 6f   "vfs=..." optio
3690: 6e 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 20  n may be passed 
36a0: 61 73 20 74 68 65 20 7a 54 61 72 67 65 74 20 6f  as the zTarget o
36b0: 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4d 50  ption..**.** IMP
36c0: 4f 52 54 41 4e 54 20 4e 4f 54 45 20 46 4f 52 20  ORTANT NOTE FOR 
36d0: 5a 49 50 56 46 53 20 55 53 45 52 53 3a 20 54 68  ZIPVFS USERS: Th
36e0: 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20  e RBU extension 
36f0: 77 6f 72 6b 73 20 77 69 74 68 20 61 6c 6c 20 6f  works with all o
3700: 66 0a 2a 2a 20 53 51 4c 69 74 65 27 73 20 62 75  f.** SQLite's bu
3710: 69 6c 74 2d 69 6e 20 56 46 53 73 2c 20 69 6e 63  ilt-in VFSs, inc
3720: 6c 75 64 69 6e 67 20 74 68 65 20 6d 75 6c 74 69  luding the multi
3730: 70 6c 65 78 6f 72 20 56 46 53 2e 20 48 6f 77 65  plexor VFS. Howe
3740: 76 65 72 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e  ver it does.** n
3750: 6f 74 20 77 6f 72 6b 20 6f 75 74 20 6f 66 20 74  ot work out of t
3760: 68 65 20 62 6f 78 20 77 69 74 68 20 7a 69 70 76  he box with zipv
3770: 66 73 2e 20 52 65 66 65 72 20 74 6f 20 74 68 65  fs. Refer to the
3780: 20 63 6f 6d 6d 65 6e 74 20 64 65 73 63 72 69 62   comment describ
3790: 69 6e 67 0a 2a 2a 20 74 68 65 20 7a 69 70 76 66  ing.** the zipvf
37a0: 73 5f 63 72 65 61 74 65 5f 76 66 73 28 29 20 41  s_create_vfs() A
37b0: 50 49 20 62 65 6c 6f 77 20 66 6f 72 20 64 65 74  PI below for det
37c0: 61 69 6c 73 20 6f 6e 20 75 73 69 6e 67 20 52 42  ails on using RB
37d0: 55 20 77 69 74 68 20 7a 69 70 76 66 73 2e 0a 2a  U with zipvfs..*
37e0: 2f 0a 73 71 6c 69 74 65 33 72 62 75 20 2a 73 71  /.sqlite3rbu *sq
37f0: 6c 69 74 65 33 72 62 75 5f 6f 70 65 6e 28 0a 20  lite3rbu_open(. 
3800: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
3810: 72 67 65 74 2c 20 0a 20 20 63 6f 6e 73 74 20 63  rget, .  const c
3820: 68 61 72 20 2a 7a 52 62 75 2c 0a 20 20 63 6f 6e  har *zRbu,.  con
3830: 73 74 20 63 68 61 72 20 2a 7a 53 74 61 74 65 0a  st char *zState.
3840: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 4f 70 65 6e 20 61  );../*.** Open a
3850: 6e 20 52 42 55 20 68 61 6e 64 6c 65 20 74 6f 20  n RBU handle to 
3860: 70 65 72 66 6f 72 6d 20 61 6e 20 52 42 55 20 76  perform an RBU v
3870: 61 63 75 75 6d 20 6f 6e 20 64 61 74 61 62 61 73  acuum on databas
3880: 65 20 66 69 6c 65 20 7a 54 61 72 67 65 74 2e 0a  e file zTarget..
3890: 2a 2a 20 41 6e 20 52 42 55 20 76 61 63 75 75 6d  ** An RBU vacuum
38a0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 53   is similar to S
38b0: 51 4c 69 74 65 27 73 20 62 75 69 6c 74 2d 69 6e  QLite's built-in
38c0: 20 56 41 43 55 55 4d 20 63 6f 6d 6d 61 6e 64 2c   VACUUM command,
38d0: 20 65 78 63 65 70 74 0a 2a 2a 20 74 68 61 74 20   except.** that 
38e0: 69 74 20 63 61 6e 20 62 65 20 73 75 73 70 65 6e  it can be suspen
38f0: 64 65 64 20 61 6e 64 20 72 65 73 75 6d 65 64 20  ded and resumed 
3900: 6c 69 6b 65 20 61 6e 20 52 42 55 20 75 70 64 61  like an RBU upda
3910: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  te..**.** The se
3920: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
3930: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   this function i
3940: 64 65 6e 74 69 66 69 65 73 20 61 20 64 61 74 61  dentifies a data
3950: 62 61 73 65 20 69 6e 20 77 68 69 63 68 20 0a 2a  base in which .*
3960: 2a 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 73  * to store the s
3970: 74 61 74 65 20 6f 66 20 74 68 65 20 52 42 55 20  tate of the RBU 
3980: 76 61 63 75 75 6d 20 6f 70 65 72 61 74 69 6f 6e  vacuum operation
3990: 20 69 66 20 69 74 20 69 73 20 73 75 73 70 65 6e   if it is suspen
39a0: 64 65 64 2e 20 54 68 65 20 0a 2a 2a 20 66 69 72  ded. The .** fir
39b0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 72  st time sqlite3r
39c0: 62 75 5f 76 61 63 75 75 6d 28 29 20 69 73 20 63  bu_vacuum() is c
39d0: 61 6c 6c 65 64 2c 20 74 6f 20 73 74 61 72 74 20  alled, to start 
39e0: 61 6e 20 52 42 55 20 76 61 63 75 75 6d 0a 2a 2a  an RBU vacuum.**
39f0: 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 20   operation, the 
3a00: 73 74 61 74 65 20 64 61 74 61 62 61 73 65 20 73  state database s
3a10: 68 6f 75 6c 64 20 65 69 74 68 65 72 20 6e 6f 74  hould either not
3a20: 20 65 78 69 73 74 20 6f 72 20 62 65 20 65 6d 70   exist or be emp
3a30: 74 79 0a 2a 2a 20 28 63 6f 6e 74 61 69 6e 20 6e  ty.** (contain n
3a40: 6f 20 74 61 62 6c 65 73 29 2e 20 49 66 20 61 6e  o tables). If an
3a50: 20 52 42 55 20 76 61 63 75 75 6d 20 69 73 20 73   RBU vacuum is s
3a60: 75 73 70 65 6e 64 65 64 20 62 79 20 63 61 6c 6c  uspended by call
3a70: 69 6e 67 20 0a 2a 2a 20 73 71 6c 69 74 65 33 72  ing .** sqlite3r
3a80: 62 75 5f 63 6c 6f 73 65 28 29 20 6f 6e 20 74 68  bu_close() on th
3a90: 65 20 52 42 55 20 68 61 6e 64 6c 65 20 62 65 66  e RBU handle bef
3aa0: 6f 72 65 20 73 71 6c 69 74 65 33 72 62 75 5f 73  ore sqlite3rbu_s
3ab0: 74 65 70 28 29 20 68 61 73 0a 2a 2a 20 72 65 74  tep() has.** ret
3ac0: 75 72 6e 65 64 20 53 51 4c 49 54 45 5f 44 4f 4e  urned SQLITE_DON
3ad0: 45 2c 20 74 68 65 20 76 61 63 75 75 6d 20 73 74  E, the vacuum st
3ae0: 61 74 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ate is stored in
3af0: 20 74 68 65 20 73 74 61 74 65 20 64 61 74 61 62   the state datab
3b00: 61 73 65 2e 20 0a 2a 2a 20 54 68 65 20 76 61 63  ase. .** The vac
3b10: 75 75 6d 20 63 61 6e 20 62 65 20 72 65 73 75 6d  uum can be resum
3b20: 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ed by calling th
3b30: 69 73 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 6f  is function to o
3b40: 70 65 6e 20 61 20 6e 65 77 20 52 42 55 0a 2a 2a  pen a new RBU.**
3b50: 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 79 69   handle specifyi
3b60: 6e 67 20 74 68 65 20 73 61 6d 65 20 74 61 72 67  ng the same targ
3b70: 65 74 20 61 6e 64 20 73 74 61 74 65 20 64 61 74  et and state dat
3b80: 61 62 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  abases..**.** If
3b90: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
3ba0: 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 20 74  ment passed to t
3bb0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
3bc0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a  NULL, then the.*
3bd0: 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 73 74  * name of the st
3be0: 61 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ate database is 
3bf0: 22 3c 64 61 74 61 62 61 73 65 3e 2d 76 61 63 75  "<database>-vacu
3c00: 75 6d 22 2c 20 77 68 65 72 65 20 3c 64 61 74 61  um", where <data
3c10: 62 61 73 65 3e 0a 2a 2a 20 69 73 20 74 68 65 20  base>.** is the 
3c20: 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 72 67  name of the targ
3c30: 65 74 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  et database file
3c40: 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20  . In this case, 
3c50: 6f 6e 20 55 4e 49 58 2c 20 69 66 20 74 68 65 0a  on UNIX, if the.
3c60: 2a 2a 20 73 74 61 74 65 20 64 61 74 61 62 61 73  ** state databas
3c70: 65 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  e is not already
3c80: 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 20   present in the 
3c90: 66 69 6c 65 2d 73 79 73 74 65 6d 2c 20 69 74 20  file-system, it 
3ca0: 69 73 20 63 72 65 61 74 65 64 0a 2a 2a 20 77 69  is created.** wi
3cb0: 74 68 20 74 68 65 20 73 61 6d 65 20 70 65 72 6d  th the same perm
3cc0: 69 73 73 69 6f 6e 73 20 61 73 20 74 68 65 20 74  issions as the t
3cd0: 61 72 67 65 74 20 64 62 20 69 73 20 6d 61 64 65  arget db is made
3ce0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
3cf0: 63 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 64  ction does not d
3d00: 65 6c 65 74 65 20 74 68 65 20 73 74 61 74 65 20  elete the state 
3d10: 64 61 74 61 62 61 73 65 20 61 66 74 65 72 20 61  database after a
3d20: 6e 20 52 42 55 20 76 61 63 75 75 6d 0a 2a 2a 20  n RBU vacuum.** 
3d30: 69 73 20 63 6f 6d 70 6c 65 74 65 64 2c 20 65 76  is completed, ev
3d40: 65 6e 20 69 66 20 69 74 20 63 72 65 61 74 65 64  en if it created
3d50: 20 69 74 2e 20 48 6f 77 65 76 65 72 2c 20 69 66   it. However, if
3d60: 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
3d70: 73 71 6c 69 74 65 33 72 62 75 5f 63 6c 6f 73 65  sqlite3rbu_close
3d80: 28 29 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76  () returns any v
3d90: 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
3da0: 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 20 63  SQLITE_OK, the c
3db0: 6f 6e 74 65 6e 74 73 0a 2a 2a 20 6f 66 20 74 68  ontents.** of th
3dc0: 65 20 73 74 61 74 65 20 74 61 62 6c 65 73 20 77  e state tables w
3dd0: 69 74 68 69 6e 20 74 68 65 20 73 74 61 74 65 20  ithin the state 
3de0: 64 61 74 61 62 61 73 65 20 61 72 65 20 7a 65 72  database are zer
3df0: 6f 65 64 2e 20 54 68 69 73 20 77 61 79 2c 0a 2a  oed. This way,.*
3e00: 2a 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  * the next call 
3e10: 74 6f 20 73 71 6c 69 74 65 33 72 62 75 5f 76 61  to sqlite3rbu_va
3e20: 63 75 75 6d 28 29 20 6f 70 65 6e 73 20 61 20 68  cuum() opens a h
3e30: 61 6e 64 6c 65 20 74 68 61 74 20 73 74 61 72 74  andle that start
3e40: 73 20 61 20 0a 2a 2a 20 6e 65 77 20 52 42 55 20  s a .** new RBU 
3e50: 76 61 63 75 75 6d 20 6f 70 65 72 61 74 69 6f 6e  vacuum operation
3e60: 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20  ..**.** As with 
3e70: 73 71 6c 69 74 65 33 72 62 75 5f 6f 70 65 6e 28  sqlite3rbu_open(
3e80: 29 2c 20 5a 69 70 76 66 73 20 75 73 65 72 73 20  ), Zipvfs users 
3e90: 73 68 6f 75 6c 64 20 72 65 76 65 72 20 74 6f 20  should rever to 
3ea0: 74 68 65 20 63 6f 6d 6d 65 6e 74 0a 2a 2a 20 64  the comment.** d
3eb0: 65 73 63 72 69 62 69 6e 67 20 74 68 65 20 73 71  escribing the sq
3ec0: 6c 69 74 65 33 72 62 75 5f 63 72 65 61 74 65 5f  lite3rbu_create_
3ed0: 76 66 73 28 29 20 41 50 49 20 66 75 6e 63 74 69  vfs() API functi
3ee0: 6f 6e 20 62 65 6c 6f 77 20 66 6f 72 20 0a 2a 2a  on below for .**
3ef0: 20 61 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f   a description o
3f00: 66 20 74 68 65 20 63 6f 6d 70 6c 69 63 61 74 69  f the complicati
3f10: 6f 6e 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  ons associated w
3f20: 69 74 68 20 75 73 69 6e 67 20 52 42 55 20 77 69  ith using RBU wi
3f30: 74 68 20 0a 2a 2a 20 7a 69 70 76 66 73 20 64 61  th .** zipvfs da
3f40: 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 73 71 6c 69  tabases..*/.sqli
3f50: 74 65 33 72 62 75 20 2a 73 71 6c 69 74 65 33 72  te3rbu *sqlite3r
3f60: 62 75 5f 76 61 63 75 75 6d 28 0a 20 20 63 6f 6e  bu_vacuum(.  con
3f70: 73 74 20 63 68 61 72 20 2a 7a 54 61 72 67 65 74  st char *zTarget
3f80: 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
3f90: 2a 7a 53 74 61 74 65 0a 29 3b 0a 0a 2f 2a 0a 2a  *zState.);../*.*
3fa0: 2a 20 49 6e 74 65 72 6e 61 6c 6c 79 2c 20 65 61  * Internally, ea
3fb0: 63 68 20 52 42 55 20 63 6f 6e 6e 65 63 74 69 6f  ch RBU connectio
3fc0: 6e 20 75 73 65 73 20 61 20 73 65 70 61 72 61 74  n uses a separat
3fd0: 65 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  e SQLite databas
3fe0: 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
3ff0: 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 74   to access the t
4000: 61 72 67 65 74 20 61 6e 64 20 72 62 75 20 75 70  arget and rbu up
4010: 64 61 74 65 20 64 61 74 61 62 61 73 65 73 2e 20  date databases. 
4020: 54 68 69 73 0a 2a 2a 20 41 50 49 20 61 6c 6c 6f  This.** API allo
4030: 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ws the applicati
4040: 6f 6e 20 64 69 72 65 63 74 20 61 63 63 65 73 73  on direct access
4050: 20 74 6f 20 74 68 65 73 65 20 64 61 74 61 62 61   to these databa
4060: 73 65 20 68 61 6e 64 6c 65 73 2e 0a 2a 2a 0a 2a  se handles..**.*
4070: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
4080: 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 20 74  ment passed to t
4090: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  his function mus
40a0: 74 20 62 65 20 61 20 76 61 6c 69 64 2c 20 6f 70  t be a valid, op
40b0: 65 6e 2c 20 52 42 55 0a 2a 2a 20 68 61 6e 64 6c  en, RBU.** handl
40c0: 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  e. The second ar
40d0: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
40e0: 20 70 61 73 73 65 64 20 7a 65 72 6f 20 74 6f 20   passed zero to 
40f0: 61 63 63 65 73 73 20 74 68 65 20 74 61 72 67 65  access the targe
4100: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61  t.** database ha
4110: 6e 64 6c 65 2c 20 6f 72 20 6e 6f 6e 2d 7a 65 72  ndle, or non-zer
4120: 6f 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  o to access the 
4130: 72 62 75 20 75 70 64 61 74 65 20 64 61 74 61 62  rbu update datab
4140: 61 73 65 20 68 61 6e 64 6c 65 2e 0a 2a 2a 20 41  ase handle..** A
4150: 63 63 65 73 73 69 6e 67 20 74 68 65 20 75 6e 64  ccessing the und
4160: 65 72 6c 79 69 6e 67 20 64 61 74 61 62 61 73 65  erlying database
4170: 20 68 61 6e 64 6c 65 73 20 6d 61 79 20 62 65 20   handles may be 
4180: 75 73 65 66 75 6c 20 69 6e 20 74 68 65 0a 2a 2a  useful in the.**
4190: 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 63 65 6e 61   following scena
41a0: 72 69 6f 73 3a 0a 2a 2a 0a 2a 2a 20 20 20 2a 20  rios:.**.**   * 
41b0: 49 66 20 61 6e 79 20 74 61 72 67 65 74 20 74 61  If any target ta
41c0: 62 6c 65 73 20 61 72 65 20 76 69 72 74 75 61 6c  bles are virtual
41d0: 20 74 61 62 6c 65 73 2c 20 69 74 20 6d 61 79 20   tables, it may 
41e0: 62 65 20 6e 65 63 65 73 73 61 72 79 20 74 6f 0a  be necessary to.
41f0: 2a 2a 20 20 20 20 20 63 61 6c 6c 20 73 71 6c 69  **     call sqli
4200: 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
4210: 65 28 29 20 6f 6e 20 74 68 65 20 74 61 72 67 65  e() on the targe
4220: 74 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  t database handl
4230: 65 20 74 6f 20 0a 2a 2a 20 20 20 20 20 72 65 67  e to .**     reg
4240: 69 73 74 65 72 20 74 68 65 20 72 65 71 75 69 72  ister the requir
4250: 65 64 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ed virtual table
4260: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
4270: 2e 0a 2a 2a 0a 2a 2a 20 20 20 2a 20 49 66 20 74  ..**.**   * If t
4280: 68 65 20 64 61 74 61 5f 78 78 78 20 74 61 62 6c  he data_xxx tabl
4290: 65 73 20 69 6e 20 74 68 65 20 52 42 55 20 73 6f  es in the RBU so
42a0: 75 72 63 65 20 64 61 74 61 62 61 73 65 20 61 72  urce database ar
42b0: 65 20 76 69 72 74 75 61 6c 20 0a 2a 2a 20 20 20  e virtual .**   
42c0: 20 20 74 61 62 6c 65 73 2c 20 74 68 65 20 61 70    tables, the ap
42d0: 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 6e 65  plication may ne
42e0: 65 64 20 74 6f 20 63 61 6c 6c 20 73 71 6c 69 74  ed to call sqlit
42f0: 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
4300: 28 29 20 6f 6e 0a 2a 2a 20 20 20 20 20 74 68 65  () on.**     the
4310: 20 72 62 75 20 75 70 64 61 74 65 20 64 62 20 68   rbu update db h
4320: 61 6e 64 6c 65 20 74 6f 20 61 6e 79 20 72 65 71  andle to any req
4330: 75 69 72 65 64 20 76 69 72 74 75 61 6c 20 74 61  uired virtual ta
4340: 62 6c 65 0a 2a 2a 20 20 20 20 20 69 6d 70 6c 65  ble.**     imple
4350: 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  mentations..**.*
4360: 2a 20 20 20 2a 20 49 66 20 74 68 65 20 61 70 70  *   * If the app
4370: 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 74 68  lication uses th
4380: 65 20 22 72 62 75 5f 64 65 6c 74 61 28 29 22 20  e "rbu_delta()" 
4390: 66 65 61 74 75 72 65 20 64 65 73 63 72 69 62 65  feature describe
43a0: 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 20 20 20 20  d above,.**     
43b0: 69 74 20 6d 75 73 74 20 75 73 65 20 73 71 6c 69  it must use sqli
43c0: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
43d0: 69 6f 6e 28 29 20 6f 72 20 73 69 6d 69 6c 61 72  ion() or similar
43e0: 20 74 6f 20 72 65 67 69 73 74 65 72 20 74 68 65   to register the
43f0: 0a 2a 2a 20 20 20 20 20 72 62 75 5f 64 65 6c 74  .**     rbu_delt
4400: 61 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  a() implementati
4410: 6f 6e 20 77 69 74 68 20 74 68 65 20 74 61 72 67  on with the targ
4420: 65 74 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  et database hand
4430: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  le..**.** If an 
4440: 65 72 72 6f 72 20 68 61 73 20 6f 63 63 75 72 72  error has occurr
4450: 65 64 2c 20 65 69 74 68 65 72 20 77 68 69 6c 65  ed, either while
4460: 20 6f 70 65 6e 69 6e 67 20 6f 72 20 73 74 65 70   opening or step
4470: 70 69 6e 67 20 74 68 65 20 52 42 55 20 6f 62 6a  ping the RBU obj
4480: 65 63 74 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e  ect,.** this fun
4490: 63 74 69 6f 6e 20 6d 61 79 20 72 65 74 75 72 6e  ction may return
44a0: 20 4e 55 4c 4c 2e 20 54 68 65 20 65 72 72 6f 72   NULL. The error
44b0: 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
44c0: 65 20 6d 61 79 20 62 65 20 63 6f 6c 6c 65 63 74  e may be collect
44d0: 65 64 0a 2a 2a 20 77 68 65 6e 20 73 71 6c 69 74  ed.** when sqlit
44e0: 65 33 72 62 75 5f 63 6c 6f 73 65 28 29 20 69 73  e3rbu_close() is
44f0: 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 44   called..**.** D
4500: 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 73 20  atabase handles 
4510: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
4520: 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e   function remain
4530: 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
4540: 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
4550: 20 61 6e 79 20 73 71 6c 69 74 65 33 72 62 75 5f   any sqlite3rbu_
4560: 78 78 78 28 29 20 66 75 6e 63 74 69 6f 6e 20 6f  xxx() function o
4570: 74 68 65 72 20 74 68 61 6e 20 73 71 6c 69 74 65  ther than sqlite
4580: 33 72 62 75 5f 64 62 28 29 2e 0a 2a 2f 0a 73 71  3rbu_db()..*/.sq
4590: 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 72 62  lite3 *sqlite3rb
45a0: 75 5f 64 62 28 73 71 6c 69 74 65 33 72 62 75 2a  u_db(sqlite3rbu*
45b0: 2c 20 69 6e 74 20 62 52 62 75 29 3b 0a 0a 2f 2a  , int bRbu);../*
45c0: 0a 2a 2a 20 44 6f 20 73 6f 6d 65 20 77 6f 72 6b  .** Do some work
45d0: 20 74 6f 77 61 72 64 73 20 61 70 70 6c 79 69 6e   towards applyin
45e0: 67 20 74 68 65 20 52 42 55 20 75 70 64 61 74 65  g the RBU update
45f0: 20 74 6f 20 74 68 65 20 74 61 72 67 65 74 20 64   to the target d
4600: 62 2e 20 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  b. .**.** Return
4610: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 69 66 20   SQLITE_DONE if 
4620: 74 68 65 20 75 70 64 61 74 65 20 68 61 73 20 62  the update has b
4630: 65 65 6e 20 63 6f 6d 70 6c 65 74 65 6c 79 20 61  een completely a
4640: 70 70 6c 69 65 64 2c 20 6f 72 20 0a 2a 2a 20 53  pplied, or .** S
4650: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 6e 6f 20 65  QLITE_OK if no e
4660: 72 72 6f 72 20 6f 63 63 75 72 73 20 62 75 74 20  rror occurs but 
4670: 74 68 65 72 65 20 72 65 6d 61 69 6e 73 20 77 6f  there remains wo
4680: 72 6b 20 74 6f 20 64 6f 20 74 6f 20 61 70 70 6c  rk to do to appl
4690: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 75 70 64  y.** the RBU upd
46a0: 61 74 65 2e 20 49 66 20 61 6e 20 65 72 72 6f 72  ate. If an error
46b0: 20 64 6f 65 73 20 6f 63 63 75 72 2c 20 73 6f 6d   does occur, som
46c0: 65 20 6f 74 68 65 72 20 65 72 72 6f 72 20 63 6f  e other error co
46d0: 64 65 20 69 73 20 0a 2a 2a 20 72 65 74 75 72 6e  de is .** return
46e0: 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65 20  ed. .**.** Once 
46f0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
4700: 33 72 62 75 5f 73 74 65 70 28 29 20 68 61 73 20  3rbu_step() has 
4710: 72 65 74 75 72 6e 65 64 20 61 20 76 61 6c 75 65  returned a value
4720: 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 53   other than.** S
4730: 51 4c 49 54 45 5f 4f 4b 2c 20 61 6c 6c 20 73 75  QLITE_OK, all su
4740: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 6f  bsequent calls o
4750: 6e 20 74 68 65 20 73 61 6d 65 20 52 42 55 20 68  n the same RBU h
4760: 61 6e 64 6c 65 20 61 72 65 20 6e 6f 2d 6f 70 73  andle are no-ops
4770: 0a 2a 2a 20 74 68 61 74 20 69 6d 6d 65 64 69 61  .** that immedia
4780: 74 65 6c 79 20 72 65 74 75 72 6e 20 74 68 65 20  tely return the 
4790: 73 61 6d 65 20 76 61 6c 75 65 2e 0a 2a 2f 0a 69  same value..*/.i
47a0: 6e 74 20 73 71 6c 69 74 65 33 72 62 75 5f 73 74  nt sqlite3rbu_st
47b0: 65 70 28 73 71 6c 69 74 65 33 72 62 75 20 2a 70  ep(sqlite3rbu *p
47c0: 52 62 75 29 3b 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72  Rbu);../*.** For
47d0: 63 65 20 52 42 55 20 74 6f 20 73 61 76 65 20 69  ce RBU to save i
47e0: 74 73 20 73 74 61 74 65 20 74 6f 20 64 69 73 6b  ts state to disk
47f0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 70 6f 77  ..**.** If a pow
4800: 65 72 20 66 61 69 6c 75 72 65 20 6f 72 20 61 70  er failure or ap
4810: 70 6c 69 63 61 74 69 6f 6e 20 63 72 61 73 68 20  plication crash 
4820: 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 6e  occurs during an
4830: 20 75 70 64 61 74 65 2c 20 66 6f 6c 6c 6f 77 69   update, followi
4840: 6e 67 0a 2a 2a 20 73 79 73 74 65 6d 20 72 65 63  ng.** system rec
4850: 6f 76 65 72 79 20 52 42 55 20 6d 61 79 20 72 65  overy RBU may re
4860: 73 75 6d 65 20 74 68 65 20 75 70 64 61 74 65 20  sume the update 
4870: 66 72 6f 6d 20 74 68 65 20 70 6f 69 6e 74 20 61  from the point a
4880: 74 20 77 68 69 63 68 20 74 68 65 20 73 74 61 74  t which the stat
4890: 65 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 73 61  e.** was last sa
48a0: 76 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  ved. In other wo
48b0: 72 64 73 2c 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rds, from the mo
48c0: 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
48d0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a  sful call to .**
48e0: 20 73 71 6c 69 74 65 33 72 62 75 5f 63 6c 6f 73   sqlite3rbu_clos
48f0: 65 28 29 20 6f 72 20 74 68 69 73 20 66 75 6e 63  e() or this func
4900: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 49  tion..**.** SQLI
4910: 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
4920: 64 20 69 66 20 73 75 63 63 65 73 73 66 75 6c 2c  d if successful,
4930: 20 6f 72 20 61 6e 20 53 51 4c 69 74 65 20 65 72   or an SQLite er
4940: 72 6f 72 20 63 6f 64 65 20 6f 74 68 65 72 77 69  ror code otherwi
4950: 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  se..*/.int sqlit
4960: 65 33 72 62 75 5f 73 61 76 65 73 74 61 74 65 28  e3rbu_savestate(
4970: 73 71 6c 69 74 65 33 72 62 75 20 2a 70 52 62 75  sqlite3rbu *pRbu
4980: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 6c 6f 73 65 20  );../*.** Close 
4990: 61 6e 20 52 42 55 20 68 61 6e 64 6c 65 2e 20 0a  an RBU handle. .
49a0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 52 42 55  **.** If the RBU
49b0: 20 75 70 64 61 74 65 20 68 61 73 20 62 65 65 6e   update has been
49c0: 20 63 6f 6d 70 6c 65 74 65 6c 79 20 61 70 70 6c   completely appl
49d0: 69 65 64 2c 20 6d 61 72 6b 20 74 68 65 20 52 42  ied, mark the RB
49e0: 55 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 61 73  U database.** as
49f0: 20 66 75 6c 6c 79 20 61 70 70 6c 69 65 64 2e 20   fully applied. 
4a00: 4f 74 68 65 72 77 69 73 65 2c 20 61 73 73 75 6d  Otherwise, assum
4a10: 69 6e 67 20 6e 6f 20 65 72 72 6f 72 20 68 61 73  ing no error has
4a20: 20 6f 63 63 75 72 72 65 64 2c 20 73 61 76 65 20   occurred, save 
4a30: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 73  the.** current s
4a40: 74 61 74 65 20 6f 66 20 74 68 65 20 52 42 55 20  tate of the RBU 
4a50: 75 70 64 61 74 65 20 61 70 70 6c 69 61 74 69 6f  update appliatio
4a60: 6e 20 74 6f 20 74 68 65 20 52 42 55 20 64 61 74  n to the RBU dat
4a70: 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  abase..**.** If 
4a80: 61 6e 20 65 72 72 6f 72 20 68 61 73 20 61 6c 72  an error has alr
4a90: 65 61 64 79 20 6f 63 63 75 72 72 65 64 20 61 73  eady occurred as
4aa0: 20 70 61 72 74 20 6f 66 20 61 6e 20 73 71 6c 69   part of an sqli
4ab0: 74 65 33 72 62 75 5f 73 74 65 70 28 29 0a 2a 2a  te3rbu_step().**
4ac0: 20 6f 72 20 73 71 6c 69 74 65 33 72 62 75 5f 6f   or sqlite3rbu_o
4ad0: 70 65 6e 28 29 20 63 61 6c 6c 2c 20 6f 72 20 69  pen() call, or i
4ae0: 66 20 6f 6e 65 20 6f 63 63 75 72 73 20 77 69 74  f one occurs wit
4af0: 68 69 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f  hin this functio
4b00: 6e 2c 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  n, an.** SQLite 
4b10: 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
4b20: 74 75 72 6e 65 64 2e 20 41 64 64 69 74 69 6f 6e  turned. Addition
4b30: 61 6c 6c 79 2c 20 2a 70 7a 45 72 72 6d 73 67 20  ally, *pzErrmsg 
4b40: 6d 61 79 20 62 65 20 73 65 74 20 74 6f 0a 2a 2a  may be set to.**
4b50: 20 70 6f 69 6e 74 20 74 6f 20 61 20 62 75 66 66   point to a buff
4b60: 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20  er containing a 
4b70: 75 74 66 2d 38 20 66 6f 72 6d 61 74 74 65 64 20  utf-8 formatted 
4b80: 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
4b90: 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
4ba0: 65 2e 20 49 74 20 69 73 20 74 68 65 20 72 65 73  e. It is the res
4bb0: 70 6f 6e 73 69 62 69 6c 69 74 79 20 6f 66 20 74  ponsibility of t
4bc0: 68 65 20 63 61 6c 6c 65 72 20 74 6f 20 65 76 65  he caller to eve
4bd0: 6e 74 75 61 6c 6c 79 20 66 72 65 65 20 61 6e 79  ntually free any
4be0: 20 0a 2a 2a 20 73 75 63 68 20 62 75 66 66 65 72   .** such buffer
4bf0: 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66   using sqlite3_f
4c00: 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 4f 74 68  ree()..**.** Oth
4c10: 65 72 77 69 73 65 2c 20 69 66 20 6e 6f 20 65 72  erwise, if no er
4c20: 72 6f 72 20 6f 63 63 75 72 73 2c 20 74 68 69 73  ror occurs, this
4c30: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
4c40: 73 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 74  s SQLITE_OK if t
4c50: 68 65 0a 2a 2a 20 75 70 64 61 74 65 20 68 61 73  he.** update has
4c60: 20 62 65 65 6e 20 70 61 72 74 69 61 6c 6c 79 20   been partially 
4c70: 61 70 70 6c 69 65 64 2c 20 6f 72 20 53 51 4c 49  applied, or SQLI
4c80: 54 45 5f 44 4f 4e 45 20 69 66 20 69 74 20 68 61  TE_DONE if it ha
4c90: 73 20 62 65 65 6e 20 0a 2a 2a 20 63 6f 6d 70 6c  s been .** compl
4ca0: 65 74 65 6c 79 20 61 70 70 6c 69 65 64 2e 0a 2a  etely applied..*
4cb0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 72 62 75  /.int sqlite3rbu
4cc0: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 72 62  _close(sqlite3rb
4cd0: 75 20 2a 70 52 62 75 2c 20 63 68 61 72 20 2a 2a  u *pRbu, char **
4ce0: 70 7a 45 72 72 6d 73 67 29 3b 0a 0a 2f 2a 0a 2a  pzErrmsg);../*.*
4cf0: 2a 20 52 65 74 75 72 6e 20 74 68 65 20 74 6f 74  * Return the tot
4d00: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 6b 65 79  al number of key
4d10: 2d 76 61 6c 75 65 20 6f 70 65 72 61 74 69 6f 6e  -value operation
4d20: 73 20 28 69 6e 73 65 72 74 73 2c 20 64 65 6c 65  s (inserts, dele
4d30: 74 65 73 20 6f 72 20 0a 2a 2a 20 75 70 64 61 74  tes or .** updat
4d40: 65 73 29 20 74 68 61 74 20 68 61 76 65 20 62 65  es) that have be
4d50: 65 6e 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20  en performed on 
4d60: 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62  the target datab
4d70: 61 73 65 20 73 69 6e 63 65 20 74 68 65 0a 2a 2a  ase since the.**
4d80: 20 63 75 72 72 65 6e 74 20 52 42 55 20 75 70 64   current RBU upd
4d90: 61 74 65 20 77 61 73 20 73 74 61 72 74 65 64 2e  ate was started.
4da0: 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
4db0: 34 20 73 71 6c 69 74 65 33 72 62 75 5f 70 72 6f  4 sqlite3rbu_pro
4dc0: 67 72 65 73 73 28 73 71 6c 69 74 65 33 72 62 75  gress(sqlite3rbu
4dd0: 20 2a 70 52 62 75 29 3b 0a 0a 2f 2a 0a 2a 2a 20   *pRbu);../*.** 
4de0: 4f 62 74 61 69 6e 20 70 65 72 6d 79 72 69 61 64  Obtain permyriad
4df0: 61 67 65 20 28 70 65 72 6d 79 72 69 61 64 61 67  age (permyriadag
4e00: 65 20 69 73 20 74 6f 20 31 30 30 30 30 20 61 73  e is to 10000 as
4e10: 20 70 65 72 63 65 6e 74 61 67 65 20 69 73 20 74   percentage is t
4e20: 6f 20 31 30 30 29 20 0a 2a 2a 20 70 72 6f 67 72  o 100) .** progr
4e30: 65 73 73 20 69 6e 64 69 63 61 74 69 6f 6e 73 20  ess indications 
4e40: 66 6f 72 20 74 68 65 20 74 77 6f 20 73 74 61 67  for the two stag
4e50: 65 73 20 6f 66 20 61 6e 20 52 42 55 20 75 70 64  es of an RBU upd
4e60: 61 74 65 2e 20 54 68 69 73 20 41 50 49 20 6d 61  ate. This API ma
4e70: 79 0a 2a 2a 20 62 65 20 75 73 65 66 75 6c 20 66  y.** be useful f
4e80: 6f 72 20 64 72 69 76 69 6e 67 20 47 55 49 20 70  or driving GUI p
4e90: 72 6f 67 72 65 73 73 20 69 6e 64 69 63 61 74 6f  rogress indicato
4ea0: 72 73 20 61 6e 64 20 73 69 6d 69 6c 61 72 2e 0a  rs and similar..
4eb0: 2a 2a 0a 2a 2a 20 41 6e 20 52 42 55 20 75 70 64  **.** An RBU upd
4ec0: 61 74 65 20 69 73 20 64 69 76 69 64 65 64 20 69  ate is divided i
4ed0: 6e 74 6f 20 74 77 6f 20 73 74 61 67 65 73 3a 0a  nto two stages:.
4ee0: 2a 2a 0a 2a 2a 20 20 20 2a 20 53 74 61 67 65 20  **.**   * Stage 
4ef0: 31 2c 20 69 6e 20 77 68 69 63 68 20 63 68 61 6e  1, in which chan
4f00: 67 65 73 20 61 72 65 20 61 63 63 75 6d 75 6c 61  ges are accumula
4f10: 74 65 64 20 69 6e 20 61 6e 20 6f 61 6c 2f 77 61  ted in an oal/wa
4f20: 6c 20 66 69 6c 65 2c 20 61 6e 64 0a 2a 2a 20 20  l file, and.**  
4f30: 20 2a 20 53 74 61 67 65 20 32 2c 20 69 6e 20 77   * Stage 2, in w
4f40: 68 69 63 68 20 74 68 65 20 63 6f 6e 74 65 6e 74  hich the content
4f50: 73 20 6f 66 20 74 68 65 20 77 61 6c 20 66 69 6c  s of the wal fil
4f60: 65 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  e are copied int
4f70: 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 6d 61 69  o the.**     mai
4f80: 6e 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a  n database..**.*
4f90: 2a 20 54 68 65 20 75 70 64 61 74 65 20 69 73 20  * The update is 
4fa0: 76 69 73 69 62 6c 65 20 74 6f 20 6e 6f 6e 2d 52  visible to non-R
4fb0: 42 55 20 63 6c 69 65 6e 74 73 20 64 75 72 69 6e  BU clients durin
4fc0: 67 20 73 74 61 67 65 20 32 2e 20 44 75 72 69 6e  g stage 2. Durin
4fd0: 67 20 73 74 61 67 65 20 31 0a 2a 2a 20 6e 6f 6e  g stage 1.** non
4fe0: 2d 52 42 55 20 72 65 61 64 65 72 20 63 6c 69 65  -RBU reader clie
4ff0: 6e 74 73 20 6d 61 79 20 73 65 65 20 74 68 65 20  nts may see the 
5000: 6f 72 69 67 69 6e 61 6c 20 64 61 74 61 62 61 73  original databas
5010: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73  e..**.** If this
5020: 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 20 64   API is called d
5030: 75 72 69 6e 67 20 73 74 61 67 65 20 32 20 6f 66  uring stage 2 of
5040: 20 74 68 65 20 75 70 64 61 74 65 2c 20 6f 75 74   the update, out
5050: 70 75 74 20 76 61 72 69 61 62 6c 65 20 0a 2a 2a  put variable .**
5060: 20 28 2a 70 6e 4f 6e 65 29 20 69 73 20 73 65 74   (*pnOne) is set
5070: 20 74 6f 20 31 30 30 30 30 20 74 6f 20 69 6e 64   to 10000 to ind
5080: 69 63 61 74 65 20 74 68 61 74 20 73 74 61 67 65  icate that stage
5090: 20 31 20 68 61 73 20 66 69 6e 69 73 68 65 64 20   1 has finished 
50a0: 61 6e 64 20 28 2a 70 6e 54 77 6f 29 0a 2a 2a 20  and (*pnTwo).** 
50b0: 74 6f 20 61 20 76 61 6c 75 65 20 62 65 74 77 65  to a value betwe
50c0: 65 6e 20 30 20 61 6e 64 20 31 30 30 30 30 20 74  en 0 and 10000 t
50d0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 70  o indicate the p
50e0: 65 72 6d 79 72 69 61 64 61 67 65 20 70 72 6f 67  ermyriadage prog
50f0: 72 65 73 73 20 6f 66 0a 2a 2a 20 73 74 61 67 65  ress of.** stage
5100: 20 32 2e 20 41 20 76 61 6c 75 65 20 6f 66 20 35   2. A value of 5
5110: 30 30 30 20 69 6e 64 69 63 61 74 65 73 20 74 68  000 indicates th
5120: 61 74 20 73 74 61 67 65 20 32 20 69 73 20 68 61  at stage 2 is ha
5130: 6c 66 20 66 69 6e 69 73 68 65 64 2c 20 0a 2a 2a  lf finished, .**
5140: 20 39 30 30 30 20 69 6e 64 69 63 61 74 65 73 20   9000 indicates 
5150: 74 68 61 74 20 69 74 20 69 73 20 39 30 25 20 66  that it is 90% f
5160: 69 6e 69 73 68 65 64 2c 20 61 6e 64 20 73 6f 20  inished, and so 
5170: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69  on..**.** If thi
5180: 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 20  s API is called 
5190: 64 75 72 69 6e 67 20 73 74 61 67 65 20 31 20 6f  during stage 1 o
51a0: 66 20 74 68 65 20 75 70 64 61 74 65 2c 20 6f 75  f the update, ou
51b0: 74 70 75 74 20 76 61 72 69 61 62 6c 65 20 0a 2a  tput variable .*
51c0: 2a 20 28 2a 70 6e 54 77 6f 29 20 69 73 20 73 65  * (*pnTwo) is se
51d0: 74 20 74 6f 20 30 20 74 6f 20 69 6e 64 69 63 61  t to 0 to indica
51e0: 74 65 20 74 68 61 74 20 73 74 61 67 65 20 32 20  te that stage 2 
51f0: 68 61 73 20 6e 6f 74 20 79 65 74 20 73 74 61 72  has not yet star
5200: 74 65 64 2e 20 54 68 65 0a 2a 2a 20 76 61 6c 75  ted. The.** valu
5210: 65 20 74 6f 20 77 68 69 63 68 20 28 2a 70 6e 4f  e to which (*pnO
5220: 6e 65 29 20 69 73 20 73 65 74 20 64 65 70 65 6e  ne) is set depen
5230: 64 73 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72  ds on whether or
5240: 20 6e 6f 74 20 74 68 65 20 52 42 55 20 0a 2a 2a   not the RBU .**
5250: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 74 61 69   database contai
5260: 6e 73 20 61 6e 20 22 72 62 75 5f 63 6f 75 6e 74  ns an "rbu_count
5270: 22 20 74 61 62 6c 65 2e 20 54 68 65 20 72 62 75  " table. The rbu
5280: 5f 63 6f 75 6e 74 20 74 61 62 6c 65 2c 20 69 66  _count table, if
5290: 20 69 74 20 0a 2a 2a 20 65 78 69 73 74 73 2c 20   it .** exists, 
52a0: 6d 75 73 74 20 63 6f 6e 74 61 69 6e 20 74 68 65  must contain the
52b0: 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 73 20 61 73   same columns as
52c0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a   the following:.
52d0: 2a 2a 0a 2a 2a 20 20 20 43 52 45 41 54 45 20 54  **.**   CREATE T
52e0: 41 42 4c 45 20 72 62 75 5f 63 6f 75 6e 74 28 74  ABLE rbu_count(t
52f0: 62 6c 20 54 45 58 54 20 50 52 49 4d 41 52 59 20  bl TEXT PRIMARY 
5300: 4b 45 59 2c 20 63 6e 74 20 49 4e 54 45 47 45 52  KEY, cnt INTEGER
5310: 29 20 57 49 54 48 4f 55 54 20 52 4f 57 49 44 3b  ) WITHOUT ROWID;
5320: 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 6d 75 73  .**.** There mus
5330: 74 20 62 65 20 6f 6e 65 20 72 6f 77 20 69 6e 20  t be one row in 
5340: 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 65 61  the table for ea
5350: 63 68 20 73 6f 75 72 63 65 20 28 64 61 74 61 5f  ch source (data_
5360: 78 78 78 29 20 74 61 62 6c 65 20 77 69 74 68 69  xxx) table withi
5370: 6e 0a 2a 2a 20 74 68 65 20 52 42 55 20 64 61 74  n.** the RBU dat
5380: 61 62 61 73 65 2e 20 54 68 65 20 27 74 62 6c 27  abase. The 'tbl'
5390: 20 63 6f 6c 75 6d 6e 20 73 68 6f 75 6c 64 20 63   column should c
53a0: 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 20  ontain the name 
53b0: 6f 66 20 74 68 65 20 73 6f 75 72 63 65 0a 2a 2a  of the source.**
53c0: 20 74 61 62 6c 65 2e 20 54 68 65 20 27 63 6e 74   table. The 'cnt
53d0: 27 20 63 6f 6c 75 6d 6e 20 73 68 6f 75 6c 64 20  ' column should 
53e0: 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 75 6d 62  contain the numb
53f0: 65 72 20 6f 66 20 72 6f 77 73 20 77 69 74 68 69  er of rows withi
5400: 6e 20 74 68 65 0a 2a 2a 20 73 6f 75 72 63 65 20  n the.** source 
5410: 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  table..**.** If 
5420: 74 68 65 20 72 62 75 5f 63 6f 75 6e 74 20 74 61  the rbu_count ta
5430: 62 6c 65 20 69 73 20 70 72 65 73 65 6e 74 20 61  ble is present a
5440: 6e 64 20 70 6f 70 75 6c 61 74 65 64 20 63 6f 72  nd populated cor
5450: 72 65 63 74 6c 79 20 61 6e 64 20 74 68 69 73 0a  rectly and this.
5460: 2a 2a 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64  ** API is called
5470: 20 64 75 72 69 6e 67 20 73 74 61 67 65 20 31 2c   during stage 1,
5480: 20 74 68 65 20 2a 70 6e 4f 6e 65 20 6f 75 74 70   the *pnOne outp
5490: 75 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 73  ut variable is s
54a0: 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 65 72  et to the.** per
54b0: 6d 79 72 69 61 64 61 67 65 20 70 72 6f 67 72 65  myriadage progre
54c0: 73 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 73  ss of the same s
54d0: 74 61 67 65 2e 20 49 66 20 74 68 65 20 72 62 75  tage. If the rbu
54e0: 5f 63 6f 75 6e 74 20 74 61 62 6c 65 20 64 6f 65  _count table doe
54f0: 73 0a 2a 2a 20 6e 6f 74 20 65 78 69 73 74 2c 20  s.** not exist, 
5500: 74 68 65 6e 20 28 2a 70 6e 4f 6e 65 29 20 69 73  then (*pnOne) is
5510: 20 73 65 74 20 74 6f 20 2d 31 20 64 75 72 69 6e   set to -1 durin
5520: 67 20 73 74 61 67 65 20 31 2e 20 49 66 20 74 68  g stage 1. If th
5530: 65 20 72 62 75 5f 63 6f 75 6e 74 0a 2a 2a 20 74  e rbu_count.** t
5540: 61 62 6c 65 20 65 78 69 73 74 73 20 62 75 74 20  able exists but 
5550: 69 73 20 6e 6f 74 20 63 6f 72 72 65 63 74 6c 79  is not correctly
5560: 20 70 6f 70 75 6c 61 74 65 64 2c 20 74 68 65 20   populated, the 
5570: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 2a 70 6e  value of the *pn
5580: 4f 6e 65 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61  One.** output va
5590: 72 69 61 62 6c 65 20 64 75 72 69 6e 67 20 73 74  riable during st
55a0: 61 67 65 20 31 20 69 73 20 75 6e 64 65 66 69 6e  age 1 is undefin
55b0: 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
55c0: 74 65 33 72 62 75 5f 62 70 5f 70 72 6f 67 72 65  te3rbu_bp_progre
55d0: 73 73 28 73 71 6c 69 74 65 33 72 62 75 20 2a 70  ss(sqlite3rbu *p
55e0: 52 62 75 2c 20 69 6e 74 20 2a 70 6e 4f 6e 65 2c  Rbu, int *pnOne,
55f0: 20 69 6e 74 20 2a 70 6e 54 77 6f 29 3b 0a 0a 2f   int *pnTwo);../
5600: 2a 0a 2a 2a 20 4f 62 74 61 69 6e 20 61 6e 20 69  *.** Obtain an i
5610: 6e 64 69 63 61 74 69 6f 6e 20 61 73 20 74 6f 20  ndication as to 
5620: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 67  the current stag
5630: 65 20 6f 66 20 61 6e 20 52 42 55 20 75 70 64 61  e of an RBU upda
5640: 74 65 20 6f 72 20 76 61 63 75 75 6d 2e 0a 2a 2a  te or vacuum..**
5650: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   This function a
5660: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 6f 6e  lways returns on
5670: 65 20 6f 66 20 74 68 65 20 53 51 4c 49 54 45 5f  e of the SQLITE_
5680: 52 42 55 5f 53 54 41 54 45 5f 58 58 58 20 63 6f  RBU_STATE_XXX co
5690: 6e 73 74 61 6e 74 73 0a 2a 2a 20 64 65 66 69 6e  nstants.** defin
56a0: 65 64 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2e  ed in this file.
56b0: 20 52 65 74 75 72 6e 20 76 61 6c 75 65 73 20 73   Return values s
56c0: 68 6f 75 6c 64 20 62 65 20 69 6e 74 65 72 70 72  hould be interpr
56d0: 65 74 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  eted as follows:
56e0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 49 54 45 5f 52 42  .**.** SQLITE_RB
56f0: 55 5f 53 54 41 54 45 5f 4f 41 4c 3a 0a 2a 2a 20  U_STATE_OAL:.** 
5700: 20 20 52 42 55 20 69 73 20 63 75 72 72 65 6e 74    RBU is current
5710: 6c 79 20 62 75 69 6c 64 69 6e 67 20 61 20 2a 2d  ly building a *-
5720: 6f 61 6c 20 66 69 6c 65 2e 20 54 68 65 20 6e 65  oal file. The ne
5730: 78 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  xt call to sqlit
5740: 65 33 72 62 75 5f 73 74 65 70 28 29 0a 2a 2a 20  e3rbu_step().** 
5750: 20 20 6d 61 79 20 65 69 74 68 65 72 20 61 64 64    may either add
5760: 20 66 75 72 74 68 65 72 20 64 61 74 61 20 74 6f   further data to
5770: 20 74 68 65 20 2a 2d 6f 61 6c 20 66 69 6c 65 2c   the *-oal file,
5780: 20 6f 72 20 63 6f 6d 70 75 74 65 20 64 61 74 61   or compute data
5790: 20 74 68 61 74 20 77 69 6c 6c 0a 2a 2a 20 20 20   that will.**   
57a0: 62 65 20 61 64 64 65 64 20 62 79 20 61 20 73 75  be added by a su
57b0: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 2e 0a 2a  bsequent call..*
57c0: 2a 0a 2a 2a 20 53 51 4c 49 54 45 5f 52 42 55 5f  *.** SQLITE_RBU_
57d0: 53 54 41 54 45 5f 4d 4f 56 45 3a 0a 2a 2a 20 20  STATE_MOVE:.**  
57e0: 20 52 42 55 20 68 61 73 20 66 69 6e 69 73 68 65   RBU has finishe
57f0: 64 20 62 75 69 6c 64 69 6e 67 20 74 68 65 20 2a  d building the *
5800: 2d 6f 61 6c 20 66 69 6c 65 2e 20 54 68 65 20 6e  -oal file. The n
5810: 65 78 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ext call to sqli
5820: 74 65 33 72 62 75 5f 73 74 65 70 28 29 0a 2a 2a  te3rbu_step().**
5830: 20 20 20 77 69 6c 6c 20 6d 6f 76 65 20 74 68 65     will move the
5840: 20 2a 2d 6f 61 6c 20 66 69 6c 65 20 74 6f 20 74   *-oal file to t
5850: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 2a 2d  he equivalent *-
5860: 77 61 6c 20 70 61 74 68 2e 20 49 66 20 74 68 65  wal path. If the
5870: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 20 20 6f 70   current.**   op
5880: 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 52 42  eration is an RB
5890: 55 20 75 70 64 61 74 65 2c 20 74 68 65 6e 20 74  U update, then t
58a0: 68 65 20 75 70 64 61 74 65 64 20 76 65 72 73 69  he updated versi
58b0: 6f 6e 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  on of the databa
58c0: 73 65 0a 2a 2a 20 20 20 66 69 6c 65 20 77 69 6c  se.**   file wil
58d0: 6c 20 62 65 63 6f 6d 65 20 76 69 73 69 62 6c 65  l become visible
58e0: 20 74 6f 20 6f 72 64 69 6e 61 72 79 20 53 51 4c   to ordinary SQL
58f0: 69 74 65 20 63 6c 69 65 6e 74 73 20 66 6f 6c 6c  ite clients foll
5900: 6f 77 69 6e 67 20 74 68 65 20 6e 65 78 74 0a 2a  owing the next.*
5910: 2a 20 20 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  *   call to sqli
5920: 74 65 33 72 62 75 5f 73 74 65 70 28 29 2e 0a 2a  te3rbu_step()..*
5930: 2a 0a 2a 2a 20 53 51 4c 49 54 45 5f 52 42 55 5f  *.** SQLITE_RBU_
5940: 53 54 41 54 45 5f 43 48 45 43 4b 50 4f 49 4e 54  STATE_CHECKPOINT
5950: 3a 0a 2a 2a 20 20 20 52 42 55 20 69 73 20 63 75  :.**   RBU is cu
5960: 72 72 65 6e 74 6c 79 20 70 65 72 66 6f 72 6d 69  rrently performi
5970: 6e 67 20 61 6e 20 69 6e 63 72 65 6d 65 6e 74 61  ng an incrementa
5980: 6c 20 63 68 65 63 6b 70 6f 69 6e 74 2e 20 54 68  l checkpoint. Th
5990: 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
59a0: 2a 20 20 20 73 71 6c 69 74 65 33 72 62 75 5f 73  *   sqlite3rbu_s
59b0: 74 65 70 28 29 20 77 69 6c 6c 20 63 6f 70 79 20  tep() will copy 
59c0: 61 20 70 61 67 65 20 6f 66 20 64 61 74 61 20 66  a page of data f
59d0: 72 6f 6d 20 74 68 65 20 2a 2d 77 61 6c 20 66 69  rom the *-wal fi
59e0: 6c 65 20 69 6e 74 6f 0a 2a 2a 20 20 20 74 68 65  le into.**   the
59f0: 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73 65   target database
5a00: 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   file..**.** SQL
5a10: 49 54 45 5f 52 42 55 5f 53 54 41 54 45 5f 44 4f  ITE_RBU_STATE_DO
5a20: 4e 45 3a 0a 2a 2a 20 20 20 54 68 65 20 52 42 55  NE:.**   The RBU
5a30: 20 6f 70 65 72 61 74 69 6f 6e 20 68 61 73 20 66   operation has f
5a40: 69 6e 69 73 68 65 64 2e 20 41 6e 79 20 73 75 62  inished. Any sub
5a50: 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
5a60: 20 73 71 6c 69 74 65 33 72 62 75 5f 73 74 65 70   sqlite3rbu_step
5a70: 28 29 0a 2a 2a 20 20 20 77 69 6c 6c 20 69 6d 6d  ().**   will imm
5a80: 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20  ediately return 
5a90: 53 51 4c 49 54 45 5f 44 4f 4e 45 2e 0a 2a 2a 0a  SQLITE_DONE..**.
5aa0: 2a 2a 20 53 51 4c 49 54 45 5f 52 42 55 5f 53 54  ** SQLITE_RBU_ST
5ab0: 41 54 45 5f 45 52 52 4f 52 3a 0a 2a 2a 20 20 20  ATE_ERROR:.**   
5ac0: 41 6e 20 65 72 72 6f 72 20 68 61 73 20 6f 63 63  An error has occ
5ad0: 75 72 72 65 64 2e 20 41 6e 79 20 73 75 62 73 65  urred. Any subse
5ae0: 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73  quent calls to s
5af0: 71 6c 69 74 65 33 72 62 75 5f 73 74 65 70 28 29  qlite3rbu_step()
5b00: 20 77 69 6c 6c 0a 2a 2a 20 20 20 69 6d 6d 65 64   will.**   immed
5b10: 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 74 68  iately return th
5b20: 65 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63  e SQLite error c
5b30: 6f 64 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  ode associated w
5b40: 69 74 68 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  ith the error..*
5b50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5b60: 5f 52 42 55 5f 53 54 41 54 45 5f 4f 41 4c 20 20  _RBU_STATE_OAL  
5b70: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
5b80: 53 51 4c 49 54 45 5f 52 42 55 5f 53 54 41 54 45  SQLITE_RBU_STATE
5b90: 5f 4d 4f 56 45 20 20 20 20 20 20 20 32 0a 23 64  _MOVE       2.#d
5ba0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 42 55  efine SQLITE_RBU
5bb0: 5f 53 54 41 54 45 5f 43 48 45 43 4b 50 4f 49 4e  _STATE_CHECKPOIN
5bc0: 54 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  T 3.#define SQLI
5bd0: 54 45 5f 52 42 55 5f 53 54 41 54 45 5f 44 4f 4e  TE_RBU_STATE_DON
5be0: 45 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  E       4.#defin
5bf0: 65 20 53 51 4c 49 54 45 5f 52 42 55 5f 53 54 41  e SQLITE_RBU_STA
5c00: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 35 0a  TE_ERROR      5.
5c10: 0a 69 6e 74 20 73 71 6c 69 74 65 33 72 62 75 5f  .int sqlite3rbu_
5c20: 73 74 61 74 65 28 73 71 6c 69 74 65 33 72 62 75  state(sqlite3rbu
5c30: 20 2a 70 52 62 75 29 3b 0a 0a 2f 2a 0a 2a 2a 20   *pRbu);../*.** 
5c40: 43 72 65 61 74 65 20 61 6e 20 52 42 55 20 56 46  Create an RBU VF
5c50: 53 20 6e 61 6d 65 64 20 7a 4e 61 6d 65 20 74 68  S named zName th
5c60: 61 74 20 61 63 63 65 73 73 65 73 20 74 68 65 20  at accesses the 
5c70: 75 6e 64 65 72 6c 79 69 6e 67 20 66 69 6c 65 2d  underlying file-
5c80: 73 79 73 74 65 6d 0a 2a 2a 20 76 69 61 20 65 78  system.** via ex
5c90: 69 73 74 69 6e 67 20 56 46 53 20 7a 50 61 72 65  isting VFS zPare
5ca0: 6e 74 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 7a  nt. Or, if the z
5cb0: 50 61 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72  Parent parameter
5cc0: 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 2c   is passed NULL,
5cd0: 20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 65   .** then the ne
5ce0: 77 20 52 42 55 20 56 46 53 20 75 73 65 73 20 74  w RBU VFS uses t
5cf0: 68 65 20 64 65 66 61 75 6c 74 20 73 79 73 74 65  he default syste
5d00: 6d 20 56 46 53 20 74 6f 20 61 63 63 65 73 73 20  m VFS to access 
5d10: 74 68 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 2e  the file-system.
5d20: 0a 2a 2a 20 54 68 65 20 6e 65 77 20 6f 62 6a 65  .** The new obje
5d30: 63 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64  ct is registered
5d40: 20 61 73 20 61 20 6e 6f 6e 2d 64 65 66 61 75 6c   as a non-defaul
5d50: 74 20 56 46 53 20 77 69 74 68 20 53 51 4c 69 74  t VFS with SQLit
5d60: 65 20 62 65 66 6f 72 65 20 0a 2a 2a 20 72 65 74  e before .** ret
5d70: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 50 61  urning..**.** Pa
5d80: 72 74 20 6f 66 20 74 68 65 20 52 42 55 20 69 6d  rt of the RBU im
5d90: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
5da0: 73 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 6f  s a custom VFS o
5db0: 62 6a 65 63 74 2e 20 55 73 75 61 6c 6c 79 2c 20  bject. Usually, 
5dc0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 69  this.** object i
5dd0: 73 20 63 72 65 61 74 65 64 20 61 6e 64 20 64 65  s created and de
5de0: 6c 65 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61  leted automatica
5df0: 6c 6c 79 20 62 79 20 52 42 55 2e 20 0a 2a 2a 0a  lly by RBU. .**.
5e00: 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
5e10: 20 69 73 20 66 6f 72 20 61 70 70 6c 69 63 61 74   is for applicat
5e20: 69 6f 6e 73 20 74 68 61 74 20 61 6c 73 6f 20 75  ions that also u
5e30: 73 65 20 7a 69 70 76 66 73 2e 20 49 6e 20 74 68  se zipvfs. In th
5e40: 69 73 20 63 61 73 65 2c 0a 2a 2a 20 74 68 65 20  is case,.** the 
5e50: 63 75 73 74 6f 6d 20 56 46 53 20 6d 75 73 74 20  custom VFS must 
5e60: 62 65 20 65 78 70 6c 69 63 69 74 6c 79 20 63 72  be explicitly cr
5e70: 65 61 74 65 64 20 62 79 20 74 68 65 20 75 73 65  eated by the use
5e80: 72 20 62 65 66 6f 72 65 20 74 68 65 20 52 42 55  r before the RBU
5e90: 0a 2a 2a 20 68 61 6e 64 6c 65 20 69 73 20 6f 70  .** handle is op
5ea0: 65 6e 65 64 2e 20 54 68 65 20 52 42 55 20 56 46  ened. The RBU VF
5eb0: 53 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 73 74  S should be inst
5ec0: 61 6c 6c 65 64 20 73 6f 20 74 68 61 74 20 74 68  alled so that th
5ed0: 65 20 7a 69 70 76 66 73 0a 2a 2a 20 56 46 53 20  e zipvfs.** VFS 
5ee0: 75 73 65 73 20 74 68 65 20 52 42 55 20 56 46 53  uses the RBU VFS
5ef0: 2c 20 77 68 69 63 68 20 69 6e 20 74 75 72 6e 20  , which in turn 
5f00: 75 73 65 73 20 61 6e 79 20 6f 74 68 65 72 20 56  uses any other V
5f10: 46 53 20 6c 61 79 65 72 73 20 69 6e 20 75 73 65  FS layers in use
5f20: 20 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c   .** (for exampl
5f30: 65 20 6d 75 6c 74 69 70 6c 65 78 6f 72 29 20 74  e multiplexor) t
5f40: 6f 20 61 63 63 65 73 73 20 74 68 65 20 66 69 6c  o access the fil
5f50: 65 2d 73 79 73 74 65 6d 2e 20 46 6f 72 20 65 78  e-system. For ex
5f60: 61 6d 70 6c 65 2c 0a 2a 2a 20 74 6f 20 61 73 73  ample,.** to ass
5f70: 65 6d 62 6c 65 20 61 6e 20 52 42 55 20 65 6e 61  emble an RBU ena
5f80: 62 6c 65 64 20 56 46 53 20 73 74 61 63 6b 20 74  bled VFS stack t
5f90: 68 61 74 20 75 73 65 73 20 62 6f 74 68 20 7a 69  hat uses both zi
5fa0: 70 76 66 73 20 61 6e 64 20 0a 2a 2a 20 6d 75 6c  pvfs and .** mul
5fb0: 74 69 70 6c 65 78 6f 72 20 28 65 72 72 6f 72 20  tiplexor (error 
5fc0: 63 68 65 63 6b 69 6e 67 20 6f 6d 69 74 74 65 64  checking omitted
5fd0: 29 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 2f 2f 20  ):.**.**     // 
5fe0: 43 72 65 61 74 65 20 61 20 56 46 53 20 6e 61 6d  Create a VFS nam
5ff0: 65 64 20 22 6d 75 6c 74 69 70 6c 65 78 22 20 28  ed "multiplex" (
6000: 6e 6f 74 20 74 68 65 20 64 65 66 61 75 6c 74 29  not the default)
6010: 2e 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  ..**     sqlite3
6020: 5f 6d 75 6c 74 69 70 6c 65 78 5f 69 6e 69 74 69  _multiplex_initi
6030: 61 6c 69 7a 65 28 30 2c 20 30 29 3b 0a 2a 2a 0a  alize(0, 0);.**.
6040: 2a 2a 20 20 20 20 20 2f 2f 20 43 72 65 61 74 65  **     // Create
6050: 20 61 6e 20 72 62 75 20 56 46 53 20 6e 61 6d 65   an rbu VFS name
6060: 64 20 22 72 62 75 22 20 74 68 61 74 20 75 73 65  d "rbu" that use
6070: 73 20 6d 75 6c 74 69 70 6c 65 78 6f 72 2e 20 49  s multiplexor. I
6080: 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 2f 2f 20  f the.**     // 
6090: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
60a0: 77 65 72 65 20 72 65 70 6c 61 63 65 64 20 77 69  were replaced wi
60b0: 74 68 20 4e 55 4c 4c 2c 20 74 68 65 20 22 72 62  th NULL, the "rb
60c0: 75 22 20 56 46 53 20 77 6f 75 6c 64 0a 2a 2a 20  u" VFS would.** 
60d0: 20 20 20 20 2f 2f 20 61 63 63 65 73 73 20 74 68      // access th
60e0: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 76 69  e file-system vi
60f0: 61 20 74 68 65 20 73 79 73 74 65 6d 20 64 65 66  a the system def
6100: 61 75 6c 74 20 56 46 53 2c 20 62 79 70 61 73 73  ault VFS, bypass
6110: 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 2f  ing the.**     /
6120: 2f 20 6d 75 6c 74 69 70 6c 65 78 6f 72 2e 0a 2a  / multiplexor..*
6130: 2a 20 20 20 20 20 73 71 6c 69 74 65 33 72 62 75  *     sqlite3rbu
6140: 5f 63 72 65 61 74 65 5f 76 66 73 28 22 72 62 75  _create_vfs("rbu
6150: 22 2c 20 22 6d 75 6c 74 69 70 6c 65 78 22 29 3b  ", "multiplex");
6160: 0a 2a 2a 0a 2a 2a 20 20 20 20 20 2f 2f 20 43 72  .**.**     // Cr
6170: 65 61 74 65 20 61 20 7a 69 70 76 66 73 20 56 46  eate a zipvfs VF
6180: 53 20 6e 61 6d 65 64 20 22 7a 69 70 76 66 73 22  S named "zipvfs"
6190: 20 74 68 61 74 20 75 73 65 73 20 72 62 75 2e 0a   that uses rbu..
61a0: 2a 2a 20 20 20 20 20 7a 69 70 76 66 73 5f 63 72  **     zipvfs_cr
61b0: 65 61 74 65 5f 76 66 73 5f 76 33 28 22 7a 69 70  eate_vfs_v3("zip
61c0: 76 66 73 22 2c 20 22 72 62 75 22 2c 20 30 2c 20  vfs", "rbu", 0, 
61d0: 78 43 6f 6d 70 72 65 73 73 6f 72 41 6c 67 6f 72  xCompressorAlgor
61e0: 69 74 68 6d 44 65 74 65 63 74 6f 72 29 3b 0a 2a  ithmDetector);.*
61f0: 2a 0a 2a 2a 20 20 20 20 20 2f 2f 20 4d 61 6b 65  *.**     // Make
6200: 20 7a 69 70 76 66 73 20 74 68 65 20 64 65 66 61   zipvfs the defa
6210: 75 6c 74 20 56 46 53 2e 0a 2a 2a 20 20 20 20 20  ult VFS..**     
6220: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
6230: 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
6240: 5f 66 69 6e 64 28 22 7a 69 70 76 66 73 22 29 2c  _find("zipvfs"),
6250: 20 31 29 3b 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75   1);.**.** Becau
6260: 73 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  se the default V
6270: 46 53 20 63 72 65 61 74 65 64 20 61 62 6f 76 65  FS created above
6280: 20 69 6e 63 6c 75 64 65 73 20 61 20 52 42 55 20   includes a RBU 
6290: 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79 2c 20 69  functionality, i
62a0: 74 0a 2a 2a 20 6d 61 79 20 62 65 20 75 73 65 64  t.** may be used
62b0: 20 62 79 20 52 42 55 20 63 6c 69 65 6e 74 73 2e   by RBU clients.
62c0: 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 75   Attempting to u
62d0: 73 65 20 52 42 55 20 77 69 74 68 20 61 20 7a 69  se RBU with a zi
62e0: 70 76 66 73 20 56 46 53 20 73 74 61 63 6b 0a 2a  pvfs VFS stack.*
62f0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
6300: 69 6e 63 6c 75 64 65 20 74 68 65 20 52 42 55 20  include the RBU 
6310: 6c 61 79 65 72 20 72 65 73 75 6c 74 73 20 69 6e  layer results in
6320: 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
6330: 20 54 68 65 20 6f 76 65 72 68 65 61 64 20 6f 66   The overhead of
6340: 20 61 64 64 69 6e 67 20 74 68 65 20 22 72 62 75   adding the "rbu
6350: 22 20 56 46 53 20 74 6f 20 74 68 65 20 73 79 73  " VFS to the sys
6360: 74 65 6d 20 69 73 20 6e 65 67 6c 69 67 69 62 6c  tem is negligibl
6370: 65 20 66 6f 72 20 0a 2a 2a 20 6e 6f 6e 2d 52 42  e for .** non-RB
6380: 55 20 75 73 65 72 73 2e 20 54 68 65 72 65 20 69  U users. There i
6390: 73 20 6e 6f 20 68 61 72 6d 20 69 6e 20 61 6e 20  s no harm in an 
63a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 61 63 63 65  application acce
63b0: 73 73 69 6e 67 20 74 68 65 20 0a 2a 2a 20 66 69  ssing the .** fi
63c0: 6c 65 2d 73 79 73 74 65 6d 20 76 69 61 20 22 72  le-system via "r
63d0: 62 75 22 20 61 6c 6c 20 74 68 65 20 74 69 6d 65  bu" all the time
63e0: 2c 20 65 76 65 6e 20 69 66 20 69 74 20 6f 6e 6c  , even if it onl
63f0: 79 20 75 73 65 73 20 52 42 55 20 66 75 6e 63 74  y uses RBU funct
6400: 69 6f 6e 61 6c 69 74 79 20 0a 2a 2a 20 6f 63 63  ionality .** occ
6410: 61 73 69 6f 6e 61 6c 6c 79 2e 0a 2a 2f 0a 69 6e  asionally..*/.in
6420: 74 20 73 71 6c 69 74 65 33 72 62 75 5f 63 72 65  t sqlite3rbu_cre
6430: 61 74 65 5f 76 66 73 28 63 6f 6e 73 74 20 63 68  ate_vfs(const ch
6440: 61 72 20 2a 7a 4e 61 6d 65 2c 20 63 6f 6e 73 74  ar *zName, const
6450: 20 63 68 61 72 20 2a 7a 50 61 72 65 6e 74 29 3b   char *zParent);
6460: 0a 0a 2f 2a 0a 2a 2a 20 44 65 72 65 67 69 73 74  ../*.** Deregist
6470: 65 72 20 61 6e 64 20 64 65 73 74 72 6f 79 20 61  er and destroy a
6480: 6e 20 52 42 55 20 76 66 73 20 63 72 65 61 74 65  n RBU vfs create
6490: 64 20 62 79 20 61 6e 20 65 61 72 6c 69 65 72 20  d by an earlier 
64a0: 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
64b0: 65 33 72 62 75 5f 63 72 65 61 74 65 5f 76 66 73  e3rbu_create_vfs
64c0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 56 46 53 20 6f 62  ()..**.** VFS ob
64d0: 6a 65 63 74 73 20 61 72 65 20 6e 6f 74 20 72 65  jects are not re
64e0: 66 65 72 65 6e 63 65 20 63 6f 75 6e 74 65 64 2e  ference counted.
64f0: 20 49 66 20 61 20 56 46 53 20 6f 62 6a 65 63 74   If a VFS object
6500: 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
6510: 20 62 65 66 6f 72 65 20 61 6c 6c 20 64 61 74 61   before all data
6520: 62 61 73 65 20 68 61 6e 64 6c 65 73 20 74 68 61  base handles tha
6530: 74 20 75 73 65 20 69 74 20 68 61 76 65 20 62 65  t use it have be
6540: 65 6e 20 63 6c 6f 73 65 64 2c 20 74 68 65 20 72  en closed, the r
6550: 65 73 75 6c 74 73 0a 2a 2a 20 61 72 65 20 75 6e  esults.** are un
6560: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
6570: 20 73 71 6c 69 74 65 33 72 62 75 5f 64 65 73 74   sqlite3rbu_dest
6580: 72 6f 79 5f 76 66 73 28 63 6f 6e 73 74 20 63 68  roy_vfs(const ch
6590: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 23 69 66  ar *zName);..#if
65a0: 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a  def __cplusplus.
65b0: 7d 20 20 2f 2a 20 65 6e 64 20 6f 66 20 74 68 65  }  /* end of the
65c0: 20 27 65 78 74 65 72 6e 20 22 43 22 27 20 62 6c   'extern "C"' bl
65d0: 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 23  ock */.#endif..#
65e0: 65 6e 64 69 66 20 2f 2a 20 5f 53 51 4c 49 54 45  endif /* _SQLITE
65f0: 33 52 42 55 5f 48 20 2a 2f 0a                    3RBU_H */.