1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Uniform Resource Identifiers</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
72
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="about.html">About</a>
83
<a href="sitemap.html">Sitemap</a>
84
<a href="docs.html">Documentation</a>
85
<a href="download.html">Download</a>
86
<a href="copyright.html">License</a>
87
<a href="news.html">News</a>
88
<a href="support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
123
<h1>1.0 URI Filenames In SQLite</h1>
126
Beginning with <a href="releaselog/3_7_7.html">version 3.7.7</a>, the SQLite database file argument to the
127
<a href="c3ref/open.html">sqlite3_open()</a>, <a href="c3ref/open.html">sqlite3_open16()</a>, and <a href="c3ref/open.html">sqlite3_open_v2()</a> interfaces
128
and to the <a href="lang_attach.html">ATTACH</a> command can be specified
129
either as an ordinary filename or as a Uniform Resource Identifier or URI.
130
The advantage of using a URI filename is that query parameters on the URI can
131
be used to control details of the newly created database connection.
132
For example, an alternative <a href="vfs.html">VFS</a> can be specified using a
133
"vfs=" query parameter.
134
Or the database can be opened read-only by using "mode=ro" as a query
138
<h1>2.0 Backwards Compatibility</h1>
141
In order to maintain full backwards compatibility for legacy applications,
142
the URI filename capability is disabled by default.
143
In order for URI filenames
144
to work, one or more of the following must be true:
148
<li><p>The SQLite library is compiled with the <a href="compile.html#use_uri">SQLITE_USE_URI</a>
149
compile-time option.</p></li>
150
<li><p>The <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfiguri">SQLITE_CONFIG_URI</a>, 1); configuration option
151
is set at application start-time.</p></li>
152
<li><p>The <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a> bit is OR-ed in with the set bits passed in
153
as the 3rd parameter to the <a href="c3ref/open.html">sqlite3_open_v2()</a> interface.</p></li>
157
If URI filenames are recognized when the database connection is originally
158
opened, then URI filenames will also be recognized on <a href="lang_attach.html">ATTACH</a> statements.
159
Similarly, if URI filenames are not recognized when the database connection
160
is first opened, they will not be recognized by <a href="lang_attach.html">ATTACH</a>.
164
Since SQLite always interprets any filename that does not begins
165
with "<tt>file:</tt>"
166
as an ordinary filename regardless of the URI setting, and because it is
167
very unusual to have an actual file begin with "<tt>file:</tt>",
168
it is safe for most applications to enable URI processing even if URI
169
filenames are not currently being used.
172
<h1>3.0 URI Format</h1>
175
According to <a href="http://tools.ietf.org/html/rfc3986">RFC 3986</a>, a URI consists
176
of a scheme, an authority, a path, a query string, and a fragment. The
177
scheme is always required. One of either the authority or the path is also
178
always required. The query string and fragment are optional.
182
SQLite uses the "<tt>file:</tt>" URI syntax to identify database files.
183
SQLite strives to interpret file: URIs in exactly the same way as
184
popular web-browsers such as
185
<a href="http://www.mozilla.com/en-US/firefox/new/">Firefox</a>,
186
<a href="http://www.google.com/chrome/">Chrome</a>,
187
<a href="http://www.apple.com/safari/">Safari</a>,
188
<a href="http://windows.microsoft.com/en-US/internet-explorer/products/ie/home">Internet Explorer</a>, and
189
<a href="http://www.opera.com/">Opera</a>,
190
and command-line programs such as
191
<a href="http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/start.mspx">Windows "start"</a> and the Mac OS-X
192
<a href="http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/open.1.html">"open"</a> command.
193
A succinct summary of the URI parsing rules follows:
197
<li> The scheme of the URI must be "<tt>file:</tt>". Any other scheme
198
results in the input being treated as an ordinary filename.
199
<li> The authority may be omitted, may be blank, or may be
200
"<tt>localhost</tt>". Any other authority results in an error.
201
<li> The path is optional if the authority is present. If the authority
202
is omitted then the path is required.
203
<li> The query string is optional. If the query string is present, then
204
all query parameters are passed through into the xOpen method of
205
the underlying <a href="vfs.html">VFS</a>.
206
<li> The fragment is optional. If present, it is ignored.
209
<p>Zero or more escape sequences of the form "<b>%<i>HH</i></b>"
210
(where <b><i>H</i></b> represents any hexadecimal digit) can occur
211
in the path, query string, or fragment.</p>
213
<p>A filename that is not a well-formed URI is interpreted as an
214
ordinary filename.</p>
216
<p>URIs are processed as UTF8 text.
217
The filename argument sqlite3_open16() is converted from UTF16
218
native byte order into UTF8 prior to processing.
220
<h2>3.1 The URI Path</h2>
222
<p>The path component of the URI specifies the disk file that is the
223
SQLite database to be opened. If the path component is omitted, then
224
the database is stored in a temporary file that will be automatically
225
deleted when the database connection closes. If the authority section
226
is present, then the path is always an absolute pathname. If the
227
authority section is omitted, then the path is an absolute pathname if it
228
begins with the "/" character (ASCII code 0x2f) and is a relative
229
pathname otherwise. On windows, if the absolute path begins with
230
"<b>/<i>X</i>:/</b>" where <b><i>X</i></b> is any single ASCII alphabetic
231
character ("a" through "z" or "A" through "Z") then the "<b><i>X:</i></b>"
232
is understood to be the drive letter of the volume containing the file,
233
not the toplevel directory.
235
<p>An ordinary filename can usually be converted into an equivalent URI
236
by the steps shown below. The one exception is that a relative windows
237
pathname with a drive letter cannot be converted directly into a URI; it must
238
be changed into an absolute pathname first.</p>
241
<li>Convert all "<tt>?</tt>" characters into "<tt>%3f</tt>".
242
<li>Convert all "<tt>#</tt>" characters into "<tt>%23</tt>".
243
<li>On windows only, convert all "<tt>\</tt>" characters into "<tt>/</tt>".
244
<li>Convert all sequences of two or more "<tt>/</tt>" characters into a
245
single "<tt>/</tt>" character.
246
<li>On windows only, if the filename begins with a drive letter, prepend
247
a single "<tt>/</tt>" character.
248
<li>Prepend the "<tt>file:</tt>" scheme.
251
<h2>3.2 Query String</h2>
253
<p>A URI filename can optionally be followed by a query string.
254
The query string consists of text following the first "<tt>?</tt>"
255
character but excluding the optional fragment that begins with with
256
"<tt>#</tt>". The query string is divided into key/value pairs.
257
We usually refer to these key/value pairs as "query parameters".
258
Key/value pairs are separated by a single "<tt>&</tt>" character.
259
The key comes first and is separated from the value by a single
260
"<tt>=</tt>" character.
261
Both key and value may contain <b>%HH</b> escape sequences.</p>
264
The text of query parameters is appended to the filename argument of
265
the xOpen method of the <a href="vfs.html">VFS</a>.
266
Any %HH escape sequences in the query parameters are resolved prior to
267
being appended to the xOpen filename.
268
A single zero-byte separates the xOpen filename argument from the key of
269
the first query parameters, each key and value, and each subsequent key
270
from the prior value.
271
The list of query parameters parameters appended to the xOpen filename
272
is terminated by a single zero-length key.
273
Note that the value of a query parameter can be an empty string.
276
<a name="coreqp"></a>
278
<h2>3.3 Recognized Query Parameters</h2>
281
Some query parameters are interpreted by the SQLite core and used to
282
modify the characteristics of the new connection. All query parameters
283
are always passed through into the xOpen method of the <a href="vfs.html">VFS</a> even if
284
they are previously read and interpreted by the SQLite core.
288
The following query parameters are recognized by SQLite as of version 3.7.10.
289
Other query parameters might be added to this set in future releases.
293
<dt><b>vfs=</b><i>NAME</i></dt>
294
<dd><p>The vfs query parameter causes the database connection to be opened
295
using the <a href="vfs.html">VFS</a> called <i>NAME</i>.
296
The open attempt fails if <i>NAME</i> is not the name of a <a href="vfs.html">VFS</a> that
297
is built into SQLite or that has been previously registered using
298
<a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>.</dd>
300
<dt><b>mode=ro<br>mode=rw<br>mode=rwc<br>mode=memory</b></dt>
301
<dd><p>The mode query parameter determines if the new database is opened
302
read-only, read-write, read-write and created if it does not exist, or
303
that the database is a pure in-memory database that never interacts with
304
disk, respectively. The <b>mode=memory</b> option was added in
305
<a href="releaselog/3_7_13.html">version 3.7.13</a>.
308
<dt><b>cache=shared<br>cache=private</b></dt>
309
<dd><p>The cache query parameter determines if the new database is opened
310
using <a href="sharedcache.html">shared cache mode</a> or with a private cache.
313
<dt><b>psow=0<br>psow=1</b></dt>
314
<dd><p>The psow query parameter overrides the <a href="psow.html">powersafe overwrite</a>
315
property of the database file being opened. The psow query parameter
316
works with the default windows and unix <a href="vfs.html">VFSes</a> but might be a no-op for
317
other proprietary or non-standard VFSes.
321
<h1>4.0 See Also</h1>
324
<li> <a href="c3ref/open.html#urifilenamesinsqlite3open">URI filenames in sqlite3_open()</a>
325
<li> <a href="c3ref/open.html#urifilenameexamples">URI filename examples</a>
added
removed
uri.html
