/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact f59b19d6c8920a931f096699d6faaf61c05db55f:


0000: 23 0a 23 20 52 75 6e 20 74 68 69 73 20 73 63 72  #.# Run this scr
0010: 69 70 74 20 74 6f 20 67 65 6e 65 72 61 74 65 64  ipt to generated
0020: 20 61 20 6c 6f 63 6b 69 6e 67 76 33 2e 68 74 6d   a lockingv3.htm
0030: 6c 20 6f 75 74 70 75 74 20 66 69 6c 65 0a 23 0a  l output file.#.
0040: 73 65 74 20 72 63 73 69 64 20 7b 24 49 64 3a 20  set rcsid {$Id: 
0050: 7d 0a 73 6f 75 72 63 65 20 63 6f 6d 6d 6f 6e 2e  }.source common.
0060: 74 63 6c 0a 68 65 61 64 65 72 20 7b 46 69 6c 65  tcl.header {File
0070: 20 4c 6f 63 6b 69 6e 67 20 41 6e 64 20 43 6f 6e   Locking And Con
0080: 63 75 72 72 65 6e 63 79 20 49 6e 20 53 51 4c 69  currency In SQLi
0090: 74 65 20 56 65 72 73 69 6f 6e 20 33 7d 0a 0a 70  te Version 3}..p
00a0: 72 6f 63 20 48 45 41 44 49 4e 47 20 7b 6c 65 76  roc HEADING {lev
00b0: 65 6c 20 74 69 74 6c 65 7d 20 7b 0a 20 20 67 6c  el title} {.  gl
00c0: 6f 62 61 6c 20 70 6e 75 6d 0a 20 20 69 6e 63 72  obal pnum.  incr
00d0: 20 70 6e 75 6d 28 24 6c 65 76 65 6c 29 0a 20 20   pnum($level).  
00e0: 66 6f 72 65 61 63 68 20 69 20 5b 61 72 72 61 79  foreach i [array
00f0: 20 6e 61 6d 65 73 20 70 6e 75 6d 5d 20 7b 0a 20   names pnum] {. 
0100: 20 20 20 69 66 20 7b 24 69 3e 24 6c 65 76 65 6c     if {$i>$level
0110: 7d 20 7b 73 65 74 20 70 6e 75 6d 28 24 69 29 20  } {set pnum($i) 
0120: 30 7d 0a 20 20 7d 0a 20 20 73 65 74 20 68 20 5b  0}.  }.  set h [
0130: 65 78 70 72 20 7b 24 6c 65 76 65 6c 2b 31 7d 5d  expr {$level+1}]
0140: 0a 20 20 69 66 20 7b 24 68 3e 36 7d 20 7b 73 65  .  if {$h>6} {se
0150: 74 20 68 20 36 7d 0a 20 20 73 65 74 20 6e 20 24  t h 6}.  set n $
0160: 70 6e 75 6d 28 31 29 2e 24 70 6e 75 6d 28 32 29  pnum(1).$pnum(2)
0170: 0a 20 20 66 6f 72 20 7b 73 65 74 20 69 20 33 7d  .  for {set i 3}
0180: 20 7b 24 69 3c 3d 24 6c 65 76 65 6c 7d 20 7b 69   {$i<=$level} {i
0190: 6e 63 72 20 69 7d 20 7b 0a 20 20 20 20 61 70 70  ncr i} {.    app
01a0: 65 6e 64 20 6e 20 2e 24 70 6e 75 6d 28 24 69 29  end n .$pnum($i)
01b0: 0a 20 20 7d 0a 20 20 70 75 74 73 20 22 3c 68 24  .  }.  puts "<h$
01c0: 68 3e 24 6e 20 24 74 69 74 6c 65 3c 2f 68 24 68  h>$n $title</h$h
01d0: 3e 22 0a 7d 0a 73 65 74 20 70 6e 75 6d 28 31 29  >".}.set pnum(1)
01e0: 20 30 0a 73 65 74 20 70 6e 75 6d 28 32 29 20 30   0.set pnum(2) 0
01f0: 0a 73 65 74 20 70 6e 75 6d 28 33 29 20 30 0a 73  .set pnum(3) 0.s
0200: 65 74 20 70 6e 75 6d 28 34 29 20 30 0a 73 65 74  et pnum(4) 0.set
0210: 20 70 6e 75 6d 28 35 29 20 30 0a 73 65 74 20 70   pnum(5) 0.set p
0220: 6e 75 6d 28 36 29 20 30 0a 73 65 74 20 70 6e 75  num(6) 0.set pnu
0230: 6d 28 37 29 20 30 0a 73 65 74 20 70 6e 75 6d 28  m(7) 0.set pnum(
0240: 38 29 20 30 0a 0a 48 45 41 44 49 4e 47 20 31 20  8) 0..HEADING 1 
0250: 7b 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 41 6e  {File Locking An
0260: 64 20 43 6f 6e 63 75 72 72 65 6e 63 79 20 49 6e  d Concurrency In
0270: 20 53 51 4c 69 74 65 20 56 65 72 73 69 6f 6e 20   SQLite Version 
0280: 33 7d 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 56 65  3}..puts {.<p>Ve
0290: 72 73 69 6f 6e 20 33 20 6f 66 20 53 51 4c 69 74  rsion 3 of SQLit
02a0: 65 20 69 6e 74 72 6f 64 75 63 65 73 20 61 20 6d  e introduces a m
02b0: 6f 72 65 20 63 6f 6d 70 6c 65 78 20 6c 6f 63 6b  ore complex lock
02c0: 69 6e 67 20 61 6e 64 20 6a 6f 75 72 6e 61 6c 69  ing and journali
02d0: 6e 67 20 0a 6d 65 63 68 61 6e 69 73 6d 20 64 65  ng .mechanism de
02e0: 73 69 67 6e 65 64 20 74 6f 20 69 6d 70 72 6f 76  signed to improv
02f0: 65 20 63 6f 6e 63 75 72 72 65 6e 63 79 20 61 6e  e concurrency an
0300: 64 20 72 65 64 75 63 65 20 74 68 65 20 77 72 69  d reduce the wri
0310: 74 65 72 20 73 74 61 72 76 61 74 69 6f 6e 20 0a  ter starvation .
0320: 70 72 6f 62 6c 65 6d 2e 20 20 54 68 65 20 6e 65  problem.  The ne
0330: 77 20 6d 65 63 68 61 6e 69 73 6d 20 61 6c 73 6f  w mechanism also
0340: 20 61 6c 6c 6f 77 73 20 61 74 6f 6d 69 63 20 63   allows atomic c
0350: 6f 6d 6d 69 74 73 20 6f 66 20 74 72 61 6e 73 61  ommits of transa
0360: 63 74 69 6f 6e 73 0a 69 6e 76 6f 6c 76 69 6e 67  ctions.involving
0370: 20 6d 75 6c 74 69 70 6c 65 20 64 61 74 61 62 61   multiple databa
0380: 73 65 20 66 69 6c 65 73 2e 0a 54 68 69 73 20 64  se files..This d
0390: 6f 63 75 6d 65 6e 74 20 64 65 73 63 72 69 62 65  ocument describe
03a0: 73 20 74 68 65 20 6e 65 77 20 6c 6f 63 6b 69 6e  s the new lockin
03b0: 67 20 6d 65 63 68 61 6e 69 73 6d 2e 0a 54 68 65  g mechanism..The
03c0: 20 69 6e 74 65 6e 64 65 64 20 61 75 64 69 65 6e   intended audien
03d0: 63 65 20 69 73 20 70 72 6f 67 72 61 6d 6d 65 72  ce is programmer
03e0: 73 20 77 68 6f 20 77 61 6e 74 20 74 6f 20 75 6e  s who want to un
03f0: 64 65 72 73 74 61 6e 64 20 61 6e 64 2f 6f 72 20  derstand and/or 
0400: 6d 6f 64 69 66 79 0a 74 68 65 20 70 61 67 65 72  modify.the pager
0410: 20 63 6f 64 65 20 61 6e 64 20 72 65 76 69 65 77   code and review
0420: 65 72 73 20 77 6f 72 6b 69 6e 67 20 74 6f 20 76  ers working to v
0430: 65 72 69 66 79 20 74 68 65 20 64 65 73 69 67 6e  erify the design
0440: 0a 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69  .of SQLite versi
0450: 6f 6e 20 33 2e 0a 3c 2f 70 3e 0a 7d 0a 0a 48 45  on 3..</p>.}..HE
0460: 41 44 49 4e 47 20 31 20 7b 4f 76 65 72 76 69 65  ADING 1 {Overvie
0470: 77 7d 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 0a 4c  w}..puts {.<p>.L
0480: 6f 63 6b 69 6e 67 20 61 6e 64 20 63 6f 6e 63 75  ocking and concu
0490: 72 72 65 6e 63 79 20 63 6f 6e 74 72 6f 6c 20 61  rrency control a
04a0: 72 65 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68  re handled by th
04b0: 65 20 74 68 65 20 0a 3c 61 20 68 72 65 66 3d 22  e the .<a href="
04c0: 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74  http://www.sqlit
04d0: 65 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 67 65  e.org/cvstrac/ge
04e0: 74 66 69 6c 65 2f 73 71 6c 69 74 65 2f 73 72 63  tfile/sqlite/src
04f0: 2f 70 61 67 65 72 2e 63 22 3e 0a 70 61 67 65 72  /pager.c">.pager
0500: 20 6d 6f 64 75 6c 65 3c 2f 61 3e 2e 0a 54 68 65   module</a>..The
0510: 20 70 61 67 65 72 20 6d 6f 64 75 6c 65 20 69 73   pager module is
0520: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
0530: 20 6d 61 6b 69 6e 67 20 53 51 4c 69 74 65 20 22   making SQLite "
0540: 41 43 49 44 22 20 28 41 74 6f 6d 69 63 2c 0a 43  ACID" (Atomic,.C
0550: 6f 6e 73 69 73 74 65 6e 74 2c 20 49 73 6f 6c 61  onsistent, Isola
0560: 74 65 64 2c 20 61 6e 64 20 44 75 72 61 62 6c 65  ted, and Durable
0570: 29 2e 20 20 54 68 65 20 70 61 67 65 72 20 6d 6f  ).  The pager mo
0580: 64 75 6c 65 20 6d 61 6b 65 73 20 73 75 72 65 20  dule makes sure 
0590: 63 68 61 6e 67 65 73 0a 68 61 70 70 65 6e 20 61  changes.happen a
05a0: 6c 6c 20 61 74 20 6f 6e 63 65 2c 20 74 68 61 74  ll at once, that
05b0: 20 65 69 74 68 65 72 20 61 6c 6c 20 63 68 61 6e   either all chan
05c0: 67 65 73 20 6f 63 63 75 72 20 6f 72 20 6e 6f 6e  ges occur or non
05d0: 65 20 6f 66 20 74 68 65 6d 20 64 6f 2c 0a 74 68  e of them do,.th
05e0: 61 74 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 70  at two or more p
05f0: 72 6f 63 65 73 73 65 73 20 64 6f 20 6e 6f 74 20  rocesses do not 
0600: 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 74 68  try to access th
0610: 65 20 64 61 74 61 62 61 73 65 0a 69 6e 20 69 6e  e database.in in
0620: 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 20  compatible ways 
0630: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
0640: 2c 20 61 6e 64 20 74 68 61 74 20 6f 6e 63 65 20  , and that once 
0650: 63 68 61 6e 67 65 73 20 68 61 76 65 20 62 65 65  changes have bee
0660: 6e 0a 77 72 69 74 74 65 6e 20 74 68 65 79 20 70  n.written they p
0670: 65 72 73 69 73 74 20 75 6e 74 69 6c 20 65 78 70  ersist until exp
0680: 6c 69 63 69 74 6c 79 20 64 65 6c 65 74 65 64 2e  licitly deleted.
0690: 20 20 54 68 65 20 70 61 67 65 72 20 61 6c 73 6f    The pager also
06a0: 20 70 72 6f 76 69 64 65 73 0a 61 6e 20 6d 65 6d   provides.an mem
06b0: 6f 72 79 20 63 61 63 68 65 20 6f 66 20 73 6f 6d  ory cache of som
06c0: 65 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  e of the content
06d0: 73 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  s of the disk fi
06e0: 6c 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  le.</p>..<p>The 
06f0: 70 61 67 65 72 20 69 73 20 75 6e 63 6f 6e 63 65  pager is unconce
0700: 72 6e 65 64 0a 77 69 74 68 20 74 68 65 20 64 65  rned.with the de
0710: 74 61 69 6c 73 20 6f 66 20 42 2d 54 72 65 65 73  tails of B-Trees
0720: 2c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  , text encodings
0730: 2c 20 69 6e 64 69 63 65 73 2c 20 61 6e 64 20 73  , indices, and s
0740: 6f 20 66 6f 72 74 68 2e 0a 46 72 6f 6d 20 74 68  o forth..From th
0750: 65 20 70 6f 69 6e 74 20 6f 66 20 76 69 65 77 20  e point of view 
0760: 6f 66 20 74 68 65 20 70 61 67 65 72 20 74 68 65  of the pager the
0770: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 73 69 73   database consis
0780: 74 73 20 6f 66 0a 61 20 73 69 6e 67 6c 65 20 66  ts of.a single f
0790: 69 6c 65 20 6f 66 20 75 6e 69 66 6f 72 6d 2d 73  ile of uniform-s
07a0: 69 7a 65 64 20 62 6c 6f 63 6b 73 2e 20 20 45 61  ized blocks.  Ea
07b0: 63 68 20 62 6c 6f 63 6b 20 69 73 20 63 61 6c 6c  ch block is call
07c0: 65 64 20 61 0a 22 70 61 67 65 22 20 61 6e 64 20  ed a."page" and 
07d0: 69 73 20 75 73 75 61 6c 6c 79 20 31 30 32 34 20  is usually 1024 
07e0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2e 20 20  bytes in size.  
07f0: 20 54 68 65 20 70 61 67 65 73 20 61 72 65 20 6e   The pages are n
0800: 75 6d 62 65 72 65 64 0a 62 65 67 69 6e 6e 69 6e  umbered.beginnin
0810: 67 20 77 69 74 68 20 31 2e 20 20 53 6f 20 74 68  g with 1.  So th
0820: 65 20 66 69 72 73 74 20 31 30 32 34 20 62 79 74  e first 1024 byt
0830: 65 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  es of the databa
0840: 73 65 20 61 72 65 20 63 61 6c 6c 65 64 0a 22 70  se are called."p
0850: 61 67 65 20 31 22 20 61 6e 64 20 74 68 65 20 73  age 1" and the s
0860: 65 63 6f 6e 64 20 31 30 32 34 20 62 79 74 65 73  econd 1024 bytes
0870: 20 61 72 65 20 63 61 6c 6c 20 22 70 61 67 65 20   are call "page 
0880: 32 22 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 2e  2" and so forth.
0890: 20 41 6c 6c 20 0a 6f 74 68 65 72 20 65 6e 63 6f   All .other enco
08a0: 64 69 6e 67 20 64 65 74 61 69 6c 73 20 61 72 65  ding details are
08b0: 20 68 61 6e 64 6c 65 64 20 62 79 20 68 69 67 68   handled by high
08c0: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
08d0: 20 6c 69 62 72 61 72 79 2e 20 20 0a 54 68 65 20   library.  .The 
08e0: 70 61 67 65 72 20 63 6f 6d 6d 75 6e 69 63 61 74  pager communicat
08f0: 65 73 20 77 69 74 68 20 74 68 65 20 6f 70 65 72  es with the oper
0900: 61 74 69 6e 67 20 73 79 73 74 65 6d 20 75 73 69  ating system usi
0910: 6e 67 20 6f 6e 65 20 6f 66 20 73 65 76 65 72 61  ng one of severa
0920: 6c 0a 6d 6f 64 75 6c 65 73 20 0a 28 45 78 61 6d  l.modules .(Exam
0930: 70 6c 65 73 3a 0a 3c 61 20 68 72 65 66 3d 22 68  ples:.<a href="h
0940: 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65  ttp://www.sqlite
0950: 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 67 65 74  .org/cvstrac/get
0960: 66 69 6c 65 2f 73 71 6c 69 74 65 2f 73 72 63 2f  file/sqlite/src/
0970: 6f 73 5f 75 6e 69 78 2e 63 22 3e 0a 6f 73 5f 75  os_unix.c">.os_u
0980: 6e 69 78 2e 63 3c 2f 61 3e 2c 0a 3c 61 20 68 72  nix.c</a>,.<a hr
0990: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73  ef="http://www.s
09a0: 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61  qlite.org/cvstra
09b0: 63 2f 67 65 74 66 69 6c 65 2f 73 71 6c 69 74 65  c/getfile/sqlite
09c0: 2f 73 72 63 2f 6f 73 5f 77 69 6e 2e 63 22 3e 0a  /src/os_win.c">.
09d0: 6f 73 5f 77 69 6e 2e 63 3c 2f 61 3e 29 0a 74 68  os_win.c</a>).th
09e0: 61 74 20 70 72 6f 76 69 64 65 73 20 61 20 75 6e  at provides a un
09f0: 69 66 6f 72 6d 20 61 62 73 74 72 61 63 74 69 6f  iform abstractio
0a00: 6e 20 66 6f 72 20 6f 70 65 72 61 74 69 6e 67 20  n for operating 
0a10: 73 79 73 74 65 6d 20 73 65 72 76 69 63 65 73 2e  system services.
0a20: 0a 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 70 61  .</p>..<p>The pa
0a30: 67 65 72 20 6d 6f 64 75 6c 65 20 65 66 66 65 63  ger module effec
0a40: 74 69 76 65 6c 79 20 63 6f 6e 74 72 6f 6c 73 20  tively controls 
0a50: 61 63 63 65 73 73 20 66 6f 72 20 73 65 70 61 72  access for separ
0a60: 61 74 65 20 74 68 72 65 61 64 73 2c 20 6f 72 0a  ate threads, or.
0a70: 73 65 70 61 72 61 74 65 20 70 72 6f 63 65 73 73  separate process
0a80: 65 73 2c 20 6f 72 20 62 6f 74 68 2e 20 20 54 68  es, or both.  Th
0a90: 72 6f 75 67 68 6f 75 74 20 74 68 69 73 20 64 6f  roughout this do
0aa0: 63 75 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  cument whenever 
0ab0: 74 68 65 0a 77 6f 72 64 20 22 70 72 6f 63 65 73  the.word "proces
0ac0: 73 22 20 69 73 20 77 72 69 74 74 65 6e 20 79 6f  s" is written yo
0ad0: 75 20 6d 61 79 20 73 75 62 73 74 69 74 75 74 65  u may substitute
0ae0: 20 74 68 65 20 77 6f 72 64 20 22 74 68 72 65 61   the word "threa
0af0: 64 22 20 77 69 74 68 6f 75 74 0a 63 68 61 6e 67  d" without.chang
0b00: 69 6e 67 20 74 68 65 20 74 72 75 74 68 20 6f 66  ing the truth of
0b10: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 3c   the statement.<
0b20: 2f 70 3e 0a 7d 0a 0a 48 45 41 44 49 4e 47 20 31  /p>.}..HEADING 1
0b30: 20 7b 4c 6f 63 6b 69 6e 67 7d 0a 0a 70 75 74 73   {Locking}..puts
0b40: 20 7b 0a 3c 70 3e 0a 46 72 6f 6d 20 74 68 65 20   {.<p>.From the 
0b50: 70 6f 69 6e 74 20 6f 66 20 76 69 65 77 20 6f 66  point of view of
0b60: 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 63 65 73   a single proces
0b70: 73 2c 20 61 20 64 61 74 61 62 61 73 65 20 66 69  s, a database fi
0b80: 6c 65 0a 63 61 6e 20 62 65 20 69 6e 20 6f 6e 65  le.can be in one
0b90: 20 6f 66 20 66 69 76 65 20 6c 6f 63 6b 69 6e 67   of five locking
0ba0: 20 73 74 61 74 65 73 3a 0a 3c 2f 70 3e 0a 0a 3c   states:.</p>..<
0bb0: 70 3e 0a 3c 74 61 62 6c 65 20 63 65 6c 6c 70 61  p>.<table cellpa
0bc0: 64 64 69 6e 67 3d 22 32 30 22 3e 0a 3c 74 72 3e  dding="20">.<tr>
0bd0: 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22  <td valign="top"
0be0: 3e 55 4e 4c 4f 43 4b 45 44 3c 2f 74 64 3e 0a 3c  >UNLOCKED</td>.<
0bf0: 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e  td valign="top">
0c00: 0a 4e 6f 20 6c 6f 63 6b 73 20 61 72 65 20 68 65  .No locks are he
0c10: 6c 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ld on the databa
0c20: 73 65 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  se.  The databas
0c30: 65 20 6d 61 79 20 62 65 20 6e 65 69 74 68 65 72  e may be neither
0c40: 20 72 65 61 64 20 6e 6f 72 0a 77 72 69 74 74 65   read nor.writte
0c50: 6e 2e 20 20 41 6e 79 20 69 6e 74 65 72 6e 61 6c  n.  Any internal
0c60: 6c 79 20 63 61 63 68 65 64 20 64 61 74 61 20 69  ly cached data i
0c70: 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 73  s considered sus
0c80: 70 65 63 74 20 61 6e 64 20 73 75 62 6a 65 63 74  pect and subject
0c90: 20 74 6f 0a 76 65 72 69 66 69 63 61 74 69 6f 6e   to.verification
0ca0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 64 61 74   against the dat
0cb0: 61 62 61 73 65 20 66 69 6c 65 20 62 65 66 6f 72  abase file befor
0cc0: 65 20 62 65 69 6e 67 20 75 73 65 64 2e 20 20 4f  e being used.  O
0cd0: 74 68 65 72 20 0a 70 72 6f 63 65 73 73 65 73 20  ther .processes 
0ce0: 63 61 6e 20 72 65 61 64 20 6f 72 20 77 72 69 74  can read or writ
0cf0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  e the database a
0d00: 73 20 74 68 65 69 72 20 6f 77 6e 20 6c 6f 63 6b  s their own lock
0d10: 69 6e 67 20 73 74 61 74 65 73 0a 70 65 72 6d 69  ing states.permi
0d20: 74 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  t.  This is the 
0d30: 64 65 66 61 75 6c 74 20 73 74 61 74 65 2e 0a 3c  default state..<
0d40: 2f 74 64 3e 3c 2f 74 72 3e 0a 0a 3c 74 72 3e 3c  /td></tr>..<tr><
0d50: 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e  td valign="top">
0d60: 53 48 41 52 45 44 3c 2f 74 64 3e 0a 3c 74 64 20  SHARED</td>.<td 
0d70: 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 0a 54 68  valign="top">.Th
0d80: 65 20 64 61 74 61 62 61 73 65 20 6d 61 79 20 62  e database may b
0d90: 65 20 72 65 61 64 20 62 75 74 20 6e 6f 74 20 77  e read but not w
0da0: 72 69 74 74 65 6e 2e 20 20 41 6e 79 20 6e 75 6d  ritten.  Any num
0db0: 62 65 72 20 6f 66 20 0a 70 72 6f 63 65 73 73 65  ber of .processe
0dc0: 73 20 63 61 6e 20 68 6f 6c 64 20 53 48 41 52 45  s can hold SHARE
0dd0: 44 20 6c 6f 63 6b 73 20 61 74 20 74 68 65 20 73  D locks at the s
0de0: 61 6d 65 20 74 69 6d 65 2c 20 68 65 6e 63 65 20  ame time, hence 
0df0: 74 68 65 72 65 20 63 61 6e 20 62 65 0a 6d 61 6e  there can be.man
0e00: 79 20 73 69 6d 75 6c 74 61 6e 65 6f 75 73 20 72  y simultaneous r
0e10: 65 61 64 65 72 73 2e 20 20 42 75 74 20 6e 6f 20  eaders.  But no 
0e20: 6f 74 68 65 72 20 74 68 72 65 61 64 20 6f 72 20  other thread or 
0e30: 70 72 6f 63 65 73 73 20 69 73 20 61 6c 6c 6f 77  process is allow
0e40: 65 64 0a 74 6f 20 77 72 69 74 65 20 74 6f 20 74  ed.to write to t
0e50: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
0e60: 20 77 68 69 6c 65 20 6f 6e 65 20 6f 72 20 6d 6f   while one or mo
0e70: 72 65 20 53 48 41 52 45 44 20 6c 6f 63 6b 73 20  re SHARED locks 
0e80: 61 72 65 20 61 63 74 69 76 65 2e 0a 3c 2f 74 64  are active..</td
0e90: 3e 3c 2f 74 72 3e 0a 0a 3c 74 72 3e 3c 74 64 20  ></tr>..<tr><td 
0ea0: 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 52 45 53  valign="top">RES
0eb0: 45 52 56 45 44 3c 2f 74 64 3e 0a 3c 74 64 20 76  ERVED</td>.<td v
0ec0: 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 0a 41 20 52  align="top">.A R
0ed0: 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6d 65 61  ESERVED lock mea
0ee0: 6e 73 20 74 68 61 74 20 74 68 65 20 70 72 6f 63  ns that the proc
0ef0: 65 73 73 20 69 73 20 70 6c 61 6e 6e 69 6e 67 20  ess is planning 
0f00: 6f 6e 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68  on writing to th
0f10: 65 0a 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e.database file 
0f20: 61 74 20 73 6f 6d 65 20 70 6f 69 6e 74 20 69 6e  at some point in
0f30: 20 74 68 65 20 66 75 74 75 72 65 20 62 75 74 20   the future but 
0f40: 74 68 61 74 20 69 74 20 69 73 20 63 75 72 72 65  that it is curre
0f50: 6e 74 6c 79 20 6a 75 73 74 0a 72 65 61 64 69 6e  ntly just.readin
0f60: 67 20 66 72 6f 6d 20 74 68 65 20 66 69 6c 65 2e  g from the file.
0f70: 20 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20    Only a single 
0f80: 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6d 61  RESERVED lock ma
0f90: 79 20 62 65 20 61 63 74 69 76 65 20 61 74 20 6f  y be active at o
0fa0: 6e 65 0a 74 69 6d 65 2c 20 74 68 6f 75 67 68 20  ne.time, though 
0fb0: 6d 75 6c 74 69 70 6c 65 20 53 48 41 52 45 44 20  multiple SHARED 
0fc0: 6c 6f 63 6b 73 20 63 61 6e 20 63 6f 65 78 69 73  locks can coexis
0fd0: 74 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20  t with a single 
0fe0: 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 2e 0a 52  RESERVED lock..R
0ff0: 45 53 45 52 56 45 44 20 64 69 66 66 65 72 73 20  ESERVED differs 
1000: 66 72 6f 6d 20 50 45 4e 44 49 4e 47 20 69 6e 20  from PENDING in 
1010: 74 68 61 74 20 6e 65 77 20 53 48 41 52 45 44 20  that new SHARED 
1020: 6c 6f 63 6b 73 20 63 61 6e 20 62 65 20 61 63 71  locks can be acq
1030: 75 69 72 65 64 0a 77 68 69 6c 65 20 74 68 65 72  uired.while ther
1040: 65 20 69 73 20 61 20 52 45 53 45 52 56 45 44 20  e is a RESERVED 
1050: 6c 6f 63 6b 2e 0a 3c 2f 74 64 3e 3c 2f 74 72 3e  lock..</td></tr>
1060: 0a 0a 3c 74 72 3e 3c 74 64 20 76 61 6c 69 67 6e  ..<tr><td valign
1070: 3d 22 74 6f 70 22 3e 50 45 4e 44 49 4e 47 3c 2f  ="top">PENDING</
1080: 74 64 3e 0a 3c 74 64 20 76 61 6c 69 67 6e 3d 22  td>.<td valign="
1090: 74 6f 70 22 3e 0a 41 20 50 45 4e 44 49 4e 47 20  top">.A PENDING 
10a0: 6c 6f 63 6b 20 6d 65 61 6e 73 20 74 68 61 74 20  lock means that 
10b0: 74 68 65 20 70 72 6f 63 65 73 73 20 68 6f 6c 64  the process hold
10c0: 69 6e 67 20 74 68 65 20 6c 6f 63 6b 20 77 61 6e  ing the lock wan
10d0: 74 73 20 74 6f 20 77 72 69 74 65 0a 74 6f 20 74  ts to write.to t
10e0: 68 65 20 64 61 74 61 62 61 73 65 20 61 73 20 73  he database as s
10f0: 6f 6f 6e 20 61 73 20 70 6f 73 73 69 62 6c 65 20  oon as possible 
1100: 61 6e 64 20 69 73 20 6a 75 73 74 20 77 61 69 74  and is just wait
1110: 69 6e 67 20 6f 6e 20 61 6c 6c 20 63 75 72 72 65  ing on all curre
1120: 6e 74 0a 53 48 41 52 45 44 20 6c 6f 63 6b 73 20  nt.SHARED locks 
1130: 74 6f 20 63 6c 65 61 72 20 73 6f 20 74 68 61 74  to clear so that
1140: 20 69 74 20 63 61 6e 20 67 65 74 20 61 6e 20 45   it can get an E
1150: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 2e 20 20  XCLUSIVE lock.  
1160: 4e 6f 20 6e 65 77 20 0a 53 48 41 52 45 44 20 6c  No new .SHARED l
1170: 6f 63 6b 73 20 61 72 65 20 70 65 72 6d 69 74 74  ocks are permitt
1180: 65 64 20 61 67 61 69 6e 73 74 20 74 68 65 20 64  ed against the d
1190: 61 74 61 62 61 73 65 20 69 66 0a 61 20 50 45 4e  atabase if.a PEN
11a0: 44 49 4e 47 20 6c 6f 63 6b 20 69 73 20 61 63 74  DING lock is act
11b0: 69 76 65 2c 20 74 68 6f 75 67 68 20 65 78 69 73  ive, though exis
11c0: 74 69 6e 67 20 53 48 41 52 45 44 20 6c 6f 63 6b  ting SHARED lock
11d0: 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 20 74 6f  s are allowed to
11e0: 0a 63 6f 6e 74 69 6e 75 65 2e 0a 3c 2f 74 64 3e  .continue..</td>
11f0: 3c 2f 74 72 3e 0a 0a 3c 74 72 3e 3c 74 64 20 76  </tr>..<tr><td v
1200: 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 45 58 43 4c  align="top">EXCL
1210: 55 53 49 56 45 3c 2f 74 64 3e 0a 3c 74 64 20 76  USIVE</td>.<td v
1220: 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 0a 41 6e 20  align="top">.An 
1230: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 69  EXCLUSIVE lock i
1240: 73 20 6e 65 65 64 65 64 20 69 6e 20 6f 72 64 65  s needed in orde
1250: 72 20 74 6f 20 77 72 69 74 65 20 74 6f 20 74 68  r to write to th
1260: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
1270: 0a 4f 6e 6c 79 20 6f 6e 65 20 45 58 43 4c 55 53  .Only one EXCLUS
1280: 49 56 45 20 6c 6f 63 6b 20 69 73 20 61 6c 6c 6f  IVE lock is allo
1290: 77 65 64 20 6f 6e 20 74 68 65 20 66 69 6c 65 20  wed on the file 
12a0: 61 6e 64 20 6e 6f 20 6f 74 68 65 72 20 6c 6f 63  and no other loc
12b0: 6b 73 20 6f 66 0a 61 6e 79 20 6b 69 6e 64 20 61  ks of.any kind a
12c0: 72 65 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f  re allowed to co
12d0: 65 78 69 73 74 20 77 69 74 68 20 61 6e 20 45 58  exist with an EX
12e0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 2e 20 20 49  CLUSIVE lock.  I
12f0: 6e 20 6f 72 64 65 72 20 74 6f 0a 6d 61 78 69 6d  n order to.maxim
1300: 69 7a 65 20 63 6f 6e 63 75 72 72 65 6e 63 79 2c  ize concurrency,
1310: 20 53 51 4c 69 74 65 20 77 6f 72 6b 73 20 74 6f   SQLite works to
1320: 20 6d 69 6e 69 6d 69 7a 65 20 74 68 65 20 61 6d   minimize the am
1330: 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 74 68 61  ount of time tha
1340: 74 0a 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  t.EXCLUSIVE lock
1350: 73 20 61 72 65 20 68 65 6c 64 2e 0a 3c 2f 74 64  s are held..</td
1360: 3e 3c 2f 74 72 3e 0a 3c 2f 74 61 62 6c 65 3e 0a  ></tr>.</table>.
1370: 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6f 70  </p>..<p>.The op
1380: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1390: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 75  nterface layer u
13a0: 6e 64 65 72 73 74 61 6e 64 73 20 61 6e 64 20 74  nderstands and t
13b0: 72 61 63 6b 73 20 61 6c 6c 20 66 69 76 65 0a 6c  racks all five.l
13c0: 6f 63 6b 69 6e 67 20 73 74 61 74 65 73 20 64 65  ocking states de
13d0: 73 63 72 69 62 65 64 20 61 62 6f 76 65 2e 20 20  scribed above.  
13e0: 0a 54 68 65 20 70 61 67 65 72 20 6d 6f 64 75 6c  .The pager modul
13f0: 65 20 6f 6e 6c 79 20 74 72 61 63 6b 73 20 66 6f  e only tracks fo
1400: 75 72 20 6f 66 20 74 68 65 20 66 69 76 65 20 6c  ur of the five l
1410: 6f 63 6b 69 6e 67 20 73 74 61 74 65 73 2e 0a 41  ocking states..A
1420: 20 50 45 4e 44 49 4e 47 20 6c 6f 63 6b 20 69 73   PENDING lock is
1430: 20 61 6c 77 61 79 73 20 6a 75 73 74 20 61 20 74   always just a t
1440: 65 6d 70 6f 72 61 72 79 0a 73 74 65 70 70 69 6e  emporary.steppin
1450: 67 20 73 74 6f 6e 65 20 6f 6e 20 74 68 65 20 70  g stone on the p
1460: 61 74 68 20 74 6f 20 61 6e 20 45 58 43 4c 55 53  ath to an EXCLUS
1470: 49 56 45 20 6c 6f 63 6b 20 61 6e 64 20 73 6f 20  IVE lock and so 
1480: 74 68 65 20 70 61 67 65 72 20 6d 6f 64 75 6c 65  the pager module
1490: 0a 64 6f 65 73 20 6e 6f 74 20 74 72 61 63 6b 20  .does not track 
14a0: 50 45 4e 44 49 4e 47 20 6c 6f 63 6b 73 2e 0a 3c  PENDING locks..<
14b0: 2f 70 3e 0a 7d 0a 0a 48 45 41 44 49 4e 47 20 31  /p>.}..HEADING 1
14c0: 20 7b 54 68 65 20 52 6f 6c 6c 62 61 63 6b 20 4a   {The Rollback J
14d0: 6f 75 72 6e 61 6c 7d 0a 0a 70 75 74 73 20 7b 0a  ournal}..puts {.
14e0: 3c 70 3e 41 6e 79 20 74 69 6d 65 20 61 20 70 72  <p>Any time a pr
14f0: 6f 63 65 73 73 20 77 61 6e 74 73 20 74 6f 20 6d  ocess wants to m
1500: 61 6b 65 20 61 20 63 68 61 6e 67 65 73 20 74 6f  ake a changes to
1510: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1520: 2c 20 69 74 0a 66 69 72 73 74 20 72 65 63 6f 72  , it.first recor
1530: 64 73 20 65 6e 6f 75 67 68 20 69 6e 66 6f 72 6d  ds enough inform
1540: 61 74 69 6f 6e 20 69 6e 20 74 68 65 20 3c 65 6d  ation in the <em
1550: 3e 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61  >rollback journa
1560: 6c 3c 2f 65 6d 3e 20 74 6f 0a 72 65 73 74 6f 72  l</em> to.restor
1570: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
1580: 69 6c 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ile back to its 
1590: 69 6e 69 74 69 61 6c 20 63 6f 6e 64 69 74 69 6f  initial conditio
15a0: 6e 2e 20 20 54 68 75 73 2c 20 62 65 66 6f 72 65  n.  Thus, before
15b0: 0a 61 6c 74 65 72 69 6e 67 20 61 6e 79 20 70 61  .altering any pa
15c0: 67 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ge of the databa
15d0: 73 65 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  se, the original
15e0: 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 61   contents of tha
15f0: 74 20 70 61 67 65 0a 6d 75 73 74 20 62 65 20 77  t page.must be w
1600: 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1610: 6a 6f 75 72 6e 61 6c 2e 20 20 54 68 65 20 6a 6f  journal.  The jo
1620: 75 72 6e 61 6c 20 61 6c 73 6f 20 72 65 63 6f 72  urnal also recor
1630: 64 73 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 73  ds the initial.s
1640: 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
1650: 61 73 65 20 73 6f 20 74 68 61 74 20 69 66 20 74  ase so that if t
1660: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1670: 20 67 72 6f 77 73 20 69 74 20 63 61 6e 20 62 65   grows it can be
1680: 20 74 72 75 6e 63 61 74 65 64 0a 62 61 63 6b 20   truncated.back 
1690: 74 6f 20 69 74 73 20 6f 72 69 67 69 6e 61 6c 20  to its original 
16a0: 73 69 7a 65 20 6f 6e 20 61 20 72 6f 6c 6c 62 61  size on a rollba
16b0: 63 6b 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  ck.</p>..<p>The 
16c0: 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
16d0: 20 69 73 20 61 20 6f 72 64 69 6e 61 72 79 20 64   is a ordinary d
16e0: 69 73 6b 20 66 69 6c 65 20 74 68 61 74 20 68 61  isk file that ha
16f0: 73 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  s the same name 
1700: 61 73 0a 74 68 65 20 64 61 74 61 62 61 73 65 20  as.the database 
1710: 66 69 6c 65 20 77 69 74 68 20 74 68 65 20 73 75  file with the su
1720: 66 66 69 78 20 22 3c 74 74 3e 2d 6a 6f 75 72 6e  ffix "<tt>-journ
1730: 61 6c 3c 2f 74 74 3e 22 20 61 64 64 65 64 2e 3c  al</tt>" added.<
1740: 2f 70 3e 0a 0a 3c 70 3e 49 66 20 53 51 4c 69 74  /p>..<p>If SQLit
1750: 65 20 69 73 20 77 6f 72 6b 69 6e 67 20 77 69 74  e is working wit
1760: 68 20 6d 75 6c 74 69 70 6c 65 20 64 61 74 61 62  h multiple datab
1770: 61 73 65 73 20 61 74 20 74 68 65 20 73 61 6d 65  ases at the same
1780: 20 74 69 6d 65 0a 28 75 73 69 6e 67 20 74 68 65   time.(using the
1790: 20 41 54 54 41 43 48 20 63 6f 6d 6d 61 6e 64 29   ATTACH command)
17a0: 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62   then each datab
17b0: 61 73 65 20 68 61 73 20 69 74 73 20 6f 77 6e 20  ase has its own 
17c0: 6a 6f 75 72 6e 61 6c 2e 0a 42 75 74 20 74 68 65  journal..But the
17d0: 72 65 20 69 73 20 61 6c 73 6f 20 61 20 73 65 70  re is also a sep
17e0: 61 72 61 74 65 20 61 67 67 72 65 67 61 74 65 20  arate aggregate 
17f0: 6a 6f 75 72 6e 61 6c 0a 63 61 6c 6c 65 64 20 74  journal.called t
1800: 68 65 20 3c 65 6d 3e 6d 61 73 74 65 72 20 6a 6f  he <em>master jo
1810: 75 72 6e 61 6c 3c 2f 65 6d 3e 2e 0a 54 68 65 20  urnal</em>..The 
1820: 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61 6c 20 64  master journal d
1830: 6f 65 73 20 6e 6f 74 20 63 6f 6e 74 61 69 6e 20  oes not contain 
1840: 70 61 67 65 20 64 61 74 61 20 75 73 65 64 20 66  page data used f
1850: 6f 72 20 72 6f 6c 6c 69 6e 67 20 62 61 63 6b 0a  or rolling back.
1860: 63 68 61 6e 67 65 73 2e 20 20 49 6e 73 74 65 61  changes.  Instea
1870: 64 20 74 68 65 20 6d 61 73 74 65 72 20 6a 6f 75  d the master jou
1880: 72 6e 61 6c 20 63 6f 6e 74 61 69 6e 73 20 74 68  rnal contains th
1890: 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 69  e names of the.i
18a0: 6e 64 69 76 69 64 75 61 6c 20 66 69 6c 65 20 6a  ndividual file j
18b0: 6f 75 72 6e 61 6c 73 20 66 6f 72 20 65 61 63 68  ournals for each
18c0: 20 6f 66 20 74 68 65 20 41 54 54 41 43 48 65 64   of the ATTACHed
18d0: 20 64 61 74 61 62 61 73 65 73 2e 20 20 20 45 61   databases.   Ea
18e0: 63 68 20 6f 66 0a 74 68 65 20 69 6e 64 69 76 69  ch of.the indivi
18f0: 64 75 61 6c 20 66 69 6c 65 20 6a 6f 75 72 6e 61  dual file journa
1900: 6c 73 20 61 6c 73 6f 20 63 6f 6e 74 61 69 6e 20  ls also contain 
1910: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1920: 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61 6c 2e 0a  master journal..
1930: 49 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  If there are no 
1940: 41 54 54 41 43 48 65 64 20 64 61 74 61 62 61 73  ATTACHed databas
1950: 65 73 20 28 6f 72 20 69 66 20 6e 6f 6e 65 20 6f  es (or if none o
1960: 66 20 74 68 65 20 41 54 54 41 43 48 65 64 20 64  f the ATTACHed d
1970: 61 74 61 62 61 73 65 0a 69 73 20 70 61 72 74 69  atabase.is parti
1980: 63 69 70 61 74 69 6e 67 20 69 6e 20 74 68 65 20  cipating in the 
1990: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
19a0: 69 6f 6e 29 20 6e 6f 20 6d 61 73 74 65 72 20 6a  ion) no master j
19b0: 6f 75 72 6e 61 6c 20 69 73 0a 63 72 65 61 74 65  ournal is.create
19c0: 64 20 61 6e 64 20 74 68 65 20 6e 6f 72 6d 61 6c  d and the normal
19d0: 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61   rollback journa
19e0: 6c 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20 65 6d  l contains an em
19f0: 70 74 79 20 73 74 72 69 6e 67 0a 69 6e 20 74 68  pty string.in th
1a00: 65 20 70 6c 61 63 65 20 6e 6f 72 6d 61 6c 6c 79  e place normally
1a10: 20 72 65 73 65 72 76 65 64 20 66 6f 72 20 72 65   reserved for re
1a20: 63 6f 72 64 69 6e 67 20 74 68 65 20 6e 61 6d 65  cording the name
1a30: 20 6f 66 20 74 68 65 20 6d 61 73 74 65 72 0a 6a   of the master.j
1a40: 6f 75 72 6e 61 6c 2e 3c 2f 70 3e 0a 0a 3c 70 3e  ournal.</p>..<p>
1a50: 41 20 69 6e 64 69 76 69 64 75 61 6c 20 66 69 6c  A individual fil
1a60: 65 20 6a 6f 75 72 6e 61 6c 20 69 73 20 73 61 69  e journal is sai
1a70: 64 20 74 6f 20 62 65 20 3c 65 6d 3e 68 6f 74 3c  d to be <em>hot<
1a80: 2f 65 6d 3e 0a 69 66 20 69 74 20 6e 65 65 64 73  /em>.if it needs
1a90: 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61   to be rolled ba
1aa0: 63 6b 0a 69 6e 20 6f 72 64 65 72 20 74 6f 20 72  ck.in order to r
1ab0: 65 73 74 6f 72 65 20 74 68 65 20 69 6e 74 65 67  estore the integ
1ac0: 72 69 74 79 20 6f 66 20 69 74 73 20 64 61 74 61  rity of its data
1ad0: 62 61 73 65 2e 20 20 0a 41 20 68 6f 74 20 6a 6f  base.  .A hot jo
1ae0: 75 72 6e 61 6c 20 69 73 20 63 72 65 61 74 65 64  urnal is created
1af0: 20 77 68 65 6e 20 61 20 70 72 6f 63 65 73 73 20   when a process 
1b00: 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
1b10: 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 0a 75   of a database.u
1b20: 70 64 61 74 65 20 61 6e 64 20 61 20 70 72 6f 67  pdate and a prog
1b30: 72 61 6d 20 6f 72 20 6f 70 65 72 61 74 69 6e 67  ram or operating
1b40: 20 73 79 73 74 65 6d 20 63 72 61 73 68 20 6f 72   system crash or
1b50: 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65 20 70   power failure p
1b60: 72 65 76 65 6e 74 73 20 0a 74 68 65 20 75 70 64  revents .the upd
1b70: 61 74 65 20 66 72 6f 6d 20 63 6f 6d 70 6c 65 74  ate from complet
1b80: 69 6e 67 2e 0a 48 6f 74 20 6a 6f 75 72 6e 61 6c  ing..Hot journal
1b90: 73 20 61 72 65 20 61 6e 20 65 78 63 65 70 74 69  s are an excepti
1ba0: 6f 6e 20 63 6f 6e 64 69 74 69 6f 6e 2e 20 0a 48  on condition. .H
1bb0: 6f 74 20 6a 6f 75 72 6e 61 6c 73 20 65 78 69 73  ot journals exis
1bc0: 74 20 74 6f 20 72 65 63 6f 76 65 72 20 66 72 6f  t to recover fro
1bd0: 6d 20 63 72 61 73 68 65 73 20 61 6e 64 20 70 6f  m crashes and po
1be0: 77 65 72 20 66 61 69 6c 75 72 65 73 2e 0a 49 66  wer failures..If
1bf0: 20 65 76 65 72 79 74 68 69 6e 67 20 69 73 20 77   everything is w
1c00: 6f 72 6b 69 6e 67 20 63 6f 72 72 65 63 74 6c 79  orking correctly
1c10: 20 0a 28 74 68 61 74 20 69 73 2c 20 69 66 20 74   .(that is, if t
1c20: 68 65 72 65 20 61 72 65 20 6e 6f 20 63 72 61 73  here are no cras
1c30: 68 65 73 20 6f 72 20 70 6f 77 65 72 20 66 61 69  hes or power fai
1c40: 6c 75 72 65 73 29 0a 79 6f 75 20 77 69 6c 6c 20  lures).you will 
1c50: 6e 65 76 65 72 20 67 65 74 20 61 20 68 6f 74 20  never get a hot 
1c60: 6a 6f 75 72 6e 61 6c 2e 0a 3c 2f 70 3e 0a 0a 3c  journal..</p>..<
1c70: 70 3e 0a 49 66 20 6e 6f 20 6d 61 73 74 65 72 20  p>.If no master 
1c80: 6a 6f 75 72 6e 61 6c 20 69 73 20 69 6e 76 6f 6c  journal is invol
1c90: 76 65 64 2c 20 74 68 65 6e 0a 61 20 6a 6f 75 72  ved, then.a jour
1ca0: 6e 61 6c 20 69 73 20 68 6f 74 20 69 66 20 69 74  nal is hot if it
1cb0: 20 65 78 69 73 74 73 20 61 6e 64 20 69 74 73 20   exists and its 
1cc0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 64 61  corresponding da
1cd0: 74 61 62 61 73 65 20 66 69 6c 65 0a 64 6f 65 73  tabase file.does
1ce0: 20 6e 6f 74 20 68 61 76 65 20 61 20 52 45 53 45   not have a RESE
1cf0: 52 56 45 44 20 6c 6f 63 6b 2e 0a 49 66 20 61 20  RVED lock..If a 
1d00: 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61 6c 20 69  master journal i
1d10: 73 20 6e 61 6d 65 64 20 69 6e 20 74 68 65 20 66  s named in the f
1d20: 69 6c 65 20 6a 6f 75 72 6e 61 6c 2c 20 74 68 65  ile journal, the
1d30: 6e 20 74 68 65 20 66 69 6c 65 20 6a 6f 75 72 6e  n the file journ
1d40: 61 6c 0a 69 73 20 68 6f 74 20 69 66 20 69 74 73  al.is hot if its
1d50: 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61 6c 20   master journal 
1d60: 65 78 69 73 74 73 20 61 6e 64 20 74 68 65 72 65  exists and there
1d70: 20 69 73 20 6e 6f 20 52 45 53 45 52 56 45 44 0a   is no RESERVED.
1d80: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 63 6f 72 72  lock on the corr
1d90: 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 62 61  esponding databa
1da0: 73 65 20 66 69 6c 65 2e 0a 49 74 20 69 73 20 69  se file..It is i
1db0: 6d 70 6f 72 74 61 6e 74 20 74 6f 20 75 6e 64 65  mportant to unde
1dc0: 72 73 74 61 6e 64 20 77 68 65 6e 20 61 20 6a 6f  rstand when a jo
1dd0: 75 72 6e 61 6c 20 69 73 20 68 6f 74 20 73 6f 20  urnal is hot so 
1de0: 74 68 65 0a 70 72 65 63 65 64 69 6e 67 20 72 75  the.preceding ru
1df0: 6c 65 73 20 77 69 6c 6c 20 62 65 20 72 65 70 65  les will be repe
1e00: 61 74 65 64 20 69 6e 20 62 75 6c 6c 65 74 73 3a  ated in bullets:
1e10: 0a 3c 2f 70 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e  .</p>..<ul>.<li>
1e20: 41 20 6a 6f 75 72 6e 61 6c 20 69 73 20 68 6f 74  A journal is hot
1e30: 20 69 66 2e 2e 2e 0a 20 20 20 20 3c 75 6c 3e 0a   if....    <ul>.
1e40: 20 20 20 20 3c 6c 69 3e 49 74 20 65 78 69 73 74      <li>It exist
1e50: 73 2c 20 61 6e 64 3c 2f 6c 69 3e 0a 20 20 20 20  s, and</li>.    
1e60: 3c 6c 69 3e 49 74 27 73 20 6d 61 73 74 65 72 20  <li>It's master 
1e70: 6a 6f 75 72 6e 61 6c 20 65 78 69 73 74 73 20 6f  journal exists o
1e80: 72 20 74 68 65 20 6d 61 73 74 65 72 20 6a 6f 75  r the master jou
1e90: 72 6e 61 6c 20 6e 61 6d 65 20 69 73 20 61 6e 0a  rnal name is an.
1ea0: 20 20 20 20 20 20 20 20 65 6d 70 74 79 20 73 74          empty st
1eb0: 72 69 6e 67 2c 20 61 6e 64 3c 2f 6c 69 3e 0a 20  ring, and</li>. 
1ec0: 20 20 20 3c 6c 69 3e 54 68 65 72 65 20 69 73 20     <li>There is 
1ed0: 6e 6f 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b  no RESERVED lock
1ee0: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
1ef0: 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  nding database f
1f00: 69 6c 65 2e 3c 2f 6c 69 3e 0a 20 20 20 20 3c 2f  ile.</li>.    </
1f10: 75 6c 3e 0a 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a  ul>.</li>.</ul>.
1f20: 7d 0a 0a 48 45 41 44 49 4e 47 20 32 20 7b 44 65  }..HEADING 2 {De
1f30: 61 6c 69 6e 67 20 77 69 74 68 20 68 6f 74 20 6a  aling with hot j
1f40: 6f 75 72 6e 61 6c 73 7d 0a 0a 70 75 74 73 20 7b  ournals}..puts {
1f50: 0a 3c 70 3e 0a 42 65 66 6f 72 65 20 72 65 61 64  .<p>.Before read
1f60: 69 6e 67 20 66 72 6f 6d 20 61 20 61 20 64 61 74  ing from a a dat
1f70: 61 62 61 73 65 20 66 69 6c 65 2c 20 53 51 4c 69  abase file, SQLi
1f80: 74 65 20 61 6c 77 61 79 73 20 63 68 65 63 6b 73  te always checks
1f90: 20 74 6f 20 73 65 65 20 69 66 20 74 68 61 74 0a   to see if that.
1fa0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61  database file ha
1fb0: 73 20 61 20 68 6f 74 20 6a 6f 75 72 6e 61 6c 2e  s a hot journal.
1fc0: 20 20 49 66 20 74 68 65 20 66 69 6c 65 20 64 6f    If the file do
1fd0: 65 73 20 68 61 76 65 20 61 20 68 6f 74 20 6a 6f  es have a hot jo
1fe0: 75 72 6e 61 6c 2c 20 74 68 65 6e 0a 74 68 65 20  urnal, then.the 
1ff0: 6a 6f 75 72 6e 61 6c 20 69 73 20 72 6f 6c 6c 65  journal is rolle
2000: 64 20 62 61 63 6b 20 62 65 66 6f 72 65 20 74 68  d back before th
2010: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 2e 20  e file is read. 
2020: 20 49 6e 20 74 68 69 73 20 77 61 79 2c 20 77 65   In this way, we
2030: 20 65 6e 73 75 72 65 0a 74 68 61 74 20 74 68 65   ensure.that the
2040: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
2050: 73 20 69 6e 20 61 20 63 6f 6e 73 69 73 74 65 6e  s in a consisten
2060: 74 20 73 74 61 74 65 20 62 65 66 6f 72 65 20 69  t state before i
2070: 74 20 69 73 20 72 65 61 64 2e 0a 3c 2f 70 3e 0a  t is read..</p>.
2080: 0a 3c 70 3e 57 68 65 6e 20 61 20 70 72 6f 63 65  .<p>When a proce
2090: 73 73 20 77 61 6e 74 73 20 74 6f 20 72 65 61 64  ss wants to read
20a0: 20 66 72 6f 6d 20 61 20 64 61 74 61 62 61 73 65   from a database
20b0: 20 66 69 6c 65 2c 20 69 74 20 66 6f 6c 6c 6f 77   file, it follow
20c0: 65 64 0a 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ed.the following
20d0: 20 73 65 71 75 65 6e 63 65 20 6f 66 20 73 74 65   sequence of ste
20e0: 70 73 3a 0a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e 0a 3c  ps:.</p>..<ol>.<
20f0: 6c 69 3e 4f 70 65 6e 20 74 68 65 20 64 61 74 61  li>Open the data
2100: 62 61 73 65 20 66 69 6c 65 20 61 6e 64 20 6f 62  base file and ob
2110: 74 61 69 6e 20 61 20 53 48 41 52 45 44 20 6c 6f  tain a SHARED lo
2120: 63 6b 2e 20 20 49 66 20 74 68 65 20 53 48 41 52  ck.  If the SHAR
2130: 45 44 20 6c 6f 63 6b 0a 20 20 20 20 63 61 6e 6e  ED lock.    cann
2140: 6f 74 20 62 65 20 6f 62 74 61 69 6e 65 64 2c 20  ot be obtained, 
2150: 66 61 69 6c 20 69 6d 6d 65 64 69 61 74 65 6c 79  fail immediately
2160: 20 61 6e 64 20 72 65 74 75 72 6e 20 53 51 4c 49   and return SQLI
2170: 54 45 5f 42 55 53 59 2e 3c 2f 6c 69 3e 0a 3c 6c  TE_BUSY.</li>.<l
2180: 69 3e 43 68 65 63 6b 20 74 6f 20 73 65 65 20 69  i>Check to see i
2190: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
21a0: 69 6c 65 20 68 61 73 20 61 20 68 6f 74 20 6a 6f  ile has a hot jo
21b0: 75 72 6e 61 6c 2e 20 20 20 49 66 20 74 68 65 20  urnal.   If the 
21c0: 66 69 6c 65 0a 20 20 20 20 64 6f 65 73 20 6e 6f  file.    does no
21d0: 74 20 68 61 76 65 20 61 20 68 6f 74 20 6a 6f 75  t have a hot jou
21e0: 72 6e 61 6c 2c 20 77 65 20 61 72 65 20 64 6f 6e  rnal, we are don
21f0: 65 2e 20 20 52 65 74 75 72 6e 20 69 6d 6d 65 64  e.  Return immed
2200: 69 61 74 65 6c 79 2e 0a 20 20 20 20 49 66 20 74  iately..    If t
2210: 68 65 72 65 20 69 73 20 61 20 68 6f 74 20 6a 6f  here is a hot jo
2220: 75 72 6e 61 6c 2c 20 74 68 61 74 20 6a 6f 75 72  urnal, that jour
2230: 6e 61 6c 20 6d 75 73 74 20 62 65 20 72 6f 6c 6c  nal must be roll
2240: 65 64 20 62 61 63 6b 20 62 79 0a 20 20 20 20 74  ed back by.    t
2250: 68 65 20 73 75 62 73 65 71 75 65 6e 74 20 73 74  he subsequent st
2260: 65 70 73 20 6f 66 20 74 68 69 73 20 61 6c 67 6f  eps of this algo
2270: 72 69 74 68 6d 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e  rithm.</li>.<li>
2280: 41 63 71 75 69 72 65 20 61 20 50 45 4e 44 49 4e  Acquire a PENDIN
2290: 47 20 6c 6f 63 6b 20 74 68 65 6e 20 61 6e 20 45  G lock then an E
22a0: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
22b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22c0: 6c 65 2e 0a 20 20 20 20 28 4e 6f 74 65 3a 20 44  le..    (Note: D
22d0: 6f 20 6e 6f 74 20 61 63 71 75 69 72 65 20 61 20  o not acquire a 
22e0: 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 62 65  RESERVED lock be
22f0: 63 61 75 73 65 20 74 68 61 74 20 77 6f 75 6c 64  cause that would
2300: 20 6d 61 6b 65 0a 20 20 20 20 6f 74 68 65 72 20   make.    other 
2310: 70 72 6f 63 65 73 73 65 73 20 74 68 69 6e 6b 20  processes think 
2320: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 61 73 20  the journal was 
2330: 6e 6f 20 6c 6f 6e 67 65 72 20 68 6f 74 2e 29 20  no longer hot.) 
2340: 20 49 66 20 77 65 0a 20 20 20 20 66 61 69 6c 20   If we.    fail 
2350: 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 73 65  to acquire these
2360: 20 6c 6f 63 6b 73 20 69 74 20 6d 65 61 6e 73 20   locks it means 
2370: 61 6e 6f 74 68 65 72 20 70 72 6f 63 65 73 73 0a  another process.
2380: 20 20 20 20 69 73 20 61 6c 72 65 61 64 79 20 74      is already t
2390: 72 79 69 6e 67 20 74 6f 20 64 6f 20 74 68 65 20  rying to do the 
23a0: 72 6f 6c 6c 62 61 63 6b 2e 20 20 49 6e 20 74 68  rollback.  In th
23b0: 61 74 20 63 61 73 65 2c 0a 20 20 20 20 64 72 6f  at case,.    dro
23c0: 70 20 61 6c 6c 20 6c 6f 63 6b 73 2c 20 63 6c 6f  p all locks, clo
23d0: 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  se the database,
23e0: 20 61 6e 64 20 72 65 74 75 72 6e 20 53 51 4c 49   and return SQLI
23f0: 54 45 5f 42 55 53 59 2e 20 3c 2f 6c 69 3e 0a 3c  TE_BUSY. </li>.<
2400: 6c 69 3e 52 65 61 64 20 74 68 65 20 6a 6f 75 72  li>Read the jour
2410: 6e 61 6c 20 66 69 6c 65 20 61 6e 64 20 72 6f 6c  nal file and rol
2420: 6c 20 62 61 63 6b 20 74 68 65 20 63 68 61 6e 67  l back the chang
2430: 65 73 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 57 61 69  es.</li>.<li>Wai
2440: 74 20 66 6f 72 20 74 68 65 20 72 6f 6c 6c 65 64  t for the rolled
2450: 20 62 61 63 6b 20 63 68 61 6e 67 65 73 20 74 6f   back changes to
2460: 20 62 65 20 77 72 69 74 74 65 6e 20 6f 6e 74 6f   be written onto
2470: 20 0a 20 20 20 20 74 68 65 20 73 75 72 66 61 63   .    the surfac
2480: 65 20 6f 66 20 74 68 65 20 64 69 73 6b 2e 20 20  e of the disk.  
2490: 54 68 69 73 20 70 72 6f 74 65 63 74 73 20 74 68  This protects th
24a0: 65 20 69 6e 74 65 67 72 69 74 79 20 6f 66 20 74  e integrity of t
24b0: 68 65 20 64 61 74 61 62 61 73 65 0a 20 20 20 20  he database.    
24c0: 69 6e 20 63 61 73 65 20 61 6e 6f 74 68 65 72 20  in case another 
24d0: 70 6f 77 65 72 20 66 61 69 6c 75 72 65 20 6f 72  power failure or
24e0: 20 63 72 61 73 68 20 6f 63 63 75 72 73 2e 3c 2f   crash occurs.</
24f0: 6c 69 3e 0a 3c 6c 69 3e 44 65 6c 65 74 65 20 74  li>.<li>Delete t
2500: 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 2e  he journal file.
2510: 3c 2f 6c 69 3e 0a 3c 6c 69 3e 44 65 6c 65 74 65  </li>.<li>Delete
2520: 20 74 68 65 20 6d 61 73 74 65 72 20 6a 6f 75 72   the master jour
2530: 6e 61 6c 20 66 69 6c 65 20 69 66 20 69 74 20 69  nal file if it i
2540: 73 20 73 61 66 65 20 74 6f 20 64 6f 20 73 6f 2e  s safe to do so.
2550: 0a 20 20 20 20 54 68 69 73 20 73 74 65 70 20 69  .    This step i
2560: 73 20 6f 70 74 69 6f 6e 61 6c 2e 20 20 49 74 20  s optional.  It 
2570: 69 73 20 68 65 72 65 20 6f 6e 6c 79 20 74 6f 20  is here only to 
2580: 70 72 65 76 65 6e 74 20 73 74 61 6c 65 0a 20 20  prevent stale.  
2590: 20 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61 6c    master journal
25a0: 73 20 66 72 6f 6d 20 63 6c 75 74 74 65 72 69 6e  s from clutterin
25b0: 67 20 75 70 20 74 68 65 20 64 69 73 6b 20 64 72  g up the disk dr
25c0: 69 76 65 2e 0a 20 20 20 20 53 65 65 20 74 68 65  ive..    See the
25d0: 20 64 69 73 63 75 73 73 69 6f 6e 20 62 65 6c 6f   discussion belo
25e0: 77 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 3c 2f  w for details.</
25f0: 6c 69 3e 0a 3c 6c 69 3e 44 72 6f 70 20 74 68 65  li>.<li>Drop the
2600: 20 45 58 43 4c 55 53 49 56 45 20 61 6e 64 20 50   EXCLUSIVE and P
2610: 45 4e 44 49 4e 47 20 6c 6f 63 6b 73 20 62 75 74  ENDING locks but
2620: 20 72 65 74 61 69 6e 20 74 68 65 20 53 48 41 52   retain the SHAR
2630: 45 44 20 6c 6f 63 6b 2e 3c 2f 6c 69 3e 0a 3c 2f  ED lock.</li>.</
2640: 6f 6c 3e 0a 0a 3c 70 3e 41 66 74 65 72 20 74 68  ol>..<p>After th
2650: 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 62 6f 76  e algorithm abov
2660: 65 20 63 6f 6d 70 6c 65 74 65 73 20 73 75 63 63  e completes succ
2670: 65 73 73 66 75 6c 6c 79 2c 20 69 74 20 69 73 20  essfully, it is 
2680: 73 61 66 65 20 74 6f 20 0a 72 65 61 64 20 66 72  safe to .read fr
2690: 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20  om the database 
26a0: 66 69 6c 65 2e 20 20 4f 6e 63 65 20 61 6c 6c 20  file.  Once all 
26b0: 72 65 61 64 69 6e 67 20 68 61 73 20 63 6f 6d 70  reading has comp
26c0: 6c 65 74 65 64 2c 20 74 68 65 0a 53 48 41 52 45  leted, the.SHARE
26d0: 44 20 6c 6f 63 6b 20 69 73 20 64 72 6f 70 70 65  D lock is droppe
26e0: 64 2e 3c 2f 70 3e 0a 7d 0a 0a 48 45 41 44 49 4e  d.</p>.}..HEADIN
26f0: 47 20 32 20 7b 44 65 6c 65 74 69 6e 67 20 73 74  G 2 {Deleting st
2700: 61 6c 65 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e  ale master journ
2710: 61 6c 73 7d 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e  als}..puts {.<p>
2720: 41 20 73 74 61 6c 65 20 6d 61 73 74 65 72 20 6a  A stale master j
2730: 6f 75 72 6e 61 6c 20 69 73 20 61 20 6d 61 73 74  ournal is a mast
2740: 65 72 20 6a 6f 75 72 6e 61 6c 20 74 68 61 74 20  er journal that 
2750: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 62 65 69  is no longer bei
2760: 6e 67 0a 75 73 65 64 20 66 6f 72 20 61 6e 79 74  ng.used for anyt
2770: 68 69 6e 67 2e 20 20 54 68 65 72 65 20 69 73 20  hing.  There is 
2780: 6e 6f 20 72 65 71 75 69 72 65 6d 65 6e 74 20 74  no requirement t
2790: 68 61 74 20 73 74 61 6c 65 20 6d 61 73 74 65 72  hat stale master
27a0: 20 6a 6f 75 72 6e 61 6c 73 0a 62 65 20 64 65 6c   journals.be del
27b0: 65 74 65 64 2e 20 20 54 68 65 20 6f 6e 6c 79 20  eted.  The only 
27c0: 72 65 61 73 6f 6e 20 66 6f 72 20 64 6f 69 6e 67  reason for doing
27d0: 20 73 6f 20 69 73 20 74 6f 20 66 72 65 65 20 75   so is to free u
27e0: 70 20 64 69 73 6b 20 73 70 61 63 65 2e 3c 2f 70  p disk space.</p
27f0: 3e 0a 0a 3c 70 3e 41 20 6d 61 73 74 65 72 20 6a  >..<p>A master j
2800: 6f 75 72 6e 61 6c 20 69 73 20 73 74 61 6c 65 20  ournal is stale 
2810: 69 66 20 6e 6f 20 69 6e 64 69 76 69 64 75 61 6c  if no individual
2820: 20 66 69 6c 65 20 6a 6f 75 72 6e 61 6c 73 20 61   file journals a
2830: 72 65 20 70 6f 69 6e 74 69 6e 67 0a 74 6f 20 69  re pointing.to i
2840: 74 2e 20 20 54 6f 20 66 69 67 75 72 65 20 6f 75  t.  To figure ou
2850: 74 20 69 66 20 61 20 6d 61 73 74 65 72 20 6a 6f  t if a master jo
2860: 75 72 6e 61 6c 20 69 73 20 73 74 61 6c 65 2c 20  urnal is stale, 
2870: 77 65 20 66 69 72 73 74 20 72 65 61 64 20 74 68  we first read th
2880: 65 0a 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61 6c  e.master journal
2890: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
28a0: 61 6d 65 73 20 6f 66 20 61 6c 6c 20 6f 66 20 69  ames of all of i
28b0: 74 73 20 66 69 6c 65 20 6a 6f 75 72 6e 61 6c 73  ts file journals
28c0: 2e 20 20 54 68 65 6e 0a 77 65 20 63 68 65 63 6b  .  Then.we check
28d0: 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 66   each of those f
28e0: 69 6c 65 20 6a 6f 75 72 6e 61 6c 73 2e 20 20 49  ile journals.  I
28f0: 66 20 61 6e 79 20 6f 66 20 74 68 65 20 66 69 6c  f any of the fil
2900: 65 20 6a 6f 75 72 6e 61 6c 73 20 6e 61 6d 65 64  e journals named
2910: 0a 69 6e 20 74 68 65 20 6d 61 73 74 65 72 20 6a  .in the master j
2920: 6f 75 72 6e 61 6c 20 65 78 69 73 74 73 20 61 6e  ournal exists an
2930: 64 20 70 6f 69 6e 74 73 20 62 61 63 6b 20 74 6f  d points back to
2940: 20 74 68 65 20 6d 61 73 74 65 72 20 6a 6f 75 72   the master jour
2950: 6e 61 6c 2c 20 74 68 65 6e 0a 74 68 65 20 6d 61  nal, then.the ma
2960: 73 74 65 72 20 6a 6f 75 72 6e 61 6c 20 69 73 20  ster journal is 
2970: 6e 6f 74 20 73 74 61 6c 65 2e 20 20 49 66 20 61  not stale.  If a
2980: 6c 6c 20 66 69 6c 65 20 6a 6f 75 72 6e 61 6c 73  ll file journals
2990: 20 61 72 65 20 65 69 74 68 65 72 20 6d 69 73 73   are either miss
29a0: 69 6e 67 0a 6f 72 20 72 65 66 65 72 20 74 6f 20  ing.or refer to 
29b0: 6f 74 68 65 72 20 6d 61 73 74 65 72 20 6a 6f 75  other master jou
29c0: 72 6e 61 6c 73 20 6f 72 20 6e 6f 20 6d 61 73 74  rnals or no mast
29d0: 65 72 20 6a 6f 75 72 6e 61 6c 20 61 74 20 61 6c  er journal at al
29e0: 6c 2c 20 74 68 65 6e 20 74 68 65 0a 6d 61 73 74  l, then the.mast
29f0: 65 72 20 6a 6f 75 72 6e 61 6c 20 77 65 20 61 72  er journal we ar
2a00: 65 20 74 65 73 74 69 6e 67 20 69 73 20 73 74 61  e testing is sta
2a10: 6c 65 20 61 6e 64 20 63 61 6e 20 62 65 20 73 61  le and can be sa
2a20: 66 65 6c 79 20 64 65 6c 65 74 65 64 2e 3c 2f 70  fely deleted.</p
2a30: 3e 0a 7d 0a 0a 48 45 41 44 49 4e 47 20 31 20 7b  >.}..HEADING 1 {
2a40: 57 72 69 74 69 6e 67 20 74 6f 20 61 20 64 61 74  Writing to a dat
2a50: 61 62 61 73 65 20 66 69 6c 65 7d 0a 0a 70 75 74  abase file}..put
2a60: 73 20 7b 0a 3c 70 3e 54 6f 20 77 72 69 74 65 20  s {.<p>To write 
2a70: 74 6f 20 61 20 64 61 74 61 62 61 73 65 2c 20 61  to a database, a
2a80: 20 70 72 6f 63 65 73 73 20 6d 75 73 74 20 66 69   process must fi
2a90: 72 73 74 20 61 63 71 75 69 72 65 20 61 20 53 48  rst acquire a SH
2aa0: 41 52 45 44 20 6c 6f 63 6b 0a 61 73 20 64 65 73  ARED lock.as des
2ab0: 63 72 69 62 65 64 20 61 62 6f 76 65 20 28 70 6f  cribed above (po
2ac0: 73 73 69 62 6c 79 20 72 6f 6c 6c 69 6e 67 20 62  ssibly rolling b
2ad0: 61 63 6b 20 69 6e 63 6f 6d 70 6c 65 74 65 20 63  ack incomplete c
2ae0: 68 61 6e 67 65 73 20 69 66 20 74 68 65 72 65 0a  hanges if there.
2af0: 69 73 20 61 20 68 6f 74 20 6a 6f 75 72 6e 61 6c  is a hot journal
2b00: 29 2e 20 0a 41 66 74 65 72 20 61 20 53 48 41 52  ). .After a SHAR
2b10: 45 44 20 6c 6f 63 6b 20 69 73 20 6f 62 74 61 69  ED lock is obtai
2b20: 6e 65 64 2c 20 61 20 52 45 53 45 52 56 45 44 20  ned, a RESERVED 
2b30: 6c 6f 63 6b 20 6d 75 73 74 20 62 65 20 61 63 71  lock must be acq
2b40: 75 69 72 65 64 2e 0a 54 68 65 20 52 45 53 45 52  uired..The RESER
2b50: 56 45 44 20 6c 6f 63 6b 20 73 69 67 6e 61 6c 73  VED lock signals
2b60: 20 74 68 61 74 20 74 68 65 20 70 72 6f 63 65 73   that the proces
2b70: 73 20 69 6e 74 65 6e 64 73 20 74 6f 20 77 72 69  s intends to wri
2b80: 74 65 20 74 6f 20 74 68 65 0a 64 61 74 61 62 61  te to the.databa
2b90: 73 65 20 61 74 20 73 6f 6d 65 20 70 6f 69 6e 74  se at some point
2ba0: 20 69 6e 20 74 68 65 20 66 75 74 75 72 65 2e 20   in the future. 
2bb0: 20 4f 6e 6c 79 20 6f 6e 65 20 70 72 6f 63 65 73   Only one proces
2bc0: 73 20 61 74 20 61 20 74 69 6d 65 0a 63 61 6e 20  s at a time.can 
2bd0: 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
2be0: 6c 6f 63 6b 2e 20 20 42 75 74 20 6f 74 68 65 72  lock.  But other
2bf0: 20 70 72 6f 63 65 73 73 65 73 20 63 61 6e 20 63   processes can c
2c00: 6f 6e 74 69 6e 75 65 20 74 6f 20 72 65 61 64 0a  ontinue to read.
2c10: 74 68 65 20 64 61 74 61 62 61 73 65 20 77 68 69  the database whi
2c20: 6c 65 20 74 68 65 20 52 45 53 45 52 56 45 44 20  le the RESERVED 
2c30: 6c 6f 63 6b 20 69 73 20 68 65 6c 64 2e 0a 3c 2f  lock is held..</
2c40: 70 3e 0a 0a 3c 70 3e 49 66 20 74 68 65 20 70 72  p>..<p>If the pr
2c50: 6f 63 65 73 73 20 74 68 61 74 20 77 61 6e 74 73  ocess that wants
2c60: 20 74 6f 20 77 72 69 74 65 20 69 73 20 75 6e 61   to write is una
2c70: 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  ble to obtain a 
2c80: 52 45 53 45 52 56 45 44 0a 6c 6f 63 6b 2c 20 69  RESERVED.lock, i
2c90: 74 20 6d 75 73 74 20 6d 65 61 6e 20 74 68 61 74  t must mean that
2ca0: 20 61 6e 6f 74 68 65 72 20 70 72 6f 63 65 73 73   another process
2cb0: 20 61 6c 72 65 61 64 79 20 68 61 73 20 61 20 52   already has a R
2cc0: 45 53 45 52 56 45 44 20 6c 6f 63 6b 2e 0a 49 6e  ESERVED lock..In
2cd0: 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 20   that case, the 
2ce0: 77 72 69 74 65 20 61 74 74 65 6d 70 74 20 66 61  write attempt fa
2cf0: 69 6c 73 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ils and returns 
2d00: 53 51 4c 49 54 45 5f 42 55 53 59 2e 3c 2f 70 3e  SQLITE_BUSY.</p>
2d10: 0a 0a 3c 70 3e 41 66 74 65 72 20 6f 62 74 61 69  ..<p>After obtai
2d20: 6e 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 20  ning a RESERVED 
2d30: 6c 6f 63 6b 2c 20 74 68 65 20 70 72 6f 63 65 73  lock, the proces
2d40: 73 20 74 68 61 74 20 77 61 6e 74 73 20 74 6f 20  s that wants to 
2d50: 77 72 69 74 65 0a 63 72 65 61 74 65 73 20 61 20  write.creates a 
2d60: 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
2d70: 2e 20 20 54 68 65 20 68 65 61 64 65 72 20 6f 66  .  The header of
2d80: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 69 73 20   the journal is 
2d90: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 77 69 74 68  initialized.with
2da0: 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 69   the original si
2db0: 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
2dc0: 73 65 20 66 69 6c 65 2e 20 20 53 70 61 63 65 20  se file.  Space 
2dd0: 69 6e 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 68  in the journal h
2de0: 65 61 64 65 72 0a 69 73 20 61 6c 73 6f 20 72 65  eader.is also re
2df0: 73 65 72 76 65 64 20 66 6f 72 20 61 20 6d 61 73  served for a mas
2e00: 74 65 72 20 6a 6f 75 72 6e 61 6c 20 6e 61 6d 65  ter journal name
2e10: 2c 20 74 68 6f 75 67 68 20 74 68 65 20 6d 61 73  , though the mas
2e20: 74 65 72 20 6a 6f 75 72 6e 61 6c 0a 6e 61 6d 65  ter journal.name
2e30: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 65 6d   is initially em
2e40: 70 74 79 2e 3c 2f 70 3e 0a 0a 3c 70 3e 42 65 66  pty.</p>..<p>Bef
2e50: 6f 72 65 20 6d 61 6b 69 6e 67 20 63 68 61 6e 67  ore making chang
2e60: 65 73 20 74 6f 20 61 6e 79 20 70 61 67 65 20 6f  es to any page o
2e70: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  f the database, 
2e80: 74 68 65 20 70 72 6f 63 65 73 73 20 77 72 69 74  the process writ
2e90: 65 73 0a 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  es.the original 
2ea0: 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 61 74 20  content of that 
2eb0: 70 61 67 65 20 69 6e 74 6f 20 74 68 65 20 72 6f  page into the ro
2ec0: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 2e 20  llback journal. 
2ed0: 20 43 68 61 6e 67 65 73 0a 74 6f 20 70 61 67 65   Changes.to page
2ee0: 73 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65  s are held in me
2ef0: 6d 6f 72 79 20 61 74 20 66 69 72 73 74 20 61 6e  mory at first an
2f00: 64 20 61 72 65 20 6e 6f 74 20 77 72 69 74 74 65  d are not writte
2f10: 6e 20 74 6f 20 74 68 65 20 64 69 73 6b 2e 0a 54  n to the disk..T
2f20: 68 65 20 6f 72 69 67 69 6e 61 6c 20 64 61 74 61  he original data
2f30: 62 61 73 65 20 66 69 6c 65 20 72 65 6d 61 69 6e  base file remain
2f40: 73 20 75 6e 61 6c 74 65 72 65 64 2c 20 77 68 69  s unaltered, whi
2f50: 63 68 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 74  ch means that ot
2f60: 68 65 72 0a 70 72 6f 63 65 73 73 65 73 20 63 61  her.processes ca
2f70: 6e 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 72 65  n continue to re
2f80: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ad the database.
2f90: 3c 2f 70 3e 0a 0a 3c 70 3e 45 76 65 6e 74 75 61  </p>..<p>Eventua
2fa0: 6c 6c 79 2c 20 74 68 65 20 77 72 69 74 69 6e 67  lly, the writing
2fb0: 20 70 72 6f 63 65 73 73 20 77 69 6c 6c 20 77 61   process will wa
2fc0: 6e 74 20 74 6f 20 75 70 64 61 74 65 20 74 68 65  nt to update the
2fd0: 20 64 61 74 61 62 61 73 65 0a 66 69 6c 65 2c 20   database.file, 
2fe0: 65 69 74 68 65 72 20 62 65 63 61 75 73 65 20 69  either because i
2ff0: 74 73 20 6d 65 6d 6f 72 79 20 63 61 63 68 65 20  ts memory cache 
3000: 68 61 73 20 66 69 6c 6c 65 64 20 75 70 20 6f 72  has filled up or
3010: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 0a 72   because it is.r
3020: 65 61 64 79 20 74 6f 20 63 6f 6d 6d 69 74 20 69  eady to commit i
3030: 74 73 20 63 68 61 6e 67 65 73 2e 20 20 42 65 66  ts changes.  Bef
3040: 6f 72 65 20 74 68 69 73 20 68 61 70 70 65 6e 73  ore this happens
3050: 2c 20 74 68 65 20 77 72 69 74 65 72 20 6d 75 73  , the writer mus
3060: 74 0a 6d 61 6b 65 20 73 75 72 65 20 6e 6f 20 6f  t.make sure no o
3070: 74 68 65 72 20 70 72 6f 63 65 73 73 20 69 73 20  ther process is 
3080: 72 65 61 64 69 6e 67 20 74 68 65 20 64 61 74 61  reading the data
3090: 62 61 73 65 20 61 6e 64 20 74 68 61 74 20 74 68  base and that th
30a0: 65 20 72 6f 6c 6c 62 61 63 6b 0a 6a 6f 75 72 6e  e rollback.journ
30b0: 61 6c 20 64 61 74 61 20 69 73 20 73 61 66 65 6c  al data is safel
30c0: 79 20 6f 6e 20 74 68 65 20 64 69 73 6b 20 73 75  y on the disk su
30d0: 72 66 61 63 65 20 73 6f 20 74 68 61 74 20 69 74  rface so that it
30e0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 0a   can be used to.
30f0: 72 6f 6c 6c 62 61 63 6b 20 69 6e 63 6f 6d 70 6c  rollback incompl
3100: 65 74 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74  ete changes in t
3110: 68 65 20 65 76 65 6e 74 20 6f 66 20 61 20 70 6f  he event of a po
3120: 77 65 72 20 66 61 69 6c 75 72 65 2e 0a 54 68 65  wer failure..The
3130: 20 73 74 65 70 73 20 61 72 65 20 61 73 20 66 6f   steps are as fo
3140: 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e  llows:</p>..<ol>
3150: 0a 3c 6c 69 3e 4d 61 6b 65 20 73 75 72 65 20 61  .<li>Make sure a
3160: 6c 6c 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  ll rollback jour
3170: 6e 61 6c 20 64 61 74 61 20 68 61 73 20 61 63 74  nal data has act
3180: 75 61 6c 6c 79 20 62 65 65 6e 20 77 72 69 74 74  ually been writt
3190: 65 6e 20 74 6f 0a 20 20 20 20 74 68 65 20 73 75  en to.    the su
31a0: 72 66 61 63 65 20 6f 66 20 74 68 65 20 64 69 73  rface of the dis
31b0: 6b 20 28 61 6e 64 20 69 73 20 6e 6f 74 20 6a 75  k (and is not ju
31c0: 73 74 20 62 65 69 6e 67 20 68 65 6c 64 20 69 6e  st being held in
31d0: 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 20   the operating. 
31e0: 20 20 20 73 79 73 74 65 6d 27 73 20 20 6f 72 20     system's  or 
31f0: 64 69 73 6b 20 63 6f 6e 74 72 6f 6c 6c 65 72 73  disk controllers
3200: 20 63 61 63 68 65 29 20 73 6f 20 74 68 61 74 20   cache) so that 
3210: 69 66 20 61 20 70 6f 77 65 72 20 66 61 69 6c 75  if a power failu
3220: 72 65 20 6f 63 63 75 72 73 0a 20 20 20 20 74 68  re occurs.    th
3230: 65 20 64 61 74 61 20 77 69 6c 6c 20 73 74 69 6c  e data will stil
3240: 6c 20 62 65 20 74 68 65 72 65 20 61 66 74 65 72  l be there after
3250: 20 70 6f 77 65 72 20 69 73 20 72 65 73 74 6f 72   power is restor
3260: 65 64 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 4f 62 74  ed.</li>.<li>Obt
3270: 61 69 6e 20 61 20 50 45 4e 44 49 4e 47 20 6c 6f  ain a PENDING lo
3280: 63 6b 20 61 6e 64 20 74 68 65 6e 20 61 6e 20 45  ck and then an E
3290: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
32a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
32b0: 6c 65 2e 0a 20 20 20 20 49 66 20 6f 74 68 65 72  le..    If other
32c0: 20 70 72 6f 63 65 73 73 65 73 20 61 72 65 20 73   processes are s
32d0: 74 69 6c 6c 20 68 61 76 65 20 53 48 41 52 45 44  till have SHARED
32e0: 20 6c 6f 63 6b 73 2c 20 74 68 65 20 77 72 69 74   locks, the writ
32f0: 65 72 20 6d 69 67 68 74 20 68 61 76 65 0a 20 20  er might have.  
3300: 20 20 74 6f 20 77 61 69 74 20 75 6e 74 69 6c 20    to wait until 
3310: 74 68 6f 73 65 20 53 48 41 52 45 44 20 6c 6f 63  those SHARED loc
3320: 6b 73 20 63 6c 65 61 72 20 62 65 66 6f 72 65 20  ks clear before 
3330: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 62  it is able to ob
3340: 74 61 69 6e 0a 20 20 20 20 61 6e 20 45 58 43 4c  tain.    an EXCL
3350: 55 53 49 56 45 20 6c 6f 63 6b 2e 3c 2f 6c 69 3e  USIVE lock.</li>
3360: 0a 3c 6c 69 3e 57 72 69 74 65 20 61 6c 6c 20 70  .<li>Write all p
3370: 61 67 65 20 6d 6f 64 69 66 69 63 61 74 69 6f 6e  age modification
3380: 73 20 63 75 72 72 65 6e 74 6c 79 20 68 65 6c 64  s currently held
3390: 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 75 74 20 74   in memory out t
33a0: 6f 20 74 68 65 0a 20 20 20 20 6f 72 69 67 69 6e  o the.    origin
33b0: 61 6c 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  al database disk
33c0: 20 66 69 6c 65 2e 3c 2f 6c 69 3e 0a 3c 2f 6f 6c   file.</li>.</ol
33d0: 3e 0a 0a 3c 70 3e 0a 49 66 20 74 68 65 20 72 65  >..<p>.If the re
33e0: 61 73 6f 6e 20 66 6f 72 20 77 72 69 74 69 6e 67  ason for writing
33f0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
3400: 20 66 69 6c 65 20 69 73 20 62 65 63 61 75 73 65   file is because
3410: 20 74 68 65 20 6d 65 6d 6f 72 79 0a 63 61 63 68   the memory.cach
3420: 65 20 77 61 73 20 66 75 6c 6c 2c 20 74 68 65 6e  e was full, then
3430: 20 74 68 65 20 77 72 69 74 65 72 20 77 69 6c 6c   the writer will
3440: 20 6e 6f 74 20 63 6f 6d 6d 69 74 20 72 69 67 68   not commit righ
3450: 74 20 61 77 61 79 2e 20 20 49 6e 73 74 65 61 64  t away.  Instead
3460: 2c 0a 74 68 65 20 77 72 69 74 65 72 20 6d 69 67  ,.the writer mig
3470: 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 6d  ht continue to m
3480: 61 6b 65 20 63 68 61 6e 67 65 73 20 74 6f 20 6f  ake changes to o
3490: 74 68 65 72 20 70 61 67 65 73 2e 20 20 42 65 66  ther pages.  Bef
34a0: 6f 72 65 20 0a 73 75 62 73 65 71 75 65 6e 74 20  ore .subsequent 
34b0: 63 68 61 6e 67 65 73 20 61 72 65 20 77 72 69 74  changes are writ
34c0: 74 65 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62  ten to the datab
34d0: 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 72 6f  ase file, the ro
34e0: 6c 6c 62 61 63 6b 0a 6a 6f 75 72 6e 61 6c 20 6d  llback.journal m
34f0: 75 73 74 20 62 65 20 66 6c 75 73 68 65 64 20 74  ust be flushed t
3500: 6f 20 64 69 73 6b 20 61 67 61 69 6e 2e 20 20 4e  o disk again.  N
3510: 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 74 68  ote also that th
3520: 65 20 45 58 43 4c 55 53 49 56 45 0a 6c 6f 63 6b  e EXCLUSIVE.lock
3530: 20 74 68 61 74 20 74 68 65 20 77 72 69 74 65 72   that the writer
3540: 20 6f 62 74 61 69 6e 65 64 20 69 6e 20 6f 72 64   obtained in ord
3550: 65 72 20 74 6f 20 77 72 69 74 65 20 74 6f 20 74  er to write to t
3560: 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 69 74  he database init
3570: 69 61 6c 6c 79 0a 6d 75 73 74 20 62 65 20 68 65  ially.must be he
3580: 6c 64 20 75 6e 74 69 6c 20 61 6c 6c 20 63 68 61  ld until all cha
3590: 6e 67 65 73 20 61 72 65 20 63 6f 6d 6d 69 74 74  nges are committ
35a0: 65 64 2e 20 20 54 68 61 74 20 6d 65 61 6e 73 20  ed.  That means 
35b0: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 0a 70 72  that no other.pr
35c0: 6f 63 65 73 73 65 73 20 61 72 65 20 61 62 6c 65  ocesses are able
35d0: 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
35e0: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
35f0: 0a 74 69 6d 65 20 74 68 65 20 6d 65 6d 6f 72 79  .time the memory
3600: 20 63 61 63 68 65 20 66 69 72 73 74 20 73 70 69   cache first spi
3610: 6c 6c 73 20 74 6f 20 64 69 73 6b 20 75 6e 74 69  lls to disk unti
3620: 6c 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  l the transactio
3630: 6e 0a 63 6f 6d 6d 69 74 73 2e 0a 3c 2f 70 3e 0a  n.commits..</p>.
3640: 0a 3c 70 3e 0a 57 68 65 6e 20 61 20 77 72 69 74  .<p>.When a writ
3650: 65 72 20 69 73 20 72 65 61 64 79 20 74 6f 20 63  er is ready to c
3660: 6f 6d 6d 69 74 20 69 74 73 20 63 68 61 6e 67 65  ommit its change
3670: 73 2c 20 69 74 20 65 78 65 63 75 74 65 73 20 74  s, it executes t
3680: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 73 74 65  he following.ste
3690: 70 73 3a 0a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e 0a 3c  ps:.</p>..<ol>.<
36a0: 6c 69 20 76 61 6c 75 65 3d 22 34 22 3e 0a 20 20  li value="4">.  
36b0: 20 4f 62 74 61 69 6e 20 61 6e 20 45 58 43 4c 55   Obtain an EXCLU
36c0: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
36d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
36e0: 6e 64 0a 20 20 20 6d 61 6b 65 20 73 75 72 65 20  nd.   make sure 
36f0: 61 6c 6c 20 6d 65 6d 6f 72 79 20 63 68 61 6e 67  all memory chang
3700: 65 73 20 68 61 76 65 20 62 65 65 6e 20 77 72 69  es have been wri
3710: 74 74 65 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tten to the data
3720: 62 61 73 65 20 66 69 6c 65 0a 20 20 20 75 73 69  base file.   usi
3730: 6e 67 20 74 68 65 20 61 6c 67 6f 72 69 74 68 6d  ng the algorithm
3740: 20 6f 66 20 73 74 65 70 73 20 31 2d 33 20 61 62   of steps 1-3 ab
3750: 6f 76 65 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 46 6c  ove.</li>.<li>Fl
3760: 75 73 68 20 61 6c 6c 20 64 61 74 61 62 61 73 65  ush all database
3770: 20 66 69 6c 65 20 63 68 61 6e 67 65 73 20 74 6f   file changes to
3780: 20 74 68 65 20 64 69 73 6b 2e 20 20 57 61 69 74   the disk.  Wait
3790: 20 66 6f 72 20 74 68 6f 73 65 20 63 68 61 6e 67   for those chang
37a0: 65 73 0a 20 20 20 20 74 6f 20 61 63 74 75 61 6c  es.    to actual
37b0: 6c 79 20 62 65 20 77 72 69 74 74 65 6e 20 6f 6e  ly be written on
37c0: 74 6f 20 74 68 65 20 64 69 73 6b 20 73 75 72 66  to the disk surf
37d0: 61 63 65 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 44 65  ace.</li>.<li>De
37e0: 6c 65 74 65 20 74 68 65 20 6a 6f 75 72 6e 61 6c  lete the journal
37f0: 20 66 69 6c 65 2e 20 20 54 68 69 73 20 69 73 20   file.  This is 
3800: 74 68 65 20 69 6e 73 74 61 6e 74 20 77 68 65 6e  the instant when
3810: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 72 65   the changes are
3820: 0a 20 20 20 20 63 6f 6d 6d 69 74 74 65 64 2e 20  .    committed. 
3830: 20 50 72 69 6f 72 20 74 6f 20 64 65 6c 65 74 69   Prior to deleti
3840: 6e 67 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66  ng the journal f
3850: 69 6c 65 2c 20 69 66 20 61 20 70 6f 77 65 72 20  ile, if a power 
3860: 66 61 69 6c 75 72 65 0a 20 20 20 20 6f 72 20 63  failure.    or c
3870: 72 61 73 68 20 6f 63 63 75 72 73 2c 20 74 68 65  rash occurs, the
3880: 20 6e 65 78 74 20 70 72 6f 63 65 73 73 20 74 6f   next process to
3890: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
38a0: 73 65 20 77 69 6c 6c 20 73 65 65 20 74 68 61 74  se will see that
38b0: 0a 20 20 20 20 69 74 20 68 61 73 20 61 20 68 6f  .    it has a ho
38c0: 74 20 6a 6f 75 72 6e 61 6c 20 61 6e 64 20 77 69  t journal and wi
38d0: 6c 6c 20 72 6f 6c 6c 20 74 68 65 20 63 68 61 6e  ll roll the chan
38e0: 67 65 73 20 62 61 63 6b 2e 0a 20 20 20 20 41 66  ges back..    Af
38f0: 74 65 72 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ter the journal 
3900: 69 73 20 64 65 6c 65 74 65 64 2c 20 74 68 65 72  is deleted, ther
3910: 65 20 77 69 6c 6c 20 6e 6f 20 6c 6f 6e 67 65 72  e will no longer
3920: 20 62 65 20 61 20 68 6f 74 20 6a 6f 75 72 6e 61   be a hot journa
3930: 6c 0a 20 20 20 20 61 6e 64 20 74 68 65 20 63 68  l.    and the ch
3940: 61 6e 67 65 73 20 77 69 6c 6c 20 70 65 72 73 69  anges will persi
3950: 73 74 2e 0a 20 20 20 20 3c 2f 6c 69 3e 0a 3c 6c  st..    </li>.<l
3960: 69 3e 44 72 6f 70 20 74 68 65 20 45 58 43 4c 55  i>Drop the EXCLU
3970: 53 49 56 45 20 61 6e 64 20 50 45 4e 44 49 4e 47  SIVE and PENDING
3980: 20 6c 6f 63 6b 73 20 66 72 6f 6d 20 74 68 65 20   locks from the 
3990: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 20  database file.. 
39a0: 20 20 20 3c 2f 6c 69 3e 0a 3c 2f 6f 6c 3e 0a 0a     </li>.</ol>..
39b0: 3c 70 3e 41 73 20 73 6f 6f 6e 20 61 73 20 50 45  <p>As soon as PE
39c0: 4e 44 49 4e 47 20 6c 6f 63 6b 20 69 73 20 72 65  NDING lock is re
39d0: 6c 65 61 73 65 64 20 66 72 6f 6d 20 74 68 65 20  leased from the 
39e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 6f  database file, o
39f0: 74 68 65 72 0a 70 72 6f 63 65 73 73 65 73 20 63  ther.processes c
3a00: 61 6e 20 62 65 67 69 6e 20 72 65 61 64 69 6e 67  an begin reading
3a10: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 67   the database ag
3a20: 61 69 6e 2e 20 20 49 6e 20 74 68 65 20 63 75 72  ain.  In the cur
3a30: 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
3a40: 69 6f 6e 2c 0a 74 68 65 20 52 45 53 45 52 56 45  ion,.the RESERVE
3a50: 44 20 6c 6f 63 6b 20 69 73 20 61 6c 73 6f 20 72  D lock is also r
3a60: 65 6c 65 61 73 65 64 2c 20 62 75 74 20 74 68 61  eleased, but tha
3a70: 74 20 69 73 20 6e 6f 74 20 65 73 73 65 6e 74 69  t is not essenti
3a80: 61 6c 2e 20 20 46 75 74 75 72 65 0a 76 65 72 73  al.  Future.vers
3a90: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
3aa0: 69 67 68 74 20 70 72 6f 76 69 64 65 20 61 20 22  ight provide a "
3ab0: 43 48 45 43 4b 50 4f 49 4e 54 22 20 53 51 4c 20  CHECKPOINT" SQL 
3ac0: 63 6f 6d 6d 61 6e 64 20 74 68 61 74 20 77 69 6c  command that wil
3ad0: 6c 0a 63 6f 6d 6d 69 74 20 61 6c 6c 20 63 68 61  l.commit all cha
3ae0: 6e 67 65 73 20 6d 61 64 65 20 73 6f 20 66 61 72  nges made so far
3af0: 20 77 69 74 68 69 6e 20 61 20 74 72 61 6e 73 61   within a transa
3b00: 63 74 69 6f 6e 20 62 75 74 20 72 65 74 61 69 6e  ction but retain
3b10: 20 74 68 65 0a 52 45 53 45 52 56 45 44 20 6c 6f   the.RESERVED lo
3b20: 63 6b 20 73 6f 20 74 68 61 74 20 61 64 64 69 74  ck so that addit
3b30: 69 6f 6e 61 6c 20 63 68 61 6e 67 65 73 20 63 61  ional changes ca
3b40: 6e 20 62 65 20 6d 61 64 65 20 77 69 74 68 6f 75  n be made withou
3b50: 74 20 67 69 76 65 6e 0a 61 6e 79 20 6f 74 68 65  t given.any othe
3b60: 72 20 70 72 6f 63 65 73 73 20 61 6e 20 6f 70 70  r process an opp
3b70: 6f 72 74 75 6e 69 74 79 20 74 6f 20 77 72 69 74  ortunity to writ
3b80: 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 49 66 20 61 20  e.</p>..<p>If a 
3b90: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 6e 76 6f  transaction invo
3ba0: 6c 76 65 73 20 6d 75 6c 74 69 70 6c 65 20 64 61  lves multiple da
3bb0: 74 61 62 61 73 65 73 2c 20 74 68 65 6e 20 61 20  tabases, then a 
3bc0: 6d 6f 72 65 20 63 6f 6d 70 6c 65 78 0a 63 6f 6d  more complex.com
3bd0: 6d 69 74 20 73 65 71 75 65 6e 63 65 20 69 73 20  mit sequence is 
3be0: 75 73 65 64 2c 20 61 73 20 66 6f 6c 6c 6f 77 73  used, as follows
3bf0: 3a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 20  :</p>..<ol>.<li 
3c00: 76 61 6c 75 65 3d 22 34 22 3e 0a 20 20 20 4d 61  value="4">.   Ma
3c10: 6b 65 20 73 75 72 65 20 61 6c 6c 20 69 6e 64 69  ke sure all indi
3c20: 76 69 64 75 61 6c 20 64 61 74 61 62 61 73 65 20  vidual database 
3c30: 66 69 6c 65 73 20 68 61 76 65 20 61 6e 20 45 58  files have an EX
3c40: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 61 6e 64  CLUSIVE lock and
3c50: 20 61 0a 20 20 20 76 61 6c 69 64 20 6a 6f 75 72   a.   valid jour
3c60: 6e 61 6c 2e 0a 3c 6c 69 3e 43 72 65 61 74 65 20  nal..<li>Create 
3c70: 61 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  a master-journal
3c80: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  .  The name of t
3c90: 68 65 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  he master-journa
3ca0: 6c 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  l is arbitrary..
3cb0: 20 20 20 20 28 54 68 65 20 63 75 72 72 65 6e 74      (The current
3cc0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
3cd0: 61 70 70 65 6e 64 73 20 72 61 6e 64 6f 6d 20 73  appends random s
3ce0: 75 66 66 69 78 65 73 20 74 6f 20 74 68 65 20 6e  uffixes to the n
3cf0: 61 6d 65 20 6f 66 20 74 68 65 0a 20 20 20 20 6d  ame of the.    m
3d00: 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
3d10: 65 20 75 6e 74 69 6c 20 69 74 20 66 69 6e 64 73  e until it finds
3d20: 20 61 20 6e 61 6d 65 20 74 68 61 74 20 64 6f 65   a name that doe
3d30: 73 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79  s not previously
3d40: 20 65 78 69 73 74 2e 29 0a 20 20 20 20 46 69 6c   exist.).    Fil
3d50: 6c 20 74 68 65 20 6d 61 73 74 65 72 20 6a 6f 75  l the master jou
3d60: 72 6e 61 6c 20 77 69 74 68 20 74 68 65 20 6e 61  rnal with the na
3d70: 6d 65 73 20 6f 66 20 61 6c 6c 20 74 68 65 20 69  mes of all the i
3d80: 6e 64 69 76 69 64 75 61 6c 20 6a 6f 75 72 6e 61  ndividual journa
3d90: 6c 73 0a 20 20 20 20 61 6e 64 20 66 6c 75 73 68  ls.    and flush
3da0: 20 69 74 73 20 63 6f 6e 74 65 6e 74 73 20 74 6f   its contents to
3db0: 20 64 69 73 6b 2e 0a 3c 6c 69 3e 57 72 69 74 65   disk..<li>Write
3dc0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
3dd0: 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61 6c 20   master journal 
3de0: 69 6e 74 6f 0a 20 20 20 20 61 6c 6c 20 69 6e 64  into.    all ind
3df0: 69 76 69 64 75 61 6c 20 6a 6f 75 72 6e 61 6c 73  ividual journals
3e00: 20 28 69 6e 20 73 70 61 63 65 20 73 65 74 20 61   (in space set a
3e10: 73 69 64 65 20 66 6f 72 20 74 68 61 74 20 70 75  side for that pu
3e20: 72 70 6f 73 65 20 69 6e 20 74 68 65 0a 20 20 20  rpose in the.   
3e30: 20 68 65 61 64 65 72 73 20 6f 66 20 74 68 65 20   headers of the 
3e40: 69 6e 64 69 76 69 64 75 61 6c 20 6a 6f 75 72 6e  individual journ
3e50: 61 6c 73 29 20 61 6e 64 20 66 6c 75 73 68 20 74  als) and flush t
3e60: 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
3e70: 68 65 0a 20 20 20 20 69 6e 64 69 76 69 64 75 61  he.    individua
3e80: 6c 20 6a 6f 75 72 6e 61 6c 73 20 74 6f 20 64 69  l journals to di
3e90: 73 6b 20 61 6e 64 20 77 61 69 74 20 66 6f 72 20  sk and wait for 
3ea0: 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 74 6f  those changes to
3eb0: 20 72 65 61 63 68 20 74 68 65 0a 20 20 20 20 64   reach the.    d
3ec0: 69 73 6b 20 73 75 72 66 61 63 65 2e 0a 3c 6c 69  isk surface..<li
3ed0: 3e 46 6c 75 73 68 20 61 6c 6c 20 64 61 74 61 62  >Flush all datab
3ee0: 61 73 65 20 66 69 6c 65 20 63 68 61 6e 67 65 73  ase file changes
3ef0: 20 74 6f 20 74 68 65 20 64 69 73 6b 2e 20 20 57   to the disk.  W
3f00: 61 69 74 20 66 6f 72 20 74 68 6f 73 65 20 63 68  ait for those ch
3f10: 61 6e 67 65 73 0a 20 20 20 20 74 6f 20 61 63 74  anges.    to act
3f20: 75 61 6c 6c 79 20 62 65 20 77 72 69 74 74 65 6e  ually be written
3f30: 20 6f 6e 74 6f 20 74 68 65 20 64 69 73 6b 20 73   onto the disk s
3f40: 75 72 66 61 63 65 2e 3c 2f 6c 69 3e 0a 3c 6c 69  urface.</li>.<li
3f50: 3e 44 65 6c 65 74 65 20 74 68 65 20 6d 61 73 74  >Delete the mast
3f60: 65 72 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 2e  er journal file.
3f70: 20 20 54 68 69 73 20 69 73 20 74 68 65 20 69 6e    This is the in
3f80: 73 74 61 6e 74 20 77 68 65 6e 20 74 68 65 20 63  stant when the c
3f90: 68 61 6e 67 65 73 20 61 72 65 0a 20 20 20 20 63  hanges are.    c
3fa0: 6f 6d 6d 69 74 74 65 64 2e 20 20 50 72 69 6f 72  ommitted.  Prior
3fb0: 20 74 6f 20 64 65 6c 65 74 69 6e 67 20 74 68 65   to deleting the
3fc0: 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61 6c 20   master journal 
3fd0: 66 69 6c 65 2c 20 69 66 20 61 20 70 6f 77 65 72  file, if a power
3fe0: 20 66 61 69 6c 75 72 65 0a 20 20 20 20 6f 72 20   failure.    or 
3ff0: 63 72 61 73 68 20 6f 63 63 75 72 73 2c 20 74 68  crash occurs, th
4000: 65 20 69 6e 64 69 76 69 64 75 61 6c 20 66 69 6c  e individual fil
4010: 65 20 6a 6f 75 72 6e 61 6c 73 20 77 69 6c 6c 20  e journals will 
4020: 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 68 6f  be considered ho
4030: 74 0a 20 20 20 20 61 6e 64 20 77 69 6c 6c 20 62  t.    and will b
4040: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79  e rolled back by
4050: 20 74 68 65 20 6e 65 78 74 20 70 72 6f 63 65 73   the next proces
4060: 73 20 74 68 61 74 0a 20 20 20 20 61 74 74 65 6d  s that.    attem
4070: 70 74 73 20 74 6f 20 72 65 61 64 20 74 68 65 6d  pts to read them
4080: 2e 20 20 41 66 74 65 72 20 74 68 65 20 6d 61 73  .  After the mas
4090: 74 65 72 20 6a 6f 75 72 6e 61 6c 20 68 61 73 20  ter journal has 
40a0: 62 65 65 6e 20 64 65 6c 65 74 65 64 2c 0a 20 20  been deleted,.  
40b0: 20 20 74 68 65 20 66 69 6c 65 20 6a 6f 75 72 6e    the file journ
40c0: 61 6c 73 20 77 69 6c 6c 20 6e 6f 20 6c 6f 6e 67  als will no long
40d0: 65 72 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64  er be considered
40e0: 20 68 6f 74 20 61 6e 64 20 74 68 65 20 63 68 61   hot and the cha
40f0: 6e 67 65 73 0a 20 20 20 20 77 69 6c 6c 20 70 65  nges.    will pe
4100: 72 73 69 73 74 2e 0a 20 20 20 20 3c 2f 6c 69 3e  rsist..    </li>
4110: 0a 3c 6c 69 3e 44 65 6c 65 74 65 20 61 6c 6c 20  .<li>Delete all 
4120: 69 6e 64 69 76 69 64 75 61 6c 20 6a 6f 75 72 6e  individual journ
4130: 61 6c 20 66 69 6c 65 73 2e 0a 3c 6c 69 3e 44 72  al files..<li>Dr
4140: 6f 70 20 74 68 65 20 45 58 43 4c 55 53 49 56 45  op the EXCLUSIVE
4150: 20 61 6e 64 20 50 45 4e 44 49 4e 47 20 6c 6f 63   and PENDING loc
4160: 6b 73 20 66 72 6f 6d 20 61 6c 6c 20 64 61 74 61  ks from all data
4170: 62 61 73 65 20 66 69 6c 65 73 2e 0a 20 20 20 20  base files..    
4180: 3c 2f 6c 69 3e 0a 3c 2f 6f 6c 3e 0a 7d 0a 0a 48  </li>.</ol>.}..H
4190: 45 41 44 49 4e 47 20 32 20 7b 57 72 69 74 65 72  EADING 2 {Writer
41a0: 20 73 74 61 72 76 61 74 69 6f 6e 7d 0a 0a 70 75   starvation}..pu
41b0: 74 73 20 7b 0a 3c 70 3e 49 6e 20 53 51 4c 69 74  ts {.<p>In SQLit
41c0: 65 20 76 65 72 73 69 6f 6e 20 32 2c 20 69 66 20  e version 2, if 
41d0: 6d 61 6e 79 20 70 72 6f 63 65 73 73 65 73 20 61  many processes a
41e0: 72 65 20 72 65 61 64 69 6e 67 20 66 72 6f 6d 20  re reading from 
41f0: 74 68 65 20 64 61 74 61 62 61 73 65 2c 0a 69 74  the database,.it
4200: 20 6d 69 67 68 74 20 62 65 20 74 68 65 20 63 61   might be the ca
4210: 73 65 20 74 68 61 74 20 74 68 65 72 65 20 69 73  se that there is
4220: 20 6e 65 76 65 72 20 61 20 74 69 6d 65 20 77 68   never a time wh
4230: 65 6e 20 74 68 65 72 65 20 61 72 65 0a 6e 6f 20  en there are.no 
4240: 61 63 74 69 76 65 20 72 65 61 64 65 72 73 2e 20  active readers. 
4250: 20 41 6e 64 20 69 66 20 74 68 65 72 65 20 69 73   And if there is
4260: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
4270: 20 6f 6e 65 20 72 65 61 64 20 6c 6f 63 6b 20 6f   one read lock o
4280: 6e 20 74 68 65 0a 64 61 74 61 62 61 73 65 2c 20  n the.database, 
4290: 6e 6f 20 70 72 6f 63 65 73 73 20 77 6f 75 6c 64  no process would
42a0: 20 65 76 65 72 20 62 65 20 61 62 6c 65 20 74 6f   ever be able to
42b0: 20 6d 61 6b 65 20 63 68 61 6e 67 65 73 20 74 6f   make changes to
42c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 62 65   the database.be
42d0: 63 61 75 73 65 20 69 74 20 77 6f 75 6c 64 20 62  cause it would b
42e0: 65 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20  e impossible to 
42f0: 61 63 71 75 69 72 65 20 61 20 77 72 69 74 65 20  acquire a write 
4300: 6c 6f 63 6b 2e 20 20 54 68 69 73 20 73 69 74 75  lock.  This situ
4310: 61 74 69 6f 6e 0a 69 73 20 63 61 6c 6c 65 64 20  ation.is called 
4320: 3c 65 6d 3e 77 72 69 74 65 72 20 73 74 61 72 76  <em>writer starv
4330: 61 74 69 6f 6e 3c 2f 65 6d 3e 2e 3c 2f 70 3e 0a  ation</em>.</p>.
4340: 0a 3c 70 3e 53 51 4c 69 74 65 20 76 65 72 73 69  .<p>SQLite versi
4350: 6f 6e 20 33 20 73 65 65 6b 73 20 74 6f 20 61 76  on 3 seeks to av
4360: 6f 69 64 20 77 72 69 74 65 72 20 73 74 61 72 76  oid writer starv
4370: 61 74 69 6f 6e 20 74 68 72 6f 75 67 68 20 74 68  ation through th
4380: 65 20 75 73 65 20 6f 66 0a 74 68 65 20 50 45 4e  e use of.the PEN
4390: 44 49 4e 47 20 6c 6f 63 6b 2e 20 20 54 68 65 20  DING lock.  The 
43a0: 50 45 4e 44 49 4e 47 20 6c 6f 63 6b 20 61 6c 6c  PENDING lock all
43b0: 6f 77 73 20 65 78 69 73 74 69 6e 67 20 72 65 61  ows existing rea
43c0: 64 65 72 73 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ders to continue
43d0: 0a 62 75 74 20 70 72 65 76 65 6e 74 73 20 6e 65  .but prevents ne
43e0: 77 20 72 65 61 64 65 72 73 20 66 72 6f 6d 20 63  w readers from c
43f0: 6f 6e 6e 65 63 74 69 6e 67 20 74 6f 20 74 68 65  onnecting to the
4400: 20 64 61 74 61 62 61 73 65 2e 20 20 53 6f 20 77   database.  So w
4410: 68 65 6e 20 61 0a 70 72 6f 63 65 73 73 20 77 61  hen a.process wa
4420: 6e 74 73 20 74 6f 20 77 72 69 74 65 20 61 20 62  nts to write a b
4430: 75 73 79 20 64 61 74 61 62 61 73 65 2c 20 69 74  usy database, it
4440: 20 63 61 6e 20 73 65 74 20 61 20 50 45 4e 44 49   can set a PENDI
4450: 4e 47 20 6c 6f 63 6b 20 77 68 69 63 68 0a 77 69  NG lock which.wi
4460: 6c 6c 20 70 72 65 76 65 6e 74 20 6e 65 77 20 72  ll prevent new r
4470: 65 61 64 65 72 73 20 66 72 6f 6d 20 63 6f 6d 69  eaders from comi
4480: 6e 67 20 69 6e 2e 20 20 41 73 73 75 6d 69 6e 67  ng in.  Assuming
4490: 20 65 78 69 73 74 69 6e 67 20 72 65 61 64 65 72   existing reader
44a0: 73 20 64 6f 0a 65 76 65 6e 74 75 61 6c 6c 79 20  s do.eventually 
44b0: 63 6f 6d 70 6c 65 74 65 2c 20 61 6c 6c 20 53 48  complete, all SH
44c0: 41 52 45 44 20 6c 6f 63 6b 73 20 77 69 6c 6c 20  ARED locks will 
44d0: 65 76 65 6e 74 75 61 6c 6c 79 20 63 6c 65 61 72  eventually clear
44e0: 20 61 6e 64 20 74 68 65 0a 77 72 69 74 65 72 20   and the.writer 
44f0: 77 69 6c 6c 20 62 65 20 67 69 76 65 6e 20 61 20  will be given a 
4500: 63 68 61 6e 63 65 20 74 6f 20 6d 61 6b 65 20 69  chance to make i
4510: 74 73 20 63 68 61 6e 67 65 73 2e 3c 2f 70 3e 0a  ts changes.</p>.
4520: 7d 0a 0a 48 45 41 44 49 4e 47 20 31 20 7b 48 6f  }..HEADING 1 {Ho
4530: 77 20 54 6f 20 43 6f 72 72 75 70 74 20 59 6f 75  w To Corrupt You
4540: 72 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73  r Database Files
4550: 7d 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 54 68 65  }..puts {.<p>The
4560: 20 70 61 67 65 72 20 6d 6f 64 75 6c 65 20 69 73   pager module is
4570: 20 72 6f 62 75 73 74 20 62 75 74 20 69 74 20 69   robust but it i
4580: 73 20 6e 6f 74 20 63 6f 6d 70 6c 65 74 65 6c 79  s not completely
4590: 20 66 61 69 6c 73 61 66 65 2e 0a 49 74 20 63 61   failsafe..It ca
45a0: 6e 20 62 65 20 73 75 62 76 65 72 74 65 64 2e 20  n be subverted. 
45b0: 20 54 68 69 73 20 73 65 63 74 69 6f 6e 20 61 74   This section at
45c0: 74 65 6d 70 74 73 20 74 6f 20 69 64 65 6e 74 69  tempts to identi
45d0: 66 79 20 61 6e 64 20 65 78 70 6c 61 69 6e 0a 74  fy and explain.t
45e0: 68 65 20 72 69 73 6b 73 2e 3c 2f 70 3e 0a 0a 3c  he risks.</p>..<
45f0: 70 3e 0a 43 6c 65 61 72 6c 79 2c 20 61 20 68 61  p>.Clearly, a ha
4600: 72 64 77 61 72 65 20 6f 72 20 6f 70 65 72 61 74  rdware or operat
4610: 69 6e 67 20 73 79 73 74 65 6d 20 66 61 75 6c 74  ing system fault
4620: 20 74 68 61 74 20 69 6e 74 72 6f 64 75 63 65 73   that introduces
4630: 20 69 6e 63 6f 72 72 65 63 74 20 64 61 74 61 0a   incorrect data.
4640: 69 6e 74 6f 20 74 68 65 20 6d 69 64 64 6c 65 20  into the middle 
4650: 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
4660: 66 69 6c 65 20 6f 72 20 6a 6f 75 72 6e 61 6c 20  file or journal 
4670: 77 69 6c 6c 20 63 61 75 73 65 20 70 72 6f 62 6c  will cause probl
4680: 65 6d 73 2e 0a 4c 69 6b 65 77 69 73 65 2c 20 0a  ems..Likewise, .
4690: 69 66 20 61 20 72 6f 67 75 65 20 70 72 6f 63 65  if a rogue proce
46a0: 73 73 20 6f 70 65 6e 73 20 61 20 64 61 74 61 62  ss opens a datab
46b0: 61 73 65 20 66 69 6c 65 20 6f 72 20 6a 6f 75 72  ase file or jour
46c0: 6e 61 6c 20 61 6e 64 20 77 72 69 74 65 73 20 6d  nal and writes m
46d0: 61 6c 66 6f 72 6d 65 64 0a 64 61 74 61 20 69 6e  alformed.data in
46e0: 74 6f 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  to the middle of
46f0: 20 69 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61   it, then the da
4700: 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 63 6f  tabase will beco
4710: 6d 65 20 63 6f 72 72 75 70 74 2e 0a 54 68 65 72  me corrupt..Ther
4720: 65 20 69 73 20 6e 6f 74 20 6d 75 63 68 20 74 68  e is not much th
4730: 61 74 20 63 61 6e 20 62 65 20 64 6f 6e 65 20 61  at can be done a
4740: 62 6f 75 74 20 74 68 65 73 65 20 6b 69 6e 64 73  bout these kinds
4750: 20 6f 66 20 70 72 6f 62 6c 65 6d 73 0a 73 6f 20   of problems.so 
4760: 74 68 65 79 20 61 72 65 20 67 69 76 65 6e 20 6e  they are given n
4770: 6f 20 66 75 72 74 68 65 72 20 61 74 74 65 6e 74  o further attent
4780: 69 6f 6e 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 53  ion..</p>..<p>.S
4790: 51 4c 69 74 65 20 75 73 65 73 20 50 4f 53 49 58  QLite uses POSIX
47a0: 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 73 20   advisory locks 
47b0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 6c 6f 63  to implement loc
47c0: 6b 69 6e 67 20 6f 6e 20 55 6e 69 78 2e 20 20 4f  king on Unix.  O
47d0: 6e 0a 77 69 6e 64 6f 77 73 20 69 74 20 75 73 65  n.windows it use
47e0: 73 20 74 68 65 20 4c 6f 63 6b 46 69 6c 65 28 29  s the LockFile()
47f0: 2c 20 4c 6f 63 6b 46 69 6c 65 45 78 28 29 2c 20  , LockFileEx(), 
4800: 61 6e 64 20 55 6e 6c 6f 63 6b 46 69 6c 65 28 29  and UnlockFile()
4810: 20 73 79 73 74 65 6d 0a 63 61 6c 6c 73 2e 20 20   system.calls.  
4820: 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
4830: 68 61 74 20 74 68 65 73 65 20 73 79 73 74 65 6d  hat these system
4840: 20 63 61 6c 6c 73 20 61 6c 6c 20 77 6f 72 6b 20   calls all work 
4850: 61 73 20 61 64 76 65 72 74 69 73 65 64 2e 20 20  as advertised.  
4860: 49 66 0a 74 68 61 74 20 69 73 20 6e 6f 74 20 74  If.that is not t
4870: 68 65 20 63 61 73 65 2c 20 74 68 65 6e 20 64 61  he case, then da
4880: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
4890: 6e 20 63 61 6e 20 72 65 73 75 6c 74 2e 20 20 4f  n can result.  O
48a0: 6e 65 20 73 68 6f 75 6c 64 0a 6e 6f 74 65 20 74  ne should.note t
48b0: 68 61 74 20 50 4f 53 49 58 20 61 64 76 69 73 6f  hat POSIX adviso
48c0: 72 79 20 6c 6f 63 6b 69 6e 67 20 69 73 20 6b 6e  ry locking is kn
48d0: 6f 77 6e 20 74 6f 20 62 65 20 62 75 67 67 79 20  own to be buggy 
48e0: 6f 72 20 65 76 65 6e 20 75 6e 69 6d 70 6c 65 6d  or even unimplem
48f0: 65 6e 74 65 64 0a 6f 6e 20 6d 61 6e 79 20 4e 46  ented.on many NF
4900: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
4910: 73 20 28 69 6e 63 6c 75 64 69 6e 67 20 72 65 63  s (including rec
4920: 65 6e 74 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ent versions of 
4930: 4d 61 63 20 4f 53 20 58 29 0a 61 6e 64 20 74 68  Mac OS X).and th
4940: 61 74 20 74 68 65 72 65 20 61 72 65 20 72 65 70  at there are rep
4950: 6f 72 74 73 20 6f 66 20 6c 6f 63 6b 69 6e 67 20  orts of locking 
4960: 70 72 6f 62 6c 65 6d 73 0a 66 6f 72 20 6e 65 74  problems.for net
4970: 77 6f 72 6b 20 66 69 6c 65 73 79 73 74 65 6d 73  work filesystems
4980: 20 75 6e 64 65 72 20 77 69 6e 64 6f 77 73 2e 20   under windows. 
4990: 20 59 6f 75 72 20 62 65 73 74 20 64 65 66 65 6e   Your best defen
49a0: 73 65 20 69 73 20 74 6f 20 6e 6f 74 0a 75 73 65  se is to not.use
49b0: 20 53 51 4c 69 74 65 20 66 6f 72 20 66 69 6c 65   SQLite for file
49c0: 73 20 6f 6e 20 61 20 6e 65 74 77 6f 72 6b 20 66  s on a network f
49d0: 69 6c 65 73 79 73 74 65 6d 2e 0a 3c 2f 70 3e 0a  ilesystem..</p>.
49e0: 0a 3c 70 3e 0a 53 51 4c 69 74 65 20 75 73 65 73  .<p>.SQLite uses
49f0: 20 74 68 65 20 66 73 79 6e 63 28 29 20 73 79 73   the fsync() sys
4a00: 74 65 6d 20 63 61 6c 6c 20 74 6f 20 66 6c 75 73  tem call to flus
4a10: 68 20 64 61 74 61 20 74 6f 20 74 68 65 20 64 69  h data to the di
4a20: 73 6b 20 75 6e 64 65 72 20 55 6e 69 78 20 61 6e  sk under Unix an
4a30: 64 0a 69 74 20 75 73 65 73 20 74 68 65 20 46 6c  d.it uses the Fl
4a40: 75 73 68 46 69 6c 65 42 75 66 66 65 72 73 28 29  ushFileBuffers()
4a50: 20 74 6f 20 64 6f 20 74 68 65 20 73 61 6d 65 20   to do the same 
4a60: 75 6e 64 65 72 20 77 69 6e 64 6f 77 73 2e 20 20  under windows.  
4a70: 4f 6e 63 65 20 61 67 61 69 6e 2c 0a 53 51 4c 69  Once again,.SQLi
4a80: 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
4a90: 74 68 65 73 65 20 6f 70 65 72 61 74 69 6e 67 20  these operating 
4aa0: 73 79 73 74 65 6d 20 73 65 72 76 69 63 65 73 20  system services 
4ab0: 66 75 6e 63 74 69 6f 6e 20 61 73 20 61 64 76 65  function as adve
4ac0: 72 74 69 73 65 64 2e 0a 42 75 74 20 69 74 20 68  rtised..But it h
4ad0: 61 73 20 62 65 65 6e 20 72 65 70 6f 72 74 65 64  as been reported
4ae0: 20 74 68 61 74 20 66 73 79 6e 63 28 29 20 61 6e   that fsync() an
4af0: 64 20 46 6c 75 73 68 46 69 6c 65 42 75 66 66 65  d FlushFileBuffe
4b00: 72 73 28 29 20 64 6f 20 6e 6f 74 20 61 6c 77 61  rs() do not alwa
4b10: 79 73 0a 77 6f 72 6b 20 63 6f 72 72 65 63 74 6c  ys.work correctl
4b20: 79 2c 20 65 73 70 65 63 69 61 6c 6c 79 20 77 69  y, especially wi
4b30: 74 68 20 69 6e 65 78 70 65 6e 73 69 76 65 20 49  th inexpensive I
4b40: 44 45 20 64 69 73 6b 73 2e 20 20 41 70 70 61 72  DE disks.  Appar
4b50: 65 6e 74 6c 79 20 73 6f 6d 65 0a 6d 61 6e 75 66  ently some.manuf
4b60: 61 63 74 75 72 65 73 20 6f 66 20 49 44 45 20 64  actures of IDE d
4b70: 69 73 6b 73 20 68 61 76 65 20 64 65 66 65 63 74  isks have defect
4b80: 69 76 65 20 63 6f 6e 74 72 6f 6c 6c 65 72 20 63  ive controller c
4b90: 68 69 70 73 20 74 68 61 74 20 72 65 70 6f 72 74  hips that report
4ba0: 0a 74 68 61 74 20 64 61 74 61 20 68 61 73 20 72  .that data has r
4bb0: 65 61 63 68 65 64 20 74 68 65 20 64 69 73 6b 20  eached the disk 
4bc0: 73 75 72 66 61 63 65 20 77 68 65 6e 20 69 6e 20  surface when in 
4bd0: 66 61 63 74 20 74 68 65 20 64 61 74 61 20 69 73  fact the data is
4be0: 20 73 74 69 6c 6c 0a 69 6e 20 76 6f 6c 61 74 69   still.in volati
4bf0: 6c 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  le cache memory 
4c00: 69 6e 20 74 68 65 20 64 69 73 6b 20 64 72 69 76  in the disk driv
4c10: 65 20 65 6c 65 63 74 72 6f 6e 69 63 73 2e 20 20  e electronics.  
4c20: 54 68 65 72 65 20 61 72 65 20 61 6c 73 6f 0a 72  There are also.r
4c30: 65 70 6f 72 74 73 20 74 68 61 74 20 77 69 6e 64  eports that wind
4c40: 6f 77 73 20 73 6f 6d 65 74 69 6d 65 73 20 63 68  ows sometimes ch
4c50: 6f 6f 73 65 73 20 74 6f 20 69 67 6e 6f 72 65 20  ooses to ignore 
4c60: 46 6c 75 73 68 46 69 6c 65 42 75 66 66 65 72 73  FlushFileBuffers
4c70: 28 29 20 66 6f 72 0a 75 6e 73 70 65 63 69 66 69  () for.unspecifi
4c80: 65 64 20 72 65 61 73 6f 6e 73 2e 20 20 54 68 65  ed reasons.  The
4c90: 20 61 75 74 68 6f 72 20 63 61 6e 6e 6f 74 20 76   author cannot v
4ca0: 65 72 69 66 79 20 61 6e 79 20 6f 66 20 74 68 65  erify any of the
4cb0: 73 65 20 72 65 70 6f 72 74 73 2e 0a 42 75 74 20  se reports..But 
4cc0: 69 66 20 74 68 65 79 20 61 72 65 20 74 72 75 65  if they are true
4cd0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
4ce0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
4cf0: 69 6f 6e 20 69 73 20 61 20 70 6f 73 73 69 62 69  ion is a possibi
4d00: 6c 69 74 79 0a 66 6f 6c 6c 6f 77 69 6e 67 20 61  lity.following a
4d10: 6e 20 75 6e 65 78 70 65 63 74 65 64 20 70 6f 77  n unexpected pow
4d20: 65 72 20 6c 6f 73 73 2e 20 20 54 68 65 73 65 20  er loss.  These 
4d30: 61 72 65 20 68 61 72 64 77 61 72 65 20 61 6e 64  are hardware and
4d40: 2f 6f 72 20 6f 70 65 72 61 74 69 6e 67 0a 73 79  /or operating.sy
4d50: 73 74 65 6d 20 62 75 67 73 20 74 68 61 74 20 53  stem bugs that S
4d60: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
4d70: 74 6f 20 64 65 66 65 6e 64 20 61 67 61 69 6e 73  to defend agains
4d80: 74 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49 66 20  t..</p>..<p>.If 
4d90: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
4da0: 20 66 61 69 6c 75 72 65 20 6f 63 63 75 72 73 20   failure occurs 
4db0: 61 6e 64 20 72 65 73 75 6c 74 73 20 69 6e 20 61  and results in a
4dc0: 20 68 6f 74 20 6a 6f 75 72 6e 61 6c 20 62 75 74   hot journal but
4dd0: 20 74 68 61 74 0a 6a 6f 75 72 6e 61 6c 20 69 73   that.journal is
4de0: 20 64 65 6c 65 74 65 64 2c 20 74 68 65 20 6e 65   deleted, the ne
4df0: 78 74 20 70 72 6f 63 65 73 73 20 74 6f 20 6f 70  xt process to op
4e00: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4e10: 77 69 6c 6c 20 6e 6f 74 0a 6b 6e 6f 77 20 74 68  will not.know th
4e20: 61 74 20 69 74 20 63 6f 6e 74 61 69 6e 73 20 63  at it contains c
4e30: 68 61 6e 67 65 73 20 74 68 61 74 20 6e 65 65 64  hanges that need
4e40: 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61   to be rolled ba
4e50: 63 6b 2e 20 20 54 68 65 20 72 6f 6c 6c 62 61 63  ck.  The rollbac
4e60: 6b 0a 77 69 6c 6c 20 6e 6f 74 20 6f 63 63 75 72  k.will not occur
4e70: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
4e80: 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
4e90: 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
4ea0: 74 20 73 74 61 74 65 2e 0a 52 6f 6c 6c 62 61 63  t state..Rollbac
4eb0: 6b 20 6a 6f 75 72 6e 61 6c 73 20 6d 69 67 68 74  k journals might
4ec0: 20 62 65 20 64 65 6c 65 74 65 64 20 66 6f 72 20   be deleted for 
4ed0: 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 72 65  any number of re
4ee0: 61 73 6f 6e 73 3a 0a 3c 2f 70 3e 0a 0a 3c 75 6c  asons:.</p>..<ul
4ef0: 3e 0a 3c 6c 69 3e 41 6e 20 61 64 6d 69 6e 69 73  >.<li>An adminis
4f00: 74 72 61 74 6f 72 20 6d 69 67 68 74 20 62 65 20  trator might be 
4f10: 63 6c 65 61 6e 69 6e 67 20 75 70 20 61 66 74 65  cleaning up afte
4f20: 72 20 61 6e 20 4f 53 20 63 72 61 73 68 20 6f 72  r an OS crash or
4f30: 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65 2c 0a   power failure,.
4f40: 20 20 20 20 73 65 65 20 74 68 65 20 6a 6f 75 72      see the jour
4f50: 6e 61 6c 20 66 69 6c 65 2c 20 74 68 69 6e 6b 20  nal file, think 
4f60: 69 74 20 69 73 20 6a 75 6e 6b 2c 20 61 6e 64 20  it is junk, and 
4f70: 64 65 6c 65 74 65 20 69 74 2e 3c 2f 6c 69 3e 0a  delete it.</li>.
4f80: 3c 6c 69 3e 53 6f 6d 65 6f 6e 65 20 28 6f 72 20  <li>Someone (or 
4f90: 73 6f 6d 65 20 70 72 6f 63 65 73 73 29 20 6d 69  some process) mi
4fa0: 67 68 74 20 72 65 6e 61 6d 65 20 74 68 65 20 64  ght rename the d
4fb0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 62 75 74  atabase file but
4fc0: 20 66 61 69 6c 20 74 6f 0a 20 20 20 20 61 6c 73   fail to.    als
4fd0: 6f 20 72 65 6e 61 6d 65 20 69 74 73 20 61 73 73  o rename its ass
4fe0: 6f 63 69 61 74 65 64 20 6a 6f 75 72 6e 61 6c 2e  ociated journal.
4ff0: 3c 2f 6c 69 3e 0a 3c 6c 69 3e 49 66 20 74 68 65  </li>.<li>If the
5000: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
5010: 61 73 20 61 6c 69 61 73 65 73 20 28 68 61 72 64  as aliases (hard
5020: 20 6f 72 20 73 6f 66 74 20 6c 69 6e 6b 73 29 20   or soft links) 
5030: 61 6e 64 20 74 68 65 20 66 69 6c 65 0a 20 20 20  and the file.   
5040: 20 69 73 20 6f 70 65 6e 65 64 20 62 79 20 61 20   is opened by a 
5050: 64 69 66 66 65 72 65 6e 74 20 61 6c 69 61 73 20  different alias 
5060: 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 75 73 65  than the one use
5070: 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20  d to create the 
5080: 6a 6f 75 72 6e 61 6c 2c 0a 20 20 20 20 74 68 65  journal,.    the
5090: 6e 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 69  n the journal wi
50a0: 6c 6c 20 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2e  ll not be found.
50b0: 20 20 54 6f 20 61 76 6f 69 64 20 74 68 69 73 20    To avoid this 
50c0: 70 72 6f 62 6c 65 6d 2c 20 79 6f 75 20 73 68 6f  problem, you sho
50d0: 75 6c 64 0a 20 20 20 20 6e 6f 74 20 63 72 65 61  uld.    not crea
50e0: 74 65 20 6c 69 6e 6b 73 20 74 6f 20 53 51 4c 69  te links to SQLi
50f0: 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
5100: 73 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 46 69 6c 65  s.</li>.<li>File
5110: 73 79 73 74 65 6d 20 63 6f 72 72 75 70 74 69 6f  system corruptio
5120: 6e 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 70 6f  n following a po
5130: 77 65 72 20 66 61 69 6c 75 72 65 20 6d 69 67 68  wer failure migh
5140: 74 20 63 61 75 73 65 20 74 68 65 0a 20 20 20 20  t cause the.    
5150: 6a 6f 75 72 6e 61 6c 20 74 6f 20 62 65 20 72 65  journal to be re
5160: 6e 61 6d 65 64 20 6f 72 20 64 65 6c 65 74 65 64  named or deleted
5170: 2e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a 0a 3c 70  .</li>.</ul>..<p
5180: 3e 0a 54 68 65 20 6c 61 73 74 20 28 66 6f 75 72  >.The last (four
5190: 74 68 29 20 62 75 6c 6c 65 74 20 61 62 6f 76 65  th) bullet above
51a0: 20 6d 65 72 69 74 73 20 61 64 64 69 74 69 6f 6e   merits addition
51b0: 61 6c 20 63 6f 6d 6d 65 6e 74 2e 20 20 57 68 65  al comment.  Whe
51c0: 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 73  n SQLite creates
51d0: 0a 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20  .a journal file 
51e0: 6f 6e 20 55 6e 69 78 2c 20 69 74 20 6f 70 65 6e  on Unix, it open
51f0: 73 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  s the directory 
5200: 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  that contains th
5210: 61 74 20 66 69 6c 65 20 61 6e 64 0a 63 61 6c 6c  at file and.call
5220: 73 20 66 73 79 6e 63 28 29 20 6f 6e 20 74 68 65  s fsync() on the
5230: 20 64 69 72 65 63 74 6f 72 79 2c 20 69 6e 20 61   directory, in a
5240: 6e 20 65 66 66 6f 72 74 20 74 6f 20 70 75 73 68  n effort to push
5250: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 69   the directory i
5260: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 74 6f 20 64 69  nformation.to di
5270: 73 6b 2e 20 20 42 75 74 20 73 75 70 70 6f 73 65  sk.  But suppose
5280: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
5290: 65 73 73 20 69 73 20 61 64 64 69 6e 67 20 6f 72  ess is adding or
52a0: 20 72 65 6d 6f 76 69 6e 67 20 75 6e 72 65 6c 61   removing unrela
52b0: 74 65 64 0a 66 69 6c 65 73 20 74 6f 20 74 68 65  ted.files to the
52c0: 20 64 69 72 65 63 74 6f 72 79 20 74 68 61 74 20   directory that 
52d0: 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
52e0: 61 62 61 73 65 20 61 6e 64 20 6a 6f 75 72 6e 61  abase and journa
52f0: 6c 20 61 74 20 74 68 65 20 74 68 65 0a 6d 6f 6d  l at the the.mom
5300: 65 6e 74 20 6f 66 20 61 20 70 6f 77 65 72 20 66  ent of a power f
5310: 61 69 6c 75 72 65 2e 20 20 54 68 65 20 73 75 70  ailure.  The sup
5320: 70 6f 73 65 64 6c 79 20 75 6e 72 65 6c 61 74 65  posedly unrelate
5330: 64 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 69  d actions of thi
5340: 73 20 6f 74 68 65 72 0a 70 72 6f 63 65 73 73 20  s other.process 
5350: 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
5360: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  the journal file
5370: 20 62 65 69 6e 67 20 64 72 6f 70 70 65 64 20 66   being dropped f
5380: 72 6f 6d 20 74 68 65 20 64 69 72 65 63 74 6f 72  rom the director
5390: 79 20 61 6e 64 0a 6d 6f 76 65 64 20 69 6e 74 6f  y and.moved into
53a0: 20 22 6c 6f 73 74 2b 66 6f 75 6e 64 22 2e 20 20   "lost+found".  
53b0: 54 68 69 73 20 69 73 20 61 6e 20 75 6e 6c 69 6b  This is an unlik
53c0: 65 6c 79 20 73 63 65 6e 61 72 69 6f 2c 20 62 75  ely scenario, bu
53d0: 74 20 69 74 20 63 6f 75 6c 64 20 68 61 70 70 65  t it could happe
53e0: 6e 2e 0a 54 68 65 20 62 65 73 74 20 64 65 66 65  n..The best defe
53f0: 6e 73 65 73 20 61 72 65 20 74 6f 20 75 73 65 20  nses are to use 
5400: 61 20 6a 6f 75 72 6e 61 6c 69 6e 67 20 66 69 6c  a journaling fil
5410: 65 73 79 73 74 65 6d 20 6f 72 20 74 6f 20 6b 65  esystem or to ke
5420: 65 70 20 74 68 65 0a 64 61 74 61 62 61 73 65 20  ep the.database 
5430: 61 6e 64 20 6a 6f 75 72 6e 61 6c 20 69 6e 20 61  and journal in a
5440: 20 64 69 72 65 63 74 6f 72 79 20 62 79 20 74 68   directory by th
5450: 65 6d 73 65 6c 76 65 73 2e 0a 3c 2f 70 3e 0a 0a  emselves..</p>..
5460: 3c 70 3e 0a 46 6f 72 20 61 20 63 6f 6d 6d 69 74  <p>.For a commit
5470: 20 69 6e 76 6f 6c 76 69 6e 67 20 6d 75 6c 74 69   involving multi
5480: 70 6c 65 20 64 61 74 61 62 61 73 65 73 20 61 6e  ple databases an
5490: 64 20 61 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e  d a master journ
54a0: 61 6c 2c 20 69 66 20 74 68 65 0a 76 61 72 69 6f  al, if the.vario
54b0: 75 73 20 64 61 74 61 62 61 73 65 73 20 77 65 72  us databases wer
54c0: 65 20 6f 6e 20 64 69 66 66 65 72 65 6e 74 20 64  e on different d
54d0: 69 73 6b 20 76 6f 6c 75 6d 65 73 20 61 6e 64 20  isk volumes and 
54e0: 61 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65 20  a power failure 
54f0: 6f 63 63 75 72 73 0a 64 75 72 69 6e 67 20 74 68  occurs.during th
5500: 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 6e 20 77  e commit, then w
5510: 68 65 6e 20 74 68 65 20 6d 61 63 68 69 6e 65 20  hen the machine 
5520: 63 6f 6d 65 73 20 62 61 63 6b 20 75 70 20 74 68  comes back up th
5530: 65 20 64 69 73 6b 73 20 6d 69 67 68 74 0a 62 65  e disks might.be
5540: 20 72 65 6d 6f 75 6e 74 65 64 20 77 69 74 68 20   remounted with 
5550: 64 69 66 66 65 72 65 6e 74 20 6e 61 6d 65 73 2e  different names.
5560: 20 20 4f 72 20 73 6f 6d 65 20 64 69 73 6b 73 20    Or some disks 
5570: 6d 69 67 68 74 20 6e 6f 74 20 62 65 20 6d 6f 75  might not be mou
5580: 6e 74 65 64 0a 61 74 20 61 6c 6c 2e 20 20 20 57  nted.at all.   W
5590: 68 65 6e 20 74 68 69 73 20 68 61 70 70 65 6e 73  hen this happens
55a0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
55b0: 66 69 6c 65 20 6a 6f 75 72 6e 61 6c 73 20 61 6e  file journals an
55c0: 64 20 74 68 65 20 6d 61 73 74 65 72 0a 6a 6f 75  d the master.jou
55d0: 72 6e 61 6c 20 6d 69 67 68 74 20 6e 6f 74 20 62  rnal might not b
55e0: 65 20 61 62 6c 65 20 74 6f 20 66 69 6e 64 20 65  e able to find e
55f0: 61 63 68 20 6f 74 68 65 72 2e 20 54 68 65 20 77  ach other. The w
5600: 6f 72 73 74 20 6f 75 74 63 6f 6d 65 20 66 72 6f  orst outcome fro
5610: 6d 0a 74 68 69 73 20 73 63 65 6e 61 72 69 6f 20  m.this scenario 
5620: 69 73 20 74 68 61 74 20 74 68 65 20 63 6f 6d 6d  is that the comm
5630: 69 74 20 63 65 61 73 65 73 20 74 6f 20 62 65 20  it ceases to be 
5640: 61 74 6f 6d 69 63 2e 20 20 0a 53 6f 6d 65 20 64  atomic.  .Some d
5650: 61 74 61 62 61 73 65 73 20 6d 69 67 68 74 20 62  atabases might b
5660: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e  e rolled back an
5670: 64 20 6f 74 68 65 72 73 20 6d 69 67 68 74 20 6e  d others might n
5680: 6f 74 2e 20 0a 41 6c 6c 20 64 61 74 61 62 61 73  ot. .All databas
5690: 65 73 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  es will continue
56a0: 20 74 6f 20 62 65 20 73 65 6c 66 2d 63 6f 6e 73   to be self-cons
56b0: 69 73 74 65 6e 74 2e 0a 54 6f 20 64 65 66 65 6e  istent..To defen
56c0: 64 20 61 67 61 69 6e 73 74 20 74 68 69 73 20 70  d against this p
56d0: 72 6f 62 6c 65 6d 2c 20 6b 65 65 70 20 61 6c 6c  roblem, keep all
56e0: 20 64 61 74 61 62 61 73 65 73 0a 6f 6e 20 74 68   databases.on th
56f0: 65 20 73 61 6d 65 20 64 69 73 6b 20 76 6f 6c 75  e same disk volu
5700: 6d 65 20 61 6e 64 2f 6f 72 20 72 65 6d 6f 75 6e  me and/or remoun
5710: 74 20 64 69 73 6b 73 20 75 73 69 6e 67 20 65 78  t disks using ex
5720: 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 6e  actly the same n
5730: 61 6d 65 73 0a 61 66 74 65 72 20 61 20 70 6f 77  ames.after a pow
5740: 65 72 20 66 61 69 6c 75 72 65 2e 0a 3c 2f 70 3e  er failure..</p>
5750: 0a 7d 0a 0a 48 45 41 44 49 4e 47 20 31 20 7b 54  .}..HEADING 1 {T
5760: 72 61 6e 73 61 63 74 69 6f 6e 20 43 6f 6e 74 72  ransaction Contr
5770: 6f 6c 20 41 74 20 54 68 65 20 53 51 4c 20 4c 65  ol At The SQL Le
5780: 76 65 6c 7d 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e  vel}..puts {.<p>
5790: 0a 54 68 65 20 63 68 61 6e 67 65 73 20 74 6f 20  .The changes to 
57a0: 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 63 6f 6e 63  locking and conc
57b0: 75 72 72 65 6e 63 79 20 63 6f 6e 74 72 6f 6c 20  urrency control 
57c0: 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
57d0: 6e 20 33 20 61 6c 73 6f 0a 69 6e 74 72 6f 64 75  n 3 also.introdu
57e0: 63 65 20 73 6f 6d 65 20 73 75 62 74 6c 65 20 63  ce some subtle c
57f0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 77 61  hanges in the wa
5800: 79 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 77  y transactions w
5810: 6f 72 6b 20 61 74 20 74 68 65 20 53 51 4c 0a 6c  ork at the SQL.l
5820: 61 6e 67 75 61 67 65 20 6c 65 76 65 6c 2e 0a 42  anguage level..B
5830: 79 20 64 65 66 61 75 6c 74 2c 20 53 51 4c 69 74  y default, SQLit
5840: 65 20 76 65 72 73 69 6f 6e 20 33 20 6f 70 65 72  e version 3 oper
5850: 61 74 65 73 20 69 6e 20 3c 65 6d 3e 61 75 74 6f  ates in <em>auto
5860: 63 6f 6d 6d 69 74 3c 2f 65 6d 3e 20 6d 6f 64 65  commit</em> mode
5870: 2e 0a 49 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  ..In autocommit 
5880: 6d 6f 64 65 2c 0a 61 6c 6c 20 63 68 61 6e 67 65  mode,.all change
5890: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
58a0: 65 20 61 72 65 20 63 6f 6d 6d 69 74 74 65 64 20  e are committed 
58b0: 61 73 20 73 6f 6f 6e 20 61 73 20 61 6c 6c 20 6f  as soon as all o
58c0: 70 65 72 61 74 69 6f 6e 73 20 61 73 73 6f 63 69  perations associ
58d0: 61 74 65 64 0a 77 69 74 68 20 74 68 65 20 63 75  ated.with the cu
58e0: 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 63  rrent database c
58f0: 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f 6d 70 6c 65  onnection comple
5900: 74 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  te.</p>..<p>The 
5910: 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 22 42 45 47  SQL command "BEG
5920: 49 4e 20 54 52 41 4e 53 41 43 54 49 4f 4e 22 20  IN TRANSACTION" 
5930: 28 74 68 65 20 54 52 41 4e 53 41 43 54 49 4f 4e  (the TRANSACTION
5940: 20 6b 65 79 77 6f 72 64 0a 69 73 20 6f 70 74 69   keyword.is opti
5950: 6f 6e 61 6c 29 20 69 73 20 75 73 65 64 20 74 6f  onal) is used to
5960: 20 74 61 6b 65 20 53 51 4c 69 74 65 20 6f 75 74   take SQLite out
5970: 20 6f 66 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   of autocommit m
5980: 6f 64 65 2e 0a 4e 6f 74 65 20 74 68 61 74 20 74  ode..Note that t
5990: 68 65 20 42 45 47 49 4e 20 63 6f 6d 6d 61 6e 64  he BEGIN command
59a0: 20 64 6f 65 73 20 6e 6f 74 20 61 63 71 75 69 72   does not acquir
59b0: 65 20 61 6e 79 20 6c 6f 63 6b 73 20 6f 6e 20 74  e any locks on t
59c0: 68 65 20 64 61 74 61 62 61 73 65 2e 0a 41 66 74  he database..Aft
59d0: 65 72 20 61 20 42 45 47 49 4e 20 63 6f 6d 6d 61  er a BEGIN comma
59e0: 6e 64 2c 20 61 20 53 48 41 52 45 44 20 6c 6f 63  nd, a SHARED loc
59f0: 6b 20 77 69 6c 6c 20 62 65 20 61 63 71 75 69 72  k will be acquir
5a00: 65 64 20 77 68 65 6e 20 74 68 65 20 66 69 72 73  ed when the firs
5a10: 74 0a 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  t.SELECT stateme
5a20: 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2e 20  nt is executed. 
5a30: 20 41 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   A RESERVED lock
5a40: 20 77 69 6c 6c 20 62 65 20 61 63 71 75 69 72 65   will be acquire
5a50: 64 20 77 68 65 6e 0a 74 68 65 20 66 69 72 73 74  d when.the first
5a60: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
5a70: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
5a80: 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
5a90: 2e 20 20 4e 6f 20 45 58 43 4c 55 53 49 56 45 0a  .  No EXCLUSIVE.
5aa0: 6c 6f 63 6b 20 69 73 20 61 63 71 75 69 72 65 64  lock is acquired
5ab0: 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
5ac0: 65 20 6d 65 6d 6f 72 79 20 63 61 63 68 65 20 66  e memory cache f
5ad0: 69 6c 6c 73 20 75 70 20 61 6e 64 20 6d 75 73 74  ills up and must
5ae0: 0a 62 65 20 73 70 69 6c 6c 65 64 20 74 6f 20 64  .be spilled to d
5af0: 69 73 6b 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  isk or until the
5b00: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d   transaction com
5b10: 6d 69 74 73 2e 20 20 49 6e 20 74 68 69 73 20 77  mits.  In this w
5b20: 61 79 2c 0a 74 68 65 20 73 79 73 74 65 6d 20 64  ay,.the system d
5b30: 65 6c 61 79 73 20 62 6c 6f 63 6b 69 6e 67 20 72  elays blocking r
5b40: 65 61 64 20 61 63 63 65 73 73 20 74 6f 20 74 68  ead access to th
5b50: 65 20 66 69 6c 65 20 66 69 6c 65 20 75 6e 74 69  e file file unti
5b60: 6c 20 74 68 65 0a 6c 61 73 74 20 70 6f 73 73 69  l the.last possi
5b70: 62 6c 65 20 6d 6f 6d 65 6e 74 2e 0a 3c 2f 70 3e  ble moment..</p>
5b80: 0a 0a 3c 70 3e 54 68 65 20 53 51 4c 20 63 6f 6d  ..<p>The SQL com
5b90: 6d 61 6e 64 20 22 43 4f 4d 4d 49 54 22 20 20 64  mand "COMMIT"  d
5ba0: 6f 65 73 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79  oes not actually
5bb0: 20 63 6f 6d 6d 69 74 20 74 68 65 20 63 68 61 6e   commit the chan
5bc0: 67 65 73 20 74 6f 0a 64 69 73 6b 2e 20 20 49 74  ges to.disk.  It
5bd0: 20 6a 75 73 74 20 74 75 72 6e 73 20 61 75 74 6f   just turns auto
5be0: 63 6f 6d 6d 69 74 20 62 61 63 6b 20 6f 6e 2e 20  commit back on. 
5bf0: 20 54 68 65 6e 2c 20 61 74 20 74 68 65 20 63 6f   Then, at the co
5c00: 6e 63 6c 75 73 69 6f 6e 20 6f 66 0a 74 68 65 20  nclusion of.the 
5c10: 63 6f 6d 6d 61 6e 64 2c 20 74 68 65 20 72 65 67  command, the reg
5c20: 75 6c 61 72 20 61 75 74 6f 63 6f 6d 6d 69 74 20  ular autocommit 
5c30: 6c 6f 67 69 63 20 74 61 6b 65 73 20 6f 76 65 72  logic takes over
5c40: 20 61 6e 64 20 63 61 75 73 65 73 20 74 68 65 0a   and causes the.
5c50: 61 63 74 75 61 6c 20 63 6f 6d 6d 69 74 20 74 6f  actual commit to
5c60: 20 64 69 73 6b 20 74 6f 20 6f 63 63 75 72 2e 0a   disk to occur..
5c70: 54 68 65 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20  The SQL command 
5c80: 22 52 4f 4c 4c 42 41 43 4b 22 20 61 6c 73 6f 20  "ROLLBACK" also 
5c90: 6f 70 65 72 61 74 65 73 20 62 79 20 74 75 72 6e  operates by turn
5ca0: 69 6e 67 20 61 75 74 6f 63 6f 6d 6d 69 74 20 62  ing autocommit b
5cb0: 61 63 6b 20 6f 6e 2c 0a 62 75 74 20 69 74 20 61  ack on,.but it a
5cc0: 6c 73 6f 20 73 65 74 73 20 61 20 66 6c 61 67 20  lso sets a flag 
5cd0: 74 68 61 74 20 74 65 6c 6c 73 20 74 68 65 20 61  that tells the a
5ce0: 75 74 6f 63 6f 6d 6d 69 74 20 6c 6f 67 69 63 20  utocommit logic 
5cf0: 74 6f 20 72 6f 6c 6c 62 61 63 6b 20 72 61 74 68  to rollback rath
5d00: 65 72 0a 74 68 61 6e 20 63 6f 6d 6d 69 74 2e 3c  er.than commit.<
5d10: 2f 70 3e 0a 0a 3c 70 3e 49 66 20 74 68 65 20 53  /p>..<p>If the S
5d20: 51 4c 20 43 4f 4d 4d 49 54 20 63 6f 6d 6d 61 6e  QL COMMIT comman
5d30: 64 20 74 75 72 6e 73 20 61 75 74 6f 63 6f 6d 6d  d turns autocomm
5d40: 69 74 20 6f 6e 20 61 6e 64 20 74 68 65 20 61 75  it on and the au
5d50: 74 6f 63 6f 6d 6d 69 74 20 6c 6f 67 69 63 0a 74  tocommit logic.t
5d60: 68 65 6e 20 74 72 69 65 73 20 74 6f 20 63 6f 6d  hen tries to com
5d70: 6d 69 74 20 63 68 61 6e 67 65 20 62 75 74 20 66  mit change but f
5d80: 61 69 6c 73 20 62 65 63 61 75 73 65 20 73 6f 6d  ails because som
5d90: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 20  e other process 
5da0: 69 73 20 68 6f 6c 64 69 6e 67 0a 61 20 53 48 41  is holding.a SHA
5db0: 52 45 44 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 61  RED lock, then a
5dc0: 75 74 6f 63 6f 6d 6d 69 74 20 69 73 20 74 75 72  utocommit is tur
5dd0: 6e 65 64 20 62 61 63 6b 20 6f 66 66 20 61 75 74  ned back off aut
5de0: 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 69  omatically.  Thi
5df0: 73 0a 61 6c 6c 6f 77 73 20 74 68 65 20 75 73 65  s.allows the use
5e00: 72 20 74 6f 20 72 65 74 72 79 20 74 68 65 20 43  r to retry the C
5e10: 4f 4d 4d 49 54 20 61 74 20 61 20 6c 61 74 65 72  OMMIT at a later
5e20: 20 74 69 6d 65 20 61 66 74 65 72 20 74 68 65 20   time after the 
5e30: 53 48 41 52 45 44 20 6c 6f 63 6b 0a 68 61 73 20  SHARED lock.has 
5e40: 68 61 64 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  had an opportuni
5e50: 74 79 20 74 6f 20 63 6c 65 61 72 2e 3c 2f 70 3e  ty to clear.</p>
5e60: 0a 0a 3c 70 3e 49 66 20 6d 75 6c 74 69 70 6c 65  ..<p>If multiple
5e70: 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 62 65   commands are be
5e80: 69 6e 67 20 65 78 65 63 75 74 65 64 20 61 67 61  ing executed aga
5e90: 69 6e 73 74 20 74 68 65 20 73 61 6d 65 20 53 51  inst the same SQ
5ea0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 0a 63 6f  Lite database.co
5eb0: 6e 6e 65 63 74 69 6f 6e 20 61 74 20 74 68 65 20  nnection at the 
5ec0: 73 61 6d 65 20 74 69 6d 65 2c 20 74 68 65 20 61  same time, the a
5ed0: 75 74 6f 63 6f 6d 6d 69 74 20 69 73 20 64 65 66  utocommit is def
5ee0: 65 72 72 65 64 20 75 6e 74 69 6c 20 74 68 65 20  erred until the 
5ef0: 76 65 72 79 0a 6c 61 73 74 20 63 6f 6d 6d 61 6e  very.last comman
5f00: 64 20 63 6f 6d 70 6c 65 74 65 73 2e 20 20 46 6f  d completes.  Fo
5f10: 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20  r example, if a 
5f20: 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
5f30: 20 69 73 20 62 65 69 6e 67 0a 65 78 65 63 75 74   is being.execut
5f40: 65 64 2c 20 74 68 65 20 65 78 65 63 75 74 69 6f  ed, the executio
5f50: 6e 20 6f 66 20 74 68 65 20 63 6f 6d 6d 61 6e 64  n of the command
5f60: 20 77 69 6c 6c 20 70 61 75 73 65 20 61 73 20 65   will pause as e
5f70: 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 0a 72  ach row of the.r
5f80: 65 73 75 6c 74 20 69 73 20 72 65 74 75 72 6e 65  esult is returne
5f90: 64 2e 20 20 44 75 72 69 6e 67 20 74 68 69 73 20  d.  During this 
5fa0: 70 61 75 73 65 20 6f 74 68 65 72 20 49 4e 53 45  pause other INSE
5fb0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
5fc0: 45 4c 45 54 45 0a 63 6f 6d 6d 61 6e 64 73 20 63  ELETE.commands c
5fd0: 61 6e 20 62 65 20 65 78 65 63 75 74 65 64 20 61  an be executed a
5fe0: 67 61 69 6e 73 74 20 6f 74 68 65 72 20 74 61 62  gainst other tab
5ff0: 6c 65 73 20 69 6e 20 74 68 65 20 64 61 74 61 62  les in the datab
6000: 61 73 65 2e 20 20 42 75 74 20 6e 6f 6e 65 0a 6f  ase.  But none.o
6010: 66 20 74 68 65 73 65 20 63 68 61 6e 67 65 73 20  f these changes 
6020: 77 69 6c 6c 20 63 6f 6d 6d 69 74 20 75 6e 74 69  will commit unti
6030: 6c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53  l the original S
6040: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20  ELECT statement 
6050: 66 69 6e 69 73 68 65 73 2e 0a 3c 2f 70 3e 0a 7d  finishes..</p>.}
6060: 0a 0a 0a 66 6f 6f 74 65 72 20 24 72 63 73 69 64  ...footer $rcsid
6070: 0a                                               .