Documentation Source Text

Hex Artifact Content
Login

Artifact 9b1dbf50c3fb0831fae573aad455246dae497c76b4c8fac04f85e8f5c02677fe:


0000: 3c 74 69 74 6c 65 3e 57 72 69 74 65 2d 41 68 65  <title>Write-Ahe
0010: 61 64 20 4c 6f 67 67 69 6e 67 3c 2f 74 69 74 6c  ad Logging</titl
0020: 65 3e 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79 77 6f  e>.<tcl>hd_keywo
0030: 72 64 73 20 7b 57 41 4c 7d 20 7b 77 72 69 74 65  rds {WAL} {write
0040: 2d 61 68 65 61 64 20 6c 6f 67 7d 20 7b 57 41 4c  -ahead log} {WAL
0050: 20 6d 6f 64 65 7d 3c 2f 74 63 6c 3e 0a 0a 3c 74   mode}</tcl>..<t
0060: 61 62 6c 65 5f 6f 66 5f 63 6f 6e 74 65 6e 74 73  able_of_contents
0070: 3e 0a 0a 3c 68 31 3e 4f 76 65 72 76 69 65 77 3c  >..<h1>Overview<
0080: 2f 68 31 3e 0a 0a 3c 70 3e 54 68 65 20 64 65 66  /h1>..<p>The def
0090: 61 75 6c 74 20 6d 65 74 68 6f 64 20 62 79 20 77  ault method by w
00a0: 68 69 63 68 20 53 51 4c 69 74 65 20 69 6d 70 6c  hich SQLite impl
00b0: 65 6d 65 6e 74 73 0a 5b 61 74 6f 6d 69 63 20 63  ements.[atomic c
00c0: 6f 6d 6d 69 74 20 7c 20 61 74 6f 6d 69 63 20 63  ommit | atomic c
00d0: 6f 6d 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61  ommit and rollba
00e0: 63 6b 5d 20 69 73 20 61 20 5b 72 6f 6c 6c 62 61  ck] is a [rollba
00f0: 63 6b 20 6a 6f 75 72 6e 61 6c 5d 2e 0a 42 65 67  ck journal]..Beg
0100: 69 6e 6e 69 6e 67 20 77 69 74 68 20 5b 76 65 72  inning with [ver
0110: 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 28 5b 64 61  sion 3.7.0] ([da
0120: 74 65 6f 66 3a 33 2e 37 2e 30 5d 29 2c 20 61 20  teof:3.7.0]), a 
0130: 6e 65 77 20 22 57 72 69 74 65 2d 41 68 65 61 64  new "Write-Ahead
0140: 20 4c 6f 67 22 20 6f 70 74 69 6f 6e 0a 28 68 65   Log" option.(he
0150: 72 65 61 66 74 65 72 20 72 65 66 65 72 72 65 64  reafter referred
0160: 20 74 6f 20 61 73 20 22 57 41 4c 22 29 20 69 73   to as "WAL") is
0170: 20 61 76 61 69 6c 61 62 6c 65 2e 3c 2f 70 3e 0a   available.</p>.
0180: 0a 3c 70 3e 54 68 65 72 65 20 61 72 65 20 61 64  .<p>There are ad
0190: 76 61 6e 74 61 67 65 73 20 61 6e 64 20 64 69 73  vantages and dis
01a0: 61 64 76 61 6e 74 61 67 65 73 20 74 6f 20 75 73  advantages to us
01b0: 69 6e 67 20 57 41 4c 20 69 6e 73 74 65 61 64 20  ing WAL instead 
01c0: 6f 66 0a 61 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  of.a rollback jo
01d0: 75 72 6e 61 6c 2e 20 20 41 64 76 61 6e 74 61 67  urnal.  Advantag
01e0: 65 73 20 69 6e 63 6c 75 64 65 3a 3c 2f 70 3e 0a  es include:</p>.
01f0: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
0200: 74 20 61 64 76 61 6e 74 61 67 65 73 20 7b 61 64  t advantages {ad
0210: 76 61 6e 74 61 67 65 73 20 6f 66 20 57 41 4c 2d  vantages of WAL-
0220: 6d 6f 64 65 7d 3c 2f 74 63 6c 3e 0a 3c 6f 6c 3e  mode}</tcl>.<ol>
0230: 0a 3c 6c 69 3e 57 41 4c 20 69 73 20 73 69 67 6e  .<li>WAL is sign
0240: 69 66 69 63 61 6e 74 6c 79 20 66 61 73 74 65 72  ificantly faster
0250: 20 69 6e 20 6d 6f 73 74 20 73 63 65 6e 61 72 69   in most scenari
0260: 6f 73 2e 0a 3c 6c 69 3e 57 41 4c 20 70 72 6f 76  os..<li>WAL prov
0270: 69 64 65 73 20 6d 6f 72 65 20 63 6f 6e 63 75 72  ides more concur
0280: 72 65 6e 63 79 20 61 73 20 72 65 61 64 65 72 73  rency as readers
0290: 20 64 6f 20 6e 6f 74 20 62 6c 6f 63 6b 20 77 72   do not block wr
02a0: 69 74 65 72 73 20 61 6e 64 20 0a 20 20 20 20 61  iters and .    a
02b0: 20 77 72 69 74 65 72 20 64 6f 65 73 20 6e 6f 74   writer does not
02c0: 20 62 6c 6f 63 6b 20 72 65 61 64 65 72 73 2e 20   block readers. 
02d0: 20 52 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   Reading and wri
02e0: 74 69 6e 67 20 63 61 6e 20 70 72 6f 63 65 65 64  ting can proceed
02f0: 20 0a 20 20 20 20 63 6f 6e 63 75 72 72 65 6e 74   .    concurrent
0300: 6c 79 2e 0a 3c 6c 69 3e 44 69 73 6b 20 49 2f 4f  ly..<li>Disk I/O
0310: 20 6f 70 65 72 61 74 69 6f 6e 73 20 74 65 6e 64   operations tend
0320: 73 20 74 6f 20 62 65 20 6d 6f 72 65 20 73 65 71  s to be more seq
0330: 75 65 6e 74 69 61 6c 20 75 73 69 6e 67 20 57 41  uential using WA
0340: 4c 2e 0a 3c 6c 69 3e 57 41 4c 20 75 73 65 73 20  L..<li>WAL uses 
0350: 6d 61 6e 79 20 66 65 77 65 72 20 66 73 79 6e 63  many fewer fsync
0360: 28 29 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 6e  () operations an
0370: 64 20 69 73 20 74 68 75 73 20 6c 65 73 73 20 76  d is thus less v
0380: 75 6c 6e 65 72 61 62 6c 65 20 74 6f 0a 20 20 20  ulnerable to.   
0390: 20 70 72 6f 62 6c 65 6d 73 20 6f 6e 20 73 79 73   problems on sys
03a0: 74 65 6d 73 20 77 68 65 72 65 20 74 68 65 20 66  tems where the f
03b0: 73 79 6e 63 28 29 20 73 79 73 74 65 6d 20 63 61  sync() system ca
03c0: 6c 6c 20 69 73 20 62 72 6f 6b 65 6e 2e 0a 3c 2f  ll is broken..</
03d0: 6f 6c 3e 0a 0a 3c 70 3e 42 75 74 20 74 68 65 72  ol>..<p>But ther
03e0: 65 20 61 72 65 20 61 6c 73 6f 20 64 69 73 61 64  e are also disad
03f0: 76 61 6e 74 61 67 65 73 3a 3c 2f 70 3e 0a 0a 3c  vantages:</p>..<
0400: 6f 6c 3e 0a 3c 6c 69 3e 57 41 4c 20 6e 6f 72 6d  ol>.<li>WAL norm
0410: 61 6c 6c 79 20 72 65 71 75 69 72 65 73 20 74 68  ally requires th
0420: 61 74 20 74 68 65 20 5b 56 46 53 5d 20 0a 20 20  at the [VFS] .  
0430: 20 20 73 75 70 70 6f 72 74 20 73 68 61 72 65 64    support shared
0440: 2d 6d 65 6d 6f 72 79 20 70 72 69 6d 69 74 69 76  -memory primitiv
0450: 65 73 2e 0a 20 20 20 20 28 45 78 63 65 70 74 69  es..    (Excepti
0460: 6f 6e 3a 20 5b 57 41 4c 20 77 69 74 68 6f 75 74  on: [WAL without
0470: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 5d 29   shared memory])
0480: 0a 20 20 20 20 54 68 65 20 62 75 69 6c 74 2d 69  .    The built-i
0490: 6e 20 75 6e 69 78 20 61 6e 64 20 77 69 6e 64 6f  n unix and windo
04a0: 77 73 20 56 46 53 65 73 0a 20 20 20 20 73 75 70  ws VFSes.    sup
04b0: 70 6f 72 74 20 74 68 69 73 20 62 75 74 20 74 68  port this but th
04c0: 69 72 64 2d 70 61 72 74 79 20 65 78 74 65 6e 73  ird-party extens
04d0: 69 6f 6e 20 56 46 53 65 73 20 66 6f 72 20 63 75  ion VFSes for cu
04e0: 73 74 6f 6d 20 6f 70 65 72 61 74 69 6e 67 0a 20  stom operating. 
04f0: 20 20 20 73 79 73 74 65 6d 73 20 6d 69 67 68 74     systems might
0500: 20 6e 6f 74 2e 0a 3c 6c 69 3e 41 6c 6c 20 70 72   not..<li>All pr
0510: 6f 63 65 73 73 65 73 20 75 73 69 6e 67 20 61 20  ocesses using a 
0520: 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 62 65  database must be
0530: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 68 6f 73   on the same hos
0540: 74 20 63 6f 6d 70 75 74 65 72 3b 0a 20 20 20 20  t computer;.    
0550: 57 41 4c 20 64 6f 65 73 20 6e 6f 74 20 77 6f 72  WAL does not wor
0560: 6b 20 6f 76 65 72 20 61 20 6e 65 74 77 6f 72 6b  k over a network
0570: 20 66 69 6c 65 73 79 73 74 65 6d 2e 0a 3c 6c 69   filesystem..<li
0580: 3e 54 72 61 6e 73 61 63 74 69 6f 6e 73 20 74 68  >Transactions th
0590: 61 74 20 69 6e 76 6f 6c 76 65 20 63 68 61 6e 67  at involve chang
05a0: 65 73 20 61 67 61 69 6e 73 74 20 6d 75 6c 74 69  es against multi
05b0: 70 6c 65 20 5b 41 54 54 41 43 48 20 7c 20 41 54  ple [ATTACH | AT
05c0: 54 41 43 48 65 64 5d 0a 20 20 20 20 64 61 74 61  TACHed].    data
05d0: 62 61 73 65 73 20 61 72 65 20 61 74 6f 6d 69 63  bases are atomic
05e0: 20 66 6f 72 20 65 61 63 68 20 69 6e 64 69 76 69   for each indivi
05f0: 64 75 61 6c 20 64 61 74 61 62 61 73 65 2c 20 62  dual database, b
0600: 75 74 20 61 72 65 20 6e 6f 74 0a 20 20 20 20 61  ut are not.    a
0610: 74 6f 6d 69 63 20 61 63 72 6f 73 73 20 61 6c 6c  tomic across all
0620: 20 64 61 74 61 62 61 73 65 73 20 61 73 20 61 20   databases as a 
0630: 73 65 74 2e 0a 3c 6c 69 3e 49 74 20 69 73 20 6e  set..<li>It is n
0640: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
0650: 68 61 6e 67 65 20 74 68 65 20 5b 70 61 67 65 5f  hange the [page_
0660: 73 69 7a 65 5d 20 61 66 74 65 72 20 65 6e 74 65  size] after ente
0670: 72 69 6e 67 20 57 41 4c 0a 20 20 20 20 6d 6f 64  ring WAL.    mod
0680: 65 2c 20 65 69 74 68 65 72 20 6f 6e 20 61 6e 20  e, either on an 
0690: 65 6d 70 74 79 20 64 61 74 61 62 61 73 65 20 6f  empty database o
06a0: 72 20 62 79 20 75 73 69 6e 67 20 5b 56 41 43 55  r by using [VACU
06b0: 55 4d 5d 20 6f 72 20 62 79 20 72 65 73 74 6f 72  UM] or by restor
06c0: 69 6e 67 0a 20 20 20 20 66 72 6f 6d 20 61 20 62  ing.    from a b
06d0: 61 63 6b 75 70 20 75 73 69 6e 67 20 74 68 65 20  ackup using the 
06e0: 5b 62 61 63 6b 75 70 20 41 50 49 5d 2e 20 20 59  [backup API].  Y
06f0: 6f 75 20 6d 75 73 74 20 62 65 20 69 6e 20 61 20  ou must be in a 
0700: 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
0710: 0a 20 20 20 20 6d 6f 64 65 20 74 6f 20 63 68 61  .    mode to cha
0720: 6e 67 65 20 74 68 65 20 70 61 67 65 20 73 69 7a  nge the page siz
0730: 65 2e 0a 3c 6c 69 3e 3c 73 3e 49 74 20 69 73 20  e..<li><s>It is 
0740: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
0750: 6f 70 65 6e 20 5b 72 65 61 64 2d 6f 6e 6c 79 20  open [read-only 
0760: 57 41 4c 20 64 61 74 61 62 61 73 65 73 5d 2e 0a  WAL databases]..
0770: 20 20 20 20 54 68 65 20 6f 70 65 6e 69 6e 67 20      The opening 
0780: 70 72 6f 63 65 73 73 20 6d 75 73 74 20 68 61 76  process must hav
0790: 65 20 77 72 69 74 65 20 70 72 69 76 69 6c 65 67  e write privileg
07a0: 65 73 20 66 6f 72 20 22 3c 74 74 3e 2d 73 68 6d  es for "<tt>-shm
07b0: 3c 2f 74 74 3e 22 0a 20 20 20 20 5b 77 61 6c 2d  </tt>".    [wal-
07c0: 69 6e 64 65 78 5d 20 73 68 61 72 65 64 20 6d 65  index] shared me
07d0: 6d 6f 72 79 20 66 69 6c 65 20 61 73 73 6f 63 69  mory file associ
07e0: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
07f0: 74 61 62 61 73 65 2c 20 69 66 20 74 68 61 74 0a  tabase, if that.
0800: 20 20 20 20 66 69 6c 65 20 65 78 69 73 74 73 2c      file exists,
0810: 20 6f 72 20 65 6c 73 65 20 77 72 69 74 65 20 61   or else write a
0820: 63 63 65 73 73 20 6f 6e 20 74 68 65 20 64 69 72  ccess on the dir
0830: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
0840: 67 0a 20 20 20 20 74 68 65 20 64 61 74 61 62 61  g.    the databa
0850: 73 65 20 66 69 6c 65 20 69 66 20 74 68 65 20 22  se file if the "
0860: 3c 74 74 3e 2d 73 68 6d 3c 2f 74 74 3e 22 20 66  <tt>-shm</tt>" f
0870: 69 6c 65 20 64 6f 65 73 20 6e 6f 74 20 65 78 69  ile does not exi
0880: 73 74 2e 3c 2f 73 3e 0a 20 20 20 20 42 65 67 69  st.</s>.    Begi
0890: 6e 6e 69 6e 67 20 77 69 74 68 20 5b 76 65 72 73  nning with [vers
08a0: 69 6f 6e 20 33 2e 32 32 2e 30 5d 20 28 5b 64 61  ion 3.22.0] ([da
08b0: 74 65 6f 66 3a 33 2e 32 32 2e 30 5d 29 2c 20 61  teof:3.22.0]), a
08c0: 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 20 20 20 20   read-only .    
08d0: 57 41 4c 2d 6d 6f 64 65 20 64 61 74 61 62 61 73  WAL-mode databas
08e0: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 6f 70  e file can be op
08f0: 65 6e 65 64 20 69 66 0a 20 20 20 20 74 68 65 20  ened if.    the 
0900: 3c 74 74 3e 2d 73 68 6d 3c 2f 74 74 3e 20 61 6e  <tt>-shm</tt> an
0910: 64 20 3c 74 74 3e 2d 77 61 6c 3c 2f 74 74 3e 20  d <tt>-wal</tt> 
0920: 66 69 6c 65 73 0a 20 20 20 20 61 6c 72 65 61 64  files.    alread
0930: 79 20 65 78 69 73 74 73 20 6f 72 20 74 68 6f 73  y exists or thos
0940: 65 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 63  e files can be c
0950: 72 65 61 74 65 64 20 6f 72 20 74 68 65 0a 20 20  reated or the.  
0960: 20 20 5b 69 6d 6d 75 74 61 62 6c 65 20 71 75 65    [immutable que
0970: 72 79 20 70 61 72 61 6d 65 74 65 72 7c 64 61 74  ry parameter|dat
0980: 61 62 61 73 65 20 69 73 20 69 6d 6d 75 74 61 62  abase is immutab
0990: 6c 65 5d 2e 0a 3c 6c 69 3e 57 41 4c 20 6d 69 67  le]..<li>WAL mig
09a0: 68 74 20 62 65 20 76 65 72 79 20 73 6c 69 67 68  ht be very sligh
09b0: 74 6c 79 20 73 6c 6f 77 65 72 20 28 70 65 72 68  tly slower (perh
09c0: 61 70 73 20 31 25 20 6f 72 20 32 25 20 73 6c 6f  aps 1% or 2% slo
09d0: 77 65 72 29 0a 20 20 20 20 74 68 61 6e 20 74 68  wer).    than th
09e0: 65 20 74 72 61 64 69 74 69 6f 6e 61 6c 20 72 6f  e traditional ro
09f0: 6c 6c 62 61 63 6b 2d 6a 6f 75 72 6e 61 6c 20 61  llback-journal a
0a00: 70 70 72 6f 61 63 68 0a 20 20 20 20 69 6e 20 61  pproach.    in a
0a10: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
0a20: 20 64 6f 20 6d 6f 73 74 6c 79 20 72 65 61 64 73   do mostly reads
0a30: 20 61 6e 64 20 73 65 6c 64 6f 6d 20 77 72 69 74   and seldom writ
0a40: 65 2e 0a 3c 6c 69 3e 54 68 65 72 65 20 69 73 20  e..<li>There is 
0a50: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  an additional qu
0a60: 61 73 69 2d 70 65 72 73 69 73 74 65 6e 74 20 22  asi-persistent "
0a70: 3c 74 74 3e 2d 77 61 6c 3c 2f 74 74 3e 22 20 66  <tt>-wal</tt>" f
0a80: 69 6c 65 20 61 6e 64 0a 20 20 20 20 22 3c 74 74  ile and.    "<tt
0a90: 3e 2d 73 68 6d 3c 2f 74 74 3e 22 20 73 68 61 72  >-shm</tt>" shar
0aa0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 20 61  ed memory file a
0ab0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 65  ssociated with e
0ac0: 61 63 68 0a 20 20 20 20 64 61 74 61 62 61 73 65  ach.    database
0ad0: 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61 6b 65  , which can make
0ae0: 20 53 51 4c 69 74 65 20 6c 65 73 73 20 61 70 70   SQLite less app
0af0: 65 61 6c 69 6e 67 20 66 6f 72 20 75 73 65 20 61  ealing for use a
0b00: 73 20 61 6e 20 0a 20 20 20 20 5b 61 70 70 6c 69  s an .    [appli
0b10: 63 61 74 69 6f 6e 20 66 69 6c 65 2d 66 6f 72 6d  cation file-form
0b20: 61 74 5d 2e 0a 3c 6c 69 3e 54 68 65 72 65 20 69  at]..<li>There i
0b30: 73 20 74 68 65 20 65 78 74 72 61 20 6f 70 65 72  s the extra oper
0b40: 61 74 69 6f 6e 20 6f 66 20 5b 63 68 65 63 6b 70  ation of [checkp
0b50: 6f 69 6e 74 69 6e 67 5d 20 77 68 69 63 68 2c 20  ointing] which, 
0b60: 74 68 6f 75 67 68 20 61 75 74 6f 6d 61 74 69 63  though automatic
0b70: 0a 20 20 20 20 62 79 20 64 65 66 61 75 6c 74 2c  .    by default,
0b80: 20 69 73 20 73 74 69 6c 6c 20 73 6f 6d 65 74 68   is still someth
0b90: 69 6e 67 20 74 68 61 74 20 61 70 70 6c 69 63 61  ing that applica
0ba0: 74 69 6f 6e 20 64 65 76 65 6c 6f 70 65 72 73 20  tion developers 
0bb0: 6e 65 65 64 20 74 6f 0a 20 20 20 20 62 65 20 6d  need to.    be m
0bc0: 69 6e 64 66 75 6c 20 6f 66 2e 0a 3c 6c 69 3e 3c  indful of..<li><
0bd0: 73 3e 57 41 4c 20 77 6f 72 6b 73 20 62 65 73 74  s>WAL works best
0be0: 20 77 69 74 68 20 73 6d 61 6c 6c 65 72 20 74 72   with smaller tr
0bf0: 61 6e 73 61 63 74 69 6f 6e 73 2e 20 20 57 41 4c  ansactions.  WAL
0c00: 20 64 6f 65 73 0a 20 20 20 20 6e 6f 74 20 77 6f   does.    not wo
0c10: 72 6b 20 77 65 6c 6c 20 66 6f 72 20 76 65 72 79  rk well for very
0c20: 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
0c30: 6f 6e 73 2e 20 20 46 6f 72 20 74 72 61 6e 73 61  ons.  For transa
0c40: 63 74 69 6f 6e 73 20 6c 61 72 67 65 72 20 74 68  ctions larger th
0c50: 61 6e 0a 20 20 20 20 61 62 6f 75 74 20 31 30 30  an.    about 100
0c60: 20 6d 65 67 61 62 79 74 65 73 2c 20 74 72 61 64   megabytes, trad
0c70: 69 74 69 6f 6e 61 6c 20 72 6f 6c 6c 62 61 63 6b  itional rollback
0c80: 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 20 77   journal modes w
0c90: 69 6c 6c 20 6c 69 6b 65 6c 79 0a 20 20 20 20 62  ill likely.    b
0ca0: 65 20 66 61 73 74 65 72 2e 20 20 46 6f 72 20 74  e faster.  For t
0cb0: 72 61 6e 73 61 63 74 69 6f 6e 73 20 69 6e 20 65  ransactions in e
0cc0: 78 63 65 73 73 20 6f 66 20 61 20 67 69 67 61 62  xcess of a gigab
0cd0: 79 74 65 2c 20 57 41 4c 20 6d 6f 64 65 20 6d 61  yte, WAL mode ma
0ce0: 79 20 0a 20 20 20 20 66 61 69 6c 20 77 69 74 68  y .    fail with
0cf0: 20 61 6e 20 49 2f 4f 20 6f 72 20 64 69 73 6b 2d   an I/O or disk-
0d00: 66 75 6c 6c 20 65 72 72 6f 72 2e 0a 20 20 20 20  full error..    
0d10: 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
0d20: 64 20 74 68 61 74 20 6f 6e 65 20 6f 66 20 74 68  d that one of th
0d30: 65 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e  e rollback journ
0d40: 61 6c 20 6d 6f 64 65 73 20 62 65 20 75 73 65 64  al modes be used
0d50: 20 66 6f 72 0a 20 20 20 20 74 72 61 6e 73 61 63   for.    transac
0d60: 74 69 6f 6e 73 20 6c 61 72 67 65 72 20 74 68 61  tions larger tha
0d70: 6e 20 61 20 66 65 77 20 64 6f 7a 65 6e 20 6d 65  n a few dozen me
0d80: 67 61 62 79 74 65 73 2e 3c 2f 73 3e 0a 20 20 20  gabytes.</s>.   
0d90: 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
0da0: 5b 76 65 72 73 69 6f 6e 20 33 2e 31 31 2e 30 5d  [version 3.11.0]
0db0: 20 28 5b 64 61 74 65 6f 66 3a 33 2e 31 31 2e 30   ([dateof:3.11.0
0dc0: 5d 29 2c 20 0a 20 20 20 20 57 41 4c 20 6d 6f 64  ]), .    WAL mod
0dd0: 65 20 77 6f 72 6b 73 20 61 73 20 65 66 66 69 63  e works as effic
0de0: 69 65 6e 74 6c 79 20 77 69 74 68 0a 20 20 20 20  iently with.    
0df0: 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
0e00: 6e 73 20 61 73 20 64 6f 65 73 20 72 6f 6c 6c 62  ns as does rollb
0e10: 61 63 6b 20 6d 6f 64 65 2e 0a 20 20 20 20 0a 3c  ack mode..    .<
0e20: 2f 6f 6c 3e 0a 0a 3c 68 31 3e 48 6f 77 20 57 41  /ol>..<h1>How WA
0e30: 4c 20 57 6f 72 6b 73 3c 2f 68 31 3e 0a 0a 3c 70  L Works</h1>..<p
0e40: 3e 54 68 65 20 74 72 61 64 69 74 69 6f 6e 61 6c  >The traditional
0e50: 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61   rollback journa
0e60: 6c 20 77 6f 72 6b 73 20 62 79 20 77 72 69 74 69  l works by writi
0e70: 6e 67 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ng a copy of the
0e80: 0a 6f 72 69 67 69 6e 61 6c 20 75 6e 63 68 61 6e  .original unchan
0e90: 67 65 64 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ged database con
0ea0: 74 65 6e 74 20 69 6e 74 6f 20 61 20 73 65 70 61  tent into a sepa
0eb0: 72 61 74 65 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  rate rollback jo
0ec0: 75 72 6e 61 6c 20 66 69 6c 65 0a 61 6e 64 20 74  urnal file.and t
0ed0: 68 65 6e 20 77 72 69 74 69 6e 67 20 63 68 61 6e  hen writing chan
0ee0: 67 65 73 20 64 69 72 65 63 74 6c 79 20 69 6e 74  ges directly int
0ef0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
0f00: 69 6c 65 2e 20 20 49 6e 20 74 68 65 0a 65 76 65  ile.  In the.eve
0f10: 6e 74 20 6f 66 20 61 20 63 72 61 73 68 20 6f 72  nt of a crash or
0f20: 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 20 74 68 65   [ROLLBACK], the
0f30: 20 6f 72 69 67 69 6e 61 6c 20 63 6f 6e 74 65 6e   original conten
0f40: 74 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  t contained in t
0f50: 68 65 0a 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  he.rollback jour
0f60: 6e 61 6c 20 69 73 20 70 6c 61 79 65 64 20 62 61  nal is played ba
0f70: 63 6b 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  ck into the data
0f80: 62 61 73 65 20 66 69 6c 65 20 74 6f 0a 72 65 76  base file to.rev
0f90: 65 72 74 20 74 68 65 20 64 61 74 61 62 61 73 65  ert the database
0fa0: 20 66 69 6c 65 20 74 6f 20 69 74 73 20 6f 72 69   file to its ori
0fb0: 67 69 6e 61 6c 20 73 74 61 74 65 2e 20 20 54 68  ginal state.  Th
0fc0: 65 20 5b 43 4f 4d 4d 49 54 5d 20 6f 63 63 75 72  e [COMMIT] occur
0fd0: 73 0a 77 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62  s.when the rollb
0fe0: 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 69 73 20 64  ack journal is d
0ff0: 65 6c 65 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e  eleted.</p>..<p>
1000: 54 68 65 20 57 41 4c 20 61 70 70 72 6f 61 63 68  The WAL approach
1010: 20 69 6e 76 65 72 74 73 20 74 68 69 73 2e 20 20   inverts this.  
1020: 54 68 65 20 6f 72 69 67 69 6e 61 6c 20 63 6f 6e  The original con
1030: 74 65 6e 74 20 69 73 20 70 72 65 73 65 72 76 65  tent is preserve
1040: 64 0a 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  d.in the databas
1050: 65 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 63  e file and the c
1060: 68 61 6e 67 65 73 20 61 72 65 20 61 70 70 65 6e  hanges are appen
1070: 64 65 64 20 69 6e 74 6f 20 61 20 73 65 70 61 72  ded into a separ
1080: 61 74 65 0a 57 41 4c 20 66 69 6c 65 2e 20 20 41  ate.WAL file.  A
1090: 20 5b 43 4f 4d 4d 49 54 5d 20 6f 63 63 75 72 73   [COMMIT] occurs
10a0: 20 77 68 65 6e 20 61 20 73 70 65 63 69 61 6c 20   when a special 
10b0: 72 65 63 6f 72 64 20 69 6e 64 69 63 61 74 69 6e  record indicatin
10c0: 67 20 61 20 63 6f 6d 6d 69 74 0a 69 73 20 61 70  g a commit.is ap
10d0: 70 65 6e 64 65 64 20 74 6f 20 74 68 65 20 57 41  pended to the WA
10e0: 4c 2e 20 20 54 68 75 73 20 61 20 43 4f 4d 4d 49  L.  Thus a COMMI
10f0: 54 20 63 61 6e 20 68 61 70 70 65 6e 20 77 69 74  T can happen wit
1100: 68 6f 75 74 20 65 76 65 72 20 77 72 69 74 69 6e  hout ever writin
1110: 67 0a 74 6f 20 74 68 65 20 6f 72 69 67 69 6e 61  g.to the origina
1120: 6c 20 64 61 74 61 62 61 73 65 2c 20 77 68 69 63  l database, whic
1130: 68 20 61 6c 6c 6f 77 73 20 72 65 61 64 65 72 73  h allows readers
1140: 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6f 70 65   to continue ope
1150: 72 61 74 69 6e 67 0a 66 72 6f 6d 20 74 68 65 20  rating.from the 
1160: 6f 72 69 67 69 6e 61 6c 20 75 6e 61 6c 74 65 72  original unalter
1170: 65 64 20 64 61 74 61 62 61 73 65 20 77 68 69 6c  ed database whil
1180: 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 73 69  e changes are si
1190: 6d 75 6c 74 61 6e 65 6f 75 73 6c 79 20 62 65 69  multaneously bei
11a0: 6e 67 0a 63 6f 6d 6d 69 74 74 65 64 20 69 6e 74  ng.committed int
11b0: 6f 20 74 68 65 20 57 41 4c 2e 20 20 4d 75 6c 74  o the WAL.  Mult
11c0: 69 70 6c 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  iple transaction
11d0: 73 20 63 61 6e 20 62 65 20 61 70 70 65 6e 64 65  s can be appende
11e0: 64 20 74 6f 20 74 68 65 0a 65 6e 64 20 6f 66 20  d to the.end of 
11f0: 61 20 73 69 6e 67 6c 65 20 57 41 4c 20 66 69 6c  a single WAL fil
1200: 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f  e.</p>..<tcl>hd_
1210: 66 72 61 67 6d 65 6e 74 20 63 6b 70 74 20 63 68  fragment ckpt ch
1220: 65 63 6b 70 6f 69 6e 74 20 63 68 65 63 6b 70 6f  eckpoint checkpo
1230: 69 6e 74 65 64 20 63 68 65 63 6b 70 6f 69 6e 74  inted checkpoint
1240: 69 6e 67 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 43 68  ing</tcl>.<h2>Ch
1250: 65 63 6b 70 6f 69 6e 74 69 6e 67 3c 2f 68 32 3e  eckpointing</h2>
1260: 0a 0a 3c 70 3e 4f 66 20 63 6f 75 72 73 65 2c 20  ..<p>Of course, 
1270: 6f 6e 65 20 77 61 6e 74 73 20 74 6f 20 65 76 65  one wants to eve
1280: 6e 74 75 61 6c 6c 79 20 74 72 61 6e 73 66 65 72  ntually transfer
1290: 20 61 6c 6c 20 74 68 65 20 74 72 61 6e 73 61 63   all the transac
12a0: 74 69 6f 6e 73 20 74 68 61 74 0a 61 72 65 20 61  tions that.are a
12b0: 70 70 65 6e 64 65 64 20 69 6e 20 74 68 65 20 57  ppended in the W
12c0: 41 4c 20 66 69 6c 65 20 62 61 63 6b 20 69 6e 74  AL file back int
12d0: 6f 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 64  o the original d
12e0: 61 74 61 62 61 73 65 2e 20 20 4d 6f 76 69 6e 67  atabase.  Moving
12f0: 0a 74 68 65 20 57 41 4c 20 66 69 6c 65 20 74 72  .the WAL file tr
1300: 61 6e 73 61 63 74 69 6f 6e 73 20 62 61 63 6b 20  ansactions back 
1310: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
1320: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 0a 22 3c  e is called a."<
1330: 69 3e 63 68 65 63 6b 70 6f 69 6e 74 3c 2f 69 3e  i>checkpoint</i>
1340: 22 2e 3c 70 3e 0a 0a 3c 70 3e 41 6e 6f 74 68 65  ".<p>..<p>Anothe
1350: 72 20 77 61 79 20 74 6f 20 74 68 69 6e 6b 20 61  r way to think a
1360: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65  bout the differe
1370: 6e 63 65 20 62 65 74 77 65 65 6e 20 72 6f 6c 6c  nce between roll
1380: 62 61 63 6b 20 61 6e 64 20 0a 77 72 69 74 65 2d  back and .write-
1390: 61 68 65 61 64 20 6c 6f 67 20 69 73 20 74 68 61  ahead log is tha
13a0: 74 20 69 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63  t in the rollbac
13b0: 6b 2d 6a 6f 75 72 6e 61 6c 0a 61 70 70 72 6f 61  k-journal.approa
13c0: 63 68 2c 20 74 68 65 72 65 20 61 72 65 20 74 77  ch, there are tw
13d0: 6f 20 70 72 69 6d 69 74 69 76 65 20 6f 70 65 72  o primitive oper
13e0: 61 74 69 6f 6e 73 2c 20 72 65 61 64 69 6e 67 20  ations, reading 
13f0: 61 6e 64 20 77 72 69 74 69 6e 67 2c 0a 77 68 65  and writing,.whe
1400: 72 65 61 73 20 77 69 74 68 20 61 20 77 72 69 74  reas with a writ
1410: 65 2d 61 68 65 61 64 20 6c 6f 67 0a 74 68 65 72  e-ahead log.ther
1420: 65 20 61 72 65 20 6e 6f 77 20 74 68 72 65 65 20  e are now three 
1430: 70 72 69 6d 69 74 69 76 65 20 6f 70 65 72 61 74  primitive operat
1440: 69 6f 6e 73 3a 20 20 72 65 61 64 69 6e 67 2c 20  ions:  reading, 
1450: 77 72 69 74 69 6e 67 2c 20 61 6e 64 0a 63 68 65  writing, and.che
1460: 63 6b 70 6f 69 6e 74 69 6e 67 2e 3c 2f 70 3e 0a  ckpointing.</p>.
1470: 0a 3c 70 3e 42 79 20 64 65 66 61 75 6c 74 2c 20  .<p>By default, 
1480: 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 63 68  SQLite does a ch
1490: 65 63 6b 70 6f 69 6e 74 20 61 75 74 6f 6d 61 74  eckpoint automat
14a0: 69 63 61 6c 6c 79 20 77 68 65 6e 20 74 68 65 20  ically when the 
14b0: 57 41 4c 20 66 69 6c 65 0a 72 65 61 63 68 65 73  WAL file.reaches
14c0: 20 61 20 74 68 72 65 73 68 6f 6c 64 20 73 69 7a   a threshold siz
14d0: 65 20 6f 66 20 31 30 30 30 20 70 61 67 65 73 2e  e of 1000 pages.
14e0: 20 20 28 54 68 65 0a 5b 53 51 4c 49 54 45 5f 44    (The.[SQLITE_D
14f0: 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55 54 4f 43  EFAULT_WAL_AUTOC
1500: 48 45 43 4b 50 4f 49 4e 54 5d 20 63 6f 6d 70 69  HECKPOINT] compi
1510: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63  le-time option c
1520: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 0a 73 70  an be used to.sp
1530: 65 63 69 66 79 20 61 20 64 69 66 66 65 72 65 6e  ecify a differen
1540: 74 20 64 65 66 61 75 6c 74 2e 29 20 41 70 70 6c  t default.) Appl
1550: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 20 57  ications using W
1560: 41 4c 20 64 6f 0a 6e 6f 74 20 68 61 76 65 20 74  AL do.not have t
1570: 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 69 6e  o do anything in
1580: 20 6f 72 64 65 72 20 74 6f 20 66 6f 72 20 74 68   order to for th
1590: 65 73 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 20  ese checkpoints 
15a0: 74 6f 20 6f 63 63 75 72 2e 20 20 0a 42 75 74 20  to occur.  .But 
15b0: 69 66 20 74 68 65 79 20 77 61 6e 74 20 74 6f 2c  if they want to,
15c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 63 61   applications ca
15d0: 6e 20 61 64 6a 75 73 74 20 74 68 65 20 61 75 74  n adjust the aut
15e0: 6f 6d 61 74 69 63 20 63 68 65 63 6b 70 6f 69 6e  omatic checkpoin
15f0: 74 0a 74 68 72 65 73 68 6f 6c 64 2e 20 20 4f 72  t.threshold.  Or
1600: 20 74 68 65 79 20 63 61 6e 20 74 75 72 6e 20 6f   they can turn o
1610: 66 66 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  ff the automatic
1620: 20 63 68 65 63 6b 70 6f 69 6e 74 73 20 61 6e 64   checkpoints and
1630: 20 72 75 6e 20 0a 63 68 65 63 6b 70 6f 69 6e 74   run .checkpoint
1640: 73 20 64 75 72 69 6e 67 20 69 64 6c 65 20 6d 6f  s during idle mo
1650: 6d 65 6e 74 73 20 6f 72 20 69 6e 20 61 20 73 65  ments or in a se
1660: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6f 72  parate thread or
1670: 20 70 72 6f 63 65 73 73 2e 3c 2f 70 3e 0a 0a 3c   process.</p>..<
1680: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
1690: 63 6f 6e 63 75 72 72 65 6e 63 79 20 7b 57 41 4c  concurrency {WAL
16a0: 20 63 6f 6e 63 75 72 72 65 6e 63 79 7d 3c 2f 74   concurrency}</t
16b0: 63 6c 3e 0a 3c 68 32 3e 43 6f 6e 63 75 72 72 65  cl>.<h2>Concurre
16c0: 6e 63 79 3c 2f 68 32 3e 0a 0a 3c 70 3e 57 68 65  ncy</h2>..<p>Whe
16d0: 6e 20 61 20 72 65 61 64 20 6f 70 65 72 61 74 69  n a read operati
16e0: 6f 6e 20 62 65 67 69 6e 73 20 6f 6e 20 61 20 57  on begins on a W
16f0: 41 4c 2d 6d 6f 64 65 20 64 61 74 61 62 61 73 65  AL-mode database
1700: 2c 20 69 74 20 66 69 72 73 74 0a 72 65 6d 65 6d  , it first.remem
1710: 62 65 72 73 20 74 68 65 20 6c 6f 63 61 74 69 6f  bers the locatio
1720: 6e 20 6f 66 20 74 68 65 20 6c 61 73 74 20 76 61  n of the last va
1730: 6c 69 64 20 63 6f 6d 6d 69 74 20 72 65 63 6f 72  lid commit recor
1740: 64 20 69 6e 20 74 68 65 20 57 41 4c 2e 0a 43 61  d in the WAL..Ca
1750: 6c 6c 20 74 68 69 73 20 70 6f 69 6e 74 20 74 68  ll this point th
1760: 65 20 22 65 6e 64 20 6d 61 72 6b 22 2e 20 20 42  e "end mark".  B
1770: 65 63 61 75 73 65 20 74 68 65 20 57 41 4c 20 63  ecause the WAL c
1780: 61 6e 20 62 65 20 67 72 6f 77 69 6e 67 20 61 6e  an be growing an
1790: 64 0a 61 64 64 69 6e 67 20 6e 65 77 20 63 6f 6d  d.adding new com
17a0: 6d 69 74 20 72 65 63 6f 72 64 73 20 77 68 69 6c  mit records whil
17b0: 65 20 76 61 72 69 6f 75 73 20 72 65 61 64 65 72  e various reader
17c0: 73 20 63 6f 6e 6e 65 63 74 20 74 6f 20 74 68 65  s connect to the
17d0: 20 64 61 74 61 62 61 73 65 2c 0a 65 61 63 68 20   database,.each 
17e0: 72 65 61 64 65 72 20 63 61 6e 20 70 6f 74 65 6e  reader can poten
17f0: 74 69 61 6c 6c 79 20 68 61 76 65 20 69 74 73 20  tially have its 
1800: 6f 77 6e 20 65 6e 64 20 6d 61 72 6b 2e 20 20 42  own end mark.  B
1810: 75 74 20 66 6f 72 20 61 6e 79 0a 70 61 72 74 69  ut for any.parti
1820: 63 75 6c 61 72 20 72 65 61 64 65 72 2c 20 74 68  cular reader, th
1830: 65 20 65 6e 64 20 6d 61 72 6b 20 69 73 20 75 6e  e end mark is un
1840: 63 68 61 6e 67 65 64 20 66 6f 72 20 74 68 65 20  changed for the 
1850: 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  duration of the.
1860: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 75  transaction, thu
1870: 73 20 65 6e 73 75 72 69 6e 67 20 74 68 61 74 20  s ensuring that 
1880: 61 20 73 69 6e 67 6c 65 20 72 65 61 64 20 74 72  a single read tr
1890: 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 6c 79 20 73  ansaction only s
18a0: 65 65 73 0a 74 68 65 20 64 61 74 61 62 61 73 65  ees.the database
18b0: 20 63 6f 6e 74 65 6e 74 20 61 73 20 69 74 20 65   content as it e
18c0: 78 69 73 74 65 64 20 61 74 20 61 20 73 69 6e 67  xisted at a sing
18d0: 6c 65 20 70 6f 69 6e 74 20 69 6e 20 74 69 6d 65  le point in time
18e0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 57 68 65 6e 20 61  .</p>..<p>When a
18f0: 20 72 65 61 64 65 72 20 6e 65 65 64 73 20 61 20   reader needs a 
1900: 70 61 67 65 20 6f 66 20 63 6f 6e 74 65 6e 74 2c  page of content,
1910: 20 69 74 20 66 69 72 73 74 20 63 68 65 63 6b 73   it first checks
1920: 20 74 68 65 20 57 41 4c 20 74 6f 0a 73 65 65 20   the WAL to.see 
1930: 69 66 20 74 68 61 74 20 70 61 67 65 20 61 70 70  if that page app
1940: 65 61 72 73 20 74 68 65 72 65 2c 20 61 6e 64 20  ears there, and 
1950: 69 66 20 73 6f 20 69 74 20 70 75 6c 6c 73 20 69  if so it pulls i
1960: 6e 20 74 68 65 20 6c 61 73 74 20 63 6f 70 79 0a  n the last copy.
1970: 6f 66 20 74 68 65 20 70 61 67 65 20 74 68 61 74  of the page that
1980: 20 6f 63 63 75 72 73 20 69 6e 20 74 68 65 20 57   occurs in the W
1990: 41 4c 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  AL prior to the 
19a0: 72 65 61 64 65 72 27 73 20 65 6e 64 20 6d 61 72  reader's end mar
19b0: 6b 2e 0a 49 66 20 6e 6f 20 63 6f 70 79 20 6f 66  k..If no copy of
19c0: 20 74 68 65 20 70 61 67 65 20 65 78 69 73 74 73   the page exists
19d0: 20 69 6e 20 74 68 65 20 57 41 4c 20 70 72 69 6f   in the WAL prio
19e0: 72 20 74 6f 20 74 68 65 20 72 65 61 64 65 72 27  r to the reader'
19f0: 73 20 65 6e 64 20 6d 61 72 6b 2c 0a 74 68 65 6e  s end mark,.then
1a00: 20 74 68 65 20 70 61 67 65 20 69 73 20 72 65 61   the page is rea
1a10: 64 20 66 72 6f 6d 20 74 68 65 20 6f 72 69 67 69  d from the origi
1a20: 6e 61 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  nal database fil
1a30: 65 2e 20 20 52 65 61 64 65 72 73 20 63 61 6e 0a  e.  Readers can.
1a40: 65 78 69 73 74 20 69 6e 20 73 65 70 61 72 61 74  exist in separat
1a50: 65 20 70 72 6f 63 65 73 73 65 73 2c 20 73 6f 20  e processes, so 
1a60: 74 6f 20 61 76 6f 69 64 20 66 6f 72 63 69 6e 67  to avoid forcing
1a70: 20 65 76 65 72 79 20 72 65 61 64 65 72 20 74 6f   every reader to
1a80: 20 73 63 61 6e 0a 74 68 65 20 65 6e 74 69 72 65   scan.the entire
1a90: 20 57 41 4c 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72   WAL looking for
1aa0: 20 70 61 67 65 73 20 28 74 68 65 20 57 41 4c 20   pages (the WAL 
1ab0: 66 69 6c 65 20 63 61 6e 20 67 72 6f 77 20 74 6f  file can grow to
1ac0: 0a 6d 75 6c 74 69 70 6c 65 20 6d 65 67 61 62 79  .multiple megaby
1ad0: 74 65 73 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  tes, depending o
1ae0: 6e 20 68 6f 77 20 6f 66 74 65 6e 20 63 68 65 63  n how often chec
1af0: 6b 70 6f 69 6e 74 73 20 61 72 65 20 72 75 6e 29  kpoints are run)
1b00: 2c 20 61 0a 64 61 74 61 20 73 74 72 75 63 74 75  , a.data structu
1b10: 72 65 20 63 61 6c 6c 65 64 20 74 68 65 20 22 77  re called the "w
1b20: 61 6c 2d 69 6e 64 65 78 22 20 69 73 20 6d 61 69  al-index" is mai
1b30: 6e 74 61 69 6e 65 64 20 69 6e 20 73 68 61 72 65  ntained in share
1b40: 64 20 6d 65 6d 6f 72 79 0a 77 68 69 63 68 20 68  d memory.which h
1b50: 65 6c 70 73 20 72 65 61 64 65 72 73 20 6c 6f 63  elps readers loc
1b60: 61 74 65 20 70 61 67 65 73 20 69 6e 20 74 68 65  ate pages in the
1b70: 20 57 41 4c 20 71 75 69 63 6b 6c 79 20 61 6e 64   WAL quickly and
1b80: 20 77 69 74 68 20 61 20 6d 69 6e 69 6d 75 6d 0a   with a minimum.
1b90: 6f 66 20 49 2f 4f 2e 20 20 54 68 65 20 77 61 6c  of I/O.  The wal
1ba0: 2d 69 6e 64 65 78 20 67 72 65 61 74 6c 79 20 69  -index greatly i
1bb0: 6d 70 72 6f 76 65 73 20 74 68 65 20 70 65 72 66  mproves the perf
1bc0: 6f 72 6d 61 6e 63 65 20 6f 66 20 72 65 61 64 65  ormance of reade
1bd0: 72 73 2c 0a 62 75 74 20 74 68 65 20 75 73 65 20  rs,.but the use 
1be0: 6f 66 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  of shared memory
1bf0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
1c00: 72 65 61 64 65 72 73 20 6d 75 73 74 20 65 78 69  readers must exi
1c10: 73 74 20 6f 6e 20 74 68 65 0a 73 61 6d 65 20 6d  st on the.same m
1c20: 61 63 68 69 6e 65 2e 20 20 54 68 69 73 20 69 73  achine.  This is
1c30: 20 77 68 79 20 74 68 65 20 77 72 69 74 65 2d 61   why the write-a
1c40: 68 65 61 64 20 6c 6f 67 20 69 6d 70 6c 65 6d 65  head log impleme
1c50: 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 6e 6f 74  ntation will not
1c60: 0a 77 6f 72 6b 20 6f 6e 20 61 20 6e 65 74 77 6f  .work on a netwo
1c70: 72 6b 20 66 69 6c 65 73 79 73 74 65 6d 2e 3c 2f  rk filesystem.</
1c80: 70 3e 0a 0a 3c 70 3e 57 72 69 74 65 72 73 20 6d  p>..<p>Writers m
1c90: 65 72 65 6c 79 20 61 70 70 65 6e 64 20 6e 65 77  erely append new
1ca0: 20 63 6f 6e 74 65 6e 74 20 74 6f 20 74 68 65 20   content to the 
1cb0: 65 6e 64 20 6f 66 20 74 68 65 20 57 41 4c 20 66  end of the WAL f
1cc0: 69 6c 65 2e 0a 42 65 63 61 75 73 65 20 77 72 69  ile..Because wri
1cd0: 74 65 72 73 20 64 6f 20 6e 6f 74 68 69 6e 67 20  ters do nothing 
1ce0: 74 68 61 74 20 77 6f 75 6c 64 20 69 6e 74 65 72  that would inter
1cf0: 66 65 72 65 20 77 69 74 68 20 74 68 65 20 61 63  fere with the ac
1d00: 74 69 6f 6e 73 20 6f 66 0a 72 65 61 64 65 72 73  tions of.readers
1d10: 2c 20 77 72 69 74 65 72 73 20 61 6e 64 20 72 65  , writers and re
1d20: 61 64 65 72 73 20 63 61 6e 20 72 75 6e 20 61 74  aders can run at
1d30: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
1d40: 20 48 6f 77 65 76 65 72 2c 0a 73 69 6e 63 65 20   However,.since 
1d50: 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 6f 6e  there is only on
1d60: 65 20 57 41 4c 20 66 69 6c 65 2c 20 74 68 65 72  e WAL file, ther
1d70: 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 6f 6e  e can only be on
1d80: 65 20 77 72 69 74 65 72 20 61 74 0a 61 20 74 69  e writer at.a ti
1d90: 6d 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 41 20 63 68  me.</p>..<p>A ch
1da0: 65 63 6b 70 6f 69 6e 74 20 6f 70 65 72 61 74 69  eckpoint operati
1db0: 6f 6e 20 74 61 6b 65 73 20 63 6f 6e 74 65 6e 74  on takes content
1dc0: 20 66 72 6f 6d 20 74 68 65 20 57 41 4c 20 66 69   from the WAL fi
1dd0: 6c 65 0a 61 6e 64 20 74 72 61 6e 73 66 65 72 73  le.and transfers
1de0: 20 69 74 20 62 61 63 6b 20 69 6e 74 6f 20 74 68   it back into th
1df0: 65 20 6f 72 69 67 69 6e 61 6c 20 64 61 74 61 62  e original datab
1e00: 61 73 65 20 66 69 6c 65 2e 0a 41 20 63 68 65 63  ase file..A chec
1e10: 6b 70 6f 69 6e 74 20 63 61 6e 20 72 75 6e 20 63  kpoint can run c
1e20: 6f 6e 63 75 72 72 65 6e 74 6c 79 20 77 69 74 68  oncurrently with
1e30: 20 72 65 61 64 65 72 73 2c 20 68 6f 77 65 76 65   readers, howeve
1e40: 72 20 74 68 65 20 63 68 65 63 6b 70 6f 69 6e 74  r the checkpoint
1e50: 0a 6d 75 73 74 20 73 74 6f 70 20 77 68 65 6e 20  .must stop when 
1e60: 69 74 20 72 65 61 63 68 65 73 20 61 20 70 61 67  it reaches a pag
1e70: 65 20 69 6e 20 74 68 65 20 57 41 4c 20 74 68 61  e in the WAL tha
1e80: 74 20 69 73 20 70 61 73 74 20 74 68 65 20 65 6e  t is past the en
1e90: 64 20 6d 61 72 6b 0a 6f 66 20 61 6e 79 20 63 75  d mark.of any cu
1ea0: 72 72 65 6e 74 20 72 65 61 64 65 72 2e 20 20 54  rrent reader.  T
1eb0: 68 65 20 63 68 65 63 6b 70 6f 69 6e 74 20 68 61  he checkpoint ha
1ec0: 73 20 74 6f 20 73 74 6f 70 20 61 74 20 74 68 61  s to stop at tha
1ed0: 74 20 70 6f 69 6e 74 20 62 65 63 61 75 73 65 0a  t point because.
1ee0: 6f 74 68 65 72 77 69 73 65 20 69 74 20 6d 69 67  otherwise it mig
1ef0: 68 74 20 6f 76 65 72 77 72 69 74 65 20 70 61 72  ht overwrite par
1f00: 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
1f10: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
1f20: 72 65 61 64 65 72 0a 69 73 20 61 63 74 69 76 65  reader.is active
1f30: 6c 79 20 75 73 69 6e 67 2e 20 20 54 68 65 20 63  ly using.  The c
1f40: 68 65 63 6b 70 6f 69 6e 74 20 72 65 6d 65 6d 62  heckpoint rememb
1f50: 65 72 73 20 28 69 6e 20 74 68 65 20 77 61 6c 2d  ers (in the wal-
1f60: 69 6e 64 65 78 29 20 68 6f 77 20 66 61 72 0a 69  index) how far.i
1f70: 74 20 67 6f 74 20 61 6e 64 20 77 69 6c 6c 20 72  t got and will r
1f80: 65 73 75 6d 65 20 74 72 61 6e 73 66 65 72 72 69  esume transferri
1f90: 6e 67 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20  ng content from 
1fa0: 74 68 65 20 57 41 4c 20 74 6f 20 74 68 65 20 64  the WAL to the d
1fb0: 61 74 61 62 61 73 65 0a 66 72 6f 6d 20 77 68 65  atabase.from whe
1fc0: 72 65 20 69 74 20 6c 65 66 74 20 6f 66 66 20 6f  re it left off o
1fd0: 6e 20 74 68 65 20 6e 65 78 74 20 69 6e 76 6f 63  n the next invoc
1fe0: 61 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54  ation.</p>..<p>T
1ff0: 68 75 73 20 61 20 6c 6f 6e 67 2d 72 75 6e 6e 69  hus a long-runni
2000: 6e 67 20 72 65 61 64 20 74 72 61 6e 73 61 63 74  ng read transact
2010: 69 6f 6e 20 63 61 6e 20 70 72 65 76 65 6e 74 20  ion can prevent 
2020: 61 20 63 68 65 63 6b 70 6f 69 6e 74 65 72 20 66  a checkpointer f
2030: 72 6f 6d 0a 6d 61 6b 69 6e 67 20 70 72 6f 67 72  rom.making progr
2040: 65 73 73 2e 20 20 42 75 74 20 70 72 65 73 75 6d  ess.  But presum
2050: 61 62 6c 79 20 65 76 65 72 79 20 72 65 61 64 20  ably every read 
2060: 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c  transaction will
2070: 20 65 76 65 6e 74 75 61 6c 6c 79 0a 65 6e 64 20   eventually.end 
2080: 61 6e 64 20 74 68 65 20 63 68 65 63 6b 70 6f 69  and the checkpoi
2090: 6e 74 65 72 20 77 69 6c 6c 20 62 65 20 61 62 6c  nter will be abl
20a0: 65 20 74 6f 20 63 6f 6e 74 69 6e 75 65 2e 3c 2f  e to continue.</
20b0: 70 3e 0a 0a 3c 70 3e 57 68 65 6e 65 76 65 72 20  p>..<p>Whenever 
20c0: 61 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  a write operatio
20d0: 6e 20 6f 63 63 75 72 73 2c 20 74 68 65 20 77 72  n occurs, the wr
20e0: 69 74 65 72 20 63 68 65 63 6b 73 20 68 6f 77 20  iter checks how 
20f0: 6d 75 63 68 20 70 72 6f 67 72 65 73 73 0a 74 68  much progress.th
2100: 65 20 63 68 65 63 6b 70 6f 69 6e 74 65 72 20 68  e checkpointer h
2110: 61 73 20 6d 61 64 65 2c 20 61 6e 64 20 69 66 20  as made, and if 
2120: 74 68 65 20 65 6e 74 69 72 65 20 57 41 4c 20 68  the entire WAL h
2130: 61 73 20 62 65 65 6e 20 74 72 61 6e 73 66 65 72  as been transfer
2140: 72 65 64 20 69 6e 74 6f 0a 74 68 65 20 64 61 74  red into.the dat
2150: 61 62 61 73 65 20 61 6e 64 20 73 79 6e 63 65 64  abase and synced
2160: 20 61 6e 64 20 69 66 20 6e 6f 20 72 65 61 64 65   and if no reade
2170: 72 73 20 61 72 65 20 6d 61 6b 69 6e 67 20 75 73  rs are making us
2180: 65 20 6f 66 20 74 68 65 20 57 41 4c 2c 20 74 68  e of the WAL, th
2190: 65 6e 0a 74 68 65 20 77 72 69 74 65 72 20 77 69  en.the writer wi
21a0: 6c 6c 20 72 65 77 69 6e 64 20 74 68 65 20 57 41  ll rewind the WA
21b0: 4c 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  L back to the be
21c0: 67 69 6e 6e 69 6e 67 20 61 6e 64 20 73 74 61 72  ginning and star
21d0: 74 20 70 75 74 74 69 6e 67 20 6e 65 77 0a 74 72  t putting new.tr
21e0: 61 6e 73 61 63 74 69 6f 6e 73 20 61 74 20 74 68  ansactions at th
21f0: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 74  e beginning of t
2200: 68 65 20 57 41 4c 2e 20 20 54 68 69 73 20 6d 65  he WAL.  This me
2210: 63 68 61 6e 69 73 6d 20 70 72 65 76 65 6e 74 73  chanism prevents
2220: 20 61 20 57 41 4c 0a 66 69 6c 65 20 66 72 6f 6d   a WAL.file from
2230: 20 67 72 6f 77 69 6e 67 20 77 69 74 68 6f 75 74   growing without
2240: 20 62 6f 75 6e 64 2e 3c 2f 70 3e 0a 0a 3c 74 63   bound.</p>..<tc
2250: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 66 61  l>hd_fragment fa
2260: 73 74 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 50 65 72  st</tcl>.<h2>Per
2270: 66 6f 72 6d 61 6e 63 65 20 43 6f 6e 73 69 64 65  formance Conside
2280: 72 61 74 69 6f 6e 73 3c 2f 68 32 3e 0a 0a 3c 70  rations</h2>..<p
2290: 3e 57 72 69 74 65 20 74 72 61 6e 73 61 63 74 69  >Write transacti
22a0: 6f 6e 73 20 61 72 65 20 76 65 72 79 20 66 61 73  ons are very fas
22b0: 74 20 73 69 6e 63 65 20 74 68 65 79 20 6f 6e 6c  t since they onl
22c0: 79 20 69 6e 76 6f 6c 76 65 20 77 72 69 74 69 6e  y involve writin
22d0: 67 0a 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 6e  g.the content on
22e0: 63 65 20 28 76 65 72 73 75 73 20 74 77 69 63 65  ce (versus twice
22f0: 20 66 6f 72 20 72 6f 6c 6c 62 61 63 6b 2d 6a 6f   for rollback-jo
2300: 75 72 6e 61 6c 20 74 72 61 6e 73 61 63 74 69 6f  urnal transactio
2310: 6e 73 29 0a 61 6e 64 20 62 65 63 61 75 73 65 20  ns).and because 
2320: 74 68 65 20 77 72 69 74 65 73 20 61 72 65 20 61  the writes are a
2330: 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c 2e 20 20  ll sequential.  
2340: 46 75 72 74 68 65 72 2c 20 73 79 6e 63 69 6e 67  Further, syncing
2350: 20 74 68 65 0a 63 6f 6e 74 65 6e 74 20 74 6f 20   the.content to 
2360: 74 68 65 20 64 69 73 6b 20 69 73 20 6e 6f 74 20  the disk is not 
2370: 72 65 71 75 69 72 65 64 2c 20 61 73 20 6c 6f 6e  required, as lon
2380: 67 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  g as the applica
2390: 74 69 6f 6e 20 69 73 0a 77 69 6c 6c 69 6e 67 20  tion is.willing 
23a0: 74 6f 20 73 61 63 72 69 66 69 63 65 20 64 75 72  to sacrifice dur
23b0: 61 62 69 6c 69 74 79 20 66 6f 6c 6c 6f 77 69 6e  ability followin
23c0: 67 20 61 20 70 6f 77 65 72 20 6c 6f 73 73 20 6f  g a power loss o
23d0: 72 20 68 61 72 64 20 72 65 62 6f 6f 74 2e 0a 28  r hard reboot..(
23e0: 57 72 69 74 65 72 73 20 73 79 6e 63 20 74 68 65  Writers sync the
23f0: 20 57 41 4c 20 6f 6e 20 65 76 65 72 79 20 74 72   WAL on every tr
2400: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74  ansaction commit
2410: 20 69 66 0a 5b 50 52 41 47 4d 41 20 73 79 6e 63   if.[PRAGMA sync
2420: 68 72 6f 6e 6f 75 73 5d 20 69 73 20 73 65 74 20  hronous] is set 
2430: 74 6f 20 46 55 4c 4c 20 62 75 74 20 6f 6d 69 74  to FULL but omit
2440: 20 74 68 69 73 20 73 79 6e 63 20 69 66 0a 5b 50   this sync if.[P
2450: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
2460: 73 5d 20 69 73 20 73 65 74 20 74 6f 20 4e 4f 52  s] is set to NOR
2470: 4d 41 4c 2e 29 3c 2f 70 3e 0a 0a 3c 70 3e 4f 6e  MAL.)</p>..<p>On
2480: 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
2490: 20 72 65 61 64 20 70 65 72 66 6f 72 6d 61 6e 63   read performanc
24a0: 65 20 64 65 74 65 72 69 6f 72 61 74 65 73 20 61  e deteriorates a
24b0: 73 20 74 68 65 20 57 41 4c 20 66 69 6c 65 0a 67  s the WAL file.g
24c0: 72 6f 77 73 20 69 6e 20 73 69 7a 65 20 73 69 6e  rows in size sin
24d0: 63 65 20 65 61 63 68 20 72 65 61 64 65 72 20 6d  ce each reader m
24e0: 75 73 74 20 63 68 65 63 6b 20 74 68 65 20 57 41  ust check the WA
24f0: 4c 20 66 69 6c 65 20 66 6f 72 20 74 68 65 20 63  L file for the c
2500: 6f 6e 74 65 6e 74 0a 61 6e 64 20 74 68 65 20 74  ontent.and the t
2510: 69 6d 65 20 6e 65 65 64 65 64 20 74 6f 20 63 68  ime needed to ch
2520: 65 63 6b 20 74 68 65 20 57 41 4c 20 66 69 6c 65  eck the WAL file
2530: 20 69 73 20 70 72 6f 70 6f 72 74 69 6f 6e 61 6c   is proportional
2540: 0a 74 6f 20 74 68 65 20 73 69 7a 65 20 6f 66 20  .to the size of 
2550: 74 68 65 20 57 41 4c 20 66 69 6c 65 2e 20 20 54  the WAL file.  T
2560: 68 65 20 77 61 6c 2d 69 6e 64 65 78 20 68 65 6c  he wal-index hel
2570: 70 73 20 66 69 6e 64 20 63 6f 6e 74 65 6e 74 0a  ps find content.
2580: 69 6e 20 74 68 65 20 57 41 4c 20 66 69 6c 65 20  in the WAL file 
2590: 6d 75 63 68 20 66 61 73 74 65 72 2c 20 62 75 74  much faster, but
25a0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 73 74 69   performance sti
25b0: 6c 6c 20 66 61 6c 6c 73 20 6f 66 66 20 77 69 74  ll falls off wit
25c0: 68 0a 69 6e 63 72 65 61 73 69 6e 67 20 57 41 4c  h.increasing WAL
25d0: 20 66 69 6c 65 20 73 69 7a 65 2e 20 20 48 65 6e   file size.  Hen
25e0: 63 65 2c 20 74 6f 20 6d 61 69 6e 74 61 69 6e 20  ce, to maintain 
25f0: 67 6f 6f 64 20 72 65 61 64 20 70 65 72 66 6f 72  good read perfor
2600: 6d 61 6e 63 65 20 0a 69 74 20 69 73 20 69 6d 70  mance .it is imp
2610: 6f 72 74 61 6e 74 20 74 6f 20 6b 65 65 70 20 74  ortant to keep t
2620: 68 65 20 57 41 4c 20 66 69 6c 65 20 73 69 7a 65  he WAL file size
2630: 20 64 6f 77 6e 20 62 79 0a 72 75 6e 6e 69 6e 67   down by.running
2640: 20 63 68 65 63 6b 70 6f 69 6e 74 73 20 61 74 20   checkpoints at 
2650: 72 65 67 75 6c 61 72 20 69 6e 74 65 72 76 61 6c  regular interval
2660: 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 43 68 65 63 6b  s.</p>..<p>Check
2670: 70 6f 69 6e 74 69 6e 67 20 64 6f 65 73 20 72 65  pointing does re
2680: 71 75 69 72 65 20 73 79 6e 63 20 6f 70 65 72 61  quire sync opera
2690: 74 69 6f 6e 73 20 69 6e 20 6f 72 64 65 72 20 74  tions in order t
26a0: 6f 20 61 76 6f 69 64 0a 74 68 65 20 70 6f 73 73  o avoid.the poss
26b0: 69 62 69 6c 69 74 79 20 6f 66 20 64 61 74 61 62  ibility of datab
26c0: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 66  ase corruption f
26d0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 70 6f 77 65 72  ollowing a power
26e0: 20 6c 6f 73 73 0a 6f 72 20 68 61 72 64 20 72 65   loss.or hard re
26f0: 62 6f 6f 74 2e 20 20 54 68 65 20 57 41 4c 20 6d  boot.  The WAL m
2700: 75 73 74 20 62 65 20 73 79 6e 63 65 64 20 74 6f  ust be synced to
2710: 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72   persistent stor
2720: 61 67 65 0a 70 72 69 6f 72 20 74 6f 20 6d 6f 76  age.prior to mov
2730: 69 6e 67 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d  ing content from
2740: 20 74 68 65 20 57 41 4c 20 69 6e 74 6f 20 74 68   the WAL into th
2750: 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
2760: 68 65 0a 64 61 74 61 62 61 73 65 20 66 69 6c 65  he.database file
2770: 20 6d 75 73 74 20 62 79 20 73 79 6e 63 65 64 20   must by synced 
2780: 70 72 69 6f 72 20 74 6f 20 72 65 73 65 74 74 69  prior to resetti
2790: 6e 67 20 74 68 65 20 57 41 4c 2e 0a 43 68 65 63  ng the WAL..Chec
27a0: 6b 70 6f 69 6e 74 20 61 6c 73 6f 20 72 65 71 75  kpoint also requ
27b0: 69 72 65 73 20 6d 6f 72 65 20 73 65 65 6b 69 6e  ires more seekin
27c0: 67 2e 0a 54 68 65 20 63 68 65 63 6b 70 6f 69 6e  g..The checkpoin
27d0: 74 65 72 20 6d 61 6b 65 73 20 61 6e 20 65 66 66  ter makes an eff
27e0: 6f 72 74 20 74 6f 0a 64 6f 20 61 73 20 6d 61 6e  ort to.do as man
27f0: 79 20 73 65 71 75 65 6e 74 69 61 6c 20 70 61 67  y sequential pag
2800: 65 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  e writes to the 
2810: 64 61 74 61 62 61 73 65 20 61 73 20 69 74 20 63  database as it c
2820: 61 6e 20 28 74 68 65 20 70 61 67 65 73 0a 61 72  an (the pages.ar
2830: 65 20 74 72 61 6e 73 66 65 72 72 65 64 20 66 72  e transferred fr
2840: 6f 6d 20 57 41 4c 20 74 6f 20 64 61 74 61 62 61  om WAL to databa
2850: 73 65 20 69 6e 20 61 73 63 65 6e 64 69 6e 67 20  se in ascending 
2860: 6f 72 64 65 72 29 20 62 75 74 20 65 76 65 6e 0a  order) but even.
2870: 74 68 65 6e 20 74 68 65 72 65 20 77 69 6c 6c 20  then there will 
2880: 74 79 70 69 63 61 6c 6c 79 20 62 65 20 6d 61 6e  typically be man
2890: 79 20 73 65 65 6b 20 6f 70 65 72 61 74 69 6f 6e  y seek operation
28a0: 73 20 69 6e 74 65 72 73 70 65 72 73 65 64 20 61  s interspersed a
28b0: 6d 6f 6e 67 0a 74 68 65 20 70 61 67 65 20 77 72  mong.the page wr
28c0: 69 74 65 73 2e 20 20 54 68 65 73 65 20 66 61 63  ites.  These fac
28d0: 74 6f 72 73 20 63 6f 6d 62 69 6e 65 20 74 6f 20  tors combine to 
28e0: 6d 61 6b 65 20 63 68 65 63 6b 70 6f 69 6e 74 73  make checkpoints
28f0: 20 73 6c 6f 77 65 72 20 74 68 61 6e 0a 77 72 69   slower than.wri
2900: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e  te transactions.
2910: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 64 65 66  </p>..<p>The def
2920: 61 75 6c 74 20 73 74 72 61 74 65 67 79 20 69 73  ault strategy is
2930: 20 74 6f 20 61 6c 6c 6f 77 20 73 75 63 63 65 73   to allow succes
2940: 73 69 76 65 20 77 72 69 74 65 20 74 72 61 6e 73  sive write trans
2950: 61 63 74 69 6f 6e 73 20 74 6f 0a 67 72 6f 77 20  actions to.grow 
2960: 74 68 65 20 57 41 4c 20 75 6e 74 69 6c 20 74 68  the WAL until th
2970: 65 20 57 41 4c 20 62 65 63 6f 6d 65 73 20 61 62  e WAL becomes ab
2980: 6f 75 74 20 31 30 30 30 20 70 61 67 65 73 20 69  out 1000 pages i
2990: 6e 20 73 69 7a 65 2c 20 74 68 65 6e 20 74 6f 0a  n size, then to.
29a0: 72 75 6e 20 61 20 63 68 65 63 6b 70 6f 69 6e 74  run a checkpoint
29b0: 20 6f 70 65 72 61 74 69 6f 6e 20 66 6f 72 20 65   operation for e
29c0: 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 43  ach subsequent C
29d0: 4f 4d 4d 49 54 20 75 6e 74 69 6c 20 74 68 65 20  OMMIT until the 
29e0: 57 41 4c 0a 69 73 20 72 65 73 65 74 20 74 6f 20  WAL.is reset to 
29f0: 62 65 20 73 6d 61 6c 6c 65 72 20 74 68 61 6e 20  be smaller than 
2a00: 31 30 30 30 20 70 61 67 65 73 2e 20 20 42 79 20  1000 pages.  By 
2a10: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 63 68 65  default, the che
2a20: 63 6b 70 6f 69 6e 74 20 77 69 6c 6c 20 62 65 0a  ckpoint will be.
2a30: 72 75 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  run automaticall
2a40: 79 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68  y by the same th
2a50: 72 65 61 64 20 74 68 61 74 20 64 6f 65 73 20 74  read that does t
2a60: 68 65 20 43 4f 4d 4d 49 54 20 74 68 61 74 20 70  he COMMIT that p
2a70: 75 73 68 65 73 0a 74 68 65 20 57 41 4c 20 6f 76  ushes.the WAL ov
2a80: 65 72 20 69 74 73 20 73 69 7a 65 20 6c 69 6d 69  er its size limi
2a90: 74 2e 20 20 54 68 69 73 20 68 61 73 20 74 68 65  t.  This has the
2aa0: 20 65 66 66 65 63 74 20 6f 66 20 63 61 75 73 69   effect of causi
2ab0: 6e 67 20 6d 6f 73 74 0a 43 4f 4d 4d 49 54 20 6f  ng most.COMMIT o
2ac0: 70 65 72 61 74 69 6f 6e 73 20 74 6f 20 62 65 20  perations to be 
2ad0: 76 65 72 79 20 66 61 73 74 20 62 75 74 20 61 6e  very fast but an
2ae0: 20 6f 63 63 61 73 69 6f 6e 61 6c 20 43 4f 4d 4d   occasional COMM
2af0: 49 54 20 28 74 68 6f 73 65 20 74 68 61 74 20 74  IT (those that t
2b00: 72 69 67 67 65 72 0a 61 20 63 68 65 63 6b 70 6f  rigger.a checkpo
2b10: 69 6e 74 29 20 74 6f 20 62 65 20 6d 75 63 68 20  int) to be much 
2b20: 73 6c 6f 77 65 72 2e 20 20 49 66 20 74 68 61 74  slower.  If that
2b30: 20 65 66 66 65 63 74 20 69 73 20 75 6e 64 65 73   effect is undes
2b40: 69 72 61 62 6c 65 2c 20 74 68 65 6e 0a 74 68 65  irable, then.the
2b50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
2b60: 20 64 69 73 61 62 6c 65 20 61 75 74 6f 6d 61 74   disable automat
2b70: 69 63 20 63 68 65 63 6b 70 6f 69 6e 74 69 6e 67  ic checkpointing
2b80: 20 61 6e 64 20 72 75 6e 20 74 68 65 0a 70 65 72   and run the.per
2b90: 69 6f 64 69 63 20 63 68 65 63 6b 70 6f 69 6e 74  iodic checkpoint
2ba0: 73 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 20  s in a separate 
2bb0: 74 68 72 65 61 64 2c 20 6f 72 20 73 65 70 61 72  thread, or separ
2bc0: 61 74 65 20 70 72 6f 63 65 73 73 2e 0a 28 4c 69  ate process..(Li
2bd0: 6e 6b 73 20 74 6f 20 63 6f 6d 6d 61 6e 64 73 20  nks to commands 
2be0: 61 6e 64 20 69 6e 74 65 72 66 61 63 65 73 20 74  and interfaces t
2bf0: 6f 20 61 63 63 6f 6d 70 6c 69 73 68 20 74 68 69  o accomplish thi
2c00: 73 20 61 72 65 0a 3c 61 20 68 72 65 66 3d 22 23  s are.<a href="#
2c10: 68 6f 77 5f 74 6f 5f 63 68 65 63 6b 70 6f 69 6e  how_to_checkpoin
2c20: 74 22 3e 73 68 6f 77 6e 20 62 65 6c 6f 77 3c 2f  t">shown below</
2c30: 61 3e 2e 29 3c 2f 70 3e 0a 0a 0a 3c 70 3e 4e 6f  a>.)</p>...<p>No
2c40: 74 65 20 74 68 61 74 20 77 69 74 68 20 5b 50 52  te that with [PR
2c50: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
2c60: 5d 20 73 65 74 20 74 6f 20 4e 4f 52 4d 41 4c 2c  ] set to NORMAL,
2c70: 20 74 68 65 20 63 68 65 63 6b 70 6f 69 6e 74 0a   the checkpoint.
2c80: 69 73 20 74 68 65 20 6f 6e 6c 79 20 6f 70 65 72  is the only oper
2c90: 61 74 69 6f 6e 20 74 6f 20 69 73 73 75 65 20 61  ation to issue a
2ca0: 6e 20 49 2f 4f 20 62 61 72 72 69 65 72 20 6f 72  n I/O barrier or
2cb0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 0a   sync operation.
2cc0: 28 66 73 79 6e 63 28 29 20 6f 6e 20 75 6e 69 78  (fsync() on unix
2cd0: 20 6f 72 20 46 6c 75 73 68 46 69 6c 65 42 75 66   or FlushFileBuf
2ce0: 66 65 72 73 28 29 20 6f 6e 20 77 69 6e 64 6f 77  fers() on window
2cf0: 73 29 2e 20 20 49 66 20 61 6e 20 61 70 70 6c 69  s).  If an appli
2d00: 63 61 74 69 6f 6e 0a 74 68 65 72 65 66 6f 72 65  cation.therefore
2d10: 20 72 75 6e 73 20 63 68 65 63 6b 70 6f 69 6e 74   runs checkpoint
2d20: 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   in a separate t
2d30: 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73  hread or process
2d40: 2c 20 74 68 65 20 6d 61 69 6e 0a 74 68 72 65 61  , the main.threa
2d50: 64 20 6f 72 20 70 72 6f 63 65 73 73 20 74 68 61  d or process tha
2d60: 74 20 69 73 20 64 6f 69 6e 67 20 64 61 74 61 62  t is doing datab
2d70: 61 73 65 20 71 75 65 72 69 65 73 20 61 6e 64 20  ase queries and 
2d80: 75 70 64 61 74 65 73 20 77 69 6c 6c 20 6e 65 76  updates will nev
2d90: 65 72 0a 62 6c 6f 63 6b 20 6f 6e 20 61 20 73 79  er.block on a sy
2da0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 54  nc operation.  T
2db0: 68 69 73 20 68 65 6c 70 73 20 74 6f 20 70 72 65  his helps to pre
2dc0: 76 65 6e 74 20 22 6c 61 74 63 68 2d 75 70 22 20  vent "latch-up" 
2dd0: 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  in applications.
2de0: 72 75 6e 6e 69 6e 67 20 6f 6e 20 61 20 62 75 73  running on a bus
2df0: 79 20 64 69 73 6b 20 64 72 69 76 65 2e 20 20 54  y disk drive.  T
2e00: 68 65 20 64 6f 77 6e 73 69 64 65 20 74 6f 0a 74  he downside to.t
2e10: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
2e20: 6e 20 69 73 20 74 68 61 74 20 74 72 61 6e 73 61  n is that transa
2e30: 63 74 69 6f 6e 73 20 61 72 65 20 6e 6f 20 6c 6f  ctions are no lo
2e40: 6e 67 65 72 20 64 75 72 61 62 6c 65 20 61 6e 64  nger durable and
2e50: 0a 6d 69 67 68 74 20 72 6f 6c 6c 62 61 63 6b 20  .might rollback 
2e60: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 70 6f 77 65  following a powe
2e70: 72 20 66 61 69 6c 75 72 65 20 6f 72 20 68 61 72  r failure or har
2e80: 64 20 72 65 73 65 74 2e 3c 2f 70 3e 0a 0a 0a 3c  d reset.</p>...<
2e90: 70 3e 4e 6f 74 69 63 65 20 74 6f 6f 20 74 68 61  p>Notice too tha
2ea0: 74 20 74 68 65 72 65 20 69 73 20 61 20 74 72 61  t there is a tra
2eb0: 64 65 6f 66 66 20 62 65 74 77 65 65 6e 20 61 76  deoff between av
2ec0: 65 72 61 67 65 20 72 65 61 64 20 70 65 72 66 6f  erage read perfo
2ed0: 72 6d 61 6e 63 65 0a 61 6e 64 20 61 76 65 72 61  rmance.and avera
2ee0: 67 65 20 77 72 69 74 65 20 70 65 72 66 6f 72 6d  ge write perform
2ef0: 61 6e 63 65 2e 20 20 54 6f 20 6d 61 78 69 6d 69  ance.  To maximi
2f00: 7a 65 20 74 68 65 20 72 65 61 64 20 70 65 72 66  ze the read perf
2f10: 6f 72 6d 61 6e 63 65 2c 0a 6f 6e 65 20 77 61 6e  ormance,.one wan
2f20: 74 73 20 74 6f 20 6b 65 65 70 20 74 68 65 20 57  ts to keep the W
2f30: 41 4c 20 61 73 20 73 6d 61 6c 6c 20 61 73 20 70  AL as small as p
2f40: 6f 73 73 69 62 6c 65 20 61 6e 64 20 68 65 6e 63  ossible and henc
2f50: 65 20 72 75 6e 20 63 68 65 63 6b 70 6f 69 6e 74  e run checkpoint
2f60: 73 0a 66 72 65 71 75 65 6e 74 6c 79 2c 20 70 65  s.frequently, pe
2f70: 72 68 61 70 73 20 61 73 20 6f 66 74 65 6e 20 61  rhaps as often a
2f80: 73 20 65 76 65 72 79 20 43 4f 4d 4d 49 54 2e 20  s every COMMIT. 
2f90: 20 54 6f 20 6d 61 78 69 6d 69 7a 65 0a 77 72 69   To maximize.wri
2fa0: 74 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 2c 20  te performance, 
2fb0: 6f 6e 65 20 77 61 6e 74 73 20 74 6f 20 61 6d 6f  one wants to amo
2fc0: 72 74 69 7a 65 20 74 68 65 20 63 6f 73 74 20 6f  rtize the cost o
2fd0: 66 20 65 61 63 68 20 63 68 65 63 6b 70 6f 69 6e  f each checkpoin
2fe0: 74 0a 6f 76 65 72 20 61 73 20 6d 61 6e 79 20 77  t.over as many w
2ff0: 72 69 74 65 73 20 61 73 20 70 6f 73 73 69 62 6c  rites as possibl
3000: 65 2c 20 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  e, meaning that 
3010: 6f 6e 65 20 77 61 6e 74 73 20 74 6f 20 72 75 6e  one wants to run
3020: 20 63 68 65 63 6b 70 6f 69 6e 74 73 0a 69 6e 66   checkpoints.inf
3030: 72 65 71 75 65 6e 74 6c 79 20 61 6e 64 20 6c 65  requently and le
3040: 74 20 74 68 65 20 57 41 4c 20 67 72 6f 77 20 61  t the WAL grow a
3050: 73 20 6c 61 72 67 65 20 61 73 20 70 6f 73 73 69  s large as possi
3060: 62 6c 65 20 62 65 66 6f 72 65 20 65 61 63 68 20  ble before each 
3070: 0a 63 68 65 63 6b 70 6f 69 6e 74 2e 20 20 54 68  .checkpoint.  Th
3080: 65 20 64 65 63 69 73 69 6f 6e 20 6f 66 20 68 6f  e decision of ho
3090: 77 20 6f 66 74 65 6e 20 74 6f 20 72 75 6e 20 63  w often to run c
30a0: 68 65 63 6b 70 6f 69 6e 74 73 20 6d 61 79 20 74  heckpoints may t
30b0: 68 65 72 65 66 6f 72 65 0a 76 61 72 79 20 66 72  herefore.vary fr
30c0: 6f 6d 20 6f 6e 65 20 61 70 70 6c 69 63 61 74 69  om one applicati
30d0: 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 20 64 65  on to another de
30e0: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 72  pending on the r
30f0: 65 6c 61 74 69 76 65 20 72 65 61 64 0a 61 6e 64  elative read.and
3100: 20 77 72 69 74 65 20 70 65 72 66 6f 72 6d 61 6e   write performan
3110: 63 65 20 72 65 71 75 69 72 65 6d 65 6e 74 73 20  ce requirements 
3120: 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
3130: 6f 6e 2e 0a 54 68 65 20 64 65 66 61 75 6c 74 20  on..The default 
3140: 73 74 72 61 74 65 67 79 20 69 73 20 74 6f 20 72  strategy is to r
3150: 75 6e 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20  un a checkpoint 
3160: 6f 6e 63 65 20 74 68 65 20 57 41 4c 0a 72 65 61  once the WAL.rea
3170: 63 68 65 73 20 31 30 30 30 20 70 61 67 65 73 20  ches 1000 pages 
3180: 61 6e 64 20 74 68 69 73 20 73 74 72 61 74 65 67  and this strateg
3190: 79 20 73 65 65 6d 73 20 74 6f 20 77 6f 72 6b 20  y seems to work 
31a0: 77 65 6c 6c 20 69 6e 20 74 65 73 74 20 61 70 70  well in test app
31b0: 6c 69 63 61 74 69 6f 6e 73 20 6f 6e 20 0a 77 6f  lications on .wo
31c0: 72 6b 73 74 61 74 69 6f 6e 73 2c 20 62 75 74 20  rkstations, but 
31d0: 6f 74 68 65 72 20 73 74 72 61 74 65 67 69 65 73  other strategies
31e0: 20 6d 69 67 68 74 20 77 6f 72 6b 20 62 65 74 74   might work bett
31f0: 65 72 20 6f 6e 20 64 69 66 66 65 72 65 6e 74 20  er on different 
3200: 0a 70 6c 61 74 66 6f 72 6d 73 20 6f 72 20 66 6f  .platforms or fo
3210: 72 20 64 69 66 66 65 72 65 6e 74 20 77 6f 72 6b  r different work
3220: 6c 6f 61 64 73 2e 3c 2f 70 3e 0a 0a 3c 68 31 3e  loads.</p>..<h1>
3230: 41 63 74 69 76 61 74 69 6e 67 20 41 6e 64 20 43  Activating And C
3240: 6f 6e 66 69 67 75 72 69 6e 67 20 57 41 4c 20 4d  onfiguring WAL M
3250: 6f 64 65 3c 2f 68 31 3e 0a 0a 3c 70 3e 41 6e 20  ode</h1>..<p>An 
3260: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
3270: 63 6f 6e 6e 65 63 74 69 6f 6e 20 64 65 66 61 75  connection defau
3280: 6c 74 73 20 74 6f 20 0a 5b 6a 6f 75 72 6e 61 6c  lts to .[journal
3290: 5f 6d 6f 64 65 20 7c 20 6a 6f 75 72 6e 61 6c 5f  _mode | journal_
32a0: 6d 6f 64 65 3d 44 45 4c 45 54 45 5d 2e 20 20 54  mode=DELETE].  T
32b0: 6f 20 63 6f 6e 76 65 72 74 20 74 6f 20 57 41 4c  o convert to WAL
32c0: 20 6d 6f 64 65 2c 20 75 73 65 20 74 68 65 0a 66   mode, use the.f
32d0: 6f 6c 6c 6f 77 69 6e 67 20 70 72 61 67 6d 61 3a  ollowing pragma:
32e0: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
32f0: 65 3e 3c 70 72 65 3e 0a 50 52 41 47 4d 41 20 6a  e><pre>.PRAGMA j
3300: 6f 75 72 6e 61 6c 5f 6d 6f 64 65 3d 57 41 4c 3b  ournal_mode=WAL;
3310: 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
3320: 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 6a 6f 75  ote>..<p>The jou
3330: 72 6e 61 6c 5f 6d 6f 64 65 20 70 72 61 67 6d 61  rnal_mode pragma
3340: 20 72 65 74 75 72 6e 73 20 61 20 73 74 72 69 6e   returns a strin
3350: 67 20 77 68 69 63 68 20 69 73 20 74 68 65 20 6e  g which is the n
3360: 65 77 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 2e  ew journal mode.
3370: 0a 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  .On success, the
3380: 20 70 72 61 67 6d 61 20 77 69 6c 6c 20 72 65 74   pragma will ret
3390: 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
33a0: 3c 74 74 3e 77 61 6c 3c 2f 74 74 3e 22 2e 20 20  <tt>wal</tt>".  
33b0: 49 66 20 0a 74 68 65 20 63 6f 6e 76 65 72 73 69  If .the conversi
33c0: 6f 6e 20 74 6f 20 57 41 4c 20 63 6f 75 6c 64 20  on to WAL could 
33d0: 6e 6f 74 20 62 65 20 63 6f 6d 70 6c 65 74 65 64  not be completed
33e0: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69   (for example, i
33f0: 66 20 74 68 65 20 5b 56 46 53 5d 0a 64 6f 65 73  f the [VFS].does
3400: 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65   not support the
3410: 20 6e 65 63 65 73 73 61 72 79 20 73 68 61 72 65   necessary share
3420: 64 2d 6d 65 6d 6f 72 79 20 70 72 69 6d 69 74 69  d-memory primiti
3430: 76 65 73 29 20 74 68 65 6e 20 74 68 65 0a 6a 6f  ves) then the.jo
3440: 75 72 6e 61 6c 69 6e 67 20 6d 6f 64 65 20 77 69  urnaling mode wi
3450: 6c 6c 20 62 65 20 75 6e 63 68 61 6e 67 65 64 20  ll be unchanged 
3460: 61 6e 64 20 74 68 65 20 73 74 72 69 6e 67 20 72  and the string r
3470: 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
3480: 0a 70 72 69 6d 69 74 69 76 65 20 77 69 6c 6c 20  .primitive will 
3490: 62 65 20 74 68 65 20 70 72 69 6f 72 20 6a 6f 75  be the prior jou
34a0: 72 6e 61 6c 69 6e 67 20 6d 6f 64 65 20 28 66 6f  rnaling mode (fo
34b0: 72 20 65 78 61 6d 70 6c 65 20 22 3c 74 74 3e 64  r example "<tt>d
34c0: 65 6c 65 74 65 3c 2f 74 74 3e 22 29 2e 0a 0a 3c  elete</tt>")...<
34d0: 61 20 6e 61 6d 65 3d 22 68 6f 77 5f 74 6f 5f 63  a name="how_to_c
34e0: 68 65 63 6b 70 6f 69 6e 74 22 3e 3c 2f 61 3e 0a  heckpoint"></a>.
34f0: 3c 68 32 3e 41 75 74 6f 6d 61 74 69 63 20 43 68  <h2>Automatic Ch
3500: 65 63 6b 70 6f 69 6e 74 3c 2f 68 32 3e 0a 0a 3c  eckpoint</h2>..<
3510: 70 3e 42 79 20 64 65 66 61 75 6c 74 2c 20 53 51  p>By default, SQ
3520: 4c 69 74 65 20 77 69 6c 6c 20 61 75 74 6f 6d 61  Lite will automa
3530: 74 69 63 61 6c 6c 79 20 63 68 65 63 6b 70 6f 69  tically checkpoi
3540: 6e 74 20 77 68 65 6e 65 76 65 72 20 61 20 5b 43  nt whenever a [C
3550: 4f 4d 4d 49 54 5d 0a 6f 63 63 75 72 73 20 74 68  OMMIT].occurs th
3560: 61 74 20 63 61 75 73 65 73 20 74 68 65 20 57 41  at causes the WA
3570: 4c 20 66 69 6c 65 20 74 6f 20 62 65 20 31 30 30  L file to be 100
3580: 30 20 70 61 67 65 73 20 6f 72 20 6d 6f 72 65 20  0 pages or more 
3590: 69 6e 20 73 69 7a 65 2c 20 6f 72 20 77 68 65 6e  in size, or when
35a0: 20 74 68 65 20 0a 6c 61 73 74 20 64 61 74 61 62   the .last datab
35b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
35c0: 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
35d0: 65 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 64  e closes.  The d
35e0: 65 66 61 75 6c 74 20 0a 63 6f 6e 66 69 67 75 72  efault .configur
35f0: 61 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65  ation is intende
3600: 64 20 74 6f 20 77 6f 72 6b 20 77 65 6c 6c 20 66  d to work well f
3610: 6f 72 20 6d 6f 73 74 20 61 70 70 6c 69 63 61 74  or most applicat
3620: 69 6f 6e 73 2e 0a 42 75 74 20 70 72 6f 67 72 61  ions..But progra
3630: 6d 73 20 74 68 61 74 20 77 61 6e 74 20 6d 6f 72  ms that want mor
3640: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 66 6f  e control can fo
3650: 72 63 65 20 61 20 63 68 65 63 6b 70 6f 69 6e 74  rce a checkpoint
3660: 0a 75 73 69 6e 67 20 74 68 65 20 5b 77 61 6c 5f  .using the [wal_
3670: 63 68 65 63 6b 70 6f 69 6e 74 20 70 72 61 67 6d  checkpoint pragm
3680: 61 5d 20 6f 72 20 62 79 20 63 61 6c 6c 69 6e 67  a] or by calling
3690: 20 74 68 65 0a 5b 73 71 6c 69 74 65 33 5f 77 61   the.[sqlite3_wa
36a0: 6c 5f 63 68 65 63 6b 70 6f 69 6e 74 28 29 5d 20  l_checkpoint()] 
36b0: 43 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  C interface.  Th
36c0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 68 65 63  e automatic chec
36d0: 6b 70 6f 69 6e 74 0a 74 68 72 65 73 68 6f 6c 64  kpoint.threshold
36e0: 20 63 61 6e 20 62 65 20 63 68 61 6e 67 65 64 20   can be changed 
36f0: 6f 72 20 61 75 74 6f 6d 61 74 69 63 20 63 68 65  or automatic che
3700: 63 6b 70 6f 69 6e 74 69 6e 67 20 63 61 6e 20 62  ckpointing can b
3710: 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 64 69 73  e completely.dis
3720: 61 62 6c 65 64 20 75 73 69 6e 67 20 74 68 65 20  abled using the 
3730: 5b 77 61 6c 5f 61 75 74 6f 63 68 65 63 6b 70 6f  [wal_autocheckpo
3740: 69 6e 74 20 70 72 61 67 6d 61 5d 20 6f 72 20 62  int pragma] or b
3750: 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 0a 5b 73  y calling the.[s
3760: 71 6c 69 74 65 33 5f 77 61 6c 5f 61 75 74 6f 63  qlite3_wal_autoc
3770: 68 65 63 6b 70 6f 69 6e 74 28 29 5d 20 43 20 69  heckpoint()] C i
3780: 6e 74 65 72 66 61 63 65 2e 20 20 41 20 70 72 6f  nterface.  A pro
3790: 67 72 61 6d 20 63 61 6e 20 61 6c 73 6f 20 0a 75  gram can also .u
37a0: 73 65 20 5b 73 71 6c 69 74 65 33 5f 77 61 6c 5f  se [sqlite3_wal_
37b0: 68 6f 6f 6b 28 29 5d 20 74 6f 20 72 65 67 69 73  hook()] to regis
37c0: 74 65 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 74  ter a callback t
37d0: 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
37e0: 6e 65 76 65 72 0a 61 6e 79 20 74 72 61 6e 73 61  never.any transa
37f0: 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 74 6f  ction commits to
3800: 20 74 68 65 20 57 41 4c 2e 20 20 54 68 69 73 20   the WAL.  This 
3810: 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 74 68 65  callback can the
3820: 6e 20 69 6e 76 6f 6b 65 0a 5b 73 71 6c 69 74 65  n invoke.[sqlite
3830: 33 5f 77 61 6c 5f 63 68 65 63 6b 70 6f 69 6e 74  3_wal_checkpoint
3840: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
3850: 77 61 6c 5f 63 68 65 63 6b 70 6f 69 6e 74 5f 76  wal_checkpoint_v
3860: 32 28 29 5d 20 62 61 73 65 64 20 6f 6e 20 77 68  2()] based on wh
3870: 61 74 65 76 65 72 0a 63 72 69 74 65 72 69 61 20  atever.criteria 
3880: 69 74 20 74 68 69 6e 6b 73 20 69 73 20 61 70 70  it thinks is app
3890: 72 6f 70 72 69 61 74 65 2e 20 20 28 54 68 65 20  ropriate.  (The 
38a0: 61 75 74 6f 6d 61 74 69 63 20 63 68 65 63 6b 70  automatic checkp
38b0: 6f 69 6e 74 20 6d 65 63 68 61 6e 69 73 6d 0a 69  oint mechanism.i
38c0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
38d0: 20 61 20 73 69 6d 70 6c 65 20 77 72 61 70 70 65   a simple wrappe
38e0: 72 20 61 72 6f 75 6e 64 20 5b 73 71 6c 69 74 65  r around [sqlite
38f0: 33 5f 77 61 6c 5f 68 6f 6f 6b 28 29 5d 2e 29 3c  3_wal_hook()].)<
3900: 2f 70 3e 0a 0a 3c 68 32 3e 41 70 70 6c 69 63 61  /p>..<h2>Applica
3910: 74 69 6f 6e 2d 49 6e 69 74 69 61 74 65 64 20 43  tion-Initiated C
3920: 68 65 63 6b 70 6f 69 6e 74 73 3c 2f 68 32 3e 0a  heckpoints</h2>.
3930: 0a 3c 70 3e 41 6e 20 61 70 70 6c 69 63 61 74 69  .<p>An applicati
3940: 6f 6e 20 63 61 6e 20 69 6e 69 74 69 61 74 65 20  on can initiate 
3950: 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 75 73 69  a checkpoint usi
3960: 6e 67 20 61 6e 79 20 77 72 69 74 61 62 6c 65 20  ng any writable 
3970: 64 61 74 61 62 61 73 65 0a 63 6f 6e 6e 65 63 74  database.connect
3980: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ion on the datab
3990: 61 73 65 20 73 69 6d 70 6c 79 20 62 79 20 69 6e  ase simply by in
39a0: 76 6f 6b 69 6e 67 0a 5b 73 71 6c 69 74 65 33 5f  voking.[sqlite3_
39b0: 77 61 6c 5f 63 68 65 63 6b 70 6f 69 6e 74 28 29  wal_checkpoint()
39c0: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 77 61  ] or [sqlite3_wa
39d0: 6c 5f 63 68 65 63 6b 70 6f 69 6e 74 5f 76 32 28  l_checkpoint_v2(
39e0: 29 5d 2e 0a 54 68 65 72 65 20 61 72 65 20 74 68  )]..There are th
39f0: 72 65 65 20 73 75 62 74 79 70 65 73 20 6f 66 20  ree subtypes of 
3a00: 63 68 65 63 6b 70 6f 69 6e 74 73 20 74 68 61 74  checkpoints that
3a10: 20 76 61 72 79 20 69 6e 20 74 68 65 69 72 20 61   vary in their a
3a20: 67 67 72 65 73 73 69 76 65 6e 65 73 73 3a 0a 50  ggressiveness:.P
3a30: 41 53 53 49 56 45 2c 20 46 55 4c 4c 2c 20 61 6e  ASSIVE, FULL, an
3a40: 64 20 52 45 53 54 41 52 54 2e 20 20 54 68 65 20  d RESTART.  The 
3a50: 64 65 66 61 75 6c 74 20 63 68 65 63 6b 70 6f 69  default checkpoi
3a60: 6e 74 20 73 74 79 6c 65 20 69 73 20 50 41 53 53  nt style is PASS
3a70: 49 56 45 2c 20 77 68 69 63 68 0a 64 6f 65 73 20  IVE, which.does 
3a80: 61 73 20 6d 75 63 68 20 77 6f 72 6b 20 61 73 20  as much work as 
3a90: 69 74 20 63 61 6e 20 77 69 74 68 6f 75 74 20 69  it can without i
3aa0: 6e 74 65 72 66 65 72 69 6e 67 20 77 69 74 68 20  nterfering with 
3ab0: 6f 74 68 65 72 20 64 61 74 61 62 61 73 65 0a 63  other database.c
3ac0: 6f 6e 6e 65 63 74 69 6f 6e 73 2c 20 61 6e 64 20  onnections, and 
3ad0: 77 68 69 63 68 20 6d 69 67 68 74 20 6e 6f 74 20  which might not 
3ae0: 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
3af0: 6e 20 69 66 20 74 68 65 72 65 20 61 72 65 0a 63  n if there are.c
3b00: 6f 6e 63 75 72 72 65 6e 74 20 72 65 61 64 65 72  oncurrent reader
3b10: 73 20 6f 72 20 77 72 69 74 65 72 73 2e 0a 41 6c  s or writers..Al
3b20: 6c 20 63 68 65 63 6b 70 6f 69 6e 74 73 20 69 6e  l checkpoints in
3b30: 69 74 69 61 74 65 64 20 62 79 20 5b 73 71 6c 69  itiated by [sqli
3b40: 74 65 33 5f 77 61 6c 5f 63 68 65 63 6b 70 6f 69  te3_wal_checkpoi
3b50: 6e 74 28 29 5d 20 61 6e 64 0a 62 79 20 74 68 65  nt()] and.by the
3b60: 20 61 75 74 6f 6d 61 74 69 63 20 63 68 65 63 6b   automatic check
3b70: 70 6f 69 6e 74 20 6d 65 63 68 61 6e 69 73 6d 20  point mechanism 
3b80: 61 72 65 20 50 41 53 53 49 56 45 2e 20 20 46 55  are PASSIVE.  FU
3b90: 4c 4c 20 61 6e 64 20 52 45 53 54 41 52 54 0a 63  LL and RESTART.c
3ba0: 68 65 63 6b 70 6f 69 6e 74 73 20 74 72 79 20 68  heckpoints try h
3bb0: 61 72 64 65 72 20 74 6f 20 72 75 6e 20 74 68 65  arder to run the
3bc0: 20 63 68 65 63 6b 70 6f 69 6e 74 20 74 6f 20 63   checkpoint to c
3bd0: 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 20 63 61  ompletion and ca
3be0: 6e 20 6f 6e 6c 79 0a 62 65 20 69 6e 69 74 69 61  n only.be initia
3bf0: 74 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f  ted by a call to
3c00: 20 5b 73 71 6c 69 74 65 33 5f 77 61 6c 5f 63 68   [sqlite3_wal_ch
3c10: 65 63 6b 70 6f 69 6e 74 5f 76 32 28 29 5d 2e 20  eckpoint_v2()]. 
3c20: 20 53 65 65 20 74 68 65 0a 5b 73 71 6c 69 74 65   See the.[sqlite
3c30: 33 5f 77 61 6c 5f 63 68 65 63 6b 70 6f 69 6e 74  3_wal_checkpoint
3c40: 5f 76 32 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61  _v2()] documenta
3c50: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
3c60: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  nal information.
3c70: 6f 6e 20 46 55 4c 4c 20 61 6e 64 20 52 45 53 45  on FULL and RESE
3c80: 54 20 63 68 65 63 6b 70 6f 69 6e 74 73 2e 0a 0a  T checkpoints...
3c90: 3c 68 32 3e 50 65 72 73 69 73 74 65 6e 63 65 20  <h2>Persistence 
3ca0: 6f 66 20 57 41 4c 20 6d 6f 64 65 3c 2f 68 32 3e  of WAL mode</h2>
3cb0: 0a 0a 3c 70 3e 55 6e 6c 69 6b 65 20 74 68 65 20  ..<p>Unlike the 
3cc0: 6f 74 68 65 72 20 6a 6f 75 72 6e 61 6c 69 6e 67  other journaling
3cd0: 20 6d 6f 64 65 73 2c 20 0a 5b 6a 6f 75 72 6e 61   modes, .[journa
3ce0: 6c 5f 6d 6f 64 65 20 7c 20 50 52 41 47 4d 41 20  l_mode | PRAGMA 
3cf0: 6a 6f 75 72 6e 61 6c 5f 6d 6f 64 65 3d 57 41 4c  journal_mode=WAL
3d00: 5d 20 69 73 0a 70 65 72 73 69 73 74 65 6e 74 2e  ] is.persistent.
3d10: 20 20 49 66 20 61 20 70 72 6f 63 65 73 73 20 73    If a process s
3d20: 65 74 73 20 57 41 4c 20 6d 6f 64 65 2c 20 74 68  ets WAL mode, th
3d30: 65 6e 20 63 6c 6f 73 65 73 20 61 6e 64 20 72 65  en closes and re
3d40: 6f 70 65 6e 73 20 74 68 65 0a 64 61 74 61 62 61  opens the.databa
3d50: 73 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  se, the database
3d60: 20 77 69 6c 6c 20 63 6f 6d 65 20 62 61 63 6b 20   will come back 
3d70: 69 6e 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 6e  in WAL mode.  In
3d80: 20 63 6f 6e 74 72 61 73 74 2c 20 69 66 0a 61 20   contrast, if.a 
3d90: 70 72 6f 63 65 73 73 20 73 65 74 73 20 28 66 6f  process sets (fo
3da0: 72 20 65 78 61 6d 70 6c 65 29 20 50 52 41 47 4d  r example) PRAGM
3db0: 41 20 6a 6f 75 72 6e 61 6c 5f 6d 6f 64 65 3d 54  A journal_mode=T
3dc0: 52 55 4e 43 41 54 45 20 61 6e 64 20 74 68 65 6e  RUNCATE and then
3dd0: 20 63 6c 6f 73 65 73 20 61 6e 64 0a 72 65 6f 70   closes and.reop
3de0: 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ens the database
3df0: 20 77 69 6c 6c 20 63 6f 6d 65 20 62 61 63 6b 20   will come back 
3e00: 75 70 20 69 6e 20 74 68 65 20 64 65 66 61 75 6c  up in the defaul
3e10: 74 20 72 6f 6c 6c 62 61 63 6b 20 6d 6f 64 65 20  t rollback mode 
3e20: 6f 66 0a 44 45 4c 45 54 45 20 72 61 74 68 65 72  of.DELETE rather
3e30: 20 74 68 61 6e 20 74 68 65 20 70 72 65 76 69 6f   than the previo
3e40: 75 73 20 54 52 55 4e 43 41 54 45 20 73 65 74 74  us TRUNCATE sett
3e50: 69 6e 67 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  ing.</p>..<p>The
3e60: 20 70 65 72 73 69 73 74 65 6e 63 65 20 6f 66 20   persistence of 
3e70: 57 41 4c 20 6d 6f 64 65 20 6d 65 61 6e 73 20 74  WAL mode means t
3e80: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
3e90: 20 63 61 6e 20 62 65 20 63 6f 6e 76 65 72 74 65   can be converte
3ea0: 64 0a 74 6f 20 75 73 69 6e 67 20 53 51 4c 69 74  d.to using SQLit
3eb0: 65 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20 77 69  e in WAL mode wi
3ec0: 74 68 6f 75 74 20 6d 61 6b 69 6e 67 20 61 6e 79  thout making any
3ed0: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
3ee0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 69 74 73 65  application.itse
3ef0: 6c 66 2e 20 20 4f 6e 65 20 68 61 73 20 6d 65 72  lf.  One has mer
3f00: 65 6c 79 20 74 6f 20 72 75 6e 20 22 3c 74 74 3e  ely to run "<tt>
3f10: 50 52 41 47 4d 41 20 6a 6f 75 72 6e 61 6c 5f 6d  PRAGMA journal_m
3f20: 6f 64 65 3d 57 41 4c 3b 3c 2f 74 74 3e 22 20 6f  ode=WAL;</tt>" o
3f30: 6e 20 74 68 65 0a 64 61 74 61 62 61 73 65 20 66  n the.database f
3f40: 69 6c 65 28 73 29 20 75 73 69 6e 67 20 74 68 65  ile(s) using the
3f50: 20 5b 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 73   [command-line s
3f60: 68 65 6c 6c 5d 20 6f 72 20 6f 74 68 65 72 20 75  hell] or other u
3f70: 74 69 6c 69 74 79 2c 20 74 68 65 6e 0a 72 65 73  tility, then.res
3f80: 74 61 72 74 20 74 68 65 20 61 70 70 6c 69 63 61  tart the applica
3f90: 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68  tion.</p>..<p>Th
3fa0: 65 20 57 41 4c 20 6a 6f 75 72 6e 61 6c 20 6d 6f  e WAL journal mo
3fb0: 64 65 20 77 69 6c 6c 20 62 65 20 73 65 74 20 6f  de will be set o
3fc0: 6e 20 61 6c 6c 0a 63 6f 6e 6e 65 63 74 69 6f 6e  n all.connection
3fd0: 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  s to the same da
3fe0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 66 20 69  tabase file if i
3ff0: 74 20 69 73 20 73 65 74 20 6f 6e 20 61 6e 79 20  t is set on any 
4000: 6f 6e 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  one connection..
4010: 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  </p>..<tcl>hd_fr
4020: 61 67 6d 65 6e 74 20 7b 77 61 6c 66 69 6c 65 7d  agment {walfile}
4030: 20 7b 57 41 4c 20 66 69 6c 65 7d 3c 2f 74 63 6c   {WAL file}</tcl
4040: 3e 0a 3c 68 31 3e 54 68 65 20 57 41 4c 20 46 69  >.<h1>The WAL Fi
4050: 6c 65 3c 2f 68 31 3e 0a 0a 3c 70 3e 57 68 69 6c  le</h1>..<p>Whil
4060: 65 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  e a [database co
4070: 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 6f 70 65  nnection] is ope
4080: 6e 20 6f 6e 20 61 20 57 41 4c 2d 6d 6f 64 65 20  n on a WAL-mode 
4090: 64 61 74 61 62 61 73 65 2c 20 53 51 4c 69 74 65  database, SQLite
40a0: 0a 6d 61 69 6e 74 61 69 6e 73 20 61 6e 20 65 78  .maintains an ex
40b0: 74 72 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  tra journal file
40c0: 20 63 61 6c 6c 65 64 20 61 20 22 57 72 69 74 65   called a "Write
40d0: 20 41 68 65 61 64 20 4c 6f 67 22 20 6f 72 20 22   Ahead Log" or "
40e0: 57 41 4c 20 46 69 6c 65 22 2e 0a 54 68 65 20 6e  WAL File"..The n
40f0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
4100: 20 6f 6e 20 64 69 73 6b 20 69 73 20 75 73 75 61   on disk is usua
4110: 6c 6c 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lly the name of 
4120: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4130: 65 0a 77 69 74 68 20 61 6e 20 65 78 74 72 61 20  e.with an extra 
4140: 22 3c 74 74 3e 2d 77 61 6c 3c 2f 74 74 3e 22 20  "<tt>-wal</tt>" 
4150: 73 75 66 66 69 78 2c 20 74 68 6f 75 67 68 20 64  suffix, though d
4160: 69 66 66 65 72 65 6e 74 20 6e 61 6d 69 6e 67 20  ifferent naming 
4170: 72 75 6c 65 73 20 6d 61 79 0a 61 70 70 6c 79 20  rules may.apply 
4180: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
4190: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
41a0: 54 45 5f 45 4e 41 42 4c 45 5f 38 5f 33 5f 4e 41  TE_ENABLE_8_3_NA
41b0: 4d 45 53 5d 2e 0a 0a 3c 70 3e 54 68 65 20 57 41  MES]...<p>The WA
41c0: 4c 20 66 69 6c 65 20 65 78 69 73 74 73 20 66 6f  L file exists fo
41d0: 72 20 61 73 20 6c 6f 6e 67 20 61 73 20 61 6e 79  r as long as any
41e0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
41f0: 63 74 69 6f 6e 5d 20 68 61 73 20 74 68 65 0a 64  ction] has the.d
4200: 61 74 61 62 61 73 65 20 6f 70 65 6e 2e 20 20 55  atabase open.  U
4210: 73 75 61 6c 6c 79 2c 20 74 68 65 20 57 41 4c 20  sually, the WAL 
4220: 66 69 6c 65 20 69 73 20 64 65 6c 65 74 65 64 20  file is deleted 
4230: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 77 68  automatically wh
4240: 65 6e 20 74 68 65 0a 6c 61 73 74 20 63 6f 6e 6e  en the.last conn
4250: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
4260: 74 61 62 61 73 65 20 63 6c 6f 73 65 73 2e 20 20  tabase closes.  
4270: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
4280: 6c 61 73 74 20 70 72 6f 63 65 73 73 20 74 6f 0a  last process to.
4290: 68 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  have the databas
42a0: 65 20 6f 70 65 6e 20 65 78 69 74 73 20 77 69 74  e open exits wit
42b0: 68 6f 75 74 20 63 6c 65 61 6e 6c 79 0a 73 68 75  hout cleanly.shu
42c0: 74 74 69 6e 67 20 64 6f 77 6e 20 74 68 65 20 64  tting down the d
42d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
42e0: 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 0a 5b  on, or if the .[
42f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
4300: 53 49 53 54 5f 57 41 4c 5d 20 5b 66 69 6c 65 20  SIST_WAL] [file 
4310: 63 6f 6e 74 72 6f 6c 5d 20 69 73 20 75 73 65 64  control] is used
4320: 2c 20 74 68 65 6e 20 74 68 65 20 57 41 4c 20 66  , then the WAL f
4330: 69 6c 65 0a 6d 69 67 68 74 20 62 65 20 72 65 74  ile.might be ret
4340: 61 69 6e 65 64 20 6f 6e 20 64 69 73 6b 20 61 66  ained on disk af
4350: 74 65 72 20 61 6c 6c 20 63 6f 6e 6e 65 63 74 69  ter all connecti
4360: 6f 6e 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  ons to the datab
4370: 61 73 65 20 68 61 76 65 0a 62 65 65 6e 20 63 6c  ase have.been cl
4380: 6f 73 65 64 2e 20 20 54 68 65 20 57 41 4c 20 66  osed.  The WAL f
4390: 69 6c 65 20 69 73 20 70 61 72 74 20 6f 66 20 74  ile is part of t
43a0: 68 65 20 70 65 72 73 69 73 74 65 6e 74 20 73 74  he persistent st
43b0: 61 74 65 20 6f 66 20 74 68 65 0a 64 61 74 61 62  ate of the.datab
43c0: 61 73 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 62  ase and should b
43d0: 65 20 6b 65 70 74 20 77 69 74 68 20 74 68 65 20  e kept with the 
43e0: 64 61 74 61 62 61 73 65 20 69 66 20 74 68 65 20  database if the 
43f0: 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 70 69  database is copi
4400: 65 64 0a 6f 72 20 6d 6f 76 65 64 2e 20 20 49 66  ed.or moved.  If
4410: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
4420: 20 69 73 20 73 65 70 61 72 61 74 65 64 20 66 72   is separated fr
4430: 6f 6d 20 69 74 73 20 57 41 4c 20 66 69 6c 65 2c  om its WAL file,
4440: 20 74 68 65 6e 0a 74 72 61 6e 73 61 63 74 69 6f   then.transactio
4450: 6e 73 20 74 68 61 74 20 77 65 72 65 20 70 72 65  ns that were pre
4460: 76 69 6f 75 73 6c 79 20 63 6f 6d 6d 69 74 74 65  viously committe
4470: 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  d to the databas
4480: 65 20 6d 69 67 68 74 20 62 65 20 6c 6f 73 74 2c  e might be lost,
4490: 0a 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  .or the database
44a0: 20 66 69 6c 65 20 6d 69 67 68 74 20 62 65 63 6f   file might beco
44b0: 6d 65 20 63 6f 72 72 75 70 74 65 64 2e 0a 54 68  me corrupted..Th
44c0: 65 20 6f 6e 6c 79 20 73 61 66 65 20 77 61 79 20  e only safe way 
44d0: 74 6f 20 72 65 6d 6f 76 65 20 61 20 57 41 4c 20  to remove a WAL 
44e0: 66 69 6c 65 20 69 73 0a 74 6f 20 6f 70 65 6e 20  file is.to open 
44f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4500: 65 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  e using one of t
4510: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
4520: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 74  ()] interfaces.t
4530: 68 65 6e 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  hen immediately 
4540: 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
4550: 73 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  se using [sqlite
4560: 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 0a 3c 70 3e  3_close()]...<p>
4570: 54 68 65 20 5b 57 41 4c 20 66 69 6c 65 20 66 6f  The [WAL file fo
4580: 72 6d 61 74 5d 20 69 73 20 70 72 65 63 69 73 65  rmat] is precise
4590: 6c 79 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69  ly defined and i
45a0: 73 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  s cross-platform
45b0: 2e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d  ...<tcl>hd_fragm
45c0: 65 6e 74 20 7b 72 65 61 64 6f 6e 6c 79 7d 20 7b  ent {readonly} {
45d0: 72 65 61 64 2d 6f 6e 6c 79 20 57 41 4c 20 64 61  read-only WAL da
45e0: 74 61 62 61 73 65 73 7d 3c 2f 74 63 6c 3e 0a 3c  tabases}</tcl>.<
45f0: 68 31 3e 52 65 61 64 2d 4f 6e 6c 79 20 44 61 74  h1>Read-Only Dat
4600: 61 62 61 73 65 73 3c 2f 68 31 3e 0a 0a 3c 70 3e  abases</h1>..<p>
4610: 4f 6c 64 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  Older versions o
4620: 66 20 53 51 4c 69 74 65 20 63 6f 75 6c 64 20 6e  f SQLite could n
4630: 6f 74 20 72 65 61 64 20 61 20 57 41 4c 2d 6d 6f  ot read a WAL-mo
4640: 64 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74  de database that
4650: 20 77 61 73 0a 72 65 61 64 2d 6f 6e 6c 79 2e 20   was.read-only. 
4660: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
4670: 20 77 72 69 74 65 20 61 63 63 65 73 73 20 77 61   write access wa
4680: 73 20 72 65 71 75 69 72 65 64 20 69 6e 20 6f 72  s required in or
4690: 64 65 72 20 74 6f 20 72 65 61 64 20 61 0a 57 41  der to read a.WA
46a0: 4c 2d 6d 6f 64 65 20 64 61 74 61 62 61 73 65 2e  L-mode database.
46b0: 20 20 54 68 69 73 20 63 6f 6e 73 74 72 61 69 6e    This constrain
46c0: 74 20 77 61 73 20 72 65 6c 61 78 65 64 20 62 65  t was relaxed be
46d0: 67 69 6e 6e 69 6e 67 20 77 69 74 68 0a 53 51 4c  ginning with.SQL
46e0: 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 32  ite [version 3.2
46f0: 32 2e 30 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e  2.0] ([dateof:3.
4700: 32 32 2e 30 5d 29 2e 0a 0a 3c 70 3e 4f 6e 20 6e  22.0])...<p>On n
4710: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
4720: 20 53 51 4c 69 74 65 2c 0a 61 20 57 41 4c 2d 6d   SQLite,.a WAL-m
4730: 6f 64 65 20 64 61 74 61 62 61 73 65 20 6f 6e 20  ode database on 
4740: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2c  read-only media,
4750: 20 6f 72 20 61 20 57 41 4c 2d 6d 6f 64 65 20 64   or a WAL-mode d
4760: 61 74 61 62 61 73 65 20 74 68 61 74 20 6c 61 63  atabase that lac
4770: 6b 73 0a 77 72 69 74 65 20 70 65 72 6d 69 73 73  ks.write permiss
4780: 69 6f 6e 2c 20 63 61 6e 20 73 74 69 6c 6c 20 62  ion, can still b
4790: 65 20 72 65 61 64 20 61 73 20 6c 6f 6e 67 20 61  e read as long a
47a0: 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  s one or more of
47b0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 63   the following.c
47c0: 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 6d 65  onditions are me
47d0: 74 3a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 54 68 65 20  t:.<ol>.<li>The 
47e0: 3c 74 74 3e 2d 73 68 6d 3c 2f 74 74 3e 20 61 6e  <tt>-shm</tt> an
47f0: 64 20 3c 74 74 3e 2d 77 61 6c 3c 2f 74 74 3e 20  d <tt>-wal</tt> 
4800: 66 69 6c 65 73 20 61 6c 72 65 61 64 79 20 65 78  files already ex
4810: 69 73 74 73 20 61 6e 64 20 61 72 65 20 72 65 61  ists and are rea
4820: 64 61 62 6c 65 0a 3c 6c 69 3e 54 68 65 72 65 20  dable.<li>There 
4830: 69 73 20 77 72 69 74 65 20 70 65 72 6d 69 73 73  is write permiss
4840: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63  ion on the direc
4850: 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  tory containing 
4860: 74 68 65 20 64 61 74 61 62 61 73 65 20 73 6f 0a  the database so.
4870: 20 20 20 20 74 68 61 74 20 74 68 65 20 3c 74 74      that the <tt
4880: 3e 2d 73 68 6d 3c 2f 74 74 3e 20 61 6e 64 20 3c  >-shm</tt> and <
4890: 74 74 3e 2d 77 61 6c 3c 2f 74 74 3e 20 66 69 6c  tt>-wal</tt> fil
48a0: 65 73 20 63 61 6e 20 62 65 20 63 72 65 61 74 65  es can be create
48b0: 64 2e 0a 3c 6c 69 3e 54 68 65 20 64 61 74 61 62  d..<li>The datab
48c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
48d0: 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 74  s opened using t
48e0: 68 65 0a 20 20 20 20 5b 69 6d 6d 75 74 61 62 6c  he.    [immutabl
48f0: 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
4900: 72 5d 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 45 76  r]..</ol>..<p>Ev
4910: 65 6e 20 74 68 6f 75 67 68 20 69 74 20 69 73 20  en though it is 
4920: 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e  possible to open
4930: 20 61 20 72 65 61 64 2d 6f 6e 6c 79 20 57 41 4c   a read-only WAL
4940: 2d 6d 6f 64 65 20 64 61 74 61 62 61 73 65 2c 0a  -mode database,.
4950: 69 74 20 69 73 20 67 6f 6f 64 20 70 72 61 63 74  it is good pract
4960: 69 63 65 20 74 6f 20 63 6f 6e 76 65 72 74 65 64  ice to converted
4970: 20 74 6f 20 0a 5b 6a 6f 75 72 6e 61 6c 5f 6d 6f   to .[journal_mo
4980: 64 65 20 7c 20 50 52 41 47 4d 41 20 6a 6f 75 72  de | PRAGMA jour
4990: 6e 61 6c 5f 6d 6f 64 65 3d 44 45 4c 45 54 45 5d  nal_mode=DELETE]
49a0: 20 70 72 69 6f 72 20 74 6f 20 62 75 72 6e 69 6e   prior to burnin
49b0: 67 20 61 6e 0a 53 51 4c 69 74 65 20 64 61 74 61  g an.SQLite data
49c0: 62 61 73 65 20 69 6d 61 67 65 20 6f 6e 74 6f 20  base image onto 
49d0: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e  read-only media.
49e0: 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72  </p>..<tcl>hd_fr
49f0: 61 67 6d 65 6e 74 20 62 69 67 77 61 6c 20 7b 6c  agment bigwal {l
4a00: 61 72 67 65 20 57 41 4c 20 66 69 6c 65 73 7d 20  arge WAL files} 
4a10: 7b 61 76 6f 69 64 69 6e 67 20 6c 61 72 67 65 20  {avoiding large 
4a20: 57 41 4c 20 66 69 6c 65 73 7d 3c 2f 74 63 6c 3e  WAL files}</tcl>
4a30: 0a 3c 68 31 3e 41 76 6f 69 64 69 6e 67 20 45 78  .<h1>Avoiding Ex
4a40: 63 65 73 73 69 76 65 6c 79 20 4c 61 72 67 65 20  cessively Large 
4a50: 57 41 4c 20 46 69 6c 65 73 3c 2f 68 31 3e 0a 0a  WAL Files</h1>..
4a60: 3c 70 3e 49 6e 20 6e 6f 72 6d 61 6c 20 63 61 73  <p>In normal cas
4a70: 65 73 2c 20 6e 65 77 20 63 6f 6e 74 65 6e 74 20  es, new content 
4a80: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  is appended to t
4a90: 68 65 20 57 41 4c 20 66 69 6c 65 20 75 6e 74 69  he WAL file unti
4aa0: 6c 20 74 68 65 0a 57 41 4c 20 66 69 6c 65 20 61  l the.WAL file a
4ab0: 63 63 75 6d 75 6c 61 74 65 73 20 61 62 6f 75 74  ccumulates about
4ac0: 20 31 30 30 30 20 70 61 67 65 73 20 28 61 6e 64   1000 pages (and
4ad0: 20 69 73 20 74 68 75 73 20 61 62 6f 75 74 20 34   is thus about 4
4ae0: 4d 42 20 0a 69 6e 20 73 69 7a 65 29 20 61 74 20  MB .in size) at 
4af0: 77 68 69 63 68 20 70 6f 69 6e 74 20 61 20 63 68  which point a ch
4b00: 65 63 6b 70 6f 69 6e 74 20 69 73 20 61 75 74 6f  eckpoint is auto
4b10: 6d 61 74 69 63 61 6c 6c 79 20 72 75 6e 20 61 6e  matically run an
4b20: 64 20 74 68 65 20 57 41 4c 20 66 69 6c 65 0a 69  d the WAL file.i
4b30: 73 20 72 65 63 79 63 6c 65 64 2e 20 20 54 68 65  s recycled.  The
4b40: 20 63 68 65 63 6b 70 6f 69 6e 74 20 64 6f 65 73   checkpoint does
4b50: 20 6e 6f 74 20 6e 6f 72 6d 61 6c 6c 79 20 74 72   not normally tr
4b60: 75 6e 63 61 74 65 20 74 68 65 20 57 41 4c 20 66  uncate the WAL f
4b70: 69 6c 65 0a 28 75 6e 6c 65 73 73 20 74 68 65 20  ile.(unless the 
4b80: 5b 6a 6f 75 72 6e 61 6c 5f 73 69 7a 65 5f 6c 69  [journal_size_li
4b90: 6d 69 74 20 70 72 61 67 6d 61 5d 20 69 73 20 73  mit pragma] is s
4ba0: 65 74 29 2e 20 20 49 6e 73 74 65 61 64 2c 20 69  et).  Instead, i
4bb0: 74 20 6d 65 72 65 6c 79 0a 63 61 75 73 65 73 20  t merely.causes 
4bc0: 53 51 4c 69 74 65 20 74 6f 20 73 74 61 72 74 20  SQLite to start 
4bd0: 6f 76 65 72 77 72 69 74 69 6e 67 20 74 68 65 20  overwriting the 
4be0: 57 41 4c 20 66 69 6c 65 20 66 72 6f 6d 20 74 68  WAL file from th
4bf0: 65 20 62 65 67 69 6e 6e 69 6e 67 2e 0a 54 68 69  e beginning..Thi
4c00: 73 20 69 73 20 64 6f 6e 65 20 62 65 63 61 75 73  s is done becaus
4c10: 65 20 69 74 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  e it is normally
4c20: 20 66 61 73 74 65 72 20 74 6f 20 6f 76 65 72 77   faster to overw
4c30: 72 69 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  rite an existing
4c40: 20 66 69 6c 65 0a 74 68 61 6e 20 74 6f 20 61 70   file.than to ap
4c50: 70 65 6e 64 2e 20 20 57 68 65 6e 20 74 68 65 20  pend.  When the 
4c60: 6c 61 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  last connection 
4c70: 74 6f 20 61 20 64 61 74 61 62 61 73 65 20 63 6c  to a database cl
4c80: 6f 73 65 73 2c 20 74 68 61 74 0a 63 6f 6e 6e 65  oses, that.conne
4c90: 63 74 69 6f 6e 20 64 6f 65 73 20 6f 6e 65 20 6c  ction does one l
4ca0: 61 73 74 20 63 68 65 63 6b 70 6f 69 6e 74 20 61  ast checkpoint a
4cb0: 6e 64 20 74 68 65 6e 20 64 65 6c 65 74 65 73 20  nd then deletes 
4cc0: 74 68 65 20 57 41 4c 20 61 6e 64 20 69 74 73 0a  the WAL and its.
4cd0: 61 73 73 6f 63 69 61 74 65 64 20 73 68 61 72 65  associated share
4ce0: 64 2d 6d 65 6d 6f 72 79 20 66 69 6c 65 2c 20 74  d-memory file, t
4cf0: 6f 20 63 6c 65 61 6e 20 75 70 20 74 68 65 20 64  o clean up the d
4d00: 69 73 6b 2e 0a 0a 3c 70 3e 53 6f 20 69 6e 20 74  isk...<p>So in t
4d10: 68 65 20 76 61 73 74 20 6d 61 6a 6f 72 69 74 79  he vast majority
4d20: 20 6f 66 20 63 61 73 65 73 2c 20 61 70 70 6c 69   of cases, appli
4d30: 63 61 74 69 6f 6e 73 20 6e 65 65 64 20 6e 6f 74  cations need not
4d40: 20 77 6f 72 72 79 20 61 62 6f 75 74 0a 74 68 65   worry about.the
4d50: 20 57 41 4c 20 66 69 6c 65 20 61 74 20 61 6c 6c   WAL file at all
4d60: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  .  SQLite will a
4d70: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 74 61 6b  utomatically tak
4d80: 65 20 63 61 72 65 20 6f 66 20 69 74 2e 20 20 42  e care of it.  B
4d90: 75 74 0a 69 74 20 69 73 20 70 6f 73 73 69 62 6c  ut.it is possibl
4da0: 65 20 74 6f 20 67 65 74 20 53 51 4c 69 74 65 20  e to get SQLite 
4db0: 69 6e 74 6f 20 61 20 73 74 61 74 65 20 77 68 65  into a state whe
4dc0: 72 65 20 74 68 65 20 57 41 4c 20 66 69 6c 65 20  re the WAL file 
4dd0: 77 69 6c 6c 20 67 72 6f 77 0a 77 69 74 68 6f 75  will grow.withou
4de0: 74 20 62 6f 75 6e 64 2c 20 63 61 75 73 69 6e 67  t bound, causing
4df0: 20 65 78 63 65 73 73 20 64 69 73 6b 20 73 70 61   excess disk spa
4e00: 63 65 20 75 73 61 67 65 20 61 6e 64 20 73 6c 6f  ce usage and slo
4e10: 77 20 71 75 65 72 69 65 73 20 73 70 65 65 64 73  w queries speeds
4e20: 2e 0a 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ..The following 
4e30: 62 75 6c 6c 65 74 73 20 65 6e 75 6d 65 72 61 74  bullets enumerat
4e40: 65 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 77 61  e some of the wa
4e50: 79 73 20 74 68 61 74 20 74 68 69 73 20 63 61 6e  ys that this can
4e60: 20 68 61 70 70 65 6e 0a 61 6e 64 20 68 6f 77 20   happen.and how 
4e70: 74 6f 20 61 76 6f 69 64 20 74 68 65 6d 2e 0a 0a  to avoid them...
4e80: 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70 3e 0a 3c 62 3e  <ul>.<li><p>.<b>
4e90: 44 69 73 61 62 6c 69 6e 67 20 74 68 65 20 61 75  Disabling the au
4ea0: 74 6f 6d 61 74 69 63 20 63 68 65 63 6b 70 6f 69  tomatic checkpoi
4eb0: 6e 74 20 6d 65 63 68 61 6e 69 73 6d 2e 3c 2f 62  nt mechanism.</b
4ec0: 3e 0a 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  >.In its default
4ed0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
4ee0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 65 63  SQLite will chec
4ef0: 6b 70 6f 69 6e 74 20 74 68 65 20 57 41 4c 20 66  kpoint the WAL f
4f00: 69 6c 65 20 61 74 20 74 68 65 0a 63 6f 6e 63 6c  ile at the.concl
4f10: 75 73 69 6f 6e 20 6f 66 20 61 6e 79 20 74 72 61  usion of any tra
4f20: 6e 73 61 63 74 69 6f 6e 20 77 68 65 6e 20 74 68  nsaction when th
4f30: 65 20 57 41 4c 20 66 69 6c 65 20 69 73 20 6d 6f  e WAL file is mo
4f40: 72 65 20 74 68 61 6e 20 31 30 30 30 20 70 61 67  re than 1000 pag
4f50: 65 73 0a 6c 6f 6e 67 2e 20 20 48 6f 77 65 76 65  es.long.  Howeve
4f60: 72 2c 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  r, compile-time 
4f70: 61 6e 64 20 72 75 6e 2d 74 69 6d 65 20 6f 70 74  and run-time opt
4f80: 69 6f 6e 73 20 65 78 69 73 74 20 74 68 61 74 20  ions exist that 
4f90: 63 61 6e 20 64 69 73 61 62 6c 65 0a 6f 72 20 64  can disable.or d
4fa0: 65 66 65 72 20 74 68 69 73 20 61 75 74 6f 6d 61  efer this automa
4fb0: 74 69 63 20 63 68 65 63 6b 70 6f 69 6e 74 2e 20  tic checkpoint. 
4fc0: 20 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   If an applicati
4fd0: 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  on disables the.
4fe0: 61 75 74 6f 6d 61 74 69 63 20 63 68 65 63 6b 70  automatic checkp
4ff0: 6f 69 6e 74 2c 20 74 68 65 6e 20 74 68 65 72 65  oint, then there
5000: 20 69 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 70   is nothing to p
5010: 72 65 76 65 6e 74 20 74 68 65 20 57 41 4c 20 66  revent the WAL f
5020: 69 6c 65 0a 66 72 6f 6d 20 67 72 6f 77 69 6e 67  ile.from growing
5030: 20 65 78 63 65 73 73 69 76 65 6c 79 2e 0a 0a 3c   excessively...<
5040: 6c 69 3e 3c 70 3e 0a 3c 62 3e 43 68 65 63 6b 70  li><p>.<b>Checkp
5050: 6f 69 6e 74 20 73 74 61 72 76 61 74 69 6f 6e 2e  oint starvation.
5060: 3c 2f 62 3e 0a 41 20 63 68 65 63 6b 70 6f 69 6e  </b>.A checkpoin
5070: 74 20 69 73 20 6f 6e 6c 79 20 61 62 6c 65 20 74  t is only able t
5080: 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  o run to complet
5090: 69 6f 6e 2c 20 61 6e 64 20 72 65 73 65 74 20 74  ion, and reset t
50a0: 68 65 20 57 41 4c 20 66 69 6c 65 2c 0a 69 66 20  he WAL file,.if 
50b0: 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68  there are no oth
50c0: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
50d0: 65 63 74 69 6f 6e 73 20 75 73 69 6e 67 20 74 68  ections using th
50e0: 65 20 57 41 4c 20 66 69 6c 65 2e 20 20 49 66 20  e WAL file.  If 
50f0: 61 6e 6f 74 68 65 72 0a 63 6f 6e 6e 65 63 74 69  another.connecti
5100: 6f 6e 20 68 61 73 20 61 20 72 65 61 64 20 74 72  on has a read tr
5110: 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2c 0a  ansaction open,.
5120: 74 68 65 6e 20 74 68 65 20 63 68 65 63 6b 70 6f  then the checkpo
5130: 69 6e 74 20 63 61 6e 6e 6f 74 20 72 65 73 65 74  int cannot reset
5140: 20 74 68 65 20 57 41 4c 20 66 69 6c 65 20 62 65   the WAL file be
5150: 63 61 75 73 65 0a 64 6f 69 6e 67 20 73 6f 20 6d  cause.doing so m
5160: 69 67 68 74 20 64 65 6c 65 74 65 20 63 6f 6e 74  ight delete cont
5170: 65 6e 74 20 6f 75 74 20 66 72 6f 6d 20 75 6e 64  ent out from und
5180: 65 72 20 74 68 65 20 72 65 61 64 65 72 2e 0a 54  er the reader..T
5190: 68 65 20 63 68 65 63 6b 70 6f 69 6e 74 20 77 69  he checkpoint wi
51a0: 6c 6c 20 64 6f 20 61 73 20 6d 75 63 68 20 77 6f  ll do as much wo
51b0: 72 6b 20 61 73 20 69 74 20 63 61 6e 20 77 69 74  rk as it can wit
51c0: 68 6f 75 74 20 75 70 73 65 74 74 69 6e 67 20 74  hout upsetting t
51d0: 68 65 0a 72 65 61 64 65 72 2c 20 62 75 74 20 69  he.reader, but i
51e0: 74 20 63 61 6e 6e 6f 74 20 72 75 6e 20 74 6f 20  t cannot run to 
51f0: 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 54 68 65 20  completion..The 
5200: 63 68 65 63 6b 70 6f 69 6e 74 20 77 69 6c 6c 20  checkpoint will 
5210: 73 74 61 72 74 20 75 70 20 61 67 61 69 6e 20 77  start up again w
5220: 68 65 72 65 20 69 74 20 6c 65 66 74 20 6f 66 66  here it left off
5230: 20 61 66 74 65 72 20 74 68 65 20 6e 65 78 74 0a   after the next.
5240: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
5250: 6e 2e 20 20 54 68 69 73 20 72 65 70 65 61 74 73  n.  This repeats
5260: 20 75 6e 74 69 6c 20 73 6f 6d 65 20 63 68 65 63   until some chec
5270: 6b 70 6f 69 6e 74 20 69 73 20 61 62 6c 65 20 74  kpoint is able t
5280: 6f 20 63 6f 6d 70 6c 65 74 65 2e 0a 0a 3c 70 3e  o complete...<p>
5290: 48 6f 77 65 76 65 72 2c 20 69 66 20 61 20 64 61  However, if a da
52a0: 74 61 62 61 73 65 20 68 61 73 20 6d 61 6e 79 20  tabase has many 
52b0: 63 6f 6e 63 75 72 72 65 6e 74 20 6f 76 65 72 6c  concurrent overl
52c0: 61 70 70 69 6e 67 20 72 65 61 64 65 72 73 0a 61  apping readers.a
52d0: 6e 64 20 74 68 65 72 65 20 69 73 20 61 6c 77 61  nd there is alwa
52e0: 79 73 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20  ys at least one 
52f0: 61 63 74 69 76 65 20 72 65 61 64 65 72 2c 20 74  active reader, t
5300: 68 65 6e 0a 6e 6f 20 63 68 65 63 6b 70 6f 69 6e  hen.no checkpoin
5310: 74 73 20 77 69 6c 6c 20 62 65 20 61 62 6c 65 20  ts will be able 
5320: 74 6f 20 63 6f 6d 70 6c 65 74 65 0a 61 6e 64 20  to complete.and 
5330: 68 65 6e 63 65 20 74 68 65 20 57 41 4c 20 66 69  hence the WAL fi
5340: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 77 69 74  le will grow wit
5350: 68 6f 75 74 20 62 6f 75 6e 64 2e 0a 0a 3c 70 3e  hout bound...<p>
5360: 54 68 69 73 20 73 63 65 6e 61 72 69 6f 20 63 61  This scenario ca
5370: 6e 20 62 65 20 61 76 6f 69 64 65 64 20 62 79 20  n be avoided by 
5380: 65 6e 73 75 72 69 6e 67 20 74 68 61 74 20 74 68  ensuring that th
5390: 65 72 65 20 61 72 65 20 22 72 65 61 64 65 72 20  ere are "reader 
53a0: 67 61 70 73 22 3a 0a 74 69 6d 65 73 20 77 68 65  gaps":.times whe
53b0: 6e 20 6e 6f 20 70 72 6f 63 65 73 73 65 73 20 61  n no processes a
53c0: 72 65 20 72 65 61 64 69 6e 67 20 66 72 6f 6d 20  re reading from 
53d0: 74 68 65 20 0a 64 61 74 61 62 61 73 65 20 61 6e  the .database an
53e0: 64 20 74 68 61 74 20 63 68 65 63 6b 70 6f 69 6e  d that checkpoin
53f0: 74 73 20 61 72 65 20 61 74 74 65 6d 70 74 65 64  ts are attempted
5400: 20 64 75 72 69 6e 67 20 74 68 6f 73 65 20 74 69   during those ti
5410: 6d 65 73 2e 0a 49 6e 20 61 70 70 6c 69 63 61 74  mes..In applicat
5420: 69 6f 6e 73 20 77 69 74 68 20 6d 61 6e 79 20 63  ions with many c
5430: 6f 6e 63 75 72 72 65 6e 74 20 72 65 61 64 65 72  oncurrent reader
5440: 73 2c 20 6f 6e 65 20 6d 69 67 68 74 20 61 6c 73  s, one might als
5450: 6f 20 63 6f 6e 73 69 64 65 72 20 0a 72 75 6e 6e  o consider .runn
5460: 69 6e 67 20 6d 61 6e 75 61 6c 20 63 68 65 63 6b  ing manual check
5470: 70 6f 69 6e 74 73 20 77 69 74 68 20 74 68 65 20  points with the 
5480: 5b 53 51 4c 49 54 45 5f 43 48 45 43 4b 50 4f 49  [SQLITE_CHECKPOI
5490: 4e 54 5f 52 45 53 54 41 52 54 5d 20 6f 72 0a 5b  NT_RESTART] or.[
54a0: 53 51 4c 49 54 45 5f 43 48 45 43 4b 50 4f 49 4e  SQLITE_CHECKPOIN
54b0: 54 5f 54 52 55 4e 43 41 54 45 5d 20 6f 70 74 69  T_TRUNCATE] opti
54c0: 6f 6e 20 77 68 69 63 68 20 77 69 6c 6c 20 65 6e  on which will en
54d0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 63 68  sure that the ch
54e0: 65 63 6b 70 6f 69 6e 74 0a 72 75 6e 73 20 74 6f  eckpoint.runs to
54f0: 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 62 65 66 6f   completion befo
5500: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 20 20 54  re returning.  T
5510: 68 65 20 64 69 73 61 64 76 61 6e 74 61 67 65 20  he disadvantage 
5520: 6f 66 20 75 73 69 6e 67 0a 5b 53 51 4c 49 54 45  of using.[SQLITE
5530: 5f 43 48 45 43 4b 50 4f 49 4e 54 5f 52 45 53 54  _CHECKPOINT_REST
5540: 41 52 54 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  ART] and [SQLITE
5550: 5f 43 48 45 43 4b 50 4f 49 4e 54 5f 54 52 55 4e  _CHECKPOINT_TRUN
5560: 43 41 54 45 5d 20 69 73 20 74 68 61 74 0a 72 65  CATE] is that.re
5570: 61 64 65 72 73 20 6d 69 67 68 74 20 62 6c 6f 63  aders might bloc
5580: 6b 20 77 68 69 6c 65 20 74 68 65 20 63 68 65 63  k while the chec
5590: 6b 70 6f 69 6e 74 20 69 73 20 72 75 6e 6e 69 6e  kpoint is runnin
55a0: 67 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 3c 62 3e 56  g...<li><p>.<b>V
55b0: 65 72 79 20 6c 61 72 67 65 20 77 72 69 74 65 20  ery large write 
55c0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e 3c 2f 62  transactions.</b
55d0: 3e 0a 41 20 63 68 65 63 6b 70 6f 69 6e 74 20 63  >.A checkpoint c
55e0: 61 6e 20 6f 6e 6c 79 20 63 6f 6d 70 6c 65 74 65  an only complete
55f0: 20 77 68 65 6e 20 6e 6f 20 6f 74 68 65 72 20 74   when no other t
5600: 72 61 6e 73 61 63 74 69 6f 6e 73 20 61 72 65 20  ransactions are 
5610: 72 75 6e 6e 69 6e 67 2c 20 0a 77 68 69 63 68 20  running, .which 
5620: 6d 65 61 6e 73 20 74 68 65 20 57 41 4c 20 66 69  means the WAL fi
5630: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 72 65 73  le cannot be res
5640: 65 74 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  et in the middle
5650: 20 6f 66 20 61 20 77 72 69 74 65 0a 74 72 61 6e   of a write.tran
5660: 73 61 63 74 69 6f 6e 2e 20 20 53 6f 20 61 20 6c  saction.  So a l
5670: 61 72 67 65 20 63 68 61 6e 67 65 20 74 6f 20 61  arge change to a
5680: 20 6c 61 72 67 65 20 64 61 74 61 62 61 73 65 0a   large database.
5690: 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
56a0: 61 20 6c 61 72 67 65 20 57 41 4c 20 66 69 6c 65  a large WAL file
56b0: 2e 20 20 54 68 65 20 57 41 4c 20 66 69 6c 65 20  .  The WAL file 
56c0: 77 69 6c 6c 20 62 65 20 63 68 65 63 6b 70 6f 69  will be checkpoi
56d0: 6e 74 65 64 0a 6f 6e 63 65 20 74 68 65 20 77 72  nted.once the wr
56e0: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
56f0: 63 6f 6d 70 6c 65 74 65 73 20 28 61 73 73 75 6d  completes (assum
5700: 69 6e 67 20 74 68 65 72 65 20 61 72 65 20 6e 6f  ing there are no
5710: 20 6f 74 68 65 72 20 72 65 61 64 65 72 73 0a 62   other readers.b
5720: 6c 6f 63 6b 69 6e 67 20 69 74 29 20 62 75 74 20  locking it) but 
5730: 69 6e 20 74 68 65 20 6d 65 61 6e 74 69 6d 65 2c  in the meantime,
5740: 20 74 68 65 20 66 69 6c 65 20 63 61 6e 20 67 72   the file can gr
5750: 6f 77 20 76 65 72 79 20 62 69 67 2e 0a 0a 3c 70  ow very big...<p
5760: 3e 41 73 20 6f 66 20 53 51 4c 69 74 65 20 5b 76  >As of SQLite [v
5770: 65 72 73 69 6f 6e 20 33 2e 31 31 2e 30 5d 20 28  ersion 3.11.0] (
5780: 5b 64 61 74 65 6f 66 3a 33 2e 31 31 2e 30 5d 29  [dateof:3.11.0])
5790: 2c 20 0a 74 68 65 20 57 41 4c 20 66 69 6c 65 20  , .the WAL file 
57a0: 66 6f 72 20 61 20 73 69 6e 67 6c 65 20 74 72 61  for a single tra
57b0: 6e 73 61 63 74 69 6f 6e 0a 73 68 6f 75 6c 64 20  nsaction.should 
57c0: 62 65 20 70 72 6f 70 6f 72 74 69 6f 6e 61 6c 20  be proportional 
57d0: 69 6e 20 73 69 7a 65 20 74 6f 20 74 68 65 20 74  in size to the t
57e0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 74 73 65 6c  ransaction itsel
57f0: 66 2e 20 20 50 61 67 65 73 20 74 68 61 74 0a 61  f.  Pages that.a
5800: 72 65 20 63 68 61 6e 67 65 64 20 62 79 20 74 68  re changed by th
5810: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 68  e transaction sh
5820: 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 77 72 69  ould only be wri
5830: 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 57 41  tten into the WA
5840: 4c 20 66 69 6c 65 0a 6f 6e 63 65 2e 20 20 48 6f  L file.once.  Ho
5850: 77 65 76 65 72 2c 20 77 69 74 68 20 6f 6c 64 65  wever, with olde
5860: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
5870: 4c 69 74 65 2c 20 74 68 65 20 73 61 6d 65 20 70  Lite, the same p
5880: 61 67 65 20 6d 69 67 68 74 20 62 65 0a 77 72 69  age might be.wri
5890: 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 57 41  tten into the WA
58a0: 4c 20 66 69 6c 65 20 6d 75 6c 74 69 70 6c 65 20  L file multiple 
58b0: 74 69 6d 65 73 20 69 66 20 74 68 65 20 74 72 61  times if the tra
58c0: 6e 73 61 63 74 69 6f 6e 20 67 72 6f 77 73 20 6c  nsaction grows l
58d0: 61 72 67 65 72 0a 74 68 61 6e 20 74 68 65 20 70  arger.than the p
58e0: 61 67 65 20 63 61 63 68 65 2e 0a 3c 2f 75 6c 3e  age cache..</ul>
58f0: 0a 0a 3c 68 31 3e 49 6d 70 6c 65 6d 65 6e 74 61  ..<h1>Implementa
5900: 74 69 6f 6e 20 4f 66 20 53 68 61 72 65 64 2d 4d  tion Of Shared-M
5910: 65 6d 6f 72 79 20 46 6f 72 20 54 68 65 20 57 41  emory For The WA
5920: 4c 2d 49 6e 64 65 78 3c 2f 68 31 3e 0a 0a 3c 70  L-Index</h1>..<p
5930: 3e 54 68 65 20 5b 77 61 6c 2d 69 6e 64 65 78 5d  >The [wal-index]
5940: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
5950: 75 73 69 6e 67 20 61 6e 20 6f 72 64 69 6e 61 72  using an ordinar
5960: 79 20 66 69 6c 65 20 74 68 61 74 20 69 73 0a 6d  y file that is.m
5970: 6d 61 70 70 65 64 20 66 6f 72 20 72 6f 62 75 73  mapped for robus
5980: 74 6e 65 73 73 2e 20 20 45 61 72 6c 79 20 28 70  tness.  Early (p
5990: 72 65 2d 72 65 6c 65 61 73 65 29 20 69 6d 70 6c  re-release) impl
59a0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 57  ementations of W
59b0: 41 4c 20 6d 6f 64 65 0a 73 74 6f 72 65 64 20 74  AL mode.stored t
59c0: 68 65 20 77 61 6c 2d 69 6e 64 65 78 20 69 6e 20  he wal-index in 
59d0: 76 6f 6c 61 74 69 6c 65 20 73 68 61 72 65 64 2d  volatile shared-
59e0: 6d 65 6d 6f 72 79 2c 20 73 75 63 68 20 61 73 20  memory, such as 
59f0: 66 69 6c 65 73 20 63 72 65 61 74 65 64 20 69 6e  files created in
5a00: 0a 2f 64 65 76 2f 73 68 6d 20 6f 6e 20 4c 69 6e  ./dev/shm on Lin
5a10: 75 78 20 6f 72 20 2f 74 6d 70 20 6f 6e 20 6f 74  ux or /tmp on ot
5a20: 68 65 72 20 75 6e 69 78 20 73 79 73 74 65 6d 73  her unix systems
5a30: 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 0a 77  .  The problem.w
5a40: 69 74 68 20 74 68 61 74 20 61 70 70 72 6f 61 63  ith that approac
5a50: 68 20 69 73 20 74 68 61 74 20 70 72 6f 63 65 73  h is that proces
5a60: 73 65 73 20 77 69 74 68 20 61 20 64 69 66 66 65  ses with a diffe
5a70: 72 65 6e 74 20 72 6f 6f 74 20 64 69 72 65 63 74  rent root direct
5a80: 6f 72 79 0a 28 63 68 61 6e 67 65 64 20 76 69 61  ory.(changed via
5a90: 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f   <a href="http:/
5aa0: 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61 2e 6f 72  /en.wikipedia.or
5ab0: 67 2f 77 69 6b 69 2f 43 68 72 6f 6f 74 22 3e 63  g/wiki/Chroot">c
5ac0: 68 72 6f 6f 74 3c 2f 61 3e 29 0a 77 69 6c 6c 20  hroot</a>).will 
5ad0: 73 65 65 20 64 69 66 66 65 72 65 6e 74 20 66 69  see different fi
5ae0: 6c 65 73 20 61 6e 64 20 68 65 6e 63 65 20 75 73  les and hence us
5af0: 65 20 64 69 66 66 65 72 65 6e 74 20 73 68 61 72  e different shar
5b00: 65 64 20 6d 65 6d 6f 72 79 20 61 72 65 61 73 2c  ed memory areas,
5b10: 0a 6c 65 61 64 69 6e 67 20 74 6f 20 64 61 74 61  .leading to data
5b20: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
5b30: 20 20 4f 74 68 65 72 20 6d 65 74 68 6f 64 73 20    Other methods 
5b40: 66 6f 72 20 63 72 65 61 74 69 6e 67 20 6e 61 6d  for creating nam
5b50: 65 6c 65 73 73 0a 73 68 61 72 65 64 20 6d 65 6d  eless.shared mem
5b60: 6f 72 79 20 62 6c 6f 63 6b 73 20 61 72 65 20 6e  ory blocks are n
5b70: 6f 74 20 70 6f 72 74 61 62 6c 65 20 61 63 72 6f  ot portable acro
5b80: 73 73 20 74 68 65 20 76 61 72 69 6f 75 73 20 66  ss the various f
5b90: 6c 61 76 6f 72 73 20 6f 66 0a 75 6e 69 78 2e 20  lavors of.unix. 
5ba0: 20 41 6e 64 20 77 65 20 63 6f 75 6c 64 20 6e 6f   And we could no
5bb0: 74 20 66 69 6e 64 20 61 6e 79 20 6d 65 74 68 6f  t find any metho
5bc0: 64 20 74 6f 20 63 72 65 61 74 65 20 6e 61 6d 65  d to create name
5bd0: 6c 65 73 73 20 73 68 61 72 65 64 0a 6d 65 6d 6f  less shared.memo
5be0: 72 79 20 62 6c 6f 63 6b 73 20 6f 6e 20 77 69 6e  ry blocks on win
5bf0: 64 6f 77 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  dows.  The only 
5c00: 77 61 79 20 77 65 20 68 61 76 65 20 66 6f 75 6e  way we have foun
5c10: 64 20 74 6f 20 67 75 61 72 61 6e 74 65 65 0a 74  d to guarantee.t
5c20: 68 61 74 20 61 6c 6c 20 70 72 6f 63 65 73 73 65  hat all processe
5c30: 73 20 61 63 63 65 73 73 69 6e 67 20 74 68 65 20  s accessing the 
5c40: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 66 69  same database fi
5c50: 6c 65 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  le use the same 
5c60: 73 68 61 72 65 64 0a 6d 65 6d 6f 72 79 20 69 73  shared.memory is
5c70: 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 73   to create the s
5c80: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 62 79 20  hared memory by 
5c90: 6d 6d 61 70 70 69 6e 67 20 61 20 66 69 6c 65 20  mmapping a file 
5ca0: 69 6e 20 74 68 65 20 73 61 6d 65 0a 64 69 72 65  in the same.dire
5cb0: 63 74 6f 72 79 20 61 73 20 74 68 65 20 64 61 74  ctory as the dat
5cc0: 61 62 61 73 65 20 69 74 73 65 6c 66 2e 3c 2f 70  abase itself.</p
5cd0: 3e 0a 0a 3c 70 3e 55 73 69 6e 67 20 61 6e 20 6f  >..<p>Using an o
5ce0: 72 64 69 6e 61 72 79 20 64 69 73 6b 20 66 69 6c  rdinary disk fil
5cf0: 65 20 74 6f 20 70 72 6f 76 69 64 65 20 73 68 61  e to provide sha
5d00: 72 65 64 20 6d 65 6d 6f 72 79 20 68 61 73 20 74  red memory has t
5d10: 68 65 20 0a 64 69 73 61 64 76 61 6e 74 61 67 65  he .disadvantage
5d20: 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 61   that it might a
5d30: 63 74 75 61 6c 6c 79 20 64 6f 20 75 6e 6e 65 63  ctually do unnec
5d40: 65 73 73 61 72 79 20 64 69 73 6b 20 49 2f 4f 20  essary disk I/O 
5d50: 62 79 0a 77 72 69 74 69 6e 67 20 74 68 65 20 73  by.writing the s
5d60: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 74 6f 20  hared memory to 
5d70: 64 69 73 6b 2e 20 20 48 6f 77 65 76 65 72 2c 20  disk.  However, 
5d80: 74 68 65 20 64 65 76 65 6c 6f 70 65 72 73 20 64  the developers d
5d90: 6f 20 6e 6f 74 0a 74 68 69 6e 6b 20 74 68 69 73  o not.think this
5da0: 20 69 73 20 61 20 6d 61 6a 6f 72 20 63 6f 6e 63   is a major conc
5db0: 65 72 6e 20 73 69 6e 63 65 20 74 68 65 20 77 61  ern since the wa
5dc0: 6c 2d 69 6e 64 65 78 20 72 61 72 65 6c 79 20 65  l-index rarely e
5dd0: 78 63 65 65 64 73 0a 33 32 20 4b 69 42 20 69 6e  xceeds.32 KiB in
5de0: 20 73 69 7a 65 20 61 6e 64 20 69 73 20 6e 65 76   size and is nev
5df0: 65 72 20 73 79 6e 63 65 64 2e 20 20 46 75 72 74  er synced.  Furt
5e00: 68 65 72 6d 6f 72 65 2c 20 74 68 65 20 77 61 6c  hermore, the wal
5e10: 2d 69 6e 64 65 78 20 0a 62 61 63 6b 69 6e 67 20  -index .backing 
5e20: 66 69 6c 65 20 69 73 20 64 65 6c 65 74 65 64 20  file is deleted 
5e30: 77 68 65 6e 20 74 68 65 20 6c 61 73 74 20 64 61  when the last da
5e40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5e50: 6e 20 64 69 73 63 6f 6e 6e 65 63 74 73 2c 0a 77  n disconnects,.w
5e60: 68 69 63 68 20 6f 66 74 65 6e 20 70 72 65 76 65  hich often preve
5e70: 6e 74 73 20 61 6e 79 20 72 65 61 6c 20 64 69 73  nts any real dis
5e80: 6b 20 49 2f 4f 20 66 72 6f 6d 20 65 76 65 72 20  k I/O from ever 
5e90: 68 61 70 70 65 6e 69 6e 67 2e 3c 2f 70 3e 0a 0a  happening.</p>..
5ea0: 3c 70 3e 53 70 65 63 69 61 6c 69 7a 65 64 20 61  <p>Specialized a
5eb0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 66 6f 72 20  pplications for 
5ec0: 77 68 69 63 68 20 74 68 65 20 64 65 66 61 75 6c  which the defaul
5ed0: 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
5ee0: 20 6f 66 0a 73 68 61 72 65 64 20 6d 65 6d 6f 72   of.shared memor
5ef0: 79 20 69 73 20 75 6e 61 63 63 65 70 74 61 62 6c  y is unacceptabl
5f00: 65 20 63 61 6e 20 64 65 76 69 73 65 20 61 6c 74  e can devise alt
5f10: 65 72 6e 61 74 69 76 65 20 6d 65 74 68 6f 64 73  ernative methods
5f20: 20 76 69 61 20 61 0a 63 75 73 74 6f 6d 20 5b 56   via a.custom [V
5f30: 46 53 5d 2e 20 20 0a 46 6f 72 20 65 78 61 6d 70  FS].  .For examp
5f40: 6c 65 2c 20 69 66 20 69 74 20 69 73 20 6b 6e 6f  le, if it is kno
5f50: 77 6e 20 74 68 61 74 20 61 20 70 61 72 74 69 63  wn that a partic
5f60: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 77 69  ular database.wi
5f70: 6c 6c 20 6f 6e 6c 79 20 62 65 20 61 63 63 65 73  ll only be acces
5f80: 73 65 64 20 62 79 20 74 68 72 65 61 64 73 20 77  sed by threads w
5f90: 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 70  ithin a single p
5fa0: 72 6f 63 65 73 73 2c 20 74 68 65 20 77 61 6c 2d  rocess, the wal-
5fb0: 69 6e 64 65 78 0a 63 61 6e 20 62 65 20 69 6d 70  index.can be imp
5fc0: 6c 65 6d 65 6e 74 65 64 20 75 73 69 6e 67 20 68  lemented using h
5fd0: 65 61 70 20 6d 65 6d 6f 72 79 20 69 6e 73 74 65  eap memory inste
5fe0: 61 64 20 6f 66 20 74 72 75 65 20 73 68 61 72 65  ad of true share
5ff0: 64 20 6d 65 6d 6f 72 79 2e 3c 2f 70 3e 0a 0a 3c  d memory.</p>..<
6000: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
6010: 6e 6f 73 68 6d 20 7b 57 41 4c 20 77 69 74 68 6f  noshm {WAL witho
6020: 75 74 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  ut shared memory
6030: 7d 3c 2f 74 63 6c 3e 0a 3c 68 31 3e 55 73 65 20  }</tcl>.<h1>Use 
6040: 6f 66 20 57 41 4c 20 57 69 74 68 6f 75 74 20 53  of WAL Without S
6050: 68 61 72 65 64 2d 4d 65 6d 6f 72 79 3c 2f 68 31  hared-Memory</h1
6060: 3e 0a 0a 3c 70 3e 42 65 67 69 6e 6e 69 6e 67 20  >..<p>Beginning 
6070: 69 6e 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  in SQLite [versi
6080: 6f 6e 20 33 2e 37 2e 34 5d 20 28 5b 64 61 74 65  on 3.7.4] ([date
6090: 6f 66 3a 33 2e 37 2e 34 5d 29 2c 20 0a 5e 57 41  of:3.7.4]), .^WA
60a0: 4c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  L databases can 
60b0: 62 65 20 63 72 65 61 74 65 64 2c 20 72 65 61 64  be created, read
60c0: 2c 20 61 6e 64 0a 77 72 69 74 74 65 6e 20 65 76  , and.written ev
60d0: 65 6e 20 69 66 20 73 68 61 72 65 64 20 6d 65 6d  en if shared mem
60e0: 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
60f0: 6c 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  le as long as th
6100: 65 0a 5b 6c 6f 63 6b 69 6e 67 5f 6d 6f 64 65 5d  e.[locking_mode]
6110: 20 69 73 20 73 65 74 20 74 6f 20 45 58 43 4c 55   is set to EXCLU
6120: 53 49 56 45 20 62 65 66 6f 72 65 20 74 68 65 20  SIVE before the 
6130: 66 69 72 73 74 20 61 74 74 65 6d 70 74 65 64 20  first attempted 
6140: 61 63 63 65 73 73 2e 0a 49 6e 20 6f 74 68 65 72  access..In other
6150: 20 77 6f 72 64 73 2c 20 61 20 70 72 6f 63 65 73   words, a proces
6160: 73 20 63 61 6e 20 69 6e 74 65 72 61 63 74 20 77  s can interact w
6170: 69 74 68 0a 61 20 57 41 4c 20 64 61 74 61 62 61  ith.a WAL databa
6180: 73 65 20 77 69 74 68 6f 75 74 20 75 73 69 6e 67  se without using
6190: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 69   shared memory i
61a0: 66 20 74 68 61 74 0a 70 72 6f 63 65 73 73 20 69  f that.process i
61b0: 73 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  s guaranteed to 
61c0: 62 65 20 74 68 65 20 6f 6e 6c 79 20 70 72 6f 63  be the only proc
61d0: 65 73 73 20 61 63 63 65 73 73 69 6e 67 20 74 68  ess accessing th
61e0: 65 20 64 61 74 61 62 61 73 65 2e 0a 5e 54 68 69  e database..^Thi
61f0: 73 20 66 65 61 74 75 72 65 20 61 6c 6c 6f 77 73  s feature allows
6200: 20 57 41 4c 20 64 61 74 61 62 61 73 65 73 20 74   WAL databases t
6210: 6f 20 62 65 20 63 72 65 61 74 65 64 2c 20 72 65  o be created, re
6220: 61 64 2c 20 61 6e 64 20 77 72 69 74 74 65 6e 0a  ad, and written.
6230: 62 79 20 6c 65 67 61 63 79 20 5b 56 46 53 65 73  by legacy [VFSes
6240: 5d 20 74 68 61 74 20 6c 61 63 6b 20 74 68 65 20  ] that lack the 
6250: 22 76 65 72 73 69 6f 6e 20 32 22 20 73 68 61 72  "version 2" shar
6260: 65 64 2d 6d 65 6d 6f 72 79 0a 6d 65 74 68 6f 64  ed-memory.method
6270: 73 20 78 53 68 6d 4d 61 70 2c 20 78 53 68 6d 4c  s xShmMap, xShmL
6280: 6f 63 6b 2c 20 78 53 68 6d 42 61 72 72 69 65 72  ock, xShmBarrier
6290: 2c 20 61 6e 64 20 78 53 68 6d 55 6e 6d 61 70 20  , and xShmUnmap 
62a0: 6f 6e 20 74 68 65 0a 5b 73 71 6c 69 74 65 33 5f  on the.[sqlite3_
62b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
62c0: 63 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e 28 49 66  ct.</p>..<p>^(If
62d0: 20 5b 6c 6f 63 6b 69 6e 67 5f 6d 6f 64 65 20 7c   [locking_mode |
62e0: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 69   EXCLUSIVE locki
62f0: 6e 67 20 6d 6f 64 65 5d 0a 69 73 20 73 65 74 20  ng mode].is set 
6300: 70 72 69 6f 72 20 74 6f 20 74 68 65 20 66 69 72  prior to the fir
6310: 73 74 20 57 41 4c 2d 6d 6f 64 65 20 0a 64 61 74  st WAL-mode .dat
6320: 61 62 61 73 65 20 61 63 63 65 73 73 2c 20 74 68  abase access, th
6330: 65 6e 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20  en SQLite never 
6340: 61 74 74 65 6d 70 74 73 20 74 6f 20 63 61 6c 6c  attempts to call
6350: 20 61 6e 79 20 6f 66 20 74 68 65 0a 73 68 61 72   any of the.shar
6360: 65 64 2d 6d 65 6d 6f 72 79 20 6d 65 74 68 6f 64  ed-memory method
6370: 73 20 61 6e 64 20 68 65 6e 63 65 20 6e 6f 20 73  s and hence no s
6380: 68 61 72 65 64 2d 6d 65 6d 6f 72 79 0a 77 61 6c  hared-memory.wal
6390: 2d 69 6e 64 65 78 20 69 73 20 65 76 65 72 20 63  -index is ever c
63a0: 72 65 61 74 65 64 2e 29 5e 0a 5e 28 49 6e 20 74  reated.)^.^(In t
63b0: 68 61 74 20 63 61 73 65 2c 20 74 68 65 20 64 61  hat case, the da
63c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
63d0: 6e 20 72 65 6d 61 69 6e 73 20 69 6e 20 45 58 43  n remains in EXC
63e0: 4c 55 53 49 56 45 20 6d 6f 64 65 0a 61 73 20 6c  LUSIVE mode.as l
63f0: 6f 6e 67 20 61 73 20 74 68 65 20 6a 6f 75 72 6e  ong as the journ
6400: 61 6c 20 6d 6f 64 65 20 69 73 20 57 41 4c 3b 20  al mode is WAL; 
6410: 61 74 74 65 6d 70 74 73 20 74 6f 20 63 68 61 6e  attempts to chan
6420: 67 65 20 74 68 65 20 6c 6f 63 6b 69 6e 67 0a 6d  ge the locking.m
6430: 6f 64 65 20 75 73 69 6e 67 20 22 3c 74 74 3e 50  ode using "<tt>P
6440: 52 41 47 4d 41 20 6c 6f 63 6b 69 6e 67 5f 6d 6f  RAGMA locking_mo
6450: 64 65 3d 4e 4f 52 4d 41 4c 3b 3c 2f 74 74 3e 22  de=NORMAL;</tt>"
6460: 20 61 72 65 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 5e   are no-ops.)^.^
6470: 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  The only way to 
6480: 63 68 61 6e 67 65 20 6f 75 74 20 6f 66 20 45 58  change out of EX
6490: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 69 6e 67 20  CLUSIVE locking 
64a0: 6d 6f 64 65 20 69 73 20 74 6f 20 66 69 72 73 74  mode is to first
64b0: 0a 63 68 61 6e 67 65 20 6f 75 74 20 6f 66 20 57  .change out of W
64c0: 41 4c 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 2e  AL journal mode.
64d0: 3c 2f 70 3e 0a 0a 3c 70 3e 5e 49 66 20 4e 4f 52  </p>..<p>^If NOR
64e0: 4d 41 4c 20 6c 6f 63 6b 69 6e 67 20 6d 6f 64 65  MAL locking mode
64f0: 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 66 6f   is in effect fo
6500: 72 20 74 68 65 20 66 69 72 73 74 20 57 41 4c 2d  r the first WAL-
6510: 6d 6f 64 65 20 64 61 74 61 62 61 73 65 0a 61 63  mode database.ac
6520: 63 65 73 73 2c 20 74 68 65 6e 20 74 68 65 20 73  cess, then the s
6530: 68 61 72 65 64 2d 6d 65 6d 6f 72 79 20 77 61 6c  hared-memory wal
6540: 2d 69 6e 64 65 78 20 69 73 20 63 72 65 61 74 65  -index is create
6550: 64 2e 20 20 5e 54 68 69 73 20 6d 65 61 6e 73 20  d.  ^This means 
6560: 74 68 61 74 20 74 68 65 0a 75 6e 64 65 72 6c 79  that the.underly
6570: 69 6e 67 20 56 46 53 20 6d 75 73 74 20 73 75 70  ing VFS must sup
6580: 70 6f 72 74 20 74 68 65 20 22 76 65 72 73 69 6f  port the "versio
6590: 6e 20 32 22 20 73 68 61 72 65 64 2d 6d 65 6d 6f  n 2" shared-memo
65a0: 72 79 2e 0a 5e 49 66 20 74 68 65 20 56 46 53 20  ry..^If the VFS 
65b0: 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
65c0: 20 73 68 61 72 65 64 2d 6d 65 6d 6f 72 79 20 6d   shared-memory m
65d0: 65 74 68 6f 64 73 2c 20 74 68 65 6e 20 74 68 65  ethods, then the
65e0: 20 61 74 74 65 6d 70 74 20 74 6f 0a 6f 70 65 6e   attempt to.open
65f0: 20 61 20 64 61 74 61 62 61 73 65 20 74 68 61 74   a database that
6600: 20 69 73 20 61 6c 72 65 61 64 79 20 69 6e 20 57   is already in W
6610: 41 4c 20 6d 6f 64 65 2c 20 6f 72 20 74 68 65 20  AL mode, or the 
6620: 61 74 74 65 6d 70 74 20 63 6f 6e 76 65 72 74 20  attempt convert 
6630: 61 0a 64 61 74 61 62 61 73 65 20 69 6e 74 6f 20  a.database into 
6640: 57 41 4c 20 6d 6f 64 65 2c 20 77 69 6c 6c 20 66  WAL mode, will f
6650: 61 69 6c 2e 0a 5e 41 73 20 6c 6f 6e 67 20 61 73  ail..^As long as
6660: 20 65 78 61 63 74 6c 79 20 6f 6e 65 20 63 6f 6e   exactly one con
6670: 6e 65 63 74 69 6f 6e 20 69 73 20 75 73 69 6e 67  nection is using
6680: 20 61 20 73 68 61 72 65 64 2d 6d 65 6d 6f 72 79   a shared-memory
6690: 20 77 61 6c 2d 69 6e 64 65 78 2c 20 0a 74 68 65   wal-index, .the
66a0: 20 6c 6f 63 6b 69 6e 67 20 6d 6f 64 65 20 63 61   locking mode ca
66b0: 6e 20 62 65 20 63 68 61 6e 67 65 64 20 66 72 65  n be changed fre
66c0: 65 6c 79 20 62 65 74 77 65 65 6e 20 4e 4f 52 4d  ely between NORM
66d0: 41 4c 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  AL and EXCLUSIVE
66e0: 2e 20 20 0a 5e 49 74 20 69 73 20 6f 6e 6c 79 20  .  .^It is only 
66f0: 77 68 65 6e 20 74 68 65 20 73 68 61 72 65 64 2d  when the shared-
6700: 6d 65 6d 6f 72 79 20 77 61 6c 2d 69 6e 64 65 78  memory wal-index
6710: 20 69 73 20 6f 6d 69 74 74 65 64 2c 20 77 68 65   is omitted, whe
6720: 6e 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20 0a 6d  n the locking .m
6730: 6f 64 65 20 69 73 20 45 58 43 4c 55 53 49 56 45  ode is EXCLUSIVE
6740: 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 66 69   prior to the fi
6750: 72 73 74 20 57 41 4c 2d 6d 6f 64 65 20 64 61 74  rst WAL-mode dat
6760: 61 62 61 73 65 20 61 63 63 65 73 73 2c 20 74 68  abase access, th
6770: 61 74 20 74 68 65 20 0a 6c 6f 63 6b 69 6e 67 20  at the .locking 
6780: 6d 6f 64 65 20 69 73 20 73 74 75 63 6b 20 69 6e  mode is stuck in
6790: 20 45 58 43 4c 55 53 49 56 45 2e 3c 2f 70 3e 0a   EXCLUSIVE.</p>.
67a0: 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e  .<tcl>hd_fragmen
67b0: 74 20 62 75 73 79 20 7b 57 41 4c 2d 6d 6f 64 65  t busy {WAL-mode
67c0: 20 72 65 61 64 20 62 6c 6f 63 6b 69 6e 67 7d 3c   read blocking}<
67d0: 2f 74 63 6c 3e 0a 3c 68 31 3e 53 6f 6d 65 74 69  /tcl>.<h1>Someti
67e0: 6d 65 73 20 51 75 65 72 69 65 73 20 52 65 74 75  mes Queries Retu
67f0: 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 20 49  rn SQLITE_BUSY I
6800: 6e 20 57 41 4c 20 4d 6f 64 65 3c 2f 68 31 3e 0a  n WAL Mode</h1>.
6810: 0a 3c 70 3e 54 68 65 20 5b 61 64 76 61 6e 74 61  .<p>The [advanta
6820: 67 65 73 20 6f 66 20 57 41 4c 2d 6d 6f 64 65 7c  ges of WAL-mode|
6830: 73 65 63 6f 6e 64 20 61 64 76 61 6e 74 61 67 65  second advantage
6840: 20 6f 66 20 57 41 4c 2d 6d 6f 64 65 5d 20 69 73   of WAL-mode] is
6850: 20 74 68 61 74 0a 77 72 69 74 65 72 73 20 64 6f   that.writers do
6860: 20 6e 6f 74 20 62 6c 6f 63 6b 20 72 65 61 64 65   not block reade
6870: 72 73 20 61 6e 64 20 72 65 61 64 65 72 73 20 74  rs and readers t
6880: 6f 20 64 6f 20 6e 6f 74 20 62 6c 6f 63 6b 20 77  o do not block w
6890: 72 69 74 65 72 73 2e 0a 54 68 69 73 20 69 73 20  riters..This is 
68a0: 3c 75 3e 6d 6f 73 74 6c 79 3c 2f 75 3e 20 74 72  <u>mostly</u> tr
68b0: 75 65 2e 0a 42 75 74 20 74 68 65 72 65 20 61 72  ue..But there ar
68c0: 65 20 73 6f 6d 65 20 6f 62 73 63 75 72 65 20 63  e some obscure c
68d0: 61 73 65 73 20 77 68 65 72 65 20 61 20 71 75 65  ases where a que
68e0: 72 79 20 61 67 61 69 6e 73 74 20 61 20 57 41 4c  ry against a WAL
68f0: 2d 6d 6f 64 65 0a 64 61 74 61 62 61 73 65 20 63  -mode.database c
6900: 61 6e 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  an return [SQLIT
6910: 45 5f 42 55 53 59 5d 2c 20 73 6f 20 61 70 70 6c  E_BUSY], so appl
6920: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
6930: 62 65 20 70 72 65 70 61 72 65 64 0a 66 6f 72 20  be prepared.for 
6940: 74 68 61 74 20 68 61 70 70 65 6e 73 74 61 6e 63  that happenstanc
6950: 65 2e 0a 0a 3c 70 3e 43 61 73 65 73 20 77 68 65  e...<p>Cases whe
6960: 72 65 20 61 20 71 75 65 72 79 20 61 67 61 69 6e  re a query again
6970: 73 74 20 61 20 57 41 4c 2d 6d 6f 64 65 20 64 61  st a WAL-mode da
6980: 74 61 62 61 73 65 20 63 61 6e 20 72 65 74 75 72  tabase can retur
6990: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
69a0: 69 6e 63 6c 75 64 65 20 74 68 65 20 66 6f 6c 6c  include the foll
69b0: 6f 77 69 6e 67 3a 0a 0a 3c 75 6c 3e 0a 3c 6c 69  owing:..<ul>.<li
69c0: 3e 3c 70 3e 49 66 20 61 6e 6f 74 68 65 72 20 64  ><p>If another d
69d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
69e0: 6f 6e 20 68 61 73 20 74 68 65 20 64 61 74 61 62  on has the datab
69f0: 61 73 65 20 6d 6f 64 65 20 6f 70 65 6e 0a 69 6e  ase mode open.in
6a00: 20 5b 6c 6f 63 6b 69 6e 67 5f 6d 6f 64 65 7c 65   [locking_mode|e
6a10: 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 69 6e 67  xclusive locking
6a20: 20 6d 6f 64 65 5d 20 74 68 65 6e 20 61 6c 6c 20   mode] then all 
6a30: 71 75 65 72 69 65 73 20 61 67 61 69 6e 73 74 20  queries against 
6a40: 74 68 65 0a 64 61 74 61 62 61 73 65 20 77 69 6c  the.database wil
6a50: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
6a60: 5f 42 55 53 59 5d 2e 20 20 42 6f 74 68 20 43 68  _BUSY].  Both Ch
6a70: 72 6f 6d 65 20 61 6e 64 20 46 69 72 65 66 6f 78  rome and Firefox
6a80: 20 6f 70 65 6e 20 74 68 65 69 72 0a 64 61 74 61   open their.data
6a90: 62 61 73 65 20 66 69 6c 65 73 20 69 6e 20 65 78  base files in ex
6aa0: 63 6c 75 73 69 76 65 20 6c 6f 63 6b 69 6e 67 20  clusive locking 
6ab0: 6d 6f 64 65 2c 20 73 6f 20 61 74 74 65 6d 70 74  mode, so attempt
6ac0: 73 20 74 6f 20 72 65 61 64 20 43 68 72 6f 6d 65  s to read Chrome
6ad0: 20 6f 72 0a 46 69 72 65 66 6f 78 20 64 61 74 61   or.Firefox data
6ae0: 62 61 73 65 73 20 77 68 69 6c 65 20 74 68 65 20  bases while the 
6af0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 72 65  applications are
6b00: 20 72 75 6e 6e 69 6e 67 20 77 69 6c 6c 20 72 75   running will ru
6b10: 6e 20 69 6e 74 6f 20 74 68 69 73 0a 70 72 6f 62  n into this.prob
6b20: 6c 65 6d 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  lem, for example
6b30: 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 57 68 65 6e 20  ...<li><p>.When 
6b40: 74 68 65 20 6c 61 73 74 20 63 6f 6e 6e 65 63 74  the last connect
6b50: 69 6f 6e 20 74 6f 20 61 20 70 61 72 74 69 63 75  ion to a particu
6b60: 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 73 20  lar database is 
6b70: 63 6c 6f 73 69 6e 67 2c 20 74 68 61 74 0a 63 6f  closing, that.co
6b80: 6e 6e 65 63 74 69 6f 6e 20 77 69 6c 6c 20 61 63  nnection will ac
6b90: 71 75 69 72 65 20 61 6e 20 65 78 63 6c 75 73 69  quire an exclusi
6ba0: 76 65 20 6c 6f 63 6b 20 66 6f 72 20 61 20 73 68  ve lock for a sh
6bb0: 6f 72 74 20 74 69 6d 65 20 77 68 69 6c 65 20 69  ort time while i
6bc0: 74 0a 63 6c 65 61 6e 73 20 75 70 20 74 68 65 20  t.cleans up the 
6bd0: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 2d 6d  WAL and shared-m
6be0: 65 6d 6f 72 79 20 66 69 6c 65 73 2e 20 20 49 66  emory files.  If
6bf0: 20 61 20 73 65 63 6f 6e 64 20 64 61 74 61 62 61   a second databa
6c00: 73 65 20 74 72 69 65 73 0a 74 6f 20 6f 70 65 6e  se tries.to open
6c10: 20 61 6e 64 20 71 75 65 72 79 20 74 68 65 20 64   and query the d
6c20: 61 74 61 62 61 73 65 20 77 68 69 6c 65 20 74 68  atabase while th
6c30: 65 20 66 69 72 73 74 20 63 6f 6e 6e 65 63 74 69  e first connecti
6c40: 6f 6e 0a 69 73 20 73 74 69 6c 6c 20 69 6e 20 74  on.is still in t
6c50: 68 65 20 6d 69 64 64 6c 65 0a 6f 66 20 69 74 73  he middle.of its
6c60: 20 63 6c 65 61 6e 75 70 20 70 72 6f 63 65 73 73   cleanup process
6c70: 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 63 6f 6e  , the second con
6c80: 6e 65 63 74 69 6f 6e 20 6d 69 67 68 74 20 67 65  nection might ge
6c90: 74 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  t an [SQLITE_BUS
6ca0: 59 5d 0a 65 72 72 6f 72 2e 0a 0a 3c 6c 69 3e 3c  Y].error...<li><
6cb0: 70 3e 0a 49 66 20 74 68 65 20 6c 61 73 74 20 63  p>.If the last c
6cc0: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 61 20 64  onnection to a d
6cd0: 61 74 61 62 61 73 65 20 63 72 61 73 68 65 64 2c  atabase crashed,
6ce0: 20 74 68 65 6e 20 74 68 65 20 66 69 72 73 74 20   then the first 
6cf0: 6e 65 77 0a 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  new.connection t
6d00: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
6d10: 61 73 65 20 77 69 6c 6c 20 73 74 61 72 74 20 61  ase will start a
6d20: 20 72 65 63 6f 76 65 72 79 20 70 72 6f 63 65 73   recovery proces
6d30: 73 2e 20 20 41 6e 0a 65 78 63 6c 75 73 69 76 65  s.  An.exclusive
6d40: 20 6c 6f 63 6b 20 69 73 20 68 65 6c 64 20 64 75   lock is held du
6d50: 72 69 6e 67 20 72 65 63 6f 76 65 72 79 2e 20 20  ring recovery.  
6d60: 53 6f 20 69 66 20 61 20 74 68 69 72 64 20 64 61  So if a third da
6d70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6d80: 6e 0a 74 72 69 65 73 20 74 6f 20 6a 75 6d 70 20  n.tries to jump 
6d90: 69 6e 20 61 6e 64 20 71 75 65 72 79 20 77 68 69  in and query whi
6da0: 6c 65 20 74 68 65 20 73 65 63 6f 6e 64 20 63 6f  le the second co
6db0: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  nnection is runn
6dc0: 69 6e 67 20 72 65 63 6f 76 65 72 79 2c 0a 74 68  ing recovery,.th
6dd0: 65 20 74 68 69 72 64 20 63 6f 6e 6e 65 63 74 69  e third connecti
6de0: 6f 6e 20 77 69 6c 6c 20 67 65 74 20 61 6e 20 5b  on will get an [
6df0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
6e00: 6f 72 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 74 63 6c 3e  or..</ul>..<tcl>
6e10: 68 64 5f 66 72 61 67 6d 65 6e 74 20 62 6b 77 72  hd_fragment bkwr
6e20: 64 73 20 7b 57 41 4c 20 62 61 63 6b 77 61 72 64  ds {WAL backward
6e30: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 7d  s compatibility}
6e40: 3c 2f 74 63 6c 3e 0a 3c 68 31 3e 42 61 63 6b 77  </tcl>.<h1>Backw
6e50: 61 72 64 73 20 43 6f 6d 70 61 74 69 62 69 6c 69  ards Compatibili
6e60: 74 79 3c 2f 68 31 3e 0a 0a 3c 70 3e 54 68 65 20  ty</h1>..<p>The 
6e70: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 66 6f  database file fo
6e80: 72 6d 61 74 20 69 73 20 75 6e 63 68 61 6e 67 65  rmat is unchange
6e90: 64 20 66 6f 72 20 57 41 4c 20 6d 6f 64 65 2e 20  d for WAL mode. 
6ea0: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 0a 57 41   However, the.WA
6eb0: 4c 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 5b  L file and the [
6ec0: 77 61 6c 2d 69 6e 64 65 78 5d 20 61 72 65 20 6e  wal-index] are n
6ed0: 65 77 20 63 6f 6e 63 65 70 74 73 20 61 6e 64 20  ew concepts and 
6ee0: 73 6f 20 6f 6c 64 65 72 20 76 65 72 73 69 6f 6e  so older version
6ef0: 73 20 6f 66 20 0a 53 51 4c 69 74 65 20 77 69 6c  s of .SQLite wil
6f00: 6c 20 6e 6f 74 20 6b 6e 6f 77 0a 68 6f 77 20 74  l not know.how t
6f10: 6f 20 72 65 63 6f 76 65 72 20 61 20 63 72 61 73  o recover a cras
6f20: 68 65 64 20 53 51 4c 69 74 65 20 64 61 74 61 62  hed SQLite datab
6f30: 61 73 65 20 74 68 61 74 20 77 61 73 20 6f 70 65  ase that was ope
6f40: 72 61 74 69 6e 67 20 69 6e 20 57 41 4c 20 6d 6f  rating in WAL mo
6f50: 64 65 0a 77 68 65 6e 20 74 68 65 20 63 72 61 73  de.when the cras
6f60: 68 20 6f 63 63 75 72 72 65 64 2e 0a 5e 28 54 6f  h occurred..^(To
6f70: 20 70 72 65 76 65 6e 74 20 6f 6c 64 65 72 20 76   prevent older v
6f80: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
6f90: 65 20 28 70 72 69 6f 72 20 74 6f 20 76 65 72 73  e (prior to vers
6fa0: 69 6f 6e 20 33 2e 37 2e 30 2c 20 32 30 31 30 2d  ion 3.7.0, 2010-
6fb0: 30 37 2d 32 32 29 0a 66 72 6f 6d 20 74 72 79 69  07-22).from tryi
6fc0: 6e 67 20 74 6f 20 72 65 63 6f 76 65 72 0a 61 20  ng to recover.a 
6fd0: 57 41 4c 2d 6d 6f 64 65 20 64 61 74 61 62 61 73  WAL-mode databas
6fe0: 65 20 28 61 6e 64 20 6d 61 6b 69 6e 67 20 6d 61  e (and making ma
6ff0: 74 74 65 72 73 20 77 6f 72 73 65 29 20 74 68 65  tters worse) the
7000: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 66   database file f
7010: 6f 72 6d 61 74 0a 76 65 72 73 69 6f 6e 20 6e 75  ormat.version nu
7020: 6d 62 65 72 73 20 28 62 79 74 65 73 20 31 38 20  mbers (bytes 18 
7030: 61 6e 64 20 31 39 20 69 6e 20 74 68 65 20 5b 64  and 19 in the [d
7040: 61 74 61 62 61 73 65 20 68 65 61 64 65 72 5d 29  atabase header])
7050: 0a 61 72 65 20 69 6e 63 72 65 61 73 65 64 20 66  .are increased f
7060: 72 6f 6d 20 31 20 74 6f 20 32 20 69 6e 20 57 41  rom 1 to 2 in WA
7070: 4c 20 6d 6f 64 65 2e 29 5e 0a 54 68 75 73 2c 20  L mode.)^.Thus, 
7080: 69 66 20 61 6e 20 6f 6c 64 65 72 20 76 65 72 73  if an older vers
7090: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 61 74  ion of SQLite at
70a0: 74 65 6d 70 74 73 20 74 6f 20 63 6f 6e 6e 65 63  tempts to connec
70b0: 74 20 74 6f 20 61 6e 20 53 51 4c 69 74 65 0a 64  t to an SQLite.d
70c0: 61 74 61 62 61 73 65 20 74 68 61 74 20 69 73 20  atabase that is 
70d0: 6f 70 65 72 61 74 69 6e 67 20 69 6e 20 57 41 4c  operating in WAL
70e0: 20 6d 6f 64 65 2c 20 69 74 20 77 69 6c 6c 20 72   mode, it will r
70f0: 65 70 6f 72 74 20 61 6e 20 65 72 72 6f 72 20 61  eport an error a
7100: 6c 6f 6e 67 0a 74 68 65 20 6c 69 6e 65 73 20 6f  long.the lines o
7110: 66 20 22 66 69 6c 65 20 69 73 20 65 6e 63 72 79  f "file is encry
7120: 70 74 65 64 20 6f 72 20 69 73 20 6e 6f 74 20 61  pted or is not a
7130: 20 64 61 74 61 62 61 73 65 22 2e 3c 2f 70 3e 0a   database".</p>.
7140: 0a 3c 70 3e 5e 28 4f 6e 65 20 63 61 6e 20 65 78  .<p>^(One can ex
7150: 70 6c 69 63 69 74 6c 79 20 63 68 61 6e 67 65 20  plicitly change 
7160: 6f 75 74 20 6f 66 20 57 41 4c 20 6d 6f 64 65 20  out of WAL mode 
7170: 75 73 69 6e 67 20 61 20 70 72 61 67 6d 61 20 73  using a pragma s
7180: 75 63 68 20 61 73 0a 74 68 69 73 3a 3c 2f 70 3e  uch as.this:</p>
7190: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
71a0: 72 65 3e 0a 50 52 41 47 4d 41 20 6a 6f 75 72 6e  re>.PRAGMA journ
71b0: 61 6c 5f 6d 6f 64 65 3d 44 45 4c 45 54 45 3b 0a  al_mode=DELETE;.
71c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
71d0: 74 65 3e 0a 29 5e 0a 0a 3c 70 3e 5e 28 44 65 6c  te>.)^..<p>^(Del
71e0: 69 62 65 72 61 74 65 6c 79 20 63 68 61 6e 67 69  iberately changi
71f0: 6e 67 20 6f 75 74 20 6f 66 20 57 41 4c 20 6d 6f  ng out of WAL mo
7200: 64 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 64  de changes the d
7210: 61 74 61 62 61 73 65 20 66 69 6c 65 20 66 6f 72  atabase file for
7220: 6d 61 74 0a 76 65 72 73 69 6f 6e 20 6e 75 6d 62  mat.version numb
7230: 65 72 73 20 62 61 63 6b 20 74 6f 20 31 20 73 6f  ers back to 1 so
7240: 20 74 68 61 74 20 6f 6c 64 65 72 20 76 65 72 73   that older vers
7250: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 63  ions of SQLite c
7260: 61 6e 20 6f 6e 63 65 20 61 67 61 69 6e 20 0a 61  an once again .a
7270: 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
7280: 73 65 20 66 69 6c 65 2e 29 5e 3c 2f 70 3e 0a     se file.)^</p>.