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 */..