Debian Codegraph @

www/c3ref/open.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>Opening A New Database Connection</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 <!-- keywords: sqlite3_open sqlite3_open16 sqlite3_open_v2 -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Opening A New Database Connection</h2>
122 </div>
123 <blockquote><pre>
124 int sqlite3_open(
125 const char *filename, /* Database filename (UTF-8) */
126 sqlite3 **ppDb /* OUT: SQLite db handle */
127 );
128 int sqlite3_open16(
129 const void *filename, /* Database filename (UTF-16) */
130 sqlite3 **ppDb /* OUT: SQLite db handle */
131 );
132 int sqlite3_open_v2(
133 const char *filename, /* Database filename (UTF-8) */
134 sqlite3 **ppDb, /* OUT: SQLite db handle */
135 int flags, /* Flags */
136 const char *zVfs /* Name of VFS module to use */
137 );
138 </pre></blockquote>
139 <p>
140 These routines open an SQLite database file as specified by the
141 filename argument. The filename argument is interpreted as UTF-8 for
142 sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
143 order for sqlite3_open16(). A <a href="../c3ref/sqlite3.html">database connection</a> handle is usually
144 returned in *ppDb, even if an error occurs. The only exception is that
145 if SQLite is unable to allocate memory to hold the <a href="../c3ref/sqlite3.html">sqlite3</a> object,
146 a NULL will be written into *ppDb instead of a pointer to the <a href="../c3ref/sqlite3.html">sqlite3</a>
147 object. If the database is opened (and/or created) successfully, then
148 <a href="../rescode.html#ok">SQLITE_OK</a> is returned. Otherwise an <a href="../rescode.html">error code</a> is returned. The
149 <a href="../c3ref/errcode.html">sqlite3_errmsg()</a> or <a href="../c3ref/errcode.html">sqlite3_errmsg16()</a> routines can be used to obtain
150 an English language description of the error following a failure of any
151 of the sqlite3_open() routines.</p>
152
153 <p>The default encoding will be UTF-8 for databases created using
154 sqlite3_open() or sqlite3_open_v2(). The default encoding for databases
155 created using sqlite3_open16() will be UTF-16 in the native byte order.</p>
156
157 <p>Whether or not an error occurs when it is opened, resources
158 associated with the <a href="../c3ref/sqlite3.html">database connection</a> handle should be released by
159 passing it to <a href="../c3ref/close.html">sqlite3_close()</a> when it is no longer required.</p>
160
161 <p>The sqlite3_open_v2() interface works like sqlite3_open()
162 except that it accepts two additional parameters for additional control
163 over the new database connection. The flags parameter to
164 sqlite3_open_v2() must include, at a minimum, one of the following
165 three flag combinations:</p>
166
167 <p><dl>
168 <dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a></dt>
169 <dd>The database is opened in read-only mode. If the database does
170 not already exist, an error is returned.</dd></p>
171
172 <p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a></dt>
173 <dd>The database is opened for reading and writing if possible, or
174 reading only if the file is write protected by the operating
175 system. In either case the database must already exist, otherwise
176 an error is returned. For historical reasons, if opening in
177 read-write mode fails due to OS-level permissions, an attempt is
178 made to open it in read-only mode. <a href="../c3ref/db_readonly.html">sqlite3_db_readonly()</a> can be
179 used to determine whether the database is actually
180 read-write.</dd></p>
181
182 <p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a> | <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_CREATE</a></dt>
183 <dd>The database is opened for reading and writing, and is created if
184 it does not already exist. This is the behavior that is always used for
185 sqlite3_open() and sqlite3_open16().</dd>
186 </dl></p>
187
188 <p>In addition to the required flags, the following optional flags are
189 also supported:</p>
190
191 <p><dl>
192 <dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a></dt>
193 <dd>The filename can be interpreted as a URI if this flag is set.</dd></p>
194
195 <p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_MEMORY</a></dt>
196 <dd>The database will be opened as an in-memory database. The database
197 is named by the "filename" argument for the purposes of cache-sharing,
198 if shared cache mode is enabled, but the "filename" is otherwise ignored.
199 </dd></p>
200
201 <p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOMUTEX</a></dt>
202 <dd>The new database connection will use the "multi-thread"
203 <a href="../threadsafe.html">threading mode</a>. This means that separate threads are allowed
204 to use SQLite at the same time, as long as each thread is using
205 a different <a href="../c3ref/sqlite3.html">database connection</a>.</p>
206
207 <p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_FULLMUTEX</a></dt>
208 <dd>The new database connection will use the "serialized"
209 <a href="../threadsafe.html">threading mode</a>. This means the multiple threads can safely
210 attempt to use the same database connection at the same time.
211 (Mutexes will block any actual concurrency, but in this mode
212 there is no harm in trying.)</p>
213
214 <p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_SHAREDCACHE</a></dt>
215 <dd>The database is opened with <a href="../sharedcache.html">shared cache</a> enabled, overriding
216 the default shared cache setting provided by
217 <a href="../c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a>.
218 The <a href="../sharedcache.html#dontuse">use of shared cache mode is discouraged</a> and hence shared cache
219 capabilities may be omitted from many builds of SQLite. In such cases,
220 this option is a no-op.</p>
221
222 <p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_PRIVATECACHE</a></dt>
223 <dd>The database is opened with <a href="../sharedcache.html">shared cache</a> disabled, overriding
224 the default shared cache setting provided by
225 <a href="../c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a>.</p>
226
227 <p><a name="openexrescode"></a>
228 <dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXRESCODE</a></dt>
229 <dd>The database connection comes up in "extended result code mode".
230 In other words, the database behaves as if
231 <a href="../c3ref/extended_result_codes.html">sqlite3_extended_result_codes(db,1)</a> were called on the database
232 connection as soon as the connection is created. In addition to setting
233 the extended result code mode, this flag also causes <a href="../c3ref/open.html">sqlite3_open_v2()</a>
234 to return an extended result code.</dd></p>
235
236 <p><a name="opennofollow"></a>
237 <dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOFOLLOW</a></dt>
238 <dd>The database filename is not allowed to contain a symbolic link</dd>
239 </dl></p>
240
241 <p>If the 3rd parameter to sqlite3_open_v2() is not one of the
242 required combinations shown above optionally combined with other
243 <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_* bits</a>
244 then the behavior is undefined. Historic versions of SQLite
245 have silently ignored surplus bits in the flags parameter to
246 sqlite3_open_v2(), however that behavior might not be carried through
247 into future versions of SQLite and so applications should not rely
248 upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
249 for sqlite3_open_v2(). The SQLITE_OPEN_EXCLUSIVE does *not* cause
250 the open to fail if the database already exists. The SQLITE_OPEN_EXCLUSIVE
251 flag is intended for use by the <a href="../c3ref/vfs.html">VFS interface</a> only, and not
252 by sqlite3_open_v2().</p>
253
254 <p>The fourth parameter to sqlite3_open_v2() is the name of the
255 <a href="../c3ref/vfs.html">sqlite3_vfs</a> object that defines the operating system interface that
256 the new database connection should use. If the fourth parameter is
257 a NULL pointer then the default <a href="../c3ref/vfs.html">sqlite3_vfs</a> object is used.</p>
258
259 <p>If the filename is ":memory:", then a private, temporary in-memory database
260 is created for the connection. This in-memory database will vanish when
261 the database connection is closed. Future versions of SQLite might
262 make use of additional special filenames that begin with the ":" character.
263 It is recommended that when a database filename actually does begin with
264 a ":" character you should prefix the filename with a pathname such as
265 "./" to avoid ambiguity.</p>
266
267 <p>If the filename is an empty string, then a private, temporary
268 on-disk database will be created. This private database will be
269 automatically deleted as soon as the database connection is closed.</p>
270
271 <p><a name="urifilenamesinsqlite3open"></a>
272 <h3>URI Filenames</h3></p>
273
274 <p>If <a href="../uri.html">URI filename</a> interpretation is enabled, and the filename argument
275 begins with "file:", then the filename is interpreted as a URI. URI
276 filename interpretation is enabled if the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a> flag is
277 set in the third argument to sqlite3_open_v2(), or if it has
278 been enabled globally using the <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfiguri">SQLITE_CONFIG_URI</a> option with the
279 <a href="../c3ref/config.html">sqlite3_config()</a> method or by the <a href="../compile.html#use_uri">SQLITE_USE_URI</a> compile-time option.
280 URI filename interpretation is turned off
281 by default, but future releases of SQLite might enable URI filename
282 interpretation by default. See "<a href="../uri.html">URI filenames</a>" for additional
283 information.</p>
284
285 <p>URI filenames are parsed according to RFC 3986. If the URI contains an
286 authority, then it must be either an empty string or the string
287 "localhost". If the authority is not an empty string or "localhost", an
288 error is returned to the caller. The fragment component of a URI, if
289 present, is ignored.</p>
290
291 <p>SQLite uses the path component of the URI as the name of the disk file
292 which contains the database. If the path begins with a '/' character,
293 then it is interpreted as an absolute path. If the path does not begin
294 with a '/' (meaning that the authority section is omitted from the URI)
295 then the path is interpreted as a relative path.
296 On windows, the first component of an absolute path
297 is a drive specification (e.g. "C:").</p>
298
299 <p><a name="coreuriqueryparameters"></a>
300
301 The query component of a URI may contain parameters that are interpreted
302 either by SQLite itself, or by a <a href="../vfs.html">custom VFS implementation</a>.
303 SQLite and its built-in <a href="../vfs.html">VFSes</a> interpret the
304 following query parameters:</p>
305
306 <p><ul>
307 <li> <b>vfs</b>: The "vfs" parameter may be used to specify the name of
308 a VFS object that provides the operating system interface that should
309 be used to access the database file on disk. If this option is set to
310 an empty string the default VFS object is used. Specifying an unknown
311 VFS is an error. If sqlite3_open_v2() is used and the vfs option is
312 present, then the VFS specified by the option takes precedence over
313 the value passed as the fourth parameter to sqlite3_open_v2().</p>
314
315 <p><li> <b>mode</b>: The mode parameter may be set to either "ro", "rw",
316 "rwc", or "memory". Attempting to set it to any other value is
317 an error.
318 If "ro" is specified, then the database is opened for read-only
319 access, just as if the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a> flag had been set in the
320 third argument to sqlite3_open_v2(). If the mode option is set to
321 "rw", then the database is opened for read-write (but not create)
322 access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
323 been set. Value "rwc" is equivalent to setting both
324 SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. If the mode option is
325 set to "memory" then a pure <a href="../inmemorydb.html">in-memory database</a> that never reads
326 or writes from disk is used. It is an error to specify a value for
327 the mode parameter that is less restrictive than that specified by
328 the flags passed in the third parameter to sqlite3_open_v2().</p>
329
330 <p><li> <b>cache</b>: The cache parameter may be set to either "shared" or
331 "private". Setting it to "shared" is equivalent to setting the
332 SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
333 sqlite3_open_v2(). Setting the cache parameter to "private" is
334 equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
335 If sqlite3_open_v2() is used and the "cache" parameter is present in
336 a URI filename, its value overrides any behavior requested by setting
337 SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.</p>
338
339 <p><li> <b>psow</b>: The psow parameter indicates whether or not the
340 <a href="../psow.html">powersafe overwrite</a> property does or does not apply to the
341 storage media on which the database file resides.</p>
342
343 <p><li> <b>nolock</b>: The nolock parameter is a boolean query parameter
344 which if set disables file locking in rollback journal modes. This
345 is useful for accessing a database on a filesystem that does not
346 support locking. Caution: Database corruption might result if two
347 or more processes write to the same database and any one of those
348 processes uses nolock=1.</p>
349
350 <p><li> <b>immutable</b>: The immutable parameter is a boolean query
351 parameter that indicates that the database file is stored on
352 read-only media. When immutable is set, SQLite assumes that the
353 database file cannot be changed, even by a process with higher
354 privilege, and so the database is opened read-only and all locking
355 and change detection is disabled. Caution: Setting the immutable
356 property on a database file that does in fact change can result
357 in incorrect query results and/or <a href="../rescode.html#corrupt">SQLITE_CORRUPT</a> errors.
358 See also: <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_IMMUTABLE</a>.</p>
359
360 <p></ul></p>
361
362 <p>Specifying an unknown parameter in the query component of a URI is not an
363 error. Future versions of SQLite might understand additional query
364 parameters. See "<a href="../uri.html#coreqp">query parameters with special meaning to SQLite</a>" for
365 additional information.</p>
366
367 <p><a name="urifilenameexamples"></a>
368 <h3>URI filename examples</h3></p>
369
370 <p><table border="1" align=center cellpadding=5>
371 <tr><th> URI filenames <th> Results
372 <tr><td> file:data.db <td>
373 Open the file "data.db" in the current directory.
374 <tr><td> file:/home/fred/data.db<br>
375 file:///home/fred/data.db <br>
376 file://localhost/home/fred/data.db <br> <td>
377 Open the database file "/home/fred/data.db".
378 <tr><td> file://darkstar/home/fred/data.db <td>
379 An error. "darkstar" is not a recognized authority.
380 <tr><td style="white-space:nowrap">
381 file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
382 <td> Windows only: Open the file "data.db" on fred's desktop on drive
383 C:. Note that the %20 escaping in this example is not strictly
384 necessary - space characters can be used literally
385 in URI filenames.
386 <tr><td> file:data.db?mode=ro&cache=private <td>
387 Open file "data.db" in the current directory for read-only access.
388 Regardless of whether or not shared-cache mode is enabled by
389 default, use a private cache.
390 <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
391 Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
392 that uses dot-files in place of posix advisory locking.
393 <tr><td> file:data.db?mode=readonly <td>
394 An error. "readonly" is not a valid option for the "mode" parameter.
395 Use "ro" instead: "file:data.db?mode=ro".
396 </table></p>
397
398 <p>URI hexadecimal escape sequences (%HH) are supported within the path and
399 query components of a URI. A hexadecimal escape sequence consists of a
400 percent sign - "%" - followed by exactly two hexadecimal digits
401 specifying an octet value. Before the path or query components of a
402 URI filename are interpreted, they are encoded using UTF-8 and all
403 hexadecimal escape sequences replaced by a single byte containing the
404 corresponding octet. If this process generates an invalid UTF-8 encoding,
405 the results are undefined.</p>
406
407 <p><b>Note to Windows users:</b> The encoding used for the filename argument
408 of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
409 codepage is currently defined. Filenames containing international
410 characters must be converted to UTF-8 prior to passing them into
411 sqlite3_open() or sqlite3_open_v2().</p>
412
413 <p><b>Note to Windows Runtime users:</b> The temporary directory must be set
414 prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
415 features that require the use of temporary files may fail.</p>
416
417 <p>See also: <a href="../c3ref/temp_directory.html">sqlite3_temp_directory</a>
418 </p><p>See also lists of
419 <a href="../c3ref/objlist.html">Objects</a>,
420 <a href="../c3ref/constlist.html">Constants</a>, and
421 <a href="../c3ref/funclist.html">Functions</a>.</p>
422