SQLite
Hex Artifact Content
Not logged in

Artifact d7cc99350c10134f358fe1a8997d9225b3f712b2:


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 74 68 65 20 3c 69 6e 74 65 67  f the the <integ
12d0: 65 72 3e 20 70 6f 72 74 69 6f 6e 20 6f 66 20 74  er> portion of t
12e0: 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 6f 66 20 74  he names.** of t
12f0: 68 65 20 52 42 55 20 74 61 62 6c 65 73 20 74 68  he RBU tables th
1300: 65 20 75 73 65 72 20 63 61 6e 20 74 68 65 72 65  e user can there
1310: 66 6f 72 65 20 63 6f 6e 74 72 6f 6c 20 74 68 65  fore control the
1320: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 20   order in which 
1330: 74 68 65 79 0a 2a 2a 20 61 72 65 20 70 72 6f 63  they.** are proc
1340: 65 73 73 65 64 2e 20 54 68 69 73 20 63 61 6e 20  essed. This can 
1350: 62 65 20 75 73 65 66 75 6c 2c 20 66 6f 72 20 65  be useful, for e
1360: 78 61 6d 70 6c 65 2c 20 74 6f 20 65 6e 73 75 72  xample, to ensur
1370: 65 20 74 68 61 74 20 22 65 78 74 65 72 6e 61 6c  e that "external
1380: 0a 2a 2a 20 63 6f 6e 74 65 6e 74 22 20 46 54 53  .** content" FTS
1390: 34 20 74 61 62 6c 65 73 20 61 72 65 20 75 70 64  4 tables are upd
13a0: 61 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 69  ated before thei
13b0: 72 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 6f 6e  r underlying con
13c0: 74 65 6e 74 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a  tent tables..**.
13d0: 2a 2a 20 49 66 20 74 68 65 20 74 61 72 67 65 74  ** If the target
13e0: 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
13f0: 69 73 20 61 20 76 69 72 74 75 61 6c 20 74 61 62  is a virtual tab
1400: 6c 65 20 6f 72 20 61 20 74 61 62 6c 65 20 74 68  le or a table th
1410: 61 74 20 68 61 73 20 6e 6f 0a 2a 2a 20 50 52 49  at has no.** PRI
1420: 4d 41 52 59 20 4b 45 59 20 64 65 63 6c 61 72 61  MARY KEY declara
1430: 74 69 6f 6e 2c 20 74 68 65 20 64 61 74 61 5f 25  tion, the data_%
1440: 20 74 61 62 6c 65 20 6d 75 73 74 20 61 6c 73 6f   table must also
1450: 20 63 6f 6e 74 61 69 6e 20 61 20 63 6f 6c 75 6d   contain a colum
1460: 6e 20 0a 2a 2a 20 6e 61 6d 65 64 20 22 72 62 75  n .** named "rbu
1470: 5f 72 6f 77 69 64 22 2e 20 54 68 69 73 20 63 6f  _rowid". This co
1480: 6c 75 6d 6e 20 69 73 20 6d 61 70 70 65 64 20 74  lumn is mapped t
1490: 6f 20 74 68 65 20 74 61 62 6c 65 73 20 69 6d 70  o the tables imp
14a0: 6c 69 63 69 74 20 70 72 69 6d 61 72 79 20 0a 2a  licit primary .*
14b0: 2a 20 6b 65 79 20 63 6f 6c 75 6d 6e 20 2d 20 22  * key column - "
14c0: 72 6f 77 69 64 22 2e 20 56 69 72 74 75 61 6c 20  rowid". Virtual 
14d0: 74 61 62 6c 65 73 20 66 6f 72 20 77 68 69 63 68  tables for which
14e0: 20 74 68 65 20 22 72 6f 77 69 64 22 20 63 6f 6c   the "rowid" col
14f0: 75 6d 6e 20 64 6f 65 73 20 0a 2a 2a 20 6e 6f 74  umn does .** not
1500: 20 66 75 6e 63 74 69 6f 6e 20 6c 69 6b 65 20 61   function like a
1510: 20 70 72 69 6d 61 72 79 20 6b 65 79 20 76 61 6c   primary key val
1520: 75 65 20 63 61 6e 6e 6f 74 20 62 65 20 75 70 64  ue cannot be upd
1530: 61 74 65 64 20 75 73 69 6e 67 20 52 42 55 2e 20  ated using RBU. 
1540: 46 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  For .** example,
1550: 20 69 66 20 74 68 65 20 74 61 72 67 65 74 20 64   if the target d
1560: 62 20 63 6f 6e 74 61 69 6e 73 20 65 69 74 68 65  b contains eithe
1570: 72 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  r of the followi
1580: 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 43 52 45 41  ng:.**.**   CREA
1590: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
15a0: 20 78 31 20 55 53 49 4e 47 20 66 74 73 33 28 61   x1 USING fts3(a
15b0: 2c 20 62 29 3b 0a 2a 2a 20 20 20 43 52 45 41 54  , b);.**   CREAT
15c0: 45 20 54 41 42 4c 45 20 78 31 28 61 2c 20 62 29  E TABLE x1(a, b)
15d0: 0a 2a 2a 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  .**.** then the 
15e0: 52 42 55 20 64 61 74 61 62 61 73 65 20 73 68 6f  RBU database sho
15f0: 75 6c 64 20 63 6f 6e 74 61 69 6e 3a 0a 2a 2a 0a  uld contain:.**.
1600: 2a 2a 20 20 20 43 52 45 41 54 45 20 54 41 42 4c  **   CREATE TABL
1610: 45 20 64 61 74 61 5f 78 31 28 61 2c 20 62 2c 20  E data_x1(a, b, 
1620: 72 62 75 5f 72 6f 77 69 64 2c 20 72 62 75 5f 63  rbu_rowid, rbu_c
1630: 6f 6e 74 72 6f 6c 29 3b 0a 2a 2a 0a 2a 2a 20 41  ontrol);.**.** A
1640: 6c 6c 20 6e 6f 6e 2d 68 69 64 64 65 6e 20 63 6f  ll non-hidden co
1650: 6c 75 6d 6e 73 20 28 69 2e 65 2e 20 61 6c 6c 20  lumns (i.e. all 
1660: 63 6f 6c 75 6d 6e 73 20 6d 61 74 63 68 65 64 20  columns matched 
1670: 62 79 20 22 53 45 4c 45 43 54 20 2a 22 29 20 6f  by "SELECT *") o
1680: 66 20 74 68 65 0a 2a 2a 20 74 61 72 67 65 74 20  f the.** target 
1690: 74 61 62 6c 65 20 6d 75 73 74 20 62 65 20 70 72  table must be pr
16a0: 65 73 65 6e 74 20 69 6e 20 74 68 65 20 69 6e 70  esent in the inp
16b0: 75 74 20 74 61 62 6c 65 2e 20 46 6f 72 20 76 69  ut table. For vi
16c0: 72 74 75 61 6c 20 74 61 62 6c 65 73 2c 0a 2a 2a  rtual tables,.**
16d0: 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 20   hidden columns 
16e0: 61 72 65 20 6f 70 74 69 6f 6e 61 6c 20 2d 20 74  are optional - t
16f0: 68 65 79 20 61 72 65 20 75 70 64 61 74 65 64 20  hey are updated 
1700: 62 79 20 52 42 55 20 69 66 20 70 72 65 73 65 6e  by RBU if presen
1710: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 69 6e 70 75  t in.** the inpu
1720: 74 20 74 61 62 6c 65 2c 20 6f 72 20 6e 6f 74 20  t table, or not 
1730: 6f 74 68 65 72 77 69 73 65 2e 20 46 6f 72 20 65  otherwise. For e
1740: 78 61 6d 70 6c 65 2c 20 74 6f 20 77 72 69 74 65  xample, to write
1750: 20 74 6f 20 61 6e 20 66 74 73 34 0a 2a 2a 20 74   to an fts4.** t
1760: 61 62 6c 65 20 77 69 74 68 20 61 20 68 69 64 64  able with a hidd
1770: 65 6e 20 6c 61 6e 67 75 61 67 65 69 64 20 63 6f  en languageid co
1780: 6c 75 6d 6e 20 73 75 63 68 20 61 73 3a 0a 2a 2a  lumn such as:.**
1790: 0a 2a 2a 20 20 20 43 52 45 41 54 45 20 56 49 52  .**   CREATE VIR
17a0: 54 55 41 4c 20 54 41 42 4c 45 20 66 74 31 20 55  TUAL TABLE ft1 U
17b0: 53 49 4e 47 20 66 74 73 34 28 61 2c 20 62 2c 20  SING fts4(a, b, 
17c0: 6c 61 6e 67 75 61 67 65 69 64 3d 27 6c 61 6e 67  languageid='lang
17d0: 69 64 27 29 3b 0a 2a 2a 0a 2a 2a 20 45 69 74 68  id');.**.** Eith
17e0: 65 72 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  er of the follow
17f0: 69 6e 67 20 69 6e 70 75 74 20 74 61 62 6c 65 20  ing input table 
1800: 73 63 68 65 6d 61 73 20 6d 61 79 20 62 65 20 75  schemas may be u
1810: 73 65 64 3a 0a 2a 2a 0a 2a 2a 20 20 20 43 52 45  sed:.**.**   CRE
1820: 41 54 45 20 54 41 42 4c 45 20 64 61 74 61 5f 66  ATE TABLE data_f
1830: 74 31 28 61 2c 20 62 2c 20 6c 61 6e 67 69 64 2c  t1(a, b, langid,
1840: 20 72 62 75 5f 72 6f 77 69 64 2c 20 72 62 75 5f   rbu_rowid, rbu_
1850: 63 6f 6e 74 72 6f 6c 29 3b 0a 2a 2a 20 20 20 43  control);.**   C
1860: 52 45 41 54 45 20 54 41 42 4c 45 20 64 61 74 61  REATE TABLE data
1870: 5f 66 74 31 28 61 2c 20 62 2c 20 72 62 75 5f 72  _ft1(a, b, rbu_r
1880: 6f 77 69 64 2c 20 72 62 75 5f 63 6f 6e 74 72 6f  owid, rbu_contro
1890: 6c 29 3b 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 61  l);.**.** For ea
18a0: 63 68 20 72 6f 77 20 74 6f 20 49 4e 53 45 52 54  ch row to INSERT
18b0: 20 69 6e 74 6f 20 74 68 65 20 74 61 72 67 65 74   into the target
18c0: 20 64 61 74 61 62 61 73 65 20 61 73 20 70 61 72   database as par
18d0: 74 20 6f 66 20 74 68 65 20 52 42 55 20 0a 2a 2a  t of the RBU .**
18e0: 20 75 70 64 61 74 65 2c 20 74 68 65 20 63 6f 72   update, the cor
18f0: 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 5f  responding data_
1900: 25 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 63  % table should c
1910: 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 20  ontain a single 
1920: 72 65 63 6f 72 64 0a 2a 2a 20 77 69 74 68 20 74  record.** with t
1930: 68 65 20 22 72 62 75 5f 63 6f 6e 74 72 6f 6c 22  he "rbu_control"
1940: 20 63 6f 6c 75 6d 6e 20 73 65 74 20 74 6f 20 63   column set to c
1950: 6f 6e 74 61 69 6e 20 69 6e 74 65 67 65 72 20 76  ontain integer v
1960: 61 6c 75 65 20 30 2e 20 54 68 65 0a 2a 2a 20 6f  alue 0. The.** o
1970: 74 68 65 72 20 63 6f 6c 75 6d 6e 73 20 73 68 6f  ther columns sho
1980: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68  uld be set to th
1990: 65 20 76 61 6c 75 65 73 20 74 68 61 74 20 6d 61  e values that ma
19a0: 6b 65 20 75 70 20 74 68 65 20 6e 65 77 20 72 65  ke up the new re
19b0: 63 6f 72 64 20 0a 2a 2a 20 74 6f 20 69 6e 73 65  cord .** to inse
19c0: 72 74 2e 20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rt. .**.** If th
19d0: 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73  e target databas
19e0: 65 20 74 61 62 6c 65 20 68 61 73 20 61 6e 20 49  e table has an I
19f0: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
1a00: 45 59 2c 20 69 74 20 69 73 20 6e 6f 74 20 0a 2a  EY, it is not .*
1a10: 2a 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  * possible to in
1a20: 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75  sert a NULL valu
1a30: 65 20 69 6e 74 6f 20 74 68 65 20 49 50 4b 20 63  e into the IPK c
1a40: 6f 6c 75 6d 6e 2e 20 41 74 74 65 6d 70 74 69 6e  olumn. Attemptin
1a50: 67 20 74 6f 20 0a 2a 2a 20 64 6f 20 73 6f 20 72  g to .** do so r
1a60: 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 53 51 4c  esults in an SQL
1a70: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 65 72 72  ITE_MISMATCH err
1a80: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 61  or..**.** For ea
1a90: 63 68 20 72 6f 77 20 74 6f 20 44 45 4c 45 54 45  ch row to DELETE
1aa0: 20 66 72 6f 6d 20 74 68 65 20 74 61 72 67 65 74   from the target
1ab0: 20 64 61 74 61 62 61 73 65 20 61 73 20 70 61 72   database as par
1ac0: 74 20 6f 66 20 74 68 65 20 52 42 55 20 0a 2a 2a  t of the RBU .**
1ad0: 20 75 70 64 61 74 65 2c 20 74 68 65 20 63 6f 72   update, the cor
1ae0: 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 5f  responding data_
1af0: 25 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 63  % table should c
1b00: 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 20  ontain a single 
1b10: 72 65 63 6f 72 64 0a 2a 2a 20 77 69 74 68 20 74  record.** with t
1b20: 68 65 20 22 72 62 75 5f 63 6f 6e 74 72 6f 6c 22  he "rbu_control"
1b30: 20 63 6f 6c 75 6d 6e 20 73 65 74 20 74 6f 20 63   column set to c
1b40: 6f 6e 74 61 69 6e 20 69 6e 74 65 67 65 72 20 76  ontain integer v
1b50: 61 6c 75 65 20 31 2e 20 54 68 65 0a 2a 2a 20 72  alue 1. The.** r
1b60: 65 61 6c 20 70 72 69 6d 61 72 79 20 6b 65 79 20  eal primary key 
1b70: 76 61 6c 75 65 73 20 6f 66 20 74 68 65 20 72 6f  values of the ro
1b80: 77 20 74 6f 20 64 65 6c 65 74 65 20 73 68 6f 75  w to delete shou
1b90: 6c 64 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  ld be stored in 
1ba0: 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
1bb0: 64 69 6e 67 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ding columns of 
1bc0: 74 68 65 20 64 61 74 61 5f 25 20 74 61 62 6c 65  the data_% table
1bd0: 2e 20 54 68 65 20 76 61 6c 75 65 73 20 73 74 6f  . The values sto
1be0: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 6f 74  red in the.** ot
1bf0: 68 65 72 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20  her columns are 
1c00: 6e 6f 74 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  not used..**.** 
1c10: 46 6f 72 20 65 61 63 68 20 72 6f 77 20 74 6f 20  For each row to 
1c20: 55 50 44 41 54 45 20 66 72 6f 6d 20 74 68 65 20  UPDATE from the 
1c30: 74 61 72 67 65 74 20 64 61 74 61 62 61 73 65 20  target database 
1c40: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 52  as part of the R
1c50: 42 55 20 0a 2a 2a 20 75 70 64 61 74 65 2c 20 74  BU .** update, t
1c60: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
1c70: 20 64 61 74 61 5f 25 20 74 61 62 6c 65 20 73 68   data_% table sh
1c80: 6f 75 6c 64 20 63 6f 6e 74 61 69 6e 20 61 20 73  ould contain a s
1c90: 69 6e 67 6c 65 20 72 65 63 6f 72 64 0a 2a 2a 20  ingle record.** 
1ca0: 77 69 74 68 20 74 68 65 20 22 72 62 75 5f 63 6f  with the "rbu_co
1cb0: 6e 74 72 6f 6c 22 20 63 6f 6c 75 6d 6e 20 73 65  ntrol" column se
1cc0: 74 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 76  t to contain a v
1cd0: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 74 65 78  alue of type tex
1ce0: 74 2e 0a 2a 2a 20 54 68 65 20 72 65 61 6c 20 70  t..** The real p
1cf0: 72 69 6d 61 72 79 20 6b 65 79 20 76 61 6c 75 65  rimary key value
1d00: 73 20 69 64 65 6e 74 69 66 79 69 6e 67 20 74 68  s identifying th
1d10: 65 20 72 6f 77 20 74 6f 20 75 70 64 61 74 65 20  e row to update 
1d20: 73 68 6f 75 6c 64 20 62 65 20 0a 2a 2a 20 73 74  should be .** st
1d30: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 6f 72 72  ored in the corr
1d40: 65 73 70 6f 6e 64 69 6e 67 20 63 6f 6c 75 6d 6e  esponding column
1d50: 73 20 6f 66 20 74 68 65 20 64 61 74 61 5f 25 20  s of the data_% 
1d60: 74 61 62 6c 65 20 72 6f 77 2c 20 61 73 20 73 68  table row, as sh
1d70: 6f 75 6c 64 0a 2a 2a 20 74 68 65 20 6e 65 77 20  ould.** the new 
1d80: 76 61 6c 75 65 73 20 6f 66 20 61 6c 6c 20 63 6f  values of all co
1d90: 6c 75 6d 6e 73 20 62 65 69 6e 67 20 75 70 64 61  lumns being upda
1da0: 74 65 2e 20 54 68 65 20 74 65 78 74 20 76 61 6c  te. The text val
1db0: 75 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 22 72  ue in the .** "r
1dc0: 62 75 5f 63 6f 6e 74 72 6f 6c 22 20 63 6f 6c 75  bu_control" colu
1dd0: 6d 6e 20 6d 75 73 74 20 63 6f 6e 74 61 69 6e 20  mn must contain 
1de0: 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20  the same number 
1df0: 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 61 73  of characters as
1e00: 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 63 6f  .** there are co
1e10: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 74 61 72  lumns in the tar
1e20: 67 65 74 20 64 61 74 61 62 61 73 65 20 74 61 62  get database tab
1e30: 6c 65 2c 20 61 6e 64 20 6d 75 73 74 20 63 6f 6e  le, and must con
1e40: 73 69 73 74 20 65 6e 74 69 72 65 6c 79 0a 2a 2a  sist entirely.**
1e50: 20 6f 66 20 27 78 27 20 61 6e 64 20 27 2e 27 20   of 'x' and '.' 
1e60: 63 68 61 72 61 63 74 65 72 73 20 28 6f 72 20 69  characters (or i
1e70: 6e 20 73 6f 6d 65 20 73 70 65 63 69 61 6c 20 63  n some special c
1e80: 61 73 65 73 20 27 64 27 20 2d 20 73 65 65 20 62  ases 'd' - see b
1e90: 65 6c 6f 77 29 2e 20 46 6f 72 20 0a 2a 2a 20 65  elow). For .** e
1ea0: 61 63 68 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ach column that 
1eb0: 69 73 20 62 65 69 6e 67 20 75 70 64 61 74 65 64  is being updated
1ec0: 2c 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  , the correspond
1ed0: 69 6e 67 20 63 68 61 72 61 63 74 65 72 20 69 73  ing character is
1ee0: 20 73 65 74 20 74 6f 0a 2a 2a 20 27 78 27 2e 20   set to.** 'x'. 
1ef0: 46 6f 72 20 74 68 6f 73 65 20 74 68 61 74 20 72  For those that r
1f00: 65 6d 61 69 6e 20 61 73 20 74 68 65 79 20 61 72  emain as they ar
1f10: 65 2c 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  e, the correspon
1f20: 64 69 6e 67 20 63 68 61 72 61 63 74 65 72 20 6f  ding character o
1f30: 66 20 74 68 65 0a 2a 2a 20 72 62 75 5f 63 6f 6e  f the.** rbu_con
1f40: 74 72 6f 6c 20 76 61 6c 75 65 20 73 68 6f 75 6c  trol value shoul
1f50: 64 20 62 65 20 73 65 74 20 74 6f 20 27 2e 27 2e  d be set to '.'.
1f60: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69   For example, gi
1f70: 76 65 6e 20 74 68 65 20 74 61 62 6c 65 73 20 0a  ven the tables .
1f80: 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 20 75 70  ** above, the up
1f90: 64 61 74 65 20 73 74 61 74 65 6d 65 6e 74 3a 0a  date statement:.
1fa0: 2a 2a 0a 2a 2a 20 20 20 55 50 44 41 54 45 20 74  **.**   UPDATE t
1fb0: 31 20 53 45 54 20 63 20 3d 20 27 75 73 61 27 20  1 SET c = 'usa' 
1fc0: 57 48 45 52 45 20 61 20 3d 20 34 3b 0a 2a 2a 0a  WHERE a = 4;.**.
1fd0: 2a 2a 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ** is represente
1fe0: 64 20 62 79 20 74 68 65 20 64 61 74 61 5f 74 31  d by the data_t1
1ff0: 20 72 6f 77 20 63 72 65 61 74 65 64 20 62 79 3a   row created by:
2000: 0a 2a 2a 0a 2a 2a 20 20 20 49 4e 53 45 52 54 20  .**.**   INSERT 
2010: 49 4e 54 4f 20 64 61 74 61 5f 74 31 28 61 2c 20  INTO data_t1(a, 
2020: 62 2c 20 63 2c 20 72 62 75 5f 63 6f 6e 74 72 6f  b, c, rbu_contro
2030: 6c 29 20 56 41 4c 55 45 53 28 34 2c 20 4e 55 4c  l) VALUES(4, NUL
2040: 4c 2c 20 27 75 73 61 27 2c 20 27 2e 2e 78 27 29  L, 'usa', '..x')
2050: 3b 0a 2a 2a 0a 2a 2a 20 49 6e 73 74 65 61 64 20  ;.**.** Instead 
2060: 6f 66 20 61 6e 20 27 78 27 20 63 68 61 72 61 63  of an 'x' charac
2070: 74 65 72 2c 20 63 68 61 72 61 63 74 65 72 73 20  ter, characters 
2080: 6f 66 20 74 68 65 20 72 62 75 5f 63 6f 6e 74 72  of the rbu_contr
2090: 6f 6c 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  ol value specifi
20a0: 65 64 0a 2a 2a 20 66 6f 72 20 55 50 44 41 54 45  ed.** for UPDATE
20b0: 73 20 6d 61 79 20 61 6c 73 6f 20 62 65 20 73 65  s may also be se
20c0: 74 20 74 6f 20 27 64 27 2e 20 49 6e 20 74 68 69  t to 'd'. In thi
20d0: 73 20 63 61 73 65 2c 20 69 6e 73 74 65 61 64 20  s case, instead 
20e0: 6f 66 20 75 70 64 61 74 69 6e 67 20 74 68 65 0a  of updating the.
20f0: 2a 2a 20 74 61 72 67 65 74 20 74 61 62 6c 65 20  ** target table 
2100: 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 73  with the value s
2110: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 6f 72  tored in the cor
2120: 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 5f  responding data_
2130: 25 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 0a 2a 2a  % column, the.**
2140: 20 75 73 65 72 2d 64 65 66 69 6e 65 64 20 53 51   user-defined SQ
2150: 4c 20 66 75 6e 63 74 69 6f 6e 20 22 72 62 75 5f  L function "rbu_
2160: 64 65 6c 74 61 28 29 22 20 69 73 20 69 6e 76 6f  delta()" is invo
2170: 6b 65 64 20 61 6e 64 20 74 68 65 20 72 65 73 75  ked and the resu
2180: 6c 74 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20  lt stored in.** 
2190: 74 68 65 20 74 61 72 67 65 74 20 74 61 62 6c 65  the target table
21a0: 20 63 6f 6c 75 6d 6e 2e 20 72 62 75 5f 64 65 6c   column. rbu_del
21b0: 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ta() is invoked 
21c0: 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
21d0: 74 73 20 2d 20 74 68 65 0a 2a 2a 20 6f 72 69 67  ts - the.** orig
21e0: 69 6e 61 6c 20 76 61 6c 75 65 20 63 75 72 72 65  inal value curre
21f0: 6e 74 6c 79 20 73 74 6f 72 65 64 20 69 6e 20 74  ntly stored in t
2200: 68 65 20 74 61 72 67 65 74 20 74 61 62 6c 65 20  he target table 
2210: 63 6f 6c 75 6d 6e 20 61 6e 64 20 74 68 65 20 0a  column and the .
2220: 2a 2a 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  ** value specifi
2230: 65 64 20 69 6e 20 74 68 65 20 64 61 74 61 5f 78  ed in the data_x
2240: 78 78 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  xx table..**.** 
2250: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 69  For example, thi
2260: 73 20 72 6f 77 3a 0a 2a 2a 0a 2a 2a 20 20 20 49  s row:.**.**   I
2270: 4e 53 45 52 54 20 49 4e 54 4f 20 64 61 74 61 5f  NSERT INTO data_
2280: 74 31 28 61 2c 20 62 2c 20 63 2c 20 72 62 75 5f  t1(a, b, c, rbu_
2290: 63 6f 6e 74 72 6f 6c 29 20 56 41 4c 55 45 53 28  control) VALUES(
22a0: 34 2c 20 4e 55 4c 4c 2c 20 27 75 73 61 27 2c 20  4, NULL, 'usa', 
22b0: 27 2e 2e 64 27 29 3b 0a 2a 2a 0a 2a 2a 20 69 73  '..d');.**.** is
22c0: 20 73 69 6d 69 6c 61 72 20 74 6f 20 61 6e 20 55   similar to an U
22d0: 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 20  PDATE statement 
22e0: 73 75 63 68 20 61 73 3a 20 0a 2a 2a 0a 2a 2a 20  such as: .**.** 
22f0: 20 20 55 50 44 41 54 45 20 74 31 20 53 45 54 20    UPDATE t1 SET 
2300: 63 20 3d 20 72 62 75 5f 64 65 6c 74 61 28 63 2c  c = rbu_delta(c,
2310: 20 27 75 73 61 27 29 20 57 48 45 52 45 20 61 20   'usa') WHERE a 
2320: 3d 20 34 3b 0a 2a 2a 0a 2a 2a 20 46 69 6e 61 6c  = 4;.**.** Final
2330: 6c 79 2c 20 69 66 20 61 6e 20 27 66 27 20 63 68  ly, if an 'f' ch
2340: 61 72 61 63 74 65 72 20 61 70 70 65 61 72 73 20  aracter appears 
2350: 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 27 64  in place of a 'd
2360: 27 20 6f 72 20 27 73 27 20 69 6e 20 61 6e 20 0a  ' or 's' in an .
2370: 2a 2a 20 6f 74 61 5f 63 6f 6e 74 72 6f 6c 20 73  ** ota_control s
2380: 74 72 69 6e 67 2c 20 74 68 65 20 63 6f 6e 74 65  tring, the conte
2390: 6e 74 73 20 6f 66 20 74 68 65 20 64 61 74 61 5f  nts of the data_
23a0: 78 78 78 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  xxx table column
23b0: 20 69 73 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74   is assumed.** t
23c0: 6f 20 62 65 20 61 20 22 66 6f 73 73 69 6c 20 64  o be a "fossil d
23d0: 65 6c 74 61 22 20 2d 20 61 20 70 61 74 63 68 20  elta" - a patch 
23e0: 74 6f 20 62 65 20 61 70 70 6c 69 65 64 20 74 6f  to be applied to
23f0: 20 61 20 62 6c 6f 62 20 76 61 6c 75 65 20 69 6e   a blob value in
2400: 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 75   the.** format u
2410: 73 65 64 20 62 79 20 74 68 65 20 66 6f 73 73 69  sed by the fossi
2420: 6c 20 73 6f 75 72 63 65 2d 63 6f 64 65 20 6d 61  l source-code ma
2430: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
2440: 20 49 6e 20 74 68 69 73 20 63 61 73 65 0a 2a 2a   In this case.**
2450: 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 76 61   the existing va
2460: 6c 75 65 20 77 69 74 68 69 6e 20 74 68 65 20 74  lue within the t
2470: 61 72 67 65 74 20 64 61 74 61 62 61 73 65 20 74  arget database t
2480: 61 62 6c 65 20 6d 75 73 74 20 62 65 20 6f 66 20  able must be of 
2490: 74 79 70 65 20 42 4c 4f 42 2e 20 0a 2a 2a 20 49  type BLOB. .** I
24a0: 74 20 69 73 20 72 65 70 6c 61 63 65 64 20 62 79  t is replaced by
24b0: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 61   the result of a
24c0: 70 70 6c 79 69 6e 67 20 74 68 65 20 73 70 65 63  pplying the spec
24d0: 69 66 69 65 64 20 66 6f 73 73 69 6c 20 64 65 6c  ified fossil del
24e0: 74 61 20 74 6f 0a 2a 2a 20 69 74 73 65 6c 66 2e  ta to.** itself.
24f0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 74 61  .**.** If the ta
2500: 72 67 65 74 20 64 61 74 61 62 61 73 65 20 74 61  rget database ta
2510: 62 6c 65 20 69 73 20 61 20 76 69 72 74 75 61 6c  ble is a virtual
2520: 20 74 61 62 6c 65 20 6f 72 20 61 20 74 61 62 6c   table or a tabl
2530: 65 20 77 69 74 68 20 6e 6f 20 50 52 49 4d 41 52  e with no PRIMAR
2540: 59 0a 2a 2a 20 4b 45 59 2c 20 74 68 65 20 72 62  Y.** KEY, the rb
2550: 75 5f 63 6f 6e 74 72 6f 6c 20 76 61 6c 75 65 20  u_control value 
2560: 73 68 6f 75 6c 64 20 6e 6f 74 20 69 6e 63 6c 75  should not inclu
2570: 64 65 20 61 20 63 68 61 72 61 63 74 65 72 20 63  de a character c
2580: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a  orresponding .**
2590: 20 74 6f 20 74 68 65 20 72 62 75 5f 72 6f 77 69   to the rbu_rowi
25a0: 64 20 76 61 6c 75 65 2e 20 46 6f 72 20 65 78 61  d value. For exa
25b0: 6d 70 6c 65 2c 20 74 68 69 73 3a 0a 2a 2a 0a 2a  mple, this:.**.*
25c0: 2a 20 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  *   INSERT INTO 
25d0: 64 61 74 61 5f 66 74 31 28 61 2c 20 62 2c 20 72  data_ft1(a, b, r
25e0: 62 75 5f 72 6f 77 69 64 2c 20 72 62 75 5f 63 6f  bu_rowid, rbu_co
25f0: 6e 74 72 6f 6c 29 20 0a 2a 2a 20 20 20 20 20 20  ntrol) .**      
2600: 20 56 41 4c 55 45 53 28 4e 55 4c 4c 2c 20 27 75   VALUES(NULL, 'u
2610: 73 61 27 2c 20 31 32 2c 20 27 2e 78 27 29 3b 0a  sa', 12, '.x');.
2620: 2a 2a 0a 2a 2a 20 63 61 75 73 65 73 20 61 20 72  **.** causes a r
2630: 65 73 75 6c 74 20 73 69 6d 69 6c 61 72 20 74 6f  esult similar to
2640: 3a 0a 2a 2a 0a 2a 2a 20 20 20 55 50 44 41 54 45  :.**.**   UPDATE
2650: 20 66 74 31 20 53 45 54 20 62 20 3d 20 27 75 73   ft1 SET b = 'us
2660: 61 27 20 57 48 45 52 45 20 72 6f 77 69 64 20 3d  a' WHERE rowid =
2670: 20 31 32 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64   12;.**.** The d
2680: 61 74 61 5f 78 78 78 20 74 61 62 6c 65 73 20 74  ata_xxx tables t
2690: 68 65 6d 73 65 6c 76 65 73 20 73 68 6f 75 6c 64  hemselves should
26a0: 20 68 61 76 65 20 6e 6f 20 50 52 49 4d 41 52 59   have no PRIMARY
26b0: 20 4b 45 59 20 64 65 63 6c 61 72 61 74 69 6f 6e   KEY declaration
26c0: 73 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 52  s..** However, R
26d0: 42 55 20 69 73 20 6d 6f 72 65 20 65 66 66 69 63  BU is more effic
26e0: 69 65 6e 74 20 69 66 20 72 65 61 64 69 6e 67 20  ient if reading 
26f0: 74 68 65 20 72 6f 77 73 20 69 6e 20 66 72 6f 6d  the rows in from
2700: 20 65 61 63 68 20 64 61 74 61 5f 78 78 78 0a 2a   each data_xxx.*
2710: 2a 20 74 61 62 6c 65 20 69 6e 20 22 72 6f 77 69  * table in "rowi
2720: 64 22 20 6f 72 64 65 72 20 69 73 20 72 6f 75 67  d" order is roug
2730: 68 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  hly the same as 
2740: 72 65 61 64 69 6e 67 20 74 68 65 6d 20 73 6f 72  reading them sor
2750: 74 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 50 52  ted by.** the PR
2760: 49 4d 41 52 59 20 4b 45 59 20 6f 66 20 74 68 65  IMARY KEY of the
2770: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 74   corresponding t
2780: 61 72 67 65 74 20 64 61 74 61 62 61 73 65 20 74  arget database t
2790: 61 62 6c 65 2e 20 49 6e 20 6f 74 68 65 72 20 0a  able. In other .
27a0: 2a 2a 20 77 6f 72 64 73 2c 20 72 6f 77 73 20 73  ** words, rows s
27b0: 68 6f 75 6c 64 20 62 65 20 73 6f 72 74 65 64 20  hould be sorted 
27c0: 75 73 69 6e 67 20 74 68 65 20 64 65 73 74 69 6e  using the destin
27d0: 61 74 69 6f 6e 20 74 61 62 6c 65 20 50 52 49 4d  ation table PRIM
27e0: 41 52 59 20 4b 45 59 20 0a 2a 2a 20 66 69 65 6c  ARY KEY .** fiel
27f0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 79 20 61  ds before they a
2800: 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  re inserted into
2810: 20 74 68 65 20 64 61 74 61 5f 78 78 78 20 74 61   the data_xxx ta
2820: 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 53 41 47  bles..**.** USAG
2830: 45 0a 2a 2a 0a 2a 2a 20 54 68 65 20 41 50 49 20  E.**.** The API 
2840: 64 65 63 6c 61 72 65 64 20 62 65 6c 6f 77 20 61  declared below a
2850: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
2860: 74 69 6f 6e 20 74 6f 20 61 70 70 6c 79 20 61 6e  tion to apply an
2870: 20 52 42 55 20 75 70 64 61 74 65 20 0a 2a 2a 20   RBU update .** 
2880: 73 74 6f 72 65 64 20 6f 6e 20 64 69 73 6b 20 74  stored on disk t
2890: 6f 20 61 6e 20 65 78 69 73 74 69 6e 67 20 74 61  o an existing ta
28a0: 72 67 65 74 20 64 61 74 61 62 61 73 65 2e 20 45  rget database. E
28b0: 73 73 65 6e 74 69 61 6c 6c 79 2c 20 74 68 65 20  ssentially, the 
28c0: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 3a  .** application:
28d0: 0a 2a 2a 0a 2a 2a 20 20 20 20 20 31 29 20 4f 70  .**.**     1) Op
28e0: 65 6e 73 20 61 6e 20 52 42 55 20 68 61 6e 64 6c  ens an RBU handl
28f0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  e using the sqli
2900: 74 65 33 72 62 75 5f 6f 70 65 6e 28 29 20 66 75  te3rbu_open() fu
2910: 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 20 20  nction..**.**   
2920: 20 20 32 29 20 52 65 67 69 73 74 65 72 73 20 61    2) Registers a
2930: 6e 79 20 72 65 71 75 69 72 65 64 20 76 69 72 74  ny required virt
2940: 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
2950: 73 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  s with the datab
2960: 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 68 61  ase.**        ha
2970: 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79  ndle returned by
2980: 20 73 71 6c 69 74 65 33 72 62 75 5f 64 62 28 29   sqlite3rbu_db()
2990: 2e 20 41 6c 73 6f 2c 20 69 66 20 72 65 71 75 69  . Also, if requi
29a0: 72 65 64 2c 20 72 65 67 69 73 74 65 72 0a 2a 2a  red, register.**
29b0: 20 20 20 20 20 20 20 20 74 68 65 20 72 62 75 5f          the rbu_
29c0: 64 65 6c 74 61 28 29 20 69 6d 70 6c 65 6d 65 6e  delta() implemen
29d0: 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 20 20  tation..**.**   
29e0: 20 20 33 29 20 43 61 6c 6c 73 20 74 68 65 20 73    3) Calls the s
29f0: 71 6c 69 74 65 33 72 62 75 5f 73 74 65 70 28 29  qlite3rbu_step()
2a00: 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 65 20 6f 72   function one or
2a10: 20 6d 6f 72 65 20 74 69 6d 65 73 20 6f 6e 0a 2a   more times on.*
2a20: 2a 20 20 20 20 20 20 20 20 74 68 65 20 6e 65 77  *        the new
2a30: 20 68 61 6e 64 6c 65 2e 20 45 61 63 68 20 63 61   handle. Each ca
2a40: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 72 62 75  ll to sqlite3rbu
2a50: 5f 73 74 65 70 28 29 20 70 65 72 66 6f 72 6d 73  _step() performs
2a60: 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 20 20 20   a single.**    
2a70: 20 20 20 20 62 2d 74 72 65 65 20 6f 70 65 72 61      b-tree opera
2a80: 74 69 6f 6e 2c 20 73 6f 20 74 68 6f 75 73 61 6e  tion, so thousan
2a90: 64 73 20 6f 66 20 63 61 6c 6c 73 20 6d 61 79 20  ds of calls may 
2aa0: 62 65 20 72 65 71 75 69 72 65 64 20 74 6f 20 61  be required to a
2ab0: 70 70 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  pply .**        
2ac0: 61 20 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  a complete updat
2ad0: 65 2e 0a 2a 2a 0a 2a 2a 20 20 20 20 20 34 29 20  e..**.**     4) 
2ae0: 43 61 6c 6c 73 20 73 71 6c 69 74 65 33 72 62 75  Calls sqlite3rbu
2af0: 5f 63 6c 6f 73 65 28 29 20 74 6f 20 63 6c 6f 73  _close() to clos
2b00: 65 20 74 68 65 20 52 42 55 20 75 70 64 61 74 65  e the RBU update
2b10: 20 68 61 6e 64 6c 65 2e 20 49 66 0a 2a 2a 20 20   handle. If.**  
2b20: 20 20 20 20 20 20 73 71 6c 69 74 65 33 72 62 75        sqlite3rbu
2b30: 5f 73 74 65 70 28 29 20 68 61 73 20 62 65 65 6e  _step() has been
2b40: 20 63 61 6c 6c 65 64 20 65 6e 6f 75 67 68 20 74   called enough t
2b50: 69 6d 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 65  imes to complete
2b60: 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 61 70 70  ly.**        app
2b70: 6c 79 20 74 68 65 20 75 70 64 61 74 65 20 74 6f  ly the update to
2b80: 20 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61   the target data
2b90: 62 61 73 65 2c 20 74 68 65 6e 20 74 68 65 20 52  base, then the R
2ba0: 42 55 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20  BU database.**  
2bb0: 20 20 20 20 20 20 69 73 20 6d 61 72 6b 65 64 20        is marked 
2bc0: 61 73 20 66 75 6c 6c 79 20 61 70 70 6c 69 65 64  as fully applied
2bd0: 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65  . Otherwise, the
2be0: 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 52 42   state of the RB
2bf0: 55 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 64  U .**        upd
2c00: 61 74 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ate application 
2c10: 69 73 20 73 61 76 65 64 20 69 6e 20 74 68 65 20  is saved in the 
2c20: 52 42 55 20 64 61 74 61 62 61 73 65 20 66 6f 72  RBU database for
2c30: 20 6c 61 74 65 72 20 0a 2a 2a 20 20 20 20 20 20   later .**      
2c40: 20 20 72 65 73 75 6d 70 74 69 6f 6e 2e 0a 2a 2a    resumption..**
2c50: 0a 2a 2a 20 53 65 65 20 63 6f 6d 6d 65 6e 74 73  .** See comments
2c60: 20 62 65 6c 6f 77 20 66 6f 72 20 6d 6f 72 65 20   below for more 
2c70: 64 65 74 61 69 6c 20 6f 6e 20 41 50 49 73 2e 0a  detail on APIs..
2c80: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 75 70 64 61  **.** If an upda
2c90: 74 65 20 69 73 20 6f 6e 6c 79 20 70 61 72 74 69  te is only parti
2ca0: 61 6c 6c 79 20 61 70 70 6c 69 65 64 20 74 6f 20  ally applied to 
2cb0: 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62  the target datab
2cc0: 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 74 69  ase by the.** ti
2cd0: 6d 65 20 73 71 6c 69 74 65 33 72 62 75 5f 63 6c  me sqlite3rbu_cl
2ce0: 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  ose() is called,
2cf0: 20 76 61 72 69 6f 75 73 20 73 74 61 74 65 20 69   various state i
2d00: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 73 61  nformation is sa
2d10: 76 65 64 20 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ved .** within t
2d20: 68 65 20 52 42 55 20 64 61 74 61 62 61 73 65 2e  he RBU database.
2d30: 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 73 75 62   This allows sub
2d40: 73 65 71 75 65 6e 74 20 70 72 6f 63 65 73 73 65  sequent processe
2d50: 73 20 74 6f 20 61 75 74 6f 6d 61 74 69 63 61 6c  s to automatical
2d60: 6c 79 0a 2a 2a 20 72 65 73 75 6d 65 20 74 68 65  ly.** resume the
2d70: 20 52 42 55 20 75 70 64 61 74 65 20 66 72 6f 6d   RBU update from
2d80: 20 77 68 65 72 65 20 69 74 20 6c 65 66 74 20 6f   where it left o
2d90: 66 66 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 72 65 6d  ff..**.** To rem
2da0: 6f 76 65 20 61 6c 6c 20 52 42 55 20 65 78 74 65  ove all RBU exte
2db0: 6e 73 69 6f 6e 20 73 74 61 74 65 20 69 6e 66 6f  nsion state info
2dc0: 72 6d 61 74 69 6f 6e 2c 20 72 65 74 75 72 6e 69  rmation, returni
2dd0: 6e 67 20 61 6e 20 52 42 55 20 64 61 74 61 62 61  ng an RBU databa
2de0: 73 65 20 0a 2a 2a 20 74 6f 20 69 74 73 20 6f 72  se .** to its or
2df0: 69 67 69 6e 61 6c 20 63 6f 6e 74 65 6e 74 73 2c  iginal contents,
2e00: 20 69 74 20 69 73 20 73 75 66 66 69 63 69 65 6e   it is sufficien
2e10: 74 20 74 6f 20 64 72 6f 70 20 61 6c 6c 20 74 61  t to drop all ta
2e20: 62 6c 65 73 20 74 68 61 74 20 62 65 67 69 6e 0a  bles that begin.
2e30: 2a 2a 20 77 69 74 68 20 74 68 65 20 70 72 65 66  ** with the pref
2e40: 69 78 20 22 72 62 75 5f 22 0a 2a 2a 0a 2a 2a 20  ix "rbu_".**.** 
2e50: 44 41 54 41 42 41 53 45 20 4c 4f 43 4b 49 4e 47  DATABASE LOCKING
2e60: 0a 2a 2a 0a 2a 2a 20 41 6e 20 52 42 55 20 75 70  .**.** An RBU up
2e70: 64 61 74 65 20 6d 61 79 20 6e 6f 74 20 62 65 20  date may not be 
2e80: 61 70 70 6c 69 65 64 20 74 6f 20 61 20 64 61 74  applied to a dat
2e90: 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f 64  abase in WAL mod
2ea0: 65 2e 20 41 74 74 65 6d 70 74 69 6e 67 0a 2a 2a  e. Attempting.**
2eb0: 20 74 6f 20 64 6f 20 73 6f 20 69 73 20 61 6e 20   to do so is an 
2ec0: 65 72 72 6f 72 20 28 53 51 4c 49 54 45 5f 45 52  error (SQLITE_ER
2ed0: 52 4f 52 29 2e 0a 2a 2a 0a 2a 2a 20 57 68 69 6c  ROR)..**.** Whil
2ee0: 65 20 61 6e 20 52 42 55 20 68 61 6e 64 6c 65 20  e an RBU handle 
2ef0: 69 73 20 6f 70 65 6e 2c 20 61 20 53 48 41 52 45  is open, a SHARE
2f00: 44 20 6c 6f 63 6b 20 6d 61 79 20 62 65 20 68 65  D lock may be he
2f10: 6c 64 20 6f 6e 20 74 68 65 20 74 61 72 67 65 74  ld on the target
2f20: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
2f30: 65 2e 20 54 68 69 73 20 6d 65 61 6e 73 20 69 74  e. This means it
2f40: 20 69 73 20 70 6f 73 73 69 62 6c 65 20 66 6f 72   is possible for
2f50: 20 6f 74 68 65 72 20 63 6c 69 65 6e 74 73 20 74   other clients t
2f60: 6f 20 72 65 61 64 20 74 68 65 0a 2a 2a 20 64 61  o read the.** da
2f70: 74 61 62 61 73 65 2c 20 62 75 74 20 6e 6f 74 20  tabase, but not 
2f80: 74 6f 20 77 72 69 74 65 20 69 74 2e 0a 2a 2a 0a  to write it..**.
2f90: 2a 2a 20 49 66 20 61 6e 20 52 42 55 20 75 70 64  ** If an RBU upd
2fa0: 61 74 65 20 69 73 20 73 74 61 72 74 65 64 20 61  ate is started a
2fb0: 6e 64 20 74 68 65 6e 20 73 75 73 70 65 6e 64 65  nd then suspende
2fc0: 64 20 62 65 66 6f 72 65 20 69 74 20 69 73 20 63  d before it is c
2fd0: 6f 6d 70 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 65  ompleted,.** the
2fe0: 6e 20 61 6e 20 65 78 74 65 72 6e 61 6c 20 63 6c  n an external cl
2ff0: 69 65 6e 74 20 77 72 69 74 65 73 20 74 6f 20 74  ient writes to t
3000: 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 68 65  he database, the
3010: 6e 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  n attempting to 
3020: 72 65 73 75 6d 65 0a 2a 2a 20 74 68 65 20 73 75  resume.** the su
3030: 73 70 65 6e 64 65 64 20 52 42 55 20 75 70 64 61  spended RBU upda
3040: 74 65 20 69 73 20 61 6c 73 6f 20 61 6e 20 65 72  te is also an er
3050: 72 6f 72 20 28 53 51 4c 49 54 45 5f 42 55 53 59  ror (SQLITE_BUSY
3060: 29 2e 0a 2a 2f 0a 0a 23 69 66 6e 64 65 66 20 5f  )..*/..#ifndef _
3070: 53 51 4c 49 54 45 33 52 42 55 5f 48 0a 23 64 65  SQLITE3RBU_H.#de
3080: 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 52 42 55  fine _SQLITE3RBU
3090: 5f 48 0a 0a 23 69 6e 63 6c 75 64 65 20 22 73 71  _H..#include "sq
30a0: 6c 69 74 65 33 2e 68 22 20 20 20 20 20 20 20 20  lite3.h"        
30b0: 20 20 20 20 20 20 2f 2a 20 52 65 71 75 69 72 65        /* Require
30c0: 64 20 66 6f 72 20 65 72 72 6f 72 20 63 6f 64 65  d for error code
30d0: 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 2a 2f 0a   definitions */.
30e0: 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70  .#ifdef __cplusp
30f0: 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b  lus.extern "C" {
3100: 0a 23 65 6e 64 69 66 0a 0a 74 79 70 65 64 65 66  .#endif..typedef
3110: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 72   struct sqlite3r
3120: 62 75 20 73 71 6c 69 74 65 33 72 62 75 3b 0a 0a  bu sqlite3rbu;..
3130: 2f 2a 0a 2a 2a 20 4f 70 65 6e 20 61 6e 20 52 42  /*.** Open an RB
3140: 55 20 68 61 6e 64 6c 65 2e 0a 2a 2a 0a 2a 2a 20  U handle..**.** 
3150: 41 72 67 75 6d 65 6e 74 20 7a 54 61 72 67 65 74  Argument zTarget
3160: 20 69 73 20 74 68 65 20 70 61 74 68 20 74 6f 20   is the path to 
3170: 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62  the target datab
3180: 61 73 65 2e 20 41 72 67 75 6d 65 6e 74 20 7a 52  ase. Argument zR
3190: 62 75 20 69 73 0a 2a 2a 20 74 68 65 20 70 61 74  bu is.** the pat
31a0: 68 20 74 6f 20 74 68 65 20 52 42 55 20 64 61 74  h to the RBU dat
31b0: 61 62 61 73 65 2e 20 45 61 63 68 20 63 61 6c 6c  abase. Each call
31c0: 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
31d0: 6e 20 6d 75 73 74 20 62 65 20 6d 61 74 63 68 65  n must be matche
31e0: 64 0a 2a 2a 20 62 79 20 61 20 63 61 6c 6c 20 74  d.** by a call t
31f0: 6f 20 73 71 6c 69 74 65 33 72 62 75 5f 63 6c 6f  o sqlite3rbu_clo
3200: 73 65 28 29 2e 20 57 68 65 6e 20 6f 70 65 6e 69  se(). When openi
3210: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 73  ng the databases
3220: 2c 20 52 42 55 20 70 61 73 73 65 73 0a 2a 2a 20  , RBU passes.** 
3230: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
3240: 47 5f 55 52 49 20 66 6c 61 67 20 74 6f 20 73 71  G_URI flag to sq
3250: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
3260: 20 53 6f 20 69 66 20 65 69 74 68 65 72 20 7a 54   So if either zT
3270: 61 72 67 65 74 0a 2a 2a 20 6f 72 20 7a 52 62 75  arget.** or zRbu
3280: 20 62 65 67 69 6e 20 77 69 74 68 20 22 66 69 6c   begin with "fil
3290: 65 3a 22 2c 20 69 74 20 77 69 6c 6c 20 62 65 20  e:", it will be 
32a0: 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
32b0: 6e 20 53 51 4c 69 74 65 20 0a 2a 2a 20 64 61 74  n SQLite .** dat
32c0: 61 62 61 73 65 20 55 52 49 2c 20 6e 6f 74 20 61  abase URI, not a
32d0: 20 72 65 67 75 6c 61 72 20 66 69 6c 65 20 6e 61   regular file na
32e0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  me..**.** If the
32f0: 20 7a 53 74 61 74 65 20 61 72 67 75 6d 65 6e 74   zState argument
3300: 20 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c   is passed a NUL
3310: 4c 20 76 61 6c 75 65 2c 20 74 68 65 20 52 42 55  L value, the RBU
3320: 20 65 78 74 65 6e 73 69 6f 6e 20 73 74 6f 72 65   extension store
3330: 73 20 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e  s .** the curren
3340: 74 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 75  t state of the u
3350: 70 64 61 74 65 20 28 68 6f 77 20 6d 61 6e 79 20  pdate (how many 
3360: 72 6f 77 73 20 68 61 76 65 20 62 65 65 6e 20 75  rows have been u
3370: 70 64 61 74 65 64 2c 20 77 68 69 63 68 20 0a 2a  pdated, which .*
3380: 2a 20 69 6e 64 65 78 65 73 20 61 72 65 20 79 65  * indexes are ye
3390: 74 20 74 6f 20 62 65 20 75 70 64 61 74 65 64 20  t to be updated 
33a0: 65 74 63 2e 29 20 77 69 74 68 69 6e 20 74 68 65  etc.) within the
33b0: 20 52 42 55 20 64 61 74 61 62 61 73 65 20 69 74   RBU database it
33c0: 73 65 6c 66 2e 20 54 68 69 73 0a 2a 2a 20 63 61  self. This.** ca
33d0: 6e 20 62 65 20 63 6f 6e 76 65 6e 69 65 6e 74 2c  n be convenient,
33e0: 20 61 73 20 69 74 20 6d 65 61 6e 73 20 74 68 61   as it means tha
33f0: 74 20 74 68 65 20 52 42 55 20 61 70 70 6c 69 63  t the RBU applic
3400: 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
3410: 65 65 64 20 74 6f 0a 2a 2a 20 6f 72 67 61 6e 69  eed to.** organi
3420: 7a 65 20 72 65 6d 6f 76 69 6e 67 20 61 20 73 65  ze removing a se
3430: 70 61 72 61 74 65 20 73 74 61 74 65 20 66 69 6c  parate state fil
3440: 65 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  e after the upda
3450: 74 65 20 69 73 20 63 6f 6e 63 6c 75 64 65 64 2e  te is concluded.
3460: 20 0a 2a 2a 20 4f 72 2c 20 69 66 20 7a 53 74 61   .** Or, if zSta
3470: 74 65 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2c 20  te is non-NULL, 
3480: 69 74 20 6d 75 73 74 20 62 65 20 61 20 70 61 74  it must be a pat
3490: 68 20 74 6f 20 61 20 64 61 74 61 62 61 73 65 20  h to a database 
34a0: 66 69 6c 65 20 69 6e 20 77 68 69 63 68 20 0a 2a  file in which .*
34b0: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
34c0: 69 6f 6e 20 63 61 6e 20 73 74 6f 72 65 20 74 68  ion can store th
34d0: 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 75  e state of the u
34e0: 70 64 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  pdate..**.** Whe
34f0: 6e 20 72 65 73 75 6d 69 6e 67 20 61 6e 20 52 42  n resuming an RB
3500: 55 20 75 70 64 61 74 65 2c 20 74 68 65 20 7a 53  U update, the zS
3510: 74 61 74 65 20 61 72 67 75 6d 65 6e 74 20 6d 75  tate argument mu
3520: 73 74 20 62 65 20 70 61 73 73 65 64 20 74 68 65  st be passed the
3530: 20 73 61 6d 65 0a 2a 2a 20 76 61 6c 75 65 20 61   same.** value a
3540: 73 20 77 68 65 6e 20 74 68 65 20 52 42 55 20 75  s when the RBU u
3550: 70 64 61 74 65 20 77 61 73 20 73 74 61 72 74 65  pdate was starte
3560: 64 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65 20 74 68  d..**.** Once th
3570: 65 20 52 42 55 20 75 70 64 61 74 65 20 69 73 20  e RBU update is 
3580: 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 52 42  finished, the RB
3590: 55 20 65 78 74 65 6e 73 69 6f 6e 20 64 6f 65 73  U extension does
35a0: 20 6e 6f 74 20 0a 2a 2a 20 61 75 74 6f 6d 61 74   not .** automat
35b0: 69 63 61 6c 6c 79 20 72 65 6d 6f 76 65 20 61 6e  ically remove an
35c0: 79 20 7a 53 74 61 74 65 20 64 61 74 61 62 61 73  y zState databas
35d0: 65 20 66 69 6c 65 2c 20 65 76 65 6e 20 69 66 20  e file, even if 
35e0: 69 74 20 63 72 65 61 74 65 64 20 69 74 2e 0a 2a  it created it..*
35f0: 2a 0a 2a 2a 20 42 79 20 64 65 66 61 75 6c 74 2c  *.** By default,
3600: 20 52 42 55 20 75 73 65 73 20 74 68 65 20 64 65   RBU uses the de
3610: 66 61 75 6c 74 20 56 46 53 20 74 6f 20 61 63 63  fault VFS to acc
3620: 65 73 73 20 74 68 65 20 66 69 6c 65 73 20 6f 6e  ess the files on
3630: 20 64 69 73 6b 2e 20 54 6f 0a 2a 2a 20 75 73 65   disk. To.** use
3640: 20 61 20 56 46 53 20 6f 74 68 65 72 20 74 68 61   a VFS other tha
3650: 6e 20 74 68 65 20 64 65 66 61 75 6c 74 2c 20 61  n the default, a
3660: 6e 20 53 51 4c 69 74 65 20 22 66 69 6c 65 3a 22  n SQLite "file:"
3670: 20 55 52 49 20 63 6f 6e 74 61 69 6e 69 6e 67 20   URI containing 
3680: 61 0a 2a 2a 20 22 76 66 73 3d 2e 2e 2e 22 20 6f  a.** "vfs=..." o
3690: 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 70 61 73  ption may be pas
36a0: 73 65 64 20 61 73 20 74 68 65 20 7a 54 61 72 67  sed as the zTarg
36b0: 65 74 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  et option..**.**
36c0: 20 49 4d 50 4f 52 54 41 4e 54 20 4e 4f 54 45 20   IMPORTANT NOTE 
36d0: 46 4f 52 20 5a 49 50 56 46 53 20 55 53 45 52 53  FOR ZIPVFS USERS
36e0: 3a 20 54 68 65 20 52 42 55 20 65 78 74 65 6e 73  : The RBU extens
36f0: 69 6f 6e 20 77 6f 72 6b 73 20 77 69 74 68 20 61  ion works with a
3700: 6c 6c 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 27  ll of.** SQLite'
3710: 73 20 62 75 69 6c 74 2d 69 6e 20 56 46 53 73 2c  s built-in VFSs,
3720: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 6d   including the m
3730: 75 6c 74 69 70 6c 65 78 6f 72 20 56 46 53 2e 20  ultiplexor VFS. 
3740: 48 6f 77 65 76 65 72 20 69 74 20 64 6f 65 73 0a  However it does.
3750: 2a 2a 20 6e 6f 74 20 77 6f 72 6b 20 6f 75 74 20  ** not work out 
3760: 6f 66 20 74 68 65 20 62 6f 78 20 77 69 74 68 20  of the box with 
3770: 7a 69 70 76 66 73 2e 20 52 65 66 65 72 20 74 6f  zipvfs. Refer to
3780: 20 74 68 65 20 63 6f 6d 6d 65 6e 74 20 64 65 73   the comment des
3790: 63 72 69 62 69 6e 67 0a 2a 2a 20 74 68 65 20 7a  cribing.** the z
37a0: 69 70 76 66 73 5f 63 72 65 61 74 65 5f 76 66 73  ipvfs_create_vfs
37b0: 28 29 20 41 50 49 20 62 65 6c 6f 77 20 66 6f 72  () API below for
37c0: 20 64 65 74 61 69 6c 73 20 6f 6e 20 75 73 69 6e   details on usin
37d0: 67 20 52 42 55 20 77 69 74 68 20 7a 69 70 76 66  g RBU with zipvf
37e0: 73 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 72 62 75  s..*/.sqlite3rbu
37f0: 20 2a 73 71 6c 69 74 65 33 72 62 75 5f 6f 70 65   *sqlite3rbu_ope
3800: 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
3810: 2a 7a 54 61 72 67 65 74 2c 20 0a 20 20 63 6f 6e  *zTarget, .  con
3820: 73 74 20 63 68 61 72 20 2a 7a 52 62 75 2c 0a 20  st char *zRbu,. 
3830: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 74   const char *zSt
3840: 61 74 65 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 49 6e  ate.);../*.** In
3850: 74 65 72 6e 61 6c 6c 79 2c 20 65 61 63 68 20 52  ternally, each R
3860: 42 55 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  BU connection us
3870: 65 73 20 61 20 73 65 70 61 72 61 74 65 20 53 51  es a separate SQ
3880: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 0a 2a  Lite database .*
3890: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  * connection to 
38a0: 61 63 63 65 73 73 20 74 68 65 20 74 61 72 67 65  access the targe
38b0: 74 20 61 6e 64 20 72 62 75 20 75 70 64 61 74 65  t and rbu update
38c0: 20 64 61 74 61 62 61 73 65 73 2e 20 54 68 69 73   databases. This
38d0: 0a 2a 2a 20 41 50 49 20 61 6c 6c 6f 77 73 20 74  .** API allows t
38e0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
38f0: 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20  irect access to 
3900: 74 68 65 73 65 20 64 61 74 61 62 61 73 65 20 68  these database h
3910: 61 6e 64 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  andles..**.** Th
3920: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
3930: 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
3940: 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
3950: 20 61 20 76 61 6c 69 64 2c 20 6f 70 65 6e 2c 20   a valid, open, 
3960: 52 42 55 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 54  RBU.** handle. T
3970: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
3980: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  nt should be pas
3990: 73 65 64 20 7a 65 72 6f 20 74 6f 20 61 63 63 65  sed zero to acce
39a0: 73 73 20 74 68 65 20 74 61 72 67 65 74 0a 2a 2a  ss the target.**
39b0: 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
39c0: 2c 20 6f 72 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f  , or non-zero to
39d0: 20 61 63 63 65 73 73 20 74 68 65 20 72 62 75 20   access the rbu 
39e0: 75 70 64 61 74 65 20 64 61 74 61 62 61 73 65 20  update database 
39f0: 68 61 6e 64 6c 65 2e 0a 2a 2a 20 41 63 63 65 73  handle..** Acces
3a00: 73 69 6e 67 20 74 68 65 20 75 6e 64 65 72 6c 79  sing the underly
3a10: 69 6e 67 20 64 61 74 61 62 61 73 65 20 68 61 6e  ing database han
3a20: 64 6c 65 73 20 6d 61 79 20 62 65 20 75 73 65 66  dles may be usef
3a30: 75 6c 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 6c  ul in the.** fol
3a40: 6c 6f 77 69 6e 67 20 73 63 65 6e 61 72 69 6f 73  lowing scenarios
3a50: 3a 0a 2a 2a 0a 2a 2a 20 20 20 2a 20 49 66 20 61  :.**.**   * If a
3a60: 6e 79 20 74 61 72 67 65 74 20 74 61 62 6c 65 73  ny target tables
3a70: 20 61 72 65 20 76 69 72 74 75 61 6c 20 74 61 62   are virtual tab
3a80: 6c 65 73 2c 20 69 74 20 6d 61 79 20 62 65 20 6e  les, it may be n
3a90: 65 63 65 73 73 61 72 79 20 74 6f 0a 2a 2a 20 20  ecessary to.**  
3aa0: 20 20 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f     call sqlite3_
3ab0: 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20  create_module() 
3ac0: 6f 6e 20 74 68 65 20 74 61 72 67 65 74 20 64 61  on the target da
3ad0: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f  tabase handle to
3ae0: 20 0a 2a 2a 20 20 20 20 20 72 65 67 69 73 74 65   .**     registe
3af0: 72 20 74 68 65 20 72 65 71 75 69 72 65 64 20 76  r the required v
3b00: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
3b10: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a  lementations..**
3b20: 0a 2a 2a 20 20 20 2a 20 49 66 20 74 68 65 20 64  .**   * If the d
3b30: 61 74 61 5f 78 78 78 20 74 61 62 6c 65 73 20 69  ata_xxx tables i
3b40: 6e 20 74 68 65 20 52 42 55 20 73 6f 75 72 63 65  n the RBU source
3b50: 20 64 61 74 61 62 61 73 65 20 61 72 65 20 76 69   database are vi
3b60: 72 74 75 61 6c 20 0a 2a 2a 20 20 20 20 20 74 61  rtual .**     ta
3b70: 62 6c 65 73 2c 20 74 68 65 20 61 70 70 6c 69 63  bles, the applic
3b80: 61 74 69 6f 6e 20 6d 61 79 20 6e 65 65 64 20 74  ation may need t
3b90: 6f 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  o call sqlite3_c
3ba0: 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6f  reate_module() o
3bb0: 6e 0a 2a 2a 20 20 20 20 20 74 68 65 20 72 62 75  n.**     the rbu
3bc0: 20 75 70 64 61 74 65 20 64 62 20 68 61 6e 64 6c   update db handl
3bd0: 65 20 74 6f 20 61 6e 79 20 72 65 71 75 69 72 65  e to any require
3be0: 64 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 0a  d virtual table.
3bf0: 2a 2a 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74  **     implement
3c00: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 20 20  ations..**.**   
3c10: 2a 20 49 66 20 74 68 65 20 61 70 70 6c 69 63 61  * If the applica
3c20: 74 69 6f 6e 20 75 73 65 73 20 74 68 65 20 22 72  tion uses the "r
3c30: 62 75 5f 64 65 6c 74 61 28 29 22 20 66 65 61 74  bu_delta()" feat
3c40: 75 72 65 20 64 65 73 63 72 69 62 65 64 20 61 62  ure described ab
3c50: 6f 76 65 2c 0a 2a 2a 20 20 20 20 20 69 74 20 6d  ove,.**     it m
3c60: 75 73 74 20 75 73 65 20 73 71 6c 69 74 65 33 5f  ust use sqlite3_
3c70: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
3c80: 29 20 6f 72 20 73 69 6d 69 6c 61 72 20 74 6f 20  ) or similar to 
3c90: 72 65 67 69 73 74 65 72 20 74 68 65 0a 2a 2a 20  register the.** 
3ca0: 20 20 20 20 72 62 75 5f 64 65 6c 74 61 28 29 20      rbu_delta() 
3cb0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
3cc0: 69 74 68 20 74 68 65 20 74 61 72 67 65 74 20 64  ith the target d
3cd0: 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2e 0a  atabase handle..
3ce0: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f  **.** If an erro
3cf0: 72 20 68 61 73 20 6f 63 63 75 72 72 65 64 2c 20  r has occurred, 
3d00: 65 69 74 68 65 72 20 77 68 69 6c 65 20 6f 70 65  either while ope
3d10: 6e 69 6e 67 20 6f 72 20 73 74 65 70 70 69 6e 67  ning or stepping
3d20: 20 74 68 65 20 52 42 55 20 6f 62 6a 65 63 74 2c   the RBU object,
3d30: 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
3d40: 6e 20 6d 61 79 20 72 65 74 75 72 6e 20 4e 55 4c  n may return NUL
3d50: 4c 2e 20 54 68 65 20 65 72 72 6f 72 20 63 6f 64  L. The error cod
3d60: 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
3d70: 79 20 62 65 20 63 6f 6c 6c 65 63 74 65 64 0a 2a  y be collected.*
3d80: 2a 20 77 68 65 6e 20 73 71 6c 69 74 65 33 72 62  * when sqlite3rb
3d90: 75 5f 63 6c 6f 73 65 28 29 20 69 73 20 63 61 6c  u_close() is cal
3da0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 61 74 61 62  led..**.** Datab
3db0: 61 73 65 20 68 61 6e 64 6c 65 73 20 72 65 74 75  ase handles retu
3dc0: 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
3dd0: 63 74 69 6f 6e 20 72 65 6d 61 69 6e 20 76 61 6c  ction remain val
3de0: 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
3df0: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79  t.** call to any
3e00: 20 73 71 6c 69 74 65 33 72 62 75 5f 78 78 78 28   sqlite3rbu_xxx(
3e10: 29 20 66 75 6e 63 74 69 6f 6e 20 6f 74 68 65 72  ) function other
3e20: 20 74 68 61 6e 20 73 71 6c 69 74 65 33 72 62 75   than sqlite3rbu
3e30: 5f 64 62 28 29 2e 0a 2a 2f 0a 73 71 6c 69 74 65  _db()..*/.sqlite
3e40: 33 20 2a 73 71 6c 69 74 65 33 72 62 75 5f 64 62  3 *sqlite3rbu_db
3e50: 28 73 71 6c 69 74 65 33 72 62 75 2a 2c 20 69 6e  (sqlite3rbu*, in
3e60: 74 20 62 52 62 75 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t bRbu);../*.** 
3e70: 44 6f 20 73 6f 6d 65 20 77 6f 72 6b 20 74 6f 77  Do some work tow
3e80: 61 72 64 73 20 61 70 70 6c 79 69 6e 67 20 74 68  ards applying th
3e90: 65 20 52 42 55 20 75 70 64 61 74 65 20 74 6f 20  e RBU update to 
3ea0: 74 68 65 20 74 61 72 67 65 74 20 64 62 2e 20 0a  the target db. .
3eb0: 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 53 51 4c  **.** Return SQL
3ec0: 49 54 45 5f 44 4f 4e 45 20 69 66 20 74 68 65 20  ITE_DONE if the 
3ed0: 75 70 64 61 74 65 20 68 61 73 20 62 65 65 6e 20  update has been 
3ee0: 63 6f 6d 70 6c 65 74 65 6c 79 20 61 70 70 6c 69  completely appli
3ef0: 65 64 2c 20 6f 72 20 0a 2a 2a 20 53 51 4c 49 54  ed, or .** SQLIT
3f00: 45 5f 4f 4b 20 69 66 20 6e 6f 20 65 72 72 6f 72  E_OK if no error
3f10: 20 6f 63 63 75 72 73 20 62 75 74 20 74 68 65 72   occurs but ther
3f20: 65 20 72 65 6d 61 69 6e 73 20 77 6f 72 6b 20 74  e remains work t
3f30: 6f 20 64 6f 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  o do to apply.**
3f40: 20 74 68 65 20 52 42 55 20 75 70 64 61 74 65 2e   the RBU update.
3f50: 20 49 66 20 61 6e 20 65 72 72 6f 72 20 64 6f 65   If an error doe
3f60: 73 20 6f 63 63 75 72 2c 20 73 6f 6d 65 20 6f 74  s occur, some ot
3f70: 68 65 72 20 65 72 72 6f 72 20 63 6f 64 65 20 69  her error code i
3f80: 73 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 2e 20  s .** returned. 
3f90: 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65 20 61 20 63 61  .**.** Once a ca
3fa0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 72 62 75  ll to sqlite3rbu
3fb0: 5f 73 74 65 70 28 29 20 68 61 73 20 72 65 74 75  _step() has retu
3fc0: 72 6e 65 64 20 61 20 76 61 6c 75 65 20 6f 74 68  rned a value oth
3fd0: 65 72 20 74 68 61 6e 0a 2a 2a 20 53 51 4c 49 54  er than.** SQLIT
3fe0: 45 5f 4f 4b 2c 20 61 6c 6c 20 73 75 62 73 65 71  E_OK, all subseq
3ff0: 75 65 6e 74 20 63 61 6c 6c 73 20 6f 6e 20 74 68  uent calls on th
4000: 65 20 73 61 6d 65 20 52 42 55 20 68 61 6e 64 6c  e same RBU handl
4010: 65 20 61 72 65 20 6e 6f 2d 6f 70 73 0a 2a 2a 20  e are no-ops.** 
4020: 74 68 61 74 20 69 6d 6d 65 64 69 61 74 65 6c 79  that immediately
4030: 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
4040: 20 76 61 6c 75 65 2e 0a 2a 2f 0a 69 6e 74 20 73   value..*/.int s
4050: 71 6c 69 74 65 33 72 62 75 5f 73 74 65 70 28 73  qlite3rbu_step(s
4060: 71 6c 69 74 65 33 72 62 75 20 2a 70 52 62 75 29  qlite3rbu *pRbu)
4070: 3b 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 63 65 20 52  ;../*.** Force R
4080: 42 55 20 74 6f 20 73 61 76 65 20 69 74 73 20 73  BU to save its s
4090: 74 61 74 65 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a  tate to disk..**
40a0: 0a 2a 2a 20 49 66 20 61 20 70 6f 77 65 72 20 66  .** If a power f
40b0: 61 69 6c 75 72 65 20 6f 72 20 61 70 70 6c 69 63  ailure or applic
40c0: 61 74 69 6f 6e 20 63 72 61 73 68 20 6f 63 63 75  ation crash occu
40d0: 72 73 20 64 75 72 69 6e 67 20 61 6e 20 75 70 64  rs during an upd
40e0: 61 74 65 2c 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  ate, following.*
40f0: 2a 20 73 79 73 74 65 6d 20 72 65 63 6f 76 65 72  * system recover
4100: 79 20 52 42 55 20 6d 61 79 20 72 65 73 75 6d 65  y RBU may resume
4110: 20 74 68 65 20 75 70 64 61 74 65 20 66 72 6f 6d   the update from
4120: 20 74 68 65 20 70 6f 69 6e 74 20 61 74 20 77 68   the point at wh
4130: 69 63 68 20 74 68 65 20 73 74 61 74 65 0a 2a 2a  ich the state.**
4140: 20 77 61 73 20 6c 61 73 74 20 73 61 76 65 64 2e   was last saved.
4150: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
4160: 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72   from the most r
4170: 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
4180: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 73 71 6c   call to .** sql
4190: 69 74 65 33 72 62 75 5f 63 6c 6f 73 65 28 29 20  ite3rbu_close() 
41a0: 6f 72 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  or this function
41b0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  ..**.** SQLITE_O
41c0: 4b 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  K is returned if
41d0: 20 73 75 63 63 65 73 73 66 75 6c 2c 20 6f 72 20   successful, or 
41e0: 61 6e 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20  an SQLite error 
41f0: 63 6f 64 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  code otherwise..
4200: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 72 62  */.int sqlite3rb
4210: 75 5f 73 61 76 65 73 74 61 74 65 28 73 71 6c 69  u_savestate(sqli
4220: 74 65 33 72 62 75 20 2a 70 52 62 75 29 3b 0a 0a  te3rbu *pRbu);..
4230: 2f 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e 20 52  /*.** Close an R
4240: 42 55 20 68 61 6e 64 6c 65 2e 20 0a 2a 2a 0a 2a  BU handle. .**.*
4250: 2a 20 49 66 20 74 68 65 20 52 42 55 20 75 70 64  * If the RBU upd
4260: 61 74 65 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ate has been com
4270: 70 6c 65 74 65 6c 79 20 61 70 70 6c 69 65 64 2c  pletely applied,
4280: 20 6d 61 72 6b 20 74 68 65 20 52 42 55 20 64 61   mark the RBU da
4290: 74 61 62 61 73 65 0a 2a 2a 20 61 73 20 66 75 6c  tabase.** as ful
42a0: 6c 79 20 61 70 70 6c 69 65 64 2e 20 4f 74 68 65  ly applied. Othe
42b0: 72 77 69 73 65 2c 20 61 73 73 75 6d 69 6e 67 20  rwise, assuming 
42c0: 6e 6f 20 65 72 72 6f 72 20 68 61 73 20 6f 63 63  no error has occ
42d0: 75 72 72 65 64 2c 20 73 61 76 65 20 74 68 65 0a  urred, save the.
42e0: 2a 2a 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  ** current state
42f0: 20 6f 66 20 74 68 65 20 52 42 55 20 75 70 64 61   of the RBU upda
4300: 74 65 20 61 70 70 6c 69 61 74 69 6f 6e 20 74 6f  te appliation to
4310: 20 74 68 65 20 52 42 55 20 64 61 74 61 62 61 73   the RBU databas
4320: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65  e..**.** If an e
4330: 72 72 6f 72 20 68 61 73 20 61 6c 72 65 61 64 79  rror has already
4340: 20 6f 63 63 75 72 72 65 64 20 61 73 20 70 61 72   occurred as par
4350: 74 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 72  t of an sqlite3r
4360: 62 75 5f 73 74 65 70 28 29 0a 2a 2a 20 6f 72 20  bu_step().** or 
4370: 73 71 6c 69 74 65 33 72 62 75 5f 6f 70 65 6e 28  sqlite3rbu_open(
4380: 29 20 63 61 6c 6c 2c 20 6f 72 20 69 66 20 6f 6e  ) call, or if on
4390: 65 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  e occurs within 
43a0: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2c 20 61  this function, a
43b0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 72 72 6f  n.** SQLite erro
43c0: 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
43d0: 65 64 2e 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  ed. Additionally
43e0: 2c 20 2a 70 7a 45 72 72 6d 73 67 20 6d 61 79 20  , *pzErrmsg may 
43f0: 62 65 20 73 65 74 20 74 6f 0a 2a 2a 20 70 6f 69  be set to.** poi
4400: 6e 74 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  nt to a buffer c
4410: 6f 6e 74 61 69 6e 69 6e 67 20 61 20 75 74 66 2d  ontaining a utf-
4420: 38 20 66 6f 72 6d 61 74 74 65 64 20 45 6e 67 6c  8 formatted Engl
4430: 69 73 68 20 6c 61 6e 67 75 61 67 65 20 65 72 72  ish language err
4440: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 2e 20 49  or.** message. I
4450: 74 20 69 73 20 74 68 65 20 72 65 73 70 6f 6e 73  t is the respons
4460: 69 62 69 6c 69 74 79 20 6f 66 20 74 68 65 20 63  ibility of the c
4470: 61 6c 6c 65 72 20 74 6f 20 65 76 65 6e 74 75 61  aller to eventua
4480: 6c 6c 79 20 66 72 65 65 20 61 6e 79 20 0a 2a 2a  lly free any .**
4490: 20 73 75 63 68 20 62 75 66 66 65 72 20 75 73 69   such buffer usi
44a0: 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
44b0: 29 2e 0a 2a 2a 0a 2a 2a 20 4f 74 68 65 72 77 69  )..**.** Otherwi
44c0: 73 65 2c 20 69 66 20 6e 6f 20 65 72 72 6f 72 20  se, if no error 
44d0: 6f 63 63 75 72 73 2c 20 74 68 69 73 20 66 75 6e  occurs, this fun
44e0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51  ction returns SQ
44f0: 4c 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 0a 2a  LITE_OK if the.*
4500: 2a 20 75 70 64 61 74 65 20 68 61 73 20 62 65 65  * update has bee
4510: 6e 20 70 61 72 74 69 61 6c 6c 79 20 61 70 70 6c  n partially appl
4520: 69 65 64 2c 20 6f 72 20 53 51 4c 49 54 45 5f 44  ied, or SQLITE_D
4530: 4f 4e 45 20 69 66 20 69 74 20 68 61 73 20 62 65  ONE if it has be
4540: 65 6e 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 6c  en .** completel
4550: 79 20 61 70 70 6c 69 65 64 2e 0a 2a 2f 0a 69 6e  y applied..*/.in
4560: 74 20 73 71 6c 69 74 65 33 72 62 75 5f 63 6c 6f  t sqlite3rbu_clo
4570: 73 65 28 73 71 6c 69 74 65 33 72 62 75 20 2a 70  se(sqlite3rbu *p
4580: 52 62 75 2c 20 63 68 61 72 20 2a 2a 70 7a 45 72  Rbu, char **pzEr
4590: 72 6d 73 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 52 65  rmsg);../*.** Re
45a0: 74 75 72 6e 20 74 68 65 20 74 6f 74 61 6c 20 6e  turn the total n
45b0: 75 6d 62 65 72 20 6f 66 20 6b 65 79 2d 76 61 6c  umber of key-val
45c0: 75 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 28 69  ue operations (i
45d0: 6e 73 65 72 74 73 2c 20 64 65 6c 65 74 65 73 20  nserts, deletes 
45e0: 6f 72 20 0a 2a 2a 20 75 70 64 61 74 65 73 29 20  or .** updates) 
45f0: 74 68 61 74 20 68 61 76 65 20 62 65 65 6e 20 70  that have been p
4600: 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20  erformed on the 
4610: 74 61 72 67 65 74 20 64 61 74 61 62 61 73 65 20  target database 
4620: 73 69 6e 63 65 20 74 68 65 0a 2a 2a 20 63 75 72  since the.** cur
4630: 72 65 6e 74 20 52 42 55 20 75 70 64 61 74 65 20  rent RBU update 
4640: 77 61 73 20 73 74 61 72 74 65 64 2e 0a 2a 2f 0a  was started..*/.
4650: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
4660: 6c 69 74 65 33 72 62 75 5f 70 72 6f 67 72 65 73  lite3rbu_progres
4670: 73 28 73 71 6c 69 74 65 33 72 62 75 20 2a 70 52  s(sqlite3rbu *pR
4680: 62 75 29 3b 0a 0a 2f 2a 0a 2a 2a 20 4f 62 74 61  bu);../*.** Obta
4690: 69 6e 20 70 65 72 6d 79 72 69 61 64 61 67 65 20  in permyriadage 
46a0: 28 70 65 72 6d 79 72 69 61 64 61 67 65 20 69 73  (permyriadage is
46b0: 20 74 6f 20 31 30 30 30 30 20 61 73 20 70 65 72   to 10000 as per
46c0: 63 65 6e 74 61 67 65 20 69 73 20 74 6f 20 31 30  centage is to 10
46d0: 30 29 20 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20  0) .** progress 
46e0: 69 6e 64 69 63 61 74 69 6f 6e 73 20 66 6f 72 20  indications for 
46f0: 74 68 65 20 74 77 6f 20 73 74 61 67 65 73 20 6f  the two stages o
4700: 66 20 61 6e 20 52 42 55 20 75 70 64 61 74 65 2e  f an RBU update.
4710: 20 54 68 69 73 20 41 50 49 20 6d 61 79 0a 2a 2a   This API may.**
4720: 20 62 65 20 75 73 65 66 75 6c 20 66 6f 72 20 64   be useful for d
4730: 72 69 76 69 6e 67 20 47 55 49 20 70 72 6f 67 72  riving GUI progr
4740: 65 73 73 20 69 6e 64 69 63 61 74 6f 72 73 20 61  ess indicators a
4750: 6e 64 20 73 69 6d 69 6c 61 72 2e 0a 2a 2a 0a 2a  nd similar..**.*
4760: 2a 20 41 6e 20 52 42 55 20 75 70 64 61 74 65 20  * An RBU update 
4770: 69 73 20 64 69 76 69 64 65 64 20 69 6e 74 6f 20  is divided into 
4780: 74 77 6f 20 73 74 61 67 65 73 3a 0a 2a 2a 0a 2a  two stages:.**.*
4790: 2a 20 20 20 2a 20 53 74 61 67 65 20 31 2c 20 69  *   * Stage 1, i
47a0: 6e 20 77 68 69 63 68 20 63 68 61 6e 67 65 73 20  n which changes 
47b0: 61 72 65 20 61 63 63 75 6d 75 6c 61 74 65 64 20  are accumulated 
47c0: 69 6e 20 61 6e 20 6f 61 6c 2f 77 61 6c 20 66 69  in an oal/wal fi
47d0: 6c 65 2c 20 61 6e 64 0a 2a 2a 20 20 20 2a 20 53  le, and.**   * S
47e0: 74 61 67 65 20 32 2c 20 69 6e 20 77 68 69 63 68  tage 2, in which
47f0: 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
4800: 20 74 68 65 20 77 61 6c 20 66 69 6c 65 20 61 72   the wal file ar
4810: 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
4820: 65 0a 2a 2a 20 20 20 20 20 6d 61 69 6e 20 64 61  e.**     main da
4830: 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  tabase..**.** Th
4840: 65 20 75 70 64 61 74 65 20 69 73 20 76 69 73 69  e update is visi
4850: 62 6c 65 20 74 6f 20 6e 6f 6e 2d 52 42 55 20 63  ble to non-RBU c
4860: 6c 69 65 6e 74 73 20 64 75 72 69 6e 67 20 73 74  lients during st
4870: 61 67 65 20 32 2e 20 44 75 72 69 6e 67 20 73 74  age 2. During st
4880: 61 67 65 20 31 0a 2a 2a 20 6e 6f 6e 2d 52 42 55  age 1.** non-RBU
4890: 20 72 65 61 64 65 72 20 63 6c 69 65 6e 74 73 20   reader clients 
48a0: 6d 61 79 20 73 65 65 20 74 68 65 20 6f 72 69 67  may see the orig
48b0: 69 6e 61 6c 20 64 61 74 61 62 61 73 65 2e 0a 2a  inal database..*
48c0: 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 41 50 49  *.** If this API
48d0: 20 69 73 20 63 61 6c 6c 65 64 20 64 75 72 69 6e   is called durin
48e0: 67 20 73 74 61 67 65 20 32 20 6f 66 20 74 68 65  g stage 2 of the
48f0: 20 75 70 64 61 74 65 2c 20 6f 75 74 70 75 74 20   update, output 
4900: 76 61 72 69 61 62 6c 65 20 0a 2a 2a 20 28 2a 70  variable .** (*p
4910: 6e 4f 6e 65 29 20 69 73 20 73 65 74 20 74 6f 20  nOne) is set to 
4920: 31 30 30 30 30 20 74 6f 20 69 6e 64 69 63 61 74  10000 to indicat
4930: 65 20 74 68 61 74 20 73 74 61 67 65 20 31 20 68  e that stage 1 h
4940: 61 73 20 66 69 6e 69 73 68 65 64 20 61 6e 64 20  as finished and 
4950: 28 2a 70 6e 54 77 6f 29 0a 2a 2a 20 74 6f 20 61  (*pnTwo).** to a
4960: 20 76 61 6c 75 65 20 62 65 74 77 65 65 6e 20 30   value between 0
4970: 20 61 6e 64 20 31 30 30 30 30 20 74 6f 20 69 6e   and 10000 to in
4980: 64 69 63 61 74 65 20 74 68 65 20 70 65 72 6d 79  dicate the permy
4990: 72 69 61 64 61 67 65 20 70 72 6f 67 72 65 73 73  riadage progress
49a0: 20 6f 66 0a 2a 2a 20 73 74 61 67 65 20 32 2e 20   of.** stage 2. 
49b0: 41 20 76 61 6c 75 65 20 6f 66 20 35 30 30 30 20  A value of 5000 
49c0: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 73  indicates that s
49d0: 74 61 67 65 20 32 20 69 73 20 68 61 6c 66 20 66  tage 2 is half f
49e0: 69 6e 69 73 68 65 64 2c 20 0a 2a 2a 20 39 30 30  inished, .** 900
49f0: 30 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  0 indicates that
4a00: 20 69 74 20 69 73 20 39 30 25 20 66 69 6e 69 73   it is 90% finis
4a10: 68 65 64 2c 20 61 6e 64 20 73 6f 20 6f 6e 2e 0a  hed, and so on..
4a20: 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 41 50  **.** If this AP
4a30: 49 20 69 73 20 63 61 6c 6c 65 64 20 64 75 72 69  I is called duri
4a40: 6e 67 20 73 74 61 67 65 20 31 20 6f 66 20 74 68  ng stage 1 of th
4a50: 65 20 75 70 64 61 74 65 2c 20 6f 75 74 70 75 74  e update, output
4a60: 20 76 61 72 69 61 62 6c 65 20 0a 2a 2a 20 28 2a   variable .** (*
4a70: 70 6e 54 77 6f 29 20 69 73 20 73 65 74 20 74 6f  pnTwo) is set to
4a80: 20 30 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74   0 to indicate t
4a90: 68 61 74 20 73 74 61 67 65 20 32 20 68 61 73 20  hat stage 2 has 
4aa0: 6e 6f 74 20 79 65 74 20 73 74 61 72 74 65 64 2e  not yet started.
4ab0: 20 54 68 65 0a 2a 2a 20 76 61 6c 75 65 20 74 6f   The.** value to
4ac0: 20 77 68 69 63 68 20 28 2a 70 6e 4f 6e 65 29 20   which (*pnOne) 
4ad0: 69 73 20 73 65 74 20 64 65 70 65 6e 64 73 20 6f  is set depends o
4ae0: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
4af0: 20 74 68 65 20 52 42 55 20 0a 2a 2a 20 64 61 74   the RBU .** dat
4b00: 61 62 61 73 65 20 63 6f 6e 74 61 69 6e 73 20 61  abase contains a
4b10: 6e 20 22 72 62 75 5f 63 6f 75 6e 74 22 20 74 61  n "rbu_count" ta
4b20: 62 6c 65 2e 20 54 68 65 20 72 62 75 5f 63 6f 75  ble. The rbu_cou
4b30: 6e 74 20 74 61 62 6c 65 2c 20 69 66 20 69 74 20  nt table, if it 
4b40: 0a 2a 2a 20 65 78 69 73 74 73 2c 20 6d 75 73 74  .** exists, must
4b50: 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 73 61 6d   contain the sam
4b60: 65 20 63 6f 6c 75 6d 6e 73 20 61 73 20 74 68 65  e columns as the
4b70: 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a 2a 2a 0a 2a   following:.**.*
4b80: 2a 20 20 20 43 52 45 41 54 45 20 54 41 42 4c 45  *   CREATE TABLE
4b90: 20 72 62 75 5f 63 6f 75 6e 74 28 74 62 6c 20 54   rbu_count(tbl T
4ba0: 45 58 54 20 50 52 49 4d 41 52 59 20 4b 45 59 2c  EXT PRIMARY KEY,
4bb0: 20 63 6e 74 20 49 4e 54 45 47 45 52 29 20 57 49   cnt INTEGER) WI
4bc0: 54 48 4f 55 54 20 52 4f 57 49 44 3b 0a 2a 2a 0a  THOUT ROWID;.**.
4bd0: 2a 2a 20 54 68 65 72 65 20 6d 75 73 74 20 62 65  ** There must be
4be0: 20 6f 6e 65 20 72 6f 77 20 69 6e 20 74 68 65 20   one row in the 
4bf0: 74 61 62 6c 65 20 66 6f 72 20 65 61 63 68 20 73  table for each s
4c00: 6f 75 72 63 65 20 28 64 61 74 61 5f 78 78 78 29  ource (data_xxx)
4c10: 20 74 61 62 6c 65 20 77 69 74 68 69 6e 0a 2a 2a   table within.**
4c20: 20 74 68 65 20 52 42 55 20 64 61 74 61 62 61 73   the RBU databas
4c30: 65 2e 20 54 68 65 20 27 74 62 6c 27 20 63 6f 6c  e. The 'tbl' col
4c40: 75 6d 6e 20 73 68 6f 75 6c 64 20 63 6f 6e 74 61  umn should conta
4c50: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
4c60: 68 65 20 73 6f 75 72 63 65 0a 2a 2a 20 74 61 62  he source.** tab
4c70: 6c 65 2e 20 54 68 65 20 27 63 6e 74 27 20 63 6f  le. The 'cnt' co
4c80: 6c 75 6d 6e 20 73 68 6f 75 6c 64 20 63 6f 6e 74  lumn should cont
4c90: 61 69 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ain the number o
4ca0: 66 20 72 6f 77 73 20 77 69 74 68 69 6e 20 74 68  f rows within th
4cb0: 65 0a 2a 2a 20 73 6f 75 72 63 65 20 74 61 62 6c  e.** source tabl
4cc0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
4cd0: 72 62 75 5f 63 6f 75 6e 74 20 74 61 62 6c 65 20  rbu_count table 
4ce0: 69 73 20 70 72 65 73 65 6e 74 20 61 6e 64 20 70  is present and p
4cf0: 6f 70 75 6c 61 74 65 64 20 63 6f 72 72 65 63 74  opulated correct
4d00: 6c 79 20 61 6e 64 20 74 68 69 73 0a 2a 2a 20 41  ly and this.** A
4d10: 50 49 20 69 73 20 63 61 6c 6c 65 64 20 64 75 72  PI is called dur
4d20: 69 6e 67 20 73 74 61 67 65 20 31 2c 20 74 68 65  ing stage 1, the
4d30: 20 2a 70 6e 4f 6e 65 20 6f 75 74 70 75 74 20 76   *pnOne output v
4d40: 61 72 69 61 62 6c 65 20 69 73 20 73 65 74 20 74  ariable is set t
4d50: 6f 20 74 68 65 0a 2a 2a 20 70 65 72 6d 79 72 69  o the.** permyri
4d60: 61 64 61 67 65 20 70 72 6f 67 72 65 73 73 20 6f  adage progress o
4d70: 66 20 74 68 65 20 73 61 6d 65 20 73 74 61 67 65  f the same stage
4d80: 2e 20 49 66 20 74 68 65 20 72 62 75 5f 63 6f 75  . If the rbu_cou
4d90: 6e 74 20 74 61 62 6c 65 20 64 6f 65 73 0a 2a 2a  nt table does.**
4da0: 20 6e 6f 74 20 65 78 69 73 74 2c 20 74 68 65 6e   not exist, then
4db0: 20 28 2a 70 6e 4f 6e 65 29 20 69 73 20 73 65 74   (*pnOne) is set
4dc0: 20 74 6f 20 2d 31 20 64 75 72 69 6e 67 20 73 74   to -1 during st
4dd0: 61 67 65 20 31 2e 20 49 66 20 74 68 65 20 72 62  age 1. If the rb
4de0: 75 5f 63 6f 75 6e 74 0a 2a 2a 20 74 61 62 6c 65  u_count.** table
4df0: 20 65 78 69 73 74 73 20 62 75 74 20 69 73 20 6e   exists but is n
4e00: 6f 74 20 63 6f 72 72 65 63 74 6c 79 20 70 6f 70  ot correctly pop
4e10: 75 6c 61 74 65 64 2c 20 74 68 65 20 76 61 6c 75  ulated, the valu
4e20: 65 20 6f 66 20 74 68 65 20 2a 70 6e 4f 6e 65 0a  e of the *pnOne.
4e30: 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61 62  ** output variab
4e40: 6c 65 20 64 75 72 69 6e 67 20 73 74 61 67 65 20  le during stage 
4e50: 31 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  1 is undefined..
4e60: 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 72  */.void sqlite3r
4e70: 62 75 5f 62 70 5f 70 72 6f 67 72 65 73 73 28 73  bu_bp_progress(s
4e80: 71 6c 69 74 65 33 72 62 75 20 2a 70 52 62 75 2c  qlite3rbu *pRbu,
4e90: 20 69 6e 74 20 2a 70 6e 4f 6e 65 2c 20 69 6e 74   int *pnOne, int
4ea0: 20 2a 70 6e 54 77 6f 29 3b 0a 0a 2f 2a 0a 2a 2a   *pnTwo);../*.**
4eb0: 20 43 72 65 61 74 65 20 61 6e 20 52 42 55 20 56   Create an RBU V
4ec0: 46 53 20 6e 61 6d 65 64 20 7a 4e 61 6d 65 20 74  FS named zName t
4ed0: 68 61 74 20 61 63 63 65 73 73 65 73 20 74 68 65  hat accesses the
4ee0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 66 69 6c 65   underlying file
4ef0: 2d 73 79 73 74 65 6d 0a 2a 2a 20 76 69 61 20 65  -system.** via e
4f00: 78 69 73 74 69 6e 67 20 56 46 53 20 7a 50 61 72  xisting VFS zPar
4f10: 65 6e 74 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ent. Or, if the 
4f20: 7a 50 61 72 65 6e 74 20 70 61 72 61 6d 65 74 65  zParent paramete
4f30: 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
4f40: 2c 20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  , .** then the n
4f50: 65 77 20 52 42 55 20 56 46 53 20 75 73 65 73 20  ew RBU VFS uses 
4f60: 74 68 65 20 64 65 66 61 75 6c 74 20 73 79 73 74  the default syst
4f70: 65 6d 20 56 46 53 20 74 6f 20 61 63 63 65 73 73  em VFS to access
4f80: 20 74 68 65 20 66 69 6c 65 2d 73 79 73 74 65 6d   the file-system
4f90: 2e 0a 2a 2a 20 54 68 65 20 6e 65 77 20 6f 62 6a  ..** The new obj
4fa0: 65 63 74 20 69 73 20 72 65 67 69 73 74 65 72 65  ect is registere
4fb0: 64 20 61 73 20 61 20 6e 6f 6e 2d 64 65 66 61 75  d as a non-defau
4fc0: 6c 74 20 56 46 53 20 77 69 74 68 20 53 51 4c 69  lt VFS with SQLi
4fd0: 74 65 20 62 65 66 6f 72 65 20 0a 2a 2a 20 72 65  te before .** re
4fe0: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 50  turning..**.** P
4ff0: 61 72 74 20 6f 66 20 74 68 65 20 52 42 55 20 69  art of the RBU i
5000: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
5010: 65 73 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20  es a custom VFS 
5020: 6f 62 6a 65 63 74 2e 20 55 73 75 61 6c 6c 79 2c  object. Usually,
5030: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
5040: 69 73 20 63 72 65 61 74 65 64 20 61 6e 64 20 64  is created and d
5050: 65 6c 65 74 65 64 20 61 75 74 6f 6d 61 74 69 63  eleted automatic
5060: 61 6c 6c 79 20 62 79 20 52 42 55 2e 20 0a 2a 2a  ally by RBU. .**
5070: 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
5080: 6e 20 69 73 20 66 6f 72 20 61 70 70 6c 69 63 61  n is for applica
5090: 74 69 6f 6e 73 20 74 68 61 74 20 61 6c 73 6f 20  tions that also 
50a0: 75 73 65 20 7a 69 70 76 66 73 2e 20 49 6e 20 74  use zipvfs. In t
50b0: 68 69 73 20 63 61 73 65 2c 0a 2a 2a 20 74 68 65  his case,.** the
50c0: 20 63 75 73 74 6f 6d 20 56 46 53 20 6d 75 73 74   custom VFS must
50d0: 20 62 65 20 65 78 70 6c 69 63 69 74 6c 79 20 63   be explicitly c
50e0: 72 65 61 74 65 64 20 62 79 20 74 68 65 20 75 73  reated by the us
50f0: 65 72 20 62 65 66 6f 72 65 20 74 68 65 20 52 42  er before the RB
5100: 55 0a 2a 2a 20 68 61 6e 64 6c 65 20 69 73 20 6f  U.** handle is o
5110: 70 65 6e 65 64 2e 20 54 68 65 20 52 42 55 20 56  pened. The RBU V
5120: 46 53 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 73  FS should be ins
5130: 74 61 6c 6c 65 64 20 73 6f 20 74 68 61 74 20 74  talled so that t
5140: 68 65 20 7a 69 70 76 66 73 0a 2a 2a 20 56 46 53  he zipvfs.** VFS
5150: 20 75 73 65 73 20 74 68 65 20 52 42 55 20 56 46   uses the RBU VF
5160: 53 2c 20 77 68 69 63 68 20 69 6e 20 74 75 72 6e  S, which in turn
5170: 20 75 73 65 73 20 61 6e 79 20 6f 74 68 65 72 20   uses any other 
5180: 56 46 53 20 6c 61 79 65 72 73 20 69 6e 20 75 73  VFS layers in us
5190: 65 20 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  e .** (for examp
51a0: 6c 65 20 6d 75 6c 74 69 70 6c 65 78 6f 72 29 20  le multiplexor) 
51b0: 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 66 69  to access the fi
51c0: 6c 65 2d 73 79 73 74 65 6d 2e 20 46 6f 72 20 65  le-system. For e
51d0: 78 61 6d 70 6c 65 2c 0a 2a 2a 20 74 6f 20 61 73  xample,.** to as
51e0: 73 65 6d 62 6c 65 20 61 6e 20 52 42 55 20 65 6e  semble an RBU en
51f0: 61 62 6c 65 64 20 56 46 53 20 73 74 61 63 6b 20  abled VFS stack 
5200: 74 68 61 74 20 75 73 65 73 20 62 6f 74 68 20 7a  that uses both z
5210: 69 70 76 66 73 20 61 6e 64 20 0a 2a 2a 20 6d 75  ipvfs and .** mu
5220: 6c 74 69 70 6c 65 78 6f 72 20 28 65 72 72 6f 72  ltiplexor (error
5230: 20 63 68 65 63 6b 69 6e 67 20 6f 6d 69 74 74 65   checking omitte
5240: 64 29 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 2f 2f  d):.**.**     //
5250: 20 43 72 65 61 74 65 20 61 20 56 46 53 20 6e 61   Create a VFS na
5260: 6d 65 64 20 22 6d 75 6c 74 69 70 6c 65 78 22 20  med "multiplex" 
5270: 28 6e 6f 74 20 74 68 65 20 64 65 66 61 75 6c 74  (not the default
5280: 29 2e 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  )..**     sqlite
5290: 33 5f 6d 75 6c 74 69 70 6c 65 78 5f 69 6e 69 74  3_multiplex_init
52a0: 69 61 6c 69 7a 65 28 30 2c 20 30 29 3b 0a 2a 2a  ialize(0, 0);.**
52b0: 0a 2a 2a 20 20 20 20 20 2f 2f 20 43 72 65 61 74  .**     // Creat
52c0: 65 20 61 6e 20 72 62 75 20 56 46 53 20 6e 61 6d  e an rbu VFS nam
52d0: 65 64 20 22 72 62 75 22 20 74 68 61 74 20 75 73  ed "rbu" that us
52e0: 65 73 20 6d 75 6c 74 69 70 6c 65 78 6f 72 2e 20  es multiplexor. 
52f0: 49 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 2f 2f  If the.**     //
5300: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
5310: 20 77 65 72 65 20 72 65 70 6c 61 63 65 64 20 77   were replaced w
5320: 69 74 68 20 4e 55 4c 4c 2c 20 74 68 65 20 22 72  ith NULL, the "r
5330: 62 75 22 20 56 46 53 20 77 6f 75 6c 64 0a 2a 2a  bu" VFS would.**
5340: 20 20 20 20 20 2f 2f 20 61 63 63 65 73 73 20 74       // access t
5350: 68 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 76  he file-system v
5360: 69 61 20 74 68 65 20 73 79 73 74 65 6d 20 64 65  ia the system de
5370: 66 61 75 6c 74 20 56 46 53 2c 20 62 79 70 61 73  fault VFS, bypas
5380: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  sing the.**     
5390: 2f 2f 20 6d 75 6c 74 69 70 6c 65 78 6f 72 2e 0a  // multiplexor..
53a0: 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 72 62  **     sqlite3rb
53b0: 75 5f 63 72 65 61 74 65 5f 76 66 73 28 22 72 62  u_create_vfs("rb
53c0: 75 22 2c 20 22 6d 75 6c 74 69 70 6c 65 78 22 29  u", "multiplex")
53d0: 3b 0a 2a 2a 0a 2a 2a 20 20 20 20 20 2f 2f 20 43  ;.**.**     // C
53e0: 72 65 61 74 65 20 61 20 7a 69 70 76 66 73 20 56  reate a zipvfs V
53f0: 46 53 20 6e 61 6d 65 64 20 22 7a 69 70 76 66 73  FS named "zipvfs
5400: 22 20 74 68 61 74 20 75 73 65 73 20 72 62 75 2e  " that uses rbu.
5410: 0a 2a 2a 20 20 20 20 20 7a 69 70 76 66 73 5f 63  .**     zipvfs_c
5420: 72 65 61 74 65 5f 76 66 73 5f 76 33 28 22 7a 69  reate_vfs_v3("zi
5430: 70 76 66 73 22 2c 20 22 72 62 75 22 2c 20 30 2c  pvfs", "rbu", 0,
5440: 20 78 43 6f 6d 70 72 65 73 73 6f 72 41 6c 67 6f   xCompressorAlgo
5450: 72 69 74 68 6d 44 65 74 65 63 74 6f 72 29 3b 0a  rithmDetector);.
5460: 2a 2a 0a 2a 2a 20 20 20 20 20 2f 2f 20 4d 61 6b  **.**     // Mak
5470: 65 20 7a 69 70 76 66 73 20 74 68 65 20 64 65 66  e zipvfs the def
5480: 61 75 6c 74 20 56 46 53 2e 0a 2a 2a 20 20 20 20  ault VFS..**    
5490: 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67   sqlite3_vfs_reg
54a0: 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66  ister(sqlite3_vf
54b0: 73 5f 66 69 6e 64 28 22 7a 69 70 76 66 73 22 29  s_find("zipvfs")
54c0: 2c 20 31 29 3b 0a 2a 2a 0a 2a 2a 20 42 65 63 61  , 1);.**.** Beca
54d0: 75 73 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  use the default 
54e0: 56 46 53 20 63 72 65 61 74 65 64 20 61 62 6f 76  VFS created abov
54f0: 65 20 69 6e 63 6c 75 64 65 73 20 61 20 52 42 55  e includes a RBU
5500: 20 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79 2c 20   functionality, 
5510: 69 74 0a 2a 2a 20 6d 61 79 20 62 65 20 75 73 65  it.** may be use
5520: 64 20 62 79 20 52 42 55 20 63 6c 69 65 6e 74 73  d by RBU clients
5530: 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
5540: 75 73 65 20 52 42 55 20 77 69 74 68 20 61 20 7a  use RBU with a z
5550: 69 70 76 66 73 20 56 46 53 20 73 74 61 63 6b 0a  ipvfs VFS stack.
5560: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
5570: 20 69 6e 63 6c 75 64 65 20 74 68 65 20 52 42 55   include the RBU
5580: 20 6c 61 79 65 72 20 72 65 73 75 6c 74 73 20 69   layer results i
5590: 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  n an error..**.*
55a0: 2a 20 54 68 65 20 6f 76 65 72 68 65 61 64 20 6f  * The overhead o
55b0: 66 20 61 64 64 69 6e 67 20 74 68 65 20 22 72 62  f adding the "rb
55c0: 75 22 20 56 46 53 20 74 6f 20 74 68 65 20 73 79  u" VFS to the sy
55d0: 73 74 65 6d 20 69 73 20 6e 65 67 6c 69 67 69 62  stem is negligib
55e0: 6c 65 20 66 6f 72 20 0a 2a 2a 20 6e 6f 6e 2d 52  le for .** non-R
55f0: 42 55 20 75 73 65 72 73 2e 20 54 68 65 72 65 20  BU users. There 
5600: 69 73 20 6e 6f 20 68 61 72 6d 20 69 6e 20 61 6e  is no harm in an
5610: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 61 63 63   application acc
5620: 65 73 73 69 6e 67 20 74 68 65 20 0a 2a 2a 20 66  essing the .** f
5630: 69 6c 65 2d 73 79 73 74 65 6d 20 76 69 61 20 22  ile-system via "
5640: 72 62 75 22 20 61 6c 6c 20 74 68 65 20 74 69 6d  rbu" all the tim
5650: 65 2c 20 65 76 65 6e 20 69 66 20 69 74 20 6f 6e  e, even if it on
5660: 6c 79 20 75 73 65 73 20 52 42 55 20 66 75 6e 63  ly uses RBU func
5670: 74 69 6f 6e 61 6c 69 74 79 20 0a 2a 2a 20 6f 63  tionality .** oc
5680: 63 61 73 69 6f 6e 61 6c 6c 79 2e 0a 2a 2f 0a 69  casionally..*/.i
5690: 6e 74 20 73 71 6c 69 74 65 33 72 62 75 5f 63 72  nt sqlite3rbu_cr
56a0: 65 61 74 65 5f 76 66 73 28 63 6f 6e 73 74 20 63  eate_vfs(const c
56b0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 63 6f 6e 73  har *zName, cons
56c0: 74 20 63 68 61 72 20 2a 7a 50 61 72 65 6e 74 29  t char *zParent)
56d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 44 65 72 65 67 69 73  ;../*.** Deregis
56e0: 74 65 72 20 61 6e 64 20 64 65 73 74 72 6f 79 20  ter and destroy 
56f0: 61 6e 20 52 42 55 20 76 66 73 20 63 72 65 61 74  an RBU vfs creat
5700: 65 64 20 62 79 20 61 6e 20 65 61 72 6c 69 65 72  ed by an earlier
5710: 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
5720: 74 65 33 72 62 75 5f 63 72 65 61 74 65 5f 76 66  te3rbu_create_vf
5730: 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 56 46 53 20 6f  s()..**.** VFS o
5740: 62 6a 65 63 74 73 20 61 72 65 20 6e 6f 74 20 72  bjects are not r
5750: 65 66 65 72 65 6e 63 65 20 63 6f 75 6e 74 65 64  eference counted
5760: 2e 20 49 66 20 61 20 56 46 53 20 6f 62 6a 65 63  . If a VFS objec
5770: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  t is destroyed.*
5780: 2a 20 62 65 66 6f 72 65 20 61 6c 6c 20 64 61 74  * before all dat
5790: 61 62 61 73 65 20 68 61 6e 64 6c 65 73 20 74 68  abase handles th
57a0: 61 74 20 75 73 65 20 69 74 20 68 61 76 65 20 62  at use it have b
57b0: 65 65 6e 20 63 6c 6f 73 65 64 2c 20 74 68 65 20  een closed, the 
57c0: 72 65 73 75 6c 74 73 0a 2a 2a 20 61 72 65 20 75  results.** are u
57d0: 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69  ndefined..*/.voi
57e0: 64 20 73 71 6c 69 74 65 33 72 62 75 5f 64 65 73  d sqlite3rbu_des
57f0: 74 72 6f 79 5f 76 66 73 28 63 6f 6e 73 74 20 63  troy_vfs(const c
5800: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 23 69  har *zName);..#i
5810: 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73  fdef __cplusplus
5820: 0a 7d 20 20 2f 2a 20 65 6e 64 20 6f 66 20 74 68  .}  /* end of th
5830: 65 20 27 65 78 74 65 72 6e 20 22 43 22 27 20 62  e 'extern "C"' b
5840: 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a  lock */.#endif..
5850: 23 65 6e 64 69 66 20 2f 2a 20 5f 53 51 4c 49 54  #endif /* _SQLIT
5860: 45 33 52 42 55 5f 48 20 2a 2f 0a                 E3RBU_H */.