<title>Uniform Resource Identifiers</title>
<tcl>
hd_keywords {URI} {Uniform Resource Identifier} {URI filename} {URI filenames}
</tcl>

<h1>1.0 URI Filenames In SQLite</h1>

<p>
Beginning with [version 3.7.7], the SQLite database file argument to the
[sqlite3_open()], [sqlite3_open16()], and [sqlite3_open_v2()] interfaces
and to the [ATTACH] command can be specified
either as an ordinary filename or as a Uniform Resource Identifier or URI.
The advantage of using a URI filename is that query parameters on the URI can
be used to control details of the newly created database connection.
For example, an alternative [VFS] can be specified using a 
"vfs=" query parameter.
Or the database can be opened read-only by using "mode=ro" as a query
parameter.
</p>

<h1>2.0 Backwards Compatibility</h1>

<p>
In order to maintain full backwards compatibility for legacy applications,
the URI filename capability is disabled by default.  
^(In order for URI filenames
to work, one or more of the following must be true:
</p>

<ol>
<li><p>The SQLite library is compiled with the [SQLITE_USE_URI] 
       compile-time option.</p></li>
<li><p>The [sqlite3_config]([SQLITE_CONFIG_URI], 1); configuration option
       is set at application start-time.</p></li>
<li><p>The [SQLITE_OPEN_URI] bit is OR-ed in with the set bits passed in
       as the 3rd parameter to the [sqlite3_open_v2()] interface.</p></li>
</ol>)^

<p>
^If URI filenames are recognized when the database connection is originally
opened, then URI filenames will also be recognized on [ATTACH] statements.
^Similarly, if URI filenames are not recognized when the database connection
is first opened, they will not be recognized by [ATTACH].
</p>

<p>
Since SQLite always interprets any filename that does not begins 
with "<tt>file:</tt>"
as an ordinary filename regardless of the URI setting, and because it is
very unusual to have an actual file begin with "<tt>file:</tt>", 
it is safe for most applications to enable URI processing even if URI 
filenames are not currently being used.
</p>

<h1>3.0 URI Format</h1>

<p>
According to [http://tools.ietf.org/html/rfc3986 | RFC 3986], a URI consists
of a scheme, an authority, a path, a query string, and a fragment.  The
scheme is always required.  One of either the authority or the path is also
always required.  The query string and fragment are optional.
</p>

<p>
SQLite uses the "<tt>file:</tt>" URI syntax to identify database files.
SQLite strives to interpret file: URIs in exactly the same way as
popular web-browsers such as 
[http://www.mozilla.com/en-US/firefox/new/ | Firefox], 
[http://www.google.com/chrome/ | Chrome], 
[http://www.apple.com/safari/ | Safari], 
[http://windows.microsoft.com/en-US/internet-explorer/products/ie/home | Internet Explorer], and
[http://www.opera.com/ | Opera],
and command-line programs such as 
[http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/start.mspx | Windows "start"] and the Mac OS-X
[http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/open.1.html | "open"] command.
A succinct summary of the URI parsing rules follows:
</p>

<ul>
<li> ^(The scheme of the URI must be "<tt>file:</tt>".  Any other scheme
     results in the input being treated as an ordinary filename.)^
<li> ^(The authority may be omitted, may be blank, or may be
      "<tt>localhost</tt>".  Any other authority results in an error.)^
      Exception: If SQLite is compiled with [SQLITE_ALLOW_URI_AUTHORITY]
      then any authority value other than "localhost" is passed through to the 
      underlying operating system as a UNC filename.
<li> ^The path is optional if the authority is present.  ^If the authority
     is omitted then the path is required. 
<li> ^The query string is optional.  ^If the query string is present, then
      all query parameters are passed through into the xOpen method of
      the underlying [VFS].  
<li> ^(The fragment is optional.  If present, it is ignored.)^
</ul>

<p>^Zero or more escape sequences of the form  "<b>%<i>HH</i></b>" 
(where <b><i>H</i></b> represents any hexadecimal digit) can occur 
in the path, query string, or fragment.</p>

<p>^A filename that is not a well-formed URI is interpreted as an
ordinary filename.</p>

<p>^URIs are processed as UTF8 text.
^The filename argument sqlite3_open16() is converted from UTF16 
native byte order into UTF8 prior to processing.

<h2>3.1 The URI Path</h2>

<p>^The path component of the URI specifies the disk file that is the
SQLite database to be opened.  ^(If the path component is omitted, then
the database is stored in a temporary file that will be automatically
deleted when the database connection closes.)^  ^If the authority section
is present, then the path is always an absolute pathname.  ^If the 
authority section is omitted, then the path is an absolute pathname if it
begins with the "/" character (ASCII code 0x2f) and is a relative
pathname otherwise.  ^(On windows, if the absolute path begins with
"<b>/<i>X</i>:/</b>" where <b><i>X</i></b> is any single ASCII alphabetic
character ("a" through "z" or "A" through "Z") then the "<b><i>X:</i></b>"
is understood to be the drive letter of the volume containing the file,
not the toplevel directory.)^

<p>An ordinary filename can usually be converted into an equivalent URI 
by the steps shown below.  The one exception is that a relative windows
pathname with a drive letter cannot be converted directly into a URI; it must
be changed into an absolute pathname first.</p>

<ol>
<li>Convert all "<tt>?</tt>" characters into "<tt>%3f</tt>".
<li>Convert all "<tt>#</tt>" characters into "<tt>%23</tt>".
<li>On windows only, convert all "<tt>\</tt>" characters into "<tt>/</tt>".
<li>Convert all sequences of two or more "<tt>/</tt>" characters into a
    single "<tt>/</tt>" character.
<li>On windows only, if the filename begins with a drive letter, prepend
    a single "<tt>/</tt>" character.
<li>Prepend the "<tt>file:</tt>" scheme.
</ol>

<h2>3.2 Query String</h2>

<p>^A URI filename can optionally be followed by a query string.
^The query string consists of text following the first "<tt>?</tt>"
character but excluding the optional fragment that begins with with
"<tt>#</tt>".  ^The query string is divided into key/value pairs.
We usually refer to these key/value pairs as "query parameters".
^Key/value pairs are separated by a single "<tt>&amp;</tt>" character.
^The key comes first and is separated from the value by a single
"<tt>=</tt>" character.
^Both key and value may contain <b>%HH</b> escape sequences.</p>

<p>
^The text of query parameters is appended to the filename argument of
the xOpen method of the [VFS].
^Any %HH escape sequences in the query parameters are resolved prior to
being appended to the xOpen filename.
^A single zero-byte separates the xOpen filename argument from the key of
the first query parameters, each key and value, and each subsequent key
from the prior value.
^The list of query parameters parameters appended to the xOpen filename
is terminated by a single zero-length key.
Note that the value of a query parameter can be an empty string.
</p>

<tcl>hd_fragment coreqp *coreqp\
    {query parameters with special meaning to SQLite}</tcl>
<h2>3.3 Recognized Query Parameters</h2>

<p>
Some query parameters are interpreted by the SQLite core and used to 
modify the characteristics of the new connection.  ^All query parameters
are always passed through into the xOpen method of the [VFS] even if
they are previously read and interpreted by the SQLite core.
</p>

<p>
The following query parameters are recognized by SQLite as of version 3.7.10.
Other query parameters might be added to this set in future releases.
</p>

<dl>
<dt><b>vfs=</b><i>NAME</i></dt>
<dd><p>^The vfs query parameter causes the database connection to be opened
using the [VFS] called <i>NAME</i>.
^The open attempt fails if <i>NAME</i> is not the name of a [VFS] that
is built into SQLite or that has been previously registered using
[sqlite3_vfs_register()].</dd>

<dt><b>mode=ro<br>mode=rw<br>mode=rwc<br>mode=memory</b></dt>
<dd><p>^The mode query parameter determines if the new database is opened
read-only, read-write, read-write and created if it does not exist, or
that the database is a pure in-memory database that never interacts with
disk, respectively.  The <b>mode=memory</b> option was added in 
[version 3.7.13].
</dd>

<dt><b>cache=shared<br>cache=private</b></dt>
<dd><p>^The cache query parameter determines if the new database is opened
using [shared cache mode] or with a private cache.
</dd>

<dt><b>psow=0<br>psow=1</b></dt>
<dd><p>^The psow query parameter overrides the [powersafe overwrite]
property of the database file being opened.  ^The psow query parameter
works with the default windows and unix [VFSes] but might be a no-op for
other proprietary or non-standard VFSes.
</dd>
</dl>

<h1>4.0 See Also</h1>

<ul>
<li> [URI filenames in sqlite3_open()]
<li> [URI filename examples]
</ul>
