Artifact
919838c9eb9eed3045784f5ccfa9262718a31dec:
- File
pages/uri.in
— part of check-in
[b503d1f516]
at
2011-06-20 21:48:16
on branch trunk
— Documentation typos.
(user:
drh
size: 8341)
<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.)^
<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>&</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 {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.7.
Other query parameters might be added to this set in future releases.
</p>
<dl>
<dt><b>vfs=</b><i>NAME</i></dt>
<dd><p>^This 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</b></dt>
<dd><p>^These query parameters determine if the new database is opened
read-only, read-write, or read-write and created if it does not exist,
respectively.
</dd>
<dt><b>cache=shared<br>cache=private</b></dt>
<dd><p>^These query parameters determine if the new database is opened
using [shared cache mode] or with a private cache, respectively.
</dd>
</dl>
<h1>4.0 See Also</h1>
<ul>
<li> [URI filenames in sqlite3_open()]
<li> [URI filename examples]
</ul>