Documentation Source Text

Hex Artifact Content
Login

Artifact c88e9da03ab1b94612dbdf29b4e364e1bb6a53385eb742abe131d4f75a3af0a4:


0000: 3c 74 69 74 6c 65 3e 54 68 65 20 52 42 55 20 45  <title>The RBU E
0010: 78 74 65 6e 73 69 6f 6e 3c 2f 74 69 74 6c 65 3e  xtension</title>
0020: 0a 3c 74 63 6c 3e 0a 68 64 5f 6b 65 79 77 6f 72  .<tcl>.hd_keywor
0030: 64 73 20 7b 52 42 55 7d 20 7b 52 42 55 20 65 78  ds {RBU} {RBU ex
0040: 74 65 6e 73 69 6f 6e 7d 0a 3c 2f 74 63 6c 3e 0a  tension}.</tcl>.
0050: 3c 74 61 62 6c 65 5f 6f 66 5f 63 6f 6e 74 65 6e  <table_of_conten
0060: 74 73 3e 0a 3c 68 31 20 61 6c 69 67 6e 3d 27 63  ts>.<h1 align='c
0070: 65 6e 74 65 72 27 3e 54 68 65 20 52 42 55 20 45  enter'>The RBU E
0080: 78 74 65 6e 73 69 6f 6e 3c 2f 68 31 3e 0a 0a 3c  xtension</h1>..<
0090: 70 3e 54 68 65 20 52 42 55 20 65 78 74 65 6e 73  p>The RBU extens
00a0: 69 6f 6e 20 69 73 20 61 6e 20 61 64 64 2d 6f 6e  ion is an add-on
00b0: 20 66 6f 72 20 53 51 4c 69 74 65 20 64 65 73 69   for SQLite desi
00c0: 67 6e 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  gned for use wit
00d0: 68 20 6c 61 72 67 65 20 0a 53 51 4c 69 74 65 20  h large .SQLite 
00e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
00f0: 6e 20 6c 6f 77 2d 70 6f 77 65 72 20 64 65 76 69  n low-power devi
0100: 63 65 73 20 61 74 20 74 68 65 20 65 64 67 65 20  ces at the edge 
0110: 6f 66 20 61 20 6e 65 74 77 6f 72 6b 2e 20 52 42  of a network. RB
0120: 55 0a 6d 61 79 20 62 65 20 75 73 65 64 20 66 6f  U.may be used fo
0130: 72 20 74 77 6f 20 73 65 70 61 72 61 74 65 20 74  r two separate t
0140: 61 73 6b 73 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c  asks:..<ul>.  <l
0150: 69 3e 20 3c 62 3e 52 42 55 20 55 70 64 61 74 65  i> <b>RBU Update
0160: 20 6f 70 65 72 61 74 69 6f 6e 73 3c 2f 62 3e 2e   operations</b>.
0170: 20 41 6e 20 5b 52 42 55 20 55 70 64 61 74 65 5d   An [RBU Update]
0180: 20 69 73 20 61 20 62 75 6c 6b 20 75 70 64 61 74   is a bulk updat
0190: 65 20 6f 66 20 61 0a 20 20 20 20 20 20 20 20 20  e of a.         
01a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
01b0: 68 61 74 20 6d 61 79 20 69 6e 63 6c 75 64 65 20  hat may include 
01c0: 6d 61 6e 79 20 69 6e 73 65 72 74 2c 20 75 70 64  many insert, upd
01d0: 61 74 65 20 61 6e 64 20 64 65 6c 65 74 65 0a 20  ate and delete. 
01e0: 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69           operati
01f0: 6f 6e 73 20 6f 6e 20 6f 6e 65 20 6f 72 20 6d 6f  ons on one or mo
0200: 72 65 20 74 61 62 6c 65 73 2e 0a 20 20 3c 6c 69  re tables..  <li
0210: 3e 20 3c 62 3e 52 42 55 20 56 61 63 75 75 6d 20  > <b>RBU Vacuum 
0220: 6f 70 65 72 61 74 69 6f 6e 73 3c 2f 62 3e 2e 20  operations</b>. 
0230: 41 6e 20 5b 52 42 55 20 56 61 63 75 75 6d 5d 20  An [RBU Vacuum] 
0240: 6f 70 74 69 6d 69 7a 65 73 20 61 6e 64 20 72 65  optimizes and re
0250: 62 75 69 6c 64 73 20 61 6e 0a 20 20 20 20 20 20  builds an.      
0260: 20 20 20 20 65 6e 74 69 72 65 20 64 61 74 61 62      entire datab
0270: 61 73 65 20 66 69 6c 65 2c 20 77 69 74 68 20 72  ase file, with r
0280: 65 73 75 6c 74 73 20 73 69 6d 69 6c 61 72 20 74  esults similar t
0290: 6f 20 53 51 4c 69 74 65 27 73 20 6e 61 74 69 76  o SQLite's nativ
02a0: 65 20 56 41 43 55 55 4d 0a 20 20 20 20 20 20 20  e VACUUM.       
02b0: 20 20 20 63 6f 6d 6d 61 6e 64 2e 20 20 0a 3c 2f     command.  .</
02c0: 75 6c 3e 0a 0a 3c 70 3e 54 68 65 20 61 63 72 6f  ul>..<p>The acro
02d0: 6e 79 6d 20 52 42 55 20 73 74 61 6e 64 73 20 66  nym RBU stands f
02e0: 6f 72 20 22 52 65 73 75 6d 61 62 6c 65 20 42 75  or "Resumable Bu
02f0: 6c 6b 20 55 70 64 61 74 65 22 2e 0a 0a 3c 70 3e  lk Update"...<p>
0300: 42 6f 74 68 20 6f 66 20 74 68 65 20 52 42 55 20  Both of the RBU 
0310: 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
0320: 20 61 63 63 6f 6d 70 6c 69 73 68 65 64 20 75 73   accomplished us
0330: 69 6e 67 20 53 51 4c 69 74 65 27 73 20 62 75 69  ing SQLite's bui
0340: 6c 74 2d 69 6e 20 0a 53 51 4c 20 63 6f 6d 6d 61  lt-in .SQL comma
0350: 6e 64 73 20 2d 20 52 42 55 20 75 70 64 61 74 65  nds - RBU update
0360: 20 76 69 61 20 61 20 73 65 72 69 65 73 20 6f 66   via a series of
0370: 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 44 45 4c 45   [INSERT], [DELE
0380: 54 45 5d 20 61 6e 64 20 0a 5b 55 50 44 41 54 45  TE] and .[UPDATE
0390: 5d 20 63 6f 6d 6d 61 6e 64 73 20 77 69 74 68 69  ] commands withi
03a0: 6e 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73  n a single trans
03b0: 61 63 74 69 6f 6e 2c 20 61 6e 64 20 52 42 55 20  action, and RBU 
03c0: 76 61 63 75 75 6d 20 62 79 20 61 20 73 69 6e 67  vacuum by a sing
03d0: 6c 65 0a 5b 56 41 43 55 55 4d 5d 20 63 6f 6d 6d  le.[VACUUM] comm
03e0: 61 6e 64 2e 20 20 54 68 65 20 52 42 55 20 6d 6f  and.  The RBU mo
03f0: 64 75 6c 65 20 70 72 6f 76 69 64 65 73 20 74 68  dule provides th
0400: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 64 76 61  e following adva
0410: 6e 74 61 67 65 73 20 6f 76 65 72 0a 74 68 65 73  ntages over.thes
0420: 65 20 73 69 6d 70 6c 65 72 20 61 70 70 72 6f 61  e simpler approa
0430: 63 68 65 73 3a 0a 0a 0a 3c 6f 6c 3e 0a 3c 6c 69  ches:...<ol>.<li
0440: 3e 3c 62 3e 52 42 55 20 6d 61 79 20 62 65 20 6d  ><b>RBU may be m
0450: 6f 72 65 20 65 66 66 69 63 69 65 6e 74 3c 2f 62  ore efficient</b
0460: 3e 0a 0a 3c 70 3e 54 68 65 20 6d 6f 73 74 20 65  >..<p>The most e
0470: 66 66 69 63 69 65 6e 74 20 77 61 79 20 74 6f 20  fficient way to 
0480: 61 70 70 6c 79 20 63 68 61 6e 67 65 73 20 74 6f  apply changes to
0490: 20 61 20 42 2d 54 72 65 65 20 28 74 68 65 20 64   a B-Tree (the d
04a0: 61 74 61 20 73 74 72 75 63 74 75 72 65 0a 74 68  ata structure.th
04b0: 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  at SQLite uses t
04c0: 6f 20 73 74 6f 72 65 20 65 61 63 68 20 74 61 62  o store each tab
04d0: 6c 65 20 61 6e 64 20 69 6e 64 65 78 20 6f 6e 20  le and index on 
04e0: 64 69 73 6b 29 20 69 73 20 74 6f 20 6d 61 6b 65  disk) is to make
04f0: 20 74 68 65 0a 63 68 61 6e 67 65 73 20 69 6e 20   the.changes in 
0500: 6b 65 79 20 6f 72 64 65 72 2e 20 42 75 74 20 69  key order. But i
0510: 66 20 61 6e 20 53 51 4c 20 74 61 62 6c 65 20 68  f an SQL table h
0520: 61 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 69  as one or more i
0530: 6e 64 65 78 65 73 2c 20 74 68 65 20 6b 65 79 0a  ndexes, the key.
0540: 6f 72 64 65 72 20 66 6f 72 20 65 61 63 68 20 69  order for each i
0550: 6e 64 65 78 20 6d 61 79 20 62 65 20 64 69 66 66  ndex may be diff
0560: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 6d  erent from the m
0570: 61 69 6e 20 74 61 62 6c 65 20 61 6e 64 20 74 68  ain table and th
0580: 65 20 6f 74 68 65 72 0a 61 75 78 69 6c 69 61 72  e other.auxiliar
0590: 79 20 69 6e 64 65 78 65 73 2e 20 41 73 20 61 20  y indexes. As a 
05a0: 72 65 73 75 6c 74 2c 20 77 68 65 6e 20 65 78 65  result, when exe
05b0: 63 75 74 69 6e 67 20 61 20 73 65 72 69 65 73 20  cuting a series 
05c0: 6f 66 20 5b 49 4e 53 45 52 54 5d 2c 0a 5b 55 50  of [INSERT],.[UP
05d0: 44 41 54 45 5d 20 61 6e 64 20 5b 44 45 4c 45 54  DATE] and [DELET
05e0: 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 69 74  E] statements it
05f0: 20 69 73 20 6e 6f 74 20 67 65 6e 65 72 61 6c 6c   is not generall
0600: 79 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 72  y possible to or
0610: 64 65 72 20 74 68 65 0a 6f 70 65 72 61 74 69 6f  der the.operatio
0620: 6e 73 20 73 6f 20 74 68 61 74 20 61 6c 6c 20 62  ns so that all b
0630: 2d 74 72 65 65 73 20 61 72 65 20 75 70 64 61 74  -trees are updat
0640: 65 64 20 69 6e 20 6b 65 79 20 6f 72 64 65 72 2e  ed in key order.
0650: 20 54 68 65 20 52 42 55 20 75 70 64 61 74 65 0a   The RBU update.
0660: 70 72 6f 63 65 73 73 20 77 6f 72 6b 73 20 61 72  process works ar
0670: 6f 75 6e 64 20 74 68 69 73 20 62 79 20 61 70 70  ound this by app
0680: 6c 79 69 6e 67 20 61 6c 6c 20 63 68 61 6e 67 65  lying all change
0690: 73 20 74 6f 20 74 68 65 20 6d 61 69 6e 20 74 61  s to the main ta
06a0: 62 6c 65 20 69 6e 20 6f 6e 65 20 0a 70 61 73 73  ble in one .pass
06b0: 2c 20 74 68 65 6e 20 61 70 70 6c 79 69 6e 67 20  , then applying 
06c0: 63 68 61 6e 67 65 73 20 74 6f 20 65 61 63 68 20  changes to each 
06d0: 69 6e 64 65 78 20 69 6e 20 73 65 70 61 72 61 74  index in separat
06e0: 65 20 70 61 73 73 65 73 2c 20 65 6e 73 75 72 69  e passes, ensuri
06f0: 6e 67 20 65 61 63 68 0a 42 2d 54 72 65 65 20 69  ng each.B-Tree i
0700: 73 20 75 70 64 61 74 65 64 20 6f 70 74 69 6d 61  s updated optima
0710: 6c 6c 79 2e 20 46 6f 72 20 61 20 6c 61 72 67 65  lly. For a large
0720: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 28   database file (
0730: 6f 6e 65 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  one that does no
0740: 74 0a 66 69 74 20 69 6e 20 74 68 65 20 4f 53 20  t.fit in the OS 
0750: 64 69 73 6b 20 63 61 63 68 65 29 20 74 68 69 73  disk cache) this
0760: 20 70 72 6f 63 65 64 75 72 65 20 63 61 6e 20 72   procedure can r
0770: 65 73 75 6c 74 20 69 6e 20 74 77 6f 20 6f 72 64  esult in two ord
0780: 65 72 73 20 6f 66 0a 6d 61 67 6e 69 74 75 64 65  ers of.magnitude
0790: 20 66 61 73 74 65 72 20 75 70 64 61 74 65 73 2e   faster updates.
07a0: 0a 0a 3c 70 3e 41 6e 20 52 42 55 20 56 61 63 75  ..<p>An RBU Vacu
07b0: 75 6d 20 6f 70 65 72 61 74 69 6f 6e 20 72 65 71  um operation req
07c0: 75 69 72 65 73 20 6c 65 73 73 20 74 65 6d 70 6f  uires less tempo
07d0: 72 61 72 79 20 64 69 73 6b 20 73 70 61 63 65 20  rary disk space 
07e0: 61 6e 64 20 77 72 69 74 65 73 0a 6c 65 73 73 20  and writes.less 
07f0: 64 61 74 61 20 74 6f 20 64 69 73 6b 20 74 68 61  data to disk tha
0800: 6e 20 61 6e 20 53 51 4c 69 74 65 20 56 41 43 55  n an SQLite VACU
0810: 55 4d 2e 20 41 6e 20 53 51 4c 69 74 65 20 56 41  UM. An SQLite VA
0820: 43 55 55 4d 20 72 65 71 75 69 72 65 73 20 72 6f  CUUM requires ro
0830: 75 67 68 6c 79 0a 74 77 69 63 65 20 74 68 65 20  ughly.twice the 
0840: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6e 61  size of the fina
0850: 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  l database file 
0860: 69 6e 20 74 65 6d 70 6f 72 61 72 79 20 64 69 73  in temporary dis
0870: 6b 20 73 70 61 63 65 20 74 6f 20 72 75 6e 2e 0a  k space to run..
0880: 54 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74  The total amount
0890: 20 6f 66 20 64 61 74 61 20 77 72 69 74 74 65 6e   of data written
08a0: 20 69 73 20 61 72 6f 75 6e 64 20 74 68 72 65 65   is around three
08b0: 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20   times the size 
08c0: 6f 66 20 74 68 65 0a 66 69 6e 61 6c 20 64 61 74  of the.final dat
08d0: 61 62 61 73 65 20 66 69 6c 65 2e 20 42 79 20 63  abase file. By c
08e0: 6f 6e 74 72 61 73 74 2c 20 61 6e 20 52 42 55 20  ontrast, an RBU 
08f0: 56 61 63 75 75 6d 20 72 65 71 75 69 72 65 73 20  Vacuum requires 
0900: 72 6f 75 67 68 6c 79 20 74 68 65 20 73 69 7a 65  roughly the size
0910: 0a 6f 66 20 74 68 65 20 66 69 6e 61 6c 20 64 61  .of the final da
0920: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 74  tabase file in t
0930: 65 6d 70 6f 72 61 72 79 20 64 69 73 6b 20 73 70  emporary disk sp
0940: 61 63 65 20 61 6e 64 20 77 72 69 74 65 73 20 61  ace and writes a
0950: 20 74 6f 74 61 6c 20 6f 66 0a 74 77 69 63 65 20   total of.twice 
0960: 74 68 61 74 20 74 6f 20 64 69 73 6b 2e 0a 0a 3c  that to disk...<
0970: 70 3e 4f 6e 20 74 68 65 20 6f 74 68 65 72 20 68  p>On the other h
0980: 61 6e 64 2c 20 61 6e 20 52 42 55 20 56 61 63 75  and, an RBU Vacu
0990: 75 6d 20 75 73 65 73 20 6d 6f 72 65 20 43 50 55  um uses more CPU
09a0: 20 74 68 61 6e 20 61 20 72 65 67 75 6c 61 72 20   than a regular 
09b0: 53 51 4c 69 74 65 0a 56 41 43 55 55 4d 20 2d 20  SQLite.VACUUM - 
09c0: 69 6e 20 6f 6e 65 20 74 65 73 74 20 61 73 20 6d  in one test as m
09d0: 75 63 68 20 61 73 20 66 69 76 65 20 74 69 6d 65  uch as five time
09e0: 73 20 61 73 20 6d 75 63 68 2e 20 46 6f 72 20 74  s as much. For t
09f0: 68 69 73 20 72 65 61 73 6f 6e 2c 20 61 6e 20 52  his reason, an R
0a00: 42 55 0a 56 61 63 75 75 6d 20 69 73 20 6f 66 74  BU.Vacuum is oft
0a10: 65 6e 20 73 69 67 6e 69 66 69 63 61 6e 74 6c 79  en significantly
0a20: 20 73 6c 6f 77 65 72 20 74 68 61 6e 20 61 6e 20   slower than an 
0a30: 53 51 4c 69 74 65 20 56 41 43 55 55 4d 20 75 6e  SQLite VACUUM un
0a40: 64 65 72 20 74 68 65 20 73 61 6d 65 0a 63 6f 6e  der the same.con
0a50: 64 69 74 69 6f 6e 73 2e 0a 0a 3c 6c 69 3e 3c 62  ditions...<li><b
0a60: 3e 52 42 55 20 72 75 6e 73 20 69 6e 20 74 68 65  >RBU runs in the
0a70: 20 62 61 63 6b 67 72 6f 75 6e 64 3c 2f 62 3e 0a   background</b>.
0a80: 0a 3c 70 3e 41 6e 20 6f 6e 67 6f 69 6e 67 20 52  .<p>An ongoing R
0a90: 42 55 20 6f 70 65 72 61 74 69 6f 6e 20 28 65 69  BU operation (ei
0aa0: 74 68 65 72 20 61 6e 20 75 70 64 61 74 65 20 6f  ther an update o
0ab0: 72 20 61 20 76 61 63 75 75 6d 29 20 64 6f 65 73  r a vacuum) does
0ac0: 20 6e 6f 74 0a 69 6e 74 65 72 66 65 72 65 20 77   not.interfere w
0ad0: 69 74 68 20 72 65 61 64 20 61 63 63 65 73 73 20  ith read access 
0ae0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
0af0: 66 69 6c 65 2e 0a 0a 3c 6c 69 3e 3c 62 3e 52 42  file...<li><b>RB
0b00: 55 20 72 75 6e 73 20 69 6e 63 72 65 6d 65 6e 74  U runs increment
0b10: 61 6c 6c 79 3c 2f 62 3e 0a 0a 3c 70 3e 52 42 55  ally</b>..<p>RBU
0b20: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6d 61 79 20   operations may 
0b30: 62 65 20 73 75 73 70 65 6e 64 65 64 20 61 6e 64  be suspended and
0b40: 20 74 68 65 6e 20 6c 61 74 65 72 20 72 65 73 75   then later resu
0b50: 6d 65 64 2c 20 70 65 72 68 61 70 73 20 77 69 74  med, perhaps wit
0b60: 68 0a 69 6e 74 65 72 76 65 6e 69 6e 67 20 70 6f  h.intervening po
0b70: 77 65 72 20 6f 75 74 61 67 65 73 20 61 6e 64 2f  wer outages and/
0b80: 6f 72 20 73 79 73 74 65 6d 20 72 65 73 65 74 73  or system resets
0b90: 2e 20 46 6f 72 20 61 6e 20 52 42 55 20 75 70 64  . For an RBU upd
0ba0: 61 74 65 2c 20 74 68 65 0a 6f 72 69 67 69 6e 61  ate, the.origina
0bb0: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 74 65  l database conte
0bc0: 6e 74 20 72 65 6d 61 69 6e 73 20 76 69 73 69 62  nt remains visib
0bd0: 6c 65 20 74 6f 20 61 6c 6c 20 64 61 74 61 62 61  le to all databa
0be0: 73 65 20 72 65 61 64 65 72 73 20 75 6e 74 69 6c  se readers until
0bf0: 20 0a 74 68 65 20 65 6e 74 69 72 65 20 75 70 64   .the entire upd
0c00: 61 74 65 20 68 61 73 20 62 65 65 6e 20 61 70 70  ate has been app
0c10: 6c 69 65 64 20 2d 20 65 76 65 6e 20 69 66 20 74  lied - even if t
0c20: 68 65 20 75 70 64 61 74 65 20 69 73 20 73 75 73  he update is sus
0c30: 70 65 6e 64 65 64 20 61 6e 64 0a 74 68 65 6e 20  pended and.then 
0c40: 6c 61 74 65 72 20 72 65 73 75 6d 65 64 2e 0a 0a  later resumed...
0c50: 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 54 68 65 20 52 42  </ol>..<p>The RB
0c60: 55 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 6e  U extension is n
0c70: 6f 74 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  ot enabled by de
0c80: 66 61 75 6c 74 2e 20 54 6f 20 65 6e 61 62 6c 65  fault. To enable
0c90: 20 69 74 2c 20 63 6f 6d 70 69 6c 65 20 74 68 65   it, compile the
0ca0: 0a 5b 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 5d 20  .[amalgamation] 
0cb0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
0cc0: 5f 45 4e 41 42 4c 45 5f 52 42 55 5d 20 63 6f 6d  _ENABLE_RBU] com
0cd0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
0ce0: 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  ...<tcl>hd_fragm
0cf0: 65 6e 74 20 72 62 75 5f 75 70 64 61 74 65 73 20  ent rbu_updates 
0d00: 7b 52 42 55 20 55 70 64 61 74 65 7d 3c 2f 74 63  {RBU Update}</tc
0d10: 6c 3e 0a 3c 68 31 3e 52 42 55 20 55 70 64 61 74  l>.<h1>RBU Updat
0d20: 65 73 3c 2f 68 31 3e 0a 3c 68 32 3e 52 42 55 20  es</h1>.<h2>RBU 
0d30: 55 70 64 61 74 65 20 4c 69 6d 69 74 61 74 69 6f  Update Limitatio
0d40: 6e 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20  ns</h2>..<p>The 
0d50: 66 6f 6c 6c 6f 77 69 6e 67 20 6c 69 6d 69 74 61  following limita
0d60: 74 69 6f 6e 73 20 61 70 70 6c 79 20 74 6f 20 52  tions apply to R
0d70: 42 55 20 75 70 64 61 74 65 73 3a 0a 0a 3c 75 6c  BU updates:..<ul
0d80: 3e 0a 3c 6c 69 3e 3c 70 3e 54 68 65 20 63 68 61  >.<li><p>The cha
0d90: 6e 67 65 73 20 6d 75 73 74 20 63 6f 6e 73 69 73  nges must consis
0da0: 74 20 6f 66 20 5b 49 4e 53 45 52 54 5d 2c 20 5b  t of [INSERT], [
0db0: 55 50 44 41 54 45 5d 2c 20 61 6e 64 20 5b 44 45  UPDATE], and [DE
0dc0: 4c 45 54 45 5d 0a 20 20 20 20 6f 70 65 72 61 74  LETE].    operat
0dd0: 69 6f 6e 73 20 6f 6e 6c 79 2e 20 20 43 52 45 41  ions only.  CREA
0de0: 54 45 20 61 6e 64 20 44 52 4f 50 20 6f 70 65 72  TE and DROP oper
0df0: 61 74 69 6f 6e 73 20 61 72 65 20 6e 6f 74 0a 20  ations are not. 
0e00: 20 20 20 73 75 70 70 6f 72 74 65 64 2e 3c 2f 70     supported.</p
0e10: 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 5b 49  ></li>.<li><p>[I
0e20: 4e 53 45 52 54 5d 20 73 74 61 74 65 6d 65 6e 74  NSERT] statement
0e30: 73 20 6d 61 79 20 6e 6f 74 20 75 73 65 20 64 65  s may not use de
0e40: 66 61 75 6c 74 20 76 61 6c 75 65 73 2e 3c 2f 70  fault values.</p
0e50: 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 5b 55  ></li>.<li><p>[U
0e60: 50 44 41 54 45 5d 20 61 6e 64 20 5b 44 45 4c 45  PDATE] and [DELE
0e70: 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  TE] statements m
0e80: 75 73 74 20 69 64 65 6e 74 69 66 79 20 74 68 65  ust identify the
0e90: 20 74 61 72 67 65 74 20 72 6f 77 73 0a 20 20 20   target rows.   
0ea0: 20 62 79 20 72 6f 77 69 64 20 6f 72 20 62 79 20   by rowid or by 
0eb0: 6e 6f 6e 2d 4e 55 4c 4c 20 50 52 49 4d 41 52 59  non-NULL PRIMARY
0ec0: 20 4b 45 59 20 76 61 6c 75 65 73 2e 3c 2f 70 3e   KEY values.</p>
0ed0: 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 5b 55 50  </li>.<li><p>[UP
0ee0: 44 41 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  DATE] statements
0ef0: 20 6d 61 79 20 6e 6f 74 20 6d 6f 64 69 66 79 20   may not modify 
0f00: 50 52 49 4d 41 52 59 20 4b 45 59 20 6f 72 20 72  PRIMARY KEY or r
0f10: 6f 77 69 64 20 76 61 6c 75 65 73 2e 0a 20 20 20  owid values..   
0f20: 20 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c   </p></li>.<li><
0f30: 70 3e 52 42 55 20 75 70 64 61 74 65 73 20 63 61  p>RBU updates ca
0f40: 6e 6e 6f 74 20 62 65 20 61 70 70 6c 69 65 64 20  nnot be applied 
0f50: 74 6f 20 61 6e 79 20 74 61 62 6c 65 73 20 74 68  to any tables th
0f60: 61 74 20 63 6f 6e 74 61 69 6e 20 61 20 63 6f 6c  at contain a col
0f70: 75 6d 6e 0a 20 20 20 20 20 20 20 6e 61 6d 65 64  umn.       named
0f80: 20 22 72 62 75 5f 63 6f 6e 74 72 6f 6c 22 2e 3c   "rbu_control".<
0f90: 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e  /p></li>.<li><p>
0fa0: 54 68 65 20 52 42 55 20 75 70 64 61 74 65 20 77  The RBU update w
0fb0: 69 6c 6c 20 6e 6f 74 20 66 69 72 65 20 61 6e 79  ill not fire any
0fc0: 20 74 72 69 67 67 65 72 73 2e 3c 2f 70 3e 3c 2f   triggers.</p></
0fd0: 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 54 68 65 20 52  li>.<li><p>The R
0fe0: 42 55 20 75 70 64 61 74 65 20 77 69 6c 6c 20 6e  BU update will n
0ff0: 6f 74 20 64 65 74 65 63 74 20 6f 72 20 70 72 65  ot detect or pre
1000: 76 65 6e 74 20 66 6f 72 65 69 67 6e 20 6b 65 79  vent foreign key
1010: 20 6f 72 0a 20 20 20 20 20 20 20 43 48 45 43 4b   or.       CHECK
1020: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
1030: 61 74 69 6f 6e 73 2e 3c 2f 70 3e 3c 2f 6c 69 3e  ations.</p></li>
1040: 0a 3c 6c 69 3e 3c 70 3e 41 6c 6c 20 52 42 55 20  .<li><p>All RBU 
1050: 75 70 64 61 74 65 73 20 75 73 65 20 74 68 65 20  updates use the 
1060: 22 4f 52 20 52 4f 4c 4c 42 41 43 4b 22 20 63 6f  "OR ROLLBACK" co
1070: 6e 73 74 72 61 69 6e 74 20 68 61 6e 64 6c 69 6e  nstraint handlin
1080: 67 20 6d 65 63 68 61 6e 69 73 6d 2e 0a 20 20 20  g mechanism..   
1090: 20 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c   </p></li>.<li><
10a0: 70 3e 54 68 65 20 74 61 72 67 65 74 20 64 61 74  p>The target dat
10b0: 61 62 61 73 65 20 6d 61 79 20 6e 6f 74 20 62 65  abase may not be
10c0: 20 69 6e 20 5b 57 41 4c 20 6d 6f 64 65 5d 2e 3c   in [WAL mode].<
10d0: 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e  /p></li>.<li><p>
10e0: 54 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62  The target datab
10f0: 61 73 65 20 6d 61 79 20 6e 6f 74 20 63 6f 6e 74  ase may not cont
1100: 61 69 6e 20 5b 69 6e 64 65 78 65 73 20 6f 6e 20  ain [indexes on 
1110: 65 78 70 72 65 73 73 69 6f 6e 73 5d 2e 0a 3c 6c  expressions]..<l
1120: 69 3e 3c 70 3e 4e 6f 20 6f 74 68 65 72 20 77 72  i><p>No other wr
1130: 69 74 65 73 20 6d 61 79 20 6f 63 63 75 72 20 6f  ites may occur o
1140: 6e 20 74 68 65 20 74 61 72 67 65 74 20 64 61 74  n the target dat
1150: 61 62 61 73 65 20 77 68 69 6c 65 20 74 68 65 0a  abase while the.
1160: 20 20 20 20 20 20 20 52 42 55 20 75 70 64 61 74         RBU updat
1170: 65 20 69 73 20 62 65 69 6e 67 20 61 70 70 6c 69  e is being appli
1180: 65 64 2e 20 20 41 20 72 65 61 64 2d 6c 6f 63 6b  ed.  A read-lock
1190: 20 69 73 20 68 65 6c 64 20 6f 6e 20 74 68 65 20   is held on the 
11a0: 74 61 72 67 65 74 0a 20 20 20 20 20 20 20 64 61  target.       da
11b0: 74 61 62 61 73 65 20 74 6f 20 70 72 65 76 65 6e  tabase to preven
11c0: 74 20 74 68 69 73 2e 3c 2f 70 3e 3c 2f 6c 69 3e  t this.</p></li>
11d0: 0a 3c 2f 75 6c 3e 0a 0a 0a 3c 68 32 3e 50 72 65  .</ul>...<h2>Pre
11e0: 70 61 72 69 6e 67 20 61 6e 20 52 42 55 20 55 70  paring an RBU Up
11f0: 64 61 74 65 20 46 69 6c 65 3c 2f 68 32 3e 0a 0a  date File</h2>..
1200: 3c 70 3e 41 6c 6c 20 63 68 61 6e 67 65 73 20 74  <p>All changes t
1210: 6f 20 62 65 20 61 70 70 6c 69 65 64 20 62 79 20  o be applied by 
1220: 52 42 55 20 61 72 65 20 73 74 6f 72 65 64 20 69  RBU are stored i
1230: 6e 20 61 20 73 65 70 61 72 61 74 65 20 53 51 4c  n a separate SQL
1240: 69 74 65 20 64 61 74 61 62 61 73 65 0a 63 61 6c  ite database.cal
1250: 6c 65 64 20 74 68 65 20 22 52 42 55 20 64 61 74  led the "RBU dat
1260: 61 62 61 73 65 22 2e 20 20 54 68 65 20 64 61 74  abase".  The dat
1270: 61 62 61 73 65 20 74 68 61 74 20 69 73 20 74 6f  abase that is to
1280: 20 62 65 20 6d 6f 64 69 66 69 65 64 20 69 73 20   be modified is 
1290: 63 61 6c 6c 65 64 0a 74 68 65 20 22 74 61 72 67  called.the "targ
12a0: 65 74 20 64 61 74 61 62 61 73 65 22 2e 0a 0a 3c  et database"...<
12b0: 70 3e 46 6f 72 20 65 61 63 68 20 74 61 62 6c 65  p>For each table
12c0: 20 69 6e 20 74 68 65 20 74 61 72 67 65 74 20 64   in the target d
12d0: 61 74 61 62 61 73 65 20 74 68 61 74 20 77 69 6c  atabase that wil
12e0: 6c 20 62 65 20 6d 6f 64 69 66 69 65 64 20 62 79  l be modified by
12f0: 20 74 68 65 20 75 70 64 61 74 65 2c 0a 61 20 63   the update,.a c
1300: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 74 61 62  orresponding tab
1310: 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 77 69  le is created wi
1320: 74 68 69 6e 20 74 68 65 20 52 42 55 20 64 61 74  thin the RBU dat
1330: 61 62 61 73 65 2e 20 54 68 65 20 52 42 55 20 64  abase. The RBU d
1340: 61 74 61 62 61 73 65 0a 74 61 62 6c 65 20 73 63  atabase.table sc
1350: 68 65 6d 61 20 69 73 20 6e 6f 74 20 74 68 65 20  hema is not the 
1360: 73 61 6d 65 20 61 73 20 74 68 61 74 20 6f 66 20  same as that of 
1370: 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62  the target datab
1380: 61 73 65 2c 20 62 75 74 20 69 73 20 64 65 72 69  ase, but is deri
1390: 76 65 64 0a 66 72 6f 6d 20 69 74 20 61 73 20 5b  ved.from it as [
13a0: 52 42 55 20 44 61 74 61 62 61 73 65 20 54 61 62  RBU Database Tab
13b0: 6c 65 73 20 7c 20 64 65 73 63 72 69 62 65 64 20  les | described 
13c0: 62 65 6c 6f 77 5d 2e 0a 0a 3c 70 3e 54 68 65 20  below]...<p>The 
13d0: 52 42 55 20 64 61 74 61 62 61 73 65 20 74 61 62  RBU database tab
13e0: 6c 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 73 69  le contains a si
13f0: 6e 67 6c 65 20 72 6f 77 20 66 6f 72 20 65 61 63  ngle row for eac
1400: 68 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73  h target databas
1410: 65 20 0a 72 6f 77 20 69 6e 73 65 72 74 65 64 2c  e .row inserted,
1420: 20 75 70 64 61 74 65 64 20 6f 72 20 64 65 6c 65   updated or dele
1430: 74 65 64 20 62 79 20 74 68 65 20 75 70 64 61 74  ted by the updat
1440: 65 2e 20 50 6f 70 75 6c 61 74 69 6e 67 20 74 68  e. Populating th
1450: 65 20 52 42 55 20 64 61 74 61 62 61 73 65 0a 74  e RBU database.t
1460: 61 62 6c 65 73 20 69 73 20 64 65 73 63 72 69 62  ables is describ
1470: 65 64 20 69 6e 20 5b 52 42 55 20 44 61 74 61 62  ed in [RBU Datab
1480: 61 73 65 20 43 6f 6e 74 65 6e 74 73 20 7c 20 74  ase Contents | t
1490: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 63  he following sec
14a0: 74 69 6f 6e 5d 2e 0a 3c 2f 70 3e 0a 0a 3c 74 63  tion]..</p>..<tc
14b0: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 64 61  l>hd_fragment da
14c0: 74 61 62 61 73 65 5f 74 61 62 6c 65 73 20 7b 52  tabase_tables {R
14d0: 42 55 20 44 61 74 61 62 61 73 65 20 54 61 62 6c  BU Database Tabl
14e0: 65 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 54 68  es}</tcl>.<h3>Th
14f0: 65 20 52 42 55 20 44 61 74 61 62 61 73 65 20 53  e RBU Database S
1500: 63 68 65 6d 61 3c 2f 68 33 3e 0a 0a 3c 70 3e 0a  chema</h3>..<p>.
1510: 46 6f 72 20 65 61 63 68 20 74 61 62 6c 65 20 69  For each table i
1520: 6e 20 74 68 65 20 74 61 72 67 65 74 20 64 61 74  n the target dat
1530: 61 62 61 73 65 2c 20 74 68 65 20 52 42 55 20 64  abase, the RBU d
1540: 61 74 61 62 61 73 65 20 73 68 6f 75 6c 64 20 63  atabase should c
1550: 6f 6e 74 61 69 6e 20 61 20 74 61 62 6c 65 0a 6e  ontain a table.n
1560: 61 6d 65 64 20 22 64 61 74 61 26 6c 74 3b 3c 69  amed "data&lt;<i
1570: 3e 69 6e 74 65 67 65 72 3c 2f 69 3e 26 67 74 3b  >integer</i>&gt;
1580: 5f 26 6c 74 3b 3c 69 3e 74 61 72 67 65 74 2d 74  _&lt;<i>target-t
1590: 61 62 6c 65 2d 6e 61 6d 65 3c 2f 69 3e 26 67 74  able-name</i>&gt
15a0: 3b 22 20 77 68 65 72 65 0a 26 6c 74 3b 3c 69 3e  ;" where.&lt;<i>
15b0: 74 61 72 67 65 74 2d 74 61 62 6c 65 2d 6e 61 6d  target-table-nam
15c0: 65 3c 2f 69 3e 26 67 74 3b 20 69 73 20 74 68 65  e</i>&gt; is the
15d0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
15e0: 6c 65 20 69 6e 20 74 68 65 20 74 61 72 67 65 74  le in the target
15f0: 0a 64 61 74 61 62 61 73 65 20 61 6e 64 20 26 6c  .database and &l
1600: 74 3b 3c 69 3e 69 6e 74 65 67 65 72 3c 2f 69 3e  t;<i>integer</i>
1610: 26 67 74 3b 20 69 73 20 61 6e 79 20 73 65 71 75  &gt; is any sequ
1620: 65 6e 63 65 20 6f 66 20 7a 65 72 6f 20 6f 72 20  ence of zero or 
1630: 6d 6f 72 65 20 6e 75 6d 65 72 69 63 0a 63 68 61  more numeric.cha
1640: 72 61 63 74 65 72 73 20 28 30 2d 39 29 2e 20 54  racters (0-9). T
1650: 61 62 6c 65 73 20 77 69 74 68 69 6e 20 74 68 65  ables within the
1660: 20 52 42 55 20 64 61 74 61 62 61 73 65 20 61 72   RBU database ar
1670: 65 20 70 72 6f 63 65 73 73 65 64 20 69 6e 20 6f  e processed in o
1680: 72 64 65 72 20 62 79 20 0a 6e 61 6d 65 20 28 66  rder by .name (f
1690: 72 6f 6d 20 73 6d 61 6c 6c 65 73 74 20 74 6f 20  rom smallest to 
16a0: 6c 61 72 67 65 73 74 20 61 63 63 6f 72 64 69 6e  largest accordin
16b0: 67 20 74 6f 20 74 68 65 20 42 49 4e 41 52 59 20  g to the BINARY 
16c0: 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
16d0: 63 65 29 2c 0a 73 6f 20 74 68 65 20 6f 72 64 65  ce),.so the orde
16e0: 72 20 69 6e 20 77 68 69 63 68 20 74 61 72 67 65  r in which targe
16f0: 74 20 74 61 62 6c 65 73 20 61 72 65 20 75 70 64  t tables are upd
1700: 61 74 65 64 20 69 73 20 69 6e 66 6c 75 65 6e 63  ated is influenc
1710: 65 64 20 62 79 20 74 68 65 20 73 65 6c 65 63 74  ed by the select
1720: 69 6f 6e 20 0a 6f 66 20 74 68 65 20 26 6c 74 3b  ion .of the &lt;
1730: 3c 69 3e 69 6e 74 65 67 65 72 3c 2f 69 3e 26 67  <i>integer</i>&g
1740: 74 3b 20 70 6f 72 74 69 6f 6e 20 6f 66 20 74 68  t; portion of th
1750: 65 20 64 61 74 61 5f 25 20 74 61 62 6c 65 20 6e  e data_% table n
1760: 61 6d 65 2e 20 57 68 69 6c 65 20 74 68 69 73 20  ame. While this 
1770: 63 61 6e 0a 62 65 20 75 73 65 66 75 6c 20 77 68  can.be useful wh
1780: 65 6e 20 75 73 69 6e 67 20 52 42 55 20 74 6f 20  en using RBU to 
1790: 75 70 64 61 74 65 20 0a 5b 52 42 55 20 46 54 53  update .[RBU FTS
17a0: 33 2f 34 20 54 61 62 6c 65 73 20 7c 20 63 65 72  3/4 Tables | cer
17b0: 74 61 69 6e 20 74 79 70 65 73 20 6f 66 20 76 69  tain types of vi
17c0: 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 74  rtual tables], t
17d0: 68 65 72 65 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  here is normally
17e0: 20 6e 6f 0a 72 65 61 73 6f 6e 20 74 6f 20 75 73   no.reason to us
17f0: 65 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  e anything other
1800: 20 74 68 61 6e 20 61 6e 20 65 6d 70 74 79 20 73   than an empty s
1810: 74 72 69 6e 67 20 69 6e 20 70 6c 61 63 65 20 6f  tring in place o
1820: 66 0a 26 6c 74 3b 3c 69 3e 69 6e 74 65 67 65 72  f.&lt;<i>integer
1830: 3c 2f 69 3e 26 67 74 3b 2e 0a 0a 3c 70 3e 54 68  </i>&gt;...<p>Th
1840: 65 20 64 61 74 61 5f 25 20 74 61 62 6c 65 20 6d  e data_% table m
1850: 75 73 74 20 68 61 76 65 20 61 6c 6c 20 74 68 65  ust have all the
1860: 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 73 20 61 73   same columns as
1870: 20 74 68 65 20 74 61 72 67 65 74 20 74 61 62 6c   the target tabl
1880: 65 2c 20 70 6c 75 73 0a 6f 6e 65 20 61 64 64 69  e, plus.one addi
1890: 74 69 6f 6e 61 6c 20 63 6f 6c 75 6d 6e 20 6e 61  tional column na
18a0: 6d 65 64 20 22 72 62 75 5f 63 6f 6e 74 72 6f 6c  med "rbu_control
18b0: 22 2e 20 54 68 65 20 64 61 74 61 5f 25 20 74 61  ". The data_% ta
18c0: 62 6c 65 20 73 68 6f 75 6c 64 20 68 61 76 65 20  ble should have 
18d0: 6e 6f 0a 50 52 49 4d 41 52 59 20 4b 45 59 20 6f  no.PRIMARY KEY o
18e0: 72 20 55 4e 49 51 55 45 20 63 6f 6e 73 74 72 61  r UNIQUE constra
18f0: 69 6e 74 73 2c 20 62 75 74 20 65 61 63 68 20 63  ints, but each c
1900: 6f 6c 75 6d 6e 20 73 68 6f 75 6c 64 20 68 61 76  olumn should hav
1910: 65 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20  e the same type 
1920: 61 73 0a 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  as.the correspon
1930: 64 69 6e 67 20 63 6f 6c 75 6d 6e 20 69 6e 20 74  ding column in t
1940: 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61  he target databa
1950: 73 65 2e 20 54 68 65 20 72 62 75 5f 63 6f 6e 74  se. The rbu_cont
1960: 72 6f 6c 20 63 6f 6c 75 6d 6e 20 73 68 6f 75 6c  rol column shoul
1970: 64 0a 68 61 76 65 20 6e 6f 20 74 79 70 65 20 61  d.have no type a
1980: 74 20 61 6c 6c 2e 20 46 6f 72 20 65 78 61 6d 70  t all. For examp
1990: 6c 65 2c 20 69 66 20 74 68 65 20 74 61 72 67 65  le, if the targe
19a0: 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 74 61  t database conta
19b0: 69 6e 73 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b  ins:..<codeblock
19c0: 3e 0a 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  >.CREATE TABLE t
19d0: 31 28 61 20 49 4e 54 45 47 45 52 20 50 52 49 4d  1(a INTEGER PRIM
19e0: 41 52 59 20 4b 45 59 2c 20 62 20 54 45 58 54 2c  ARY KEY, b TEXT,
19f0: 20 63 20 55 4e 49 51 55 45 29 3b 0a 3c 2f 63 6f   c UNIQUE);.</co
1a00: 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54 68 65  deblock>..<p>The
1a10: 6e 20 74 68 65 20 52 42 55 20 64 61 74 61 62 61  n the RBU databa
1a20: 73 65 20 73 68 6f 75 6c 64 20 63 6f 6e 74 61 69  se should contai
1a30: 6e 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  n:..<codeblock>.
1a40: 43 52 45 41 54 45 20 54 41 42 4c 45 20 64 61 74  CREATE TABLE dat
1a50: 61 5f 74 31 28 61 20 49 4e 54 45 47 45 52 2c 20  a_t1(a INTEGER, 
1a60: 62 20 54 45 58 54 2c 20 63 2c 20 72 62 75 5f 63  b TEXT, c, rbu_c
1a70: 6f 6e 74 72 6f 6c 29 3b 0a 3c 2f 63 6f 64 65 62  ontrol);.</codeb
1a80: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54 68 65 20 6f 72  lock>..<p>The or
1a90: 64 65 72 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  der of the colum
1aa0: 6e 73 20 69 6e 20 74 68 65 20 64 61 74 61 5f 25  ns in the data_%
1ab0: 20 74 61 62 6c 65 20 64 6f 65 73 20 6e 6f 74 20   table does not 
1ac0: 6d 61 74 74 65 72 2e 0a 0a 3c 70 3e 49 66 20 74  matter...<p>If t
1ad0: 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61  he target databa
1ae0: 73 65 20 74 61 62 6c 65 20 69 73 20 61 20 76 69  se table is a vi
1af0: 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 72 20 61  rtual table or a
1b00: 20 74 61 62 6c 65 20 74 68 61 74 20 68 61 73 20   table that has 
1b10: 6e 6f 0a 50 52 49 4d 41 52 59 20 4b 45 59 20 64  no.PRIMARY KEY d
1b20: 65 63 6c 61 72 61 74 69 6f 6e 2c 20 74 68 65 20  eclaration, the 
1b30: 64 61 74 61 5f 25 20 74 61 62 6c 65 20 6d 75 73  data_% table mus
1b40: 74 20 61 6c 73 6f 20 63 6f 6e 74 61 69 6e 20 61  t also contain a
1b50: 20 63 6f 6c 75 6d 6e 20 0a 6e 61 6d 65 64 20 22   column .named "
1b60: 72 62 75 5f 72 6f 77 69 64 22 2e 20 54 68 65 20  rbu_rowid". The 
1b70: 72 62 75 5f 72 6f 77 69 64 20 63 6f 6c 75 6d 6e  rbu_rowid column
1b80: 20 69 73 20 6d 61 70 70 65 64 20 74 6f 20 74 68   is mapped to th
1b90: 65 20 74 61 62 6c 65 73 20 5b 52 4f 57 49 44 5d  e tables [ROWID]
1ba0: 2e 0a 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ..For example, i
1bb0: 66 20 74 68 65 20 74 61 72 67 65 74 20 64 61 74  f the target dat
1bc0: 61 62 61 73 65 20 63 6f 6e 74 61 69 6e 73 20 65  abase contains e
1bd0: 69 74 68 65 72 20 6f 66 20 74 68 65 20 66 6f 6c  ither of the fol
1be0: 6c 6f 77 69 6e 67 3a 0a 0a 3c 63 6f 64 65 62 6c  lowing:..<codebl
1bf0: 6f 63 6b 3e 0a 43 52 45 41 54 45 20 56 49 52 54  ock>.CREATE VIRT
1c00: 55 41 4c 20 54 41 42 4c 45 20 78 31 20 55 53 49  UAL TABLE x1 USI
1c10: 4e 47 20 66 74 73 33 28 61 2c 20 62 29 3b 0a 43  NG fts3(a, b);.C
1c20: 52 45 41 54 45 20 54 41 42 4c 45 20 78 31 28 61  REATE TABLE x1(a
1c30: 2c 20 62 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63  , b);.</codebloc
1c40: 6b 3e 0a 0a 3c 70 3e 74 68 65 6e 20 74 68 65 20  k>..<p>then the 
1c50: 52 42 55 20 64 61 74 61 62 61 73 65 20 73 68 6f  RBU database sho
1c60: 75 6c 64 20 63 6f 6e 74 61 69 6e 3a 0a 0a 3c 63  uld contain:..<c
1c70: 6f 64 65 62 6c 6f 63 6b 3e 0a 43 52 45 41 54 45  odeblock>.CREATE
1c80: 20 54 41 42 4c 45 20 64 61 74 61 5f 78 31 28 61   TABLE data_x1(a
1c90: 2c 20 62 2c 20 72 62 75 5f 72 6f 77 69 64 2c 20  , b, rbu_rowid, 
1ca0: 72 62 75 5f 63 6f 6e 74 72 6f 6c 29 3b 0a 3c 2f  rbu_control);.</
1cb0: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 56  codeblock>..<p>V
1cc0: 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 66 6f  irtual tables fo
1cd0: 72 20 77 68 69 63 68 20 74 68 65 20 22 72 6f 77  r which the "row
1ce0: 69 64 22 20 63 6f 6c 75 6d 6e 20 64 6f 65 73 20  id" column does 
1cf0: 0a 6e 6f 74 20 66 75 6e 63 74 69 6f 6e 20 6c 69  .not function li
1d00: 6b 65 20 61 20 70 72 69 6d 61 72 79 20 6b 65 79  ke a primary key
1d10: 20 76 61 6c 75 65 20 63 61 6e 6e 6f 74 20 62 65   value cannot be
1d20: 20 75 70 64 61 74 65 64 20 75 73 69 6e 67 20 52   updated using R
1d30: 42 55 2e 0a 0a 3c 70 3e 0a 41 6c 6c 20 6e 6f 6e  BU...<p>.All non
1d40: 2d 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 20  -hidden columns 
1d50: 28 69 2e 65 2e 20 61 6c 6c 20 63 6f 6c 75 6d 6e  (i.e. all column
1d60: 73 20 6d 61 74 63 68 65 64 20 62 79 20 22 53 45  s matched by "SE
1d70: 4c 45 43 54 20 2a 22 29 20 6f 66 20 74 68 65 0a  LECT *") of the.
1d80: 74 61 72 67 65 74 20 74 61 62 6c 65 20 6d 75 73  target table mus
1d90: 74 20 62 65 20 70 72 65 73 65 6e 74 20 69 6e 20  t be present in 
1da0: 74 68 65 20 69 6e 70 75 74 20 74 61 62 6c 65 2e  the input table.
1db0: 20 46 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62   For virtual tab
1dc0: 6c 65 73 2c 0a 68 69 64 64 65 6e 20 63 6f 6c 75  les,.hidden colu
1dd0: 6d 6e 73 20 61 72 65 20 6f 70 74 69 6f 6e 61 6c  mns are optional
1de0: 20 2d 20 74 68 65 79 20 61 72 65 20 75 70 64 61   - they are upda
1df0: 74 65 64 20 62 79 20 52 42 55 20 69 66 20 70 72  ted by RBU if pr
1e00: 65 73 65 6e 74 20 69 6e 0a 74 68 65 20 69 6e 70  esent in.the inp
1e10: 75 74 20 74 61 62 6c 65 2c 20 6f 72 20 6e 6f 74  ut table, or not
1e20: 20 6f 74 68 65 72 77 69 73 65 2e 20 46 6f 72 20   otherwise. For 
1e30: 65 78 61 6d 70 6c 65 2c 20 74 6f 20 77 72 69 74  example, to writ
1e40: 65 20 74 6f 20 61 6e 20 66 74 73 34 0a 74 61 62  e to an fts4.tab
1e50: 6c 65 20 77 69 74 68 20 61 20 68 69 64 64 65 6e  le with a hidden
1e60: 20 6c 61 6e 67 75 61 67 65 69 64 20 63 6f 6c 75   languageid colu
1e70: 6d 6e 20 73 75 63 68 20 61 73 3a 0a 0a 3c 63 6f  mn such as:..<co
1e80: 64 65 62 6c 6f 63 6b 3e 0a 43 52 45 41 54 45 20  deblock>.CREATE 
1e90: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66 74  VIRTUAL TABLE ft
1ea0: 31 20 55 53 49 4e 47 20 66 74 73 34 28 61 2c 20  1 USING fts4(a, 
1eb0: 62 2c 20 6c 61 6e 67 75 61 67 65 69 64 3d 27 6c  b, languageid='l
1ec0: 61 6e 67 69 64 27 29 3b 0a 3c 2f 63 6f 64 65 62  angid');.</codeb
1ed0: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 45 69 74 68 65 72  lock>..<p>Either
1ee0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
1ef0: 67 20 69 6e 70 75 74 20 74 61 62 6c 65 20 73 63  g input table sc
1f00: 68 65 6d 61 73 20 6d 61 79 20 62 65 20 75 73 65  hemas may be use
1f10: 64 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  d:..<codeblock>.
1f20: 43 52 45 41 54 45 20 54 41 42 4c 45 20 64 61 74  CREATE TABLE dat
1f30: 61 5f 66 74 31 28 61 2c 20 62 2c 20 6c 61 6e 67  a_ft1(a, b, lang
1f40: 69 64 2c 20 72 62 75 5f 72 6f 77 69 64 2c 20 72  id, rbu_rowid, r
1f50: 62 75 5f 63 6f 6e 74 72 6f 6c 29 3b 0a 43 52 45  bu_control);.CRE
1f60: 41 54 45 20 54 41 42 4c 45 20 64 61 74 61 5f 66  ATE TABLE data_f
1f70: 74 31 28 61 2c 20 62 2c 20 72 62 75 5f 72 6f 77  t1(a, b, rbu_row
1f80: 69 64 2c 20 72 62 75 5f 63 6f 6e 74 72 6f 6c 29  id, rbu_control)
1f90: 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a  ;.</codeblock>..
1fa0: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
1fb0: 20 64 61 74 61 62 61 73 65 5f 63 6f 6e 74 65 6e   database_conten
1fc0: 74 73 20 7b 52 42 55 20 44 61 74 61 62 61 73 65  ts {RBU Database
1fd0: 20 43 6f 6e 74 65 6e 74 73 7d 3c 2f 74 63 6c 3e   Contents}</tcl>
1fe0: 0a 3c 68 33 3e 52 42 55 20 44 61 74 61 62 61 73  .<h3>RBU Databas
1ff0: 65 20 43 6f 6e 74 65 6e 74 73 3c 2f 68 33 3e 0a  e Contents</h3>.
2000: 0a 3c 70 3e 46 6f 72 20 65 61 63 68 20 72 6f 77  .<p>For each row
2010: 20 74 6f 20 49 4e 53 45 52 54 20 69 6e 74 6f 20   to INSERT into 
2020: 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62  the target datab
2030: 61 73 65 20 61 73 20 70 61 72 74 20 6f 66 20 74  ase as part of t
2040: 68 65 20 52 42 55 20 0a 75 70 64 61 74 65 2c 20  he RBU .update, 
2050: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2060: 67 20 64 61 74 61 5f 25 20 74 61 62 6c 65 20 73  g data_% table s
2070: 68 6f 75 6c 64 20 63 6f 6e 74 61 69 6e 20 61 20  hould contain a 
2080: 73 69 6e 67 6c 65 20 72 65 63 6f 72 64 0a 77 69  single record.wi
2090: 74 68 20 74 68 65 20 22 72 62 75 5f 63 6f 6e 74  th the "rbu_cont
20a0: 72 6f 6c 22 20 63 6f 6c 75 6d 6e 20 73 65 74 20  rol" column set 
20b0: 74 6f 20 63 6f 6e 74 61 69 6e 20 69 6e 74 65 67  to contain integ
20c0: 65 72 20 76 61 6c 75 65 20 30 2e 20 54 68 65 0a  er value 0. The.
20d0: 6f 74 68 65 72 20 63 6f 6c 75 6d 6e 73 20 73 68  other columns sh
20e0: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
20f0: 68 65 20 76 61 6c 75 65 73 20 74 68 61 74 20 6d  he values that m
2100: 61 6b 65 20 75 70 20 74 68 65 20 6e 65 77 20 72  ake up the new r
2110: 65 63 6f 72 64 20 0a 74 6f 20 69 6e 73 65 72 74  ecord .to insert
2120: 2e 20 0a 0a 3c 70 3e 54 68 65 20 22 72 62 75 5f  . ..<p>The "rbu_
2130: 63 6f 6e 74 72 6f 6c 22 20 63 6f 6c 75 6d 6e 20  control" column 
2140: 6d 61 79 20 61 6c 73 6f 20 62 65 20 73 65 74 20  may also be set 
2150: 74 6f 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  to integer value
2160: 20 32 20 66 6f 72 20 0a 61 6e 20 49 4e 53 45 52   2 for .an INSER
2170: 54 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c  T. In this case,
2180: 20 74 68 65 20 6e 65 77 20 72 6f 77 20 73 69 6c   the new row sil
2190: 65 6e 74 6c 79 20 72 65 70 6c 61 63 65 73 20 61  ently replaces a
21a0: 6e 79 20 65 78 69 73 74 69 6e 67 20 72 6f 77 20  ny existing row 
21b0: 74 68 61 74 0a 68 61 73 20 74 68 65 20 73 61 6d  that.has the sam
21c0: 65 20 70 72 69 6d 61 72 79 20 6b 65 79 20 76 61  e primary key va
21d0: 6c 75 65 73 2e 20 54 68 69 73 20 69 73 20 65 71  lues. This is eq
21e0: 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 44 45  uivalent to a DE
21f0: 4c 45 54 45 20 66 6f 6c 6c 6f 77 65 64 20 62 79  LETE followed by
2200: 20 61 6e 0a 49 4e 53 45 52 54 20 77 69 74 68 20   an.INSERT with 
2210: 74 68 65 20 73 61 6d 65 20 70 72 69 6d 61 72 79  the same primary
2220: 20 6b 65 79 20 76 61 6c 75 65 73 2e 20 49 74 20   key values. It 
2230: 69 73 20 6e 6f 74 20 74 68 65 20 73 61 6d 65 20  is not the same 
2240: 61 73 20 61 6e 20 53 51 4c 20 52 45 50 4c 41 43  as an SQL REPLAC
2250: 45 0a 63 6f 6d 6d 61 6e 64 2c 20 61 73 20 69 6e  E.command, as in
2260: 20 74 68 61 74 20 63 61 73 65 20 74 68 65 20 6e   that case the n
2270: 65 77 20 72 6f 77 20 6d 61 79 20 72 65 70 6c 61  ew row may repla
2280: 63 65 20 61 6e 79 20 63 6f 6e 66 6c 69 63 74 69  ce any conflicti
2290: 6e 67 20 72 6f 77 73 20 28 69 2e 65 2e 0a 74 68  ng rows (i.e..th
22a0: 6f 73 65 20 74 68 61 74 20 63 6f 6e 66 6c 69 63  ose that conflic
22b0: 74 20 64 75 65 20 74 6f 20 55 4e 49 51 55 45 20  t due to UNIQUE 
22c0: 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 72 20 69  constraints or i
22d0: 6e 64 65 78 65 73 29 2c 20 6e 6f 74 20 6a 75 73  ndexes), not jus
22e0: 74 20 74 68 6f 73 65 20 77 69 74 68 0a 63 6f 6e  t those with.con
22f0: 66 6c 69 63 74 69 6e 67 20 70 72 69 6d 61 72 79  flicting primary
2300: 20 6b 65 79 73 2e 0a 0a 3c 70 3e 49 66 20 74 68   keys...<p>If th
2310: 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73  e target databas
2320: 65 20 74 61 62 6c 65 20 68 61 73 20 61 6e 20 49  e table has an I
2330: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
2340: 45 59 2c 20 69 74 20 69 73 20 6e 6f 74 20 0a 70  EY, it is not .p
2350: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 73 65 72  ossible to inser
2360: 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  t a NULL value i
2370: 6e 74 6f 20 74 68 65 20 49 50 4b 20 63 6f 6c 75  nto the IPK colu
2380: 6d 6e 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  mn. Attempting t
2390: 6f 20 0a 64 6f 20 73 6f 20 72 65 73 75 6c 74 73  o .do so results
23a0: 20 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49   in an SQLITE_MI
23b0: 53 4d 41 54 43 48 20 65 72 72 6f 72 2e 0a 0a 3c  SMATCH error...<
23c0: 70 3e 46 6f 72 20 65 61 63 68 20 72 6f 77 20 74  p>For each row t
23d0: 6f 20 44 45 4c 45 54 45 20 66 72 6f 6d 20 74 68  o DELETE from th
23e0: 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73  e target databas
23f0: 65 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  e as part of the
2400: 20 52 42 55 20 0a 75 70 64 61 74 65 2c 20 74 68   RBU .update, th
2410: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2420: 64 61 74 61 5f 25 20 74 61 62 6c 65 20 73 68 6f  data_% table sho
2430: 75 6c 64 20 63 6f 6e 74 61 69 6e 20 61 20 73 69  uld contain a si
2440: 6e 67 6c 65 20 72 65 63 6f 72 64 0a 77 69 74 68  ngle record.with
2450: 20 74 68 65 20 22 72 62 75 5f 63 6f 6e 74 72 6f   the "rbu_contro
2460: 6c 22 20 63 6f 6c 75 6d 6e 20 73 65 74 20 74 6f  l" column set to
2470: 20 63 6f 6e 74 61 69 6e 20 69 6e 74 65 67 65 72   contain integer
2480: 20 76 61 6c 75 65 20 31 2e 20 54 68 65 0a 72 65   value 1. The.re
2490: 61 6c 20 70 72 69 6d 61 72 79 20 6b 65 79 20 76  al primary key v
24a0: 61 6c 75 65 73 20 6f 66 20 74 68 65 20 72 6f 77  alues of the row
24b0: 20 74 6f 20 64 65 6c 65 74 65 20 73 68 6f 75 6c   to delete shoul
24c0: 64 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 74  d be stored in t
24d0: 68 65 0a 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he.corresponding
24e0: 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 74 68 65 20   columns of the 
24f0: 64 61 74 61 5f 25 20 74 61 62 6c 65 2e 20 54 68  data_% table. Th
2500: 65 20 76 61 6c 75 65 73 20 73 74 6f 72 65 64 20  e values stored 
2510: 69 6e 20 74 68 65 0a 6f 74 68 65 72 20 63 6f 6c  in the.other col
2520: 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20 75 73 65  umns are not use
2530: 64 2e 0a 0a 3c 70 3e 46 6f 72 20 65 61 63 68 20  d...<p>For each 
2540: 72 6f 77 20 74 6f 20 55 50 44 41 54 45 20 66 72  row to UPDATE fr
2550: 6f 6d 20 74 68 65 20 74 61 72 67 65 74 20 64 61  om the target da
2560: 74 61 62 61 73 65 20 61 73 20 70 61 72 74 20 6f  tabase as part o
2570: 66 20 74 68 65 20 52 42 55 20 0a 75 70 64 61 74  f the RBU .updat
2580: 65 2c 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  e, the correspon
2590: 64 69 6e 67 20 64 61 74 61 5f 25 20 74 61 62 6c  ding data_% tabl
25a0: 65 20 73 68 6f 75 6c 64 20 63 6f 6e 74 61 69 6e  e should contain
25b0: 20 61 20 73 69 6e 67 6c 65 20 72 65 63 6f 72 64   a single record
25c0: 0a 77 69 74 68 20 74 68 65 20 22 72 62 75 5f 63  .with the "rbu_c
25d0: 6f 6e 74 72 6f 6c 22 20 63 6f 6c 75 6d 6e 20 73  ontrol" column s
25e0: 65 74 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  et to contain a 
25f0: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 74 65  value of type te
2600: 78 74 2e 0a 54 68 65 20 72 65 61 6c 20 70 72 69  xt..The real pri
2610: 6d 61 72 79 20 6b 65 79 20 76 61 6c 75 65 73 20  mary key values 
2620: 69 64 65 6e 74 69 66 79 69 6e 67 20 74 68 65 20  identifying the 
2630: 72 6f 77 20 74 6f 20 75 70 64 61 74 65 20 73 68  row to update sh
2640: 6f 75 6c 64 20 62 65 20 0a 73 74 6f 72 65 64 20  ould be .stored 
2650: 69 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  in the correspon
2660: 64 69 6e 67 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ding columns of 
2670: 74 68 65 20 64 61 74 61 5f 25 20 74 61 62 6c 65  the data_% table
2680: 20 72 6f 77 2c 20 61 73 20 73 68 6f 75 6c 64 0a   row, as should.
2690: 74 68 65 20 6e 65 77 20 76 61 6c 75 65 73 20 6f  the new values o
26a0: 66 20 61 6c 6c 20 63 6f 6c 75 6d 6e 73 20 62 65  f all columns be
26b0: 69 6e 67 20 75 70 64 61 74 65 2e 20 54 68 65 20  ing update. The 
26c0: 74 65 78 74 20 76 61 6c 75 65 20 69 6e 20 74 68  text value in th
26d0: 65 20 0a 22 72 62 75 5f 63 6f 6e 74 72 6f 6c 22  e ."rbu_control"
26e0: 20 63 6f 6c 75 6d 6e 20 6d 75 73 74 20 63 6f 6e   column must con
26f0: 74 61 69 6e 20 74 68 65 20 73 61 6d 65 20 6e 75  tain the same nu
2700: 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2710: 72 73 20 61 73 0a 74 68 65 72 65 20 61 72 65 20  rs as.there are 
2720: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 74  columns in the t
2730: 61 72 67 65 74 20 64 61 74 61 62 61 73 65 20 74  arget database t
2740: 61 62 6c 65 2c 20 61 6e 64 20 6d 75 73 74 20 63  able, and must c
2750: 6f 6e 73 69 73 74 20 65 6e 74 69 72 65 6c 79 0a  onsist entirely.
2760: 6f 66 20 27 78 27 20 61 6e 64 20 27 2e 27 20 63  of 'x' and '.' c
2770: 68 61 72 61 63 74 65 72 73 20 28 6f 72 20 69 6e  haracters (or in
2780: 20 73 6f 6d 65 20 73 70 65 63 69 61 6c 20 63 61   some special ca
2790: 73 65 73 20 27 64 27 20 2d 20 73 65 65 20 62 65  ses 'd' - see be
27a0: 6c 6f 77 29 2e 20 46 6f 72 20 0a 65 61 63 68 20  low). For .each 
27b0: 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 62  column that is b
27c0: 65 69 6e 67 20 75 70 64 61 74 65 64 2c 20 74 68  eing updated, th
27d0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
27e0: 63 68 61 72 61 63 74 65 72 20 69 73 20 73 65 74  character is set
27f0: 20 74 6f 0a 27 78 27 2e 20 46 6f 72 20 74 68 6f   to.'x'. For tho
2800: 73 65 20 74 68 61 74 20 72 65 6d 61 69 6e 20 61  se that remain a
2810: 73 20 74 68 65 79 20 61 72 65 2c 20 74 68 65 20  s they are, the 
2820: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 63 68  corresponding ch
2830: 61 72 61 63 74 65 72 20 6f 66 20 74 68 65 0a 72  aracter of the.r
2840: 62 75 5f 63 6f 6e 74 72 6f 6c 20 76 61 6c 75 65  bu_control value
2850: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
2860: 6f 20 27 2e 27 2e 20 46 6f 72 20 65 78 61 6d 70  o '.'. For examp
2870: 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 74 61  le, given the ta
2880: 62 6c 65 73 20 0a 61 62 6f 76 65 2c 20 74 68 65  bles .above, the
2890: 20 75 70 64 61 74 65 20 73 74 61 74 65 6d 65 6e   update statemen
28a0: 74 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  t:..<codeblock>.
28b0: 55 50 44 41 54 45 20 74 31 20 53 45 54 20 63 20  UPDATE t1 SET c 
28c0: 3d 20 27 75 73 61 27 20 57 48 45 52 45 20 61 20  = 'usa' WHERE a 
28d0: 3d 20 34 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  = 4;.</codeblock
28e0: 3e 0a 0a 3c 70 3e 69 73 20 72 65 70 72 65 73 65  >..<p>is represe
28f0: 6e 74 65 64 20 62 79 20 74 68 65 20 64 61 74 61  nted by the data
2900: 5f 74 31 20 72 6f 77 20 63 72 65 61 74 65 64 20  _t1 row created 
2910: 62 79 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e  by:..<codeblock>
2920: 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 64 61 74  .INSERT INTO dat
2930: 61 5f 74 31 28 61 2c 20 62 2c 20 63 2c 20 72 62  a_t1(a, b, c, rb
2940: 75 5f 63 6f 6e 74 72 6f 6c 29 20 56 41 4c 55 45  u_control) VALUE
2950: 53 28 34 2c 20 4e 55 4c 4c 2c 20 27 75 73 61 27  S(4, NULL, 'usa'
2960: 2c 20 27 2e 2e 78 27 29 3b 0a 3c 2f 63 6f 64 65  , '..x');.</code
2970: 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 49 66 20 52 42  block>..<p>If RB
2980: 55 20 69 73 20 75 73 65 64 20 74 6f 20 75 70 64  U is used to upd
2990: 61 74 65 20 61 20 6c 61 72 67 65 20 42 4c 4f 42  ate a large BLOB
29a0: 20 76 61 6c 75 65 20 77 69 74 68 69 6e 20 61 20   value within a 
29b0: 74 61 72 67 65 74 20 64 61 74 61 62 61 73 65 2c  target database,
29c0: 20 69 74 0a 6d 61 79 20 62 65 20 6d 6f 72 65 20   it.may be more 
29d0: 65 66 66 69 63 69 65 6e 74 20 74 6f 20 73 74 6f  efficient to sto
29e0: 72 65 20 61 20 70 61 74 63 68 20 6f 72 20 64 65  re a patch or de
29f0: 6c 74 61 20 74 68 61 74 20 63 61 6e 20 62 65 20  lta that can be 
2a00: 75 73 65 64 20 74 6f 20 6d 6f 64 69 66 79 0a 74  used to modify.t
2a10: 68 65 20 65 78 69 73 74 69 6e 67 20 42 4c 4f 42  he existing BLOB
2a20: 20 69 6e 73 74 65 61 64 20 6f 66 20 61 6e 20 65   instead of an e
2a30: 6e 74 69 72 65 6c 79 20 6e 65 77 20 76 61 6c 75  ntirely new valu
2a40: 65 20 77 69 74 68 69 6e 20 74 68 65 20 52 42 55  e within the RBU
2a50: 20 64 61 74 61 62 61 73 65 2e 20 0a 52 42 55 20   database. .RBU 
2a60: 61 6c 6c 6f 77 73 20 64 65 6c 74 61 73 20 74 6f  allows deltas to
2a70: 20 62 65 20 73 70 65 63 69 66 69 65 64 20 69 6e   be specified in
2a80: 20 74 77 6f 20 77 61 79 73 3a 0a 0a 3c 75 6c 3e   two ways:..<ul>
2a90: 0a 20 20 3c 6c 69 3e 20 49 6e 20 74 68 65 20 22  .  <li> In the "
2aa0: 66 6f 73 73 69 6c 20 64 65 6c 74 61 22 20 66 6f  fossil delta" fo
2ab0: 72 6d 61 74 20 2d 20 74 68 65 20 66 6f 72 6d 61  rmat - the forma
2ac0: 74 20 75 73 65 64 20 66 6f 72 20 62 6c 6f 62 20  t used for blob 
2ad0: 64 65 6c 74 61 73 20 62 79 20 74 68 65 20 0a 20  deltas by the . 
2ae0: 20 3c 61 20 68 72 65 66 3d 68 74 74 70 3a 2f 2f   <a href=http://
2af0: 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 3e 46  fossil-scm.org>F
2b00: 6f 73 73 69 6c 20 73 6f 75 72 63 65 2d 63 6f 64  ossil source-cod
2b10: 65 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73  e management sys
2b20: 74 65 6d 3c 2f 61 3e 2c 20 6f 72 0a 0a 20 20 3c  tem</a>, or..  <
2b30: 6c 69 3e 20 49 6e 20 61 20 63 75 73 74 6f 6d 20  li> In a custom 
2b40: 66 6f 72 6d 61 74 20 64 65 66 69 6e 65 64 20 62  format defined b
2b50: 79 20 74 68 65 20 52 42 55 20 61 70 70 6c 69 63  y the RBU applic
2b60: 61 74 69 6f 6e 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70  ation..</ul>..<p
2b70: 3e 20 54 68 65 20 66 6f 73 73 69 6c 20 64 65 6c  > The fossil del
2b80: 74 61 20 66 6f 72 6d 61 74 20 6d 61 79 20 6f 6e  ta format may on
2b90: 6c 79 20 62 65 20 75 73 65 64 20 74 6f 20 75 70  ly be used to up
2ba0: 64 61 74 65 20 42 4c 4f 42 20 76 61 6c 75 65 73  date BLOB values
2bb0: 2e 20 49 6e 73 74 65 61 64 0a 6f 66 20 73 74 6f  . Instead.of sto
2bc0: 72 69 6e 67 20 74 68 65 20 6e 65 77 20 42 4c 4f  ring the new BLO
2bd0: 42 20 77 69 74 68 69 6e 20 74 68 65 20 64 61 74  B within the dat
2be0: 61 5f 25 20 74 61 62 6c 65 2c 20 74 68 65 20 66  a_% table, the f
2bf0: 6f 73 73 69 6c 20 64 65 6c 74 61 20 69 73 20 73  ossil delta is s
2c00: 74 6f 72 65 64 0a 69 6e 73 74 65 61 64 2e 20 41  tored.instead. A
2c10: 6e 64 20 69 6e 73 74 65 61 64 20 6f 66 20 73 70  nd instead of sp
2c20: 65 63 69 66 79 69 6e 67 20 61 6e 20 27 78 27 20  ecifying an 'x' 
2c30: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  as part of the r
2c40: 62 75 5f 63 6f 6e 74 72 6f 6c 20 73 74 72 69 6e  bu_control strin
2c50: 67 0a 66 6f 72 20 74 68 65 20 63 6f 6c 75 6d 6e  g.for the column
2c60: 20 74 6f 20 62 65 20 75 70 64 61 74 65 64 2c 20   to be updated, 
2c70: 61 6e 20 27 66 27 20 63 68 61 72 61 63 74 65 72  an 'f' character
2c80: 20 69 73 20 73 74 6f 72 65 64 2e 20 57 68 65 6e   is stored. When
2c90: 20 70 72 6f 63 65 73 73 69 6e 67 0a 61 6e 20 27   processing.an '
2ca0: 66 27 20 75 70 64 61 74 65 2c 20 52 42 55 20 6c  f' update, RBU l
2cb0: 6f 61 64 73 20 74 68 65 20 6f 72 69 67 69 6e 61  oads the origina
2cc0: 6c 20 42 4c 4f 42 20 64 61 74 61 20 66 72 6f 6d  l BLOB data from
2cd0: 20 64 69 73 6b 2c 20 61 70 70 6c 69 65 73 20 74   disk, applies t
2ce0: 68 65 20 66 6f 73 73 69 6c 0a 64 65 6c 74 61 20  he fossil.delta 
2cf0: 74 6f 20 69 74 20 61 6e 64 20 73 74 6f 72 65 73  to it and stores
2d00: 20 74 68 65 20 72 65 73 75 6c 74 73 20 62 61 63   the results bac
2d10: 6b 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  k into the datab
2d20: 61 73 65 20 66 69 6c 65 2e 20 54 68 65 20 52 42  ase file. The RB
2d30: 55 0a 64 61 74 61 62 61 73 65 73 20 67 65 6e 65  U.databases gene
2d40: 72 61 74 65 64 20 62 79 20 5b 73 71 6c 64 69 66  rated by [sqldif
2d50: 66 20 2d 2d 72 62 75 5d 20 6d 61 6b 65 20 75 73  f --rbu] make us
2d60: 65 20 6f 66 20 66 6f 73 73 69 6c 20 64 65 6c 74  e of fossil delt
2d70: 61 73 20 77 68 65 72 65 76 65 72 0a 64 6f 69 6e  as wherever.doin
2d80: 67 20 73 6f 20 77 6f 75 6c 64 20 73 61 76 65 20  g so would save 
2d90: 73 70 61 63 65 20 69 6e 20 74 68 65 20 52 42 55  space in the RBU
2da0: 20 64 61 74 61 62 61 73 65 2e 0a 0a 3c 70 3e 20   database...<p> 
2db0: 54 6f 20 75 73 65 20 61 20 63 75 73 74 6f 6d 20  To use a custom 
2dc0: 64 65 6c 74 61 20 66 6f 72 6d 61 74 2c 20 74 68  delta format, th
2dd0: 65 20 52 42 55 20 61 70 70 6c 69 63 61 74 69 6f  e RBU applicatio
2de0: 6e 20 6d 75 73 74 20 72 65 67 69 73 74 65 72 20  n must register 
2df0: 61 0a 75 73 65 72 2d 64 65 66 69 6e 65 64 20 53  a.user-defined S
2e00: 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65  QL function name
2e10: 64 20 22 72 62 75 5f 64 65 6c 74 61 22 20 62 65  d "rbu_delta" be
2e20: 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 20 74  fore beginning t
2e30: 6f 20 70 72 6f 63 65 73 73 20 74 68 65 0a 75 70  o process the.up
2e40: 64 61 74 65 2e 20 72 62 75 5f 64 65 6c 74 61 28  date. rbu_delta(
2e50: 29 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  ) will be invoke
2e60: 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
2e70: 65 6e 74 73 20 2d 20 74 68 65 20 6f 72 69 67 69  ents - the origi
2e80: 6e 61 6c 20 76 61 6c 75 65 0a 73 74 6f 72 65 64  nal value.stored
2e90: 20 69 6e 20 74 68 65 20 74 61 72 67 65 74 20 74   in the target t
2ea0: 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 61 6e 64 20  able column and 
2eb0: 74 68 65 20 64 65 6c 74 61 20 76 61 6c 75 65 20  the delta value 
2ec0: 70 72 6f 76 69 64 65 64 20 61 73 20 70 61 72 74  provided as part
2ed0: 20 6f 66 0a 74 68 65 20 52 42 55 20 75 70 64 61   of.the RBU upda
2ee0: 74 65 2e 20 49 74 20 73 68 6f 75 6c 64 20 72 65  te. It should re
2ef0: 74 75 72 6e 20 74 68 65 20 72 65 73 75 6c 74 20  turn the result 
2f00: 6f 66 20 61 70 70 6c 79 69 6e 67 20 74 68 65 20  of applying the 
2f10: 64 65 6c 74 61 20 74 6f 20 74 68 65 0a 6f 72 69  delta to the.ori
2f20: 67 69 6e 61 6c 20 76 61 6c 75 65 2e 20 54 6f 20  ginal value. To 
2f30: 75 73 65 20 74 68 65 20 63 75 73 74 6f 6d 20 64  use the custom d
2f40: 65 6c 74 61 20 66 75 6e 63 74 69 6f 6e 2c 20 74  elta function, t
2f50: 68 65 20 63 68 61 72 61 63 74 65 72 20 6f 66 20  he character of 
2f60: 74 68 65 0a 72 62 75 5f 63 6f 6e 74 72 6f 6c 20  the.rbu_control 
2f70: 76 61 6c 75 65 20 63 6f 72 72 65 73 70 6f 6e 64  value correspond
2f80: 69 6e 67 20 74 6f 20 74 68 65 20 74 61 72 67 65  ing to the targe
2f90: 74 20 63 6f 6c 75 6d 6e 20 74 6f 20 75 70 64 61  t column to upda
2fa0: 74 65 20 6d 75 73 74 20 62 65 0a 73 65 74 20 74  te must be.set t
2fb0: 6f 20 27 64 27 20 69 6e 73 74 65 61 64 20 6f 66  o 'd' instead of
2fc0: 20 27 78 27 2e 20 54 68 65 6e 2c 20 69 6e 73 74   'x'. Then, inst
2fd0: 65 61 64 20 6f 66 20 75 70 64 61 74 69 6e 67 20  ead of updating 
2fe0: 74 68 65 20 74 61 72 67 65 74 20 74 61 62 6c 65  the target table
2ff0: 20 77 69 74 68 20 74 68 65 0a 76 61 6c 75 65 20   with the.value 
3000: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 6f  stored in the co
3010: 72 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61  rresponding data
3020: 5f 25 20 63 6f 6c 75 6d 6e 2c 20 52 42 55 20 69  _% column, RBU i
3030: 6e 76 6f 6b 65 73 20 74 68 65 20 75 73 65 72 2d  nvokes the user-
3040: 64 65 66 69 6e 65 64 0a 53 51 4c 20 66 75 6e 63  defined.SQL func
3050: 74 69 6f 6e 20 22 72 62 75 5f 64 65 6c 74 61 28  tion "rbu_delta(
3060: 29 22 20 61 6e 64 20 74 68 65 20 73 74 6f 72 65  )" and the store
3070: 20 69 6e 20 74 68 65 20 74 61 72 67 65 74 20 74   in the target t
3080: 61 62 6c 65 20 63 6f 6c 75 6d 6e 2e 0a 0a 3c 70  able column...<p
3090: 3e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68  >For example, th
30a0: 69 73 20 72 6f 77 3a 0a 0a 3c 63 6f 64 65 62 6c  is row:..<codebl
30b0: 6f 63 6b 3e 0a 49 4e 53 45 52 54 20 49 4e 54 4f  ock>.INSERT INTO
30c0: 20 64 61 74 61 5f 74 31 28 61 2c 20 62 2c 20 63   data_t1(a, b, c
30d0: 2c 20 72 62 75 5f 63 6f 6e 74 72 6f 6c 29 20 56  , rbu_control) V
30e0: 41 4c 55 45 53 28 34 2c 20 4e 55 4c 4c 2c 20 27  ALUES(4, NULL, '
30f0: 75 73 61 27 2c 20 27 2e 2e 64 27 29 3b 0a 3c 2f  usa', '..d');.</
3100: 63 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 63  codeblock>..<p>c
3110: 61 75 73 65 73 20 52 42 55 20 74 6f 20 75 70 64  auses RBU to upd
3120: 61 74 65 20 74 68 65 20 74 61 72 67 65 74 20 64  ate the target d
3130: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 69 6e  atabase table in
3140: 20 61 20 77 61 79 20 73 69 6d 69 6c 61 72 20 74   a way similar t
3150: 6f 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  o:..<codeblock>.
3160: 55 50 44 41 54 45 20 74 31 20 53 45 54 20 63 20  UPDATE t1 SET c 
3170: 3d 20 72 62 75 5f 64 65 6c 74 61 28 63 2c 20 27  = rbu_delta(c, '
3180: 75 73 61 27 29 20 57 48 45 52 45 20 61 20 3d 20  usa') WHERE a = 
3190: 34 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a  4;.</codeblock>.
31a0: 0a 3c 70 3e 49 66 20 74 68 65 20 74 61 72 67 65  .<p>If the targe
31b0: 74 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  t database table
31c0: 20 69 73 20 61 20 76 69 72 74 75 61 6c 20 74 61   is a virtual ta
31d0: 62 6c 65 20 6f 72 20 61 20 74 61 62 6c 65 20 77  ble or a table w
31e0: 69 74 68 20 6e 6f 20 50 52 49 4d 41 52 59 0a 4b  ith no PRIMARY.K
31f0: 45 59 2c 20 74 68 65 20 72 62 75 5f 63 6f 6e 74  EY, the rbu_cont
3200: 72 6f 6c 20 76 61 6c 75 65 20 73 68 6f 75 6c 64  rol value should
3210: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 61 20 63   not include a c
3220: 68 61 72 61 63 74 65 72 20 63 6f 72 72 65 73 70  haracter corresp
3230: 6f 6e 64 69 6e 67 20 0a 74 6f 20 74 68 65 20 72  onding .to the r
3240: 62 75 5f 72 6f 77 69 64 20 76 61 6c 75 65 2e 20  bu_rowid value. 
3250: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 69  For example, thi
3260: 73 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  s:..<codeblock>.
3270: 49 4e 53 45 52 54 20 49 4e 54 4f 20 64 61 74 61  INSERT INTO data
3280: 5f 66 74 31 28 61 2c 20 62 2c 20 72 62 75 5f 72  _ft1(a, b, rbu_r
3290: 6f 77 69 64 2c 20 72 62 75 5f 63 6f 6e 74 72 6f  owid, rbu_contro
32a0: 6c 29 20 0a 20 20 56 41 4c 55 45 53 28 4e 55 4c  l) .  VALUES(NUL
32b0: 4c 2c 20 27 75 73 61 27 2c 20 31 32 2c 20 27 2e  L, 'usa', 12, '.
32c0: 78 27 29 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  x');.</codeblock
32d0: 3e 0a 0a 0a 3c 70 3e 63 61 75 73 65 73 20 61 20  >...<p>causes a 
32e0: 72 65 73 75 6c 74 20 73 69 6d 69 6c 61 72 20 74  result similar t
32f0: 6f 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a  o:..<codeblock>.
3300: 55 50 44 41 54 45 20 66 74 31 20 53 45 54 20 62  UPDATE ft1 SET b
3310: 20 3d 20 27 75 73 61 27 20 57 48 45 52 45 20 72   = 'usa' WHERE r
3320: 6f 77 69 64 20 3d 20 31 32 3b 0a 3c 2f 63 6f 64  owid = 12;.</cod
3330: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54 68 65 20  eblock>..<p>The 
3340: 64 61 74 61 5f 25 20 74 61 62 6c 65 73 20 74 68  data_% tables th
3350: 65 6d 73 65 6c 76 65 73 20 73 68 6f 75 6c 64 20  emselves should 
3360: 68 61 76 65 20 6e 6f 20 50 52 49 4d 41 52 59 20  have no PRIMARY 
3370: 4b 45 59 20 64 65 63 6c 61 72 61 74 69 6f 6e 73  KEY declarations
3380: 2e 0a 48 6f 77 65 76 65 72 2c 20 52 42 55 20 69  ..However, RBU i
3390: 73 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  s more efficient
33a0: 20 69 66 20 72 65 61 64 69 6e 67 20 74 68 65 20   if reading the 
33b0: 72 6f 77 73 20 69 6e 20 66 72 6f 6d 20 65 61 63  rows in from eac
33c0: 68 20 64 61 74 61 5f 25 0a 74 61 62 6c 65 20 69  h data_%.table i
33d0: 6e 20 22 72 6f 77 69 64 22 20 6f 72 64 65 72 20  n "rowid" order 
33e0: 69 73 20 72 6f 75 67 68 6c 79 20 74 68 65 20 73  is roughly the s
33f0: 61 6d 65 20 61 73 20 72 65 61 64 69 6e 67 20 74  ame as reading t
3400: 68 65 6d 20 73 6f 72 74 65 64 20 62 79 0a 74 68  hem sorted by.th
3410: 65 20 50 52 49 4d 41 52 59 20 4b 45 59 20 6f 66  e PRIMARY KEY of
3420: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
3430: 6e 67 20 74 61 72 67 65 74 20 64 61 74 61 62 61  ng target databa
3440: 73 65 20 74 61 62 6c 65 2e 20 49 6e 20 6f 74 68  se table. In oth
3450: 65 72 20 0a 77 6f 72 64 73 2c 20 72 6f 77 73 20  er .words, rows 
3460: 73 68 6f 75 6c 64 20 62 65 20 73 6f 72 74 65 64  should be sorted
3470: 20 75 73 69 6e 67 20 74 68 65 20 64 65 73 74 69   using the desti
3480: 6e 61 74 69 6f 6e 20 74 61 62 6c 65 20 50 52 49  nation table PRI
3490: 4d 41 52 59 20 4b 45 59 20 0a 66 69 65 6c 64 73  MARY KEY .fields
34a0: 20 62 65 66 6f 72 65 20 74 68 65 79 20 61 72 65   before they are
34b0: 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 74   inserted into t
34c0: 68 65 20 64 61 74 61 5f 25 20 74 61 62 6c 65 73  he data_% tables
34d0: 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  ...<tcl>hd_fragm
34e0: 65 6e 74 20 66 74 73 34 5f 74 61 62 6c 65 73 20  ent fts4_tables 
34f0: 7b 52 42 55 20 46 54 53 33 2f 34 20 54 61 62 6c  {RBU FTS3/4 Tabl
3500: 65 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 55 73  es}</tcl>.<h3>Us
3510: 69 6e 67 20 52 42 55 20 77 69 74 68 20 46 54 53  ing RBU with FTS
3520: 33 2f 34 20 54 61 62 6c 65 73 3c 2f 68 33 3e 0a  3/4 Tables</h3>.
3530: 0a 3c 70 3e 55 73 75 61 6c 6c 79 2c 20 61 6e 20  .<p>Usually, an 
3540: 5b 46 54 53 33 20 7c 20 46 54 53 33 20 6f 72 20  [FTS3 | FTS3 or 
3550: 46 54 53 34 5d 20 74 61 62 6c 65 20 69 73 20 61  FTS4] table is a
3560: 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 20 76  n example of a v
3570: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 0a 77 69  irtual table .wi
3580: 74 68 20 61 20 72 6f 77 69 64 20 74 68 61 74 20  th a rowid that 
3590: 77 6f 72 6b 73 20 6c 69 6b 65 20 61 20 50 52 49  works like a PRI
35a0: 4d 41 52 59 20 4b 45 59 2e 20 53 6f 2c 20 66 6f  MARY KEY. So, fo
35b0: 72 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  r the following 
35c0: 46 54 53 34 20 74 61 62 6c 65 73 3a 0a 0a 3c 63  FTS4 tables:..<c
35d0: 6f 64 65 62 6c 6f 63 6b 3e 0a 43 52 45 41 54 45  odeblock>.CREATE
35e0: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 66   VIRTUAL TABLE f
35f0: 74 31 20 55 53 49 4e 47 20 66 74 73 34 28 61 64  t1 USING fts4(ad
3600: 64 72 2c 20 74 65 78 74 29 3b 0a 43 52 45 41 54  dr, text);.CREAT
3610: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
3620: 66 74 32 20 55 53 49 4e 47 20 66 74 73 34 3b 20  ft2 USING fts4; 
3630: 20 20 20 20 20 20 20 20 20 20 20 20 2d 2d 20 69              -- i
3640: 6d 70 6c 69 63 69 74 20 22 63 6f 6e 74 65 6e 74  mplicit "content
3650: 22 20 63 6f 6c 75 6d 6e 0a 3c 2f 63 6f 64 65 62  " column.</codeb
3660: 6c 6f 63 6b 3e 0a 0a 3c 70 3e 54 68 65 20 64 61  lock>..<p>The da
3670: 74 61 5f 25 20 74 61 62 6c 65 73 20 6d 61 79 20  ta_% tables may 
3680: 62 65 20 63 72 65 61 74 65 64 20 61 73 20 66 6f  be created as fo
3690: 6c 6c 6f 77 73 3a 0a 0a 3c 63 6f 64 65 62 6c 6f  llows:..<codeblo
36a0: 63 6b 3e 0a 43 52 45 41 54 45 20 54 41 42 4c 45  ck>.CREATE TABLE
36b0: 20 64 61 74 61 5f 66 74 31 20 55 53 49 4e 47 20   data_ft1 USING 
36c0: 66 74 73 34 28 61 64 64 72 2c 20 74 65 78 74 2c  fts4(addr, text,
36d0: 20 72 62 75 5f 72 6f 77 69 64 2c 20 72 62 75 5f   rbu_rowid, rbu_
36e0: 63 6f 6e 74 72 6f 6c 29 3b 0a 43 52 45 41 54 45  control);.CREATE
36f0: 20 54 41 42 4c 45 20 64 61 74 61 5f 66 74 32 20   TABLE data_ft2 
3700: 55 53 49 4e 47 20 66 74 73 34 28 63 6f 6e 74 65  USING fts4(conte
3710: 6e 74 2c 20 72 62 75 5f 72 6f 77 69 64 2c 20 72  nt, rbu_rowid, r
3720: 62 75 5f 63 6f 6e 74 72 6f 6c 29 3b 0a 3c 2f 63  bu_control);.</c
3730: 6f 64 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 41 6e  odeblock>..<p>An
3740: 64 20 70 6f 70 75 6c 61 74 65 64 20 61 73 20 69  d populated as i
3750: 66 20 74 68 65 20 74 61 72 67 65 74 20 74 61 62  f the target tab
3760: 6c 65 20 77 65 72 65 20 61 6e 20 6f 72 64 69 6e  le were an ordin
3770: 61 72 79 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ary SQLite table
3780: 20 77 69 74 68 20 6e 6f 0a 65 78 70 6c 69 63 69   with no.explici
3790: 74 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f  t PRIMARY KEY co
37a0: 6c 75 6d 6e 73 2e 0a 0a 3c 70 3e 5b 63 6f 6e 74  lumns...<p>[cont
37b0: 65 6e 74 6c 65 73 73 20 66 74 73 34 20 74 61 62  entless fts4 tab
37c0: 6c 65 73 20 7c 20 43 6f 6e 74 65 6e 74 6c 65 73  les | Contentles
37d0: 73 20 46 54 53 34 20 74 61 62 6c 65 73 5d 20 61  s FTS4 tables] a
37e0: 72 65 20 68 61 6e 64 6c 65 64 20 73 69 6d 69 6c  re handled simil
37f0: 61 72 6c 79 2c 0a 65 78 63 65 70 74 20 74 68 61  arly,.except tha
3800: 74 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  t any attempt to
3810: 20 75 70 64 61 74 65 20 6f 72 20 64 65 6c 65 74   update or delet
3820: 65 20 72 6f 77 73 20 77 69 6c 6c 20 63 61 75 73  e rows will caus
3830: 65 20 61 6e 20 65 72 72 6f 72 20 77 68 65 6e 0a  e an error when.
3840: 61 70 70 6c 79 69 6e 67 20 74 68 65 20 75 70 64  applying the upd
3850: 61 74 65 2e 0a 0a 3c 70 3e 5b 65 78 74 65 72 6e  ate...<p>[extern
3860: 61 6c 20 63 6f 6e 74 65 6e 74 20 66 74 73 34 20  al content fts4 
3870: 74 61 62 6c 65 73 20 7c 20 45 78 74 65 72 6e 61  tables | Externa
3880: 6c 20 63 6f 6e 74 65 6e 74 20 46 54 53 34 20 74  l content FTS4 t
3890: 61 62 6c 65 73 5d 20 6d 61 79 20 61 6c 73 6f 20  ables] may also 
38a0: 62 65 20 0a 75 70 64 61 74 65 64 20 75 73 69 6e  be .updated usin
38b0: 67 20 52 42 55 2e 20 49 6e 20 74 68 69 73 20 63  g RBU. In this c
38c0: 61 73 65 20 74 68 65 20 75 73 65 72 20 69 73 20  ase the user is 
38d0: 72 65 71 75 69 72 65 64 20 74 6f 20 63 6f 6e 66  required to conf
38e0: 69 67 75 72 65 20 74 68 65 20 52 42 55 0a 64 61  igure the RBU.da
38f0: 74 61 62 61 73 65 20 73 6f 20 74 68 61 74 20 74  tabase so that t
3900: 68 65 20 73 61 6d 65 20 73 65 74 20 6f 66 20 55  he same set of U
3910: 50 44 41 54 45 2c 20 44 45 4c 45 54 45 20 61 6e  PDATE, DELETE an
3920: 64 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69  d INSERT operati
3930: 6f 6e 73 20 61 72 65 0a 61 70 70 6c 69 65 64 20  ons are.applied 
3940: 74 6f 20 74 68 65 20 46 54 53 34 20 69 6e 64 65  to the FTS4 inde
3950: 78 20 61 73 20 74 6f 20 74 68 65 20 75 6e 64 65  x as to the unde
3960: 72 6c 79 69 6e 67 20 63 6f 6e 74 65 6e 74 20 74  rlying content t
3970: 61 62 6c 65 2e 20 41 73 20 66 6f 72 20 61 6c 6c  able. As for all
3980: 0a 75 70 64 61 74 65 73 20 6f 66 20 65 78 74 65  .updates of exte
3990: 72 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 46 54 53  rnal content FTS
39a0: 34 20 74 61 62 6c 65 73 2c 20 74 68 65 20 75 73  4 tables, the us
39b0: 65 72 20 69 73 20 61 6c 73 6f 20 72 65 71 75 69  er is also requi
39c0: 72 65 64 20 74 6f 20 65 6e 73 75 72 65 0a 74 68  red to ensure.th
39d0: 61 74 20 61 6e 79 20 55 50 44 41 54 45 20 6f 72  at any UPDATE or
39e0: 20 44 45 4c 45 54 45 20 6f 70 65 72 61 74 69 6f   DELETE operatio
39f0: 6e 73 20 61 72 65 20 61 70 70 6c 69 65 64 20 74  ns are applied t
3a00: 6f 20 74 68 65 20 46 54 53 34 20 69 6e 64 65 78  o the FTS4 index
3a10: 20 62 65 66 6f 72 65 0a 74 68 65 79 20 61 72 65   before.they are
3a20: 20 61 70 70 6c 69 65 64 20 74 6f 20 74 68 65 20   applied to the 
3a30: 75 6e 64 65 72 6c 79 69 6e 67 20 63 6f 6e 74 65  underlying conte
3a40: 6e 74 20 74 61 62 6c 65 20 28 72 65 66 65 72 20  nt table (refer 
3a50: 74 6f 20 46 54 53 34 20 64 6f 63 75 6d 65 6e 74  to FTS4 document
3a60: 61 74 69 6f 6e 0a 66 6f 72 20 61 20 64 65 74 61  ation.for a deta
3a70: 69 6c 65 64 20 65 78 70 6c 61 6e 61 74 69 6f 6e  iled explanation
3a80: 29 2e 20 49 6e 20 52 42 55 2c 20 74 68 69 73 20  ). In RBU, this 
3a90: 69 73 20 64 6f 6e 65 20 62 79 20 65 6e 73 75 72  is done by ensur
3aa0: 69 6e 67 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ing that the nam
3ab0: 65 0a 6f 66 20 74 68 65 20 64 61 74 61 5f 25 20  e.of the data_% 
3ac0: 74 61 62 6c 65 20 75 73 65 64 20 74 6f 20 77 72  table used to wr
3ad0: 69 74 65 20 74 6f 20 74 68 65 20 46 54 53 34 20  ite to the FTS4 
3ae0: 74 61 62 6c 65 20 73 6f 72 74 73 20 62 65 66 6f  table sorts befo
3af0: 72 65 20 74 68 65 20 6e 61 6d 65 0a 6f 66 20 74  re the name.of t
3b00: 68 65 20 64 61 74 61 5f 25 20 74 61 62 6c 65 20  he data_% table 
3b10: 75 73 65 64 20 74 6f 20 75 70 64 61 74 65 20 74  used to update t
3b20: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 6f  he underlying co
3b30: 6e 74 65 6e 74 20 74 61 62 6c 65 20 75 73 69 6e  ntent table usin
3b40: 67 20 74 68 65 0a 5b 42 49 4e 41 52 59 5d 20 63  g the.[BINARY] c
3b50: 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
3b60: 65 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 61  e. In order to a
3b70: 76 6f 69 64 20 64 75 70 6c 69 63 61 74 69 6e 67  void duplicating
3b80: 20 64 61 74 61 20 77 69 74 68 69 6e 20 74 68 65   data within the
3b90: 0a 52 42 55 20 64 61 74 61 62 61 73 65 2c 20 61  .RBU database, a
3ba0: 6e 20 53 51 4c 20 76 69 65 77 20 6d 61 79 20 62  n SQL view may b
3bb0: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
3bc0: 6f 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 61  of one of the da
3bd0: 74 61 5f 25 20 74 61 62 6c 65 73 2e 0a 46 6f 72  ta_% tables..For
3be0: 20 65 78 61 6d 70 6c 65 2c 20 66 6f 72 20 74 68   example, for th
3bf0: 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73  e target databas
3c00: 65 20 73 63 68 65 6d 61 3a 0a 0a 3c 63 6f 64 65  e schema:..<code
3c10: 62 6c 6f 63 6b 3e 0a 20 20 43 52 45 41 54 45 20  block>.  CREATE 
3c20: 54 41 42 4c 45 20 63 63 63 28 61 64 64 72 2c 20  TABLE ccc(addr, 
3c30: 74 65 78 74 29 3b 0a 20 20 43 52 45 41 54 45 20  text);.  CREATE 
3c40: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 63 63  VIRTUAL TABLE cc
3c50: 63 5f 66 74 73 20 55 53 49 4e 47 20 66 74 73 34  c_fts USING fts4
3c60: 28 61 64 64 72 2c 20 74 65 78 74 2c 20 63 6f 6e  (addr, text, con
3c70: 74 65 6e 74 3d 63 63 63 29 3b 0a 3c 2f 63 6f 64  tent=ccc);.</cod
3c80: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 54  eblock>..<p>.  T
3c90: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 52 42 55  he following RBU
3ca0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
3cb0: 20 6d 61 79 20 62 65 20 75 73 65 64 3a 20 0a 0a   may be used: ..
3cc0: 3c 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 20 43 52  <codeblock>.  CR
3cd0: 45 41 54 45 20 54 41 42 4c 45 20 64 61 74 61 5f  EATE TABLE data_
3ce0: 63 63 63 28 61 64 64 72 2c 20 74 65 78 74 2c 20  ccc(addr, text, 
3cf0: 72 62 75 5f 72 6f 77 69 64 2c 20 72 62 75 5f 63  rbu_rowid, rbu_c
3d00: 6f 6e 74 72 6f 6c 29 3b 0a 20 20 43 52 45 41 54  ontrol);.  CREAT
3d10: 45 20 56 49 45 57 20 64 61 74 61 30 5f 63 63 63  E VIEW data0_ccc
3d20: 5f 66 74 73 20 41 53 20 53 45 4c 45 43 54 20 2a  _fts AS SELECT *
3d30: 20 46 52 4f 4d 20 64 61 74 61 5f 63 63 63 3b 0a   FROM data_ccc;.
3d40: 3c 2f 63 6f 64 65 62 6c 6f 63 6b 3e 0a 20 0a 3c  </codeblock>. .<
3d50: 70 3e 0a 20 20 54 68 65 20 64 61 74 61 5f 63 63  p>.  The data_cc
3d60: 63 20 74 61 62 6c 65 20 6d 61 79 20 74 68 65 6e  c table may then
3d70: 20 62 65 20 70 6f 70 75 6c 61 74 65 64 20 61 73   be populated as
3d80: 20 6e 6f 72 6d 61 6c 20 77 69 74 68 20 74 68 65   normal with the
3d90: 20 75 70 64 61 74 65 73 20 69 6e 74 65 6e 64 65   updates intende
3da0: 64 0a 20 20 66 6f 72 20 74 61 72 67 65 74 20 64  d.  for target d
3db0: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 63 63  atabase table cc
3dc0: 63 2e 20 54 68 65 20 73 61 6d 65 20 75 70 64 61  c. The same upda
3dd0: 74 65 73 20 77 69 6c 6c 20 62 65 20 72 65 61 64  tes will be read
3de0: 20 62 79 20 52 42 55 20 66 72 6f 6d 0a 20 20 74   by RBU from.  t
3df0: 68 65 20 64 61 74 61 30 5f 63 63 63 5f 66 74 73  he data0_ccc_fts
3e00: 20 76 69 65 77 20 61 6e 64 20 61 70 70 6c 69 65   view and applie
3e10: 64 20 74 6f 20 46 54 53 20 74 61 62 6c 65 20 63  d to FTS table c
3e20: 63 63 5f 66 74 73 2e 20 42 65 63 61 75 73 65 0a  cc_fts. Because.
3e30: 20 20 22 64 61 74 61 30 5f 63 63 63 5f 66 74 73    "data0_ccc_fts
3e40: 22 20 69 73 20 73 6d 61 6c 6c 65 72 20 74 68 61  " is smaller tha
3e50: 6e 20 22 64 61 74 61 5f 63 63 63 22 2c 20 74 68  n "data_ccc", th
3e60: 65 20 46 54 53 20 74 61 62 6c 65 20 77 69 6c 6c  e FTS table will
3e70: 20 62 65 20 75 70 64 61 74 65 64 0a 20 20 66 69   be updated.  fi
3e80: 72 73 74 2c 20 61 73 20 72 65 71 75 69 72 65 64  rst, as required
3e90: 2e 0a 0a 3c 70 3e 0a 20 20 43 61 73 65 73 20 69  ...<p>.  Cases i
3ea0: 6e 20 77 68 69 63 68 20 74 68 65 20 75 6e 64 65  n which the unde
3eb0: 72 6c 79 69 6e 67 20 63 6f 6e 74 65 6e 74 20 74  rlying content t
3ec0: 61 62 6c 65 20 68 61 73 20 61 6e 20 65 78 70 6c  able has an expl
3ed0: 69 63 69 74 20 49 4e 54 45 47 45 52 20 50 52 49  icit INTEGER PRI
3ee0: 4d 41 52 59 0a 20 20 4b 45 59 20 63 6f 6c 75 6d  MARY.  KEY colum
3ef0: 6e 20 61 72 65 20 73 6c 69 67 68 74 6c 79 20 6d  n are slightly m
3f00: 6f 72 65 20 64 69 66 66 69 63 75 6c 74 2c 20 61  ore difficult, a
3f10: 73 20 74 68 65 20 74 65 78 74 20 76 61 6c 75 65  s the text value
3f20: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a  s stored in the.
3f30: 20 20 72 62 75 5f 63 6f 6e 74 72 6f 6c 20 63 6f    rbu_control co
3f40: 6c 75 6d 6e 20 61 72 65 20 73 6c 69 67 68 74 6c  lumn are slightl
3f50: 79 20 64 69 66 66 65 72 65 6e 74 20 66 6f 72 20  y different for 
3f60: 74 68 65 20 46 54 53 20 69 6e 64 65 78 20 61 6e  the FTS index an
3f70: 64 20 69 74 73 0a 20 20 75 6e 64 65 72 6c 79 69  d its.  underlyi
3f80: 6e 67 20 63 6f 6e 74 65 6e 74 20 74 61 62 6c 65  ng content table
3f90: 2e 20 46 6f 72 20 74 68 65 20 75 6e 64 65 72 6c  . For the underl
3fa0: 79 69 6e 67 20 63 6f 6e 74 65 6e 74 20 74 61 62  ying content tab
3fb0: 6c 65 2c 20 61 20 63 68 61 72 61 63 74 65 72 0a  le, a character.
3fc0: 20 20 6d 75 73 74 20 62 65 20 69 6e 63 6c 75 64    must be includ
3fd0: 65 64 20 69 6e 20 61 6e 79 20 72 62 75 5f 63 6f  ed in any rbu_co
3fe0: 6e 74 72 6f 6c 20 74 65 78 74 20 76 61 6c 75 65  ntrol text value
3ff0: 73 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  s for the explic
4000: 69 74 20 49 50 4b 2c 20 62 75 74 0a 20 20 66 6f  it IPK, but.  fo
4010: 72 20 74 68 65 20 46 54 53 20 74 61 62 6c 65 20  r the FTS table 
4020: 69 74 73 65 6c 66 2c 20 77 68 69 63 68 20 68 61  itself, which ha
4030: 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
4040: 77 69 64 2c 20 69 74 20 73 68 6f 75 6c 64 20 6e  wid, it should n
4050: 6f 74 2e 20 54 68 69 73 0a 20 20 69 73 20 69 6e  ot. This.  is in
4060: 63 6f 6e 76 65 6e 69 65 6e 74 2c 20 62 75 74 20  convenient, but 
4070: 63 61 6e 20 62 65 20 73 6f 6c 76 65 64 20 75 73  can be solved us
4080: 69 6e 67 20 61 20 6d 6f 72 65 20 63 6f 6d 70 6c  ing a more compl
4090: 69 63 61 74 65 64 20 76 69 65 77 2c 20 61 73 20  icated view, as 
40a0: 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 63 6f 64 65 62  follows:..<codeb
40b0: 6c 6f 63 6b 3e 0a 20 20 2d 2d 20 54 61 72 67 65  lock>.  -- Targe
40c0: 74 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  t database schem
40d0: 61 0a 20 20 43 52 45 41 54 45 20 54 41 42 4c 45  a.  CREATE TABLE
40e0: 20 64 64 64 28 69 20 49 4e 54 45 47 45 52 20 50   ddd(i INTEGER P
40f0: 52 49 4d 41 52 59 20 4b 45 59 2c 20 6b 20 54 45  RIMARY KEY, k TE
4100: 58 54 29 3b 0a 20 20 43 52 45 41 54 45 20 56 49  XT);.  CREATE VI
4110: 52 54 55 41 4c 20 54 41 42 4c 45 20 64 64 64 5f  RTUAL TABLE ddd_
4120: 66 74 73 20 55 53 49 4e 47 20 66 74 73 34 28 6b  fts USING fts4(k
4130: 2c 20 63 6f 6e 74 65 6e 74 3d 64 64 64 29 3b 0a  , content=ddd);.
4140: 0a 20 20 2d 2d 20 52 42 55 20 64 61 74 61 62 61  .  -- RBU databa
4150: 73 65 20 73 63 68 65 6d 61 0a 20 20 43 52 45 41  se schema.  CREA
4160: 54 45 20 54 41 42 4c 45 20 64 61 74 61 5f 63 63  TE TABLE data_cc
4170: 63 28 69 2c 20 6b 2c 20 72 62 75 5f 63 6f 6e 74  c(i, k, rbu_cont
4180: 72 6f 6c 29 3b 0a 20 20 43 52 45 41 54 45 20 56  rol);.  CREATE V
4190: 49 45 57 20 64 61 74 61 30 5f 63 63 63 5f 66 74  IEW data0_ccc_ft
41a0: 73 20 41 53 20 53 45 4c 45 43 54 20 69 20 41 53  s AS SELECT i AS
41b0: 20 72 62 75 5f 72 6f 77 69 64 2c 20 6b 2c 20 43   rbu_rowid, k, C
41c0: 41 53 45 20 0a 20 20 20 20 57 48 45 4e 20 72 62  ASE .    WHEN rb
41d0: 75 5f 63 6f 6e 74 72 6f 6c 20 49 4e 20 28 30 2c  u_control IN (0,
41e0: 31 29 20 54 48 45 4e 20 72 62 75 5f 63 6f 6e 74  1) THEN rbu_cont
41f0: 72 6f 6c 20 45 4c 53 45 20 73 75 62 73 74 72 28  rol ELSE substr(
4200: 72 62 75 5f 63 6f 6e 74 72 6f 6c 2c 20 32 29 20  rbu_control, 2) 
4210: 45 4e 44 0a 20 20 46 52 4f 4d 20 64 61 74 61 5f  END.  FROM data_
4220: 63 63 63 3b 0a 3c 2f 63 6f 64 65 62 6c 6f 63 6b  ccc;.</codeblock
4230: 3e 0a 0a 3c 70 3e 0a 20 20 54 68 65 20 73 75 62  >..<p>.  The sub
4240: 73 74 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  str() function i
4250: 6e 20 74 68 65 20 53 51 4c 20 76 69 65 77 20 61  n the SQL view a
4260: 62 6f 76 65 20 72 65 74 75 72 6e 73 20 74 68 65  bove returns the
4270: 20 74 65 78 74 20 6f 66 20 74 68 65 0a 20 20 72   text of the.  r
4280: 62 75 5f 63 6f 6e 74 72 6f 6c 20 61 72 67 75 6d  bu_control argum
4290: 65 6e 74 20 77 69 74 68 20 74 68 65 20 66 69 72  ent with the fir
42a0: 73 74 20 63 68 61 72 61 63 74 65 72 20 28 74 68  st character (th
42b0: 65 20 6f 6e 65 20 63 6f 72 72 65 73 70 6f 6e 64  e one correspond
42c0: 69 6e 67 20 74 6f 0a 20 20 63 6f 6c 75 6d 6e 20  ing to.  column 
42d0: 22 69 22 2c 20 77 68 69 63 68 20 69 73 20 6e 6f  "i", which is no
42e0: 74 20 72 65 71 75 69 72 65 64 20 62 79 20 74 68  t required by th
42f0: 65 20 46 54 53 20 74 61 62 6c 65 29 20 72 65 6d  e FTS table) rem
4300: 6f 76 65 64 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66  oved...<tcl>hd_f
4310: 72 61 67 6d 65 6e 74 20 73 71 6c 64 69 66 66 20  ragment sqldiff 
4320: 7b 73 71 6c 64 69 66 66 20 2d 2d 72 62 75 7d 3c  {sqldiff --rbu}<
4330: 2f 74 63 6c 3e 0a 3c 68 33 3e 41 75 74 6f 6d 61  /tcl>.<h3>Automa
4340: 74 69 63 61 6c 6c 79 20 47 65 6e 65 72 61 74 69  tically Generati
4350: 6e 67 20 52 42 55 20 55 70 64 61 74 65 73 20 77  ng RBU Updates w
4360: 69 74 68 20 73 71 6c 64 69 66 66 3c 2f 68 33 3e  ith sqldiff</h3>
4370: 0a 0a 3c 70 3e 0a 20 20 41 73 20 6f 66 20 53 51  ..<p>.  As of SQ
4380: 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e  Lite [version 3.
4390: 39 2e 30 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e  9.0] ([dateof:3.
43a0: 39 2e 30 5d 29 2c 20 0a 20 20 74 68 65 20 5b 73  9.0]), .  the [s
43b0: 71 6c 64 69 66 66 5d 20 75 74 69 6c 69 74 79 20  qldiff] utility 
43c0: 69 73 20 61 62 6c 65 20 74 6f 20 67 65 6e 65 72  is able to gener
43d0: 61 74 65 0a 20 20 52 42 55 20 64 61 74 61 62 61  ate.  RBU databa
43e0: 73 65 73 20 72 65 70 72 65 73 65 6e 74 69 6e 67  ses representing
43f0: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 20   the difference 
4400: 62 65 74 77 65 65 6e 20 74 77 6f 20 64 61 74 61  between two data
4410: 62 61 73 65 73 20 77 69 74 68 0a 20 20 69 64 65  bases with.  ide
4420: 6e 74 69 63 61 6c 20 73 63 68 65 6d 61 73 2e 20  ntical schemas. 
4430: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 65  For example, the
4440: 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6d 6d 61   following comma
4450: 6e 64 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63 6b 3e  nd:..<codeblock>
4460: 0a 73 71 6c 64 69 66 66 20 2d 2d 72 62 75 20 74  .sqldiff --rbu t
4470: 31 2e 64 62 20 74 32 2e 64 62 0a 3c 2f 63 6f 64  1.db t2.db.</cod
4480: 65 62 6c 6f 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 4f  eblock>..<p>.  O
4490: 75 74 70 75 74 73 20 61 6e 20 53 51 4c 20 73 63  utputs an SQL sc
44a0: 72 69 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  ript to create a
44b0: 6e 20 52 42 55 20 64 61 74 61 62 61 73 65 20 77  n RBU database w
44c0: 68 69 63 68 2c 20 69 66 20 75 73 65 64 20 74 6f  hich, if used to
44d0: 20 75 70 64 61 74 65 0a 20 20 64 61 74 61 62 61   update.  databa
44e0: 73 65 20 74 31 2e 64 62 2c 20 70 61 74 63 68 65  se t1.db, patche
44f0: 73 20 69 74 20 73 6f 20 74 68 61 74 20 69 74 73  s it so that its
4500: 20 63 6f 6e 74 65 6e 74 73 20 61 72 65 20 69 64   contents are id
4510: 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 61 74 20  entical to that 
4520: 6f 66 0a 20 20 64 61 74 61 62 61 73 65 20 74 32  of.  database t2
4530: 2e 64 62 2e 0a 0a 3c 70 3e 0a 20 20 42 79 20 64  .db...<p>.  By d
4540: 65 66 61 75 6c 74 2c 20 73 71 6c 64 69 66 66 20  efault, sqldiff 
4550: 61 74 74 65 6d 70 74 73 20 74 6f 20 70 72 6f 63  attempts to proc
4560: 65 73 73 20 61 6c 6c 20 6e 6f 6e 2d 76 69 72 74  ess all non-virt
4570: 75 61 6c 20 74 61 62 6c 65 73 20 77 69 74 68 69  ual tables withi
4580: 6e 0a 20 20 74 68 65 20 74 77 6f 20 64 61 74 61  n.  the two data
4590: 62 61 73 65 73 20 70 72 6f 76 69 64 65 64 20 74  bases provided t
45a0: 6f 20 69 74 2e 20 49 66 20 61 6e 79 20 74 61 62  o it. If any tab
45b0: 6c 65 20 61 70 70 65 61 72 73 20 69 6e 20 6f 6e  le appears in on
45c0: 65 20 64 61 74 61 62 61 73 65 0a 20 20 62 75 74  e database.  but
45d0: 20 6e 6f 74 20 74 68 65 20 6f 74 68 65 72 2c 20   not the other, 
45e0: 6f 72 20 69 66 20 61 6e 79 20 74 61 62 6c 65 20  or if any table 
45f0: 68 61 73 20 61 20 73 6c 69 67 68 74 6c 79 20 64  has a slightly d
4600: 69 66 66 65 72 65 6e 74 20 73 63 68 65 6d 61 20  ifferent schema 
4610: 69 6e 0a 20 20 6f 6e 65 20 64 61 74 61 62 61 73  in.  one databas
4620: 65 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  e it is an error
4630: 2e 20 54 68 65 20 22 2d 2d 74 61 62 6c 65 22 20  . The "--table" 
4640: 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73  option may be us
4650: 65 66 75 6c 20 69 66 20 74 68 69 73 0a 20 20 63  eful if this.  c
4660: 61 75 73 65 73 20 61 20 70 72 6f 62 6c 65 6d 0a  auses a problem.
4670: 20 20 0a 3c 70 3e 0a 20 20 56 69 72 74 75 61 6c    .<p>.  Virtual
4680: 20 74 61 62 6c 65 73 20 61 72 65 20 69 67 6e 6f   tables are igno
4690: 72 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  red by default b
46a0: 79 20 73 71 6c 64 69 66 66 2e 20 48 6f 77 65 76  y sqldiff. Howev
46b0: 65 72 2c 20 69 74 20 69 73 20 70 6f 73 73 69 62  er, it is possib
46c0: 6c 65 20 0a 20 20 74 6f 20 65 78 70 6c 69 63 69  le .  to explici
46d0: 74 6c 79 20 63 72 65 61 74 65 20 61 6e 20 52 42  tly create an RB
46e0: 55 20 64 61 74 61 5f 25 20 74 61 62 6c 65 20 66  U data_% table f
46f0: 6f 72 20 61 20 76 69 72 74 75 61 6c 20 74 61 62  or a virtual tab
4700: 6c 65 20 74 68 61 74 20 66 65 61 74 75 72 65 73  le that features
4710: 0a 20 20 61 20 72 6f 77 69 64 20 74 68 61 74 20  .  a rowid that 
4720: 66 75 6e 63 74 69 6f 6e 73 20 6c 69 6b 65 20 61  functions like a
4730: 20 70 72 69 6d 61 72 79 20 6b 65 79 20 75 73 69   primary key usi
4740: 6e 67 20 61 20 63 6f 6d 6d 61 6e 64 20 73 75 63  ng a command suc
4750: 68 20 61 73 3a 0a 0a 3c 63 6f 64 65 62 6c 6f 63  h as:..<codebloc
4760: 6b 3e 0a 73 71 6c 64 69 66 66 20 2d 2d 72 62 75  k>.sqldiff --rbu
4770: 20 2d 2d 74 61 62 6c 65 20 26 6c 74 3b 3c 69 3e   --table &lt;<i>
4780: 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 2d 6e 61  virtual-table-na
4790: 6d 65 3c 2f 69 3e 26 67 74 3b 20 74 31 2e 64 62  me</i>&gt; t1.db
47a0: 20 74 32 2e 64 62 0a 3c 2f 63 6f 64 65 62 6c 6f   t2.db.</codeblo
47b0: 63 6b 3e 0a 0a 3c 70 3e 0a 20 20 55 6e 66 6f 72  ck>..<p>.  Unfor
47c0: 74 75 6e 61 74 65 6c 79 2c 20 65 76 65 6e 20 74  tunately, even t
47d0: 68 6f 75 67 68 20 76 69 72 74 75 61 6c 20 74 61  hough virtual ta
47e0: 62 6c 65 73 20 61 72 65 20 69 67 6e 6f 72 65 64  bles are ignored
47f0: 20 62 79 20 64 65 66 61 75 6c 74 2c 20 61 6e 79   by default, any
4800: 0a 20 20 5b 46 54 53 20 73 68 61 64 6f 77 20 74  .  [FTS shadow t
4810: 61 62 6c 65 73 20 7c 20 75 6e 64 65 72 6c 79 69  ables | underlyi
4820: 6e 67 20 64 61 74 61 62 61 73 65 20 74 61 62 6c  ng database tabl
4830: 65 73 5d 20 74 68 61 74 20 74 68 65 79 20 63 72  es] that they cr
4840: 65 61 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  eate in order to
4850: 0a 20 20 73 74 6f 72 65 20 64 61 74 61 20 77 69  .  store data wi
4860: 74 68 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  thin the databas
4870: 65 20 61 72 65 20 6e 6f 74 2c 20 61 6e 64 20 5b  e are not, and [
4880: 73 71 6c 64 69 66 66 5d 20 77 69 6c 6c 20 69 6e  sqldiff] will in
4890: 63 6c 75 64 65 20 61 64 64 20 74 68 65 73 65 0a  clude add these.
48a0: 20 20 74 6f 20 61 6e 79 20 52 42 55 20 64 61 74    to any RBU dat
48b0: 61 62 61 73 65 2e 20 46 6f 72 20 74 68 69 73 20  abase. For this 
48c0: 72 65 61 73 6f 6e 2c 20 75 73 65 72 73 20 61 74  reason, users at
48d0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 75 73 65 20  tempting to use 
48e0: 73 71 6c 64 69 66 66 20 74 6f 0a 20 20 63 72 65  sqldiff to.  cre
48f0: 61 74 65 20 52 42 55 20 75 70 64 61 74 65 73 20  ate RBU updates 
4900: 74 6f 20 61 70 70 6c 79 20 74 6f 20 74 61 72 67  to apply to targ
4910: 65 74 20 64 61 74 61 62 61 73 65 73 20 77 69 74  et databases wit
4920: 68 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 76 69  h one or more vi
4930: 72 74 75 61 6c 0a 20 20 74 61 62 6c 65 73 20 77  rtual.  tables w
4940: 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 76 65 20  ill likely have 
4950: 74 6f 20 72 75 6e 20 73 71 6c 64 69 66 66 20 75  to run sqldiff u
4960: 73 69 6e 67 20 74 68 65 20 2d 2d 74 61 62 6c 65  sing the --table
4970: 20 6f 70 74 69 6f 6e 20 73 65 70 61 72 61 74 65   option separate
4980: 6c 79 0a 20 20 66 6f 72 20 65 61 63 68 20 74 61  ly.  for each ta
4990: 62 6c 65 20 74 6f 20 75 70 64 61 74 65 20 69 6e  ble to update in
49a0: 20 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61   the target data
49b0: 62 61 73 65 2e 0a 0a 3c 68 32 3e 52 42 55 20 55  base...<h2>RBU U
49c0: 70 64 61 74 65 20 43 2f 43 2b 2b 20 50 72 6f 67  pdate C/C++ Prog
49d0: 72 61 6d 6d 69 6e 67 3c 2f 68 32 3e 0a 0a 3c 70  ramming</h2>..<p
49e0: 3e 54 68 65 20 52 42 55 20 65 78 74 65 6e 73 69  >The RBU extensi
49f0: 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  on interface all
4a00: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
4a10: 6f 6e 20 74 6f 20 61 70 70 6c 79 20 61 6e 20 52  on to apply an R
4a20: 42 55 20 75 70 64 61 74 65 20 0a 73 74 6f 72 65  BU update .store
4a30: 64 20 69 6e 20 61 6e 20 52 42 55 20 64 61 74 61  d in an RBU data
4a40: 62 61 73 65 20 74 6f 20 61 6e 20 65 78 69 73 74  base to an exist
4a50: 69 6e 67 20 74 61 72 67 65 74 20 64 61 74 61 62  ing target datab
4a60: 61 73 65 2e 0a 54 68 65 20 70 72 6f 63 65 64 75  ase..The procedu
4a70: 72 65 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  re is as follows
4a80: 3a 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e 0a  :..<ol>.<li><p>.
4a90: 4f 70 65 6e 20 61 6e 20 52 42 55 20 68 61 6e 64  Open an RBU hand
4aa0: 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  le using the sql
4ab0: 69 74 65 33 72 62 75 5f 6f 70 65 6e 28 54 2c 41  ite3rbu_open(T,A
4ac0: 2c 53 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 0a 3c  ,S) function...<
4ad0: 70 3e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74  p>The T argument
4ae0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
4af0: 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62  the target datab
4b00: 61 73 65 20 66 69 6c 65 2e 0a 54 68 65 20 41 20  ase file..The A 
4b10: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
4b20: 6e 61 6d 65 20 6f 66 20 74 68 65 20 52 42 55 20  name of the RBU 
4b30: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 54  database file..T
4b40: 68 65 20 53 20 61 72 67 75 6d 65 6e 74 20 69 73  he S argument is
4b50: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 22   the name of a "
4b60: 73 74 61 74 65 20 64 61 74 61 62 61 73 65 22 20  state database" 
4b70: 75 73 65 64 20 74 6f 20 73 74 6f 72 65 0a 73 74  used to store.st
4b80: 61 74 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ate information 
4b90: 6e 65 65 64 65 64 20 74 6f 20 72 65 73 75 6d 65  needed to resume
4ba0: 20 74 68 65 20 75 70 64 61 74 65 20 61 66 74 65   the update afte
4bb0: 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 69 6f  r an interruptio
4bc0: 6e 2e 0a 54 68 65 20 53 20 61 72 67 75 6d 65 6e  n..The S argumen
4bd0: 74 20 63 61 6e 20 62 65 20 4e 55 4c 4c 20 69 6e  t can be NULL in
4be0: 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
4bf0: 73 74 61 74 65 20 69 6e 66 6f 72 6d 61 74 69 6f  state informatio
4c00: 6e 0a 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  n.is stored in t
4c10: 68 65 20 52 42 55 20 64 61 74 61 62 61 73 65 20  he RBU database 
4c20: 69 6e 20 76 61 72 69 6f 75 73 20 74 61 62 6c 65  in various table
4c30: 73 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 61 6c  s whose names al
4c40: 6c 0a 62 65 67 69 6e 20 77 69 74 68 20 22 72 62  l.begin with "rb
4c50: 75 5f 22 2e 0a 0a 3c 70 3e 54 68 65 20 73 71 6c  u_"...<p>The sql
4c60: 69 74 65 33 72 62 75 5f 6f 70 65 6e 28 54 2c 41  ite3rbu_open(T,A
4c70: 2c 53 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ,S) function ret
4c80: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
4c90: 6f 0a 61 6e 20 22 73 71 6c 69 74 65 33 72 62 75  o.an "sqlite3rbu
4ca0: 22 20 6f 62 6a 65 63 74 2c 20 77 68 69 63 68 20  " object, which 
4cb0: 69 73 20 74 68 65 6e 20 70 61 73 73 65 64 20 69  is then passed i
4cc0: 6e 74 6f 20 74 68 65 20 73 75 62 73 65 71 75 65  nto the subseque
4cd0: 6e 74 0a 69 6e 74 65 72 66 61 63 65 73 2e 0a 0a  nt.interfaces...
4ce0: 0a 3c 6c 69 3e 3c 70 3e 0a 52 65 67 69 73 74 65  .<li><p>.Registe
4cf0: 72 20 61 6e 79 20 72 65 71 75 69 72 65 64 20 76  r any required v
4d00: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
4d10: 75 6c 65 73 20 77 69 74 68 20 74 68 65 20 64 61  ules with the da
4d20: 74 61 62 61 73 65 0a 68 61 6e 64 6c 65 20 72 65  tabase.handle re
4d30: 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
4d40: 33 72 62 75 5f 64 62 28 58 29 20 28 77 68 65 72  3rbu_db(X) (wher
4d50: 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 73 20  e argument X is 
4d60: 74 68 65 20 73 71 6c 69 74 65 33 72 62 75 0a 70  the sqlite3rbu.p
4d70: 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 20  ointer returned 
4d80: 66 72 6f 6d 20 73 71 6c 69 74 65 33 72 62 75 5f  from sqlite3rbu_
4d90: 6f 70 65 6e 28 29 29 2e 20 20 41 6c 73 6f 2c 20  open()).  Also, 
4da0: 69 66 20 72 65 71 75 69 72 65 64 2c 20 72 65 67  if required, reg
4db0: 69 73 74 65 72 0a 74 68 65 20 72 62 75 5f 64 65  ister.the rbu_de
4dc0: 6c 74 61 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lta() SQL functi
4dd0: 6f 6e 20 75 73 69 6e 67 20 0a 5b 73 71 6c 69 74  on using .[sqlit
4de0: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
4df0: 6f 6e 5f 76 32 28 29 5d 2e 0a 0a 3c 6c 69 3e 3c  on_v2()]...<li><
4e00: 70 3e 0a 49 6e 76 6f 6b 65 20 74 68 65 20 73 71  p>.Invoke the sq
4e10: 6c 69 74 65 33 72 62 75 5f 73 74 65 70 28 58 29  lite3rbu_step(X)
4e20: 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 65 20 6f 72   function one or
4e30: 20 6d 6f 72 65 20 74 69 6d 65 73 20 6f 6e 0a 74   more times on.t
4e40: 68 65 20 73 71 6c 69 74 65 33 72 62 75 20 6f 62  he sqlite3rbu ob
4e50: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 58 2e 20  ject pointer X. 
4e60: 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
4e70: 69 74 65 33 72 62 75 5f 73 74 65 70 28 29 20 0a  ite3rbu_step() .
4e80: 70 65 72 66 6f 72 6d 73 20 61 20 73 69 6e 67 6c  performs a singl
4e90: 65 20 62 2d 74 72 65 65 20 6f 70 65 72 61 74 69  e b-tree operati
4ea0: 6f 6e 2c 20 73 6f 20 74 68 6f 75 73 61 6e 64 73  on, so thousands
4eb0: 20 6f 66 20 63 61 6c 6c 73 20 6d 61 79 20 62 65   of calls may be
4ec0: 20 0a 72 65 71 75 69 72 65 64 20 74 6f 20 61 70   .required to ap
4ed0: 70 6c 79 20 61 20 63 6f 6d 70 6c 65 74 65 20 75  ply a complete u
4ee0: 70 64 61 74 65 2e 20 20 54 68 65 20 73 71 6c 69  pdate.  The sqli
4ef0: 74 65 33 72 62 75 5f 73 74 65 70 28 29 20 0a 69  te3rbu_step() .i
4f00: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
4f10: 74 75 72 6e 20 53 51 4c 49 54 45 5f 44 4f 4e 45  turn SQLITE_DONE
4f20: 20 77 68 65 6e 20 74 68 65 20 75 70 64 61 74 65   when the update
4f30: 20 68 61 73 20 62 65 65 6e 0a 63 6f 6d 70 6c 65   has been.comple
4f40: 74 65 6c 79 20 61 70 70 6c 69 65 64 2e 0a 0a 3c  tely applied...<
4f50: 6c 69 3e 3c 70 3e 0a 43 61 6c 6c 20 73 71 6c 69  li><p>.Call sqli
4f60: 74 65 33 72 62 75 5f 63 6c 6f 73 65 28 58 29 20  te3rbu_close(X) 
4f70: 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 20 73  to destroy the s
4f80: 71 6c 69 74 65 33 72 62 75 20 6f 62 6a 65 63 74  qlite3rbu object
4f90: 20 70 6f 69 6e 74 65 72 2e 0a 49 66 20 73 71 6c   pointer..If sql
4fa0: 69 74 65 33 72 62 75 5f 73 74 65 70 28 58 29 20  ite3rbu_step(X) 
4fb0: 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
4fc0: 65 6e 6f 75 67 68 20 74 69 6d 65 73 20 74 6f 20  enough times to 
4fd0: 63 6f 6d 70 6c 65 74 65 6c 79 0a 61 70 70 6c 79  completely.apply
4fe0: 20 74 68 65 20 75 70 64 61 74 65 20 74 6f 20 74   the update to t
4ff0: 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61  he target databa
5000: 73 65 2c 20 74 68 65 6e 20 74 68 65 20 52 42 55  se, then the RBU
5010: 20 64 61 74 61 62 61 73 65 0a 69 73 20 6d 61 72   database.is mar
5020: 6b 65 64 20 61 73 20 66 75 6c 6c 79 20 61 70 70  ked as fully app
5030: 6c 69 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c  lied. Otherwise,
5040: 20 74 68 65 20 73 74 61 74 65 20 6f 66 20 74 68   the state of th
5050: 65 20 52 42 55 20 0a 75 70 64 61 74 65 20 61 70  e RBU .update ap
5060: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 73 61 76  plication is sav
5070: 65 64 20 69 6e 20 74 68 65 20 73 74 61 74 65 20  ed in the state 
5080: 64 61 74 61 62 61 73 65 20 28 6f 72 20 69 6e 20  database (or in 
5090: 74 68 65 20 52 42 55 0a 64 61 74 61 62 61 73 65  the RBU.database
50a0: 20 69 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   if the name of 
50b0: 74 68 65 20 73 74 61 74 65 20 64 61 74 61 62 61  the state databa
50c0: 73 65 20 66 69 6c 65 20 69 6e 20 73 71 6c 69 74  se file in sqlit
50d0: 65 33 72 62 75 5f 6f 70 65 6e 28 29 0a 69 73 20  e3rbu_open().is 
50e0: 4e 55 4c 4c 29 20 66 6f 72 20 6c 61 74 65 72 20  NULL) for later 
50f0: 72 65 73 75 6d 70 74 69 6f 6e 20 6f 66 20 74 68  resumption of th
5100: 65 20 75 70 64 61 74 65 2e 0a 3c 2f 6f 6c 3e 0a  e update..</ol>.
5110: 0a 3c 70 3e 49 66 20 61 6e 20 75 70 64 61 74 65  .<p>If an update
5120: 20 69 73 20 6f 6e 6c 79 20 70 61 72 74 69 61 6c   is only partial
5130: 6c 79 20 61 70 70 6c 69 65 64 20 74 6f 20 74 68  ly applied to th
5140: 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73  e target databas
5150: 65 20 62 79 20 74 68 65 0a 74 69 6d 65 20 73 71  e by the.time sq
5160: 6c 69 74 65 33 72 62 75 5f 63 6c 6f 73 65 28 29  lite3rbu_close()
5170: 20 69 73 20 63 61 6c 6c 65 64 2c 20 73 74 61 74   is called, stat
5180: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
5190: 20 73 61 76 65 64 20 0a 77 69 74 68 69 6e 20 74   saved .within t
51a0: 68 65 20 73 74 61 74 65 20 64 61 74 61 62 61 73  he state databas
51b0: 65 20 69 66 20 69 74 20 65 78 69 73 74 73 2c 20  e if it exists, 
51c0: 6f 72 20 6f 74 68 65 72 77 69 73 65 20 69 6e 20  or otherwise in 
51d0: 74 68 65 20 52 42 55 20 64 61 74 61 62 61 73 65  the RBU database
51e0: 2e 20 0a 54 68 69 73 20 61 6c 6c 6f 77 73 20 73  . .This allows s
51f0: 75 62 73 65 71 75 65 6e 74 20 70 72 6f 63 65 73  ubsequent proces
5200: 73 65 73 20 74 6f 20 61 75 74 6f 6d 61 74 69 63  ses to automatic
5210: 61 6c 6c 79 0a 72 65 73 75 6d 65 20 74 68 65 20  ally.resume the 
5220: 52 42 55 20 75 70 64 61 74 65 20 66 72 6f 6d 20  RBU update from 
5230: 77 68 65 72 65 20 69 74 20 6c 65 66 74 20 6f 66  where it left of
5240: 66 2e 0a 49 66 20 73 74 61 74 65 20 69 6e 66 6f  f..If state info
5250: 72 6d 61 74 69 6f 6e 20 69 73 20 73 74 6f 72 65  rmation is store
5260: 64 20 69 6e 20 74 68 65 20 52 42 55 20 64 61 74  d in the RBU dat
5270: 61 62 61 73 65 2c 20 69 74 20 63 61 6e 20 62 65  abase, it can be
5280: 20 72 65 6d 6f 76 65 64 0a 62 79 20 64 72 6f 70   removed.by drop
5290: 70 69 6e 67 20 61 6c 6c 20 74 61 62 6c 65 73 20  ping all tables 
52a0: 77 68 6f 73 65 20 6e 61 6d 65 73 20 62 65 67 69  whose names begi
52b0: 6e 20 77 69 74 68 20 22 72 62 75 5f 22 2e 0a 0a  n with "rbu_"...
52c0: 3c 70 3e 46 6f 72 20 6d 6f 72 65 20 64 65 74 61  <p>For more deta
52d0: 69 6c 73 2c 20 72 65 66 65 72 20 74 6f 20 74 68  ils, refer to th
52e0: 65 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 0a 3c  e comments in .<
52f0: 61 20 68 72 65 66 3d 68 74 74 70 3a 2f 2f 73 71  a href=http://sq
5300: 6c 69 74 65 2e 6f 72 67 2f 73 72 63 2f 64 6f 63  lite.org/src/doc
5310: 2f 74 72 75 6e 6b 2f 65 78 74 2f 72 62 75 2f 73  /trunk/ext/rbu/s
5320: 71 6c 69 74 65 33 72 62 75 2e 68 3e 68 65 61 64  qlite3rbu.h>head
5330: 65 72 20 66 69 6c 65 0a 73 71 6c 69 74 65 33 72  er file.sqlite3r
5340: 62 75 2e 68 3c 2f 61 3e 2e 0a 0a 3c 74 63 6c 3e  bu.h</a>...<tcl>
5350: 68 64 5f 66 72 61 67 6d 65 6e 74 20 72 62 75 5f  hd_fragment rbu_
5360: 76 61 63 75 75 6d 20 7b 52 42 55 20 56 61 63 75  vacuum {RBU Vacu
5370: 75 6d 7d 3c 2f 74 63 6c 3e 0a 3c 68 31 3e 52 42  um}</tcl>.<h1>RB
5380: 55 20 56 61 63 75 75 6d 3c 2f 68 31 3e 0a 0a 3c  U Vacuum</h1>..<
5390: 68 32 3e 52 42 55 20 56 61 63 75 75 6d 20 4c 69  h2>RBU Vacuum Li
53a0: 6d 69 74 61 74 69 6f 6e 73 3c 2f 68 32 3e 0a 0a  mitations</h2>..
53b0: 3c 70 3e 57 68 65 6e 20 63 6f 6d 70 61 72 65 64  <p>When compared
53c0: 20 77 69 74 68 20 53 51 4c 69 74 65 27 73 20 62   with SQLite's b
53d0: 75 69 6c 74 2d 69 6e 20 56 41 43 55 55 4d 20 63  uilt-in VACUUM c
53e0: 6f 6d 6d 61 6e 64 2c 20 52 42 55 20 56 61 63 75  ommand, RBU Vacu
53f0: 75 6d 20 68 61 73 20 74 68 65 0a 66 6f 6c 6c 6f  um has the.follo
5400: 77 69 6e 67 20 6c 69 6d 69 74 61 74 69 6f 6e 73  wing limitations
5410: 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 3c 70  :..<ul>.  <li><p
5420: 3e 49 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 75  >It may not be u
5430: 73 65 64 20 6f 6e 20 61 20 64 61 74 61 62 61 73  sed on a databas
5440: 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  e that contains 
5450: 5b 69 6e 64 65 78 65 73 20 6f 6e 20 65 78 70 72  [indexes on expr
5460: 65 73 73 69 6f 6e 73 5d 2e 0a 20 20 3c 6c 69 3e  essions]..  <li>
5470: 3c 70 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  <p>The database 
5480: 62 65 69 6e 67 20 76 61 63 75 75 6d 65 64 20 6d  being vacuumed m
5490: 61 79 20 6e 6f 74 20 62 65 20 69 6e 20 5b 57 41  ay not be in [WA
54a0: 4c 20 6d 6f 64 65 5d 2e 0a 3c 2f 75 6c 3e 0a 0a  L mode]..</ul>..
54b0: 3c 68 32 3e 52 42 55 20 56 61 63 75 75 6d 20 43  <h2>RBU Vacuum C
54c0: 2f 43 2b 2b 20 50 72 6f 67 72 61 6d 6d 69 6e 67  /C++ Programming
54d0: 3c 2f 68 32 3e 0a 0a 3c 70 3e 20 54 68 69 73 20  </h2>..<p> This 
54e0: 73 65 63 74 69 6f 6e 20 70 72 6f 76 69 64 65 73  section provides
54f0: 20 61 6e 20 6f 76 65 72 76 69 65 77 20 6f 66 20   an overview of 
5500: 61 6e 64 20 65 78 61 6d 70 6c 65 20 63 6f 64 65  and example code
5510: 20 64 65 6d 6f 6e 73 74 72 61 74 69 6e 67 20 74   demonstrating t
5520: 68 65 0a 20 20 20 20 69 6e 74 65 67 72 61 74 69  he.    integrati
5530: 6f 6e 20 6f 66 20 52 42 55 20 56 61 63 75 75 6d  on of RBU Vacuum
5540: 20 69 6e 74 6f 20 61 6e 20 61 70 70 6c 69 63 61   into an applica
5550: 74 69 6f 6e 20 70 72 6f 67 72 61 6d 2e 20 20 46  tion program.  F
5560: 6f 72 20 66 75 6c 6c 20 64 65 74 61 69 6c 73 2c  or full details,
5570: 0a 20 20 20 20 72 65 66 65 72 20 74 6f 20 74 68  .    refer to th
5580: 65 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 0a 20  e comments in . 
5590: 20 20 20 3c 61 20 68 72 65 66 3d 68 74 74 70 3a     <a href=http:
55a0: 2f 2f 73 71 6c 69 74 65 2e 6f 72 67 2f 73 72 63  //sqlite.org/src
55b0: 2f 64 6f 63 2f 74 72 75 6e 6b 2f 65 78 74 2f 72  /doc/trunk/ext/r
55c0: 62 75 2f 73 71 6c 69 74 65 33 72 62 75 2e 68 3e  bu/sqlite3rbu.h>
55d0: 68 65 61 64 65 72 20 66 69 6c 65 0a 20 20 20 20  header file.    
55e0: 73 71 6c 69 74 65 33 72 62 75 2e 68 3c 2f 61 3e  sqlite3rbu.h</a>
55f0: 2e 0a 0a 3c 70 3e 20 52 42 55 20 56 61 63 75 75  ...<p> RBU Vacuu
5600: 6d 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  m applications a
5610: 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
5620: 65 20 76 61 72 69 61 74 69 6f 6e 20 6f 66 20 74  e variation of t
5630: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 70 72 6f  he following.pro
5640: 63 65 64 75 72 65 3a 0a 0a 3c 6f 6c 3e 0a 20 20  cedure:..<ol>.  
5650: 3c 6c 69 3e 3c 70 3e 20 41 6e 20 52 42 55 20 68  <li><p> An RBU h
5660: 61 6e 64 6c 65 20 69 73 20 63 72 65 61 74 65 64  andle is created
5670: 20 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   by calling sqli
5680: 74 65 33 72 62 75 5f 76 61 63 75 75 6d 28 54 2c  te3rbu_vacuum(T,
5690: 20 53 29 2e 0a 0a 20 20 20 20 20 20 3c 70 3e 20   S)...      <p> 
56a0: 41 72 67 75 6d 65 6e 74 20 54 20 69 73 20 74 68  Argument T is th
56b0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
56c0: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 76  tabase file to v
56d0: 61 63 75 75 6d 2e 20 41 72 67 75 6d 65 6e 74 20  acuum. Argument 
56e0: 53 20 69 73 0a 20 20 20 20 20 20 74 68 65 20 6e  S is.      the n
56f0: 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73  ame of a databas
5700: 65 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 52  e in which the R
5710: 42 55 20 6d 6f 64 75 6c 65 20 77 69 6c 6c 20 73  BU module will s
5720: 61 76 65 20 69 74 73 20 73 74 61 74 65 20 69 66  ave its state if
5730: 20 74 68 65 0a 20 20 20 20 20 20 76 61 63 75 75   the.      vacuu
5740: 6d 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 73  m operation is s
5750: 75 73 70 65 6e 64 65 64 2e 0a 0a 20 20 20 20 20  uspended...     
5760: 20 3c 70 3e 20 49 66 20 73 74 61 74 65 20 64 61   <p> If state da
5770: 74 61 62 61 73 65 20 53 20 64 6f 65 73 20 6e 6f  tabase S does no
5780: 74 20 65 78 69 73 74 20 77 68 65 6e 20 73 71 6c  t exist when sql
5790: 69 74 65 33 72 62 75 5f 76 61 63 75 75 6d 28 29  ite3rbu_vacuum()
57a0: 20 69 73 0a 20 20 20 20 20 20 69 6e 76 6f 6b 65   is.      invoke
57b0: 64 2c 20 69 74 20 69 73 20 61 75 74 6f 6d 61 74  d, it is automat
57c0: 69 63 61 6c 6c 79 20 63 72 65 61 74 65 64 20 61  ically created a
57d0: 6e 64 20 70 6f 70 75 6c 61 74 65 64 20 77 69 74  nd populated wit
57e0: 68 20 74 68 65 20 73 69 6e 67 6c 65 20 74 61 62  h the single tab
57f0: 6c 65 0a 20 20 20 20 20 20 75 73 65 64 20 74 6f  le.      used to
5800: 20 73 74 6f 72 65 20 74 68 65 20 73 74 61 74 65   store the state
5810: 20 6f 66 20 61 6e 20 52 42 55 20 76 61 63 75 75   of an RBU vacuu
5820: 6d 20 2d 20 22 72 62 75 5f 73 74 61 74 65 22 2e  m - "rbu_state".
5830: 20 49 66 20 61 6e 20 6f 6e 67 6f 69 6e 67 20 52   If an ongoing R
5840: 42 55 0a 20 20 20 20 20 20 76 61 63 75 75 6d 20  BU.      vacuum 
5850: 69 73 20 73 75 73 70 65 6e 64 65 64 2c 20 74 68  is suspended, th
5860: 69 73 20 74 61 62 6c 65 20 69 73 20 70 6f 70 75  is table is popu
5870: 6c 61 74 65 64 20 77 69 74 68 20 73 74 61 74 65  lated with state
5880: 20 64 61 74 61 2e 20 54 68 65 20 6e 65 78 74 0a   data. The next.
5890: 20 20 20 20 20 20 74 69 6d 65 20 73 71 6c 69 74        time sqlit
58a0: 65 33 72 62 75 5f 76 61 63 75 75 6d 28 29 20 69  e3rbu_vacuum() i
58b0: 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  s called with th
58c0: 65 20 73 61 6d 65 20 53 20 70 61 72 61 6d 65 74  e same S paramet
58d0: 65 72 2c 20 69 74 20 64 65 74 65 63 74 73 0a 20  er, it detects. 
58e0: 20 20 20 20 20 74 68 69 73 20 64 61 74 61 20 61       this data a
58f0: 6e 64 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  nd attempts to r
5900: 65 73 75 6d 65 20 74 68 65 20 73 75 73 70 65 6e  esume the suspen
5910: 64 65 64 20 76 61 63 75 75 6d 20 6f 70 65 72 61  ded vacuum opera
5920: 74 69 6f 6e 2e 20 57 68 65 6e 0a 20 20 20 20 20  tion. When.     
5930: 20 61 6e 20 52 42 55 20 76 61 63 75 75 6d 20 6f   an RBU vacuum o
5940: 70 65 72 61 74 69 6f 6e 20 69 73 20 63 6f 6d 70  peration is comp
5950: 6c 65 74 65 64 20 6f 72 20 65 6e 63 6f 75 6e 74  leted or encount
5960: 65 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 52 42  ers an error, RB
5970: 55 20 0a 20 20 20 20 20 20 61 75 74 6f 6d 61 74  U .      automat
5980: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 73 20 74  ically deletes t
5990: 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
59a0: 68 65 20 72 62 75 5f 73 74 61 74 65 20 74 61 62  he rbu_state tab
59b0: 6c 65 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  le. In this case
59c0: 2c 0a 20 20 20 20 20 20 74 68 65 20 6e 65 78 74  ,.      the next
59d0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
59e0: 72 62 75 5f 76 61 63 75 75 6d 28 29 20 73 74 61  rbu_vacuum() sta
59f0: 72 74 73 20 61 6e 20 65 6e 74 69 72 65 6c 79 20  rts an entirely 
5a00: 6e 65 77 20 76 61 63 75 75 6d 0a 20 20 20 20 20  new vacuum.     
5a10: 20 6f 70 65 72 61 74 69 6f 6e 20 66 72 6f 6d 20   operation from 
5a20: 73 63 72 61 74 63 68 2e 0a 0a 20 20 20 20 20 20  scratch...      
5a30: 3c 70 3e 20 49 74 20 69 73 20 61 20 67 6f 6f 64  <p> It is a good
5a40: 20 69 64 65 61 20 74 6f 20 65 73 74 61 62 6c 69   idea to establi
5a50: 73 68 20 61 20 63 6f 6e 76 65 6e 74 69 6f 6e 20  sh a convention 
5a60: 66 6f 72 20 64 65 74 65 72 6d 69 6e 69 6e 67 20  for determining 
5a70: 74 68 65 20 52 42 55 0a 20 20 20 20 20 20 76 61  the RBU.      va
5a80: 63 75 75 6d 20 73 74 61 74 65 20 64 61 74 61 62  cuum state datab
5a90: 61 73 65 20 6e 61 6d 65 20 62 61 73 65 64 20 6f  ase name based o
5aa0: 6e 20 74 68 65 20 74 61 72 67 65 74 20 64 61 74  n the target dat
5ab0: 61 62 61 73 65 20 6e 61 6d 65 2e 20 54 68 65 0a  abase name. The.
5ac0: 20 20 20 20 20 20 65 78 61 6d 70 6c 65 20 63 6f        example co
5ad0: 64 65 20 62 65 6c 6f 77 20 75 73 65 73 20 22 26  de below uses "&
5ae0: 6c 74 3b 74 61 72 67 65 74 26 67 74 3b 2d 76 61  lt;target&gt;-va
5af0: 63 75 75 6d 22 2c 20 77 68 65 72 65 20 26 6c 74  cuum", where &lt
5b00: 3b 74 61 72 67 65 74 26 67 74 3b 20 69 73 0a 20  ;target&gt; is. 
5b10: 20 20 20 20 20 74 68 65 20 6e 61 6d 65 20 6f 66       the name of
5b20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 65   the database be
5b30: 69 6e 67 20 76 61 63 75 75 6d 65 64 2e 0a 0a 20  ing vacuumed... 
5b40: 20 3c 6c 69 3e 3c 70 3e 20 41 6e 79 20 63 75 73   <li><p> Any cus
5b50: 74 6f 6d 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  tom collation se
5b60: 71 75 65 6e 63 65 73 20 75 73 65 64 20 62 79 20  quences used by 
5b70: 69 6e 64 65 78 65 73 20 77 69 74 68 69 6e 20 74  indexes within t
5b80: 68 65 20 64 61 74 61 62 61 73 65 0a 20 20 20 20  he database.    
5b90: 20 20 62 65 69 6e 67 20 76 61 63 75 75 6d 65 64    being vacuumed
5ba0: 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20   are registered 
5bb0: 77 69 74 68 20 62 6f 74 68 20 6f 66 20 74 68 65  with both of the
5bc0: 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
5bd0: 73 20 72 65 74 75 72 6e 65 64 0a 20 20 20 20 20  s returned.     
5be0: 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 72   by the sqlite3r
5bf0: 62 75 5f 64 62 28 29 20 66 75 6e 63 74 69 6f 6e  bu_db() function
5c00: 2e 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 20 46 75 6e  ...  <li><p> Fun
5c10: 63 74 69 6f 6e 20 73 71 6c 69 74 65 33 72 62 75  ction sqlite3rbu
5c20: 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
5c30: 64 20 6f 6e 20 74 68 65 20 52 42 55 20 68 61 6e  d on the RBU han
5c40: 64 6c 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72  dle until either
5c50: 0a 20 20 20 20 20 20 74 68 65 20 52 42 55 20 76  .      the RBU v
5c60: 61 63 75 75 6d 20 69 73 20 66 69 6e 69 73 68 65  acuum is finishe
5c70: 64 2c 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  d, an error occu
5c80: 72 73 20 6f 72 20 74 68 65 20 61 70 70 6c 69 63  rs or the applic
5c90: 61 74 69 6f 6e 20 77 69 73 68 65 73 20 74 6f 0a  ation wishes to.
5ca0: 20 20 20 20 20 20 73 75 73 70 65 6e 64 20 74 68        suspend th
5cb0: 65 20 52 42 55 20 76 61 63 75 75 6d 2e 0a 0a 20  e RBU vacuum... 
5cc0: 20 20 20 20 20 3c 70 3e 20 45 61 63 68 20 63 61       <p> Each ca
5cd0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 72 62 75  ll to sqlite3rbu
5ce0: 5f 73 74 65 70 28 29 20 64 6f 65 73 20 61 20 73  _step() does a s
5cf0: 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 77  mall amount of w
5d00: 6f 72 6b 20 74 6f 77 61 72 64 73 0a 20 20 20 20  ork towards.    
5d10: 20 20 63 6f 6d 70 6c 65 74 69 6e 67 20 74 68 65    completing the
5d20: 20 76 61 63 75 75 6d 20 6f 70 65 72 61 74 69 6f   vacuum operatio
5d30: 6e 2e 20 44 65 70 65 6e 64 69 6e 67 20 6f 6e 20  n. Depending on 
5d40: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5d50: 64 61 74 61 62 61 73 65 2c 20 61 0a 20 20 20 20  database, a.    
5d60: 20 20 73 69 6e 67 6c 65 20 76 61 63 75 75 6d 20    single vacuum 
5d70: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 6f 75  may require thou
5d80: 73 61 6e 64 73 20 6f 66 20 63 61 6c 6c 73 20 74  sands of calls t
5d90: 6f 20 73 71 6c 69 74 65 33 72 62 75 5f 73 74 65  o sqlite3rbu_ste
5da0: 70 28 29 2e 0a 20 20 20 20 20 20 73 71 6c 69 74  p()..      sqlit
5db0: 65 33 72 62 75 5f 73 74 65 70 28 29 20 72 65 74  e3rbu_step() ret
5dc0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 44 4f 4e 45  urns SQLITE_DONE
5dd0: 20 69 66 20 74 68 65 20 76 61 63 75 75 6d 20 6f   if the vacuum o
5de0: 70 65 72 61 74 69 6f 6e 20 68 61 73 0a 20 20 20  peration has.   
5df0: 20 20 20 66 69 6e 69 73 68 65 64 2c 20 53 51 4c     finished, SQL
5e00: 49 54 45 5f 4f 4b 20 69 66 20 74 68 65 20 76 61  ITE_OK if the va
5e10: 63 75 75 6d 20 6f 70 65 72 61 74 69 6f 6e 20 68  cuum operation h
5e20: 61 73 20 6e 6f 74 20 66 69 6e 69 73 68 65 64 20  as not finished 
5e30: 62 75 74 20 6e 6f 20 65 72 72 6f 72 0a 20 20 20  but no error.   
5e40: 20 20 20 68 61 73 20 6f 63 63 75 72 72 65 64 2c     has occurred,
5e50: 20 61 6e 64 20 61 6e 20 53 51 4c 69 74 65 20 65   and an SQLite e
5e60: 72 72 6f 72 20 63 6f 64 65 20 69 66 20 61 6e 20  rror code if an 
5e70: 65 72 72 6f 72 20 69 73 20 65 6e 63 6f 75 6e 74  error is encount
5e80: 65 72 65 64 2e 20 49 66 0a 20 20 20 20 20 20 61  ered. If.      a
5e90: 6e 20 65 72 72 6f 72 20 64 6f 65 73 20 6f 63 63  n error does occ
5ea0: 75 72 2c 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ur, all subseque
5eb0: 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  nt calls to sqli
5ec0: 74 65 33 72 62 75 5f 73 74 65 70 28 29 20 69 6d  te3rbu_step() im
5ed0: 6d 65 64 69 61 74 65 6c 79 0a 20 20 20 20 20 20  mediately.      
5ee0: 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
5ef0: 65 72 72 6f 72 20 63 6f 64 65 2e 0a 0a 20 20 3c  error code...  <
5f00: 6c 69 3e 3c 70 3e 20 46 69 6e 61 6c 6c 79 2c 20  li><p> Finally, 
5f10: 73 71 6c 69 74 65 33 72 62 75 5f 63 6c 6f 73 65  sqlite3rbu_close
5f20: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  () is called to 
5f30: 63 6c 6f 73 65 20 74 68 65 20 52 42 55 20 68 61  close the RBU ha
5f40: 6e 64 6c 65 2e 20 49 66 20 74 68 65 0a 20 20 20  ndle. If the.   
5f50: 20 20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73     application s
5f60: 74 6f 70 70 65 64 20 63 61 6c 6c 69 6e 67 20 73  topped calling s
5f70: 71 6c 69 74 65 33 72 62 75 5f 73 74 65 70 28 29  qlite3rbu_step()
5f80: 20 62 65 66 6f 72 65 20 65 69 74 68 65 72 20 74   before either t
5f90: 68 65 20 76 61 63 75 75 6d 0a 20 20 20 20 20 20  he vacuum.      
5fa0: 66 69 6e 69 73 68 65 64 20 6f 72 20 61 6e 20 65  finished or an e
5fb0: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 2c 20 74  rror occurred, t
5fc0: 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20  he state of the 
5fd0: 76 61 63 75 75 6d 20 69 73 20 73 61 76 65 64 20  vacuum is saved 
5fe0: 69 6e 20 74 68 65 0a 20 20 20 20 20 20 73 74 61  in the.      sta
5ff0: 74 65 20 64 61 74 61 62 61 73 65 20 73 6f 20 74  te database so t
6000: 68 61 74 20 69 74 20 6d 61 79 20 62 65 20 72 65  hat it may be re
6010: 73 75 6d 65 64 20 6c 61 74 65 72 20 6f 6e 2e 0a  sumed later on..
6020: 0a 20 20 20 20 20 20 3c 70 3e 20 4c 69 6b 65 20  .      <p> Like 
6030: 73 71 6c 69 74 65 33 72 62 75 5f 73 74 65 70 28  sqlite3rbu_step(
6040: 29 2c 20 69 66 20 74 68 65 20 76 61 63 75 75 6d  ), if the vacuum
6050: 20 6f 70 65 72 61 74 69 6f 6e 20 68 61 73 20 66   operation has f
6060: 69 6e 69 73 68 65 64 2c 0a 20 20 20 20 20 20 73  inished,.      s
6070: 71 6c 69 74 65 33 72 62 75 5f 63 6c 6f 73 65 28  qlite3rbu_close(
6080: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
6090: 5f 44 4f 4e 45 2e 20 49 66 20 74 68 65 20 76 61  _DONE. If the va
60a0: 63 75 75 6d 20 68 61 73 20 6e 6f 74 20 66 69 6e  cuum has not fin
60b0: 69 73 68 65 64 0a 20 20 20 20 20 20 62 75 74 20  ished.      but 
60c0: 6e 6f 20 65 72 72 6f 72 20 68 61 73 20 6f 63 63  no error has occ
60d0: 75 72 72 65 64 2c 20 53 51 4c 49 54 45 5f 4f 4b  urred, SQLITE_OK
60e0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 72   is returned. Or
60f0: 2c 20 69 66 20 61 6e 20 65 72 72 6f 72 20 68 61  , if an error ha
6100: 73 0a 20 20 20 20 20 20 6f 63 63 75 72 72 65 64  s.      occurred
6110: 2c 20 61 6e 20 53 51 4c 69 74 65 20 65 72 72 6f  , an SQLite erro
6120: 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
6130: 65 64 2e 20 49 66 20 61 6e 20 65 72 72 6f 72 20  ed. If an error 
6140: 6f 63 63 75 72 72 65 64 20 61 73 20 70 61 72 74  occurred as part
6150: 0a 20 20 20 20 20 20 6f 66 20 61 20 70 72 69 6f  .      of a prio
6160: 72 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  r call to sqlite
6170: 33 72 62 75 5f 73 74 65 70 28 29 2c 20 73 71 6c  3rbu_step(), sql
6180: 69 74 65 33 72 62 75 5f 63 6c 6f 73 65 28 29 20  ite3rbu_close() 
6190: 72 65 74 75 72 6e 73 20 74 68 65 0a 20 20 20 20  returns the.    
61a0: 20 20 73 61 6d 65 20 65 72 72 6f 72 20 63 6f 64    same error cod
61b0: 65 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 54 68 65  e..</ol>..<p>The
61c0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 65 78 61 6d 70   following examp
61d0: 6c 65 20 63 6f 64 65 20 69 6c 6c 75 73 74 72 61  le code illustra
61e0: 74 65 73 20 74 68 65 20 74 65 63 68 6e 69 71 75  tes the techniqu
61f0: 65 73 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  es described abo
6200: 76 65 2e 20 20 0a 0a 3c 63 6f 64 65 62 6c 6f 63  ve.  ..<codebloc
6210: 6b 3e 0a 0a 3c 69 3e 2f 2a 3c 2f 69 3e 0a 3c 69  k>..<i>/*</i>.<i
6220: 3e 2a 2a 20 45 69 74 68 65 72 20 73 74 61 72 74  >** Either start
6230: 20 61 20 6e 65 77 20 52 42 55 20 76 61 63 75 75   a new RBU vacuu
6240: 6d 20 6f 72 20 72 65 73 75 6d 65 20 61 20 73 75  m or resume a su
6250: 73 70 65 6e 64 65 64 20 52 42 55 20 76 61 63 75  spended RBU vacu
6260: 75 6d 20 6f 6e 20 3c 2f 69 3e 0a 3c 69 3e 2a 2a  um on </i>.<i>**
6270: 20 64 61 74 61 62 61 73 65 20 7a 54 61 72 67 65   database zTarge
6280: 74 2e 20 52 65 74 75 72 6e 20 77 68 65 6e 20 65  t. Return when e
6290: 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f  ither an error o
62a0: 63 63 75 72 73 2c 20 74 68 65 20 52 42 55 20 3c  ccurs, the RBU <
62b0: 2f 69 3e 0a 3c 69 3e 2a 2a 20 76 61 63 75 75 6d  /i>.<i>** vacuum
62c0: 20 69 73 20 66 69 6e 69 73 68 65 64 20 6f 72 20   is finished or 
62d0: 77 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61  when the applica
62e0: 74 69 6f 6e 20 73 69 67 6e 61 6c 73 20 61 6e 20  tion signals an 
62f0: 69 6e 74 65 72 72 75 70 74 3c 2f 69 3e 0a 3c 69  interrupt</i>.<i
6300: 3e 2a 2a 20 28 63 6f 64 65 20 6e 6f 74 20 73 68  >** (code not sh
6310: 6f 77 6e 29 2e 3c 2f 69 3e 0a 3c 69 3e 2a 2a 3c  own).</i>.<i>**<
6320: 2f 69 3e 0a 3c 69 3e 2a 2a 20 49 66 20 74 68 65  /i>.<i>** If the
6330: 20 52 42 55 20 76 61 63 75 75 6d 20 69 73 20 63   RBU vacuum is c
6340: 6f 6d 70 6c 65 74 65 64 20 73 75 63 63 65 73 73  ompleted success
6350: 66 75 6c 6c 79 2c 20 72 65 74 75 72 6e 20 53 51  fully, return SQ
6360: 4c 49 54 45 5f 44 4f 4e 45 2e 3c 2f 69 3e 0a 3c  LITE_DONE.</i>.<
6370: 69 3e 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72  i>** If an error
6380: 20 6f 63 63 75 72 73 2c 20 72 65 74 75 72 6e 20   occurs, return 
6390: 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64  SQLite error cod
63a0: 65 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 61 70  e. Or, if the ap
63b0: 70 6c 69 63 61 74 69 6f 6e 3c 2f 69 3e 0a 3c 69  plication</i>.<i
63c0: 3e 2a 2a 20 73 69 67 6e 61 6c 73 20 61 6e 20 69  >** signals an i
63d0: 6e 74 65 72 72 75 70 74 2c 20 73 75 73 70 65 6e  nterrupt, suspen
63e0: 64 20 74 68 65 20 52 42 55 20 76 61 63 75 75 6d  d the RBU vacuum
63f0: 20 6f 70 65 72 61 74 69 6f 6e 20 73 6f 20 74 68   operation so th
6400: 61 74 20 69 74 3c 2f 69 3e 0a 3c 69 3e 2a 2a 20  at it</i>.<i>** 
6410: 6d 61 79 20 62 65 20 72 65 73 75 6d 65 64 20 62  may be resumed b
6420: 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
6430: 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63  all to this func
6440: 74 69 6f 6e 20 61 6e 64 20 72 65 74 75 72 6e 3c  tion and return<
6450: 2f 69 3e 0a 3c 69 3e 2a 2a 20 53 51 4c 49 54 45  /i>.<i>** SQLITE
6460: 5f 4f 4b 2e 3c 2f 69 3e 0a 3c 69 3e 2a 2a 3c 2f  _OK.</i>.<i>**</
6470: 69 3e 0a 3c 69 3e 2a 2a 20 54 68 69 73 20 66 75  i>.<i>** This fu
6480: 6e 63 74 69 6f 6e 20 75 73 65 73 20 74 68 65 20  nction uses the 
6490: 64 61 74 61 62 61 73 65 20 6e 61 6d 65 64 20 22  database named "
64a0: 26 6c 74 3b 7a 54 61 72 67 65 74 26 67 74 3b 2d  &lt;zTarget&gt;-
64b0: 76 61 63 75 75 6d 22 20 66 6f 72 3c 2f 69 3e 0a  vacuum" for</i>.
64c0: 3c 69 3e 2a 2a 20 74 68 65 20 73 74 61 74 65 20  <i>** the state 
64d0: 64 61 74 61 62 61 73 65 2c 20 77 68 65 72 65 20  database, where 
64e0: 26 6c 74 3b 7a 54 61 72 67 65 74 26 67 74 3b 20  &lt;zTarget&gt; 
64f0: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
6500: 68 65 20 64 61 74 61 62 61 73 65 20 3c 2f 69 3e  he database </i>
6510: 0a 3c 69 3e 2a 2a 20 62 65 69 6e 67 20 76 61 63  .<i>** being vac
6520: 75 75 6d 65 64 2e 3c 2f 69 3e 0a 3c 69 3e 2a 2f  uumed.</i>.<i>*/
6530: 3c 2f 69 3e 0a 69 6e 74 20 64 6f 5f 72 62 75 5f  </i>.int do_rbu_
6540: 76 61 63 75 75 6d 28 63 6f 6e 73 74 20 63 68 61  vacuum(const cha
6550: 72 20 2a 7a 54 61 72 67 65 74 29 7b 0a 20 20 69  r *zTarget){.  i
6560: 6e 74 20 72 63 3b 0a 20 20 63 68 61 72 20 2a 7a  nt rc;.  char *z
6570: 53 74 61 74 65 3b 20 20 20 20 20 20 20 20 20 20  State;          
6580: 20 20 20 20 20 20 20 20 20 3c 69 3e 2f 2a 20 4e           <i>/* N
6590: 61 6d 65 20 6f 66 20 73 74 61 74 65 20 64 61 74  ame of state dat
65a0: 61 62 61 73 65 20 2a 2f 3c 2f 69 3e 0a 20 20 73  abase */</i>.  s
65b0: 71 6c 69 74 65 33 72 62 75 20 2a 70 52 62 75 3b  qlite3rbu *pRbu;
65c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 3c                 <
65d0: 69 3e 2f 2a 20 52 42 55 20 76 61 63 75 75 6d 20  i>/* RBU vacuum 
65e0: 68 61 6e 64 6c 65 20 2a 2f 3c 2f 69 3e 0a 0a 20  handle */</i>.. 
65f0: 20 7a 53 74 61 74 65 20 3d 20 73 71 6c 69 74 65   zState = sqlite
6600: 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 2d 76 61  3_mprintf("%s-va
6610: 63 75 75 6d 22 2c 20 7a 54 61 72 67 65 74 29 3b  cuum", zTarget);
6620: 0a 20 20 69 66 28 20 7a 53 74 61 74 65 3d 3d 30  .  if( zState==0
6630: 20 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45   ) return SQLITE
6640: 5f 4e 4f 4d 45 4d 3b 0a 20 20 70 52 62 75 20 3d  _NOMEM;.  pRbu =
6650: 20 73 71 6c 69 74 65 33 72 62 75 5f 76 61 63 75   sqlite3rbu_vacu
6660: 75 6d 28 7a 54 61 72 67 65 74 2c 20 7a 53 74 61  um(zTarget, zSta
6670: 74 65 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 66  te);.  sqlite3_f
6680: 72 65 65 28 7a 53 74 61 74 65 29 3b 0a 0a 20 20  ree(zState);..  
6690: 69 66 28 20 70 52 62 75 20 29 7b 0a 20 20 20 20  if( pRbu ){.    
66a0: 73 71 6c 69 74 65 33 20 2a 64 62 54 61 72 67 65  sqlite3 *dbTarge
66b0: 74 20 3d 20 73 71 6c 69 74 65 33 72 62 75 5f 64  t = sqlite3rbu_d
66c0: 62 28 70 52 62 75 2c 20 30 29 3b 0a 20 20 20 20  b(pRbu, 0);.    
66d0: 73 71 6c 69 74 65 33 20 2a 64 62 53 74 61 74 65  sqlite3 *dbState
66e0: 20 3d 20 73 71 6c 69 74 65 33 72 62 75 5f 64 62   = sqlite3rbu_db
66f0: 28 70 52 62 75 2c 20 31 29 3b 0a 0a 20 20 20 20  (pRbu, 1);..    
6700: 3c 69 3e 2f 2a 20 41 6e 79 20 63 75 73 74 6f 6d  <i>/* Any custom
6710: 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
6720: 6e 63 65 73 20 75 73 65 64 20 62 79 20 74 68 65  nces used by the
6730: 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73 65   target database
6740: 20 6d 75 73 74 3c 2f 69 3e 0a 20 20 20 20 3c 69   must</i>.    <i
6750: 3e 2a 2a 20 62 65 20 72 65 67 69 73 74 65 72 65  >** be registere
6760: 64 20 77 69 74 68 20 62 6f 74 68 20 64 61 74 61  d with both data
6770: 62 61 73 65 20 68 61 6e 64 6c 65 73 20 68 65 72  base handles her
6780: 65 2e 20 20 2a 2f 3c 2f 69 3e 0a 0a 20 20 20 20  e.  */</i>..    
6790: 77 68 69 6c 65 28 20 73 71 6c 69 74 65 33 72 62  while( sqlite3rb
67a0: 75 5f 73 74 65 70 28 70 52 62 75 29 3d 3d 53 51  u_step(pRbu)==SQ
67b0: 4c 49 54 45 5f 4f 4b 20 29 7b 0a 20 20 20 20 20  LITE_OK ){.     
67c0: 20 69 66 28 20 3c 69 3e 26 6c 74 3b 61 70 70 6c   if( <i>&lt;appl
67d0: 69 63 61 74 69 6f 6e 20 68 61 73 20 73 69 67 6e  ication has sign
67e0: 61 6c 65 64 20 69 6e 74 65 72 72 75 70 74 26 67  aled interrupt&g
67f0: 74 3b 3c 2f 69 3e 20 29 20 62 72 65 61 6b 3b 0a  t;</i> ) break;.
6800: 20 20 20 20 7d 0a 20 20 7d 0a 20 20 72 63 20 3d      }.  }.  rc =
6810: 20 73 71 6c 69 74 65 33 72 62 75 5f 63 6c 6f 73   sqlite3rbu_clos
6820: 65 28 70 52 62 75 29 3b 0a 20 20 72 65 74 75 72  e(pRbu);.  retur
6830: 6e 20 72 63 3b 0a 7d 0a 0a 3c 2f 63 6f 64 65 62  n rc;.}..</codeb
6840: 6c 6f 63 6b 3e 0a                                lock>.