Documentation Source Text

[database corruption caused by inconsistent use of 8+3 filenames].
</p>

<h2>Adjusting SQLite To Use 8+3 Filenames</h2>

<p>
Some devices are compelled to use an older filesystem with 8+3
filename restructions in order to be compatible with legacy, or due
to other non-technical factors.  In such situations, SQLite can be
coerced into using auxiliary files that fit the 8+3 pattern as follows:
</p>

<ol>
<li><p>Compile the SQLite library with the [SQLITE_ENABLE_8_3_NAMES]
       compile-time option.
       Support for 8+3 filenames is not included in SQLite by default
       because it does introduce some overhead.  The overhead is tiny,
       but even so, we do not want to burden the billions of SQLite
       applications that do not need 8+3 filename support.</p>

<li><p>Use [URI filenames] when [sqlite3_open | opening] or
       [ATTACH | ATTACH-ing] database files and include the
       "<tt>8_3_names=1</tt>" query parameter in the URI.</p>

<li><p>Make sure that database filenames follow the 8+3 filename
       format and that they do not have an empty name or extension.
       In other words, the database filename must not contain between
       1 and 8 characters in the base name and between 1 and 3 characters
       in the extension.  Blank extensions are not allows.</p>
</ol>

<p>
When the steps above are used, SQLite will shorten filename extensions
by only using the last 3 characters of
the extension.  Thus, for example, a file that would normally be called
"<tt>app.db-journal</tt>" is shortened to just "<tt>app.nal</tt>".

<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 "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>

^If URI filenames are recognized when the database connection is originally
opened, then URI filenames will also be recognized on [ATTACH] statemenets.
^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 begin 
with "<tt>file:</tt>" is interpreted
as an ordinary filename regardless of the URI setting, and because it is
very unusual to have an actual file that beings with "<tt>file:</tt>", for
most applications it is safe to enable URI processing even if URI filenames
are not currently being used.
</p>

<h1>3.0 URI Format</h1>

<p>

^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
a temporary files is opened as a new database that will be automatically
deleted when the database connection closes.)^  ^If the authority section
is present, then the path is alway 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 the volume containing the file,
not the toplevel directory.)^

<p>An ordinary filename can usually be converted into an equivalent URI 
by the step 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>".

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 to
the xOpen method of the [VFS].
^Any %HH escape sequences in the query parameters are resolved prior to
being appended ot 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 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>
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 cases 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