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>