Debian Codegraph @

www/uri.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="sqlite.css" rel="stylesheet">
6 <title>Uniform Resource Identifiers</title>
7 <!-- path= -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="index.html">
12 <img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='about.html'>About</a>
23 <li class='desktoponly'><a href="docs.html">Documentation</a>
24 <li class='desktoponly'><a href="download.html">Download</a>
25 <li class='wideonly'><a href='copyright.html'>License</a>
26 <li class='desktoponly'><a href="support.html">Support</a>
27 <li class='desktoponly'><a href="prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='about.html'>About</a>
35 <li><a href='docs.html'>Documentation</a>
36 <li><a href='download.html'>Download</a>
37 <li><a href='support.html'>Support</a>
38 <li><a href='prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <div class=fancy>
119 <div class=nosearch>
120 <div class="fancy_title">
121 Uniform Resource Identifiers
122 </div>
123 </div>
124
125
126
127
128
129 <h1 id="uri_filenames_in_sqlite"><span>1. </span>URI Filenames In SQLite</h1>
130
131 <p>
132 Beginning with <a href="releaselog/3_7_7.html">version 3.7.7</a> (2011-06-23),
133 the SQLite database file argument to the
134 <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
135 and to the <a href="lang_attach.html">ATTACH</a> command can be specified
136 either as an ordinary filename or as a Uniform Resource Identifier or URI.
137 The advantage of using a URI filename is that query parameters on the URI can
138 be used to control details of the newly created database connection.
139 For example, an alternative <a href="vfs.html">VFS</a> can be specified using a
140 "vfs=" query parameter.
141 Or the database can be opened read-only by using "mode=ro" as a query
142 parameter.
143 </p>
144
145 <h1 id="backwards_compatibility"><span>2. </span>Backwards Compatibility</h1>
146
147 <p>
148 In order to maintain full backwards compatibility for legacy applications,
149 the URI filename capability is disabled by default.
150 URI filenames can be enabled or disabled using the <a href="compile.html#use_uri">SQLITE_USE_URI=1</a>
151 or <a href="compile.html#use_uri">SQLITE_USE_URI=0</a> compile-time options.
152 The compile-time setting for URI filenames can be changed
153 at start-time using the <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfiguri">SQLITE_CONFIG_URI</a>,1)
154 or <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfiguri">SQLITE_CONFIG_URI</a>,0) configuration calls.
155 Regardless of the compile-time or start-time settings, URI filenames
156 can be enabled for individual database connections by including the
157 <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a> bit in the set of bits passed as the F parameter
158 to <a href="c3ref/open.html">sqlite3_open_v2(N,P,F,V)</a>.
159 </p>
160
161 <p>
162 If URI filenames are recognized when the database connection is originally
163 opened, then URI filenames will also be recognized on <a href="lang_attach.html">ATTACH</a> statements.
164 Similarly, if URI filenames are not recognized when the database connection
165 is first opened, they will not be recognized by <a href="lang_attach.html">ATTACH</a>.
166 </p>
167
168 <p>
169 Since SQLite always interprets any filename that does not begin
170 with "<tt>file:</tt>"
171 as an ordinary filename regardless of the URI setting, and because it is
172 very unusual to have an actual file begin with "<tt>file:</tt>",
173 it is safe for most applications to enable URI processing even if URI
174 filenames are not currently being used.
175 </p>
176
177 <h1 id="uri_format"><span>3. </span>URI Format</h1>
178
179 <p>
180 According to <a href="http://tools.ietf.org/html/rfc3986">RFC 3986</a>, a URI consists
181 of a scheme, an authority, a path, a query string, and a fragment. The
182 scheme is always required. One of either the authority or the path is also
183 always required. The query string and fragment are optional.
184 </p>
185
186 <p>
187 SQLite uses the "<tt>file:</tt>" URI syntax to identify database files.
188 SQLite strives to interpret file: URIs in exactly the same way as
189 popular web-browsers such as
190 <a href="http://www.mozilla.com/en-US/firefox/new/">Firefox</a>,
191 <a href="http://www.google.com/chrome/">Chrome</a>,
192 <a href="http://www.apple.com/safari/">Safari</a>,
193 <a href="http://windows.microsoft.com/en-US/internet-explorer/products/ie/home">Internet Explorer</a>, and
194 <a href="http://www.opera.com/">Opera</a>,
195 and command-line programs such as Windows
196 <a href="https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/start">"cmd start"</a>
197 or
198 <a href="https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/start-process?view=powershell-7.3">"powershell start"</a>,
199 or the macOS "open" or Linux "xdg-open" commands.
200 A succinct summary of the URI parsing rules follows:
201 </p>
202
203 <ul>
204 <li> The scheme of the URI must be "<tt>file:</tt>". Any other scheme
205 results in the input being treated as an ordinary filename.
206 </li><li> The authority may be omitted, may be blank, or may be
207 "<tt>localhost</tt>". Any other authority results in an error.
208 Exception: If SQLite is compiled with <a href="compile.html#allow_uri_authority">SQLITE_ALLOW_URI_AUTHORITY</a>
209 then any authority value other than "localhost" is passed through to the
210 underlying operating system as a UNC filename.
211 </li><li> The path is optional if the authority is present. If the authority
212 is omitted then the path is required.
213 </li><li> The query string is optional. If the query string is present, then
214 all query parameters are passed through into the xOpen method of
215 the underlying <a href="vfs.html">VFS</a>.
216 </li><li> The fragment is optional. If present, it is ignored.
217 </li></ul>
218
219 <p>Zero or more escape sequences of the form "<b>%<i>HH</i></b>"
220 (where <b><i>H</i></b> represents any hexadecimal digit) can occur
221 in the path, query string, or fragment.</p>
222
223 <p>A filename that is not a well-formed URI is interpreted as an
224 ordinary filename.</p>
225
226 <p>URIs are processed as UTF8 text.
227 The filename argument sqlite3_open16() is converted from UTF16
228 native byte order into UTF8 prior to processing.
229
230 </p><h2 id="the_uri_path"><span>3.1. </span>The URI Path</h2>
231
232 <p>The path component of the URI specifies the disk file that is the
233 SQLite database to be opened. If the path component is omitted, then
234 the database is stored in a temporary file that will be automatically
235 deleted when the database connection closes. If the authority section
236 is present, then the path is always an absolute pathname. If the
237 authority section is omitted, then the path is an absolute pathname if it
238 begins with the "/" character (ASCII code 0x2f) and is a relative
239 pathname otherwise. On windows, if the absolute path begins with
240 "<b>/<i>X</i>:/</b>" where <b><i>X</i></b> is any single ASCII alphabetic
241 character ("a" through "z" or "A" through "Z") then the "<b><i>X:</i></b>"
242 is understood to be the drive letter of the volume containing the file,
243 not the toplevel directory.
244
245 </p><p>An ordinary filename can usually be converted into an equivalent URI
246 by the steps shown below. The one exception is that a relative windows
247 pathname with a drive letter cannot be converted directly into a URI; it must
248 be changed into an absolute pathname first.</p>
249
250 <ol>
251 <li>Convert all "<tt>?</tt>" characters into "<tt>%3f</tt>".
252 </li><li>Convert all "<tt>#</tt>" characters into "<tt>%23</tt>".
253 </li><li>On windows only, convert all "<tt>\</tt>" characters into "<tt>/</tt>".
254 </li><li>Convert all sequences of two or more "<tt>/</tt>" characters into a
255 single "<tt>/</tt>" character.
256 </li><li>On windows only, if the filename begins with a drive letter, prepend
257 a single "<tt>/</tt>" character.
258 </li><li>Prepend the "<tt>file:</tt>" scheme.
259 </li></ol>
260
261 <h2 id="query_string"><span>3.2. </span>Query String</h2>
262
263 <p>A URI filename can optionally be followed by a query string.
264 The query string consists of text following the first "<tt>?</tt>"
265 character but excluding the optional fragment that begins with
266 "<tt>#</tt>". The query string is divided into key/value pairs.
267 We usually refer to these key/value pairs as "query parameters".
268 Key/value pairs are separated by a single "<tt>&amp;</tt>" character.
269 The key comes first and is separated from the value by a single
270 "<tt>=</tt>" character.
271 Both key and value may contain <b>%HH</b> escape sequences.</p>
272
273 <p>
274 The text of query parameters is appended to the filename argument of
275 the xOpen method of the <a href="vfs.html">VFS</a>.
276 Any %HH escape sequences in the query parameters are resolved prior to
277 being appended to the xOpen filename.
278 A single zero-byte separates the xOpen filename argument from the key of
279 the first query parameters, each key and value, and each subsequent key
280 from the prior value.
281 The list of query parameters appended to the xOpen filename
282 is terminated by a single zero-length key.
283 Note that the value of a query parameter can be an empty string.
284 </p>
285
286 <a name="coreqp"></a>
287
288 <h2 id="recognized_query_parameters"><span>3.3. </span>Recognized Query Parameters</h2>
289
290 <p>
291 Some query parameters are interpreted by the SQLite core and used to
292 modify the characteristics of the new connection. All query parameters
293 are always passed through into the xOpen method of the <a href="vfs.html">VFS</a> even if
294 they are previously read and interpreted by the SQLite core.
295 </p>
296
297 <p>
298 The following query parameters are recognized by SQLite as of
299 <a href="releaselog/3_15_0.html">version 3.15.0</a> (2016-10-14).
300 New query parameters might be added in the future.
301 </p>
302
303 <dl>
304 <a name="uricache"></a>
305
306 <dt><b>cache=shared<br>cache=private</b></dt>
307 <dd><p>The cache query parameter determines if the new database is opened
308 using <a href="sharedcache.html">shared cache mode</a> or with a private cache.
309 </p></dd>
310
311 <a name="uriimmutable"></a>
312
313 <dt><b>immutable=1</b></dt>
314 <dd><p>The immutable query parameter is a boolean that signals to
315 SQLite that the underlying database file is held on read-only media
316 and cannot be modified, even by another process with elevated
317 privileges. SQLite always opens immutable database files
318 read-only and it skips all file locking and change detection
319 on immutable database files. If this query parameter (or
320 the <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_IMMUTABLE</a> bit in xDeviceCharacteristics)
321 asserts that a database file is immutable and that file
322 changes anyhow, then SQLite might return incorrect query
323 results and/or <a href="rescode.html#corrupt">SQLITE_CORRUPT</a> errors.
324 </p></dd>
325
326 <a name="urimode"></a>
327
328 <dt><b>mode=ro<br>mode=rw<br>mode=rwc<br>mode=memory</b></dt>
329 <dd><p>The mode query parameter determines if the new database is opened
330 read-only, read-write, read-write and created if it does not exist, or
331 that the database is a pure in-memory database that never interacts with
332 disk, respectively.
333 </p></dd>
334
335 <a name="urimodeof"></a>
336
337 <dt><b>modeof=</b><i>filename</i></dt>
338 <dd><p>When creating a new database file during <a href="c3ref/open.html">sqlite3_open_v2()</a>
339 on unix systems, SQLite will try to set the permissions of the new
340 database file to match the existing file "<i>filename</i>".
341 </p></dd>
342
343 <a name="urinolock"></a>
344
345 <dt><b>nolock=1</b></dt>
346 <dd><p>The nolock query parameter is a boolean that disables all calls
347 to the xLock, xUnlock, and xCheckReservedLock methods of the VFS when true.
348 The nolock query parameter might be used, for example, when trying to
349 access a file on a filesystem that does not support file locking.
350 Caution: If two or more <a href="c3ref/sqlite3.html">database connections</a> try to interact with
351 the same SQLite database and one or more of those connections has
352 enabled "nolock", then database corruption can result. The "nolock"
353 query parameter should only be used if the application can guarantee
354 that writes to the database are serialized.
355
356 <a name="uripsow"></a>
357
358 </p></dd><dt><b>psow=0<br>psow=1</b></dt>
359 <dd><p>The psow query parameter overrides the <a href="psow.html">powersafe overwrite</a>
360 property of the database file being opened. The psow query parameter
361 works with the default windows and unix <a href="vfs.html">VFSes</a> but might be a no-op for
362 other proprietary or non-standard VFSes.
363 </p></dd>
364
365 <a name="urivfs"></a>
366
367 <dt><b>vfs=</b><i>NAME</i></dt>
368 <dd><p>The vfs query parameter causes the database connection to be opened
369 using the <a href="vfs.html">VFS</a> called <i>NAME</i>.
370 The open attempt fails if <i>NAME</i> is not the name of a <a href="vfs.html">VFS</a> that
371 is built into SQLite or that has been previously registered using
372 <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>.</p></dd>
373 </dl>
374
375 <h1 id="see_also"><span>4. </span>See Also</h1>
376
377 <ul>
378 <li> <a href="c3ref/open.html#urifilenamesinsqlite3open">URI filenames in sqlite3_open()</a>
379 </li><li> <a href="c3ref/open.html#urifilenameexamples">URI filename examples</a>
380 </li></ul>
381 <p align="center"><small><i>This page was last updated on 2023-01-02 14:22:42Z </small></i></p>
382