Documentation Source Text

Hex Artifact Content
Login

Artifact 0a74e1471cdc18271e4704a80d8e0cafc6fcaf55:


0000: 3c 74 69 74 6c 65 3e 55 6e 69 66 6f 72 6d 20 52  <title>Uniform R
0010: 65 73 6f 75 72 63 65 20 49 64 65 6e 74 69 66 69  esource Identifi
0020: 65 72 73 3c 2f 74 69 74 6c 65 3e 0a 3c 74 63 6c  ers</title>.<tcl
0030: 3e 0a 68 64 5f 6b 65 79 77 6f 72 64 73 20 7b 55  >.hd_keywords {U
0040: 52 49 7d 20 7b 55 6e 69 66 6f 72 6d 20 52 65 73  RI} {Uniform Res
0050: 6f 75 72 63 65 20 49 64 65 6e 74 69 66 69 65 72  ource Identifier
0060: 7d 20 7b 55 52 49 20 66 69 6c 65 6e 61 6d 65 7d  } {URI filename}
0070: 20 7b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 7d   {URI filenames}
0080: 0a 3c 2f 74 63 6c 3e 0a 0a 3c 68 31 3e 31 2e 30  .</tcl>..<h1>1.0
0090: 20 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 20 49   URI Filenames I
00a0: 6e 20 53 51 4c 69 74 65 3c 2f 68 31 3e 0a 0a 3c  n SQLite</h1>..<
00b0: 70 3e 0a 42 65 67 69 6e 6e 69 6e 67 20 77 69 74  p>.Beginning wit
00c0: 68 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  h [version 3.7.7
00d0: 5d 2c 20 74 68 65 20 53 51 4c 69 74 65 20 64 61  ], the SQLite da
00e0: 74 61 62 61 73 65 20 66 69 6c 65 20 61 72 67 75  tabase file argu
00f0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 5b 73 71 6c  ment to the.[sql
0100: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
0110: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
0120: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
0130: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
0140: 61 63 65 73 0a 61 6e 64 20 74 6f 20 74 68 65 20  aces.and to the 
0150: 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
0160: 20 63 61 6e 20 62 65 20 73 70 65 63 69 66 69 65   can be specifie
0170: 64 0a 65 69 74 68 65 72 20 61 73 20 61 6e 20 6f  d.either as an o
0180: 72 64 69 6e 61 72 79 20 66 69 6c 65 6e 61 6d 65  rdinary filename
0190: 20 6f 72 20 61 73 20 61 20 55 6e 69 66 6f 72 6d   or as a Uniform
01a0: 20 52 65 73 6f 75 72 63 65 20 49 64 65 6e 74 69   Resource Identi
01b0: 66 69 65 72 20 6f 72 20 55 52 49 2e 0a 54 68 65  fier or URI..The
01c0: 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 75 73   advantage of us
01d0: 69 6e 67 20 61 20 55 52 49 20 66 69 6c 65 6e 61  ing a URI filena
01e0: 6d 65 20 69 73 20 74 68 61 74 20 71 75 65 72 79  me is that query
01f0: 20 70 61 72 61 6d 65 74 65 72 73 20 6f 6e 20 74   parameters on t
0200: 68 65 20 55 52 49 20 63 61 6e 0a 62 65 20 75 73  he URI can.be us
0210: 65 64 20 74 6f 20 63 6f 6e 74 72 6f 6c 20 64 65  ed to control de
0220: 74 61 69 6c 73 20 6f 66 20 74 68 65 20 6e 65 77  tails of the new
0230: 6c 79 20 63 72 65 61 74 65 64 20 64 61 74 61 62  ly created datab
0240: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
0250: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
0260: 61 6c 74 65 72 6e 61 74 69 76 65 20 5b 56 46 53  alternative [VFS
0270: 5d 20 63 61 6e 20 62 65 20 73 70 65 63 69 66 69  ] can be specifi
0280: 65 64 20 75 73 69 6e 67 20 61 20 0a 22 76 66 73  ed using a ."vfs
0290: 3d 22 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  =" query paramet
02a0: 65 72 2e 0a 4f 72 20 74 68 65 20 64 61 74 61 62  er..Or the datab
02b0: 61 73 65 20 63 61 6e 20 62 65 20 6f 70 65 6e 65  ase can be opene
02c0: 64 20 72 65 61 64 2d 6f 6e 6c 79 20 62 79 20 75  d read-only by u
02d0: 73 69 6e 67 20 22 6d 6f 64 65 3d 72 6f 22 20 61  sing "mode=ro" a
02e0: 73 20 61 20 71 75 65 72 79 0a 70 61 72 61 6d 65  s a query.parame
02f0: 74 65 72 2e 0a 3c 2f 70 3e 0a 0a 3c 68 31 3e 32  ter..</p>..<h1>2
0300: 2e 30 20 42 61 63 6b 77 61 72 64 73 20 43 6f 6d  .0 Backwards Com
0310: 70 61 74 69 62 69 6c 69 74 79 3c 2f 68 31 3e 0a  patibility</h1>.
0320: 0a 3c 70 3e 0a 5e 49 6e 20 6f 72 64 65 72 20 74  .<p>.^In order t
0330: 6f 20 6d 61 69 6e 74 61 69 6e 20 66 75 6c 6c 20  o maintain full 
0340: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0350: 69 62 69 6c 69 74 79 20 66 6f 72 20 6c 65 67 61  ibility for lega
0360: 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 2c  cy applications,
0370: 0a 74 68 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  .the URI filenam
0380: 65 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20  e capability is 
0390: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
03a0: 75 6c 74 2e 0a 5e 55 52 49 20 66 69 6c 65 6e 61  ult..^URI filena
03b0: 6d 65 73 20 63 61 6e 20 62 65 20 65 6e 61 62 6c  mes can be enabl
03c0: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 75  ed or disabled u
03d0: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
03e0: 5f 55 53 45 5f 55 52 49 3d 31 5d 0a 6f 72 20 5b  _USE_URI=1].or [
03f0: 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 3d 30  SQLITE_USE_URI=0
0400: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
0410: 70 74 69 6f 6e 73 2e 0a 5e 54 68 65 20 63 6f 6d  ptions..^The com
0420: 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e  pile-time settin
0430: 67 20 66 6f 72 20 55 52 49 20 66 69 6c 65 6e 61  g for URI filena
0440: 6d 65 73 20 63 61 6e 20 62 65 20 63 68 61 6e 67  mes can be chang
0450: 65 64 0a 61 74 20 73 74 61 72 74 2d 74 69 6d 65  ed.at start-time
0460: 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
0470: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
0480: 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 2c  ITE_CONFIG_URI],
0490: 31 29 0a 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  1).or [sqlite3_c
04a0: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
04b0: 4f 4e 46 49 47 5f 55 52 49 5d 2c 30 29 20 63 6f  ONFIG_URI],0) co
04c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 63 61 6c 6c  nfiguration call
04d0: 73 2e 0a 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  s..^Regardless o
04e0: 66 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  f the compile-ti
04f0: 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
0500: 20 73 65 74 74 69 6e 67 73 2c 20 55 52 49 20 66   settings, URI f
0510: 69 6c 65 6e 61 6d 65 73 0a 63 61 6e 20 62 65 20  ilenames.can be 
0520: 65 6e 61 62 6c 65 64 20 66 6f 72 20 69 6e 64 69  enabled for indi
0530: 76 69 64 75 61 6c 20 64 61 74 61 62 61 73 65 20  vidual database 
0540: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 79 20 69  connections by i
0550: 6e 63 6c 75 64 69 6e 67 20 74 68 65 0a 5b 53 51  ncluding the.[SQ
0560: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 62  LITE_OPEN_URI] b
0570: 69 74 20 69 6e 20 74 68 65 20 73 65 74 20 6f 66  it in the set of
0580: 20 62 69 74 73 20 70 61 73 73 65 64 20 61 73 20   bits passed as 
0590: 74 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 0a  the F parameter.
05a0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
05b0: 5f 76 32 28 4e 2c 50 2c 46 2c 56 29 5d 2e 0a 3c  _v2(N,P,F,V)]..<
05c0: 2f 70 3e 0a 0a 3c 70 3e 0a 5e 49 66 20 55 52 49  /p>..<p>.^If URI
05d0: 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 72   filenames are r
05e0: 65 63 6f 67 6e 69 7a 65 64 20 77 68 65 6e 20 74  ecognized when t
05f0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
0600: 65 63 74 69 6f 6e 20 69 73 20 6f 72 69 67 69 6e  ection is origin
0610: 61 6c 6c 79 0a 6f 70 65 6e 65 64 2c 20 74 68 65  ally.opened, the
0620: 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  n URI filenames 
0630: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 72 65 63  will also be rec
0640: 6f 67 6e 69 7a 65 64 20 6f 6e 20 5b 41 54 54 41  ognized on [ATTA
0650: 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CH] statements..
0660: 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 69 66 20 55  ^Similarly, if U
0670: 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
0680: 20 6e 6f 74 20 72 65 63 6f 67 6e 69 7a 65 64 20   not recognized 
0690: 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
06a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 69 73 20  e connection.is 
06b0: 66 69 72 73 74 20 6f 70 65 6e 65 64 2c 20 74 68  first opened, th
06c0: 65 79 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 72  ey will not be r
06d0: 65 63 6f 67 6e 69 7a 65 64 20 62 79 20 5b 41 54  ecognized by [AT
06e0: 54 41 43 48 5d 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  TACH]..</p>..<p>
06f0: 0a 53 69 6e 63 65 20 53 51 4c 69 74 65 20 61 6c  .Since SQLite al
0700: 77 61 79 73 20 69 6e 74 65 72 70 72 65 74 73 20  ways interprets 
0710: 61 6e 79 20 66 69 6c 65 6e 61 6d 65 20 74 68 61  any filename tha
0720: 74 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  t does not begin
0730: 0a 77 69 74 68 20 22 3c 74 74 3e 66 69 6c 65 3a  .with "<tt>file:
0740: 3c 2f 74 74 3e 22 0a 61 73 20 61 6e 20 6f 72 64  </tt>".as an ord
0750: 69 6e 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 72  inary filename r
0760: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
0770: 20 55 52 49 20 73 65 74 74 69 6e 67 2c 20 61 6e   URI setting, an
0780: 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 0a  d because it is.
0790: 76 65 72 79 20 75 6e 75 73 75 61 6c 20 74 6f 20  very unusual to 
07a0: 68 61 76 65 20 61 6e 20 61 63 74 75 61 6c 20 66  have an actual f
07b0: 69 6c 65 20 62 65 67 69 6e 20 77 69 74 68 20 22  ile begin with "
07c0: 3c 74 74 3e 66 69 6c 65 3a 3c 2f 74 74 3e 22 2c  <tt>file:</tt>",
07d0: 20 0a 69 74 20 69 73 20 73 61 66 65 20 66 6f 72   .it is safe for
07e0: 20 6d 6f 73 74 20 61 70 70 6c 69 63 61 74 69 6f   most applicatio
07f0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 55 52 49  ns to enable URI
0800: 20 70 72 6f 63 65 73 73 69 6e 67 20 65 76 65 6e   processing even
0810: 20 69 66 20 55 52 49 20 0a 66 69 6c 65 6e 61 6d   if URI .filenam
0820: 65 73 20 61 72 65 20 6e 6f 74 20 63 75 72 72 65  es are not curre
0830: 6e 74 6c 79 20 62 65 69 6e 67 20 75 73 65 64 2e  ntly being used.
0840: 0a 3c 2f 70 3e 0a 0a 3c 68 31 3e 33 2e 30 20 55  .</p>..<h1>3.0 U
0850: 52 49 20 46 6f 72 6d 61 74 3c 2f 68 31 3e 0a 0a  RI Format</h1>..
0860: 3c 70 3e 0a 41 63 63 6f 72 64 69 6e 67 20 74 6f  <p>.According to
0870: 20 5b 68 74 74 70 3a 2f 2f 74 6f 6f 6c 73 2e 69   [http://tools.i
0880: 65 74 66 2e 6f 72 67 2f 68 74 6d 6c 2f 72 66 63  etf.org/html/rfc
0890: 33 39 38 36 20 7c 20 52 46 43 20 33 39 38 36 5d  3986 | RFC 3986]
08a0: 2c 20 61 20 55 52 49 20 63 6f 6e 73 69 73 74 73  , a URI consists
08b0: 0a 6f 66 20 61 20 73 63 68 65 6d 65 2c 20 61 6e  .of a scheme, an
08c0: 20 61 75 74 68 6f 72 69 74 79 2c 20 61 20 70 61   authority, a pa
08d0: 74 68 2c 20 61 20 71 75 65 72 79 20 73 74 72 69  th, a query stri
08e0: 6e 67 2c 20 61 6e 64 20 61 20 66 72 61 67 6d 65  ng, and a fragme
08f0: 6e 74 2e 20 20 54 68 65 0a 73 63 68 65 6d 65 20  nt.  The.scheme 
0900: 69 73 20 61 6c 77 61 79 73 20 72 65 71 75 69 72  is always requir
0910: 65 64 2e 20 20 4f 6e 65 20 6f 66 20 65 69 74 68  ed.  One of eith
0920: 65 72 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  er the authority
0930: 20 6f 72 20 74 68 65 20 70 61 74 68 20 69 73 20   or the path is 
0940: 61 6c 73 6f 0a 61 6c 77 61 79 73 20 72 65 71 75  also.always requ
0950: 69 72 65 64 2e 20 20 54 68 65 20 71 75 65 72 79  ired.  The query
0960: 20 73 74 72 69 6e 67 20 61 6e 64 20 66 72 61 67   string and frag
0970: 6d 65 6e 74 20 61 72 65 20 6f 70 74 69 6f 6e 61  ment are optiona
0980: 6c 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 53 51 4c  l..</p>..<p>.SQL
0990: 69 74 65 20 75 73 65 73 20 74 68 65 20 22 3c 74  ite uses the "<t
09a0: 74 3e 66 69 6c 65 3a 3c 2f 74 74 3e 22 20 55 52  t>file:</tt>" UR
09b0: 49 20 73 79 6e 74 61 78 20 74 6f 20 69 64 65 6e  I syntax to iden
09c0: 74 69 66 79 20 64 61 74 61 62 61 73 65 20 66 69  tify database fi
09d0: 6c 65 73 2e 0a 53 51 4c 69 74 65 20 73 74 72 69  les..SQLite stri
09e0: 76 65 73 20 74 6f 20 69 6e 74 65 72 70 72 65 74  ves to interpret
09f0: 20 66 69 6c 65 3a 20 55 52 49 73 20 69 6e 20 65   file: URIs in e
0a00: 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
0a10: 77 61 79 20 61 73 0a 70 6f 70 75 6c 61 72 20 77  way as.popular w
0a20: 65 62 2d 62 72 6f 77 73 65 72 73 20 73 75 63 68  eb-browsers such
0a30: 20 61 73 20 0a 5b 68 74 74 70 3a 2f 2f 77 77 77   as .[http://www
0a40: 2e 6d 6f 7a 69 6c 6c 61 2e 63 6f 6d 2f 65 6e 2d  .mozilla.com/en-
0a50: 55 53 2f 66 69 72 65 66 6f 78 2f 6e 65 77 2f 20  US/firefox/new/ 
0a60: 7c 20 46 69 72 65 66 6f 78 5d 2c 20 0a 5b 68 74  | Firefox], .[ht
0a70: 74 70 3a 2f 2f 77 77 77 2e 67 6f 6f 67 6c 65 2e  tp://www.google.
0a80: 63 6f 6d 2f 63 68 72 6f 6d 65 2f 20 7c 20 43 68  com/chrome/ | Ch
0a90: 72 6f 6d 65 5d 2c 20 0a 5b 68 74 74 70 3a 2f 2f  rome], .[http://
0aa0: 77 77 77 2e 61 70 70 6c 65 2e 63 6f 6d 2f 73 61  www.apple.com/sa
0ab0: 66 61 72 69 2f 20 7c 20 53 61 66 61 72 69 5d 2c  fari/ | Safari],
0ac0: 20 0a 5b 68 74 74 70 3a 2f 2f 77 69 6e 64 6f 77   .[http://window
0ad0: 73 2e 6d 69 63 72 6f 73 6f 66 74 2e 63 6f 6d 2f  s.microsoft.com/
0ae0: 65 6e 2d 55 53 2f 69 6e 74 65 72 6e 65 74 2d 65  en-US/internet-e
0af0: 78 70 6c 6f 72 65 72 2f 70 72 6f 64 75 63 74 73  xplorer/products
0b00: 2f 69 65 2f 68 6f 6d 65 20 7c 20 49 6e 74 65 72  /ie/home | Inter
0b10: 6e 65 74 20 45 78 70 6c 6f 72 65 72 5d 2c 20 61  net Explorer], a
0b20: 6e 64 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e 6f  nd.[http://www.o
0b30: 70 65 72 61 2e 63 6f 6d 2f 20 7c 20 4f 70 65 72  pera.com/ | Oper
0b40: 61 5d 2c 0a 61 6e 64 20 63 6f 6d 6d 61 6e 64 2d  a],.and command-
0b50: 6c 69 6e 65 20 70 72 6f 67 72 61 6d 73 20 73 75  line programs su
0b60: 63 68 20 61 73 20 0a 5b 68 74 74 70 3a 2f 2f 77  ch as .[http://w
0b70: 77 77 2e 6d 69 63 72 6f 73 6f 66 74 2e 63 6f 6d  ww.microsoft.com
0b80: 2f 72 65 73 6f 75 72 63 65 73 2f 64 6f 63 75 6d  /resources/docum
0b90: 65 6e 74 61 74 69 6f 6e 2f 77 69 6e 64 6f 77 73  entation/windows
0ba0: 2f 78 70 2f 61 6c 6c 2f 70 72 6f 64 64 6f 63 73  /xp/all/proddocs
0bb0: 2f 65 6e 2d 75 73 2f 73 74 61 72 74 2e 6d 73 70  /en-us/start.msp
0bc0: 78 20 7c 20 57 69 6e 64 6f 77 73 20 22 73 74 61  x | Windows "sta
0bd0: 72 74 22 5d 20 61 6e 64 20 74 68 65 20 4d 61 63  rt"] and the Mac
0be0: 20 4f 53 2d 58 0a 5b 68 74 74 70 3a 2f 2f 64 65   OS-X.[http://de
0bf0: 76 65 6c 6f 70 65 72 2e 61 70 70 6c 65 2e 63 6f  veloper.apple.co
0c00: 6d 2f 6c 69 62 72 61 72 79 2f 6d 61 63 2f 23 64  m/library/mac/#d
0c10: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 2f 44 61 72  ocumentation/Dar
0c20: 77 69 6e 2f 52 65 66 65 72 65 6e 63 65 2f 4d 61  win/Reference/Ma
0c30: 6e 50 61 67 65 73 2f 6d 61 6e 31 2f 6f 70 65 6e  nPages/man1/open
0c40: 2e 31 2e 68 74 6d 6c 20 7c 20 22 6f 70 65 6e 22  .1.html | "open"
0c50: 5d 20 63 6f 6d 6d 61 6e 64 2e 0a 41 20 73 75 63  ] command..A suc
0c60: 63 69 6e 63 74 20 73 75 6d 6d 61 72 79 20 6f 66  cinct summary of
0c70: 20 74 68 65 20 55 52 49 20 70 61 72 73 69 6e 67   the URI parsing
0c80: 20 72 75 6c 65 73 20 66 6f 6c 6c 6f 77 73 3a 0a   rules follows:.
0c90: 3c 2f 70 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 20  </p>..<ul>.<li> 
0ca0: 5e 28 54 68 65 20 73 63 68 65 6d 65 20 6f 66 20  ^(The scheme of 
0cb0: 74 68 65 20 55 52 49 20 6d 75 73 74 20 62 65 20  the URI must be 
0cc0: 22 3c 74 74 3e 66 69 6c 65 3a 3c 2f 74 74 3e 22  "<tt>file:</tt>"
0cd0: 2e 20 20 41 6e 79 20 6f 74 68 65 72 20 73 63 68  .  Any other sch
0ce0: 65 6d 65 0a 20 20 20 20 20 72 65 73 75 6c 74 73  eme.     results
0cf0: 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 62 65   in the input be
0d00: 69 6e 67 20 74 72 65 61 74 65 64 20 61 73 20 61  ing treated as a
0d10: 6e 20 6f 72 64 69 6e 61 72 79 20 66 69 6c 65 6e  n ordinary filen
0d20: 61 6d 65 2e 29 5e 0a 3c 6c 69 3e 20 5e 28 54 68  ame.)^.<li> ^(Th
0d30: 65 20 61 75 74 68 6f 72 69 74 79 20 6d 61 79 20  e authority may 
0d40: 62 65 20 6f 6d 69 74 74 65 64 2c 20 6d 61 79 20  be omitted, may 
0d50: 62 65 20 62 6c 61 6e 6b 2c 20 6f 72 20 6d 61 79  be blank, or may
0d60: 20 62 65 0a 20 20 20 20 20 20 22 3c 74 74 3e 6c   be.      "<tt>l
0d70: 6f 63 61 6c 68 6f 73 74 3c 2f 74 74 3e 22 2e 20  ocalhost</tt>". 
0d80: 20 41 6e 79 20 6f 74 68 65 72 20 61 75 74 68 6f   Any other autho
0d90: 72 69 74 79 20 72 65 73 75 6c 74 73 20 69 6e 20  rity results in 
0da0: 61 6e 20 65 72 72 6f 72 2e 29 5e 0a 20 20 20 20  an error.)^.    
0db0: 20 20 45 78 63 65 70 74 69 6f 6e 3a 20 49 66 20    Exception: If 
0dc0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
0dd0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
0de0: 41 4c 4c 4f 57 5f 55 52 49 5f 41 55 54 48 4f 52  ALLOW_URI_AUTHOR
0df0: 49 54 59 5d 0a 20 20 20 20 20 20 74 68 65 6e 20  ITY].      then 
0e00: 61 6e 79 20 61 75 74 68 6f 72 69 74 79 20 76 61  any authority va
0e10: 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 22  lue other than "
0e20: 6c 6f 63 61 6c 68 6f 73 74 22 20 69 73 20 70 61  localhost" is pa
0e30: 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
0e40: 74 68 65 20 0a 20 20 20 20 20 20 75 6e 64 65 72  the .      under
0e50: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
0e60: 73 79 73 74 65 6d 20 61 73 20 61 20 55 4e 43 20  system as a UNC 
0e70: 66 69 6c 65 6e 61 6d 65 2e 0a 3c 6c 69 3e 20 5e  filename..<li> ^
0e80: 54 68 65 20 70 61 74 68 20 69 73 20 6f 70 74 69  The path is opti
0e90: 6f 6e 61 6c 20 69 66 20 74 68 65 20 61 75 74 68  onal if the auth
0ea0: 6f 72 69 74 79 20 69 73 20 70 72 65 73 65 6e 74  ority is present
0eb0: 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
0ec0: 72 69 74 79 0a 20 20 20 20 20 69 73 20 6f 6d 69  rity.     is omi
0ed0: 74 74 65 64 20 74 68 65 6e 20 74 68 65 20 70 61  tted then the pa
0ee0: 74 68 20 69 73 20 72 65 71 75 69 72 65 64 2e 20  th is required. 
0ef0: 0a 3c 6c 69 3e 20 5e 54 68 65 20 71 75 65 72 79  .<li> ^The query
0f00: 20 73 74 72 69 6e 67 20 69 73 20 6f 70 74 69 6f   string is optio
0f10: 6e 61 6c 2e 20 20 5e 49 66 20 74 68 65 20 71 75  nal.  ^If the qu
0f20: 65 72 79 20 73 74 72 69 6e 67 20 69 73 20 70 72  ery string is pr
0f30: 65 73 65 6e 74 2c 20 74 68 65 6e 0a 20 20 20 20  esent, then.    
0f40: 20 20 61 6c 6c 20 71 75 65 72 79 20 70 61 72 61    all query para
0f50: 6d 65 74 65 72 73 20 61 72 65 20 70 61 73 73 65  meters are passe
0f60: 64 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 74  d through into t
0f70: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
0f80: 6f 66 0a 20 20 20 20 20 20 74 68 65 20 75 6e 64  of.      the und
0f90: 65 72 6c 79 69 6e 67 20 5b 56 46 53 5d 2e 20 20  erlying [VFS].  
0fa0: 0a 3c 6c 69 3e 20 5e 28 54 68 65 20 66 72 61 67  .<li> ^(The frag
0fb0: 6d 65 6e 74 20 69 73 20 6f 70 74 69 6f 6e 61 6c  ment is optional
0fc0: 2e 20 20 49 66 20 70 72 65 73 65 6e 74 2c 20 69  .  If present, i
0fd0: 74 20 69 73 20 69 67 6e 6f 72 65 64 2e 29 5e 0a  t is ignored.)^.
0fe0: 3c 2f 75 6c 3e 0a 0a 3c 70 3e 5e 5a 65 72 6f 20  </ul>..<p>^Zero 
0ff0: 6f 72 20 6d 6f 72 65 20 65 73 63 61 70 65 20 73  or more escape s
1000: 65 71 75 65 6e 63 65 73 20 6f 66 20 74 68 65 20  equences of the 
1010: 66 6f 72 6d 20 20 22 3c 62 3e 25 3c 69 3e 48 48  form  "<b>%<i>HH
1020: 3c 2f 69 3e 3c 2f 62 3e 22 20 0a 28 77 68 65 72  </i></b>" .(wher
1030: 65 20 3c 62 3e 3c 69 3e 48 3c 2f 69 3e 3c 2f 62  e <b><i>H</i></b
1040: 3e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 79  > represents any
1050: 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
1060: 69 74 29 20 63 61 6e 20 6f 63 63 75 72 20 0a 69  it) can occur .i
1070: 6e 20 74 68 65 20 70 61 74 68 2c 20 71 75 65 72  n the path, quer
1080: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 66 72 61  y string, or fra
1090: 67 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 5e  gment.</p>..<p>^
10a0: 41 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20  A filename that 
10b0: 69 73 20 6e 6f 74 20 61 20 77 65 6c 6c 2d 66 6f  is not a well-fo
10c0: 72 6d 65 64 20 55 52 49 20 69 73 20 69 6e 74 65  rmed URI is inte
10d0: 72 70 72 65 74 65 64 20 61 73 20 61 6e 0a 6f 72  rpreted as an.or
10e0: 64 69 6e 61 72 79 20 66 69 6c 65 6e 61 6d 65 2e  dinary filename.
10f0: 3c 2f 70 3e 0a 0a 3c 70 3e 5e 55 52 49 73 20 61  </p>..<p>^URIs a
1100: 72 65 20 70 72 6f 63 65 73 73 65 64 20 61 73 20  re processed as 
1110: 55 54 46 38 20 74 65 78 74 2e 0a 5e 54 68 65 20  UTF8 text..^The 
1120: 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1130: 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
1140: 28 29 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  () is converted 
1150: 66 72 6f 6d 20 55 54 46 31 36 20 0a 6e 61 74 69  from UTF16 .nati
1160: 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e  ve byte order in
1170: 74 6f 20 55 54 46 38 20 70 72 69 6f 72 20 74 6f  to UTF8 prior to
1180: 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 0a 3c 68   processing...<h
1190: 32 3e 33 2e 31 20 54 68 65 20 55 52 49 20 50 61  2>3.1 The URI Pa
11a0: 74 68 3c 2f 68 32 3e 0a 0a 3c 70 3e 5e 54 68 65  th</h2>..<p>^The
11b0: 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
11c0: 6f 66 20 74 68 65 20 55 52 49 20 73 70 65 63 69  of the URI speci
11d0: 66 69 65 73 20 74 68 65 20 64 69 73 6b 20 66 69  fies the disk fi
11e0: 6c 65 20 74 68 61 74 20 69 73 20 74 68 65 0a 53  le that is the.S
11f0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 74  QLite database t
1200: 6f 20 62 65 20 6f 70 65 6e 65 64 2e 20 20 5e 28  o be opened.  ^(
1210: 49 66 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  If the path comp
1220: 6f 6e 65 6e 74 20 69 73 20 6f 6d 69 74 74 65 64  onent is omitted
1230: 2c 20 74 68 65 6e 0a 74 68 65 20 64 61 74 61 62  , then.the datab
1240: 61 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ase is stored in
1250: 20 61 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c   a temporary fil
1260: 65 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61  e that will be a
1270: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 64 65 6c  utomatically.del
1280: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 64 61  eted when the da
1290: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12a0: 6e 20 63 6c 6f 73 65 73 2e 29 5e 20 20 5e 49 66  n closes.)^  ^If
12b0: 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
12c0: 65 63 74 69 6f 6e 0a 69 73 20 70 72 65 73 65 6e  ection.is presen
12d0: 74 2c 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  t, then the path
12e0: 20 69 73 20 61 6c 77 61 79 73 20 61 6e 20 61 62   is always an ab
12f0: 73 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2e  solute pathname.
1300: 20 20 5e 49 66 20 74 68 65 20 0a 61 75 74 68 6f    ^If the .autho
1310: 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
1320: 6f 6d 69 74 74 65 64 2c 20 74 68 65 6e 20 74 68  omitted, then th
1330: 65 20 70 61 74 68 20 69 73 20 61 6e 20 61 62 73  e path is an abs
1340: 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 20 69  olute pathname i
1350: 66 20 69 74 0a 62 65 67 69 6e 73 20 77 69 74 68  f it.begins with
1360: 20 74 68 65 20 22 2f 22 20 63 68 61 72 61 63 74   the "/" charact
1370: 65 72 20 28 41 53 43 49 49 20 63 6f 64 65 20 30  er (ASCII code 0
1380: 78 32 66 29 20 61 6e 64 20 69 73 20 61 20 72 65  x2f) and is a re
1390: 6c 61 74 69 76 65 0a 70 61 74 68 6e 61 6d 65 20  lative.pathname 
13a0: 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 28 4f 6e  otherwise.  ^(On
13b0: 20 77 69 6e 64 6f 77 73 2c 20 69 66 20 74 68 65   windows, if the
13c0: 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 62   absolute path b
13d0: 65 67 69 6e 73 20 77 69 74 68 0a 22 3c 62 3e 2f  egins with."<b>/
13e0: 3c 69 3e 58 3c 2f 69 3e 3a 2f 3c 2f 62 3e 22 20  <i>X</i>:/</b>" 
13f0: 77 68 65 72 65 20 3c 62 3e 3c 69 3e 58 3c 2f 69  where <b><i>X</i
1400: 3e 3c 2f 62 3e 20 69 73 20 61 6e 79 20 73 69 6e  ></b> is any sin
1410: 67 6c 65 20 41 53 43 49 49 20 61 6c 70 68 61 62  gle ASCII alphab
1420: 65 74 69 63 0a 63 68 61 72 61 63 74 65 72 20 28  etic.character (
1430: 22 61 22 20 74 68 72 6f 75 67 68 20 22 7a 22 20  "a" through "z" 
1440: 6f 72 20 22 41 22 20 74 68 72 6f 75 67 68 20 22  or "A" through "
1450: 5a 22 29 20 74 68 65 6e 20 74 68 65 20 22 3c 62  Z") then the "<b
1460: 3e 3c 69 3e 58 3a 3c 2f 69 3e 3c 2f 62 3e 22 0a  ><i>X:</i></b>".
1470: 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 74 6f  is understood to
1480: 20 62 65 20 74 68 65 20 64 72 69 76 65 20 6c 65   be the drive le
1490: 74 74 65 72 20 6f 66 20 74 68 65 20 76 6f 6c 75  tter of the volu
14a0: 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
14b0: 65 20 66 69 6c 65 2c 0a 6e 6f 74 20 74 68 65 20  e file,.not the 
14c0: 74 6f 70 6c 65 76 65 6c 20 64 69 72 65 63 74 6f  toplevel directo
14d0: 72 79 2e 29 5e 0a 0a 3c 70 3e 41 6e 20 6f 72 64  ry.)^..<p>An ord
14e0: 69 6e 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 63  inary filename c
14f0: 61 6e 20 75 73 75 61 6c 6c 79 20 62 65 20 63 6f  an usually be co
1500: 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 6e 20  nverted into an 
1510: 65 71 75 69 76 61 6c 65 6e 74 20 55 52 49 20 0a  equivalent URI .
1520: 62 79 20 74 68 65 20 73 74 65 70 73 20 73 68 6f  by the steps sho
1530: 77 6e 20 62 65 6c 6f 77 2e 20 20 54 68 65 20 6f  wn below.  The o
1540: 6e 65 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ne exception is 
1550: 74 68 61 74 20 61 20 72 65 6c 61 74 69 76 65 20  that a relative 
1560: 77 69 6e 64 6f 77 73 0a 70 61 74 68 6e 61 6d 65  windows.pathname
1570: 20 77 69 74 68 20 61 20 64 72 69 76 65 20 6c 65   with a drive le
1580: 74 74 65 72 20 63 61 6e 6e 6f 74 20 62 65 20 63  tter cannot be c
1590: 6f 6e 76 65 72 74 65 64 20 64 69 72 65 63 74 6c  onverted directl
15a0: 79 20 69 6e 74 6f 20 61 20 55 52 49 3b 20 69 74  y into a URI; it
15b0: 20 6d 75 73 74 0a 62 65 20 63 68 61 6e 67 65 64   must.be changed
15c0: 20 69 6e 74 6f 20 61 6e 20 61 62 73 6f 6c 75 74   into an absolut
15d0: 65 20 70 61 74 68 6e 61 6d 65 20 66 69 72 73 74  e pathname first
15e0: 2e 3c 2f 70 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e  .</p>..<ol>.<li>
15f0: 43 6f 6e 76 65 72 74 20 61 6c 6c 20 22 3c 74 74  Convert all "<tt
1600: 3e 3f 3c 2f 74 74 3e 22 20 63 68 61 72 61 63 74  >?</tt>" charact
1610: 65 72 73 20 69 6e 74 6f 20 22 3c 74 74 3e 25 33  ers into "<tt>%3
1620: 66 3c 2f 74 74 3e 22 2e 0a 3c 6c 69 3e 43 6f 6e  f</tt>"..<li>Con
1630: 76 65 72 74 20 61 6c 6c 20 22 3c 74 74 3e 23 3c  vert all "<tt>#<
1640: 2f 74 74 3e 22 20 63 68 61 72 61 63 74 65 72 73  /tt>" characters
1650: 20 69 6e 74 6f 20 22 3c 74 74 3e 25 32 33 3c 2f   into "<tt>%23</
1660: 74 74 3e 22 2e 0a 3c 6c 69 3e 4f 6e 20 77 69 6e  tt>"..<li>On win
1670: 64 6f 77 73 20 6f 6e 6c 79 2c 20 63 6f 6e 76 65  dows only, conve
1680: 72 74 20 61 6c 6c 20 22 3c 74 74 3e 5c 3c 2f 74  rt all "<tt>\</t
1690: 74 3e 22 20 63 68 61 72 61 63 74 65 72 73 20 69  t>" characters i
16a0: 6e 74 6f 20 22 3c 74 74 3e 2f 3c 2f 74 74 3e 22  nto "<tt>/</tt>"
16b0: 2e 0a 3c 6c 69 3e 43 6f 6e 76 65 72 74 20 61 6c  ..<li>Convert al
16c0: 6c 20 73 65 71 75 65 6e 63 65 73 20 6f 66 20 74  l sequences of t
16d0: 77 6f 20 6f 72 20 6d 6f 72 65 20 22 3c 74 74 3e  wo or more "<tt>
16e0: 2f 3c 2f 74 74 3e 22 20 63 68 61 72 61 63 74 65  /</tt>" characte
16f0: 72 73 20 69 6e 74 6f 20 61 0a 20 20 20 20 73 69  rs into a.    si
1700: 6e 67 6c 65 20 22 3c 74 74 3e 2f 3c 2f 74 74 3e  ngle "<tt>/</tt>
1710: 22 20 63 68 61 72 61 63 74 65 72 2e 0a 3c 6c 69  " character..<li
1720: 3e 4f 6e 20 77 69 6e 64 6f 77 73 20 6f 6e 6c 79  >On windows only
1730: 2c 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  , if the filenam
1740: 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
1750: 64 72 69 76 65 20 6c 65 74 74 65 72 2c 20 70 72  drive letter, pr
1760: 65 70 65 6e 64 0a 20 20 20 20 61 20 73 69 6e 67  epend.    a sing
1770: 6c 65 20 22 3c 74 74 3e 2f 3c 2f 74 74 3e 22 20  le "<tt>/</tt>" 
1780: 63 68 61 72 61 63 74 65 72 2e 0a 3c 6c 69 3e 50  character..<li>P
1790: 72 65 70 65 6e 64 20 74 68 65 20 22 3c 74 74 3e  repend the "<tt>
17a0: 66 69 6c 65 3a 3c 2f 74 74 3e 22 20 73 63 68 65  file:</tt>" sche
17b0: 6d 65 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 68 32 3e 33  me..</ol>..<h2>3
17c0: 2e 32 20 51 75 65 72 79 20 53 74 72 69 6e 67 3c  .2 Query String<
17d0: 2f 68 32 3e 0a 0a 3c 70 3e 5e 41 20 55 52 49 20  /h2>..<p>^A URI 
17e0: 66 69 6c 65 6e 61 6d 65 20 63 61 6e 20 6f 70 74  filename can opt
17f0: 69 6f 6e 61 6c 6c 79 20 62 65 20 66 6f 6c 6c 6f  ionally be follo
1800: 77 65 64 20 62 79 20 61 20 71 75 65 72 79 20 73  wed by a query s
1810: 74 72 69 6e 67 2e 0a 5e 54 68 65 20 71 75 65 72  tring..^The quer
1820: 79 20 73 74 72 69 6e 67 20 63 6f 6e 73 69 73 74  y string consist
1830: 73 20 6f 66 20 74 65 78 74 20 66 6f 6c 6c 6f 77  s of text follow
1840: 69 6e 67 20 74 68 65 20 66 69 72 73 74 20 22 3c  ing the first "<
1850: 74 74 3e 3f 3c 2f 74 74 3e 22 0a 63 68 61 72 61  tt>?</tt>".chara
1860: 63 74 65 72 20 62 75 74 20 65 78 63 6c 75 64 69  cter but excludi
1870: 6e 67 20 74 68 65 20 6f 70 74 69 6f 6e 61 6c 20  ng the optional 
1880: 66 72 61 67 6d 65 6e 74 20 74 68 61 74 20 62 65  fragment that be
1890: 67 69 6e 73 20 77 69 74 68 0a 22 3c 74 74 3e 23  gins with."<tt>#
18a0: 3c 2f 74 74 3e 22 2e 20 20 5e 54 68 65 20 71 75  </tt>".  ^The qu
18b0: 65 72 79 20 73 74 72 69 6e 67 20 69 73 20 64 69  ery string is di
18c0: 76 69 64 65 64 20 69 6e 74 6f 20 6b 65 79 2f 76  vided into key/v
18d0: 61 6c 75 65 20 70 61 69 72 73 2e 0a 57 65 20 75  alue pairs..We u
18e0: 73 75 61 6c 6c 79 20 72 65 66 65 72 20 74 6f 20  sually refer to 
18f0: 74 68 65 73 65 20 6b 65 79 2f 76 61 6c 75 65 20  these key/value 
1900: 70 61 69 72 73 20 61 73 20 22 71 75 65 72 79 20  pairs as "query 
1910: 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 5e 4b 65  parameters"..^Ke
1920: 79 2f 76 61 6c 75 65 20 70 61 69 72 73 20 61 72  y/value pairs ar
1930: 65 20 73 65 70 61 72 61 74 65 64 20 62 79 20 61  e separated by a
1940: 20 73 69 6e 67 6c 65 20 22 3c 74 74 3e 26 61 6d   single "<tt>&am
1950: 70 3b 3c 2f 74 74 3e 22 20 63 68 61 72 61 63 74  p;</tt>" charact
1960: 65 72 2e 0a 5e 54 68 65 20 6b 65 79 20 63 6f 6d  er..^The key com
1970: 65 73 20 66 69 72 73 74 20 61 6e 64 20 69 73 20  es first and is 
1980: 73 65 70 61 72 61 74 65 64 20 66 72 6f 6d 20 74  separated from t
1990: 68 65 20 76 61 6c 75 65 20 62 79 20 61 20 73 69  he value by a si
19a0: 6e 67 6c 65 0a 22 3c 74 74 3e 3d 3c 2f 74 74 3e  ngle."<tt>=</tt>
19b0: 22 20 63 68 61 72 61 63 74 65 72 2e 0a 5e 42 6f  " character..^Bo
19c0: 74 68 20 6b 65 79 20 61 6e 64 20 76 61 6c 75 65  th key and value
19d0: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 3c 62 3e   may contain <b>
19e0: 25 48 48 3c 2f 62 3e 20 65 73 63 61 70 65 20 73  %HH</b> escape s
19f0: 65 71 75 65 6e 63 65 73 2e 3c 2f 70 3e 0a 0a 3c  equences.</p>..<
1a00: 70 3e 0a 5e 54 68 65 20 74 65 78 74 20 6f 66 20  p>.^The text of 
1a10: 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
1a20: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
1a30: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1a40: 75 6d 65 6e 74 20 6f 66 0a 74 68 65 20 78 4f 70  ument of.the xOp
1a50: 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
1a60: 20 5b 56 46 53 5d 2e 0a 5e 41 6e 79 20 25 48 48   [VFS]..^Any %HH
1a70: 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
1a80: 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 70  s in the query p
1a90: 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 72 65  arameters are re
1aa0: 73 6f 6c 76 65 64 20 70 72 69 6f 72 20 74 6f 0a  solved prior to.
1ab0: 62 65 69 6e 67 20 61 70 70 65 6e 64 65 64 20 74  being appended t
1ac0: 6f 20 74 68 65 20 78 4f 70 65 6e 20 66 69 6c 65  o the xOpen file
1ad0: 6e 61 6d 65 2e 0a 5e 41 20 73 69 6e 67 6c 65 20  name..^A single 
1ae0: 7a 65 72 6f 2d 62 79 74 65 20 73 65 70 61 72 61  zero-byte separa
1af0: 74 65 73 20 74 68 65 20 78 4f 70 65 6e 20 66 69  tes the xOpen fi
1b00: 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1b10: 66 72 6f 6d 20 74 68 65 20 6b 65 79 20 6f 66 0a  from the key of.
1b20: 74 68 65 20 66 69 72 73 74 20 71 75 65 72 79 20  the first query 
1b30: 70 61 72 61 6d 65 74 65 72 73 2c 20 65 61 63 68  parameters, each
1b40: 20 6b 65 79 20 61 6e 64 20 76 61 6c 75 65 2c 20   key and value, 
1b50: 61 6e 64 20 65 61 63 68 20 73 75 62 73 65 71 75  and each subsequ
1b60: 65 6e 74 20 6b 65 79 0a 66 72 6f 6d 20 74 68 65  ent key.from the
1b70: 20 70 72 69 6f 72 20 76 61 6c 75 65 2e 0a 5e 54   prior value..^T
1b80: 68 65 20 6c 69 73 74 20 6f 66 20 71 75 65 72 79  he list of query
1b90: 20 70 61 72 61 6d 65 74 65 72 73 20 61 70 70 65   parameters appe
1ba0: 6e 64 65 64 20 74 6f 20 74 68 65 20 78 4f 70 65  nded to the xOpe
1bb0: 6e 20 66 69 6c 65 6e 61 6d 65 0a 69 73 20 74 65  n filename.is te
1bc0: 72 6d 69 6e 61 74 65 64 20 62 79 20 61 20 73 69  rminated by a si
1bd0: 6e 67 6c 65 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  ngle zero-length
1be0: 20 6b 65 79 2e 0a 4e 6f 74 65 20 74 68 61 74 20   key..Note that 
1bf0: 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 71  the value of a q
1c00: 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 63  uery parameter c
1c10: 61 6e 20 62 65 20 61 6e 20 65 6d 70 74 79 20 73  an be an empty s
1c20: 74 72 69 6e 67 2e 0a 3c 2f 70 3e 0a 0a 3c 74 63  tring..</p>..<tc
1c30: 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 63 6f  l>hd_fragment co
1c40: 72 65 71 70 20 2a 63 6f 72 65 71 70 20 7b 73 74  reqp *coreqp {st
1c50: 61 6e 64 61 72 64 20 71 75 65 72 79 20 70 61 72  andard query par
1c60: 61 6d 65 74 65 72 73 7d 20 7b 55 52 49 20 71 75  ameters} {URI qu
1c70: 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ery parameters} 
1c80: 5c 0a 20 20 20 20 7b 71 75 65 72 79 20 70 61 72  \.    {query par
1c90: 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
1ca0: 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
1cb0: 53 51 4c 69 74 65 7d 3c 2f 74 63 6c 3e 0a 3c 68  SQLite}</tcl>.<h
1cc0: 32 3e 33 2e 33 20 52 65 63 6f 67 6e 69 7a 65 64  2>3.3 Recognized
1cd0: 20 51 75 65 72 79 20 50 61 72 61 6d 65 74 65 72   Query Parameter
1ce0: 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 53 6f 6d 65  s</h2>..<p>.Some
1cf0: 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
1d00: 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1d10: 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20  d by the SQLite 
1d20: 63 6f 72 65 20 61 6e 64 20 75 73 65 64 20 74 6f  core and used to
1d30: 20 0a 6d 6f 64 69 66 79 20 74 68 65 20 63 68 61   .modify the cha
1d40: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
1d50: 74 68 65 20 6e 65 77 20 63 6f 6e 6e 65 63 74 69  the new connecti
1d60: 6f 6e 2e 20 20 5e 41 6c 6c 20 71 75 65 72 79 20  on.  ^All query 
1d70: 70 61 72 61 6d 65 74 65 72 73 0a 61 72 65 20 61  parameters.are a
1d80: 6c 77 61 79 73 20 70 61 73 73 65 64 20 74 68 72  lways passed thr
1d90: 6f 75 67 68 20 69 6e 74 6f 20 74 68 65 20 78 4f  ough into the xO
1da0: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
1db0: 65 20 5b 56 46 53 5d 20 65 76 65 6e 20 69 66 0a  e [VFS] even if.
1dc0: 74 68 65 79 20 61 72 65 20 70 72 65 76 69 6f 75  they are previou
1dd0: 73 6c 79 20 72 65 61 64 20 61 6e 64 20 69 6e 74  sly read and int
1de0: 65 72 70 72 65 74 65 64 20 62 79 20 74 68 65 20  erpreted by the 
1df0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 0a 3c 2f 70  SQLite core..</p
1e00: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 66 6f 6c 6c 6f  >..<p>.The follo
1e10: 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
1e20: 65 74 65 72 73 20 61 72 65 20 72 65 63 6f 67 6e  eters are recogn
1e30: 69 7a 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  ized by SQLite a
1e40: 73 20 6f 66 20 76 65 72 73 69 6f 6e 20 33 2e 38  s of version 3.8
1e50: 2e 30 2e 0a 4f 74 68 65 72 20 71 75 65 72 79 20  .0..Other query 
1e60: 70 61 72 61 6d 65 74 65 72 73 20 6d 69 67 68 74  parameters might
1e70: 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 69   be added to thi
1e80: 73 20 73 65 74 20 69 6e 20 66 75 74 75 72 65 20  s set in future 
1e90: 72 65 6c 65 61 73 65 73 2e 0a 3c 2f 70 3e 0a 0a  releases..</p>..
1ea0: 3c 64 6c 3e 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  <dl>.<tcl>hd_fra
1eb0: 67 6d 65 6e 74 20 75 72 69 76 66 73 20 7b 22 76  gment urivfs {"v
1ec0: 66 73 22 20 71 75 65 72 79 20 70 61 72 61 6d 65  fs" query parame
1ed0: 74 65 72 7d 3c 2f 74 63 6c 3e 0a 3c 64 74 3e 3c  ter}</tcl>.<dt><
1ee0: 62 3e 76 66 73 3d 3c 2f 62 3e 3c 69 3e 4e 41 4d  b>vfs=</b><i>NAM
1ef0: 45 3c 2f 69 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  E</i></dt>.<dd><
1f00: 70 3e 5e 54 68 65 20 76 66 73 20 71 75 65 72 79  p>^The vfs query
1f10: 20 70 61 72 61 6d 65 74 65 72 20 63 61 75 73 65   parameter cause
1f20: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1f30: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 20  onnection to be 
1f40: 6f 70 65 6e 65 64 0a 75 73 69 6e 67 20 74 68 65  opened.using the
1f50: 20 5b 56 46 53 5d 20 63 61 6c 6c 65 64 20 3c 69   [VFS] called <i
1f60: 3e 4e 41 4d 45 3c 2f 69 3e 2e 0a 5e 54 68 65 20  >NAME</i>..^The 
1f70: 6f 70 65 6e 20 61 74 74 65 6d 70 74 20 66 61 69  open attempt fai
1f80: 6c 73 20 69 66 20 3c 69 3e 4e 41 4d 45 3c 2f 69  ls if <i>NAME</i
1f90: 3e 20 69 73 20 6e 6f 74 20 74 68 65 20 6e 61 6d  > is not the nam
1fa0: 65 20 6f 66 20 61 20 5b 56 46 53 5d 20 74 68 61  e of a [VFS] tha
1fb0: 74 0a 69 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  t.is built into 
1fc0: 53 51 4c 69 74 65 20 6f 72 20 74 68 61 74 20 68  SQLite or that h
1fd0: 61 73 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73  as been previous
1fe0: 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 75 73  ly registered us
1ff0: 69 6e 67 0a 5b 73 71 6c 69 74 65 33 5f 76 66 73  ing.[sqlite3_vfs
2000: 5f 72 65 67 69 73 74 65 72 28 29 5d 2e 3c 2f 64  _register()].</d
2010: 64 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67  d>..<tcl>hd_frag
2020: 6d 65 6e 74 20 75 72 69 6d 6f 64 65 20 7b 22 6d  ment urimode {"m
2030: 6f 64 65 22 20 71 75 65 72 79 20 70 61 72 61 6d  ode" query param
2040: 65 74 65 72 7d 3c 2f 74 63 6c 3e 0a 3c 64 74 3e  eter}</tcl>.<dt>
2050: 3c 62 3e 6d 6f 64 65 3d 72 6f 3c 62 72 3e 6d 6f  <b>mode=ro<br>mo
2060: 64 65 3d 72 77 3c 62 72 3e 6d 6f 64 65 3d 72 77  de=rw<br>mode=rw
2070: 63 3c 62 72 3e 6d 6f 64 65 3d 6d 65 6d 6f 72 79  c<br>mode=memory
2080: 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70  </b></dt>.<dd><p
2090: 3e 5e 54 68 65 20 6d 6f 64 65 20 71 75 65 72 79  >^The mode query
20a0: 20 70 61 72 61 6d 65 74 65 72 20 64 65 74 65 72   parameter deter
20b0: 6d 69 6e 65 73 20 69 66 20 74 68 65 20 6e 65 77  mines if the new
20c0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20d0: 6e 65 64 0a 72 65 61 64 2d 6f 6e 6c 79 2c 20 72  ned.read-only, r
20e0: 65 61 64 2d 77 72 69 74 65 2c 20 72 65 61 64 2d  ead-write, read-
20f0: 77 72 69 74 65 20 61 6e 64 20 63 72 65 61 74 65  write and create
2100: 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74  d if it does not
2110: 20 65 78 69 73 74 2c 20 6f 72 0a 74 68 61 74 20   exist, or.that 
2120: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
2130: 61 20 70 75 72 65 20 69 6e 2d 6d 65 6d 6f 72 79  a pure in-memory
2140: 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20 6e   database that n
2150: 65 76 65 72 20 69 6e 74 65 72 61 63 74 73 20 77  ever interacts w
2160: 69 74 68 0a 64 69 73 6b 2c 20 72 65 73 70 65 63  ith.disk, respec
2170: 74 69 76 65 6c 79 2e 0a 3c 2f 64 64 3e 0a 0a 3c  tively..</dd>..<
2180: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
2190: 75 72 69 63 61 63 68 65 20 7b 22 63 61 63 68 65  uricache {"cache
21a0: 22 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  " query paramete
21b0: 72 7d 3c 2f 74 63 6c 3e 0a 3c 64 74 3e 3c 62 3e  r}</tcl>.<dt><b>
21c0: 63 61 63 68 65 3d 73 68 61 72 65 64 3c 62 72 3e  cache=shared<br>
21d0: 63 61 63 68 65 3d 70 72 69 76 61 74 65 3c 2f 62  cache=private</b
21e0: 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 5e 54  ></dt>.<dd><p>^T
21f0: 68 65 20 63 61 63 68 65 20 71 75 65 72 79 20 70  he cache query p
2200: 61 72 61 6d 65 74 65 72 20 64 65 74 65 72 6d 69  arameter determi
2210: 6e 65 73 20 69 66 20 74 68 65 20 6e 65 77 20 64  nes if the new d
2220: 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
2230: 64 0a 75 73 69 6e 67 20 5b 73 68 61 72 65 64 20  d.using [shared 
2240: 63 61 63 68 65 20 6d 6f 64 65 5d 20 6f 72 20 77  cache mode] or w
2250: 69 74 68 20 61 20 70 72 69 76 61 74 65 20 63 61  ith a private ca
2260: 63 68 65 2e 0a 3c 2f 64 64 3e 0a 0a 3c 74 63 6c  che..</dd>..<tcl
2270: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 75 72 69  >hd_fragment uri
2280: 70 73 6f 77 20 7b 22 70 73 6f 77 22 20 71 75 65  psow {"psow" que
2290: 72 79 20 70 61 72 61 6d 65 74 65 72 7d 3c 2f 74  ry parameter}</t
22a0: 63 6c 3e 0a 3c 64 74 3e 3c 62 3e 70 73 6f 77 3d  cl>.<dt><b>psow=
22b0: 30 3c 62 72 3e 70 73 6f 77 3d 31 3c 2f 62 3e 3c  0<br>psow=1</b><
22c0: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 5e 54 68 65  /dt>.<dd><p>^The
22d0: 20 70 73 6f 77 20 71 75 65 72 79 20 70 61 72 61   psow query para
22e0: 6d 65 74 65 72 20 6f 76 65 72 72 69 64 65 73 20  meter overrides 
22f0: 74 68 65 20 5b 70 6f 77 65 72 73 61 66 65 20 6f  the [powersafe o
2300: 76 65 72 77 72 69 74 65 5d 0a 70 72 6f 70 65 72  verwrite].proper
2310: 74 79 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ty of the databa
2320: 73 65 20 66 69 6c 65 20 62 65 69 6e 67 20 6f 70  se file being op
2330: 65 6e 65 64 2e 20 20 5e 54 68 65 20 70 73 6f 77  ened.  ^The psow
2340: 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
2350: 0a 77 6f 72 6b 73 20 77 69 74 68 20 74 68 65 20  .works with the 
2360: 64 65 66 61 75 6c 74 20 77 69 6e 64 6f 77 73 20  default windows 
2370: 61 6e 64 20 75 6e 69 78 20 5b 56 46 53 65 73 5d  and unix [VFSes]
2380: 20 62 75 74 20 6d 69 67 68 74 20 62 65 20 61 20   but might be a 
2390: 6e 6f 2d 6f 70 20 66 6f 72 0a 6f 74 68 65 72 20  no-op for.other 
23a0: 70 72 6f 70 72 69 65 74 61 72 79 20 6f 72 20 6e  proprietary or n
23b0: 6f 6e 2d 73 74 61 6e 64 61 72 64 20 56 46 53 65  on-standard VFSe
23c0: 73 2e 0a 3c 2f 64 64 3e 0a 0a 3c 74 63 6c 3e 68  s..</dd>..<tcl>h
23d0: 64 5f 66 72 61 67 6d 65 6e 74 20 75 72 69 6e 6f  d_fragment urino
23e0: 6c 6f 63 6b 20 7b 22 6e 6f 6c 6f 63 6b 22 20 71  lock {"nolock" q
23f0: 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 7d 3c  uery parameter}<
2400: 2f 74 63 6c 3e 0a 3c 64 74 3e 3c 62 3e 6e 6f 6c  /tcl>.<dt><b>nol
2410: 6f 63 6b 3d 31 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c  ock=1</b></dt>.<
2420: 64 64 3e 3c 70 3e 5e 54 68 65 20 6e 6f 6c 6f 63  dd><p>^The noloc
2430: 6b 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  k query paramete
2440: 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 74  r is a boolean t
2450: 68 61 74 20 64 69 73 61 62 6c 65 73 20 61 6c 6c  hat disables all
2460: 20 63 61 6c 6c 73 0a 74 6f 20 74 68 65 20 78 4c   calls.to the xL
2470: 6f 63 6b 2c 20 78 55 6e 6c 6f 63 6b 2c 20 61 6e  ock, xUnlock, an
2480: 64 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  d xCheckReserved
2490: 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20 6f 66 20  Lock methods of 
24a0: 74 68 65 20 56 46 53 20 77 68 65 6e 20 74 72 75  the VFS when tru
24b0: 65 2e 0a 54 68 65 20 6e 6f 6c 6f 63 6b 20 71 75  e..The nolock qu
24c0: 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6d 69  ery parameter mi
24d0: 67 68 74 20 62 65 20 75 73 65 64 2c 20 66 6f 72  ght be used, for
24e0: 20 65 78 61 6d 70 6c 65 2c 20 77 68 65 6e 20 74   example, when t
24f0: 72 79 69 6e 67 20 74 6f 0a 61 63 63 65 73 73 20  rying to.access 
2500: 61 20 66 69 6c 65 20 6f 6e 20 61 20 66 69 6c 65  a file on a file
2510: 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
2520: 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 66 69 6c   not support fil
2530: 65 20 6c 6f 63 6b 69 6e 67 2e 0a 43 61 75 74 69  e locking..Cauti
2540: 6f 6e 3a 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  on:  If two or m
2550: 6f 72 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ore [database co
2560: 6e 6e 65 63 74 69 6f 6e 73 5d 20 74 72 79 20 74  nnections] try t
2570: 6f 20 69 6e 74 65 72 61 63 74 20 77 69 74 68 20  o interact with 
2580: 0a 74 68 65 20 73 61 6d 65 20 53 51 4c 69 74 65  .the same SQLite
2590: 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 6f 6e   database and on
25a0: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 6f  e or more of tho
25b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 68  se connections h
25c0: 61 73 0a 65 6e 61 62 6c 65 64 20 22 6e 6f 6c 6f  as.enabled "nolo
25d0: 63 6b 22 2c 20 74 68 65 6e 20 64 61 74 61 62 61  ck", then databa
25e0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 63 61  se corruption ca
25f0: 6e 20 72 65 73 75 6c 74 2e 20 20 54 68 65 20 22  n result.  The "
2600: 6e 6f 6c 6f 63 6b 22 0a 71 75 65 72 79 20 70 61  nolock".query pa
2610: 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 6f  rameter should o
2620: 6e 6c 79 20 62 65 20 75 73 65 64 20 69 66 20 74  nly be used if t
2630: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
2640: 61 6e 20 67 75 61 72 61 6e 74 65 65 0a 74 68 61  an guarantee.tha
2650: 74 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  t writes to the 
2660: 64 61 74 61 62 61 73 65 20 61 72 65 20 73 65 72  database are ser
2670: 69 61 6c 69 7a 65 64 2e 0a 3c 2f 64 64 3e 0a 0a  ialized..</dd>..
2680: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
2690: 20 75 72 69 69 6d 6d 75 74 61 62 6c 65 20 7b 22   uriimmutable {"
26a0: 69 6d 6d 75 74 61 62 6c 65 22 20 71 75 65 72 79  immutable" query
26b0: 20 70 61 72 61 6d 65 74 65 72 7d 3c 2f 74 63 6c   parameter}</tcl
26c0: 3e 0a 3c 64 74 3e 3c 62 3e 69 6d 6d 75 74 61 62  >.<dt><b>immutab
26d0: 6c 65 3d 31 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c 64  le=1</b></dt>.<d
26e0: 64 3e 3c 70 3e 5e 54 68 65 20 69 6d 6d 75 74 61  d><p>^The immuta
26f0: 62 6c 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ble query parame
2700: 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
2710: 20 74 68 61 74 20 73 69 67 6e 61 6c 73 20 74 6f   that signals to
2720: 0a 53 51 4c 69 74 65 20 74 68 61 74 20 74 68 65  .SQLite that the
2730: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 61 74 61   underlying data
2740: 62 61 73 65 20 66 69 6c 65 20 69 73 20 68 65 6c  base file is hel
2750: 64 20 6f 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d on read-only m
2760: 65 64 69 61 0a 61 6e 64 20 63 61 6e 6e 6f 74 20  edia.and cannot 
2770: 62 65 20 6d 6f 64 69 66 69 65 64 2c 20 65 76 65  be modified, eve
2780: 6e 20 62 79 20 61 6e 6f 74 68 65 72 20 70 72 6f  n by another pro
2790: 63 65 73 73 20 77 69 74 68 20 65 6c 65 76 61 74  cess with elevat
27a0: 65 64 20 0a 70 72 69 76 69 6c 65 67 65 73 2e 20  ed .privileges. 
27b0: 20 5e 53 51 4c 69 74 65 20 61 6c 77 61 79 73 20   ^SQLite always 
27c0: 6f 70 65 6e 73 20 69 6d 6d 75 74 61 62 6c 65 20  opens immutable 
27d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 0a 72  database files.r
27e0: 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 69 74 20  ead-only and it 
27f0: 73 6b 69 70 73 20 61 6c 6c 20 66 69 6c 65 20 6c  skips all file l
2800: 6f 63 6b 69 6e 67 20 61 6e 64 20 63 68 61 6e 67  ocking and chang
2810: 65 20 64 65 74 65 63 74 69 6f 6e 0a 6f 6e 20 69  e detection.on i
2820: 6d 6d 75 74 61 62 6c 65 20 64 61 74 61 62 61 73  mmutable databas
2830: 65 20 66 69 6c 65 73 2e 20 20 49 66 20 74 68 65  e files.  If the
2840: 73 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  se query paramet
2850: 65 72 20 28 6f 72 0a 74 68 65 20 5b 53 51 4c 49  er (or.the [SQLI
2860: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
2870: 4c 45 5d 20 62 69 74 20 69 6e 20 78 44 65 76 69  LE] bit in xDevi
2880: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
2890: 73 29 0a 61 73 73 65 72 74 73 20 74 68 61 74 20  s).asserts that 
28a0: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
28b0: 69 73 20 69 6d 6d 75 74 61 62 6c 65 20 61 6e 64  is immutable and
28c0: 20 74 68 61 74 20 66 69 6c 65 20 0a 63 68 61 6e   that file .chan
28d0: 67 65 73 20 61 6e 79 68 6f 77 2c 20 74 68 65 6e  ges anyhow, then
28e0: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 72 65   SQLite might re
28f0: 74 75 72 6e 20 69 6e 63 6f 72 72 65 63 74 20 71  turn incorrect q
2900: 75 65 72 79 20 0a 72 65 73 75 6c 74 73 20 61 6e  uery .results an
2910: 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
2920: 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 3c 2f  RUPT] errors..</
2930: 64 64 3e 0a 3c 2f 64 6c 3e 0a 0a 3c 68 31 3e 34  dd>.</dl>..<h1>4
2940: 2e 30 20 53 65 65 20 41 6c 73 6f 3c 2f 68 31 3e  .0 See Also</h1>
2950: 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 20 5b 55 52 49  ..<ul>.<li> [URI
2960: 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
2970: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 3c 6c  lite3_open()].<l
2980: 69 3e 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  i> [URI filename
2990: 20 65 78 61 6d 70 6c 65 73 5d 0a 3c 2f 75 6c 3e   examples].</ul>
29a0: 0a                                               .