/ Hex Artifact Content
Login

Artifact e52345bd20323bef6146bfce18ae0829b2b7c87d:


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 20 7b 6c 61 62 65 6c 20  el title {label 
00c0: 7b 7d 7d 7d 20 7b 0a 20 20 67 6c 6f 62 61 6c 20  {}}} {.  global 
00d0: 70 6e 75 6d 0a 20 20 69 6e 63 72 20 70 6e 75 6d  pnum.  incr pnum
00e0: 28 24 6c 65 76 65 6c 29 0a 20 20 66 6f 72 65 61  ($level).  forea
00f0: 63 68 20 69 20 5b 61 72 72 61 79 20 6e 61 6d 65  ch i [array name
0100: 73 20 70 6e 75 6d 5d 20 7b 0a 20 20 20 20 69 66  s pnum] {.    if
0110: 20 7b 24 69 3e 24 6c 65 76 65 6c 7d 20 7b 73 65   {$i>$level} {se
0120: 74 20 70 6e 75 6d 28 24 69 29 20 30 7d 0a 20 20  t pnum($i) 0}.  
0130: 7d 0a 20 20 73 65 74 20 68 20 5b 65 78 70 72 20  }.  set h [expr 
0140: 7b 24 6c 65 76 65 6c 2b 31 7d 5d 0a 20 20 69 66  {$level+1}].  if
0150: 20 7b 24 68 3e 36 7d 20 7b 73 65 74 20 68 20 36   {$h>6} {set h 6
0160: 7d 0a 20 20 73 65 74 20 6e 20 24 70 6e 75 6d 28  }.  set n $pnum(
0170: 31 29 2e 24 70 6e 75 6d 28 32 29 0a 20 20 66 6f  1).$pnum(2).  fo
0180: 72 20 7b 73 65 74 20 69 20 33 7d 20 7b 24 69 3c  r {set i 3} {$i<
0190: 3d 24 6c 65 76 65 6c 7d 20 7b 69 6e 63 72 20 69  =$level} {incr i
01a0: 7d 20 7b 0a 20 20 20 20 61 70 70 65 6e 64 20 6e  } {.    append n
01b0: 20 2e 24 70 6e 75 6d 28 24 69 29 0a 20 20 7d 0a   .$pnum($i).  }.
01c0: 20 20 69 66 20 7b 24 6c 61 62 65 6c 21 3d 22 22    if {$label!=""
01d0: 7d 20 7b 0a 20 20 20 20 70 75 74 73 20 22 3c 61  } {.    puts "<a
01e0: 20 6e 61 6d 65 3d 5c 22 24 6c 61 62 65 6c 5c 22   name=\"$label\"
01f0: 3e 22 0a 20 20 7d 0a 20 20 70 75 74 73 20 22 3c  >".  }.  puts "<
0200: 68 24 68 3e 24 6e 20 24 74 69 74 6c 65 3c 2f 68  h$h>$n $title</h
0210: 24 68 3e 22 0a 7d 0a 73 65 74 20 70 6e 75 6d 28  $h>".}.set pnum(
0220: 31 29 20 30 0a 73 65 74 20 70 6e 75 6d 28 32 29  1) 0.set pnum(2)
0230: 20 30 0a 73 65 74 20 70 6e 75 6d 28 33 29 20 30   0.set pnum(3) 0
0240: 0a 73 65 74 20 70 6e 75 6d 28 34 29 20 30 0a 73  .set pnum(4) 0.s
0250: 65 74 20 70 6e 75 6d 28 35 29 20 30 0a 73 65 74  et pnum(5) 0.set
0260: 20 70 6e 75 6d 28 36 29 20 30 0a 73 65 74 20 70   pnum(6) 0.set p
0270: 6e 75 6d 28 37 29 20 30 0a 73 65 74 20 70 6e 75  num(7) 0.set pnu
0280: 6d 28 38 29 20 30 0a 0a 48 45 41 44 49 4e 47 20  m(8) 0..HEADING 
0290: 31 20 7b 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  1 {File Locking 
02a0: 41 6e 64 20 43 6f 6e 63 75 72 72 65 6e 63 79 20  And Concurrency 
02b0: 49 6e 20 53 51 4c 69 74 65 20 56 65 72 73 69 6f  In SQLite Versio
02c0: 6e 20 33 7d 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e  n 3}..puts {.<p>
02d0: 56 65 72 73 69 6f 6e 20 33 20 6f 66 20 53 51 4c  Version 3 of SQL
02e0: 69 74 65 20 69 6e 74 72 6f 64 75 63 65 73 20 61  ite introduces a
02f0: 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 78 20 6c 6f   more complex lo
0300: 63 6b 69 6e 67 20 61 6e 64 20 6a 6f 75 72 6e 61  cking and journa
0310: 6c 69 6e 67 20 0a 6d 65 63 68 61 6e 69 73 6d 20  ling .mechanism 
0320: 64 65 73 69 67 6e 65 64 20 74 6f 20 69 6d 70 72  designed to impr
0330: 6f 76 65 20 63 6f 6e 63 75 72 72 65 6e 63 79 20  ove concurrency 
0340: 61 6e 64 20 72 65 64 75 63 65 20 74 68 65 20 77  and reduce the w
0350: 72 69 74 65 72 20 73 74 61 72 76 61 74 69 6f 6e  riter starvation
0360: 20 0a 70 72 6f 62 6c 65 6d 2e 20 20 54 68 65 20   .problem.  The 
0370: 6e 65 77 20 6d 65 63 68 61 6e 69 73 6d 20 61 6c  new mechanism al
0380: 73 6f 20 61 6c 6c 6f 77 73 20 61 74 6f 6d 69 63  so allows atomic
0390: 20 63 6f 6d 6d 69 74 73 20 6f 66 20 74 72 61 6e   commits of tran
03a0: 73 61 63 74 69 6f 6e 73 0a 69 6e 76 6f 6c 76 69  sactions.involvi
03b0: 6e 67 20 6d 75 6c 74 69 70 6c 65 20 64 61 74 61  ng multiple data
03c0: 62 61 73 65 20 66 69 6c 65 73 2e 0a 54 68 69 73  base files..This
03d0: 20 64 6f 63 75 6d 65 6e 74 20 64 65 73 63 72 69   document descri
03e0: 62 65 73 20 74 68 65 20 6e 65 77 20 6c 6f 63 6b  bes the new lock
03f0: 69 6e 67 20 6d 65 63 68 61 6e 69 73 6d 2e 0a 54  ing mechanism..T
0400: 68 65 20 69 6e 74 65 6e 64 65 64 20 61 75 64 69  he intended audi
0410: 65 6e 63 65 20 69 73 20 70 72 6f 67 72 61 6d 6d  ence is programm
0420: 65 72 73 20 77 68 6f 20 77 61 6e 74 20 74 6f 20  ers who want to 
0430: 75 6e 64 65 72 73 74 61 6e 64 20 61 6e 64 2f 6f  understand and/o
0440: 72 20 6d 6f 64 69 66 79 0a 74 68 65 20 70 61 67  r modify.the pag
0450: 65 72 20 63 6f 64 65 20 61 6e 64 20 72 65 76 69  er code and revi
0460: 65 77 65 72 73 20 77 6f 72 6b 69 6e 67 20 74 6f  ewers working to
0470: 20 76 65 72 69 66 79 20 74 68 65 20 64 65 73 69   verify the desi
0480: 67 6e 0a 6f 66 20 53 51 4c 69 74 65 20 76 65 72  gn.of SQLite ver
0490: 73 69 6f 6e 20 33 2e 0a 3c 2f 70 3e 0a 7d 0a 0a  sion 3..</p>.}..
04a0: 48 45 41 44 49 4e 47 20 31 20 7b 4f 76 65 72 76  HEADING 1 {Overv
04b0: 69 65 77 7d 20 6f 76 65 72 76 69 65 77 0a 0a 70  iew} overview..p
04c0: 75 74 73 20 7b 0a 3c 70 3e 0a 4c 6f 63 6b 69 6e  uts {.<p>.Lockin
04d0: 67 20 61 6e 64 20 63 6f 6e 63 75 72 72 65 6e 63  g and concurrenc
04e0: 79 20 63 6f 6e 74 72 6f 6c 20 61 72 65 20 68 61  y control are ha
04f0: 6e 64 6c 65 64 20 62 79 20 74 68 65 20 74 68 65  ndled by the the
0500: 20 0a 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a   .<a href="http:
0510: 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67  //www.sqlite.org
0520: 2f 63 76 73 74 72 61 63 2f 67 65 74 66 69 6c 65  /cvstrac/getfile
0530: 2f 73 71 6c 69 74 65 2f 73 72 63 2f 70 61 67 65  /sqlite/src/page
0540: 72 2e 63 22 3e 0a 70 61 67 65 72 20 6d 6f 64 75  r.c">.pager modu
0550: 6c 65 3c 2f 61 3e 2e 0a 54 68 65 20 70 61 67 65  le</a>..The page
0560: 72 20 6d 6f 64 75 6c 65 20 69 73 20 72 65 73 70  r module is resp
0570: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 6d 61 6b 69  onsible for maki
0580: 6e 67 20 53 51 4c 69 74 65 20 22 41 43 49 44 22  ng SQLite "ACID"
0590: 20 28 41 74 6f 6d 69 63 2c 0a 43 6f 6e 73 69 73   (Atomic,.Consis
05a0: 74 65 6e 74 2c 20 49 73 6f 6c 61 74 65 64 2c 20  tent, Isolated, 
05b0: 61 6e 64 20 44 75 72 61 62 6c 65 29 2e 20 20 54  and Durable).  T
05c0: 68 65 20 70 61 67 65 72 20 6d 6f 64 75 6c 65 20  he pager module 
05d0: 6d 61 6b 65 73 20 73 75 72 65 20 63 68 61 6e 67  makes sure chang
05e0: 65 73 0a 68 61 70 70 65 6e 20 61 6c 6c 20 61 74  es.happen all at
05f0: 20 6f 6e 63 65 2c 20 74 68 61 74 20 65 69 74 68   once, that eith
0600: 65 72 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 6f  er all changes o
0610: 63 63 75 72 20 6f 72 20 6e 6f 6e 65 20 6f 66 20  ccur or none of 
0620: 74 68 65 6d 20 64 6f 2c 0a 74 68 61 74 20 74 77  them do,.that tw
0630: 6f 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73  o or more proces
0640: 73 65 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  ses do not try t
0650: 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
0660: 61 62 61 73 65 0a 69 6e 20 69 6e 63 6f 6d 70 61  abase.in incompa
0670: 74 69 62 6c 65 20 77 61 79 73 20 61 74 20 74 68  tible ways at th
0680: 65 20 73 61 6d 65 20 74 69 6d 65 2c 20 61 6e 64  e same time, and
0690: 20 74 68 61 74 20 6f 6e 63 65 20 63 68 61 6e 67   that once chang
06a0: 65 73 20 68 61 76 65 20 62 65 65 6e 0a 77 72 69  es have been.wri
06b0: 74 74 65 6e 20 74 68 65 79 20 70 65 72 73 69 73  tten they persis
06c0: 74 20 75 6e 74 69 6c 20 65 78 70 6c 69 63 69 74  t until explicit
06d0: 6c 79 20 64 65 6c 65 74 65 64 2e 20 20 54 68 65  ly deleted.  The
06e0: 20 70 61 67 65 72 20 61 6c 73 6f 20 70 72 6f 76   pager also prov
06f0: 69 64 65 73 0a 61 6e 20 6d 65 6d 6f 72 79 20 63  ides.an memory c
0700: 61 63 68 65 20 6f 66 20 73 6f 6d 65 20 6f 66 20  ache of some of 
0710: 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
0720: 74 68 65 20 64 69 73 6b 20 66 69 6c 65 2e 3c 2f  the disk file.</
0730: 70 3e 0a 0a 3c 70 3e 54 68 65 20 70 61 67 65 72  p>..<p>The pager
0740: 20 69 73 20 75 6e 63 6f 6e 63 65 72 6e 65 64 0a   is unconcerned.
0750: 77 69 74 68 20 74 68 65 20 64 65 74 61 69 6c 73  with the details
0760: 20 6f 66 20 42 2d 54 72 65 65 73 2c 20 74 65 78   of B-Trees, tex
0770: 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 69 6e 64  t encodings, ind
0780: 69 63 65 73 2c 20 61 6e 64 20 73 6f 20 66 6f 72  ices, and so for
0790: 74 68 2e 0a 46 72 6f 6d 20 74 68 65 20 70 6f 69  th..From the poi
07a0: 6e 74 20 6f 66 20 76 69 65 77 20 6f 66 20 74 68  nt of view of th
07b0: 65 20 70 61 67 65 72 20 74 68 65 20 64 61 74 61  e pager the data
07c0: 62 61 73 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  base consists of
07d0: 0a 61 20 73 69 6e 67 6c 65 20 66 69 6c 65 20 6f  .a single file o
07e0: 66 20 75 6e 69 66 6f 72 6d 2d 73 69 7a 65 64 20  f uniform-sized 
07f0: 62 6c 6f 63 6b 73 2e 20 20 45 61 63 68 20 62 6c  blocks.  Each bl
0800: 6f 63 6b 20 69 73 20 63 61 6c 6c 65 64 20 61 0a  ock is called a.
0810: 22 70 61 67 65 22 20 61 6e 64 20 69 73 20 75 73  "page" and is us
0820: 75 61 6c 6c 79 20 31 30 32 34 20 62 79 74 65 73  ually 1024 bytes
0830: 20 69 6e 20 73 69 7a 65 2e 20 20 20 54 68 65 20   in size.   The 
0840: 70 61 67 65 73 20 61 72 65 20 6e 75 6d 62 65 72  pages are number
0850: 65 64 0a 62 65 67 69 6e 6e 69 6e 67 20 77 69 74  ed.beginning wit
0860: 68 20 31 2e 20 20 53 6f 20 74 68 65 20 66 69 72  h 1.  So the fir
0870: 73 74 20 31 30 32 34 20 62 79 74 65 73 20 6f 66  st 1024 bytes of
0880: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 72   the database ar
0890: 65 20 63 61 6c 6c 65 64 0a 22 70 61 67 65 20 31  e called."page 1
08a0: 22 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  " and the second
08b0: 20 31 30 32 34 20 62 79 74 65 73 20 61 72 65 20   1024 bytes are 
08c0: 63 61 6c 6c 20 22 70 61 67 65 20 32 22 20 61 6e  call "page 2" an
08d0: 64 20 73 6f 20 66 6f 72 74 68 2e 20 41 6c 6c 20  d so forth. All 
08e0: 0a 6f 74 68 65 72 20 65 6e 63 6f 64 69 6e 67 20  .other encoding 
08f0: 64 65 74 61 69 6c 73 20 61 72 65 20 68 61 6e 64  details are hand
0900: 6c 65 64 20 62 79 20 68 69 67 68 65 72 20 6c 61  led by higher la
0910: 79 65 72 73 20 6f 66 20 74 68 65 20 6c 69 62 72  yers of the libr
0920: 61 72 79 2e 20 20 0a 54 68 65 20 70 61 67 65 72  ary.  .The pager
0930: 20 63 6f 6d 6d 75 6e 69 63 61 74 65 73 20 77 69   communicates wi
0940: 74 68 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  th the operating
0950: 20 73 79 73 74 65 6d 20 75 73 69 6e 67 20 6f 6e   system using on
0960: 65 20 6f 66 20 73 65 76 65 72 61 6c 0a 6d 6f 64  e of several.mod
0970: 75 6c 65 73 20 0a 28 45 78 61 6d 70 6c 65 73 3a  ules .(Examples:
0980: 0a 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f  .<a href="http:/
0990: 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f  /www.sqlite.org/
09a0: 63 76 73 74 72 61 63 2f 67 65 74 66 69 6c 65 2f  cvstrac/getfile/
09b0: 73 71 6c 69 74 65 2f 73 72 63 2f 6f 73 5f 75 6e  sqlite/src/os_un
09c0: 69 78 2e 63 22 3e 0a 6f 73 5f 75 6e 69 78 2e 63  ix.c">.os_unix.c
09d0: 3c 2f 61 3e 2c 0a 3c 61 20 68 72 65 66 3d 22 68  </a>,.<a href="h
09e0: 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65  ttp://www.sqlite
09f0: 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 67 65 74  .org/cvstrac/get
0a00: 66 69 6c 65 2f 73 71 6c 69 74 65 2f 73 72 63 2f  file/sqlite/src/
0a10: 6f 73 5f 77 69 6e 2e 63 22 3e 0a 6f 73 5f 77 69  os_win.c">.os_wi
0a20: 6e 2e 63 3c 2f 61 3e 29 0a 74 68 61 74 20 70 72  n.c</a>).that pr
0a30: 6f 76 69 64 65 73 20 61 20 75 6e 69 66 6f 72 6d  ovides a uniform
0a40: 20 61 62 73 74 72 61 63 74 69 6f 6e 20 66 6f 72   abstraction for
0a50: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
0a60: 6d 20 73 65 72 76 69 63 65 73 2e 0a 3c 2f 70 3e  m services..</p>
0a70: 0a 0a 3c 70 3e 54 68 65 20 70 61 67 65 72 20 6d  ..<p>The pager m
0a80: 6f 64 75 6c 65 20 65 66 66 65 63 74 69 76 65 6c  odule effectivel
0a90: 79 20 63 6f 6e 74 72 6f 6c 73 20 61 63 63 65 73  y controls acces
0aa0: 73 20 66 6f 72 20 73 65 70 61 72 61 74 65 20 74  s for separate t
0ab0: 68 72 65 61 64 73 2c 20 6f 72 0a 73 65 70 61 72  hreads, or.separ
0ac0: 61 74 65 20 70 72 6f 63 65 73 73 65 73 2c 20 6f  ate processes, o
0ad0: 72 20 62 6f 74 68 2e 20 20 54 68 72 6f 75 67 68  r both.  Through
0ae0: 6f 75 74 20 74 68 69 73 20 64 6f 63 75 6d 65 6e  out this documen
0af0: 74 20 77 68 65 6e 65 76 65 72 20 74 68 65 0a 77  t whenever the.w
0b00: 6f 72 64 20 22 70 72 6f 63 65 73 73 22 20 69 73  ord "process" is
0b10: 20 77 72 69 74 74 65 6e 20 79 6f 75 20 6d 61 79   written you may
0b20: 20 73 75 62 73 74 69 74 75 74 65 20 74 68 65 20   substitute the 
0b30: 77 6f 72 64 20 22 74 68 72 65 61 64 22 20 77 69  word "thread" wi
0b40: 74 68 6f 75 74 0a 63 68 61 6e 67 69 6e 67 20 74  thout.changing t
0b50: 68 65 20 74 72 75 74 68 20 6f 66 20 74 68 65 20  he truth of the 
0b60: 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 70 3e 0a 7d  statement.</p>.}
0b70: 0a 0a 48 45 41 44 49 4e 47 20 31 20 7b 4c 6f 63  ..HEADING 1 {Loc
0b80: 6b 69 6e 67 7d 20 6c 6f 63 6b 69 6e 67 0a 0a 70  king} locking..p
0b90: 75 74 73 20 7b 0a 3c 70 3e 0a 46 72 6f 6d 20 74  uts {.<p>.From t
0ba0: 68 65 20 70 6f 69 6e 74 20 6f 66 20 76 69 65 77  he point of view
0bb0: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f   of a single pro
0bc0: 63 65 73 73 2c 20 61 20 64 61 74 61 62 61 73 65  cess, a database
0bd0: 20 66 69 6c 65 0a 63 61 6e 20 62 65 20 69 6e 20   file.can be in 
0be0: 6f 6e 65 20 6f 66 20 66 69 76 65 20 6c 6f 63 6b  one of five lock
0bf0: 69 6e 67 20 73 74 61 74 65 73 3a 0a 3c 2f 70 3e  ing states:.</p>
0c00: 0a 0a 3c 70 3e 0a 3c 74 61 62 6c 65 20 63 65 6c  ..<p>.<table cel
0c10: 6c 70 61 64 64 69 6e 67 3d 22 32 30 22 3e 0a 3c  lpadding="20">.<
0c20: 74 72 3e 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74  tr><td valign="t
0c30: 6f 70 22 3e 55 4e 4c 4f 43 4b 45 44 3c 2f 74 64  op">UNLOCKED</td
0c40: 3e 0a 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f  >.<td valign="to
0c50: 70 22 3e 0a 4e 6f 20 6c 6f 63 6b 73 20 61 72 65  p">.No locks are
0c60: 20 68 65 6c 64 20 6f 6e 20 74 68 65 20 64 61 74   held on the dat
0c70: 61 62 61 73 65 2e 20 20 54 68 65 20 64 61 74 61  abase.  The data
0c80: 62 61 73 65 20 6d 61 79 20 62 65 20 6e 65 69 74  base may be neit
0c90: 68 65 72 20 72 65 61 64 20 6e 6f 72 0a 77 72 69  her read nor.wri
0ca0: 74 74 65 6e 2e 20 20 41 6e 79 20 69 6e 74 65 72  tten.  Any inter
0cb0: 6e 61 6c 6c 79 20 63 61 63 68 65 64 20 64 61 74  nally cached dat
0cc0: 61 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  a is considered 
0cd0: 73 75 73 70 65 63 74 20 61 6e 64 20 73 75 62 6a  suspect and subj
0ce0: 65 63 74 20 74 6f 0a 76 65 72 69 66 69 63 61 74  ect to.verificat
0cf0: 69 6f 6e 20 61 67 61 69 6e 73 74 20 74 68 65 20  ion against the 
0d00: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 62 65  database file be
0d10: 66 6f 72 65 20 62 65 69 6e 67 20 75 73 65 64 2e  fore being used.
0d20: 20 20 4f 74 68 65 72 20 0a 70 72 6f 63 65 73 73    Other .process
0d30: 65 73 20 63 61 6e 20 72 65 61 64 20 6f 72 20 77  es can read or w
0d40: 72 69 74 65 20 74 68 65 20 64 61 74 61 62 61 73  rite the databas
0d50: 65 20 61 73 20 74 68 65 69 72 20 6f 77 6e 20 6c  e as their own l
0d60: 6f 63 6b 69 6e 67 20 73 74 61 74 65 73 0a 70 65  ocking states.pe
0d70: 72 6d 69 74 2e 20 20 54 68 69 73 20 69 73 20 74  rmit.  This is t
0d80: 68 65 20 64 65 66 61 75 6c 74 20 73 74 61 74 65  he default state
0d90: 2e 0a 3c 2f 74 64 3e 3c 2f 74 72 3e 0a 0a 3c 74  ..</td></tr>..<t
0da0: 72 3e 3c 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f  r><td valign="to
0db0: 70 22 3e 53 48 41 52 45 44 3c 2f 74 64 3e 0a 3c  p">SHARED</td>.<
0dc0: 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e  td valign="top">
0dd0: 0a 54 68 65 20 64 61 74 61 62 61 73 65 20 6d 61  .The database ma
0de0: 79 20 62 65 20 72 65 61 64 20 62 75 74 20 6e 6f  y be read but no
0df0: 74 20 77 72 69 74 74 65 6e 2e 20 20 41 6e 79 20  t written.  Any 
0e00: 6e 75 6d 62 65 72 20 6f 66 20 0a 70 72 6f 63 65  number of .proce
0e10: 73 73 65 73 20 63 61 6e 20 68 6f 6c 64 20 53 48  sses can hold SH
0e20: 41 52 45 44 20 6c 6f 63 6b 73 20 61 74 20 74 68  ARED locks at th
0e30: 65 20 73 61 6d 65 20 74 69 6d 65 2c 20 68 65 6e  e same time, hen
0e40: 63 65 20 74 68 65 72 65 20 63 61 6e 20 62 65 0a  ce there can be.
0e50: 6d 61 6e 79 20 73 69 6d 75 6c 74 61 6e 65 6f 75  many simultaneou
0e60: 73 20 72 65 61 64 65 72 73 2e 20 20 42 75 74 20  s readers.  But 
0e70: 6e 6f 20 6f 74 68 65 72 20 74 68 72 65 61 64 20  no other thread 
0e80: 6f 72 20 70 72 6f 63 65 73 73 20 69 73 20 61 6c  or process is al
0e90: 6c 6f 77 65 64 0a 74 6f 20 77 72 69 74 65 20 74  lowed.to write t
0ea0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
0eb0: 69 6c 65 20 77 68 69 6c 65 20 6f 6e 65 20 6f 72  ile while one or
0ec0: 20 6d 6f 72 65 20 53 48 41 52 45 44 20 6c 6f 63   more SHARED loc
0ed0: 6b 73 20 61 72 65 20 61 63 74 69 76 65 2e 0a 3c  ks are active..<
0ee0: 2f 74 64 3e 3c 2f 74 72 3e 0a 0a 3c 74 72 3e 3c  /td></tr>..<tr><
0ef0: 74 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e  td valign="top">
0f00: 52 45 53 45 52 56 45 44 3c 2f 74 64 3e 0a 3c 74  RESERVED</td>.<t
0f10: 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 0a  d valign="top">.
0f20: 41 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  A RESERVED lock 
0f30: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 70  means that the p
0f40: 72 6f 63 65 73 73 20 69 73 20 70 6c 61 6e 6e 69  rocess is planni
0f50: 6e 67 20 6f 6e 20 77 72 69 74 69 6e 67 20 74 6f  ng on writing to
0f60: 20 74 68 65 0a 64 61 74 61 62 61 73 65 20 66 69   the.database fi
0f70: 6c 65 20 61 74 20 73 6f 6d 65 20 70 6f 69 6e 74  le at some point
0f80: 20 69 6e 20 74 68 65 20 66 75 74 75 72 65 20 62   in the future b
0f90: 75 74 20 74 68 61 74 20 69 74 20 69 73 20 63 75  ut that it is cu
0fa0: 72 72 65 6e 74 6c 79 20 6a 75 73 74 0a 72 65 61  rrently just.rea
0fb0: 64 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 66 69  ding from the fi
0fc0: 6c 65 2e 20 20 4f 6e 6c 79 20 61 20 73 69 6e 67  le.  Only a sing
0fd0: 6c 65 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b  le RESERVED lock
0fe0: 20 6d 61 79 20 62 65 20 61 63 74 69 76 65 20 61   may be active a
0ff0: 74 20 6f 6e 65 0a 74 69 6d 65 2c 20 74 68 6f 75  t one.time, thou
1000: 67 68 20 6d 75 6c 74 69 70 6c 65 20 53 48 41 52  gh multiple SHAR
1010: 45 44 20 6c 6f 63 6b 73 20 63 61 6e 20 63 6f 65  ED locks can coe
1020: 78 69 73 74 20 77 69 74 68 20 61 20 73 69 6e 67  xist with a sing
1030: 6c 65 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b  le RESERVED lock
1040: 2e 0a 52 45 53 45 52 56 45 44 20 64 69 66 66 65  ..RESERVED diffe
1050: 72 73 20 66 72 6f 6d 20 50 45 4e 44 49 4e 47 20  rs from PENDING 
1060: 69 6e 20 74 68 61 74 20 6e 65 77 20 53 48 41 52  in that new SHAR
1070: 45 44 20 6c 6f 63 6b 73 20 63 61 6e 20 62 65 20  ED locks can be 
1080: 61 63 71 75 69 72 65 64 0a 77 68 69 6c 65 20 74  acquired.while t
1090: 68 65 72 65 20 69 73 20 61 20 52 45 53 45 52 56  here is a RESERV
10a0: 45 44 20 6c 6f 63 6b 2e 0a 3c 2f 74 64 3e 3c 2f  ED lock..</td></
10b0: 74 72 3e 0a 0a 3c 74 72 3e 3c 74 64 20 76 61 6c  tr>..<tr><td val
10c0: 69 67 6e 3d 22 74 6f 70 22 3e 50 45 4e 44 49 4e  ign="top">PENDIN
10d0: 47 3c 2f 74 64 3e 0a 3c 74 64 20 76 61 6c 69 67  G</td>.<td valig
10e0: 6e 3d 22 74 6f 70 22 3e 0a 41 20 50 45 4e 44 49  n="top">.A PENDI
10f0: 4e 47 20 6c 6f 63 6b 20 6d 65 61 6e 73 20 74 68  NG lock means th
1100: 61 74 20 74 68 65 20 70 72 6f 63 65 73 73 20 68  at the process h
1110: 6f 6c 64 69 6e 67 20 74 68 65 20 6c 6f 63 6b 20  olding the lock 
1120: 77 61 6e 74 73 20 74 6f 20 77 72 69 74 65 0a 74  wants to write.t
1130: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  o the database a
1140: 73 20 73 6f 6f 6e 20 61 73 20 70 6f 73 73 69 62  s soon as possib
1150: 6c 65 20 61 6e 64 20 69 73 20 6a 75 73 74 20 77  le and is just w
1160: 61 69 74 69 6e 67 20 6f 6e 20 61 6c 6c 20 63 75  aiting on all cu
1170: 72 72 65 6e 74 0a 53 48 41 52 45 44 20 6c 6f 63  rrent.SHARED loc
1180: 6b 73 20 74 6f 20 63 6c 65 61 72 20 73 6f 20 74  ks to clear so t
1190: 68 61 74 20 69 74 20 63 61 6e 20 67 65 74 20 61  hat it can get a
11a0: 6e 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  n EXCLUSIVE lock
11b0: 2e 20 20 4e 6f 20 6e 65 77 20 0a 53 48 41 52 45  .  No new .SHARE
11c0: 44 20 6c 6f 63 6b 73 20 61 72 65 20 70 65 72 6d  D locks are perm
11d0: 69 74 74 65 64 20 61 67 61 69 6e 73 74 20 74 68  itted against th
11e0: 65 20 64 61 74 61 62 61 73 65 20 69 66 0a 61 20  e database if.a 
11f0: 50 45 4e 44 49 4e 47 20 6c 6f 63 6b 20 69 73 20  PENDING lock is 
1200: 61 63 74 69 76 65 2c 20 74 68 6f 75 67 68 20 65  active, though e
1210: 78 69 73 74 69 6e 67 20 53 48 41 52 45 44 20 6c  xisting SHARED l
1220: 6f 63 6b 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ocks are allowed
1230: 20 74 6f 0a 63 6f 6e 74 69 6e 75 65 2e 0a 3c 2f   to.continue..</
1240: 74 64 3e 3c 2f 74 72 3e 0a 0a 3c 74 72 3e 3c 74  td></tr>..<tr><t
1250: 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 45  d valign="top">E
1260: 58 43 4c 55 53 49 56 45 3c 2f 74 64 3e 0a 3c 74  XCLUSIVE</td>.<t
1270: 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 0a  d valign="top">.
1280: 41 6e 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  An EXCLUSIVE loc
1290: 6b 20 69 73 20 6e 65 65 64 65 64 20 69 6e 20 6f  k is needed in o
12a0: 72 64 65 72 20 74 6f 20 77 72 69 74 65 20 74 6f  rder to write to
12b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
12c0: 6c 65 2e 0a 4f 6e 6c 79 20 6f 6e 65 20 45 58 43  le..Only one EXC
12d0: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 69 73 20 61  LUSIVE lock is a
12e0: 6c 6c 6f 77 65 64 20 6f 6e 20 74 68 65 20 66 69  llowed on the fi
12f0: 6c 65 20 61 6e 64 20 6e 6f 20 6f 74 68 65 72 20  le and no other 
1300: 6c 6f 63 6b 73 20 6f 66 0a 61 6e 79 20 6b 69 6e  locks of.any kin
1310: 64 20 61 72 65 20 61 6c 6c 6f 77 65 64 20 74 6f  d are allowed to
1320: 20 63 6f 65 78 69 73 74 20 77 69 74 68 20 61 6e   coexist with an
1330: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 2e   EXCLUSIVE lock.
1340: 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 0a 6d 61    In order to.ma
1350: 78 69 6d 69 7a 65 20 63 6f 6e 63 75 72 72 65 6e  ximize concurren
1360: 63 79 2c 20 53 51 4c 69 74 65 20 77 6f 72 6b 73  cy, SQLite works
1370: 20 74 6f 20 6d 69 6e 69 6d 69 7a 65 20 74 68 65   to minimize the
1380: 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1390: 74 68 61 74 0a 45 58 43 4c 55 53 49 56 45 20 6c  that.EXCLUSIVE l
13a0: 6f 63 6b 73 20 61 72 65 20 68 65 6c 64 2e 0a 3c  ocks are held..<
13b0: 2f 74 64 3e 3c 2f 74 72 3e 0a 3c 2f 74 61 62 6c  /td></tr>.</tabl
13c0: 65 3e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65  e>.</p>..<p>.The
13d0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
13e0: 6d 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  m interface laye
13f0: 72 20 75 6e 64 65 72 73 74 61 6e 64 73 20 61 6e  r understands an
1400: 64 20 74 72 61 63 6b 73 20 61 6c 6c 20 66 69 76  d tracks all fiv
1410: 65 0a 6c 6f 63 6b 69 6e 67 20 73 74 61 74 65 73  e.locking states
1420: 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
1430: 2e 20 20 0a 54 68 65 20 70 61 67 65 72 20 6d 6f  .  .The pager mo
1440: 64 75 6c 65 20 6f 6e 6c 79 20 74 72 61 63 6b 73  dule only tracks
1450: 20 66 6f 75 72 20 6f 66 20 74 68 65 20 66 69 76   four of the fiv
1460: 65 20 6c 6f 63 6b 69 6e 67 20 73 74 61 74 65 73  e locking states
1470: 2e 0a 41 20 50 45 4e 44 49 4e 47 20 6c 6f 63 6b  ..A PENDING lock
1480: 20 69 73 20 61 6c 77 61 79 73 20 6a 75 73 74 20   is always just 
1490: 61 20 74 65 6d 70 6f 72 61 72 79 0a 73 74 65 70  a temporary.step
14a0: 70 69 6e 67 20 73 74 6f 6e 65 20 6f 6e 20 74 68  ping stone on th
14b0: 65 20 70 61 74 68 20 74 6f 20 61 6e 20 45 58 43  e path to an EXC
14c0: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 61 6e 64 20  LUSIVE lock and 
14d0: 73 6f 20 74 68 65 20 70 61 67 65 72 20 6d 6f 64  so the pager mod
14e0: 75 6c 65 0a 64 6f 65 73 20 6e 6f 74 20 74 72 61  ule.does not tra
14f0: 63 6b 20 50 45 4e 44 49 4e 47 20 6c 6f 63 6b 73  ck PENDING locks
1500: 2e 0a 3c 2f 70 3e 0a 7d 0a 0a 48 45 41 44 49 4e  ..</p>.}..HEADIN
1510: 47 20 31 20 7b 54 68 65 20 52 6f 6c 6c 62 61 63  G 1 {The Rollbac
1520: 6b 20 4a 6f 75 72 6e 61 6c 7d 20 72 6f 6c 6c 62  k Journal} rollb
1530: 61 63 6b 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 41  ack..puts {.<p>A
1540: 6e 79 20 74 69 6d 65 20 61 20 70 72 6f 63 65 73  ny time a proces
1550: 73 20 77 61 6e 74 73 20 74 6f 20 6d 61 6b 65 20  s wants to make 
1560: 61 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 64  a changes to a d
1570: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 69 74  atabase file, it
1580: 0a 66 69 72 73 74 20 72 65 63 6f 72 64 73 20 65  .first records e
1590: 6e 6f 75 67 68 20 69 6e 66 6f 72 6d 61 74 69 6f  nough informatio
15a0: 6e 20 69 6e 20 74 68 65 20 3c 65 6d 3e 72 6f 6c  n in the <em>rol
15b0: 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 3c 2f 65  lback journal</e
15c0: 6d 3e 20 74 6f 0a 72 65 73 74 6f 72 65 20 74 68  m> to.restore th
15d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
15e0: 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
15f0: 69 61 6c 20 63 6f 6e 64 69 74 69 6f 6e 2e 20 20  ial condition.  
1600: 54 68 75 73 2c 20 62 65 66 6f 72 65 0a 61 6c 74  Thus, before.alt
1610: 65 72 69 6e 67 20 61 6e 79 20 70 61 67 65 20 6f  ering any page o
1620: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  f the database, 
1630: 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 63 6f 6e  the original con
1640: 74 65 6e 74 73 20 6f 66 20 74 68 61 74 20 70 61  tents of that pa
1650: 67 65 0a 6d 75 73 74 20 62 65 20 77 72 69 74 74  ge.must be writt
1660: 65 6e 20 69 6e 74 6f 20 74 68 65 20 6a 6f 75 72  en into the jour
1670: 6e 61 6c 2e 20 20 54 68 65 20 6a 6f 75 72 6e 61  nal.  The journa
1680: 6c 20 61 6c 73 6f 20 72 65 63 6f 72 64 73 20 74  l also records t
1690: 68 65 20 69 6e 69 74 69 61 6c 0a 73 69 7a 65 20  he initial.size 
16a0: 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
16b0: 73 6f 20 74 68 61 74 20 69 66 20 74 68 65 20 64  so that if the d
16c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 72 6f  atabase file gro
16d0: 77 73 20 69 74 20 63 61 6e 20 62 65 20 74 72 75  ws it can be tru
16e0: 6e 63 61 74 65 64 0a 62 61 63 6b 20 74 6f 20 69  ncated.back to i
16f0: 74 73 20 6f 72 69 67 69 6e 61 6c 20 73 69 7a 65  ts original size
1700: 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 3c   on a rollback.<
1710: 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 72 6f 6c 6c  /p>..<p>The roll
1720: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 69 73 20  back journal is 
1730: 61 20 6f 72 64 69 6e 61 72 79 20 64 69 73 6b 20  a ordinary disk 
1740: 66 69 6c 65 20 74 68 61 74 20 68 61 73 20 74 68  file that has th
1750: 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 73 0a 74  e same name as.t
1760: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1770: 20 77 69 74 68 20 74 68 65 20 73 75 66 66 69 78   with the suffix
1780: 20 22 3c 74 74 3e 2d 6a 6f 75 72 6e 61 6c 3c 2f   "<tt>-journal</
1790: 74 74 3e 22 20 61 64 64 65 64 2e 3c 2f 70 3e 0a  tt>" added.</p>.
17a0: 0a 3c 70 3e 49 66 20 53 51 4c 69 74 65 20 69 73  .<p>If SQLite is
17b0: 20 77 6f 72 6b 69 6e 67 20 77 69 74 68 20 6d 75   working with mu
17c0: 6c 74 69 70 6c 65 20 64 61 74 61 62 61 73 65 73  ltiple databases
17d0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
17e0: 65 0a 28 75 73 69 6e 67 20 74 68 65 20 41 54 54  e.(using the ATT
17f0: 41 43 48 20 63 6f 6d 6d 61 6e 64 29 20 74 68 65  ACH command) the
1800: 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  n each database 
1810: 68 61 73 20 69 74 73 20 6f 77 6e 20 6a 6f 75 72  has its own jour
1820: 6e 61 6c 2e 0a 42 75 74 20 74 68 65 72 65 20 69  nal..But there i
1830: 73 20 61 6c 73 6f 20 61 20 73 65 70 61 72 61 74  s also a separat
1840: 65 20 61 67 67 72 65 67 61 74 65 20 6a 6f 75 72  e aggregate jour
1850: 6e 61 6c 0a 63 61 6c 6c 65 64 20 74 68 65 20 3c  nal.called the <
1860: 65 6d 3e 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61  em>master journa
1870: 6c 3c 2f 65 6d 3e 2e 0a 54 68 65 20 6d 61 73 74  l</em>..The mast
1880: 65 72 20 6a 6f 75 72 6e 61 6c 20 64 6f 65 73 20  er journal does 
1890: 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 70 61 67 65  not contain page
18a0: 20 64 61 74 61 20 75 73 65 64 20 66 6f 72 20 72   data used for r
18b0: 6f 6c 6c 69 6e 67 20 62 61 63 6b 0a 63 68 61 6e  olling back.chan
18c0: 67 65 73 2e 20 20 49 6e 73 74 65 61 64 20 74 68  ges.  Instead th
18d0: 65 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61 6c  e master journal
18e0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 6e 61   contains the na
18f0: 6d 65 73 20 6f 66 20 74 68 65 0a 69 6e 64 69 76  mes of the.indiv
1900: 69 64 75 61 6c 20 66 69 6c 65 20 6a 6f 75 72 6e  idual file journ
1910: 61 6c 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  als for each of 
1920: 74 68 65 20 41 54 54 41 43 48 65 64 20 64 61 74  the ATTACHed dat
1930: 61 62 61 73 65 73 2e 20 20 20 45 61 63 68 20 6f  abases.   Each o
1940: 66 0a 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c  f.the individual
1950: 20 66 69 6c 65 20 6a 6f 75 72 6e 61 6c 73 20 61   file journals a
1960: 6c 73 6f 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  lso contain the 
1970: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 73 74  name of the mast
1980: 65 72 20 6a 6f 75 72 6e 61 6c 2e 0a 49 66 20 74  er journal..If t
1990: 68 65 72 65 20 61 72 65 20 6e 6f 20 41 54 54 41  here are no ATTA
19a0: 43 48 65 64 20 64 61 74 61 62 61 73 65 73 20 28  CHed databases (
19b0: 6f 72 20 69 66 20 6e 6f 6e 65 20 6f 66 20 74 68  or if none of th
19c0: 65 20 41 54 54 41 43 48 65 64 20 64 61 74 61 62  e ATTACHed datab
19d0: 61 73 65 0a 69 73 20 70 61 72 74 69 63 69 70 61  ase.is participa
19e0: 74 69 6e 67 20 69 6e 20 74 68 65 20 63 75 72 72  ting in the curr
19f0: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 29  ent transaction)
1a00: 20 6e 6f 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e   no master journ
1a10: 61 6c 20 69 73 0a 63 72 65 61 74 65 64 20 61 6e  al is.created an
1a20: 64 20 74 68 65 20 6e 6f 72 6d 61 6c 20 72 6f 6c  d the normal rol
1a30: 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 63 6f  lback journal co
1a40: 6e 74 61 69 6e 73 20 61 6e 20 65 6d 70 74 79 20  ntains an empty 
1a50: 73 74 72 69 6e 67 0a 69 6e 20 74 68 65 20 70 6c  string.in the pl
1a60: 61 63 65 20 6e 6f 72 6d 61 6c 6c 79 20 72 65 73  ace normally res
1a70: 65 72 76 65 64 20 66 6f 72 20 72 65 63 6f 72 64  erved for record
1a80: 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
1a90: 74 68 65 20 6d 61 73 74 65 72 0a 6a 6f 75 72 6e  the master.journ
1aa0: 61 6c 2e 3c 2f 70 3e 0a 0a 3c 70 3e 41 20 69 6e  al.</p>..<p>A in
1ab0: 64 69 76 69 64 75 61 6c 20 66 69 6c 65 20 6a 6f  dividual file jo
1ac0: 75 72 6e 61 6c 20 69 73 20 73 61 69 64 20 74 6f  urnal is said to
1ad0: 20 62 65 20 3c 65 6d 3e 68 6f 74 3c 2f 65 6d 3e   be <em>hot</em>
1ae0: 0a 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20  .if it needs to 
1af0: 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 0a 69  be rolled back.i
1b00: 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 73 74 6f  n order to resto
1b10: 72 65 20 74 68 65 20 69 6e 74 65 67 72 69 74 79  re the integrity
1b20: 20 6f 66 20 69 74 73 20 64 61 74 61 62 61 73 65   of its database
1b30: 2e 20 20 0a 41 20 68 6f 74 20 6a 6f 75 72 6e 61  .  .A hot journa
1b40: 6c 20 69 73 20 63 72 65 61 74 65 64 20 77 68 65  l is created whe
1b50: 6e 20 61 20 70 72 6f 63 65 73 73 20 69 73 20 69  n a process is i
1b60: 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
1b70: 61 20 64 61 74 61 62 61 73 65 0a 75 70 64 61 74  a database.updat
1b80: 65 20 61 6e 64 20 61 20 70 72 6f 67 72 61 6d 20  e and a program 
1b90: 6f 72 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  or operating sys
1ba0: 74 65 6d 20 63 72 61 73 68 20 6f 72 20 70 6f 77  tem crash or pow
1bb0: 65 72 20 66 61 69 6c 75 72 65 20 70 72 65 76 65  er failure preve
1bc0: 6e 74 73 20 0a 74 68 65 20 75 70 64 61 74 65 20  nts .the update 
1bd0: 66 72 6f 6d 20 63 6f 6d 70 6c 65 74 69 6e 67 2e  from completing.
1be0: 0a 48 6f 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72  .Hot journals ar
1bf0: 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 63  e an exception c
1c00: 6f 6e 64 69 74 69 6f 6e 2e 20 0a 48 6f 74 20 6a  ondition. .Hot j
1c10: 6f 75 72 6e 61 6c 73 20 65 78 69 73 74 20 74 6f  ournals exist to
1c20: 20 72 65 63 6f 76 65 72 20 66 72 6f 6d 20 63 72   recover from cr
1c30: 61 73 68 65 73 20 61 6e 64 20 70 6f 77 65 72 20  ashes and power 
1c40: 66 61 69 6c 75 72 65 73 2e 0a 49 66 20 65 76 65  failures..If eve
1c50: 72 79 74 68 69 6e 67 20 69 73 20 77 6f 72 6b 69  rything is worki
1c60: 6e 67 20 63 6f 72 72 65 63 74 6c 79 20 0a 28 74  ng correctly .(t
1c70: 68 61 74 20 69 73 2c 20 69 66 20 74 68 65 72 65  hat is, if there
1c80: 20 61 72 65 20 6e 6f 20 63 72 61 73 68 65 73 20   are no crashes 
1c90: 6f 72 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65  or power failure
1ca0: 73 29 0a 79 6f 75 20 77 69 6c 6c 20 6e 65 76 65  s).you will neve
1cb0: 72 20 67 65 74 20 61 20 68 6f 74 20 6a 6f 75 72  r get a hot jour
1cc0: 6e 61 6c 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 49  nal..</p>..<p>.I
1cd0: 66 20 6e 6f 20 6d 61 73 74 65 72 20 6a 6f 75 72  f no master jour
1ce0: 6e 61 6c 20 69 73 20 69 6e 76 6f 6c 76 65 64 2c  nal is involved,
1cf0: 20 74 68 65 6e 0a 61 20 6a 6f 75 72 6e 61 6c 20   then.a journal 
1d00: 69 73 20 68 6f 74 20 69 66 20 69 74 20 65 78 69  is hot if it exi
1d10: 73 74 73 20 61 6e 64 20 69 74 73 20 63 6f 72 72  sts and its corr
1d20: 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 62 61  esponding databa
1d30: 73 65 20 66 69 6c 65 0a 64 6f 65 73 20 6e 6f 74  se file.does not
1d40: 20 68 61 76 65 20 61 20 52 45 53 45 52 56 45 44   have a RESERVED
1d50: 20 6c 6f 63 6b 2e 0a 49 66 20 61 20 6d 61 73 74   lock..If a mast
1d60: 65 72 20 6a 6f 75 72 6e 61 6c 20 69 73 20 6e 61  er journal is na
1d70: 6d 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20  med in the file 
1d80: 6a 6f 75 72 6e 61 6c 2c 20 74 68 65 6e 20 74 68  journal, then th
1d90: 65 20 66 69 6c 65 20 6a 6f 75 72 6e 61 6c 0a 69  e file journal.i
1da0: 73 20 68 6f 74 20 69 66 20 69 74 73 20 6d 61 73  s hot if its mas
1db0: 74 65 72 20 6a 6f 75 72 6e 61 6c 20 65 78 69 73  ter journal exis
1dc0: 74 73 20 61 6e 64 20 74 68 65 72 65 20 69 73 20  ts and there is 
1dd0: 6e 6f 20 52 45 53 45 52 56 45 44 0a 6c 6f 63 6b  no RESERVED.lock
1de0: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
1df0: 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  nding database f
1e00: 69 6c 65 2e 0a 49 74 20 69 73 20 69 6d 70 6f 72  ile..It is impor
1e10: 74 61 6e 74 20 74 6f 20 75 6e 64 65 72 73 74 61  tant to understa
1e20: 6e 64 20 77 68 65 6e 20 61 20 6a 6f 75 72 6e 61  nd when a journa
1e30: 6c 20 69 73 20 68 6f 74 20 73 6f 20 74 68 65 0a  l is hot so the.
1e40: 70 72 65 63 65 64 69 6e 67 20 72 75 6c 65 73 20  preceding rules 
1e50: 77 69 6c 6c 20 62 65 20 72 65 70 65 61 74 65 64  will be repeated
1e60: 20 69 6e 20 62 75 6c 6c 65 74 73 3a 0a 3c 2f 70   in bullets:.</p
1e70: 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 41 20 6a 6f  >..<ul>.<li>A jo
1e80: 75 72 6e 61 6c 20 69 73 20 68 6f 74 20 69 66 2e  urnal is hot if.
1e90: 2e 2e 0a 20 20 20 20 3c 75 6c 3e 0a 20 20 20 20  ...    <ul>.    
1ea0: 3c 6c 69 3e 49 74 20 65 78 69 73 74 73 2c 20 61  <li>It exists, a
1eb0: 6e 64 3c 2f 6c 69 3e 0a 20 20 20 20 3c 6c 69 3e  nd</li>.    <li>
1ec0: 49 74 27 73 20 6d 61 73 74 65 72 20 6a 6f 75 72  It's master jour
1ed0: 6e 61 6c 20 65 78 69 73 74 73 20 6f 72 20 74 68  nal exists or th
1ee0: 65 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61 6c  e master journal
1ef0: 20 6e 61 6d 65 20 69 73 20 61 6e 0a 20 20 20 20   name is an.    
1f00: 20 20 20 20 65 6d 70 74 79 20 73 74 72 69 6e 67      empty string
1f10: 2c 20 61 6e 64 3c 2f 6c 69 3e 0a 20 20 20 20 3c  , and</li>.    <
1f20: 6c 69 3e 54 68 65 72 65 20 69 73 20 6e 6f 20 52  li>There is no R
1f30: 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
1f40: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
1f50: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  g database file.
1f60: 3c 2f 6c 69 3e 0a 20 20 20 20 3c 2f 75 6c 3e 0a  </li>.    </ul>.
1f70: 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a 7d 0a 0a 48  </li>.</ul>.}..H
1f80: 45 41 44 49 4e 47 20 32 20 7b 44 65 61 6c 69 6e  EADING 2 {Dealin
1f90: 67 20 77 69 74 68 20 68 6f 74 20 6a 6f 75 72 6e  g with hot journ
1fa0: 61 6c 73 7d 20 68 6f 74 5f 6a 6f 75 72 6e 61 6c  als} hot_journal
1fb0: 73 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 0a 42 65  s..puts {.<p>.Be
1fc0: 66 6f 72 65 20 72 65 61 64 69 6e 67 20 66 72 6f  fore reading fro
1fd0: 6d 20 61 20 61 20 64 61 74 61 62 61 73 65 20 66  m a a database f
1fe0: 69 6c 65 2c 20 53 51 4c 69 74 65 20 61 6c 77 61  ile, SQLite alwa
1ff0: 79 73 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65  ys checks to see
2000: 20 69 66 20 74 68 61 74 0a 64 61 74 61 62 61 73   if that.databas
2010: 65 20 66 69 6c 65 20 68 61 73 20 61 20 68 6f 74  e file has a hot
2020: 20 6a 6f 75 72 6e 61 6c 2e 20 20 49 66 20 74 68   journal.  If th
2030: 65 20 66 69 6c 65 20 64 6f 65 73 20 68 61 76 65  e file does have
2040: 20 61 20 68 6f 74 20 6a 6f 75 72 6e 61 6c 2c 20   a hot journal, 
2050: 74 68 65 6e 0a 74 68 65 20 6a 6f 75 72 6e 61 6c  then.the journal
2060: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
2070: 62 65 66 6f 72 65 20 74 68 65 20 66 69 6c 65 20  before the file 
2080: 69 73 20 72 65 61 64 2e 20 20 49 6e 20 74 68 69  is read.  In thi
2090: 73 20 77 61 79 2c 20 77 65 20 65 6e 73 75 72 65  s way, we ensure
20a0: 0a 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61  .that the databa
20b0: 73 65 20 66 69 6c 65 20 69 73 20 69 6e 20 61 20  se file is in a 
20c0: 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
20d0: 20 62 65 66 6f 72 65 20 69 74 20 69 73 20 72 65   before it is re
20e0: 61 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 57 68 65  ad..</p>..<p>Whe
20f0: 6e 20 61 20 70 72 6f 63 65 73 73 20 77 61 6e 74  n a process want
2100: 73 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61  s to read from a
2110: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
2120: 69 74 20 66 6f 6c 6c 6f 77 65 64 0a 74 68 65 20  it followed.the 
2130: 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 71 75 65 6e  following sequen
2140: 63 65 20 6f 66 20 73 74 65 70 73 3a 0a 3c 2f 70  ce of steps:.</p
2150: 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 4f 70 65 6e  >..<ol>.<li>Open
2160: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2170: 6c 65 20 61 6e 64 20 6f 62 74 61 69 6e 20 61 20  le and obtain a 
2180: 53 48 41 52 45 44 20 6c 6f 63 6b 2e 20 20 49 66  SHARED lock.  If
2190: 20 74 68 65 20 53 48 41 52 45 44 20 6c 6f 63 6b   the SHARED lock
21a0: 0a 20 20 20 20 63 61 6e 6e 6f 74 20 62 65 20 6f  .    cannot be o
21b0: 62 74 61 69 6e 65 64 2c 20 66 61 69 6c 20 69 6d  btained, fail im
21c0: 6d 65 64 69 61 74 65 6c 79 20 61 6e 64 20 72 65  mediately and re
21d0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59  turn SQLITE_BUSY
21e0: 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 43 68 65 63 6b  .</li>.<li>Check
21f0: 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 64   to see if the d
2200: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 73  atabase file has
2210: 20 61 20 68 6f 74 20 6a 6f 75 72 6e 61 6c 2e 20   a hot journal. 
2220: 20 20 49 66 20 74 68 65 20 66 69 6c 65 0a 20 20    If the file.  
2230: 20 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20    does not have 
2240: 61 20 68 6f 74 20 6a 6f 75 72 6e 61 6c 2c 20 77  a hot journal, w
2250: 65 20 61 72 65 20 64 6f 6e 65 2e 20 20 52 65 74  e are done.  Ret
2260: 75 72 6e 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  urn immediately.
2270: 0a 20 20 20 20 49 66 20 74 68 65 72 65 20 69 73  .    If there is
2280: 20 61 20 68 6f 74 20 6a 6f 75 72 6e 61 6c 2c 20   a hot journal, 
2290: 74 68 61 74 20 6a 6f 75 72 6e 61 6c 20 6d 75 73  that journal mus
22a0: 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
22b0: 20 62 79 0a 20 20 20 20 74 68 65 20 73 75 62 73   by.    the subs
22c0: 65 71 75 65 6e 74 20 73 74 65 70 73 20 6f 66 20  equent steps of 
22d0: 74 68 69 73 20 61 6c 67 6f 72 69 74 68 6d 2e 3c  this algorithm.<
22e0: 2f 6c 69 3e 0a 3c 6c 69 3e 41 63 71 75 69 72 65  /li>.<li>Acquire
22f0: 20 61 20 50 45 4e 44 49 4e 47 20 6c 6f 63 6b 20   a PENDING lock 
2300: 74 68 65 6e 20 61 6e 20 45 58 43 4c 55 53 49 56  then an EXCLUSIV
2310: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  E lock on the da
2320: 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 20 20 20  tabase file..   
2330: 20 28 4e 6f 74 65 3a 20 44 6f 20 6e 6f 74 20 61   (Note: Do not a
2340: 63 71 75 69 72 65 20 61 20 52 45 53 45 52 56 45  cquire a RESERVE
2350: 44 20 6c 6f 63 6b 20 62 65 63 61 75 73 65 20 74  D lock because t
2360: 68 61 74 20 77 6f 75 6c 64 20 6d 61 6b 65 0a 20  hat would make. 
2370: 20 20 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73     other process
2380: 65 73 20 74 68 69 6e 6b 20 74 68 65 20 6a 6f 75  es think the jou
2390: 72 6e 61 6c 20 77 61 73 20 6e 6f 20 6c 6f 6e 67  rnal was no long
23a0: 65 72 20 68 6f 74 2e 29 20 20 49 66 20 77 65 0a  er hot.)  If we.
23b0: 20 20 20 20 66 61 69 6c 20 74 6f 20 61 63 71 75      fail to acqu
23c0: 69 72 65 20 74 68 65 73 65 20 6c 6f 63 6b 73 20  ire these locks 
23d0: 69 74 20 6d 65 61 6e 73 20 61 6e 6f 74 68 65 72  it means another
23e0: 20 70 72 6f 63 65 73 73 0a 20 20 20 20 69 73 20   process.    is 
23f0: 61 6c 72 65 61 64 79 20 74 72 79 69 6e 67 20 74  already trying t
2400: 6f 20 64 6f 20 74 68 65 20 72 6f 6c 6c 62 61 63  o do the rollbac
2410: 6b 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  k.  In that case
2420: 2c 0a 20 20 20 20 64 72 6f 70 20 61 6c 6c 20 6c  ,.    drop all l
2430: 6f 63 6b 73 2c 20 63 6c 6f 73 65 20 74 68 65 20  ocks, close the 
2440: 64 61 74 61 62 61 73 65 2c 20 61 6e 64 20 72 65  database, and re
2450: 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59  turn SQLITE_BUSY
2460: 2e 20 3c 2f 6c 69 3e 0a 3c 6c 69 3e 52 65 61 64  . </li>.<li>Read
2470: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c   the journal fil
2480: 65 20 61 6e 64 20 72 6f 6c 6c 20 62 61 63 6b 20  e and roll back 
2490: 74 68 65 20 63 68 61 6e 67 65 73 2e 3c 2f 6c 69  the changes.</li
24a0: 3e 0a 3c 6c 69 3e 57 61 69 74 20 66 6f 72 20 74  >.<li>Wait for t
24b0: 68 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 63  he rolled back c
24c0: 68 61 6e 67 65 73 20 74 6f 20 62 65 20 77 72 69  hanges to be wri
24d0: 74 74 65 6e 20 6f 6e 74 6f 20 0a 20 20 20 20 74  tten onto .    t
24e0: 68 65 20 73 75 72 66 61 63 65 20 6f 66 20 74 68  he surface of th
24f0: 65 20 64 69 73 6b 2e 20 20 54 68 69 73 20 70 72  e disk.  This pr
2500: 6f 74 65 63 74 73 20 74 68 65 20 69 6e 74 65 67  otects the integ
2510: 72 69 74 79 20 6f 66 20 74 68 65 20 64 61 74 61  rity of the data
2520: 62 61 73 65 0a 20 20 20 20 69 6e 20 63 61 73 65  base.    in case
2530: 20 61 6e 6f 74 68 65 72 20 70 6f 77 65 72 20 66   another power f
2540: 61 69 6c 75 72 65 20 6f 72 20 63 72 61 73 68 20  ailure or crash 
2550: 6f 63 63 75 72 73 2e 3c 2f 6c 69 3e 0a 3c 6c 69  occurs.</li>.<li
2560: 3e 44 65 6c 65 74 65 20 74 68 65 20 6a 6f 75 72  >Delete the jour
2570: 6e 61 6c 20 66 69 6c 65 2e 3c 2f 6c 69 3e 0a 3c  nal file.</li>.<
2580: 6c 69 3e 44 65 6c 65 74 65 20 74 68 65 20 6d 61  li>Delete the ma
2590: 73 74 65 72 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  ster journal fil
25a0: 65 20 69 66 20 69 74 20 69 73 20 73 61 66 65 20  e if it is safe 
25b0: 74 6f 20 64 6f 20 73 6f 2e 0a 20 20 20 20 54 68  to do so..    Th
25c0: 69 73 20 73 74 65 70 20 69 73 20 6f 70 74 69 6f  is step is optio
25d0: 6e 61 6c 2e 20 20 49 74 20 69 73 20 68 65 72 65  nal.  It is here
25e0: 20 6f 6e 6c 79 20 74 6f 20 70 72 65 76 65 6e 74   only to prevent
25f0: 20 73 74 61 6c 65 0a 20 20 20 20 6d 61 73 74 65   stale.    maste
2600: 72 20 6a 6f 75 72 6e 61 6c 73 20 66 72 6f 6d 20  r journals from 
2610: 63 6c 75 74 74 65 72 69 6e 67 20 75 70 20 74 68  cluttering up th
2620: 65 20 64 69 73 6b 20 64 72 69 76 65 2e 0a 20 20  e disk drive..  
2630: 20 20 53 65 65 20 74 68 65 20 64 69 73 63 75 73    See the discus
2640: 73 69 6f 6e 20 62 65 6c 6f 77 20 66 6f 72 20 64  sion below for d
2650: 65 74 61 69 6c 73 2e 3c 2f 6c 69 3e 0a 3c 6c 69  etails.</li>.<li
2660: 3e 44 72 6f 70 20 74 68 65 20 45 58 43 4c 55 53  >Drop the EXCLUS
2670: 49 56 45 20 61 6e 64 20 50 45 4e 44 49 4e 47 20  IVE and PENDING 
2680: 6c 6f 63 6b 73 20 62 75 74 20 72 65 74 61 69 6e  locks but retain
2690: 20 74 68 65 20 53 48 41 52 45 44 20 6c 6f 63 6b   the SHARED lock
26a0: 2e 3c 2f 6c 69 3e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70  .</li>.</ol>..<p
26b0: 3e 41 66 74 65 72 20 74 68 65 20 61 6c 67 6f 72  >After the algor
26c0: 69 74 68 6d 20 61 62 6f 76 65 20 63 6f 6d 70 6c  ithm above compl
26d0: 65 74 65 73 20 73 75 63 63 65 73 73 66 75 6c 6c  etes successfull
26e0: 79 2c 20 69 74 20 69 73 20 73 61 66 65 20 74 6f  y, it is safe to
26f0: 20 0a 72 65 61 64 20 66 72 6f 6d 20 74 68 65 20   .read from the 
2700: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 20  database file.  
2710: 4f 6e 63 65 20 61 6c 6c 20 72 65 61 64 69 6e 67  Once all reading
2720: 20 68 61 73 20 63 6f 6d 70 6c 65 74 65 64 2c 20   has completed, 
2730: 74 68 65 0a 53 48 41 52 45 44 20 6c 6f 63 6b 20  the.SHARED lock 
2740: 69 73 20 64 72 6f 70 70 65 64 2e 3c 2f 70 3e 0a  is dropped.</p>.
2750: 7d 0a 0a 48 45 41 44 49 4e 47 20 32 20 7b 44 65  }..HEADING 2 {De
2760: 6c 65 74 69 6e 67 20 73 74 61 6c 65 20 6d 61 73  leting stale mas
2770: 74 65 72 20 6a 6f 75 72 6e 61 6c 73 7d 20 73 74  ter journals} st
2780: 61 6c 65 5f 6d 61 73 74 65 72 5f 6a 6f 75 72 6e  ale_master_journ
2790: 61 6c 73 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 41  als..puts {.<p>A
27a0: 20 73 74 61 6c 65 20 6d 61 73 74 65 72 20 6a 6f   stale master jo
27b0: 75 72 6e 61 6c 20 69 73 20 61 20 6d 61 73 74 65  urnal is a maste
27c0: 72 20 6a 6f 75 72 6e 61 6c 20 74 68 61 74 20 69  r journal that i
27d0: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 62 65 69 6e  s no longer bein
27e0: 67 0a 75 73 65 64 20 66 6f 72 20 61 6e 79 74 68  g.used for anyth
27f0: 69 6e 67 2e 20 20 54 68 65 72 65 20 69 73 20 6e  ing.  There is n
2800: 6f 20 72 65 71 75 69 72 65 6d 65 6e 74 20 74 68  o requirement th
2810: 61 74 20 73 74 61 6c 65 20 6d 61 73 74 65 72 20  at stale master 
2820: 6a 6f 75 72 6e 61 6c 73 0a 62 65 20 64 65 6c 65  journals.be dele
2830: 74 65 64 2e 20 20 54 68 65 20 6f 6e 6c 79 20 72  ted.  The only r
2840: 65 61 73 6f 6e 20 66 6f 72 20 64 6f 69 6e 67 20  eason for doing 
2850: 73 6f 20 69 73 20 74 6f 20 66 72 65 65 20 75 70  so is to free up
2860: 20 64 69 73 6b 20 73 70 61 63 65 2e 3c 2f 70 3e   disk space.</p>
2870: 0a 0a 3c 70 3e 41 20 6d 61 73 74 65 72 20 6a 6f  ..<p>A master jo
2880: 75 72 6e 61 6c 20 69 73 20 73 74 61 6c 65 20 69  urnal is stale i
2890: 66 20 6e 6f 20 69 6e 64 69 76 69 64 75 61 6c 20  f no individual 
28a0: 66 69 6c 65 20 6a 6f 75 72 6e 61 6c 73 20 61 72  file journals ar
28b0: 65 20 70 6f 69 6e 74 69 6e 67 0a 74 6f 20 69 74  e pointing.to it
28c0: 2e 20 20 54 6f 20 66 69 67 75 72 65 20 6f 75 74  .  To figure out
28d0: 20 69 66 20 61 20 6d 61 73 74 65 72 20 6a 6f 75   if a master jou
28e0: 72 6e 61 6c 20 69 73 20 73 74 61 6c 65 2c 20 77  rnal is stale, w
28f0: 65 20 66 69 72 73 74 20 72 65 61 64 20 74 68 65  e first read the
2900: 0a 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61 6c 20  .master journal 
2910: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
2920: 6d 65 73 20 6f 66 20 61 6c 6c 20 6f 66 20 69 74  mes of all of it
2930: 73 20 66 69 6c 65 20 6a 6f 75 72 6e 61 6c 73 2e  s file journals.
2940: 20 20 54 68 65 6e 0a 77 65 20 63 68 65 63 6b 20    Then.we check 
2950: 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 66 69  each of those fi
2960: 6c 65 20 6a 6f 75 72 6e 61 6c 73 2e 20 20 49 66  le journals.  If
2970: 20 61 6e 79 20 6f 66 20 74 68 65 20 66 69 6c 65   any of the file
2980: 20 6a 6f 75 72 6e 61 6c 73 20 6e 61 6d 65 64 0a   journals named.
2990: 69 6e 20 74 68 65 20 6d 61 73 74 65 72 20 6a 6f  in the master jo
29a0: 75 72 6e 61 6c 20 65 78 69 73 74 73 20 61 6e 64  urnal exists and
29b0: 20 70 6f 69 6e 74 73 20 62 61 63 6b 20 74 6f 20   points back to 
29c0: 74 68 65 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e  the master journ
29d0: 61 6c 2c 20 74 68 65 6e 0a 74 68 65 20 6d 61 73  al, then.the mas
29e0: 74 65 72 20 6a 6f 75 72 6e 61 6c 20 69 73 20 6e  ter journal is n
29f0: 6f 74 20 73 74 61 6c 65 2e 20 20 49 66 20 61 6c  ot stale.  If al
2a00: 6c 20 66 69 6c 65 20 6a 6f 75 72 6e 61 6c 73 20  l file journals 
2a10: 61 72 65 20 65 69 74 68 65 72 20 6d 69 73 73 69  are either missi
2a20: 6e 67 0a 6f 72 20 72 65 66 65 72 20 74 6f 20 6f  ng.or refer to o
2a30: 74 68 65 72 20 6d 61 73 74 65 72 20 6a 6f 75 72  ther master jour
2a40: 6e 61 6c 73 20 6f 72 20 6e 6f 20 6d 61 73 74 65  nals or no maste
2a50: 72 20 6a 6f 75 72 6e 61 6c 20 61 74 20 61 6c 6c  r journal at all
2a60: 2c 20 74 68 65 6e 20 74 68 65 0a 6d 61 73 74 65  , then the.maste
2a70: 72 20 6a 6f 75 72 6e 61 6c 20 77 65 20 61 72 65  r journal we are
2a80: 20 74 65 73 74 69 6e 67 20 69 73 20 73 74 61 6c   testing is stal
2a90: 65 20 61 6e 64 20 63 61 6e 20 62 65 20 73 61 66  e and can be saf
2aa0: 65 6c 79 20 64 65 6c 65 74 65 64 2e 3c 2f 70 3e  ely deleted.</p>
2ab0: 0a 7d 0a 0a 48 45 41 44 49 4e 47 20 31 20 7b 57  .}..HEADING 1 {W
2ac0: 72 69 74 69 6e 67 20 74 6f 20 61 20 64 61 74 61  riting to a data
2ad0: 62 61 73 65 20 66 69 6c 65 7d 20 77 72 69 74 69  base file} writi
2ae0: 6e 67 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 54 6f  ng..puts {.<p>To
2af0: 20 77 72 69 74 65 20 74 6f 20 61 20 64 61 74 61   write to a data
2b00: 62 61 73 65 2c 20 61 20 70 72 6f 63 65 73 73 20  base, a process 
2b10: 6d 75 73 74 20 66 69 72 73 74 20 61 63 71 75 69  must first acqui
2b20: 72 65 20 61 20 53 48 41 52 45 44 20 6c 6f 63 6b  re a SHARED lock
2b30: 0a 61 73 20 64 65 73 63 72 69 62 65 64 20 61 62  .as described ab
2b40: 6f 76 65 20 28 70 6f 73 73 69 62 6c 79 20 72 6f  ove (possibly ro
2b50: 6c 6c 69 6e 67 20 62 61 63 6b 20 69 6e 63 6f 6d  lling back incom
2b60: 70 6c 65 74 65 20 63 68 61 6e 67 65 73 20 69 66  plete changes if
2b70: 20 74 68 65 72 65 0a 69 73 20 61 20 68 6f 74 20   there.is a hot 
2b80: 6a 6f 75 72 6e 61 6c 29 2e 20 0a 41 66 74 65 72  journal). .After
2b90: 20 61 20 53 48 41 52 45 44 20 6c 6f 63 6b 20 69   a SHARED lock i
2ba0: 73 20 6f 62 74 61 69 6e 65 64 2c 20 61 20 52 45  s obtained, a RE
2bb0: 53 45 52 56 45 44 20 6c 6f 63 6b 20 6d 75 73 74  SERVED lock must
2bc0: 20 62 65 20 61 63 71 75 69 72 65 64 2e 0a 54 68   be acquired..Th
2bd0: 65 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  e RESERVED lock 
2be0: 73 69 67 6e 61 6c 73 20 74 68 61 74 20 74 68 65  signals that the
2bf0: 20 70 72 6f 63 65 73 73 20 69 6e 74 65 6e 64 73   process intends
2c00: 20 74 6f 20 77 72 69 74 65 20 74 6f 20 74 68 65   to write to the
2c10: 0a 64 61 74 61 62 61 73 65 20 61 74 20 73 6f 6d  .database at som
2c20: 65 20 70 6f 69 6e 74 20 69 6e 20 74 68 65 20 66  e point in the f
2c30: 75 74 75 72 65 2e 20 20 4f 6e 6c 79 20 6f 6e 65  uture.  Only one
2c40: 20 70 72 6f 63 65 73 73 20 61 74 20 61 20 74 69   process at a ti
2c50: 6d 65 0a 63 61 6e 20 68 6f 6c 64 20 61 20 52 45  me.can hold a RE
2c60: 53 45 52 56 45 44 20 6c 6f 63 6b 2e 20 20 42 75  SERVED lock.  Bu
2c70: 74 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  t other processe
2c80: 73 20 63 61 6e 20 63 6f 6e 74 69 6e 75 65 20 74  s can continue t
2c90: 6f 20 72 65 61 64 0a 74 68 65 20 64 61 74 61 62  o read.the datab
2ca0: 61 73 65 20 77 68 69 6c 65 20 74 68 65 20 52 45  ase while the RE
2cb0: 53 45 52 56 45 44 20 6c 6f 63 6b 20 69 73 20 68  SERVED lock is h
2cc0: 65 6c 64 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 49 66  eld..</p>..<p>If
2cd0: 20 74 68 65 20 70 72 6f 63 65 73 73 20 74 68 61   the process tha
2ce0: 74 20 77 61 6e 74 73 20 74 6f 20 77 72 69 74 65  t wants to write
2cf0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
2d00: 74 61 69 6e 20 61 20 52 45 53 45 52 56 45 44 0a  tain a RESERVED.
2d10: 6c 6f 63 6b 2c 20 69 74 20 6d 75 73 74 20 6d 65  lock, it must me
2d20: 61 6e 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  an that another 
2d30: 70 72 6f 63 65 73 73 20 61 6c 72 65 61 64 79 20  process already 
2d40: 68 61 73 20 61 20 52 45 53 45 52 56 45 44 20 6c  has a RESERVED l
2d50: 6f 63 6b 2e 0a 49 6e 20 74 68 61 74 20 63 61 73  ock..In that cas
2d60: 65 2c 20 74 68 65 20 77 72 69 74 65 20 61 74 74  e, the write att
2d70: 65 6d 70 74 20 66 61 69 6c 73 20 61 6e 64 20 72  empt fails and r
2d80: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 42 55  eturns SQLITE_BU
2d90: 53 59 2e 3c 2f 70 3e 0a 0a 3c 70 3e 41 66 74 65  SY.</p>..<p>Afte
2da0: 72 20 6f 62 74 61 69 6e 69 6e 67 20 61 20 52 45  r obtaining a RE
2db0: 53 45 52 56 45 44 20 6c 6f 63 6b 2c 20 74 68 65  SERVED lock, the
2dc0: 20 70 72 6f 63 65 73 73 20 74 68 61 74 20 77 61   process that wa
2dd0: 6e 74 73 20 74 6f 20 77 72 69 74 65 0a 63 72 65  nts to write.cre
2de0: 61 74 65 73 20 61 20 72 6f 6c 6c 62 61 63 6b 20  ates a rollback 
2df0: 6a 6f 75 72 6e 61 6c 2e 20 20 54 68 65 20 68 65  journal.  The he
2e00: 61 64 65 72 20 6f 66 20 74 68 65 20 6a 6f 75 72  ader of the jour
2e10: 6e 61 6c 20 69 73 20 69 6e 69 74 69 61 6c 69 7a  nal is initializ
2e20: 65 64 0a 77 69 74 68 20 74 68 65 20 6f 72 69 67  ed.with the orig
2e30: 69 6e 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  inal size of the
2e40: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
2e50: 20 53 70 61 63 65 20 69 6e 20 74 68 65 20 6a 6f   Space in the jo
2e60: 75 72 6e 61 6c 20 68 65 61 64 65 72 0a 69 73 20  urnal header.is 
2e70: 61 6c 73 6f 20 72 65 73 65 72 76 65 64 20 66 6f  also reserved fo
2e80: 72 20 61 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e  r a master journ
2e90: 61 6c 20 6e 61 6d 65 2c 20 74 68 6f 75 67 68 20  al name, though 
2ea0: 74 68 65 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e  the master journ
2eb0: 61 6c 0a 6e 61 6d 65 20 69 73 20 69 6e 69 74 69  al.name is initi
2ec0: 61 6c 6c 79 20 65 6d 70 74 79 2e 3c 2f 70 3e 0a  ally empty.</p>.
2ed0: 0a 3c 70 3e 42 65 66 6f 72 65 20 6d 61 6b 69 6e  .<p>Before makin
2ee0: 67 20 63 68 61 6e 67 65 73 20 74 6f 20 61 6e 79  g changes to any
2ef0: 20 70 61 67 65 20 6f 66 20 74 68 65 20 64 61 74   page of the dat
2f00: 61 62 61 73 65 2c 20 74 68 65 20 70 72 6f 63 65  abase, the proce
2f10: 73 73 20 77 72 69 74 65 73 0a 74 68 65 20 6f 72  ss writes.the or
2f20: 69 67 69 6e 61 6c 20 63 6f 6e 74 65 6e 74 20 6f  iginal content o
2f30: 66 20 74 68 61 74 20 70 61 67 65 20 69 6e 74 6f  f that page into
2f40: 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f   the rollback jo
2f50: 75 72 6e 61 6c 2e 20 20 43 68 61 6e 67 65 73 0a  urnal.  Changes.
2f60: 74 6f 20 70 61 67 65 73 20 61 72 65 20 68 65 6c  to pages are hel
2f70: 64 20 69 6e 20 6d 65 6d 6f 72 79 20 61 74 20 66  d in memory at f
2f80: 69 72 73 74 20 61 6e 64 20 61 72 65 20 6e 6f 74  irst and are not
2f90: 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68 65 20   written to the 
2fa0: 64 69 73 6b 2e 0a 54 68 65 20 6f 72 69 67 69 6e  disk..The origin
2fb0: 61 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  al database file
2fc0: 20 72 65 6d 61 69 6e 73 20 75 6e 61 6c 74 65 72   remains unalter
2fd0: 65 64 2c 20 77 68 69 63 68 20 6d 65 61 6e 73 20  ed, which means 
2fe0: 74 68 61 74 20 6f 74 68 65 72 0a 70 72 6f 63 65  that other.proce
2ff0: 73 73 65 73 20 63 61 6e 20 63 6f 6e 74 69 6e 75  sses can continu
3000: 65 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61  e to read the da
3010: 74 61 62 61 73 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e  tabase.</p>..<p>
3020: 45 76 65 6e 74 75 61 6c 6c 79 2c 20 74 68 65 20  Eventually, the 
3030: 77 72 69 74 69 6e 67 20 70 72 6f 63 65 73 73 20  writing process 
3040: 77 69 6c 6c 20 77 61 6e 74 20 74 6f 20 75 70 64  will want to upd
3050: 61 74 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ate the database
3060: 0a 66 69 6c 65 2c 20 65 69 74 68 65 72 20 62 65  .file, either be
3070: 63 61 75 73 65 20 69 74 73 20 6d 65 6d 6f 72 79  cause its memory
3080: 20 63 61 63 68 65 20 68 61 73 20 66 69 6c 6c 65   cache has fille
3090: 64 20 75 70 20 6f 72 20 62 65 63 61 75 73 65 20  d up or because 
30a0: 69 74 20 69 73 0a 72 65 61 64 79 20 74 6f 20 63  it is.ready to c
30b0: 6f 6d 6d 69 74 20 69 74 73 20 63 68 61 6e 67 65  ommit its change
30c0: 73 2e 20 20 42 65 66 6f 72 65 20 74 68 69 73 20  s.  Before this 
30d0: 68 61 70 70 65 6e 73 2c 20 74 68 65 20 77 72 69  happens, the wri
30e0: 74 65 72 20 6d 75 73 74 0a 6d 61 6b 65 20 73 75  ter must.make su
30f0: 72 65 20 6e 6f 20 6f 74 68 65 72 20 70 72 6f 63  re no other proc
3100: 65 73 73 20 69 73 20 72 65 61 64 69 6e 67 20 74  ess is reading t
3110: 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
3120: 74 68 61 74 20 74 68 65 20 72 6f 6c 6c 62 61 63  that the rollbac
3130: 6b 0a 6a 6f 75 72 6e 61 6c 20 64 61 74 61 20 69  k.journal data i
3140: 73 20 73 61 66 65 6c 79 20 6f 6e 20 74 68 65 20  s safely on the 
3150: 64 69 73 6b 20 73 75 72 66 61 63 65 20 73 6f 20  disk surface so 
3160: 74 68 61 74 20 69 74 20 63 61 6e 20 62 65 20 75  that it can be u
3170: 73 65 64 20 74 6f 0a 72 6f 6c 6c 62 61 63 6b 20  sed to.rollback 
3180: 69 6e 63 6f 6d 70 6c 65 74 65 20 63 68 61 6e 67  incomplete chang
3190: 65 73 20 69 6e 20 74 68 65 20 65 76 65 6e 74 20  es in the event 
31a0: 6f 66 20 61 20 70 6f 77 65 72 20 66 61 69 6c 75  of a power failu
31b0: 72 65 2e 0a 54 68 65 20 73 74 65 70 73 20 61 72  re..The steps ar
31c0: 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70  e as follows:</p
31d0: 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 4d 61 6b 65  >..<ol>.<li>Make
31e0: 20 73 75 72 65 20 61 6c 6c 20 72 6f 6c 6c 62 61   sure all rollba
31f0: 63 6b 20 6a 6f 75 72 6e 61 6c 20 64 61 74 61 20  ck journal data 
3200: 68 61 73 20 61 63 74 75 61 6c 6c 79 20 62 65 65  has actually bee
3210: 6e 20 77 72 69 74 74 65 6e 20 74 6f 0a 20 20 20  n written to.   
3220: 20 74 68 65 20 73 75 72 66 61 63 65 20 6f 66 20   the surface of 
3230: 74 68 65 20 64 69 73 6b 20 28 61 6e 64 20 69 73  the disk (and is
3240: 20 6e 6f 74 20 6a 75 73 74 20 62 65 69 6e 67 20   not just being 
3250: 68 65 6c 64 20 69 6e 20 74 68 65 20 6f 70 65 72  held in the oper
3260: 61 74 69 6e 67 0a 20 20 20 20 73 79 73 74 65 6d  ating.    system
3270: 27 73 20 20 6f 72 20 64 69 73 6b 20 63 6f 6e 74  's  or disk cont
3280: 72 6f 6c 6c 65 72 73 20 63 61 63 68 65 29 20 73  rollers cache) s
3290: 6f 20 74 68 61 74 20 69 66 20 61 20 70 6f 77 65  o that if a powe
32a0: 72 20 66 61 69 6c 75 72 65 20 6f 63 63 75 72 73  r failure occurs
32b0: 0a 20 20 20 20 74 68 65 20 64 61 74 61 20 77 69  .    the data wi
32c0: 6c 6c 20 73 74 69 6c 6c 20 62 65 20 74 68 65 72  ll still be ther
32d0: 65 20 61 66 74 65 72 20 70 6f 77 65 72 20 69 73  e after power is
32e0: 20 72 65 73 74 6f 72 65 64 2e 3c 2f 6c 69 3e 0a   restored.</li>.
32f0: 3c 6c 69 3e 4f 62 74 61 69 6e 20 61 20 50 45 4e  <li>Obtain a PEN
3300: 44 49 4e 47 20 6c 6f 63 6b 20 61 6e 64 20 74 68  DING lock and th
3310: 65 6e 20 61 6e 20 45 58 43 4c 55 53 49 56 45 20  en an EXCLUSIVE 
3320: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
3330: 62 61 73 65 20 66 69 6c 65 2e 0a 20 20 20 20 49  base file..    I
3340: 66 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  f other processe
3350: 73 20 61 72 65 20 73 74 69 6c 6c 20 68 61 76 65  s are still have
3360: 20 53 48 41 52 45 44 20 6c 6f 63 6b 73 2c 20 74   SHARED locks, t
3370: 68 65 20 77 72 69 74 65 72 20 6d 69 67 68 74 20  he writer might 
3380: 68 61 76 65 0a 20 20 20 20 74 6f 20 77 61 69 74  have.    to wait
3390: 20 75 6e 74 69 6c 20 74 68 6f 73 65 20 53 48 41   until those SHA
33a0: 52 45 44 20 6c 6f 63 6b 73 20 63 6c 65 61 72 20  RED locks clear 
33b0: 62 65 66 6f 72 65 20 69 74 20 69 73 20 61 62 6c  before it is abl
33c0: 65 20 74 6f 20 6f 62 74 61 69 6e 0a 20 20 20 20  e to obtain.    
33d0: 61 6e 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  an EXCLUSIVE loc
33e0: 6b 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 57 72 69 74  k.</li>.<li>Writ
33f0: 65 20 61 6c 6c 20 70 61 67 65 20 6d 6f 64 69 66  e all page modif
3400: 69 63 61 74 69 6f 6e 73 20 63 75 72 72 65 6e 74  ications current
3410: 6c 79 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  ly held in memor
3420: 79 20 6f 75 74 20 74 6f 20 74 68 65 0a 20 20 20  y out to the.   
3430: 20 6f 72 69 67 69 6e 61 6c 20 64 61 74 61 62 61   original databa
3440: 73 65 20 64 69 73 6b 20 66 69 6c 65 2e 3c 2f 6c  se disk file.</l
3450: 69 3e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 0a 49 66  i>.</ol>..<p>.If
3460: 20 74 68 65 20 72 65 61 73 6f 6e 20 66 6f 72 20   the reason for 
3470: 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 64  writing to the d
3480: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
3490: 62 65 63 61 75 73 65 20 74 68 65 20 6d 65 6d 6f  because the memo
34a0: 72 79 0a 63 61 63 68 65 20 77 61 73 20 66 75 6c  ry.cache was ful
34b0: 6c 2c 20 74 68 65 6e 20 74 68 65 20 77 72 69 74  l, then the writ
34c0: 65 72 20 77 69 6c 6c 20 6e 6f 74 20 63 6f 6d 6d  er will not comm
34d0: 69 74 20 72 69 67 68 74 20 61 77 61 79 2e 20 20  it right away.  
34e0: 49 6e 73 74 65 61 64 2c 0a 74 68 65 20 77 72 69  Instead,.the wri
34f0: 74 65 72 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  ter might contin
3500: 75 65 20 74 6f 20 6d 61 6b 65 20 63 68 61 6e 67  ue to make chang
3510: 65 73 20 74 6f 20 6f 74 68 65 72 20 70 61 67 65  es to other page
3520: 73 2e 20 20 42 65 66 6f 72 65 20 0a 73 75 62 73  s.  Before .subs
3530: 65 71 75 65 6e 74 20 63 68 61 6e 67 65 73 20 61  equent changes a
3540: 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68  re written to th
3550: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
3560: 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 0a 6a 6f   the rollback.jo
3570: 75 72 6e 61 6c 20 6d 75 73 74 20 62 65 20 66 6c  urnal must be fl
3580: 75 73 68 65 64 20 74 6f 20 64 69 73 6b 20 61 67  ushed to disk ag
3590: 61 69 6e 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20  ain.  Note also 
35a0: 74 68 61 74 20 74 68 65 20 45 58 43 4c 55 53 49  that the EXCLUSI
35b0: 56 45 0a 6c 6f 63 6b 20 74 68 61 74 20 74 68 65  VE.lock that the
35c0: 20 77 72 69 74 65 72 20 6f 62 74 61 69 6e 65 64   writer obtained
35d0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 72 69   in order to wri
35e0: 74 65 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  te to the databa
35f0: 73 65 20 69 6e 69 74 69 61 6c 6c 79 0a 6d 75 73  se initially.mus
3600: 74 20 62 65 20 68 65 6c 64 20 75 6e 74 69 6c 20  t be held until 
3610: 61 6c 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20  all changes are 
3620: 63 6f 6d 6d 69 74 74 65 64 2e 20 20 54 68 61 74  committed.  That
3630: 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 6f   means that no o
3640: 74 68 65 72 0a 70 72 6f 63 65 73 73 65 73 20 61  ther.processes a
3650: 72 65 20 61 62 6c 65 20 74 6f 20 61 63 63 65 73  re able to acces
3660: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
3670: 72 6f 6d 20 74 68 65 0a 74 69 6d 65 20 74 68 65  rom the.time the
3680: 20 6d 65 6d 6f 72 79 20 63 61 63 68 65 20 66 69   memory cache fi
3690: 72 73 74 20 73 70 69 6c 6c 73 20 74 6f 20 64 69  rst spills to di
36a0: 73 6b 20 75 6e 74 69 6c 20 74 68 65 20 74 72 61  sk until the tra
36b0: 6e 73 61 63 74 69 6f 6e 0a 63 6f 6d 6d 69 74 73  nsaction.commits
36c0: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 57 68 65 6e  ..</p>..<p>.When
36d0: 20 61 20 77 72 69 74 65 72 20 69 73 20 72 65 61   a writer is rea
36e0: 64 79 20 74 6f 20 63 6f 6d 6d 69 74 20 69 74 73  dy to commit its
36f0: 20 63 68 61 6e 67 65 73 2c 20 69 74 20 65 78 65   changes, it exe
3700: 63 75 74 65 73 20 74 68 65 20 66 6f 6c 6c 6f 77  cutes the follow
3710: 69 6e 67 0a 73 74 65 70 73 3a 0a 3c 2f 70 3e 0a  ing.steps:.</p>.
3720: 0a 3c 6f 6c 3e 0a 3c 6c 69 20 76 61 6c 75 65 3d  .<ol>.<li value=
3730: 22 34 22 3e 0a 20 20 20 4f 62 74 61 69 6e 20 61  "4">.   Obtain a
3740: 6e 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  n EXCLUSIVE lock
3750: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
3760: 20 66 69 6c 65 20 61 6e 64 0a 20 20 20 6d 61 6b   file and.   mak
3770: 65 20 73 75 72 65 20 61 6c 6c 20 6d 65 6d 6f 72  e sure all memor
3780: 79 20 63 68 61 6e 67 65 73 20 68 61 76 65 20 62  y changes have b
3790: 65 65 6e 20 77 72 69 74 74 65 6e 20 74 6f 20 74  een written to t
37a0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
37b0: 0a 20 20 20 75 73 69 6e 67 20 74 68 65 20 61 6c  .   using the al
37c0: 67 6f 72 69 74 68 6d 20 6f 66 20 73 74 65 70 73  gorithm of steps
37d0: 20 31 2d 33 20 61 62 6f 76 65 2e 3c 2f 6c 69 3e   1-3 above.</li>
37e0: 0a 3c 6c 69 3e 46 6c 75 73 68 20 61 6c 6c 20 64  .<li>Flush all d
37f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 68 61  atabase file cha
3800: 6e 67 65 73 20 74 6f 20 74 68 65 20 64 69 73 6b  nges to the disk
3810: 2e 20 20 57 61 69 74 20 66 6f 72 20 74 68 6f 73  .  Wait for thos
3820: 65 20 63 68 61 6e 67 65 73 0a 20 20 20 20 74 6f  e changes.    to
3830: 20 61 63 74 75 61 6c 6c 79 20 62 65 20 77 72 69   actually be wri
3840: 74 74 65 6e 20 6f 6e 74 6f 20 74 68 65 20 64 69  tten onto the di
3850: 73 6b 20 73 75 72 66 61 63 65 2e 3c 2f 6c 69 3e  sk surface.</li>
3860: 0a 3c 6c 69 3e 44 65 6c 65 74 65 20 74 68 65 20  .<li>Delete the 
3870: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 2e 20 20 54  journal file.  T
3880: 68 69 73 20 69 73 20 74 68 65 20 69 6e 73 74 61  his is the insta
3890: 6e 74 20 77 68 65 6e 20 74 68 65 20 63 68 61 6e  nt when the chan
38a0: 67 65 73 20 61 72 65 0a 20 20 20 20 63 6f 6d 6d  ges are.    comm
38b0: 69 74 74 65 64 2e 20 20 50 72 69 6f 72 20 74 6f  itted.  Prior to
38c0: 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 6a 6f   deleting the jo
38d0: 75 72 6e 61 6c 20 66 69 6c 65 2c 20 69 66 20 61  urnal file, if a
38e0: 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65 0a 20   power failure. 
38f0: 20 20 20 6f 72 20 63 72 61 73 68 20 6f 63 63 75     or crash occu
3900: 72 73 2c 20 74 68 65 20 6e 65 78 74 20 70 72 6f  rs, the next pro
3910: 63 65 73 73 20 74 6f 20 6f 70 65 6e 20 74 68 65  cess to open the
3920: 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 73   database will s
3930: 65 65 20 74 68 61 74 0a 20 20 20 20 69 74 20 68  ee that.    it h
3940: 61 73 20 61 20 68 6f 74 20 6a 6f 75 72 6e 61 6c  as a hot journal
3950: 20 61 6e 64 20 77 69 6c 6c 20 72 6f 6c 6c 20 74   and will roll t
3960: 68 65 20 63 68 61 6e 67 65 73 20 62 61 63 6b 2e  he changes back.
3970: 0a 20 20 20 20 41 66 74 65 72 20 74 68 65 20 6a  .    After the j
3980: 6f 75 72 6e 61 6c 20 69 73 20 64 65 6c 65 74 65  ournal is delete
3990: 64 2c 20 74 68 65 72 65 20 77 69 6c 6c 20 6e 6f  d, there will no
39a0: 20 6c 6f 6e 67 65 72 20 62 65 20 61 20 68 6f 74   longer be a hot
39b0: 20 6a 6f 75 72 6e 61 6c 0a 20 20 20 20 61 6e 64   journal.    and
39c0: 20 74 68 65 20 63 68 61 6e 67 65 73 20 77 69 6c   the changes wil
39d0: 6c 20 70 65 72 73 69 73 74 2e 0a 20 20 20 20 3c  l persist..    <
39e0: 2f 6c 69 3e 0a 3c 6c 69 3e 44 72 6f 70 20 74 68  /li>.<li>Drop th
39f0: 65 20 45 58 43 4c 55 53 49 56 45 20 61 6e 64 20  e EXCLUSIVE and 
3a00: 50 45 4e 44 49 4e 47 20 6c 6f 63 6b 73 20 66 72  PENDING locks fr
3a10: 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20  om the database 
3a20: 66 69 6c 65 2e 0a 20 20 20 20 3c 2f 6c 69 3e 0a  file..    </li>.
3a30: 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 41 73 20 73 6f 6f  </ol>..<p>As soo
3a40: 6e 20 61 73 20 50 45 4e 44 49 4e 47 20 6c 6f 63  n as PENDING loc
3a50: 6b 20 69 73 20 72 65 6c 65 61 73 65 64 20 66 72  k is released fr
3a60: 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20  om the database 
3a70: 66 69 6c 65 2c 20 6f 74 68 65 72 0a 70 72 6f 63  file, other.proc
3a80: 65 73 73 65 73 20 63 61 6e 20 62 65 67 69 6e 20  esses can begin 
3a90: 72 65 61 64 69 6e 67 20 74 68 65 20 64 61 74 61  reading the data
3aa0: 62 61 73 65 20 61 67 61 69 6e 2e 20 20 49 6e 20  base again.  In 
3ab0: 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
3ac0: 65 6d 65 6e 74 61 74 69 6f 6e 2c 0a 74 68 65 20  ementation,.the 
3ad0: 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 69 73  RESERVED lock is
3ae0: 20 61 6c 73 6f 20 72 65 6c 65 61 73 65 64 2c 20   also released, 
3af0: 62 75 74 20 74 68 61 74 20 69 73 20 6e 6f 74 20  but that is not 
3b00: 65 73 73 65 6e 74 69 61 6c 2e 20 20 46 75 74 75  essential.  Futu
3b10: 72 65 0a 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re.versions of S
3b20: 51 4c 69 74 65 20 6d 69 67 68 74 20 70 72 6f 76  QLite might prov
3b30: 69 64 65 20 61 20 22 43 48 45 43 4b 50 4f 49 4e  ide a "CHECKPOIN
3b40: 54 22 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74  T" SQL command t
3b50: 68 61 74 20 77 69 6c 6c 0a 63 6f 6d 6d 69 74 20  hat will.commit 
3b60: 61 6c 6c 20 63 68 61 6e 67 65 73 20 6d 61 64 65  all changes made
3b70: 20 73 6f 20 66 61 72 20 77 69 74 68 69 6e 20 61   so far within a
3b80: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 75 74   transaction but
3b90: 20 72 65 74 61 69 6e 20 74 68 65 0a 52 45 53 45   retain the.RESE
3ba0: 52 56 45 44 20 6c 6f 63 6b 20 73 6f 20 74 68 61  RVED lock so tha
3bb0: 74 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 68 61  t additional cha
3bc0: 6e 67 65 73 20 63 61 6e 20 62 65 20 6d 61 64 65  nges can be made
3bd0: 20 77 69 74 68 6f 75 74 20 67 69 76 65 6e 0a 61   without given.a
3be0: 6e 79 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  ny other process
3bf0: 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20   an opportunity 
3c00: 74 6f 20 77 72 69 74 65 2e 3c 2f 70 3e 0a 0a 3c  to write.</p>..<
3c10: 70 3e 49 66 20 61 20 74 72 61 6e 73 61 63 74 69  p>If a transacti
3c20: 6f 6e 20 69 6e 76 6f 6c 76 65 73 20 6d 75 6c 74  on involves mult
3c30: 69 70 6c 65 20 64 61 74 61 62 61 73 65 73 2c 20  iple databases, 
3c40: 74 68 65 6e 20 61 20 6d 6f 72 65 20 63 6f 6d 70  then a more comp
3c50: 6c 65 78 0a 63 6f 6d 6d 69 74 20 73 65 71 75 65  lex.commit seque
3c60: 6e 63 65 20 69 73 20 75 73 65 64 2c 20 61 73 20  nce is used, as 
3c70: 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 6f  follows:</p>..<o
3c80: 6c 3e 0a 3c 6c 69 20 76 61 6c 75 65 3d 22 34 22  l>.<li value="4"
3c90: 3e 0a 20 20 20 4d 61 6b 65 20 73 75 72 65 20 61  >.   Make sure a
3ca0: 6c 6c 20 69 6e 64 69 76 69 64 75 61 6c 20 64 61  ll individual da
3cb0: 74 61 62 61 73 65 20 66 69 6c 65 73 20 68 61 76  tabase files hav
3cc0: 65 20 61 6e 20 45 58 43 4c 55 53 49 56 45 20 6c  e an EXCLUSIVE l
3cd0: 6f 63 6b 20 61 6e 64 20 61 0a 20 20 20 76 61 6c  ock and a.   val
3ce0: 69 64 20 6a 6f 75 72 6e 61 6c 2e 0a 3c 6c 69 3e  id journal..<li>
3cf0: 43 72 65 61 74 65 20 61 20 6d 61 73 74 65 72 2d  Create a master-
3d00: 6a 6f 75 72 6e 61 6c 2e 20 20 54 68 65 20 6e 61  journal.  The na
3d10: 6d 65 20 6f 66 20 74 68 65 20 6d 61 73 74 65 72  me of the master
3d20: 2d 6a 6f 75 72 6e 61 6c 20 69 73 20 61 72 62 69  -journal is arbi
3d30: 74 72 61 72 79 2e 0a 20 20 20 20 28 54 68 65 20  trary..    (The 
3d40: 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
3d50: 74 61 74 69 6f 6e 20 61 70 70 65 6e 64 73 20 72  tation appends r
3d60: 61 6e 64 6f 6d 20 73 75 66 66 69 78 65 73 20 74  andom suffixes t
3d70: 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  o the name of th
3d80: 65 0a 20 20 20 20 6d 61 69 6e 20 64 61 74 61 62  e.    main datab
3d90: 61 73 65 20 66 69 6c 65 20 75 6e 74 69 6c 20 69  ase file until i
3da0: 74 20 66 69 6e 64 73 20 61 20 6e 61 6d 65 20 74  t finds a name t
3db0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 70 72 65  hat does not pre
3dc0: 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2e 29 0a  viously exist.).
3dd0: 20 20 20 20 46 69 6c 6c 20 74 68 65 20 6d 61 73      Fill the mas
3de0: 74 65 72 20 6a 6f 75 72 6e 61 6c 20 77 69 74 68  ter journal with
3df0: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 61 6c   the names of al
3e00: 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c  l the individual
3e10: 20 6a 6f 75 72 6e 61 6c 73 0a 20 20 20 20 61 6e   journals.    an
3e20: 64 20 66 6c 75 73 68 20 69 74 73 20 63 6f 6e 74  d flush its cont
3e30: 65 6e 74 73 20 74 6f 20 64 69 73 6b 2e 0a 3c 6c  ents to disk..<l
3e40: 69 3e 57 72 69 74 65 20 74 68 65 20 6e 61 6d 65  i>Write the name
3e50: 20 6f 66 20 74 68 65 20 6d 61 73 74 65 72 20 6a   of the master j
3e60: 6f 75 72 6e 61 6c 20 69 6e 74 6f 0a 20 20 20 20  ournal into.    
3e70: 61 6c 6c 20 69 6e 64 69 76 69 64 75 61 6c 20 6a  all individual j
3e80: 6f 75 72 6e 61 6c 73 20 28 69 6e 20 73 70 61 63  ournals (in spac
3e90: 65 20 73 65 74 20 61 73 69 64 65 20 66 6f 72 20  e set aside for 
3ea0: 74 68 61 74 20 70 75 72 70 6f 73 65 20 69 6e 20  that purpose in 
3eb0: 74 68 65 0a 20 20 20 20 68 65 61 64 65 72 73 20  the.    headers 
3ec0: 6f 66 20 74 68 65 20 69 6e 64 69 76 69 64 75 61  of the individua
3ed0: 6c 20 6a 6f 75 72 6e 61 6c 73 29 20 61 6e 64 20  l journals) and 
3ee0: 66 6c 75 73 68 20 74 68 65 20 63 6f 6e 74 65 6e  flush the conten
3ef0: 74 73 20 6f 66 20 74 68 65 0a 20 20 20 20 69 6e  ts of the.    in
3f00: 64 69 76 69 64 75 61 6c 20 6a 6f 75 72 6e 61 6c  dividual journal
3f10: 73 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 77 61  s to disk and wa
3f20: 69 74 20 66 6f 72 20 74 68 6f 73 65 20 63 68 61  it for those cha
3f30: 6e 67 65 73 20 74 6f 20 72 65 61 63 68 20 74 68  nges to reach th
3f40: 65 0a 20 20 20 20 64 69 73 6b 20 73 75 72 66 61  e.    disk surfa
3f50: 63 65 2e 0a 3c 6c 69 3e 46 6c 75 73 68 20 61 6c  ce..<li>Flush al
3f60: 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  l database file 
3f70: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 64  changes to the d
3f80: 69 73 6b 2e 20 20 57 61 69 74 20 66 6f 72 20 74  isk.  Wait for t
3f90: 68 6f 73 65 20 63 68 61 6e 67 65 73 0a 20 20 20  hose changes.   
3fa0: 20 74 6f 20 61 63 74 75 61 6c 6c 79 20 62 65 20   to actually be 
3fb0: 77 72 69 74 74 65 6e 20 6f 6e 74 6f 20 74 68 65  written onto the
3fc0: 20 64 69 73 6b 20 73 75 72 66 61 63 65 2e 3c 2f   disk surface.</
3fd0: 6c 69 3e 0a 3c 6c 69 3e 44 65 6c 65 74 65 20 74  li>.<li>Delete t
3fe0: 68 65 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e 61  he master journa
3ff0: 6c 20 66 69 6c 65 2e 20 20 54 68 69 73 20 69 73  l file.  This is
4000: 20 74 68 65 20 69 6e 73 74 61 6e 74 20 77 68 65   the instant whe
4010: 6e 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 72  n the changes ar
4020: 65 0a 20 20 20 20 63 6f 6d 6d 69 74 74 65 64 2e  e.    committed.
4030: 20 20 50 72 69 6f 72 20 74 6f 20 64 65 6c 65 74    Prior to delet
4040: 69 6e 67 20 74 68 65 20 6d 61 73 74 65 72 20 6a  ing the master j
4050: 6f 75 72 6e 61 6c 20 66 69 6c 65 2c 20 69 66 20  ournal file, if 
4060: 61 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65 0a  a power failure.
4070: 20 20 20 20 6f 72 20 63 72 61 73 68 20 6f 63 63      or crash occ
4080: 75 72 73 2c 20 74 68 65 20 69 6e 64 69 76 69 64  urs, the individ
4090: 75 61 6c 20 66 69 6c 65 20 6a 6f 75 72 6e 61 6c  ual file journal
40a0: 73 20 77 69 6c 6c 20 62 65 20 63 6f 6e 73 69 64  s will be consid
40b0: 65 72 65 64 20 68 6f 74 0a 20 20 20 20 61 6e 64  ered hot.    and
40c0: 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
40d0: 62 61 63 6b 20 62 79 20 74 68 65 20 6e 65 78 74  back by the next
40e0: 20 70 72 6f 63 65 73 73 20 74 68 61 74 0a 20 20   process that.  
40f0: 20 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65    attempts to re
4100: 61 64 20 74 68 65 6d 2e 20 20 41 66 74 65 72 20  ad them.  After 
4110: 74 68 65 20 6d 61 73 74 65 72 20 6a 6f 75 72 6e  the master journ
4120: 61 6c 20 68 61 73 20 62 65 65 6e 20 64 65 6c 65  al has been dele
4130: 74 65 64 2c 0a 20 20 20 20 74 68 65 20 66 69 6c  ted,.    the fil
4140: 65 20 6a 6f 75 72 6e 61 6c 73 20 77 69 6c 6c 20  e journals will 
4150: 6e 6f 20 6c 6f 6e 67 65 72 20 62 65 20 63 6f 6e  no longer be con
4160: 73 69 64 65 72 65 64 20 68 6f 74 20 61 6e 64 20  sidered hot and 
4170: 74 68 65 20 63 68 61 6e 67 65 73 0a 20 20 20 20  the changes.    
4180: 77 69 6c 6c 20 70 65 72 73 69 73 74 2e 0a 20 20  will persist..  
4190: 20 20 3c 2f 6c 69 3e 0a 3c 6c 69 3e 44 65 6c 65    </li>.<li>Dele
41a0: 74 65 20 61 6c 6c 20 69 6e 64 69 76 69 64 75 61  te all individua
41b0: 6c 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 73 2e  l journal files.
41c0: 0a 3c 6c 69 3e 44 72 6f 70 20 74 68 65 20 45 58  .<li>Drop the EX
41d0: 43 4c 55 53 49 56 45 20 61 6e 64 20 50 45 4e 44  CLUSIVE and PEND
41e0: 49 4e 47 20 6c 6f 63 6b 73 20 66 72 6f 6d 20 61  ING locks from a
41f0: 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ll database file
4200: 73 2e 0a 20 20 20 20 3c 2f 6c 69 3e 0a 3c 2f 6f  s..    </li>.</o
4210: 6c 3e 0a 7d 0a 0a 48 45 41 44 49 4e 47 20 32 20  l>.}..HEADING 2 
4220: 7b 57 72 69 74 65 72 20 73 74 61 72 76 61 74 69  {Writer starvati
4230: 6f 6e 7d 20 77 72 69 74 65 72 5f 73 74 61 72 76  on} writer_starv
4240: 61 74 69 6f 6e 0a 0a 70 75 74 73 20 7b 0a 3c 70  ation..puts {.<p
4250: 3e 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69  >In SQLite versi
4260: 6f 6e 20 32 2c 20 69 66 20 6d 61 6e 79 20 70 72  on 2, if many pr
4270: 6f 63 65 73 73 65 73 20 61 72 65 20 72 65 61 64  ocesses are read
4280: 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 64 61 74  ing from the dat
4290: 61 62 61 73 65 2c 0a 69 74 20 6d 69 67 68 74 20  abase,.it might 
42a0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
42b0: 20 74 68 65 72 65 20 69 73 20 6e 65 76 65 72 20   there is never 
42c0: 61 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 72  a time when ther
42d0: 65 20 61 72 65 0a 6e 6f 20 61 63 74 69 76 65 20  e are.no active 
42e0: 72 65 61 64 65 72 73 2e 20 20 41 6e 64 20 69 66  readers.  And if
42f0: 20 74 68 65 72 65 20 69 73 20 61 6c 77 61 79 73   there is always
4300: 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20 72 65   at least one re
4310: 61 64 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 0a 64  ad lock on the.d
4320: 61 74 61 62 61 73 65 2c 20 6e 6f 20 70 72 6f 63  atabase, no proc
4330: 65 73 73 20 77 6f 75 6c 64 20 65 76 65 72 20 62  ess would ever b
4340: 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 63  e able to make c
4350: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 64 61  hanges to the da
4360: 74 61 62 61 73 65 0a 62 65 63 61 75 73 65 20 69  tabase.because i
4370: 74 20 77 6f 75 6c 64 20 62 65 20 69 6d 70 6f 73  t would be impos
4380: 73 69 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  sible to acquire
4390: 20 61 20 77 72 69 74 65 20 6c 6f 63 6b 2e 20 20   a write lock.  
43a0: 54 68 69 73 20 73 69 74 75 61 74 69 6f 6e 0a 69  This situation.i
43b0: 73 20 63 61 6c 6c 65 64 20 3c 65 6d 3e 77 72 69  s called <em>wri
43c0: 74 65 72 20 73 74 61 72 76 61 74 69 6f 6e 3c 2f  ter starvation</
43d0: 65 6d 3e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 53 51 4c  em>.</p>..<p>SQL
43e0: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 65  ite version 3 se
43f0: 65 6b 73 20 74 6f 20 61 76 6f 69 64 20 77 72 69  eks to avoid wri
4400: 74 65 72 20 73 74 61 72 76 61 74 69 6f 6e 20 74  ter starvation t
4410: 68 72 6f 75 67 68 20 74 68 65 20 75 73 65 20 6f  hrough the use o
4420: 66 0a 74 68 65 20 50 45 4e 44 49 4e 47 20 6c 6f  f.the PENDING lo
4430: 63 6b 2e 20 20 54 68 65 20 50 45 4e 44 49 4e 47  ck.  The PENDING
4440: 20 6c 6f 63 6b 20 61 6c 6c 6f 77 73 20 65 78 69   lock allows exi
4450: 73 74 69 6e 67 20 72 65 61 64 65 72 73 20 74 6f  sting readers to
4460: 20 63 6f 6e 74 69 6e 75 65 0a 62 75 74 20 70 72   continue.but pr
4470: 65 76 65 6e 74 73 20 6e 65 77 20 72 65 61 64 65  events new reade
4480: 72 73 20 66 72 6f 6d 20 63 6f 6e 6e 65 63 74 69  rs from connecti
4490: 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ng to the databa
44a0: 73 65 2e 20 20 53 6f 20 77 68 65 6e 20 61 0a 70  se.  So when a.p
44b0: 72 6f 63 65 73 73 20 77 61 6e 74 73 20 74 6f 20  rocess wants to 
44c0: 77 72 69 74 65 20 61 20 62 75 73 79 20 64 61 74  write a busy dat
44d0: 61 62 61 73 65 2c 20 69 74 20 63 61 6e 20 73 65  abase, it can se
44e0: 74 20 61 20 50 45 4e 44 49 4e 47 20 6c 6f 63 6b  t a PENDING lock
44f0: 20 77 68 69 63 68 0a 77 69 6c 6c 20 70 72 65 76   which.will prev
4500: 65 6e 74 20 6e 65 77 20 72 65 61 64 65 72 73 20  ent new readers 
4510: 66 72 6f 6d 20 63 6f 6d 69 6e 67 20 69 6e 2e 20  from coming in. 
4520: 20 41 73 73 75 6d 69 6e 67 20 65 78 69 73 74 69   Assuming existi
4530: 6e 67 20 72 65 61 64 65 72 73 20 64 6f 0a 65 76  ng readers do.ev
4540: 65 6e 74 75 61 6c 6c 79 20 63 6f 6d 70 6c 65 74  entually complet
4550: 65 2c 20 61 6c 6c 20 53 48 41 52 45 44 20 6c 6f  e, all SHARED lo
4560: 63 6b 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  cks will eventua
4570: 6c 6c 79 20 63 6c 65 61 72 20 61 6e 64 20 74 68  lly clear and th
4580: 65 0a 77 72 69 74 65 72 20 77 69 6c 6c 20 62 65  e.writer will be
4590: 20 67 69 76 65 6e 20 61 20 63 68 61 6e 63 65 20   given a chance 
45a0: 74 6f 20 6d 61 6b 65 20 69 74 73 20 63 68 61 6e  to make its chan
45b0: 67 65 73 2e 3c 2f 70 3e 0a 7d 0a 0a 48 45 41 44  ges.</p>.}..HEAD
45c0: 49 4e 47 20 31 20 7b 48 6f 77 20 54 6f 20 43 6f  ING 1 {How To Co
45d0: 72 72 75 70 74 20 59 6f 75 72 20 44 61 74 61 62  rrupt Your Datab
45e0: 61 73 65 20 46 69 6c 65 73 7d 20 68 6f 77 5f 74  ase Files} how_t
45f0: 6f 5f 63 6f 72 72 75 70 74 0a 0a 70 75 74 73 20  o_corrupt..puts 
4600: 7b 0a 3c 70 3e 54 68 65 20 70 61 67 65 72 20 6d  {.<p>The pager m
4610: 6f 64 75 6c 65 20 69 73 20 72 6f 62 75 73 74 20  odule is robust 
4620: 62 75 74 20 69 74 20 69 73 20 6e 6f 74 20 63 6f  but it is not co
4630: 6d 70 6c 65 74 65 6c 79 20 66 61 69 6c 73 61 66  mpletely failsaf
4640: 65 2e 0a 49 74 20 63 61 6e 20 62 65 20 73 75 62  e..It can be sub
4650: 76 65 72 74 65 64 2e 20 20 54 68 69 73 20 73 65  verted.  This se
4660: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
4670: 6f 20 69 64 65 6e 74 69 66 79 20 61 6e 64 20 65  o identify and e
4680: 78 70 6c 61 69 6e 0a 74 68 65 20 72 69 73 6b 73  xplain.the risks
4690: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 0a 43 6c 65 61 72  .</p>..<p>.Clear
46a0: 6c 79 2c 20 61 20 68 61 72 64 77 61 72 65 20 6f  ly, a hardware o
46b0: 72 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  r operating syst
46c0: 65 6d 20 66 61 75 6c 74 20 74 68 61 74 20 69 6e  em fault that in
46d0: 74 72 6f 64 75 63 65 73 20 69 6e 63 6f 72 72 65  troduces incorre
46e0: 63 74 20 64 61 74 61 0a 69 6e 74 6f 20 74 68 65  ct data.into the
46f0: 20 6d 69 64 64 6c 65 20 6f 66 20 74 68 65 20 64   middle of the d
4700: 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 72 20  atabase file or 
4710: 6a 6f 75 72 6e 61 6c 20 77 69 6c 6c 20 63 61 75  journal will cau
4720: 73 65 20 70 72 6f 62 6c 65 6d 73 2e 0a 4c 69 6b  se problems..Lik
4730: 65 77 69 73 65 2c 20 0a 69 66 20 61 20 72 6f 67  ewise, .if a rog
4740: 75 65 20 70 72 6f 63 65 73 73 20 6f 70 65 6e 73  ue process opens
4750: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
4760: 20 6f 72 20 6a 6f 75 72 6e 61 6c 20 61 6e 64 20   or journal and 
4770: 77 72 69 74 65 73 20 6d 61 6c 66 6f 72 6d 65 64  writes malformed
4780: 0a 64 61 74 61 20 69 6e 74 6f 20 74 68 65 20 6d  .data into the m
4790: 69 64 64 6c 65 20 6f 66 20 69 74 2c 20 74 68 65  iddle of it, the
47a0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  n the database w
47b0: 69 6c 6c 20 62 65 63 6f 6d 65 20 63 6f 72 72 75  ill become corru
47c0: 70 74 2e 0a 54 68 65 72 65 20 69 73 20 6e 6f 74  pt..There is not
47d0: 20 6d 75 63 68 20 74 68 61 74 20 63 61 6e 20 62   much that can b
47e0: 65 20 64 6f 6e 65 20 61 62 6f 75 74 20 74 68 65  e done about the
47f0: 73 65 20 6b 69 6e 64 73 20 6f 66 20 70 72 6f 62  se kinds of prob
4800: 6c 65 6d 73 0a 73 6f 20 74 68 65 79 20 61 72 65  lems.so they are
4810: 20 67 69 76 65 6e 20 6e 6f 20 66 75 72 74 68 65   given no furthe
4820: 72 20 61 74 74 65 6e 74 69 6f 6e 2e 0a 3c 2f 70  r attention..</p
4830: 3e 0a 0a 3c 70 3e 0a 53 51 4c 69 74 65 20 75 73  >..<p>.SQLite us
4840: 65 73 20 50 4f 53 49 58 20 61 64 76 69 73 6f 72  es POSIX advisor
4850: 79 20 6c 6f 63 6b 73 20 74 6f 20 69 6d 70 6c 65  y locks to imple
4860: 6d 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 6f 6e 20  ment locking on 
4870: 55 6e 69 78 2e 20 20 4f 6e 0a 77 69 6e 64 6f 77  Unix.  On.window
4880: 73 20 69 74 20 75 73 65 73 20 74 68 65 20 4c 6f  s it uses the Lo
4890: 63 6b 46 69 6c 65 28 29 2c 20 4c 6f 63 6b 46 69  ckFile(), LockFi
48a0: 6c 65 45 78 28 29 2c 20 61 6e 64 20 55 6e 6c 6f  leEx(), and Unlo
48b0: 63 6b 46 69 6c 65 28 29 20 73 79 73 74 65 6d 0a  ckFile() system.
48c0: 63 61 6c 6c 73 2e 20 20 53 51 4c 69 74 65 20 61  calls.  SQLite a
48d0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 73  ssumes that thes
48e0: 65 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 61  e system calls a
48f0: 6c 6c 20 77 6f 72 6b 20 61 73 20 61 64 76 65 72  ll work as adver
4900: 74 69 73 65 64 2e 20 20 49 66 0a 74 68 61 74 20  tised.  If.that 
4910: 69 73 20 6e 6f 74 20 74 68 65 20 63 61 73 65 2c  is not the case,
4920: 20 74 68 65 6e 20 64 61 74 61 62 61 73 65 20 63   then database c
4930: 6f 72 72 75 70 74 69 6f 6e 20 63 61 6e 20 72 65  orruption can re
4940: 73 75 6c 74 2e 20 20 4f 6e 65 20 73 68 6f 75 6c  sult.  One shoul
4950: 64 0a 6e 6f 74 65 20 74 68 61 74 20 50 4f 53 49  d.note that POSI
4960: 58 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69  X advisory locki
4970: 6e 67 20 69 73 20 6b 6e 6f 77 6e 20 74 6f 20 62  ng is known to b
4980: 65 20 62 75 67 67 79 20 6f 72 20 65 76 65 6e 20  e buggy or even 
4990: 75 6e 69 6d 70 6c 65 6d 65 6e 74 65 64 0a 6f 6e  unimplemented.on
49a0: 20 6d 61 6e 79 20 4e 46 53 20 69 6d 70 6c 65 6d   many NFS implem
49b0: 65 6e 74 61 74 69 6f 6e 73 20 28 69 6e 63 6c 75  entations (inclu
49c0: 64 69 6e 67 20 72 65 63 65 6e 74 20 76 65 72 73  ding recent vers
49d0: 69 6f 6e 73 20 6f 66 20 4d 61 63 20 4f 53 20 58  ions of Mac OS X
49e0: 29 0a 61 6e 64 20 74 68 61 74 20 74 68 65 72 65  ).and that there
49f0: 20 61 72 65 20 72 65 70 6f 72 74 73 20 6f 66 20   are reports of 
4a00: 6c 6f 63 6b 69 6e 67 20 70 72 6f 62 6c 65 6d 73  locking problems
4a10: 0a 66 6f 72 20 6e 65 74 77 6f 72 6b 20 66 69 6c  .for network fil
4a20: 65 73 79 73 74 65 6d 73 20 75 6e 64 65 72 20 77  esystems under w
4a30: 69 6e 64 6f 77 73 2e 20 20 59 6f 75 72 20 62 65  indows.  Your be
4a40: 73 74 20 64 65 66 65 6e 73 65 20 69 73 20 74 6f  st defense is to
4a50: 20 6e 6f 74 0a 75 73 65 20 53 51 4c 69 74 65 20   not.use SQLite 
4a60: 66 6f 72 20 66 69 6c 65 73 20 6f 6e 20 61 20 6e  for files on a n
4a70: 65 74 77 6f 72 6b 20 66 69 6c 65 73 79 73 74 65  etwork filesyste
4a80: 6d 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 53 51 4c  m..</p>..<p>.SQL
4a90: 69 74 65 20 75 73 65 73 20 74 68 65 20 66 73 79  ite uses the fsy
4aa0: 6e 63 28 29 20 73 79 73 74 65 6d 20 63 61 6c 6c  nc() system call
4ab0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
4ac0: 6f 20 74 68 65 20 64 69 73 6b 20 75 6e 64 65 72  o the disk under
4ad0: 20 55 6e 69 78 20 61 6e 64 0a 69 74 20 75 73 65   Unix and.it use
4ae0: 73 20 74 68 65 20 46 6c 75 73 68 46 69 6c 65 42  s the FlushFileB
4af0: 75 66 66 65 72 73 28 29 20 74 6f 20 64 6f 20 74  uffers() to do t
4b00: 68 65 20 73 61 6d 65 20 75 6e 64 65 72 20 77 69  he same under wi
4b10: 6e 64 6f 77 73 2e 20 20 4f 6e 63 65 20 61 67 61  ndows.  Once aga
4b20: 69 6e 2c 0a 53 51 4c 69 74 65 20 61 73 73 75 6d  in,.SQLite assum
4b30: 65 73 20 74 68 61 74 20 74 68 65 73 65 20 6f 70  es that these op
4b40: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 73  erating system s
4b50: 65 72 76 69 63 65 73 20 66 75 6e 63 74 69 6f 6e  ervices function
4b60: 20 61 73 20 61 64 76 65 72 74 69 73 65 64 2e 0a   as advertised..
4b70: 42 75 74 20 69 74 20 68 61 73 20 62 65 65 6e 20  But it has been 
4b80: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 66 73  reported that fs
4b90: 79 6e 63 28 29 20 61 6e 64 20 46 6c 75 73 68 46  ync() and FlushF
4ba0: 69 6c 65 42 75 66 66 65 72 73 28 29 20 64 6f 20  ileBuffers() do 
4bb0: 6e 6f 74 20 61 6c 77 61 79 73 0a 77 6f 72 6b 20  not always.work 
4bc0: 63 6f 72 72 65 63 74 6c 79 2c 20 65 73 70 65 63  correctly, espec
4bd0: 69 61 6c 6c 79 20 77 69 74 68 20 69 6e 65 78 70  ially with inexp
4be0: 65 6e 73 69 76 65 20 49 44 45 20 64 69 73 6b 73  ensive IDE disks
4bf0: 2e 20 20 41 70 70 61 72 65 6e 74 6c 79 20 73 6f  .  Apparently so
4c00: 6d 65 0a 6d 61 6e 75 66 61 63 74 75 72 65 73 20  me.manufactures 
4c10: 6f 66 20 49 44 45 20 64 69 73 6b 73 20 68 61 76  of IDE disks hav
4c20: 65 20 64 65 66 65 63 74 69 76 65 20 63 6f 6e 74  e defective cont
4c30: 72 6f 6c 6c 65 72 20 63 68 69 70 73 20 74 68 61  roller chips tha
4c40: 74 20 72 65 70 6f 72 74 0a 74 68 61 74 20 64 61  t report.that da
4c50: 74 61 20 68 61 73 20 72 65 61 63 68 65 64 20 74  ta has reached t
4c60: 68 65 20 64 69 73 6b 20 73 75 72 66 61 63 65 20  he disk surface 
4c70: 77 68 65 6e 20 69 6e 20 66 61 63 74 20 74 68 65  when in fact the
4c80: 20 64 61 74 61 20 69 73 20 73 74 69 6c 6c 0a 69   data is still.i
4c90: 6e 20 76 6f 6c 61 74 69 6c 65 20 63 61 63 68 65  n volatile cache
4ca0: 20 6d 65 6d 6f 72 79 20 69 6e 20 74 68 65 20 64   memory in the d
4cb0: 69 73 6b 20 64 72 69 76 65 20 65 6c 65 63 74 72  isk drive electr
4cc0: 6f 6e 69 63 73 2e 20 20 54 68 65 72 65 20 61 72  onics.  There ar
4cd0: 65 20 61 6c 73 6f 0a 72 65 70 6f 72 74 73 20 74  e also.reports t
4ce0: 68 61 74 20 77 69 6e 64 6f 77 73 20 73 6f 6d 65  hat windows some
4cf0: 74 69 6d 65 73 20 63 68 6f 6f 73 65 73 20 74 6f  times chooses to
4d00: 20 69 67 6e 6f 72 65 20 46 6c 75 73 68 46 69 6c   ignore FlushFil
4d10: 65 42 75 66 66 65 72 73 28 29 20 66 6f 72 0a 75  eBuffers() for.u
4d20: 6e 73 70 65 63 69 66 69 65 64 20 72 65 61 73 6f  nspecified reaso
4d30: 6e 73 2e 20 20 54 68 65 20 61 75 74 68 6f 72 20  ns.  The author 
4d40: 63 61 6e 6e 6f 74 20 76 65 72 69 66 79 20 61 6e  cannot verify an
4d50: 79 20 6f 66 20 74 68 65 73 65 20 72 65 70 6f 72  y of these repor
4d60: 74 73 2e 0a 42 75 74 20 69 66 20 74 68 65 79 20  ts..But if they 
4d70: 61 72 65 20 74 72 75 65 2c 20 69 74 20 6d 65 61  are true, it mea
4d80: 6e 73 20 74 68 61 74 20 64 61 74 61 62 61 73 65  ns that database
4d90: 20 63 6f 72 72 75 70 74 69 6f 6e 20 69 73 20 61   corruption is a
4da0: 20 70 6f 73 73 69 62 69 6c 69 74 79 0a 66 6f 6c   possibility.fol
4db0: 6c 6f 77 69 6e 67 20 61 6e 20 75 6e 65 78 70 65  lowing an unexpe
4dc0: 63 74 65 64 20 70 6f 77 65 72 20 6c 6f 73 73 2e  cted power loss.
4dd0: 20 20 54 68 65 73 65 20 61 72 65 20 68 61 72 64    These are hard
4de0: 77 61 72 65 20 61 6e 64 2f 6f 72 20 6f 70 65 72  ware and/or oper
4df0: 61 74 69 6e 67 0a 73 79 73 74 65 6d 20 62 75 67  ating.system bug
4e00: 73 20 74 68 61 74 20 53 51 4c 69 74 65 20 69 73  s that SQLite is
4e10: 20 75 6e 61 62 6c 65 20 74 6f 20 64 65 66 65 6e   unable to defen
4e20: 64 20 61 67 61 69 6e 73 74 2e 0a 3c 2f 70 3e 0a  d against..</p>.
4e30: 0a 3c 70 3e 0a 49 66 20 61 20 63 72 61 73 68 20  .<p>.If a crash 
4e40: 6f 72 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65  or power failure
4e50: 20 6f 63 63 75 72 73 20 61 6e 64 20 72 65 73 75   occurs and resu
4e60: 6c 74 73 20 69 6e 20 61 20 68 6f 74 20 6a 6f 75  lts in a hot jou
4e70: 72 6e 61 6c 20 62 75 74 20 74 68 61 74 0a 6a 6f  rnal but that.jo
4e80: 75 72 6e 61 6c 20 69 73 20 64 65 6c 65 74 65 64  urnal is deleted
4e90: 2c 20 74 68 65 20 6e 65 78 74 20 70 72 6f 63 65  , the next proce
4ea0: 73 73 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  ss to open the d
4eb0: 61 74 61 62 61 73 65 20 77 69 6c 6c 20 6e 6f 74  atabase will not
4ec0: 0a 6b 6e 6f 77 20 74 68 61 74 20 69 74 20 63 6f  .know that it co
4ed0: 6e 74 61 69 6e 73 20 63 68 61 6e 67 65 73 20 74  ntains changes t
4ee0: 68 61 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  hat need to be r
4ef0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20 54 68 65  olled back.  The
4f00: 20 72 6f 6c 6c 62 61 63 6b 0a 77 69 6c 6c 20 6e   rollback.will n
4f10: 6f 74 20 6f 63 63 75 72 20 61 6e 64 20 74 68 65  ot occur and the
4f20: 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
4f30: 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
4f40: 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 2e  onsistent state.
4f50: 0a 52 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61  .Rollback journa
4f60: 6c 73 20 6d 69 67 68 74 20 62 65 20 64 65 6c 65  ls might be dele
4f70: 74 65 64 20 66 6f 72 20 61 6e 79 20 6e 75 6d 62  ted for any numb
4f80: 65 72 20 6f 66 20 72 65 61 73 6f 6e 73 3a 0a 3c  er of reasons:.<
4f90: 2f 70 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 41 6e  /p>..<ul>.<li>An
4fa0: 20 61 64 6d 69 6e 69 73 74 72 61 74 6f 72 20 6d   administrator m
4fb0: 69 67 68 74 20 62 65 20 63 6c 65 61 6e 69 6e 67  ight be cleaning
4fc0: 20 75 70 20 61 66 74 65 72 20 61 6e 20 4f 53 20   up after an OS 
4fd0: 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 66  crash or power f
4fe0: 61 69 6c 75 72 65 2c 0a 20 20 20 20 73 65 65 20  ailure,.    see 
4ff0: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  the journal file
5000: 2c 20 74 68 69 6e 6b 20 69 74 20 69 73 20 6a 75  , think it is ju
5010: 6e 6b 2c 20 61 6e 64 20 64 65 6c 65 74 65 20 69  nk, and delete i
5020: 74 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 53 6f 6d 65  t.</li>.<li>Some
5030: 6f 6e 65 20 28 6f 72 20 73 6f 6d 65 20 70 72 6f  one (or some pro
5040: 63 65 73 73 29 20 6d 69 67 68 74 20 72 65 6e 61  cess) might rena
5050: 6d 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  me the database 
5060: 66 69 6c 65 20 62 75 74 20 66 61 69 6c 20 74 6f  file but fail to
5070: 0a 20 20 20 20 61 6c 73 6f 20 72 65 6e 61 6d 65  .    also rename
5080: 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 64 20   its associated 
5090: 6a 6f 75 72 6e 61 6c 2e 3c 2f 6c 69 3e 0a 3c 6c  journal.</li>.<l
50a0: 69 3e 49 66 20 74 68 65 20 64 61 74 61 62 61 73  i>If the databas
50b0: 65 20 66 69 6c 65 20 68 61 73 20 61 6c 69 61 73  e file has alias
50c0: 65 73 20 28 68 61 72 64 20 6f 72 20 73 6f 66 74  es (hard or soft
50d0: 20 6c 69 6e 6b 73 29 20 61 6e 64 20 74 68 65 20   links) and the 
50e0: 66 69 6c 65 0a 20 20 20 20 69 73 20 6f 70 65 6e  file.    is open
50f0: 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e  ed by a differen
5100: 74 20 61 6c 69 61 73 20 74 68 61 6e 20 74 68 65  t alias than the
5110: 20 6f 6e 65 20 75 73 65 64 20 74 6f 20 63 72 65   one used to cre
5120: 61 74 65 20 74 68 65 20 6a 6f 75 72 6e 61 6c 2c  ate the journal,
5130: 0a 20 20 20 20 74 68 65 6e 20 74 68 65 20 6a 6f  .    then the jo
5140: 75 72 6e 61 6c 20 77 69 6c 6c 20 6e 6f 74 20 62  urnal will not b
5150: 65 20 66 6f 75 6e 64 2e 20 20 54 6f 20 61 76 6f  e found.  To avo
5160: 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 2c  id this problem,
5170: 20 79 6f 75 20 73 68 6f 75 6c 64 0a 20 20 20 20   you should.    
5180: 6e 6f 74 20 63 72 65 61 74 65 20 6c 69 6e 6b 73  not create links
5190: 20 74 6f 20 53 51 4c 69 74 65 20 64 61 74 61 62   to SQLite datab
51a0: 61 73 65 20 66 69 6c 65 73 2e 3c 2f 6c 69 3e 0a  ase files.</li>.
51b0: 3c 6c 69 3e 46 69 6c 65 73 79 73 74 65 6d 20 63  <li>Filesystem c
51c0: 6f 72 72 75 70 74 69 6f 6e 20 66 6f 6c 6c 6f 77  orruption follow
51d0: 69 6e 67 20 61 20 70 6f 77 65 72 20 66 61 69 6c  ing a power fail
51e0: 75 72 65 20 6d 69 67 68 74 20 63 61 75 73 65 20  ure might cause 
51f0: 74 68 65 0a 20 20 20 20 6a 6f 75 72 6e 61 6c 20  the.    journal 
5200: 74 6f 20 62 65 20 72 65 6e 61 6d 65 64 20 6f 72  to be renamed or
5210: 20 64 65 6c 65 74 65 64 2e 3c 2f 6c 69 3e 0a 3c   deleted.</li>.<
5220: 2f 75 6c 3e 0a 0a 3c 70 3e 0a 54 68 65 20 6c 61  /ul>..<p>.The la
5230: 73 74 20 28 66 6f 75 72 74 68 29 20 62 75 6c 6c  st (fourth) bull
5240: 65 74 20 61 62 6f 76 65 20 6d 65 72 69 74 73 20  et above merits 
5250: 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6d 6d 65  additional comme
5260: 6e 74 2e 20 20 57 68 65 6e 20 53 51 4c 69 74 65  nt.  When SQLite
5270: 20 63 72 65 61 74 65 73 0a 61 20 6a 6f 75 72 6e   creates.a journ
5280: 61 6c 20 66 69 6c 65 20 6f 6e 20 55 6e 69 78 2c  al file on Unix,
5290: 20 69 74 20 6f 70 65 6e 73 20 74 68 65 20 64 69   it opens the di
52a0: 72 65 63 74 6f 72 79 20 74 68 61 74 20 63 6f 6e  rectory that con
52b0: 74 61 69 6e 73 20 74 68 61 74 20 66 69 6c 65 20  tains that file 
52c0: 61 6e 64 0a 63 61 6c 6c 73 20 66 73 79 6e 63 28  and.calls fsync(
52d0: 29 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  ) on the directo
52e0: 72 79 2c 20 69 6e 20 61 6e 20 65 66 66 6f 72 74  ry, in an effort
52f0: 20 74 6f 20 70 75 73 68 20 74 68 65 20 64 69 72   to push the dir
5300: 65 63 74 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  ectory informati
5310: 6f 6e 0a 74 6f 20 64 69 73 6b 2e 20 20 42 75 74  on.to disk.  But
5320: 20 73 75 70 70 6f 73 65 20 73 6f 6d 65 20 6f 74   suppose some ot
5330: 68 65 72 20 70 72 6f 63 65 73 73 20 69 73 20 61  her process is a
5340: 64 64 69 6e 67 20 6f 72 20 72 65 6d 6f 76 69 6e  dding or removin
5350: 67 20 75 6e 72 65 6c 61 74 65 64 0a 66 69 6c 65  g unrelated.file
5360: 73 20 74 6f 20 74 68 65 20 64 69 72 65 63 74 6f  s to the directo
5370: 72 79 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  ry that contains
5380: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
5390: 64 20 6a 6f 75 72 6e 61 6c 20 61 74 20 74 68 65  d journal at the
53a0: 20 74 68 65 0a 6d 6f 6d 65 6e 74 20 6f 66 20 61   the.moment of a
53b0: 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65 2e 20   power failure. 
53c0: 20 54 68 65 20 73 75 70 70 6f 73 65 64 6c 79 20   The supposedly 
53d0: 75 6e 72 65 6c 61 74 65 64 20 61 63 74 69 6f 6e  unrelated action
53e0: 73 20 6f 66 20 74 68 69 73 20 6f 74 68 65 72 0a  s of this other.
53f0: 70 72 6f 63 65 73 73 20 6d 69 67 68 74 20 72 65  process might re
5400: 73 75 6c 74 20 69 6e 20 74 68 65 20 6a 6f 75 72  sult in the jour
5410: 6e 61 6c 20 66 69 6c 65 20 62 65 69 6e 67 20 64  nal file being d
5420: 72 6f 70 70 65 64 20 66 72 6f 6d 20 74 68 65 20  ropped from the 
5430: 64 69 72 65 63 74 6f 72 79 20 61 6e 64 0a 6d 6f  directory and.mo
5440: 76 65 64 20 69 6e 74 6f 20 22 6c 6f 73 74 2b 66  ved into "lost+f
5450: 6f 75 6e 64 22 2e 20 20 54 68 69 73 20 69 73 20  ound".  This is 
5460: 61 6e 20 75 6e 6c 69 6b 65 6c 79 20 73 63 65 6e  an unlikely scen
5470: 61 72 69 6f 2c 20 62 75 74 20 69 74 20 63 6f 75  ario, but it cou
5480: 6c 64 20 68 61 70 70 65 6e 2e 0a 54 68 65 20 62  ld happen..The b
5490: 65 73 74 20 64 65 66 65 6e 73 65 73 20 61 72 65  est defenses are
54a0: 20 74 6f 20 75 73 65 20 61 20 6a 6f 75 72 6e 61   to use a journa
54b0: 6c 69 6e 67 20 66 69 6c 65 73 79 73 74 65 6d 20  ling filesystem 
54c0: 6f 72 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 64  or to keep the.d
54d0: 61 74 61 62 61 73 65 20 61 6e 64 20 6a 6f 75 72  atabase and jour
54e0: 6e 61 6c 20 69 6e 20 61 20 64 69 72 65 63 74 6f  nal in a directo
54f0: 72 79 20 62 79 20 74 68 65 6d 73 65 6c 76 65 73  ry by themselves
5500: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 46 6f 72 20  ..</p>..<p>.For 
5510: 61 20 63 6f 6d 6d 69 74 20 69 6e 76 6f 6c 76 69  a commit involvi
5520: 6e 67 20 6d 75 6c 74 69 70 6c 65 20 64 61 74 61  ng multiple data
5530: 62 61 73 65 73 20 61 6e 64 20 61 20 6d 61 73 74  bases and a mast
5540: 65 72 20 6a 6f 75 72 6e 61 6c 2c 20 69 66 20 74  er journal, if t
5550: 68 65 0a 76 61 72 69 6f 75 73 20 64 61 74 61 62  he.various datab
5560: 61 73 65 73 20 77 65 72 65 20 6f 6e 20 64 69 66  ases were on dif
5570: 66 65 72 65 6e 74 20 64 69 73 6b 20 76 6f 6c 75  ferent disk volu
5580: 6d 65 73 20 61 6e 64 20 61 20 70 6f 77 65 72 20  mes and a power 
5590: 66 61 69 6c 75 72 65 20 6f 63 63 75 72 73 0a 64  failure occurs.d
55a0: 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 6d 69 74  uring the commit
55b0: 2c 20 74 68 65 6e 20 77 68 65 6e 20 74 68 65 20  , then when the 
55c0: 6d 61 63 68 69 6e 65 20 63 6f 6d 65 73 20 62 61  machine comes ba
55d0: 63 6b 20 75 70 20 74 68 65 20 64 69 73 6b 73 20  ck up the disks 
55e0: 6d 69 67 68 74 0a 62 65 20 72 65 6d 6f 75 6e 74  might.be remount
55f0: 65 64 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ed with differen
5600: 74 20 6e 61 6d 65 73 2e 20 20 4f 72 20 73 6f 6d  t names.  Or som
5610: 65 20 64 69 73 6b 73 20 6d 69 67 68 74 20 6e 6f  e disks might no
5620: 74 20 62 65 20 6d 6f 75 6e 74 65 64 0a 61 74 20  t be mounted.at 
5630: 61 6c 6c 2e 20 20 20 57 68 65 6e 20 74 68 69 73  all.   When this
5640: 20 68 61 70 70 65 6e 73 20 74 68 65 20 69 6e 64   happens the ind
5650: 69 76 69 64 75 61 6c 20 66 69 6c 65 20 6a 6f 75  ividual file jou
5660: 72 6e 61 6c 73 20 61 6e 64 20 74 68 65 20 6d 61  rnals and the ma
5670: 73 74 65 72 0a 6a 6f 75 72 6e 61 6c 20 6d 69 67  ster.journal mig
5680: 68 74 20 6e 6f 74 20 62 65 20 61 62 6c 65 20 74  ht not be able t
5690: 6f 20 66 69 6e 64 20 65 61 63 68 20 6f 74 68 65  o find each othe
56a0: 72 2e 20 54 68 65 20 77 6f 72 73 74 20 6f 75 74  r. The worst out
56b0: 63 6f 6d 65 20 66 72 6f 6d 0a 74 68 69 73 20 73  come from.this s
56c0: 63 65 6e 61 72 69 6f 20 69 73 20 74 68 61 74 20  cenario is that 
56d0: 74 68 65 20 63 6f 6d 6d 69 74 20 63 65 61 73 65  the commit cease
56e0: 73 20 74 6f 20 62 65 20 61 74 6f 6d 69 63 2e 20  s to be atomic. 
56f0: 20 0a 53 6f 6d 65 20 64 61 74 61 62 61 73 65 73   .Some databases
5700: 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
5710: 20 62 61 63 6b 20 61 6e 64 20 6f 74 68 65 72 73   back and others
5720: 20 6d 69 67 68 74 20 6e 6f 74 2e 20 0a 41 6c 6c   might not. .All
5730: 20 64 61 74 61 62 61 73 65 73 20 77 69 6c 6c 20   databases will 
5740: 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
5750: 65 6c 66 2d 63 6f 6e 73 69 73 74 65 6e 74 2e 0a  elf-consistent..
5760: 54 6f 20 64 65 66 65 6e 64 20 61 67 61 69 6e 73  To defend agains
5770: 74 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 2c 20  t this problem, 
5780: 6b 65 65 70 20 61 6c 6c 20 64 61 74 61 62 61 73  keep all databas
5790: 65 73 0a 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es.on the same d
57a0: 69 73 6b 20 76 6f 6c 75 6d 65 20 61 6e 64 2f 6f  isk volume and/o
57b0: 72 20 72 65 6d 6f 75 6e 74 20 64 69 73 6b 73 20  r remount disks 
57c0: 75 73 69 6e 67 20 65 78 61 63 74 6c 79 20 74 68  using exactly th
57d0: 65 20 73 61 6d 65 20 6e 61 6d 65 73 0a 61 66 74  e same names.aft
57e0: 65 72 20 61 20 70 6f 77 65 72 20 66 61 69 6c 75  er a power failu
57f0: 72 65 2e 0a 3c 2f 70 3e 0a 7d 0a 0a 48 45 41 44  re..</p>.}..HEAD
5800: 49 4e 47 20 31 20 7b 54 72 61 6e 73 61 63 74 69  ING 1 {Transacti
5810: 6f 6e 20 43 6f 6e 74 72 6f 6c 20 41 74 20 54 68  on Control At Th
5820: 65 20 53 51 4c 20 4c 65 76 65 6c 7d 20 74 72 61  e SQL Level} tra
5830: 6e 73 61 63 74 69 6f 6e 5f 63 6f 6e 74 72 6f 6c  nsaction_control
5840: 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 0a 54 68 65  ..puts {.<p>.The
5850: 20 63 68 61 6e 67 65 73 20 74 6f 20 6c 6f 63 6b   changes to lock
5860: 69 6e 67 20 61 6e 64 20 63 6f 6e 63 75 72 72 65  ing and concurre
5870: 6e 63 79 20 63 6f 6e 74 72 6f 6c 20 69 6e 20 53  ncy control in S
5880: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
5890: 61 6c 73 6f 0a 69 6e 74 72 6f 64 75 63 65 20 73  also.introduce s
58a0: 6f 6d 65 20 73 75 62 74 6c 65 20 63 68 61 6e 67  ome subtle chang
58b0: 65 73 20 69 6e 20 74 68 65 20 77 61 79 20 74 72  es in the way tr
58c0: 61 6e 73 61 63 74 69 6f 6e 73 20 77 6f 72 6b 20  ansactions work 
58d0: 61 74 20 74 68 65 20 53 51 4c 0a 6c 61 6e 67 75  at the SQL.langu
58e0: 61 67 65 20 6c 65 76 65 6c 2e 0a 42 79 20 64 65  age level..By de
58f0: 66 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 76 65  fault, SQLite ve
5900: 72 73 69 6f 6e 20 33 20 6f 70 65 72 61 74 65 73  rsion 3 operates
5910: 20 69 6e 20 3c 65 6d 3e 61 75 74 6f 63 6f 6d 6d   in <em>autocomm
5920: 69 74 3c 2f 65 6d 3e 20 6d 6f 64 65 2e 0a 49 6e  it</em> mode..In
5930: 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   autocommit mode
5940: 2c 0a 61 6c 6c 20 63 68 61 6e 67 65 73 20 74 6f  ,.all changes to
5950: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 72   the database ar
5960: 65 20 63 6f 6d 6d 69 74 74 65 64 20 61 73 20 73  e committed as s
5970: 6f 6f 6e 20 61 73 20 61 6c 6c 20 6f 70 65 72 61  oon as all opera
5980: 74 69 6f 6e 73 20 61 73 73 6f 63 69 61 74 65 64  tions associated
5990: 0a 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e  .with the curren
59a0: 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
59b0: 63 74 69 6f 6e 20 63 6f 6d 70 6c 65 74 65 2e 3c  ction complete.<
59c0: 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 53 51 4c 20  /p>..<p>The SQL 
59d0: 63 6f 6d 6d 61 6e 64 20 22 42 45 47 49 4e 20 54  command "BEGIN T
59e0: 52 41 4e 53 41 43 54 49 4f 4e 22 20 28 74 68 65  RANSACTION" (the
59f0: 20 54 52 41 4e 53 41 43 54 49 4f 4e 20 6b 65 79   TRANSACTION key
5a00: 77 6f 72 64 0a 69 73 20 6f 70 74 69 6f 6e 61 6c  word.is optional
5a10: 29 20 69 73 20 75 73 65 64 20 74 6f 20 74 61 6b  ) is used to tak
5a20: 65 20 53 51 4c 69 74 65 20 6f 75 74 20 6f 66 20  e SQLite out of 
5a30: 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2e  autocommit mode.
5a40: 0a 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 42  .Note that the B
5a50: 45 47 49 4e 20 63 6f 6d 6d 61 6e 64 20 64 6f 65  EGIN command doe
5a60: 73 20 6e 6f 74 20 61 63 71 75 69 72 65 20 61 6e  s not acquire an
5a70: 79 20 6c 6f 63 6b 73 20 6f 6e 20 74 68 65 20 64  y locks on the d
5a80: 61 74 61 62 61 73 65 2e 0a 41 66 74 65 72 20 61  atabase..After a
5a90: 20 42 45 47 49 4e 20 63 6f 6d 6d 61 6e 64 2c 20   BEGIN command, 
5aa0: 61 20 53 48 41 52 45 44 20 6c 6f 63 6b 20 77 69  a SHARED lock wi
5ab0: 6c 6c 20 62 65 20 61 63 71 75 69 72 65 64 20 77  ll be acquired w
5ac0: 68 65 6e 20 74 68 65 20 66 69 72 73 74 0a 53 45  hen the first.SE
5ad0: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 69  LECT statement i
5ae0: 73 20 65 78 65 63 75 74 65 64 2e 20 20 41 20 52  s executed.  A R
5af0: 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 77 69 6c  ESERVED lock wil
5b00: 6c 20 62 65 20 61 63 71 75 69 72 65 64 20 77 68  l be acquired wh
5b10: 65 6e 0a 74 68 65 20 66 69 72 73 74 20 49 4e 53  en.the first INS
5b20: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
5b30: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
5b40: 20 69 73 20 65 78 65 63 75 74 65 64 2e 20 20 4e   is executed.  N
5b50: 6f 20 45 58 43 4c 55 53 49 56 45 0a 6c 6f 63 6b  o EXCLUSIVE.lock
5b60: 20 69 73 20 61 63 71 75 69 72 65 64 20 75 6e 74   is acquired unt
5b70: 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 6d 65  il either the me
5b80: 6d 6f 72 79 20 63 61 63 68 65 20 66 69 6c 6c 73  mory cache fills
5b90: 20 75 70 20 61 6e 64 20 6d 75 73 74 0a 62 65 20   up and must.be 
5ba0: 73 70 69 6c 6c 65 64 20 74 6f 20 64 69 73 6b 20  spilled to disk 
5bb0: 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 74 72 61  or until the tra
5bc0: 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73  nsaction commits
5bd0: 2e 20 20 49 6e 20 74 68 69 73 20 77 61 79 2c 0a  .  In this way,.
5be0: 74 68 65 20 73 79 73 74 65 6d 20 64 65 6c 61 79  the system delay
5bf0: 73 20 62 6c 6f 63 6b 69 6e 67 20 72 65 61 64 20  s blocking read 
5c00: 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 66 69  access to the fi
5c10: 6c 65 20 66 69 6c 65 20 75 6e 74 69 6c 20 74 68  le file until th
5c20: 65 0a 6c 61 73 74 20 70 6f 73 73 69 62 6c 65 20  e.last possible 
5c30: 6d 6f 6d 65 6e 74 2e 0a 3c 2f 70 3e 0a 0a 3c 70  moment..</p>..<p
5c40: 3e 54 68 65 20 53 51 4c 20 63 6f 6d 6d 61 6e 64  >The SQL command
5c50: 20 22 43 4f 4d 4d 49 54 22 20 20 64 6f 65 73 20   "COMMIT"  does 
5c60: 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 63 6f 6d  not actually com
5c70: 6d 69 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  mit the changes 
5c80: 74 6f 0a 64 69 73 6b 2e 20 20 49 74 20 6a 75 73  to.disk.  It jus
5c90: 74 20 74 75 72 6e 73 20 61 75 74 6f 63 6f 6d 6d  t turns autocomm
5ca0: 69 74 20 62 61 63 6b 20 6f 6e 2e 20 20 54 68 65  it back on.  The
5cb0: 6e 2c 20 61 74 20 74 68 65 20 63 6f 6e 63 6c 75  n, at the conclu
5cc0: 73 69 6f 6e 20 6f 66 0a 74 68 65 20 63 6f 6d 6d  sion of.the comm
5cd0: 61 6e 64 2c 20 74 68 65 20 72 65 67 75 6c 61 72  and, the regular
5ce0: 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6c 6f 67 69   autocommit logi
5cf0: 63 20 74 61 6b 65 73 20 6f 76 65 72 20 61 6e 64  c takes over and
5d00: 20 63 61 75 73 65 73 20 74 68 65 0a 61 63 74 75   causes the.actu
5d10: 61 6c 20 63 6f 6d 6d 69 74 20 74 6f 20 64 69 73  al commit to dis
5d20: 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 54 68 65 20  k to occur..The 
5d30: 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 22 52 4f 4c  SQL command "ROL
5d40: 4c 42 41 43 4b 22 20 61 6c 73 6f 20 6f 70 65 72  LBACK" also oper
5d50: 61 74 65 73 20 62 79 20 74 75 72 6e 69 6e 67 20  ates by turning 
5d60: 61 75 74 6f 63 6f 6d 6d 69 74 20 62 61 63 6b 20  autocommit back 
5d70: 6f 6e 2c 0a 62 75 74 20 69 74 20 61 6c 73 6f 20  on,.but it also 
5d80: 73 65 74 73 20 61 20 66 6c 61 67 20 74 68 61 74  sets a flag that
5d90: 20 74 65 6c 6c 73 20 74 68 65 20 61 75 74 6f 63   tells the autoc
5da0: 6f 6d 6d 69 74 20 6c 6f 67 69 63 20 74 6f 20 72  ommit logic to r
5db0: 6f 6c 6c 62 61 63 6b 20 72 61 74 68 65 72 0a 74  ollback rather.t
5dc0: 68 61 6e 20 63 6f 6d 6d 69 74 2e 3c 2f 70 3e 0a  han commit.</p>.
5dd0: 0a 3c 70 3e 49 66 20 74 68 65 20 53 51 4c 20 43  .<p>If the SQL C
5de0: 4f 4d 4d 49 54 20 63 6f 6d 6d 61 6e 64 20 74 75  OMMIT command tu
5df0: 72 6e 73 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6f  rns autocommit o
5e00: 6e 20 61 6e 64 20 74 68 65 20 61 75 74 6f 63 6f  n and the autoco
5e10: 6d 6d 69 74 20 6c 6f 67 69 63 0a 74 68 65 6e 20  mmit logic.then 
5e20: 74 72 69 65 73 20 74 6f 20 63 6f 6d 6d 69 74 20  tries to commit 
5e30: 63 68 61 6e 67 65 20 62 75 74 20 66 61 69 6c 73  change but fails
5e40: 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 6f 74   because some ot
5e50: 68 65 72 20 70 72 6f 63 65 73 73 20 69 73 20 68  her process is h
5e60: 6f 6c 64 69 6e 67 0a 61 20 53 48 41 52 45 44 20  olding.a SHARED 
5e70: 6c 6f 63 6b 2c 20 74 68 65 6e 20 61 75 74 6f 63  lock, then autoc
5e80: 6f 6d 6d 69 74 20 69 73 20 74 75 72 6e 65 64 20  ommit is turned 
5e90: 62 61 63 6b 20 6f 66 66 20 61 75 74 6f 6d 61 74  back off automat
5ea0: 69 63 61 6c 6c 79 2e 20 20 54 68 69 73 0a 61 6c  ically.  This.al
5eb0: 6c 6f 77 73 20 74 68 65 20 75 73 65 72 20 74 6f  lows the user to
5ec0: 20 72 65 74 72 79 20 74 68 65 20 43 4f 4d 4d 49   retry the COMMI
5ed0: 54 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  T at a later tim
5ee0: 65 20 61 66 74 65 72 20 74 68 65 20 53 48 41 52  e after the SHAR
5ef0: 45 44 20 6c 6f 63 6b 0a 68 61 73 20 68 61 64 20  ED lock.has had 
5f00: 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74  an opportunity t
5f10: 6f 20 63 6c 65 61 72 2e 3c 2f 70 3e 0a 0a 3c 70  o clear.</p>..<p
5f20: 3e 49 66 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d  >If multiple com
5f30: 6d 61 6e 64 73 20 61 72 65 20 62 65 69 6e 67 20  mands are being 
5f40: 65 78 65 63 75 74 65 64 20 61 67 61 69 6e 73 74  executed against
5f50: 20 74 68 65 20 73 61 6d 65 20 53 51 4c 69 74 65   the same SQLite
5f60: 20 64 61 74 61 62 61 73 65 0a 63 6f 6e 6e 65 63   database.connec
5f70: 74 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65  tion at the same
5f80: 20 74 69 6d 65 2c 20 74 68 65 20 61 75 74 6f 63   time, the autoc
5f90: 6f 6d 6d 69 74 20 69 73 20 64 65 66 65 72 72 65  ommit is deferre
5fa0: 64 20 75 6e 74 69 6c 20 74 68 65 20 76 65 72 79  d until the very
5fb0: 0a 6c 61 73 74 20 63 6f 6d 6d 61 6e 64 20 63 6f  .last command co
5fc0: 6d 70 6c 65 74 65 73 2e 20 20 46 6f 72 20 65 78  mpletes.  For ex
5fd0: 61 6d 70 6c 65 2c 20 69 66 20 61 20 53 45 4c 45  ample, if a SELE
5fe0: 43 54 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  CT statement is 
5ff0: 62 65 69 6e 67 0a 65 78 65 63 75 74 65 64 2c 20  being.executed, 
6000: 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
6010: 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 77 69 6c   the command wil
6020: 6c 20 70 61 75 73 65 20 61 73 20 65 61 63 68 20  l pause as each 
6030: 72 6f 77 20 6f 66 20 74 68 65 0a 72 65 73 75 6c  row of the.resul
6040: 74 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  t is returned.  
6050: 44 75 72 69 6e 67 20 74 68 69 73 20 70 61 75 73  During this paus
6060: 65 20 6f 74 68 65 72 20 49 4e 53 45 52 54 2c 20  e other INSERT, 
6070: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
6080: 45 0a 63 6f 6d 6d 61 6e 64 73 20 63 61 6e 20 62  E.commands can b
6090: 65 20 65 78 65 63 75 74 65 64 20 61 67 61 69 6e  e executed again
60a0: 73 74 20 6f 74 68 65 72 20 74 61 62 6c 65 73 20  st other tables 
60b0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  in the database.
60c0: 20 20 42 75 74 20 6e 6f 6e 65 0a 6f 66 20 74 68    But none.of th
60d0: 65 73 65 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  ese changes will
60e0: 20 63 6f 6d 6d 69 74 20 75 6e 74 69 6c 20 74 68   commit until th
60f0: 65 20 6f 72 69 67 69 6e 61 6c 20 53 45 4c 45 43  e original SELEC
6100: 54 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  T statement fini
6110: 73 68 65 73 2e 0a 3c 2f 70 3e 0a 7d 0a 0a 0a 66  shes..</p>.}...f
6120: 6f 6f 74 65 72 20 24 72 63 73 69 64 0a           ooter $rcsid.