Documentation Source Text

Hex Artifact Content
Login

Artifact 7335f6bc3e3e457a15cf990936c4a93bdb0b1f3e:


0000: 3c 74 69 74 6c 65 3e 53 51 4c 69 74 65 20 53 68  <title>SQLite Sh
0010: 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 3c  ared-Cache Mode<
0020: 2f 74 69 74 6c 65 3e 0a 3c 74 63 6c 3e 68 64 5f  /title>.<tcl>hd_
0030: 6b 65 79 77 6f 72 64 73 20 7b 53 51 4c 69 74 65  keywords {SQLite
0040: 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f   Shared-Cache Mo
0050: 64 65 7d 20 5c 0a 20 20 20 20 20 20 20 20 7b 73  de} \.        {s
0060: 68 61 72 65 64 20 63 61 63 68 65 7d 20 7b 73 68  hared cache} {sh
0070: 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 7d  ared cache mode}
0080: 3c 2f 74 63 6c 3e 0a 0a 3c 74 61 62 6c 65 5f 6f  </tcl>..<table_o
0090: 66 5f 63 6f 6e 74 65 6e 74 73 3e 0a 0a 3c 68 31  f_contents>..<h1
00a0: 3e 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43  >SQLite Shared-C
00b0: 61 63 68 65 20 4d 6f 64 65 3c 2f 68 31 3e 0a 0a  ache Mode</h1>..
00c0: 3c 70 3e 53 74 61 72 74 69 6e 67 20 77 69 74 68  <p>Starting with
00d0: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 33 2e 30 5d   [version 3.3.0]
00e0: 20 28 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 30 5d   ([dateof:3.3.0]
00f0: 29 2c 20 0a 53 51 4c 69 74 65 20 69 6e 63 6c 75  ), .SQLite inclu
0100: 64 65 73 20 61 20 73 70 65 63 69 61 6c 20 22 73  des a special "s
0110: 68 61 72 65 64 2d 63 61 63 68 65 22 0a 6d 6f 64  hared-cache".mod
0120: 65 20 28 64 69 73 61 62 6c 65 64 20 62 79 20 64  e (disabled by d
0130: 65 66 61 75 6c 74 29 20 69 6e 74 65 6e 64 65 64  efault) intended
0140: 20 66 6f 72 20 75 73 65 20 69 6e 20 65 6d 62 65   for use in embe
0150: 64 64 65 64 20 73 65 72 76 65 72 73 2e 20 49 66  dded servers. If
0160: 0a 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f  .shared-cache mo
0170: 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  de is enabled an
0180: 64 20 61 20 74 68 72 65 61 64 20 65 73 74 61 62  d a thread estab
0190: 6c 69 73 68 65 73 20 6d 75 6c 74 69 70 6c 65 20  lishes multiple 
01a0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 74 6f 20 74  connections.to t
01b0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
01c0: 2c 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  , the connection
01d0: 73 20 73 68 61 72 65 20 61 20 73 69 6e 67 6c 65  s share a single
01e0: 20 64 61 74 61 20 61 6e 64 20 73 63 68 65 6d 61   data and schema
01f0: 20 63 61 63 68 65 2e 0a 54 68 69 73 20 63 61 6e   cache..This can
0200: 20 73 69 67 6e 69 66 69 63 61 6e 74 6c 79 20 72   significantly r
0210: 65 64 75 63 65 20 74 68 65 20 71 75 61 6e 74 69  educe the quanti
0220: 74 79 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6e 64  ty of memory and
0230: 20 49 4f 20 72 65 71 75 69 72 65 64 20 62 79 0a   IO required by.
0240: 74 68 65 20 73 79 73 74 65 6d 2e 3c 2f 70 3e 0a  the system.</p>.
0250: 0a 3c 70 3e 49 6e 20 5b 76 65 72 73 69 6f 6e 20  .<p>In [version 
0260: 33 2e 35 2e 30 5d 20 28 5b 64 61 74 65 6f 66 3a  3.5.0] ([dateof:
0270: 33 2e 35 2e 30 5d 29 2c 20 0a 73 68 61 72 65 64  3.5.0]), .shared
0280: 2d 63 61 63 68 65 20 6d 6f 64 65 20 77 61 73 20  -cache mode was 
0290: 6d 6f 64 69 66 69 65 64 20 73 6f 20 74 68 61 74  modified so that
02a0: 20 74 68 65 20 73 61 6d 65 0a 63 61 63 68 65 20   the same.cache 
02b0: 63 61 6e 20 62 65 20 73 68 61 72 65 64 20 61 63  can be shared ac
02c0: 72 6f 73 73 20 61 6e 20 65 6e 74 69 72 65 20 70  ross an entire p
02d0: 72 6f 63 65 73 73 20 72 61 74 68 65 72 20 74 68  rocess rather th
02e0: 61 6e 20 6a 75 73 74 20 77 69 74 68 69 6e 0a 61  an just within.a
02f0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
0300: 20 50 72 69 6f 72 20 74 6f 20 74 68 69 73 20 63   Prior to this c
0310: 68 61 6e 67 65 2c 20 74 68 65 72 65 20 77 65 72  hange, there wer
0320: 65 20 72 65 73 74 72 69 63 74 69 6f 6e 73 20 6f  e restrictions o
0330: 6e 0a 70 61 73 73 69 6e 67 20 64 61 74 61 62 61  n.passing databa
0340: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  se connections b
0350: 65 74 77 65 65 6e 20 74 68 72 65 61 64 73 2e 20  etween threads. 
0360: 20 54 68 6f 73 65 20 72 65 73 74 72 69 63 74 69   Those restricti
0370: 6f 6e 73 20 77 65 72 65 0a 64 72 6f 70 70 65 64  ons were.dropped
0380: 20 69 6e 20 33 2e 35 2e 30 20 75 70 64 61 74 65   in 3.5.0 update
0390: 2e 20 20 54 68 69 73 20 64 6f 63 75 6d 65 6e 74  .  This document
03a0: 20 64 65 73 63 72 69 62 65 73 20 73 68 61 72 65   describes share
03b0: 64 2d 63 61 63 68 65 20 6d 6f 64 65 0a 61 73 20  d-cache mode.as 
03c0: 6f 66 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  of version 3.5.0
03d0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 53 68 61 72 65 64  .</p>..<p>Shared
03e0: 2d 63 61 63 68 65 20 6d 6f 64 65 20 63 68 61 6e  -cache mode chan
03f0: 67 65 73 20 74 68 65 20 73 65 6d 61 6e 74 69 63  ges the semantic
0400: 73 0a 6f 66 20 74 68 65 20 6c 6f 63 6b 69 6e 67  s.of the locking
0410: 20 6d 6f 64 65 6c 20 69 6e 20 73 6f 6d 65 20 63   model in some c
0420: 61 73 65 73 2e 20 54 68 65 20 64 65 74 61 69 6c  ases. The detail
0430: 73 20 61 72 65 20 64 65 73 63 72 69 62 65 64 20  s are described 
0440: 62 79 0a 74 68 69 73 20 64 6f 63 75 6d 65 6e 74  by.this document
0450: 2e 20 41 20 62 61 73 69 63 20 75 6e 64 65 72 73  . A basic unders
0460: 74 61 6e 64 69 6e 67 20 6f 66 20 74 68 65 20 6e  tanding of the n
0470: 6f 72 6d 61 6c 20 53 51 4c 69 74 65 20 6c 6f 63  ormal SQLite loc
0480: 6b 69 6e 67 20 6d 6f 64 65 6c 20 28 73 65 65 0a  king model (see.
0490: 3c 61 20 68 72 65 66 3d 22 6c 6f 63 6b 69 6e 67  <a href="locking
04a0: 76 33 2e 68 74 6d 6c 22 3e 46 69 6c 65 20 4c 6f  v3.html">File Lo
04b0: 63 6b 69 6e 67 20 41 6e 64 20 43 6f 6e 63 75 72  cking And Concur
04c0: 72 65 6e 63 79 20 49 6e 20 53 51 4c 69 74 65 20  rency In SQLite 
04d0: 56 65 72 73 69 6f 6e 20 33 3c 2f 61 3e 0a 66 6f  Version 3</a>.fo
04e0: 72 20 64 65 74 61 69 6c 73 29 20 69 73 20 61 73  r details) is as
04f0: 73 75 6d 65 64 2e 3c 2f 70 3e 0a 0a 3c 68 31 3e  sumed.</p>..<h1>
0500: 53 68 61 72 65 64 2d 43 61 63 68 65 20 4c 6f 63  Shared-Cache Loc
0510: 6b 69 6e 67 20 4d 6f 64 65 6c 3c 2f 68 31 3e 0a  king Model</h1>.
0520: 0a 3c 70 3e 45 78 74 65 72 6e 61 6c 6c 79 2c 20  .<p>Externally, 
0530: 66 72 6f 6d 20 74 68 65 20 70 6f 69 6e 74 20 6f  from the point o
0540: 66 20 76 69 65 77 20 6f 66 20 61 6e 6f 74 68 65  f view of anothe
0550: 72 20 70 72 6f 63 65 73 73 20 6f 72 20 74 68 72  r process or thr
0560: 65 61 64 2c 20 74 77 6f 0a 6f 72 20 6d 6f 72 65  ead, two.or more
0570: 20 5b 73 71 6c 69 74 65 33 7c 64 61 74 61 62 61   [sqlite3|databa
0580: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
0590: 75 73 69 6e 67 20 61 20 73 68 61 72 65 64 2d 63  using a shared-c
05a0: 61 63 68 65 20 61 70 70 65 61 72 20 61 73 20 61  ache appear as a
05b0: 20 73 69 6e 67 6c 65 20 0a 63 6f 6e 6e 65 63 74   single .connect
05c0: 69 6f 6e 2e 20 54 68 65 20 6c 6f 63 6b 69 6e 67  ion. The locking
05d0: 20 70 72 6f 74 6f 63 6f 6c 20 75 73 65 64 20 74   protocol used t
05e0: 6f 20 61 72 62 69 74 72 61 74 65 20 62 65 74 77  o arbitrate betw
05f0: 65 65 6e 20 6d 75 6c 74 69 70 6c 65 20 0a 73 68  een multiple .sh
0600: 61 72 65 64 2d 63 61 63 68 65 73 20 6f 72 20 72  ared-caches or r
0610: 65 67 75 6c 61 72 20 64 61 74 61 62 61 73 65 20  egular database 
0620: 75 73 65 72 73 20 69 73 20 64 65 73 63 72 69 62  users is describ
0630: 65 64 20 65 6c 73 65 77 68 65 72 65 2e 0a 3c 2f  ed elsewhere..</
0640: 70 3e 0a 0a 3c 74 61 62 6c 65 20 73 74 79 6c 65  p>..<table style
0650: 3d 22 6d 61 72 67 69 6e 3a 61 75 74 6f 22 3e 0a  ="margin:auto">.
0660: 3c 74 72 3e 3c 74 64 3e 0a 3c 69 6d 67 20 73 72  <tr><td>.<img sr
0670: 63 3d 22 69 6d 61 67 65 73 2f 73 68 61 72 65 64  c="images/shared
0680: 2e 67 69 66 22 3e 0a 3c 21 2d 2d 20 3c 70 72 65  .gif">.<!-- <pre
0690: 3e 0a 20 20 20 20 20 20 20 20 20 20 20 20 2b 2d  >.            +-
06a0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2b 20 20  -------------+  
06b0: 20 20 20 20 2b 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      +-----------
06c0: 2d 2d 2d 2b 0a 20 20 20 20 20 20 20 20 20 20 20  ---+.           
06d0: 20 7c 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 32 20   | Connection 2 
06e0: 7c 20 20 20 20 20 20 7c 20 43 6f 6e 6e 65 63 74  |      | Connect
06f0: 69 6f 6e 20 33 20 7c 0a 20 20 20 20 20 20 20 20  ion 3 |.        
0700: 20 20 20 20 2b 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      +-----------
0710: 2d 2d 2d 2b 20 20 20 20 20 20 2b 2d 2d 2d 2d 2d  ---+      +-----
0720: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2b 0a 20 20 20 20 20  ---------+.     
0730: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0740: 20 20 20 20 7c 20 20 20 20 20 20 20 20 20 20 7c      |          |
0750: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
0760: 20 20 20 20 20 20 20 20 20 20 56 20 20 20 20 20            V     
0770: 20 20 20 20 20 56 0a 2b 2d 2d 2d 2d 2d 2d 2d 2d       V.+--------
0780: 2d 2d 2d 2d 2d 2d 2b 20 20 20 20 20 20 20 2b 2d  ------+       +-
0790: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2b 0a 7c  -------------+.|
07a0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 31 20 7c 20   Connection 1 | 
07b0: 20 20 20 20 20 20 7c 20 53 68 61 72 65 64 20 63        | Shared c
07c0: 61 63 68 65 20 7c 0a 2b 2d 2d 2d 2d 2d 2d 2d 2d  ache |.+--------
07d0: 2d 2d 2d 2d 2d 2d 2b 20 20 20 20 20 20 20 2b 2d  ------+       +-
07e0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2b 0a 20  -------------+. 
07f0: 20 20 20 20 20 20 20 20 20 20 20 7c 20 20 20 20             |    
0800: 20 20 20 20 20 20 20 20 7c 0a 20 20 20 20 20 20          |.      
0810: 20 20 20 20 20 20 56 20 20 20 20 20 20 20 20 20        V         
0820: 20 20 20 56 0a 20 20 20 20 20 20 20 20 20 20 2b     V.          +
0830: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
0840: 2b 0a 20 20 20 20 20 20 20 20 20 20 7c 20 20 20  +.          |   
0850: 20 44 61 74 61 62 61 73 65 20 20 20 20 7c 0a 20   Database    |. 
0860: 20 20 20 20 20 20 20 20 20 2b 2d 2d 2d 2d 2d 2d           +------
0870: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2b 0a 3c 2f 70 72  ----------+.</pr
0880: 65 3e 20 2d 2d 3e 0a 3c 2f 74 61 62 6c 65 3e 0a  e> -->.</table>.
0890: 3c 70 20 73 74 79 6c 65 3d 22 66 6f 6e 74 2d 73  <p style="font-s
08a0: 74 79 6c 65 3a 69 74 61 6c 69 63 3b 74 65 78 74  tyle:italic;text
08b0: 2d 61 6c 69 67 6e 3a 63 65 6e 74 65 72 22 3e 46  -align:center">F
08c0: 69 67 75 72 65 20 31 3c 2f 70 3e 0a 0a 3c 70 3e  igure 1</p>..<p>
08d0: 46 69 67 75 72 65 20 31 20 64 65 70 69 63 74 73  Figure 1 depicts
08e0: 20 61 6e 20 65 78 61 6d 70 6c 65 20 72 75 6e 74   an example runt
08f0: 69 6d 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ime configuratio
0900: 6e 20 77 68 65 72 65 20 74 68 72 65 65 20 0a 64  n where three .d
0910: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
0920: 6f 6e 73 20 68 61 76 65 20 62 65 65 6e 20 65 73  ons have been es
0930: 74 61 62 6c 69 73 68 65 64 2e 20 43 6f 6e 6e 65  tablished. Conne
0940: 63 74 69 6f 6e 20 31 20 69 73 20 61 20 6e 6f 72  ction 1 is a nor
0950: 6d 61 6c 0a 53 51 4c 69 74 65 20 64 61 74 61 62  mal.SQLite datab
0960: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
0970: 43 6f 6e 6e 65 63 74 69 6f 6e 73 20 32 20 61 6e  Connections 2 an
0980: 64 20 33 20 73 68 61 72 65 20 61 20 63 61 63 68  d 3 share a cach
0990: 65 20 0a 54 68 65 20 6e 6f 72 6d 61 6c 20 6c 6f  e .The normal lo
09a0: 63 6b 69 6e 67 0a 70 72 6f 74 6f 63 6f 6c 20 69  cking.protocol i
09b0: 73 20 75 73 65 64 20 74 6f 20 73 65 72 69 61 6c  s used to serial
09c0: 69 7a 65 20 64 61 74 61 62 61 73 65 20 61 63 63  ize database acc
09d0: 65 73 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e  ess between conn
09e0: 65 63 74 69 6f 6e 20 31 20 61 6e 64 0a 74 68 65  ection 1 and.the
09f0: 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 54   shared cache. T
0a00: 68 65 20 69 6e 74 65 72 6e 61 6c 20 70 72 6f 74  he internal prot
0a10: 6f 63 6f 6c 20 75 73 65 64 20 74 6f 20 73 65 72  ocol used to ser
0a20: 69 61 6c 69 7a 65 20 28 6f 72 20 6e 6f 74 2c 20  ialize (or not, 
0a30: 73 65 65 0a 22 52 65 61 64 2d 55 6e 63 6f 6d 6d  see."Read-Uncomm
0a40: 69 74 74 65 64 20 49 73 6f 6c 61 74 69 6f 6e 20  itted Isolation 
0a50: 4d 6f 64 65 22 20 62 65 6c 6f 77 29 20 61 63 63  Mode" below) acc
0a60: 65 73 73 20 74 6f 20 74 68 65 20 73 68 61 72 65  ess to the share
0a70: 64 2d 63 61 63 68 65 20 62 79 0a 63 6f 6e 6e 65  d-cache by.conne
0a80: 63 74 69 6f 6e 73 20 32 20 61 6e 64 20 33 20 69  ctions 2 and 3 i
0a90: 73 20 64 65 73 63 72 69 62 65 64 20 69 6e 20 74  s described in t
0aa0: 68 65 20 72 65 6d 61 69 6e 64 65 72 20 6f 66 20  he remainder of 
0ab0: 74 68 69 73 20 73 65 63 74 69 6f 6e 2e 0a 3c 2f  this section..</
0ac0: 70 3e 0a 0a 3c 70 3e 54 68 65 72 65 20 61 72 65  p>..<p>There are
0ad0: 20 74 68 72 65 65 20 6c 65 76 65 6c 73 20 74 6f   three levels to
0ae0: 20 74 68 65 20 73 68 61 72 65 64 2d 63 61 63 68   the shared-cach
0af0: 65 20 6c 6f 63 6b 69 6e 67 20 6d 6f 64 65 6c 2c  e locking model,
0b00: 20 0a 74 72 61 6e 73 61 63 74 69 6f 6e 20 6c 65   .transaction le
0b10: 76 65 6c 20 6c 6f 63 6b 69 6e 67 2c 20 74 61 62  vel locking, tab
0b20: 6c 65 20 6c 65 76 65 6c 20 6c 6f 63 6b 69 6e 67  le level locking
0b30: 20 61 6e 64 20 73 63 68 65 6d 61 20 6c 65 76 65   and schema leve
0b40: 6c 20 6c 6f 63 6b 69 6e 67 2e 20 0a 54 68 65 79  l locking. .They
0b50: 20 61 72 65 20 64 65 73 63 72 69 62 65 64 20 69   are described i
0b60: 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
0b70: 74 68 72 65 65 20 73 75 62 2d 73 65 63 74 69 6f  three sub-sectio
0b80: 6e 73 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 54 72 61  ns.</p>..<h2>Tra
0b90: 6e 73 61 63 74 69 6f 6e 20 4c 65 76 65 6c 20 4c  nsaction Level L
0ba0: 6f 63 6b 69 6e 67 3c 2f 68 32 3e 0a 0a 3c 70 3e  ocking</h2>..<p>
0bb0: 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
0bc0: 6e 73 20 63 61 6e 20 6f 70 65 6e 20 74 77 6f 20  ns can open two 
0bd0: 6b 69 6e 64 73 20 6f 66 20 74 72 61 6e 73 61 63  kinds of transac
0be0: 74 69 6f 6e 73 2c 20 72 65 61 64 20 61 6e 64 20  tions, read and 
0bf0: 77 72 69 74 65 0a 74 72 61 6e 73 61 63 74 69 6f  write.transactio
0c00: 6e 73 2e 20 54 68 69 73 20 69 73 20 6e 6f 74 20  ns. This is not 
0c10: 64 6f 6e 65 20 65 78 70 6c 69 63 69 74 6c 79 2c  done explicitly,
0c20: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
0c30: 73 20 69 6d 70 6c 69 63 69 74 6c 79 20 61 0a 72  s implicitly a.r
0c40: 65 61 64 2d 74 72 61 6e 73 61 63 74 69 6f 6e 20  ead-transaction 
0c50: 75 6e 74 69 6c 20 69 74 20 66 69 72 73 74 20 77  until it first w
0c60: 72 69 74 65 73 20 74 6f 20 61 20 64 61 74 61 62  rites to a datab
0c70: 61 73 65 20 74 61 62 6c 65 2c 20 61 74 20 77 68  ase table, at wh
0c80: 69 63 68 20 70 6f 69 6e 74 0a 69 74 20 62 65 63  ich point.it bec
0c90: 6f 6d 65 73 20 61 20 77 72 69 74 65 2d 74 72 61  omes a write-tra
0ca0: 6e 73 61 63 74 69 6f 6e 2e 0a 3c 2f 70 3e 0a 3c  nsaction..</p>.<
0cb0: 70 3e 41 74 20 6d 6f 73 74 20 6f 6e 65 20 63 6f  p>At most one co
0cc0: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 61 20 73 69  nnection to a si
0cd0: 6e 67 6c 65 20 73 68 61 72 65 64 20 63 61 63 68  ngle shared cach
0ce0: 65 20 6d 61 79 20 6f 70 65 6e 20 61 20 0a 77 72  e may open a .wr
0cf0: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
0d00: 61 74 20 61 6e 79 20 6f 6e 65 20 74 69 6d 65 2e  at any one time.
0d10: 20 54 68 69 73 20 6d 61 79 20 63 6f 2d 65 78 69   This may co-exi
0d20: 73 74 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62  st with any numb
0d30: 65 72 20 6f 66 20 72 65 61 64 20 0a 74 72 61 6e  er of read .tran
0d40: 73 61 63 74 69 6f 6e 73 2e 20 0a 3c 2f 70 3e 0a  sactions. .</p>.
0d50: 0a 3c 68 32 3e 54 61 62 6c 65 20 4c 65 76 65 6c  .<h2>Table Level
0d60: 20 4c 6f 63 6b 69 6e 67 3c 2f 68 32 3e 0a 0a 3c   Locking</h2>..<
0d70: 70 3e 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f  p>When two or mo
0d80: 72 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 75  re connections u
0d90: 73 65 20 61 20 73 68 61 72 65 64 2d 63 61 63 68  se a shared-cach
0da0: 65 2c 20 6c 6f 63 6b 73 20 61 72 65 20 75 73 65  e, locks are use
0db0: 64 20 74 6f 20 0a 73 65 72 69 61 6c 69 7a 65 20  d to .serialize 
0dc0: 63 6f 6e 63 75 72 72 65 6e 74 20 61 63 63 65 73  concurrent acces
0dd0: 73 20 61 74 74 65 6d 70 74 73 20 6f 6e 20 61 20  s attempts on a 
0de0: 70 65 72 2d 74 61 62 6c 65 20 62 61 73 69 73 2e  per-table basis.
0df0: 20 54 61 62 6c 65 73 20 73 75 70 70 6f 72 74 20   Tables support 
0e00: 0a 74 77 6f 20 74 79 70 65 73 20 6f 66 20 6c 6f  .two types of lo
0e10: 63 6b 73 2c 20 22 72 65 61 64 2d 6c 6f 63 6b 73  cks, "read-locks
0e20: 22 20 61 6e 64 20 22 77 72 69 74 65 2d 6c 6f 63  " and "write-loc
0e30: 6b 73 22 2e 20 4c 6f 63 6b 73 20 61 72 65 20 67  ks". Locks are g
0e40: 72 61 6e 74 65 64 20 74 6f 0a 63 6f 6e 6e 65 63  ranted to.connec
0e50: 74 69 6f 6e 73 20 2d 20 61 74 20 61 6e 79 20 6f  tions - at any o
0e60: 6e 65 20 74 69 6d 65 2c 20 65 61 63 68 20 64 61  ne time, each da
0e70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
0e80: 6e 20 68 61 73 20 65 69 74 68 65 72 20 61 0a 72  n has either a.r
0e90: 65 61 64 2d 6c 6f 63 6b 2c 20 77 72 69 74 65 2d  ead-lock, write-
0ea0: 6c 6f 63 6b 20 6f 72 20 6e 6f 20 6c 6f 63 6b 20  lock or no lock 
0eb0: 6f 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65  on each database
0ec0: 20 74 61 62 6c 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70   table..</p>..<p
0ed0: 3e 41 74 20 61 6e 79 20 6f 6e 65 20 74 69 6d 65  >At any one time
0ee0: 2c 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  , a single table
0ef0: 20 6d 61 79 20 68 61 76 65 20 61 6e 79 20 6e 75   may have any nu
0f00: 6d 62 65 72 20 6f 66 20 61 63 74 69 76 65 20 72  mber of active r
0f10: 65 61 64 2d 6c 6f 63 6b 73 0a 6f 72 20 61 20 73  ead-locks.or a s
0f20: 69 6e 67 6c 65 20 61 63 74 69 76 65 20 77 72 69  ingle active wri
0f30: 74 65 20 6c 6f 63 6b 2e 20 54 6f 20 72 65 61 64  te lock. To read
0f40: 20 64 61 74 61 20 61 20 74 61 62 6c 65 2c 20 61   data a table, a
0f50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
0f60: 20 0a 66 69 72 73 74 20 6f 62 74 61 69 6e 20 61   .first obtain a
0f70: 20 72 65 61 64 2d 6c 6f 63 6b 2e 20 54 6f 20 77   read-lock. To w
0f80: 72 69 74 65 20 74 6f 20 61 20 74 61 62 6c 65 2c  rite to a table,
0f90: 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75   a connection mu
0fa0: 73 74 20 6f 62 74 61 69 6e 20 61 20 0a 77 72 69  st obtain a .wri
0fb0: 74 65 2d 6c 6f 63 6b 20 6f 6e 20 74 68 61 74 20  te-lock on that 
0fc0: 74 61 62 6c 65 2e 20 49 66 20 61 20 72 65 71 75  table. If a requ
0fd0: 69 72 65 64 20 74 61 62 6c 65 20 6c 6f 63 6b 20  ired table lock 
0fe0: 63 61 6e 6e 6f 74 20 62 65 20 6f 62 74 61 69 6e  cannot be obtain
0ff0: 65 64 2c 0a 74 68 65 20 71 75 65 72 79 20 66 61  ed,.the query fa
1000: 69 6c 73 20 61 6e 64 20 53 51 4c 49 54 45 5f 4c  ils and SQLITE_L
1010: 4f 43 4b 45 44 20 69 73 20 72 65 74 75 72 6e 65  OCKED is returne
1020: 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
1030: 0a 3c 2f 70 3e 20 0a 0a 3c 70 3e 4f 6e 63 65 20  .</p> ..<p>Once 
1040: 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 62 74  a connection obt
1050: 61 69 6e 73 20 61 20 74 61 62 6c 65 20 6c 6f 63  ains a table loc
1060: 6b 2c 20 69 74 20 69 73 20 6e 6f 74 20 72 65 6c  k, it is not rel
1070: 65 61 73 65 64 20 75 6e 74 69 6c 20 74 68 65 0a  eased until the.
1080: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
1090: 69 6f 6e 20 28 72 65 61 64 20 6f 72 20 77 72 69  ion (read or wri
10a0: 74 65 29 20 69 73 20 63 6f 6e 63 6c 75 64 65 64  te) is concluded
10b0: 2e 0a 3c 2f 70 3e 0a 0a 3c 68 33 3e 52 65 61 64  ..</p>..<h3>Read
10c0: 2d 55 6e 63 6f 6d 6d 69 74 74 65 64 20 49 73 6f  -Uncommitted Iso
10d0: 6c 61 74 69 6f 6e 20 4d 6f 64 65 3c 2f 68 33 3e  lation Mode</h3>
10e0: 0a 0a 3c 70 3e 54 68 65 20 62 65 68 61 76 69 6f  ..<p>The behavio
10f0: 75 72 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ur described abo
1100: 76 65 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69  ve may be modifi
1110: 65 64 20 73 6c 69 67 68 74 6c 79 20 62 79 20 75  ed slightly by u
1120: 73 69 6e 67 20 74 68 65 20 0a 5b 72 65 61 64 5f  sing the .[read_
1130: 75 6e 63 6f 6d 6d 69 74 74 65 64 5d 20 70 72 61  uncommitted] pra
1140: 67 6d 61 20 74 6f 20 63 68 61 6e 67 65 20 74 68  gma to change th
1150: 65 20 69 73 6f 6c 61 74 69 6f 6e 20 6c 65 76 65  e isolation leve
1160: 6c 20 66 72 6f 6d 20 73 65 72 69 61 6c 69 7a 65  l from serialize
1170: 64 20 0a 28 74 68 65 20 64 65 66 61 75 6c 74 29  d .(the default)
1180: 2c 20 74 6f 20 72 65 61 64 2d 75 6e 63 6f 6d 6d  , to read-uncomm
1190: 69 74 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 20  itted.</p>..<p> 
11a0: 41 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  A database conne
11b0: 63 74 69 6f 6e 20 69 6e 20 72 65 61 64 2d 75 6e  ction in read-un
11c0: 63 6f 6d 6d 69 74 74 65 64 20 6d 6f 64 65 20 64  committed mode d
11d0: 6f 65 73 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  oes not attempt 
11e0: 0a 74 6f 20 6f 62 74 61 69 6e 20 72 65 61 64 2d  .to obtain read-
11f0: 6c 6f 63 6b 73 20 62 65 66 6f 72 65 20 72 65 61  locks before rea
1200: 64 69 6e 67 20 66 72 6f 6d 20 64 61 74 61 62 61  ding from databa
1210: 73 65 20 74 61 62 6c 65 73 20 61 73 20 64 65 73  se tables as des
1220: 63 72 69 62 65 64 20 0a 61 62 6f 76 65 2e 20 54  cribed .above. T
1230: 68 69 73 20 63 61 6e 20 6c 65 61 64 20 74 6f 20  his can lead to 
1240: 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 71 75 65  inconsistent que
1250: 72 79 20 72 65 73 75 6c 74 73 20 69 66 20 61 6e  ry results if an
1260: 6f 74 68 65 72 20 64 61 74 61 62 61 73 65 0a 63  other database.c
1270: 6f 6e 6e 65 63 74 69 6f 6e 20 6d 6f 64 69 66 69  onnection modifi
1280: 65 73 20 61 20 74 61 62 6c 65 20 77 68 69 6c 65  es a table while
1290: 20 69 74 20 69 73 20 62 65 69 6e 67 20 72 65 61   it is being rea
12a0: 64 2c 20 62 75 74 20 69 74 20 61 6c 73 6f 20 6d  d, but it also m
12b0: 65 61 6e 73 20 74 68 61 74 0a 61 20 72 65 61 64  eans that.a read
12c0: 2d 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65  -transaction ope
12d0: 6e 65 64 20 62 79 20 61 20 63 6f 6e 6e 65 63 74  ned by a connect
12e0: 69 6f 6e 20 69 6e 20 72 65 61 64 2d 75 6e 63 6f  ion in read-unco
12f0: 6d 6d 69 74 74 65 64 20 6d 6f 64 65 20 63 61 6e  mmitted mode can
1300: 0a 6e 65 69 74 68 65 72 20 62 6c 6f 63 6b 20 6e  .neither block n
1310: 6f 72 20 62 65 20 62 6c 6f 63 6b 65 64 20 62 79  or be blocked by
1320: 20 61 6e 79 20 6f 74 68 65 72 20 63 6f 6e 6e 65   any other conne
1330: 63 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 52  ction.</p>..<p>R
1340: 65 61 64 2d 75 6e 63 6f 6d 6d 69 74 74 65 64 20  ead-uncommitted 
1350: 6d 6f 64 65 20 68 61 73 20 6e 6f 20 65 66 66 65  mode has no effe
1360: 63 74 20 6f 6e 20 74 68 65 20 6c 6f 63 6b 73 20  ct on the locks 
1370: 72 65 71 75 69 72 65 64 20 74 6f 20 77 72 69 74  required to writ
1380: 65 20 74 6f 0a 64 61 74 61 62 61 73 65 20 74 61  e to.database ta
1390: 62 6c 65 73 20 28 69 2e 65 2e 20 72 65 61 64 2d  bles (i.e. read-
13a0: 75 6e 63 6f 6d 6d 69 74 74 65 64 20 63 6f 6e 6e  uncommitted conn
13b0: 65 63 74 69 6f 6e 73 20 6d 75 73 74 20 73 74 69  ections must sti
13c0: 6c 6c 20 6f 62 74 61 69 6e 20 0a 77 72 69 74 65  ll obtain .write
13d0: 2d 6c 6f 63 6b 73 20 61 6e 64 20 68 65 6e 63 65  -locks and hence
13e0: 20 64 61 74 61 62 61 73 65 20 77 72 69 74 65 73   database writes
13f0: 20 6d 61 79 20 73 74 69 6c 6c 20 62 6c 6f 63 6b   may still block
1400: 20 6f 72 20 62 65 20 62 6c 6f 63 6b 65 64 29 2e   or be blocked).
1410: 20 0a 41 6c 73 6f 2c 20 72 65 61 64 2d 75 6e 63   .Also, read-unc
1420: 6f 6d 6d 69 74 74 65 64 20 6d 6f 64 65 20 68 61  ommitted mode ha
1430: 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 74  s no effect on t
1440: 68 65 20 3c 69 3e 73 71 6c 69 74 65 5f 6d 61 73  he <i>sqlite_mas
1450: 74 65 72 3c 2f 69 3e 20 0a 6c 6f 63 6b 73 20 72  ter</i> .locks r
1460: 65 71 75 69 72 65 64 20 62 79 20 74 68 65 20 72  equired by the r
1470: 75 6c 65 73 20 65 6e 75 6d 65 72 61 74 65 64 20  ules enumerated 
1480: 62 65 6c 6f 77 20 28 73 65 65 20 73 65 63 74 69  below (see secti
1490: 6f 6e 20 0a 22 53 63 68 65 6d 61 20 28 73 71 6c  on ."Schema (sql
14a0: 69 74 65 5f 6d 61 73 74 65 72 29 20 4c 65 76 65  ite_master) Leve
14b0: 6c 20 4c 6f 63 6b 69 6e 67 22 29 2e 0a 3c 2f 70  l Locking")..</p
14c0: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  >..<blockquote><
14d0: 70 72 65 3e 0a 20 20 2f 2a 20 53 65 74 20 74 68  pre>.  /* Set th
14e0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72  e value of the r
14f0: 65 61 64 2d 75 6e 63 6f 6d 6d 69 74 74 65 64 20  ead-uncommitted 
1500: 66 6c 61 67 3a 0a 20 20 2a 2a 0a 20 20 2a 2a 20  flag:.  **.  ** 
1510: 20 20 54 72 75 65 20 20 2d 3e 20 53 65 74 20 74    True  -> Set t
1520: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  he connection to
1530: 20 72 65 61 64 2d 75 6e 63 6f 6d 6d 69 74 74 65   read-uncommitte
1540: 64 20 6d 6f 64 65 2e 0a 20 20 2a 2a 20 20 20 46  d mode..  **   F
1550: 61 6c 73 65 20 2d 3e 20 53 65 74 20 74 68 65 20  alse -> Set the 
1560: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 73 65  connection to se
1570: 72 69 61 6c 69 7a 65 64 20 28 74 68 65 20 64 65  rialized (the de
1580: 66 61 75 6c 74 29 20 6d 6f 64 65 2e 0a 20 20 2a  fault) mode..  *
1590: 2f 0a 20 20 50 52 41 47 4d 41 20 72 65 61 64 5f  /.  PRAGMA read_
15a0: 75 6e 63 6f 6d 6d 69 74 74 65 64 20 3d 20 26 6c  uncommitted = &l
15b0: 74 3b 62 6f 6f 6c 65 61 6e 26 67 74 3b 3b 0a 0a  t;boolean&gt;;..
15c0: 20 20 2f 2a 20 52 65 74 72 69 65 76 65 20 74 68    /* Retrieve th
15d0: 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
15e0: 6f 66 20 74 68 65 20 72 65 61 64 2d 75 6e 63 6f  of the read-unco
15f0: 6d 6d 69 74 74 65 64 20 66 6c 61 67 20 2a 2f 0a  mmitted flag */.
1600: 20 20 50 52 41 47 4d 41 20 72 65 61 64 5f 75 6e    PRAGMA read_un
1610: 63 6f 6d 6d 69 74 74 65 64 3b 0a 3c 2f 70 72 65  committed;.</pre
1620: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
1630: 3c 68 32 3e 53 63 68 65 6d 61 20 28 73 71 6c 69  <h2>Schema (sqli
1640: 74 65 5f 6d 61 73 74 65 72 29 20 4c 65 76 65 6c  te_master) Level
1650: 20 4c 6f 63 6b 69 6e 67 3c 2f 68 32 3e 0a 0a 3c   Locking</h2>..<
1660: 70 3e 54 68 65 20 3c 69 3e 73 71 6c 69 74 65 5f  p>The <i>sqlite_
1670: 6d 61 73 74 65 72 3c 2f 69 3e 20 74 61 62 6c 65  master</i> table
1680: 20 73 75 70 70 6f 72 74 73 20 73 68 61 72 65 64   supports shared
1690: 2d 63 61 63 68 65 20 72 65 61 64 20 61 6e 64 20  -cache read and 
16a0: 77 72 69 74 65 20 0a 6c 6f 63 6b 73 20 69 6e 20  write .locks in 
16b0: 74 68 65 20 73 61 6d 65 20 77 61 79 20 61 73 20  the same way as 
16c0: 61 6c 6c 20 6f 74 68 65 72 20 64 61 74 61 62 61  all other databa
16d0: 73 65 20 74 61 62 6c 65 73 20 28 73 65 65 20 64  se tables (see d
16e0: 65 73 63 72 69 70 74 69 6f 6e 20 0a 61 62 6f 76  escription .abov
16f0: 65 29 2e 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  e). The followin
1700: 67 20 73 70 65 63 69 61 6c 20 72 75 6c 65 73 20  g special rules 
1710: 61 6c 73 6f 20 61 70 70 6c 79 3a 0a 3c 2f 70 3e  also apply:.</p>
1720: 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 41 20 63 6f 6e  ..<ul>.<li>A con
1730: 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 74  nection must obt
1740: 61 69 6e 20 61 20 72 65 61 64 2d 6c 6f 63 6b 20  ain a read-lock 
1750: 6f 6e 20 3c 69 3e 73 71 6c 69 74 65 5f 6d 61 73  on <i>sqlite_mas
1760: 74 65 72 3c 2f 69 3e 20 62 65 66 6f 72 65 20 0a  ter</i> before .
1770: 61 63 63 65 73 73 69 6e 67 20 61 6e 79 20 64 61  accessing any da
1780: 74 61 62 61 73 65 20 74 61 62 6c 65 73 20 6f 72  tabase tables or
1790: 20 6f 62 74 61 69 6e 69 6e 67 20 61 6e 79 20 6f   obtaining any o
17a0: 74 68 65 72 20 72 65 61 64 20 6f 72 20 77 72 69  ther read or wri
17b0: 74 65 20 6c 6f 63 6b 73 2e 3c 2f 6c 69 3e 0a 3c  te locks.</li>.<
17c0: 6c 69 3e 42 65 66 6f 72 65 20 65 78 65 63 75 74  li>Before execut
17d0: 69 6e 67 20 61 20 73 74 61 74 65 6d 65 6e 74 20  ing a statement 
17e0: 74 68 61 74 20 6d 6f 64 69 66 69 65 73 20 74 68  that modifies th
17f0: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1800: 61 20 28 69 2e 65 2e 20 0a 61 20 43 52 45 41 54  a (i.e. .a CREAT
1810: 45 20 6f 72 20 44 52 4f 50 20 54 41 42 4c 45 20  E or DROP TABLE 
1820: 73 74 61 74 65 6d 65 6e 74 29 2c 20 61 20 63 6f  statement), a co
1830: 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  nnection must ob
1840: 74 61 69 6e 20 61 20 77 72 69 74 65 2d 6c 6f 63  tain a write-loc
1850: 6b 20 6f 6e 20 0a 3c 69 3e 73 71 6c 69 74 65 5f  k on .<i>sqlite_
1860: 6d 61 73 74 65 72 3c 2f 69 3e 2e 0a 3c 2f 6c 69  master</i>..</li
1870: 3e 0a 3c 6c 69 3e 41 20 63 6f 6e 6e 65 63 74 69  >.<li>A connecti
1880: 6f 6e 20 6d 61 79 20 6e 6f 74 20 63 6f 6d 70 69  on may not compi
1890: 6c 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  le an SQL statem
18a0: 65 6e 74 20 69 66 20 61 6e 79 20 6f 74 68 65 72  ent if any other
18b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 69 73 20 68   connection.is h
18c0: 6f 6c 64 69 6e 67 20 61 20 77 72 69 74 65 2d 6c  olding a write-l
18d0: 6f 63 6b 20 6f 6e 20 74 68 65 20 3c 69 3e 73 71  ock on the <i>sq
18e0: 6c 69 74 65 5f 6d 61 73 74 65 72 3c 2f 69 3e 20  lite_master</i> 
18f0: 74 61 62 6c 65 20 6f 66 20 61 6e 79 20 61 74 74  table of any att
1900: 61 63 68 65 64 0a 64 61 74 61 62 61 73 65 20 28  ached.database (
1910: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 64 65  including the de
1920: 66 61 75 6c 74 20 64 61 74 61 62 61 73 65 2c 20  fault database, 
1930: 22 6d 61 69 6e 22 29 2e 20 0a 3c 2f 6c 69 3e 0a  "main"). .</li>.
1940: 3c 2f 75 6c 3e 0a 0a 3c 68 31 3e 54 68 72 65 61  </ul>..<h1>Threa
1950: 64 20 52 65 6c 61 74 65 64 20 49 73 73 75 65 73  d Related Issues
1960: 3c 2f 68 31 3e 0a 0a 3c 70 3e 49 6e 20 53 51 4c  </h1>..<p>In SQL
1970: 69 74 65 20 76 65 72 73 69 6f 6e 73 20 33 2e 33  ite versions 3.3
1980: 2e 30 20 74 68 72 6f 75 67 68 20 33 2e 34 2e 32  .0 through 3.4.2
1990: 20 77 68 65 6e 20 73 68 61 72 65 64 2d 63 61 63   when shared-cac
19a0: 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
19b0: 65 64 2c 20 0a 61 20 64 61 74 61 62 61 73 65 20  ed, .a database 
19c0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 61 79 20 6f  connection may o
19d0: 6e 6c 79 20 62 65 0a 75 73 65 64 20 62 79 20 74  nly be.used by t
19e0: 68 65 20 74 68 72 65 61 64 20 74 68 61 74 20 63  he thread that c
19f0: 61 6c 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  alled [sqlite3_o
1a00: 70 65 6e 28 29 5d 20 74 6f 20 63 72 65 61 74 65  pen()] to create
1a10: 20 69 74 2e 0a 41 6e 64 20 61 20 63 6f 6e 6e 65   it..And a conne
1a20: 63 74 69 6f 6e 20 63 6f 75 6c 64 20 6f 6e 6c 79  ction could only
1a30: 20 73 68 61 72 65 20 63 61 63 68 65 20 77 69 74   share cache wit
1a40: 68 20 61 6e 6f 74 68 65 72 20 63 6f 6e 6e 65 63  h another connec
1a50: 74 69 6f 6e 20 69 6e 20 74 68 65 0a 73 61 6d 65  tion in the.same
1a60: 20 74 68 72 65 61 64 2e 0a 54 68 65 73 65 20 72   thread..These r
1a70: 65 73 74 72 69 63 74 69 6f 6e 73 20 77 65 72 65  estrictions were
1a80: 20 64 72 6f 70 70 65 64 20 62 65 67 69 6e 6e 69   dropped beginni
1a90: 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 0a  ng with SQLite .
1aa0: 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 5d 20  [version 3.5.0] 
1ab0: 28 5b 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 29  ([dateof:3.5.0])
1ac0: 2e 0a 3c 2f 70 3e 0a 0a 3c 68 31 3e 53 68 61 72  ..</p>..<h1>Shar
1ad0: 65 64 20 43 61 63 68 65 20 41 6e 64 20 56 69 72  ed Cache And Vir
1ae0: 74 75 61 6c 20 54 61 62 6c 65 73 3c 2f 68 31 3e  tual Tables</h1>
1af0: 0a 0a 3c 70 3e 0a 49 6e 20 6f 6c 64 65 72 20 76  ..<p>.In older v
1b00: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1b10: 65 2c 0a 73 68 61 72 65 64 20 63 61 63 68 65 20  e,.shared cache 
1b20: 6d 6f 64 65 20 63 6f 75 6c 64 20 6e 6f 74 20 62  mode could not b
1b30: 65 20 75 73 65 64 20 74 6f 67 65 74 68 65 72 20  e used together 
1b40: 77 69 74 68 20 76 69 72 74 75 61 6c 20 74 61 62  with virtual tab
1b50: 6c 65 73 2e 0a 54 68 69 73 20 72 65 73 74 72 69  les..This restri
1b60: 63 74 69 6f 6e 20 77 61 73 20 72 65 6d 6f 76 65  ction was remove
1b70: 64 20 69 6e 20 53 51 4c 69 74 65 20 5b 76 65 72  d in SQLite [ver
1b80: 73 69 6f 6e 20 33 2e 36 2e 31 37 5d 20 28 5b 64  sion 3.6.17] ([d
1b90: 61 74 65 6f 66 3a 33 2e 36 2e 31 37 5d 29 2e 0a  ateof:3.6.17])..
1ba0: 0a 3c 68 31 3e 45 6e 61 62 6c 69 6e 67 20 53 68  .<h1>Enabling Sh
1bb0: 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 3c  ared-Cache Mode<
1bc0: 2f 68 31 3e 0a 0a 3c 70 3e 53 68 61 72 65 64 2d  /h1>..<p>Shared-
1bd0: 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
1be0: 61 62 6c 65 64 20 6f 6e 20 61 20 70 65 72 2d 70  abled on a per-p
1bf0: 72 6f 63 65 73 73 20 62 61 73 69 73 2e 20 55 73  rocess basis. Us
1c00: 69 6e 67 20 74 68 65 20 43 20 0a 69 6e 74 65 72  ing the C .inter
1c10: 66 61 63 65 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  face, the follow
1c20: 69 6e 67 20 41 50 49 20 63 61 6e 20 62 65 20 75  ing API can be u
1c30: 73 65 64 20 74 6f 20 67 6c 6f 62 61 6c 6c 79 20  sed to globally 
1c40: 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
1c50: 65 0a 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  e.shared-cache m
1c60: 6f 64 65 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  ode:.</p>..<bloc
1c70: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 69 6e 74  kquote><pre>.int
1c80: 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
1c90: 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74  shared_cache(int
1ca0: 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  );.</pre></block
1cb0: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 45 61 63 68 20  quote>..<p>Each 
1cc0: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1cd0: 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
1ce0: 61 63 68 65 28 29 5d 20 61 66 66 65 63 74 73 20  ache()] affects 
1cf0: 73 75 62 73 65 71 75 65 6e 74 20 64 61 74 61 62  subsequent datab
1d00: 61 73 65 0a 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase.connections 
1d10: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
1d20: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1d30: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1d40: 29 5d 2c 20 6f 72 0a 5b 73 71 6c 69 74 65 33 5f  )], or.[sqlite3_
1d50: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 44 61 74  open_v2()].  Dat
1d60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d70: 73 20 74 68 61 74 20 61 6c 72 65 61 64 79 20 65  s that already e
1d80: 78 69 73 74 20 61 72 65 0a 75 6e 61 66 66 65 63  xist are.unaffec
1d90: 74 65 64 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ted.  Each call 
1da0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  to [sqlite3_enab
1db0: 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
1dc0: 29 5d 20 6f 76 65 72 72 69 64 65 73 0a 61 6c 6c  )] overrides.all
1dd0: 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 73 20   previous calls 
1de0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
1df0: 70 72 6f 63 65 73 73 2e 0a 3c 2f 70 3e 0a 0a 3c  process..</p>..<
1e00: 70 3e 49 6e 64 69 76 69 64 75 61 6c 20 64 61 74  p>Individual dat
1e10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e20: 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  s created using 
1e30: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1e40: 28 29 5d 20 63 61 6e 0a 63 68 6f 6f 73 65 20 74  ()] can.choose t
1e50: 6f 20 70 61 72 74 69 63 69 70 61 74 65 20 6f 72  o participate or
1e60: 20 6e 6f 74 20 70 61 72 74 69 63 69 70 61 74 65   not participate
1e70: 20 69 6e 20 73 68 61 72 65 64 20 63 61 63 68 65   in shared cache
1e80: 20 6d 6f 64 65 20 62 79 20 75 73 69 6e 67 0a 74   mode by using.t
1e90: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1ea0: 53 48 41 52 45 44 43 41 43 48 45 5d 20 6f 72 20  SHAREDCACHE] or 
1eb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
1ec0: 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73  VATECACHE] flags
1ed0: 20 74 68 65 0a 74 68 69 72 64 20 70 61 72 61 6d   the.third param
1ee0: 65 74 65 72 2e 20 20 54 68 65 20 75 73 65 20 6f  eter.  The use o
1ef0: 66 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  f either of thes
1f00: 65 20 66 6c 61 67 73 20 6f 76 65 72 72 69 64 65  e flags override
1f10: 73 20 74 68 65 0a 67 6c 6f 62 61 6c 20 73 68 61  s the.global sha
1f20: 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 20 73  red cache mode s
1f30: 65 74 74 69 6e 67 20 65 73 74 61 62 6c 69 73 68  etting establish
1f40: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65  ed by [sqlite3_e
1f50: 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
1f60: 68 65 28 29 5d 2e 0a 4e 6f 20 6d 6f 72 65 20 74  he()]..No more t
1f70: 68 61 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  han one of the f
1f80: 6c 61 67 73 20 73 68 6f 75 6c 64 20 62 65 20 75  lags should be u
1f90: 73 65 64 3b 20 69 66 20 62 6f 74 68 20 53 51 4c  sed; if both SQL
1fa0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1fb0: 41 43 48 45 0a 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE.and SQLITE_
1fc0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1fd0: 45 20 66 6c 61 67 73 20 61 72 65 20 75 73 65 64  E flags are used
1fe0: 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72   in the third ar
1ff0: 67 75 6d 65 6e 74 20 74 6f 0a 5b 73 71 6c 69 74  gument to.[sqlit
2000: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 74 68  e3_open_v2()] th
2010: 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2020: 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 70  is undefined.</p
2030: 3e 0a 0a 3c 70 3e 57 68 65 6e 20 5b 55 52 49 20  >..<p>When [URI 
2040: 66 69 6c 65 6e 61 6d 65 73 5d 20 61 72 65 20 75  filenames] are u
2050: 73 65 64 2c 20 74 68 65 20 22 63 61 63 68 65 22  sed, the "cache"
2060: 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
2070: 20 63 61 6e 20 62 65 20 75 73 65 64 0a 74 6f 20   can be used.to 
2080: 73 70 65 63 69 66 79 20 77 68 65 74 68 65 72 20  specify whether 
2090: 6f 72 20 6e 6f 74 20 74 68 65 20 64 61 74 61 62  or not the datab
20a0: 61 73 65 20 77 69 6c 6c 20 75 73 65 20 73 68 61  ase will use sha
20b0: 72 65 64 20 63 61 63 68 65 2e 20 20 55 73 65 0a  red cache.  Use.
20c0: 22 63 61 63 68 65 3d 73 68 61 72 65 64 22 20 74  "cache=shared" t
20d0: 6f 20 65 6e 61 62 6c 65 20 73 68 61 72 65 64 20  o enable shared 
20e0: 63 61 63 68 65 20 61 6e 64 20 22 63 61 63 68 65  cache and "cache
20f0: 3d 70 72 69 76 61 74 65 22 20 74 6f 20 64 69 73  =private" to dis
2100: 61 62 6c 65 0a 73 68 61 72 65 64 20 63 61 63 68  able.shared cach
2110: 65 2e 20 20 20 54 68 65 20 61 62 69 6c 69 74 79  e.   The ability
2120: 20 74 6f 20 75 73 65 20 55 52 49 20 71 75 65 72   to use URI quer
2130: 79 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  y parameters to 
2140: 73 70 65 63 69 66 79 20 74 68 65 0a 63 61 63 68  specify the.cach
2150: 65 20 73 68 61 72 69 6e 67 20 62 65 68 61 76 69  e sharing behavi
2160: 6f 72 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  or of a database
2170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6c 6c 6f   connection allo
2180: 77 73 20 63 61 63 68 65 20 73 68 61 72 69 6e 67  ws cache sharing
2190: 20 74 6f 0a 62 65 20 63 6f 6e 74 72 6f 6c 6c 65   to.be controlle
21a0: 64 20 69 6e 20 5b 41 54 54 41 43 48 5d 20 73 74  d in [ATTACH] st
21b0: 61 74 65 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65  atements.  For e
21c0: 78 61 6d 70 6c 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c  xample:</p>..<bl
21d0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 41  ockquote><pre>.A
21e0: 54 54 41 43 48 20 27 66 69 6c 65 3a 61 75 78 2e  TTACH 'file:aux.
21f0: 64 62 3f 63 61 63 68 65 3d 73 68 61 72 65 64 27  db?cache=shared'
2200: 20 41 53 20 61 75 78 3b 0a 3c 2f 70 72 65 3e 3c   AS aux;.</pre><
2210: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 74  /blockquote>..<t
2220: 63 6c 3e 20 68 64 5f 66 72 61 67 6d 65 6e 74 20  cl> hd_fragment 
2230: 69 6e 6d 65 6d 73 68 61 72 65 64 63 61 63 68 65  inmemsharedcache
2240: 20 7b 69 6e 2d 6d 65 6d 6f 72 79 20 73 68 61 72   {in-memory shar
2250: 65 64 2d 63 61 63 68 65 7d 20 3c 2f 74 63 6c 3e  ed-cache} </tcl>
2260: 0a 3c 68 31 3e 53 68 61 72 65 64 20 43 61 63 68  .<h1>Shared Cach
2270: 65 20 41 6e 64 20 49 6e 2d 4d 65 6d 6f 72 79 20  e And In-Memory 
2280: 44 61 74 61 62 61 73 65 73 3c 2f 68 31 3e 0a 0a  Databases</h1>..
2290: 3c 70 3e 0a 42 65 67 69 6e 6e 69 6e 67 20 77 69  <p>.Beginning wi
22a0: 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  th SQLite [versi
22b0: 6f 6e 20 33 2e 37 2e 31 33 5d 20 28 5b 64 61 74  on 3.7.13] ([dat
22c0: 65 6f 66 3a 33 2e 37 2e 31 33 5d 29 2c 20 0a 73  eof:3.7.13]), .s
22d0: 68 61 72 65 64 20 63 61 63 68 65 20 63 61 6e 20  hared cache can 
22e0: 62 65 20 75 73 65 64 20 6f 6e 0a 5b 69 6e 2d 6d  be used on.[in-m
22f0: 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 73 5d  emory databases]
2300: 2c 20 70 72 6f 76 69 64 65 64 20 74 68 61 74 20  , provided that 
2310: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
2320: 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 61 20  created using.a 
2330: 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 2e 20  [URI filename]. 
2340: 20 46 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   For backwards c
2350: 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 73 68  ompatibility, sh
2360: 61 72 65 64 20 63 61 63 68 65 20 69 73 20 61 6c  ared cache is al
2370: 77 61 79 73 0a 64 69 73 61 62 6c 65 20 66 6f 72  ways.disable for
2380: 20 69 6e 2d 6d 65 6d 6f 72 79 0a 64 61 74 61 62   in-memory.datab
2390: 61 73 65 73 20 69 66 20 74 68 65 20 75 6e 61 64  ases if the unad
23a0: 6f 72 6e 65 64 20 6e 61 6d 65 20 22 3a 6d 65 6d  orned name ":mem
23b0: 6f 72 79 3a 22 20 69 73 20 75 73 65 64 20 74 6f  ory:" is used to
23c0: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
23d0: 73 65 2e 0a 50 72 69 6f 72 20 74 6f 20 76 65 72  se..Prior to ver
23e0: 73 69 6f 6e 20 33 2e 37 2e 31 33 2c 20 73 68 61  sion 3.7.13, sha
23f0: 72 65 64 20 63 61 63 68 65 20 77 61 73 20 61 6c  red cache was al
2400: 77 61 79 73 0a 64 69 73 61 62 6c 65 64 20 66 6f  ways.disabled fo
2410: 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  r in-memory data
2420: 62 61 73 65 73 20 72 65 67 61 72 64 6c 65 73 73  bases regardless
2430: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2440: 20 6e 61 6d 65 20 75 73 65 64 2c 0a 63 75 72 72   name used,.curr
2450: 65 6e 74 20 73 79 73 74 65 6d 20 73 68 61 72 65  ent system share
2460: 64 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 2c  d cache setting,
2470: 20 6f 72 20 71 75 65 72 79 20 70 61 72 61 6d 65   or query parame
2480: 74 65 72 73 20 6f 72 20 66 6c 61 67 73 2e 0a 3c  ters or flags..<
2490: 2f 70 3e 0a 0a 3c 70 3e 0a 45 6e 61 62 6c 69 6e  /p>..<p>.Enablin
24a0: 67 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 66  g shared-cache f
24b0: 6f 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20  or an in-memory 
24c0: 64 61 74 61 62 61 73 65 20 61 6c 6c 6f 77 73 20  database allows 
24d0: 74 77 6f 20 6f 72 20 6d 6f 72 65 0a 64 61 74 61  two or more.data
24e0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
24f0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f   in the same pro
2500: 63 65 73 73 20 74 6f 20 68 61 76 65 20 61 63 63  cess to have acc
2510: 65 73 73 20 74 6f 20 74 68 65 20 73 61 6d 65 0a  ess to the same.
2520: 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
2530: 73 65 2e 20 20 41 6e 20 69 6e 2d 6d 65 6d 6f 72  se.  An in-memor
2540: 79 20 64 61 74 61 62 61 73 65 20 69 6e 20 73 68  y database in sh
2550: 61 72 65 64 20 63 61 63 68 65 20 69 73 20 61 75  ared cache is au
2560: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 64 65 6c 65  tomatically.dele
2570: 74 65 64 20 61 6e 64 20 6d 65 6d 6f 72 79 20 69  ted and memory i
2580: 73 20 72 65 63 6c 61 69 6d 65 64 20 77 68 65 6e  s reclaimed when
2590: 20 74 68 65 20 6c 61 73 74 20 63 6f 6e 6e 65 63   the last connec
25a0: 74 69 6f 6e 20 74 6f 20 74 68 61 74 20 64 61 74  tion to that dat
25b0: 61 62 61 73 65 0a 63 6c 6f 73 65 73 2e 0a 3c 2f  abase.closes..</
25c0: 70 3e 0a                                         p>.