/ Hex Artifact Content
Login

Artifact 7b20abe9247d292429d00f0a5c237ff6e0dc0196:


0000: 2f 2a 0a 2a 2a 20 32 30 31 34 20 41 75 67 75 73  /*.** 2014 Augus
0010: 74 20 33 30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  t 30.**.** The a
0020: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
0030: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
0040: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
0050: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
0060: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
0070: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
0080: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
0090: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
00a0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
00b0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
00c0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
00d0: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
00e0: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
00f0: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
0100: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
0110: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
0120: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ***.**.** This f
0180: 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ile contains the
0190: 20 70 75 62 6c 69 63 20 69 6e 74 65 72 66 61 63   public interfac
01a0: 65 20 66 6f 72 20 74 68 65 20 4f 54 41 20 65 78  e for the OTA ex
01b0: 74 65 6e 73 69 6f 6e 2e 20 0a 2a 2f 0a 0a 2f 2a  tension. .*/../*
01c0: 0a 2a 2a 20 53 55 4d 4d 41 52 59 0a 2a 2a 0a 2a  .** SUMMARY.**.*
01d0: 2a 20 57 72 69 74 69 6e 67 20 61 20 74 72 61 6e  * Writing a tran
01e0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 69  saction containi
01f0: 6e 67 20 61 20 6c 61 72 67 65 20 6e 75 6d 62 65  ng a large numbe
0200: 72 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 73 20  r of operations 
0210: 6f 6e 20 0a 2a 2a 20 62 2d 74 72 65 65 20 69 6e  on .** b-tree in
0220: 64 65 78 65 73 20 74 68 61 74 20 61 72 65 20 63  dexes that are c
0230: 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6c 61 72 67  ollectively larg
0240: 65 72 20 74 68 61 6e 20 74 68 65 20 61 76 61 69  er than the avai
0250: 6c 61 62 6c 65 20 63 61 63 68 65 0a 2a 2a 20 6d  lable cache.** m
0260: 65 6d 6f 72 79 20 63 61 6e 20 62 65 20 76 65 72  emory can be ver
0270: 79 20 69 6e 65 66 66 69 63 69 65 6e 74 2e 20 0a  y inefficient. .
0280: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 62 6c 65  **.** The proble
0290: 6d 20 69 73 20 74 68 61 74 20 69 6e 20 6f 72 64  m is that in ord
02a0: 65 72 20 74 6f 20 75 70 64 61 74 65 20 61 20 62  er to update a b
02b0: 2d 74 72 65 65 2c 20 74 68 65 20 6c 65 61 66 20  -tree, the leaf 
02c0: 70 61 67 65 20 28 61 74 20 6c 65 61 73 74 29 0a  page (at least).
02d0: 2a 2a 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ** containing th
02e0: 65 20 65 6e 74 72 79 20 62 65 69 6e 67 20 69 6e  e entry being in
02f0: 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
0300: 64 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69  d must be modifi
0310: 65 64 2e 20 49 66 20 74 68 65 0a 2a 2a 20 77 6f  ed. If the.** wo
0320: 72 6b 69 6e 67 20 73 65 74 20 6f 66 20 6c 65 61  rking set of lea
0330: 76 65 73 20 69 73 20 6c 61 72 67 65 72 20 74 68  ves is larger th
0340: 61 6e 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  an the available
0350: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 2c 20 74   cache memory, t
0360: 68 65 6e 20 61 20 0a 2a 2a 20 73 69 6e 67 6c 65  hen a .** single
0370: 20 6c 65 61 66 20 74 68 61 74 20 69 73 20 6d 6f   leaf that is mo
0380: 64 69 66 69 65 64 20 6d 6f 72 65 20 74 68 61 6e  dified more than
0390: 20 6f 6e 63 65 20 61 73 20 70 61 72 74 20 6f 66   once as part of
03a0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
03b0: 20 0a 2a 2a 20 6d 61 79 20 62 65 20 6c 6f 61 64   .** may be load
03c0: 65 64 20 66 72 6f 6d 20 6f 72 20 77 72 69 74 74  ed from or writt
03d0: 65 6e 20 74 6f 20 74 68 65 20 70 65 72 73 69 73  en to the persis
03e0: 74 65 6e 74 20 6d 65 64 69 61 20 6d 6f 72 65 20  tent media more 
03f0: 74 68 61 6e 20 6f 6e 63 65 2e 20 0a 2a 2a 20 41  than once. .** A
0400: 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 62 65 63  dditionally, bec
0410: 61 75 73 65 20 74 68 65 20 69 6e 64 65 78 20 75  ause the index u
0420: 70 64 61 74 65 73 20 61 72 65 20 6c 69 6b 65 6c  pdates are likel
0430: 79 20 74 6f 20 62 65 20 61 70 70 6c 69 65 64 20  y to be applied 
0440: 69 6e 0a 2a 2a 20 72 61 6e 64 6f 6d 20 6f 72 64  in.** random ord
0450: 65 72 2c 20 61 63 63 65 73 73 20 74 6f 20 70 61  er, access to pa
0460: 67 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 64  ges within the d
0470: 61 74 61 62 73 65 20 69 73 20 61 6c 73 6f 20 6c  atabse is also l
0480: 69 6b 65 6c 79 20 74 6f 20 62 65 20 69 6e 20 0a  ikely to be in .
0490: 2a 2a 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72 2c  ** random order,
04a0: 20 77 68 69 63 68 20 69 73 20 69 74 73 65 6c 66   which is itself
04b0: 20 71 75 69 74 65 20 69 6e 65 66 66 69 63 69 65   quite inefficie
04c0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 77 61  nt..**.** One wa
04d0: 79 20 74 6f 20 69 6d 70 72 6f 76 65 20 74 68 65  y to improve the
04e0: 20 73 69 74 75 61 74 69 6f 6e 20 69 73 20 74 6f   situation is to
04f0: 20 73 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74   sort the operat
0500: 69 6f 6e 73 20 6f 6e 20 65 61 63 68 20 69 6e 64  ions on each ind
0510: 65 78 0a 2a 2a 20 62 79 20 69 6e 64 65 78 20 6b  ex.** by index k
0520: 65 79 20 62 65 66 6f 72 65 20 61 70 70 6c 79 69  ey before applyi
0530: 6e 67 20 74 68 65 6d 20 74 6f 20 74 68 65 20 62  ng them to the b
0540: 2d 74 72 65 65 2e 20 54 68 69 73 20 6c 65 61 64  -tree. This lead
0550: 73 20 74 6f 20 61 6e 20 49 4f 0a 2a 2a 20 70 61  s to an IO.** pa
0560: 74 74 65 72 6e 20 74 68 61 74 20 72 65 73 65 6d  ttern that resem
0570: 62 6c 65 73 20 61 20 73 69 6e 67 6c 65 20 6c 69  bles a single li
0580: 6e 65 61 72 20 73 63 61 6e 20 74 68 72 6f 75 67  near scan throug
0590: 68 20 74 68 65 20 69 6e 64 65 78 20 62 2d 74 72  h the index b-tr
05a0: 65 65 2c 0a 2a 2a 20 61 6e 64 20 61 6c 6c 20 62  ee,.** and all b
05b0: 75 74 20 67 75 61 72 61 6e 74 65 65 73 20 65 61  ut guarantees ea
05c0: 63 68 20 6d 6f 64 69 66 69 65 64 20 6c 65 61 66  ch modified leaf
05d0: 20 70 61 67 65 20 69 73 20 6c 6f 61 64 65 64 20   page is loaded 
05e0: 61 6e 64 20 73 74 6f 72 65 64 20 0a 2a 2a 20 65  and stored .** e
05f0: 78 61 63 74 6c 79 20 6f 6e 63 65 2e 20 53 51 4c  xactly once. SQL
0600: 69 74 65 20 75 73 65 73 20 74 68 69 73 20 74 72  ite uses this tr
0610: 69 63 6b 20 74 6f 20 69 6d 70 72 6f 76 65 20 74  ick to improve t
0620: 68 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  he performance o
0630: 66 0a 2a 2a 20 43 52 45 41 54 45 20 49 4e 44 45  f.** CREATE INDE
0640: 58 20 63 6f 6d 6d 61 6e 64 73 2e 20 54 68 69 73  X commands. This
0650: 20 65 78 74 65 6e 73 69 6f 6e 20 61 6c 6c 6f 77   extension allow
0660: 73 20 69 74 20 74 6f 20 62 65 20 75 73 65 64 20  s it to be used 
0670: 74 6f 20 69 6d 70 72 6f 76 65 0a 2a 2a 20 74 68  to improve.** th
0680: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 66  e performance of
0690: 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
06a0: 6f 6e 73 20 6f 6e 20 65 78 69 73 74 69 6e 67 20  ons on existing 
06b0: 64 61 74 61 62 61 73 65 73 2e 0a 2a 2a 0a 2a 2a  databases..**.**
06c0: 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 74   Additionally, t
06d0: 68 69 73 20 65 78 74 65 6e 73 69 6f 6e 20 61 6c  his extension al
06e0: 6c 6f 77 73 20 74 68 65 20 77 6f 72 6b 20 69 6e  lows the work in
06f0: 76 6f 6c 76 65 64 20 69 6e 20 77 72 69 74 69 6e  volved in writin
0700: 67 20 74 68 65 20 0a 2a 2a 20 6c 61 72 67 65 20  g the .** large 
0710: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 62  transaction to b
0720: 65 20 62 72 6f 6b 65 6e 20 64 6f 77 6e 20 69 6e  e broken down in
0730: 74 6f 20 73 75 62 2d 74 72 61 6e 73 61 63 74 69  to sub-transacti
0740: 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 0a 2a  ons performed .*
0750: 2a 20 73 65 71 75 65 6e 74 69 61 6c 6c 79 20 62  * sequentially b
0760: 79 20 73 65 70 61 72 61 74 65 20 70 72 6f 63 65  y separate proce
0770: 73 73 65 73 2e 20 54 68 69 73 20 69 73 20 75 73  sses. This is us
0780: 65 66 75 6c 20 69 66 20 74 68 65 20 73 79 73 74  eful if the syst
0790: 65 6d 20 63 61 6e 6e 6f 74 20 0a 2a 2a 20 67 75  em cannot .** gu
07a0: 61 72 61 6e 74 65 65 20 74 68 61 74 20 61 20 73  arantee that a s
07b0: 69 6e 67 6c 65 20 75 70 64 61 74 65 20 70 72 6f  ingle update pro
07c0: 63 65 73 73 20 6d 61 79 20 72 75 6e 20 66 6f 72  cess may run for
07d0: 20 6c 6f 6e 67 20 65 6e 6f 75 67 68 20 74 6f 20   long enough to 
07e0: 61 70 70 6c 79 20 0a 2a 2a 20 74 68 65 20 65 6e  apply .** the en
07f0: 74 69 72 65 20 75 70 64 61 74 65 2c 20 66 6f 72  tire update, for
0800: 20 65 78 61 6d 70 6c 65 20 62 65 63 61 75 73 65   example because
0810: 20 74 68 65 20 75 70 64 61 74 65 20 69 73 20 72   the update is r
0820: 75 6e 6e 69 6e 67 20 6f 6e 20 61 20 6d 6f 62 69  unning on a mobi
0830: 6c 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  le.** device tha
0840: 74 20 69 73 20 66 72 65 71 75 65 6e 74 6c 79 20  t is frequently 
0850: 72 65 62 6f 6f 74 65 64 2e 20 45 76 65 6e 20 61  rebooted. Even a
0860: 66 74 65 72 20 74 68 65 20 77 72 69 74 65 72 20  fter the writer 
0870: 70 72 6f 63 65 73 73 20 68 61 73 20 0a 2a 2a 20  process has .** 
0880: 63 6f 6d 6d 69 74 74 65 64 20 6f 6e 65 20 6f 72  committed one or
0890: 20 6d 6f 72 65 20 73 75 62 2d 74 72 61 6e 73 61   more sub-transa
08a0: 63 74 69 6f 6e 73 2c 20 6f 74 68 65 72 20 64 61  ctions, other da
08b0: 74 61 62 61 73 65 20 63 6c 69 65 6e 74 73 20 63  tabase clients c
08c0: 6f 6e 74 69 6e 75 65 0a 2a 2a 20 74 6f 20 72 65  ontinue.** to re
08d0: 61 64 20 66 72 6f 6d 20 74 68 65 20 6f 72 69 67  ad from the orig
08e0: 69 6e 61 6c 20 64 61 74 61 62 61 73 65 20 73 6e  inal database sn
08f0: 61 70 73 68 6f 74 2e 20 49 6e 20 6f 74 68 65 72  apshot. In other
0900: 20 77 6f 72 64 73 2c 20 70 61 72 74 69 61 6c 6c   words, partiall
0910: 79 20 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 72  y .** applied tr
0920: 61 6e 73 61 63 74 69 6f 6e 73 20 61 72 65 20 6e  ansactions are n
0930: 6f 74 20 76 69 73 69 62 6c 65 20 74 6f 20 6f 74  ot visible to ot
0940: 68 65 72 20 63 6c 69 65 6e 74 73 2e 20 0a 2a 2a  her clients. .**
0950: 0a 2a 2a 20 22 4f 54 41 22 20 73 74 61 6e 64 73  .** "OTA" stands
0960: 20 66 6f 72 20 22 4f 76 65 72 20 54 68 65 20 41   for "Over The A
0970: 69 72 22 20 75 70 64 61 74 65 2e 20 41 73 20 69  ir" update. As i
0980: 6e 20 61 20 6c 61 72 67 65 20 64 61 74 61 62 61  n a large databa
0990: 73 65 20 75 70 64 61 74 65 0a 2a 2a 20 74 72 61  se update.** tra
09a0: 6e 73 6d 69 74 74 65 64 20 76 69 61 20 61 20 77  nsmitted via a w
09b0: 69 72 65 6c 65 73 73 20 6e 65 74 77 6f 72 6b 20  ireless network 
09c0: 74 6f 20 61 20 6d 6f 62 69 6c 65 20 64 65 76 69  to a mobile devi
09d0: 63 65 2e 20 41 20 74 72 61 6e 73 61 63 74 69 6f  ce. A transactio
09e0: 6e 0a 2a 2a 20 61 70 70 6c 69 65 64 20 75 73 69  n.** applied usi
09f0: 6e 67 20 74 68 69 73 20 65 78 74 65 6e 73 69 6f  ng this extensio
0a00: 6e 20 69 73 20 68 65 6e 63 65 20 72 65 66 65 72  n is hence refer
0a10: 65 64 20 74 6f 20 61 73 20 61 6e 20 22 4f 54 41  ed to as an "OTA
0a20: 20 75 70 64 61 74 65 22 2e 0a 2a 2a 0a 2a 2a 0a   update"..**.**.
0a30: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 0a 2a  ** LIMITATIONS.*
0a40: 2a 0a 2a 2a 20 41 6e 20 22 4f 54 41 20 75 70 64  *.** An "OTA upd
0a50: 61 74 65 22 20 74 72 61 6e 73 61 63 74 69 6f 6e  ate" transaction
0a60: 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 74   is subject to t
0a70: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6c 69 6d  he following lim
0a80: 69 74 61 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  itations:.**.** 
0a90: 20 20 2a 20 54 68 65 20 74 72 61 6e 73 61 63 74    * The transact
0aa0: 69 6f 6e 20 6d 75 73 74 20 63 6f 6e 73 69 73 74  ion must consist
0ab0: 20 6f 66 20 49 4e 53 45 52 54 2c 20 55 50 44 41   of INSERT, UPDA
0ac0: 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 6f 70  TE and DELETE op
0ad0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 20  erations.**     
0ae0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 20 20 2a 20  only..**.**   * 
0af0: 49 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74  INSERT statement
0b00: 73 20 6d 61 79 20 6e 6f 74 20 75 73 65 20 61 6e  s may not use an
0b10: 79 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 73  y default values
0b20: 2e 0a 2a 2a 0a 2a 2a 20 20 20 2a 20 55 50 44 41  ..**.**   * UPDA
0b30: 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 73 74  TE and DELETE st
0b40: 61 74 65 6d 65 6e 74 73 20 6d 75 73 74 20 69 64  atements must id
0b50: 65 6e 74 69 66 79 20 74 68 65 69 72 20 74 61 72  entify their tar
0b60: 67 65 74 20 72 6f 77 73 20 62 79 0a 2a 2a 20 20  get rows by.**  
0b70: 20 20 20 72 65 61 6c 20 50 52 49 4d 41 52 59 20     real PRIMARY 
0b80: 4b 45 59 20 76 61 6c 75 65 73 20 2d 20 69 2e 65  KEY values - i.e
0b90: 2e 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  . INTEGER PRIMAR
0ba0: 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 73 20 6f 72  Y KEY columns or
0bb0: 20 0a 2a 2a 20 20 20 20 20 62 79 20 74 68 65 20   .**     by the 
0bc0: 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75  PRIMARY KEY colu
0bd0: 6d 6e 73 20 6f 66 20 57 49 54 48 4f 55 54 20 52  mns of WITHOUT R
0be0: 4f 57 49 44 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a  OWID tables..**.
0bf0: 2a 2a 20 20 20 2a 20 55 50 44 41 54 45 20 73 74  **   * UPDATE st
0c00: 61 74 65 6d 65 6e 74 73 20 6d 61 79 20 6e 6f 74  atements may not
0c10: 20 6d 6f 64 69 66 79 20 72 65 61 6c 20 50 52 49   modify real PRI
0c20: 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 73  MARY KEY columns
0c30: 2e 0a 2a 2a 0a 2a 2a 20 20 20 2a 20 4e 6f 20 74  ..**.**   * No t
0c40: 72 69 67 67 65 72 73 20 77 69 6c 6c 20 62 65 20  riggers will be 
0c50: 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 20 20 2a  fired..**.**   *
0c60: 20 4e 6f 20 66 6f 72 65 69 67 6e 20 6b 65 79 20   No foreign key 
0c70: 76 69 6f 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  violations are d
0c80: 65 74 65 63 74 65 64 20 6f 72 20 72 65 70 6f 72  etected or repor
0c90: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 20 20 2a 20 4e  ted..**.**   * N
0ca0: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 68 61 6e  o constraint han
0cb0: 64 6c 69 6e 67 20 6d 6f 64 65 20 65 78 63 65 70  dling mode excep
0cc0: 74 20 66 6f 72 20 22 4f 52 20 52 4f 4c 4c 42 41  t for "OR ROLLBA
0cd0: 43 4b 22 20 69 73 20 73 75 70 70 6f 72 74 65 64  CK" is supported
0ce0: 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 50 52 45 50 41  ..**.**.** PREPA
0cf0: 52 41 54 49 4f 4e 0a 2a 2a 0a 2a 2a 20 41 6e 20  RATION.**.** An 
0d00: 22 4f 54 41 20 75 70 64 61 74 65 22 20 69 73 20  "OTA update" is 
0d10: 73 74 6f 72 65 64 20 61 73 20 61 20 73 65 70 61  stored as a sepa
0d20: 72 61 74 65 20 53 51 4c 69 74 65 20 64 61 74 61  rate SQLite data
0d30: 62 61 73 65 2e 20 41 20 64 61 74 61 62 61 73 65  base. A database
0d40: 0a 2a 2a 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  .** containing a
0d50: 6e 20 4f 54 41 20 75 70 64 61 74 65 20 69 73 20  n OTA update is 
0d60: 61 6e 20 22 4f 54 41 20 64 61 74 61 62 61 73 65  an "OTA database
0d70: 22 2e 20 46 6f 72 20 65 61 63 68 20 74 61 62 6c  ". For each tabl
0d80: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 74 61 72  e in the .** tar
0d90: 67 65 74 20 64 61 74 61 62 61 73 65 20 74 6f 20  get database to 
0da0: 62 65 20 75 70 64 61 74 65 64 2c 20 74 68 65 20  be updated, the 
0db0: 4f 54 41 20 64 61 74 61 62 61 73 65 20 73 68 6f  OTA database sho
0dc0: 75 6c 64 20 63 6f 6e 74 61 69 6e 20 61 20 74 61  uld contain a ta
0dd0: 62 6c 65 0a 2a 2a 20 6e 61 6d 65 64 20 22 64 61  ble.** named "da
0de0: 74 61 5f 3c 74 61 72 67 65 74 20 6e 61 6d 65 3e  ta_<target name>
0df0: 22 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  " containing the
0e00: 20 73 61 6d 65 20 73 65 74 20 6f 66 20 63 6f 6c   same set of col
0e10: 75 6d 6e 73 20 61 73 20 74 68 65 0a 2a 2a 20 74  umns as the.** t
0e20: 61 72 67 65 74 20 74 61 62 6c 65 2c 20 61 6e 64  arget table, and
0e30: 20 6f 6e 65 20 6d 6f 72 65 20 2d 20 22 6f 74 61   one more - "ota
0e40: 5f 63 6f 6e 74 72 6f 6c 22 2e 20 54 68 65 20 64  _control". The d
0e50: 61 74 61 5f 25 20 74 61 62 6c 65 20 73 68 6f 75  ata_% table shou
0e60: 6c 64 20 0a 2a 2a 20 68 61 76 65 20 6e 6f 20 50  ld .** have no P
0e70: 52 49 4d 41 52 59 20 4b 45 59 20 6f 72 20 55 4e  RIMARY KEY or UN
0e80: 49 51 55 45 20 63 6f 6e 73 74 72 61 69 6e 74 73  IQUE constraints
0e90: 2c 20 62 75 74 20 65 61 63 68 20 63 6f 6c 75 6d  , but each colum
0ea0: 6e 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  n should have.**
0eb0: 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 61   the same type a
0ec0: 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
0ed0: 69 6e 67 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  ing column in th
0ee0: 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73  e target databas
0ef0: 65 2e 0a 2a 2a 20 54 68 65 20 22 6f 74 61 5f 63  e..** The "ota_c
0f00: 6f 6e 74 72 6f 6c 22 20 63 6f 6c 75 6d 6e 20 73  ontrol" column s
0f10: 68 6f 75 6c 64 20 68 61 76 65 20 6e 6f 20 74 79  hould have no ty
0f20: 70 65 20 61 74 20 61 6c 6c 2e 20 46 6f 72 20 65  pe at all. For e
0f30: 78 61 6d 70 6c 65 2c 20 69 66 0a 2a 2a 20 74 68  xample, if.** th
0f40: 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73  e target databas
0f50: 65 20 63 6f 6e 74 61 69 6e 73 3a 0a 2a 2a 0a 2a  e contains:.**.*
0f60: 2a 20 20 20 43 52 45 41 54 45 20 54 41 42 4c 45  *   CREATE TABLE
0f70: 20 74 31 28 61 20 49 4e 54 45 47 45 52 20 50 52   t1(a INTEGER PR
0f80: 49 4d 41 52 59 20 4b 45 59 2c 20 62 20 54 45 58  IMARY KEY, b TEX
0f90: 54 2c 20 63 20 55 4e 49 51 55 45 29 3b 0a 2a 2a  T, c UNIQUE);.**
0fa0: 0a 2a 2a 20 54 68 65 6e 20 74 68 65 20 4f 54 41  .** Then the OTA
0fb0: 20 64 61 74 61 62 61 73 65 20 73 68 6f 75 6c 64   database should
0fc0: 20 63 6f 6e 74 61 69 6e 3a 0a 2a 2a 0a 2a 2a 20   contain:.**.** 
0fd0: 20 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 64    CREATE TABLE d
0fe0: 61 74 61 5f 74 31 28 61 20 49 4e 54 45 47 45 52  ata_t1(a INTEGER
0ff0: 2c 20 62 20 54 45 58 54 2c 20 63 2c 20 6f 74 61  , b TEXT, c, ota
1000: 5f 63 6f 6e 74 72 6f 6c 29 3b 0a 2a 2a 0a 2a 2a  _control);.**.**
1010: 20 54 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   The order of th
1020: 65 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  e columns in the
1030: 20 64 61 74 61 5f 25 20 74 61 62 6c 65 20 64 6f   data_% table do
1040: 65 73 20 6e 6f 74 20 6d 61 74 74 65 72 2e 0a 2a  es not matter..*
1050: 2a 0a 2a 2a 20 46 6f 72 20 65 61 63 68 20 72 6f  *.** For each ro
1060: 77 20 74 6f 20 49 4e 53 45 52 54 20 69 6e 74 6f  w to INSERT into
1070: 20 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61   the target data
1080: 62 61 73 65 20 61 73 20 70 61 72 74 20 6f 66 20  base as part of 
1090: 74 68 65 20 4f 54 41 20 0a 2a 2a 20 75 70 64 61  the OTA .** upda
10a0: 74 65 2c 20 74 68 65 20 63 6f 72 72 65 73 70 6f  te, the correspo
10b0: 6e 64 69 6e 67 20 64 61 74 61 5f 25 20 74 61 62  nding data_% tab
10c0: 6c 65 20 73 68 6f 75 6c 64 20 63 6f 6e 74 61 69  le should contai
10d0: 6e 20 61 20 73 69 6e 67 6c 65 20 72 65 63 6f 72  n a single recor
10e0: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 6f  d.** with the "o
10f0: 74 61 5f 63 6f 6e 74 72 6f 6c 22 20 63 6f 6c 75  ta_control" colu
1100: 6d 6e 20 73 65 74 20 74 6f 20 63 6f 6e 74 61 69  mn set to contai
1110: 6e 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  n integer value 
1120: 30 2e 20 54 68 65 0a 2a 2a 20 6f 74 68 65 72 20  0. The.** other 
1130: 63 6f 6c 75 6d 6e 73 20 73 68 6f 75 6c 64 20 62  columns should b
1140: 65 20 73 65 74 20 74 6f 20 74 68 65 20 76 61 6c  e set to the val
1150: 75 65 73 20 74 68 61 74 20 6d 61 6b 65 20 75 70  ues that make up
1160: 20 74 68 65 20 6e 65 77 20 72 65 63 6f 72 64 20   the new record 
1170: 0a 2a 2a 20 74 6f 20 69 6e 73 65 72 74 2e 20 0a  .** to insert. .
1180: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 74 61 72  **.** If the tar
1190: 67 65 74 20 64 61 74 61 62 61 73 65 20 74 61 62  get database tab
11a0: 6c 65 20 68 61 73 20 61 6e 20 49 4e 54 45 47 45  le has an INTEGE
11b0: 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 61 6e  R PRIMARY KEY an
11c0: 64 20 74 68 65 72 65 20 61 72 65 0a 2a 2a 20 6f  d there are.** o
11d0: 6e 65 20 6f 72 20 6d 6f 72 65 20 61 75 78 69 6c  ne or more auxil
11e0: 69 61 72 79 20 69 6e 64 65 78 65 73 2c 20 69 74  iary indexes, it
11f0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
1200: 20 74 6f 20 69 6e 73 65 72 74 20 61 20 4e 55 4c   to insert a NUL
1210: 4c 20 76 61 6c 75 65 0a 2a 2a 20 69 6e 74 6f 20  L value.** into 
1220: 74 68 65 20 49 50 4b 20 63 6f 6c 75 6d 6e 2e 20  the IPK column. 
1230: 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 6f  Attempting to do
1240: 20 73 6f 20 72 65 73 75 6c 74 73 20 69 6e 20 61   so results in a
1250: 6e 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  n SQLITE_MISMATC
1260: 48 0a 2a 2a 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  H.** error..**.*
1270: 2a 20 46 6f 72 20 65 61 63 68 20 72 6f 77 20 74  * For each row t
1280: 6f 20 44 45 4c 45 54 45 20 66 72 6f 6d 20 74 68  o DELETE from th
1290: 65 20 74 61 72 67 65 74 20 64 61 74 61 62 61 73  e target databas
12a0: 65 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  e as part of the
12b0: 20 4f 54 41 20 0a 2a 2a 20 75 70 64 61 74 65 2c   OTA .** update,
12c0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
12d0: 6e 67 20 64 61 74 61 5f 25 20 74 61 62 6c 65 20  ng data_% table 
12e0: 73 68 6f 75 6c 64 20 63 6f 6e 74 61 69 6e 20 61  should contain a
12f0: 20 73 69 6e 67 6c 65 20 72 65 63 6f 72 64 0a 2a   single record.*
1300: 2a 20 77 69 74 68 20 74 68 65 20 22 6f 74 61 5f  * with the "ota_
1310: 63 6f 6e 74 72 6f 6c 22 20 63 6f 6c 75 6d 6e 20  control" column 
1320: 73 65 74 20 74 6f 20 63 6f 6e 74 61 69 6e 20 69  set to contain i
1330: 6e 74 65 67 65 72 20 76 61 6c 75 65 20 31 2e 20  nteger value 1. 
1340: 54 68 65 0a 2a 2a 20 72 65 61 6c 20 70 72 69 6d  The.** real prim
1350: 61 72 79 20 6b 65 79 20 76 61 6c 75 65 73 20 6f  ary key values o
1360: 66 20 74 68 65 20 72 6f 77 20 74 6f 20 64 65 6c  f the row to del
1370: 65 74 65 20 73 68 6f 75 6c 64 20 62 65 20 73 74  ete should be st
1380: 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  ored in the.** c
1390: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 63 6f 6c  orresponding col
13a0: 75 6d 6e 73 20 6f 66 20 74 68 65 20 64 61 74 61  umns of the data
13b0: 5f 25 20 74 61 62 6c 65 2e 20 54 68 65 20 76 61  _% table. The va
13c0: 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 74  lues stored in t
13d0: 68 65 0a 2a 2a 20 6f 74 68 65 72 20 63 6f 6c 75  he.** other colu
13e0: 6d 6e 73 20 61 72 65 20 6e 6f 74 20 75 73 65 64  mns are not used
13f0: 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 61 63 68  ..**.** For each
1400: 20 72 6f 77 20 74 6f 20 55 50 44 41 54 45 20 66   row to UPDATE f
1410: 72 6f 6d 20 74 68 65 20 74 61 72 67 65 74 20 64  rom the target d
1420: 61 74 61 62 61 73 65 20 61 73 20 70 61 72 74 20  atabase as part 
1430: 6f 66 20 74 68 65 20 4f 54 41 20 0a 2a 2a 20 75  of the OTA .** u
1440: 70 64 61 74 65 2c 20 74 68 65 20 63 6f 72 72 65  pdate, the corre
1450: 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 5f 25 20  sponding data_% 
1460: 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 63 6f 6e  table should con
1470: 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 20 72 65  tain a single re
1480: 63 6f 72 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  cord.** with the
1490: 20 22 6f 74 61 5f 63 6f 6e 74 72 6f 6c 22 20 63   "ota_control" c
14a0: 6f 6c 75 6d 6e 20 73 65 74 20 74 6f 20 63 6f 6e  olumn set to con
14b0: 74 61 69 6e 20 61 20 76 61 6c 75 65 20 6f 66 20  tain a value of 
14c0: 74 79 70 65 20 74 65 78 74 2e 0a 2a 2a 20 54 68  type text..** Th
14d0: 65 20 72 65 61 6c 20 70 72 69 6d 61 72 79 20 6b  e real primary k
14e0: 65 79 20 76 61 6c 75 65 73 20 69 64 65 6e 74 69  ey values identi
14f0: 66 79 69 6e 67 20 74 68 65 20 72 6f 77 20 74 6f  fying the row to
1500: 20 75 70 64 61 74 65 20 73 68 6f 75 6c 64 20 62   update should b
1510: 65 20 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20  e .** stored in 
1520: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
1530: 67 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 74 68 65  g columns of the
1540: 20 64 61 74 61 5f 25 20 74 61 62 6c 65 20 72 6f   data_% table ro
1550: 77 2c 20 61 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  w, as should.** 
1560: 74 68 65 20 6e 65 77 20 76 61 6c 75 65 73 20 6f  the new values o
1570: 66 20 61 6c 6c 20 63 6f 6c 75 6d 6e 73 20 62 65  f all columns be
1580: 69 6e 67 20 75 70 64 61 74 65 2e 20 54 68 65 20  ing update. The 
1590: 74 65 78 74 20 76 61 6c 75 65 20 69 6e 20 74 68  text value in th
15a0: 65 20 0a 2a 2a 20 22 6f 74 61 5f 63 6f 6e 74 72  e .** "ota_contr
15b0: 6f 6c 22 20 63 6f 6c 75 6d 6e 20 6d 75 73 74 20  ol" column must 
15c0: 63 6f 6e 74 61 69 6e 20 74 68 65 20 73 61 6d 65  contain the same
15d0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
15e0: 63 74 65 72 73 20 61 73 0a 2a 2a 20 74 68 65 72  cters as.** ther
15f0: 65 20 61 72 65 20 63 6f 6c 75 6d 6e 20 69 6e 20  e are column in 
1600: 74 68 65 20 74 61 72 67 65 74 20 64 61 74 61 62  the target datab
1610: 61 73 65 20 74 61 62 6c 65 2c 20 61 6e 64 20 6d  ase table, and m
1620: 75 73 74 20 63 6f 6e 73 69 73 74 20 65 6e 74 69  ust consist enti
1630: 72 65 6c 79 0a 2a 2a 20 6f 66 20 22 78 22 20 61  rely.** of "x" a
1640: 6e 64 20 22 2e 22 20 63 68 61 72 61 63 74 65 72  nd "." character
1650: 73 2e 20 46 6f 72 20 65 61 63 68 20 63 6f 6c 75  s. For each colu
1660: 6d 6e 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  mn that is being
1670: 20 75 70 64 61 74 65 64 2c 0a 2a 2a 20 74 68 65   updated,.** the
1680: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 63   corresponding c
1690: 68 61 72 61 63 74 65 72 20 69 73 20 73 65 74 20  haracter is set 
16a0: 74 6f 20 22 78 22 2e 20 46 6f 72 20 74 68 6f 73  to "x". For thos
16b0: 65 20 74 68 61 74 20 72 65 6d 61 69 6e 20 61 73  e that remain as
16c0: 0a 2a 2a 20 74 68 65 79 20 61 72 65 2c 20 74 68  .** they are, th
16d0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
16e0: 63 68 61 72 61 63 74 65 72 20 6f 66 20 74 68 65  character of the
16f0: 20 6f 74 61 5f 63 6f 6e 74 72 6f 6c 20 76 61 6c   ota_control val
1700: 75 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  ue should.** be 
1710: 73 65 74 20 74 6f 20 22 2e 22 2e 20 46 6f 72 20  set to ".". For 
1720: 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
1730: 68 65 20 74 61 62 6c 65 73 20 61 62 6f 76 65 2c  he tables above,
1740: 20 74 68 65 20 75 70 64 61 74 65 20 0a 2a 2a 20   the update .** 
1750: 73 74 61 74 65 6d 65 6e 74 3a 0a 2a 2a 0a 2a 2a  statement:.**.**
1760: 20 20 20 55 50 44 41 54 45 20 74 31 20 53 45 54     UPDATE t1 SET
1770: 20 63 20 3d 20 27 75 73 61 27 20 57 48 45 52 45   c = 'usa' WHERE
1780: 20 61 20 3d 20 34 3b 0a 2a 2a 0a 2a 2a 20 69 73   a = 4;.**.** is
1790: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
17a0: 74 68 65 20 64 61 74 61 5f 74 31 20 72 6f 77 20  the data_t1 row 
17b0: 63 72 65 61 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a  created by:.**.*
17c0: 2a 20 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  *   INSERT INTO 
17d0: 64 61 74 61 5f 74 31 28 61 2c 20 62 2c 20 63 2c  data_t1(a, b, c,
17e0: 20 6f 74 61 5f 63 6f 6e 74 72 6f 6c 29 20 56 41   ota_control) VA
17f0: 4c 55 45 53 28 34 2c 20 4e 55 4c 4c 2c 20 27 75  LUES(4, NULL, 'u
1800: 73 61 27 2c 20 27 2e 2e 78 27 29 3b 0a 2a 2a 0a  sa', '..x');.**.
1810: 2a 2a 0a 2a 2a 20 55 53 41 47 45 0a 2a 2a 0a 2a  **.** USAGE.**.*
1820: 2a 20 54 68 65 20 41 50 49 20 64 65 63 6c 61 72  * The API declar
1830: 65 64 20 62 65 6c 6f 77 20 61 6c 6c 6f 77 73 20  ed below allows 
1840: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
1850: 6f 20 61 70 70 6c 79 20 61 6e 20 4f 54 41 20 75  o apply an OTA u
1860: 70 64 61 74 65 20 0a 2a 2a 20 73 74 6f 72 65 64  pdate .** stored
1870: 20 6f 6e 20 64 69 73 6b 20 74 6f 20 61 6e 20 65   on disk to an e
1880: 78 69 73 74 69 6e 67 20 74 61 72 67 65 74 20 64  xisting target d
1890: 61 74 61 62 61 73 65 2e 20 45 73 73 65 6e 74 69  atabase. Essenti
18a0: 61 6c 6c 79 2c 20 74 68 65 20 0a 2a 2a 20 61 70  ally, the .** ap
18b0: 70 6c 69 63 61 74 69 6f 6e 3a 0a 2a 2a 0a 2a 2a  plication:.**.**
18c0: 20 20 20 20 20 31 29 20 4f 70 65 6e 73 20 61 6e       1) Opens an
18d0: 20 4f 54 41 20 68 61 6e 64 6c 65 20 75 73 69 6e   OTA handle usin
18e0: 67 20 74 68 65 20 73 71 6c 69 74 65 33 6f 74 61  g the sqlite3ota
18f0: 5f 6f 70 65 6e 28 29 20 66 75 6e 63 74 69 6f 6e  _open() function
1900: 2e 0a 2a 2a 0a 2a 2a 20 20 20 20 20 32 29 20 43  ..**.**     2) C
1910: 61 6c 6c 73 20 74 68 65 20 73 71 6c 69 74 65 33  alls the sqlite3
1920: 6f 74 61 5f 73 74 65 70 28 29 20 66 75 6e 63 74  ota_step() funct
1930: 69 6f 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ion one or more 
1940: 74 69 6d 65 73 20 6f 6e 0a 2a 2a 20 20 20 20 20  times on.**     
1950: 20 20 20 74 68 65 20 6e 65 77 20 68 61 6e 64 6c     the new handl
1960: 65 2e 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  e. Each call to 
1970: 73 71 6c 69 74 65 33 6f 74 61 5f 73 74 65 70 28  sqlite3ota_step(
1980: 29 20 70 65 72 66 6f 72 6d 73 20 61 20 73 69 6e  ) performs a sin
1990: 67 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 62 2d  gle.**        b-
19a0: 74 72 65 65 20 6f 70 65 72 61 74 69 6f 6e 2c 20  tree operation, 
19b0: 73 6f 20 74 68 6f 75 73 61 6e 64 73 20 6f 66 20  so thousands of 
19c0: 63 61 6c 6c 73 20 6d 61 79 20 62 65 20 72 65 71  calls may be req
19d0: 75 69 72 65 64 20 74 6f 20 61 70 70 6c 79 20 0a  uired to apply .
19e0: 2a 2a 20 20 20 20 20 20 20 20 61 20 63 6f 6d 70  **        a comp
19f0: 6c 65 74 65 20 75 70 64 61 74 65 2e 0a 2a 2a 0a  lete update..**.
1a00: 2a 2a 20 20 20 20 20 33 29 20 43 61 6c 6c 73 20  **     3) Calls 
1a10: 73 71 6c 69 74 65 33 6f 74 61 5f 63 6c 6f 73 65  sqlite3ota_close
1a20: 28 29 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  () to close the 
1a30: 4f 54 41 20 75 70 64 61 74 65 20 68 61 6e 64 6c  OTA update handl
1a40: 65 2e 20 49 66 0a 2a 2a 20 20 20 20 20 20 20 20  e. If.**        
1a50: 73 71 6c 69 74 65 33 6f 74 61 5f 73 74 65 70 28  sqlite3ota_step(
1a60: 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ) has been calle
1a70: 64 20 65 6e 6f 75 67 68 20 74 69 6d 65 73 20 74  d enough times t
1a80: 6f 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  o completely.** 
1a90: 20 20 20 20 20 20 20 61 70 70 6c 79 20 74 68 65         apply the
1aa0: 20 75 70 64 61 74 65 20 74 6f 20 74 68 65 20 74   update to the t
1ab0: 61 72 67 65 74 20 64 61 74 61 62 61 73 65 2c 20  arget database, 
1ac0: 74 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 6d 69  then it is commi
1ad0: 74 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 61  tted.**        a
1ae0: 6e 64 20 6d 61 64 65 20 76 69 73 69 62 6c 65 20  nd made visible 
1af0: 74 6f 20 6f 74 68 65 72 20 64 61 74 61 62 61 73  to other databas
1b00: 65 20 63 6c 69 65 6e 74 73 20 61 74 20 74 68 69  e clients at thi
1b10: 73 20 70 6f 69 6e 74 2e 20 0a 2a 2a 20 20 20 20  s point. .**    
1b20: 20 20 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74      Otherwise, t
1b30: 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20  he state of the 
1b40: 4f 54 41 20 75 70 64 61 74 65 20 61 70 70 6c 69  OTA update appli
1b50: 63 61 74 69 6f 6e 20 69 73 20 73 61 76 65 64 0a  cation is saved.
1b60: 2a 2a 20 20 20 20 20 20 20 20 69 6e 20 74 68 65  **        in the
1b70: 20 4f 54 41 20 64 61 74 61 62 61 73 65 20 66 6f   OTA database fo
1b80: 72 20 6c 61 74 65 72 20 72 65 73 75 6d 70 74 69  r later resumpti
1b90: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 63 6f  on..**.** See co
1ba0: 6d 6d 65 6e 74 73 20 62 65 6c 6f 77 20 66 6f 72  mments below for
1bb0: 20 6d 6f 72 65 20 64 65 74 61 69 6c 20 6f 6e 20   more detail on 
1bc0: 41 50 49 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  APIs..**.** If a
1bd0: 6e 20 75 70 64 61 74 65 20 69 73 20 6f 6e 6c 79  n update is only
1be0: 20 70 61 72 74 69 61 6c 6c 79 20 61 70 70 6c 69   partially appli
1bf0: 65 64 20 74 6f 20 74 68 65 20 74 61 72 67 65 74  ed to the target
1c00: 20 64 61 74 61 62 61 73 65 20 62 79 20 74 68 65   database by the
1c10: 0a 2a 2a 20 74 69 6d 65 20 73 71 6c 69 74 65 33  .** time sqlite3
1c20: 6f 74 61 5f 63 6c 6f 73 65 28 29 20 69 73 20 63  ota_close() is c
1c30: 61 6c 6c 65 64 2c 20 76 61 72 69 6f 75 73 20 73  alled, various s
1c40: 74 61 74 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  tate information
1c50: 20 69 73 20 73 61 76 65 64 20 0a 2a 2a 20 77 69   is saved .** wi
1c60: 74 68 69 6e 20 74 68 65 20 4f 54 41 20 64 61 74  thin the OTA dat
1c70: 61 62 61 73 65 2e 20 54 68 69 73 20 61 6c 6c 6f  abase. This allo
1c80: 77 73 20 73 75 62 73 65 71 75 65 6e 74 20 70 72  ws subsequent pr
1c90: 6f 63 65 73 73 65 73 20 74 6f 20 61 75 74 6f 6d  ocesses to autom
1ca0: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 73 75  atically.** resu
1cb0: 6d 65 20 74 68 65 20 4f 54 41 20 75 70 64 61 74  me the OTA updat
1cc0: 65 20 66 72 6f 6d 20 77 68 65 72 65 20 69 74 20  e from where it 
1cd0: 6c 65 66 74 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20  left off..**.** 
1ce0: 54 6f 20 72 65 6d 6f 76 65 20 61 6c 6c 20 4f 54  To remove all OT
1cf0: 41 20 65 78 74 65 6e 73 69 6f 6e 20 73 74 61 74  A extension stat
1d00: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 72  e information, r
1d10: 65 74 75 72 6e 69 6e 67 20 61 6e 20 4f 54 41 20  eturning an OTA 
1d20: 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 74 6f 20  database .** to 
1d30: 69 74 73 20 6f 72 69 67 69 6e 61 6c 20 63 6f 6e  its original con
1d40: 74 65 6e 74 73 2c 20 69 74 20 69 73 20 73 75 66  tents, it is suf
1d50: 66 69 63 69 65 6e 74 20 74 6f 20 64 72 6f 70 20  ficient to drop 
1d60: 61 6c 6c 20 74 61 62 6c 65 73 20 74 68 61 74 20  all tables that 
1d70: 62 65 67 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68  begin.** with th
1d80: 65 20 70 72 65 66 69 78 20 22 6f 74 61 5f 22 0a  e prefix "ota_".
1d90: 2a 2f 0a 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  */..#ifndef _SQL
1da0: 49 54 45 33 4f 54 41 5f 48 0a 23 64 65 66 69 6e  ITE3OTA_H.#defin
1db0: 65 20 5f 53 51 4c 49 54 45 33 4f 54 41 5f 48 0a  e _SQLITE3OTA_H.
1dc0: 0a 23 69 6e 63 6c 75 64 65 20 22 73 71 6c 69 74  .#include "sqlit
1dd0: 65 33 2e 68 22 20 20 20 20 20 20 20 20 20 20 20  e3.h"           
1de0: 20 20 20 2f 2a 20 52 65 71 75 69 72 65 64 20 66     /* Required f
1df0: 6f 72 20 65 72 72 6f 72 20 63 6f 64 65 20 64 65  or error code de
1e00: 66 69 6e 69 74 69 6f 6e 73 20 2a 2f 0a 0a 74 79  finitions */..ty
1e10: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1e20: 69 74 65 33 6f 74 61 20 73 71 6c 69 74 65 33 6f  ite3ota sqlite3o
1e30: 74 61 3b 0a 0a 2f 2a 0a 2a 2a 20 4f 70 65 6e 20  ta;../*.** Open 
1e40: 61 6e 20 4f 54 41 20 68 61 6e 64 6c 65 2e 0a 2a  an OTA handle..*
1e50: 2a 0a 2a 2a 20 41 72 67 75 6d 65 6e 74 20 7a 54  *.** Argument zT
1e60: 61 72 67 65 74 20 69 73 20 74 68 65 20 70 61 74  arget is the pat
1e70: 68 20 74 6f 20 74 68 65 20 74 61 72 67 65 74 20  h to the target 
1e80: 64 61 74 61 62 61 73 65 2e 20 41 72 67 75 6d 65  database. Argume
1e90: 6e 74 20 7a 4f 74 61 20 69 73 0a 2a 2a 20 74 68  nt zOta is.** th
1ea0: 65 20 70 61 74 68 20 74 6f 20 74 68 65 20 4f 54  e path to the OT
1eb0: 41 20 64 61 74 61 62 61 73 65 2e 20 45 61 63 68  A database. Each
1ec0: 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
1ed0: 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 6d  nction must be m
1ee0: 61 74 63 68 65 64 0a 2a 2a 20 62 79 20 61 20 63  atched.** by a c
1ef0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 6f 74  all to sqlite3ot
1f00: 61 5f 63 6c 6f 73 65 28 29 2e 0a 2a 2f 0a 73 71  a_close()..*/.sq
1f10: 6c 69 74 65 33 6f 74 61 20 2a 73 71 6c 69 74 65  lite3ota *sqlite
1f20: 33 6f 74 61 5f 6f 70 65 6e 28 63 6f 6e 73 74 20  3ota_open(const 
1f30: 63 68 61 72 20 2a 7a 54 61 72 67 65 74 2c 20 63  char *zTarget, c
1f40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 74 61 29  onst char *zOta)
1f50: 3b 0a 0a 2f 2a 0a 2a 2a 20 44 6f 20 73 6f 6d 65  ;../*.** Do some
1f60: 20 77 6f 72 6b 20 74 6f 77 61 72 64 73 20 61 70   work towards ap
1f70: 70 6c 79 69 6e 67 20 74 68 65 20 4f 54 41 20 75  plying the OTA u
1f80: 70 64 61 74 65 20 74 6f 20 74 68 65 20 74 61 72  pdate to the tar
1f90: 67 65 74 20 64 62 2e 20 0a 2a 2a 0a 2a 2a 20 52  get db. .**.** R
1fa0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 44 4f 4e  eturn SQLITE_DON
1fb0: 45 20 69 66 20 74 68 65 20 75 70 64 61 74 65 20  E if the update 
1fc0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 6c 65 74  has been complet
1fd0: 65 6c 79 20 61 70 70 6c 69 65 64 2c 20 6f 72 20  ely applied, or 
1fe0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  .** SQLITE_OK if
1ff0: 20 6e 6f 20 65 72 72 6f 72 20 6f 63 63 75 72 73   no error occurs
2000: 20 62 75 74 20 74 68 65 72 65 20 72 65 6d 61 69   but there remai
2010: 6e 73 20 77 6f 72 6b 20 74 6f 20 64 6f 20 74 6f  ns work to do to
2020: 20 61 70 70 6c 79 0a 2a 2a 20 74 68 65 20 4f 54   apply.** the OT
2030: 41 20 75 70 64 61 74 65 2e 20 49 66 20 61 6e 20  A update. If an 
2040: 65 72 72 6f 72 20 64 6f 65 73 20 6f 63 63 75 72  error does occur
2050: 2c 20 73 6f 6d 65 20 6f 74 68 65 72 20 65 72 72  , some other err
2060: 6f 72 20 63 6f 64 65 20 69 73 20 0a 2a 2a 20 72  or code is .** r
2070: 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20  eturned. .**.** 
2080: 4f 6e 63 65 20 61 20 63 61 6c 6c 20 74 6f 20 73  Once a call to s
2090: 71 6c 69 74 65 33 6f 74 61 5f 73 74 65 70 28 29  qlite3ota_step()
20a0: 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 20   has returned a 
20b0: 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
20c0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 61  .** SQLITE_OK, a
20d0: 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ll subsequent ca
20e0: 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  lls on the same 
20f0: 4f 54 41 20 68 61 6e 64 6c 65 20 61 72 65 20 6e  OTA handle are n
2100: 6f 2d 6f 70 73 0a 2a 2a 20 74 68 61 74 20 69 6d  o-ops.** that im
2110: 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e  mediately return
2120: 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 2e   the same value.
2130: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 6f  .*/.int sqlite3o
2140: 74 61 5f 73 74 65 70 28 73 71 6c 69 74 65 33 6f  ta_step(sqlite3o
2150: 74 61 20 2a 70 4f 74 61 29 3b 0a 0a 2f 2a 0a 2a  ta *pOta);../*.*
2160: 2a 20 43 6c 6f 73 65 20 61 6e 20 4f 54 41 20 68  * Close an OTA h
2170: 61 6e 64 6c 65 2e 20 0a 2a 2a 0a 2a 2a 20 49 66  andle. .**.** If
2180: 20 74 68 65 20 4f 54 41 20 75 70 64 61 74 65 20   the OTA update 
2190: 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 6c 65 74  has been complet
21a0: 65 6c 79 20 61 70 70 6c 69 65 64 2c 20 63 6f 6d  ely applied, com
21b0: 6d 69 74 20 69 74 20 74 6f 20 74 68 65 20 74 61  mit it to the ta
21c0: 72 67 65 74 20 0a 2a 2a 20 64 61 74 61 62 61 73  rget .** databas
21d0: 65 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61 73  e. Otherwise, as
21e0: 73 75 6d 69 6e 67 20 6e 6f 20 65 72 72 6f 72 20  suming no error 
21f0: 68 61 73 20 6f 63 63 75 72 72 65 64 2c 20 73 61  has occurred, sa
2200: 76 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  ve the current .
2210: 2a 2a 20 73 74 61 74 65 20 6f 66 20 74 68 65 20  ** state of the 
2220: 4f 54 41 20 75 70 64 61 74 65 20 61 70 70 6c 69  OTA update appli
2230: 61 74 69 6f 6e 20 74 6f 20 74 68 65 20 4f 54 41  ation to the OTA
2240: 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a   database..**.**
2250: 20 49 66 20 61 6e 20 65 72 72 6f 72 20 68 61 73   If an error has
2260: 20 61 6c 72 65 61 64 79 20 6f 63 63 75 72 72 65   already occurre
2270: 64 20 61 73 20 70 61 72 74 20 6f 66 20 61 6e 20  d as part of an 
2280: 73 71 6c 69 74 65 33 6f 74 61 5f 73 74 65 70 28  sqlite3ota_step(
2290: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 6f  ).** or sqlite3o
22a0: 74 61 5f 6f 70 65 6e 28 29 20 63 61 6c 6c 2c 20  ta_open() call, 
22b0: 6f 72 20 69 66 20 6f 6e 65 20 6f 63 63 75 72 73  or if one occurs
22c0: 20 77 69 74 68 69 6e 20 74 68 69 73 20 66 75 6e   within this fun
22d0: 63 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 53 51 4c  ction, an.** SQL
22e0: 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  ite error code i
22f0: 73 20 72 65 74 75 72 6e 65 64 2e 20 41 64 64 69  s returned. Addi
2300: 74 69 6f 6e 61 6c 6c 79 2c 20 2a 70 7a 45 72 72  tionally, *pzErr
2310: 6d 73 67 20 6d 61 79 20 62 65 20 73 65 74 20 74  msg may be set t
2320: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
2330: 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
2340: 67 20 61 20 75 74 66 2d 38 20 66 6f 72 6d 61 74  g a utf-8 format
2350: 74 65 64 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67  ted English lang
2360: 75 61 67 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65  uage error.** me
2370: 73 73 61 67 65 2e 20 49 74 20 69 73 20 74 68 65  ssage. It is the
2380: 20 72 65 73 70 6f 6e 73 69 62 69 6c 69 74 79 20   responsibility 
2390: 6f 66 20 74 68 65 20 63 61 6c 6c 65 72 20 74 6f  of the caller to
23a0: 20 65 76 65 6e 74 75 61 6c 6c 79 20 66 72 65 65   eventually free
23b0: 20 61 6e 79 20 0a 2a 2a 20 73 75 63 68 20 62 75   any .** such bu
23c0: 66 66 65 72 20 75 73 69 6e 67 20 73 71 6c 69 74  ffer using sqlit
23d0: 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a  e3_free()..**.**
23e0: 20 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20 6e   Otherwise, if n
23f0: 6f 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  o error occurs, 
2400: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
2410: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20  turns SQLITE_OK 
2420: 69 66 20 74 68 65 0a 2a 2a 20 75 70 64 61 74 65  if the.** update
2430: 20 68 61 73 20 62 65 65 6e 20 70 61 72 74 69 61   has been partia
2440: 6c 6c 79 20 61 70 70 6c 69 65 64 2c 20 6f 72 20  lly applied, or 
2450: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 69 66 20 69  SQLITE_DONE if i
2460: 74 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 63  t has been .** c
2470: 6f 6d 70 6c 65 74 65 6c 79 20 61 70 70 6c 69 65  ompletely applie
2480: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2490: 33 6f 74 61 5f 63 6c 6f 73 65 28 73 71 6c 69 74  3ota_close(sqlit
24a0: 65 33 6f 74 61 20 2a 70 4f 74 61 2c 20 63 68 61  e3ota *pOta, cha
24b0: 72 20 2a 2a 70 7a 45 72 72 6d 73 67 29 3b 0a 0a  r **pzErrmsg);..
24c0: 2f 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  /*.** Return the
24d0: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
24e0: 20 6b 65 79 2d 76 61 6c 75 65 20 6f 70 65 72 61   key-value opera
24f0: 74 69 6f 6e 73 20 28 69 6e 73 65 72 74 73 2c 20  tions (inserts, 
2500: 64 65 6c 65 74 65 73 20 6f 72 20 0a 2a 2a 20 75  deletes or .** u
2510: 70 64 61 74 65 73 29 20 74 68 61 74 20 68 61 76  pdates) that hav
2520: 65 20 62 65 65 6e 20 70 65 72 66 6f 72 6d 65 64  e been performed
2530: 20 6f 6e 20 74 68 65 20 74 61 72 67 65 74 20 64   on the target d
2540: 61 74 61 62 61 73 65 20 73 69 6e 63 65 20 74 68  atabase since th
2550: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 4f 54 41  e.** current OTA
2560: 20 75 70 64 61 74 65 20 77 61 73 20 73 74 61 72   update was star
2570: 74 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ted..*/.sqlite3_
2580: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 6f 74 61  int64 sqlite3ota
2590: 5f 70 72 6f 67 72 65 73 73 28 73 71 6c 69 74 65  _progress(sqlite
25a0: 33 6f 74 61 20 2a 70 4f 74 61 29 3b 0a 0a 23 65  3ota *pOta);..#e
25b0: 6e 64 69 66 20 2f 2a 20 5f 53 51 4c 49 54 45 33  ndif /* _SQLITE3
25c0: 4f 54 41 5f 48 20 2a 2f 0a 0a                    OTA_H */..