1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
|
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="../sqlite.css" rel="stylesheet">
<title>Opening A New Database Connection</title>
<!-- path=../ -->
</head>
<body>
<div class=nosearch>
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="../index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='../about.html'>About</a>
<li class='desktoponly'><a href="../docs.html">Documentation</a>
<li class='desktoponly'><a href="../download.html">Download</a>
<li class='wideonly'><a href='../copyright.html'>License</a>
<li class='desktoponly'><a href="../support.html">Support</a>
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='../about.html'>About</a>
<li><a href='../docs.html'>Documentation</a>
<li><a href='../download.html'>Download</a>
<li><a href='../support.html'>Support</a>
<li><a href='../prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="../search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<!-- keywords: sqlite3_open sqlite3_open16 sqlite3_open_v2 -->
<div class=nosearch>
<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
<h2>Opening A New Database Connection</h2>
</div>
<blockquote><pre>
int sqlite3_open(
const char *filename, /* Database filename (UTF-8) */
sqlite3 **ppDb /* OUT: SQLite db handle */
);
int sqlite3_open16(
const void *filename, /* Database filename (UTF-16) */
sqlite3 **ppDb /* OUT: SQLite db handle */
);
int sqlite3_open_v2(
const char *filename, /* Database filename (UTF-8) */
sqlite3 **ppDb, /* OUT: SQLite db handle */
int flags, /* Flags */
const char *zVfs /* Name of VFS module to use */
);
</pre></blockquote>
<p>
These routines open an SQLite database file as specified by the
filename argument. The filename argument is interpreted as UTF-8 for
sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
order for sqlite3_open16(). A <a href="../c3ref/sqlite3.html">database connection</a> handle is usually
returned in *ppDb, even if an error occurs. The only exception is that
if SQLite is unable to allocate memory to hold the <a href="../c3ref/sqlite3.html">sqlite3</a> object,
a NULL will be written into *ppDb instead of a pointer to the <a href="../c3ref/sqlite3.html">sqlite3</a>
object. If the database is opened (and/or created) successfully, then
<a href="../rescode.html#ok">SQLITE_OK</a> is returned. Otherwise an <a href="../rescode.html">error code</a> is returned. The
<a href="../c3ref/errcode.html">sqlite3_errmsg()</a> or <a href="../c3ref/errcode.html">sqlite3_errmsg16()</a> routines can be used to obtain
an English language description of the error following a failure of any
of the sqlite3_open() routines.</p>
<p>The default encoding will be UTF-8 for databases created using
sqlite3_open() or sqlite3_open_v2(). The default encoding for databases
created using sqlite3_open16() will be UTF-16 in the native byte order.</p>
<p>Whether or not an error occurs when it is opened, resources
associated with the <a href="../c3ref/sqlite3.html">database connection</a> handle should be released by
passing it to <a href="../c3ref/close.html">sqlite3_close()</a> when it is no longer required.</p>
<p>The sqlite3_open_v2() interface works like sqlite3_open()
except that it accepts two additional parameters for additional control
over the new database connection. The flags parameter to
sqlite3_open_v2() must include, at a minimum, one of the following
three flag combinations:</p>
<p><dl>
<dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a></dt>
<dd>The database is opened in read-only mode. If the database does
not already exist, an error is returned.</dd></p>
<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a></dt>
<dd>The database is opened for reading and writing if possible, or
reading only if the file is write protected by the operating
system. In either case the database must already exist, otherwise
an error is returned. For historical reasons, if opening in
read-write mode fails due to OS-level permissions, an attempt is
made to open it in read-only mode. <a href="../c3ref/db_readonly.html">sqlite3_db_readonly()</a> can be
used to determine whether the database is actually
read-write.</dd></p>
<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>
<dd>The database is opened for reading and writing, and is created if
it does not already exist. This is the behavior that is always used for
sqlite3_open() and sqlite3_open16().</dd>
</dl></p>
<p>In addition to the required flags, the following optional flags are
also supported:</p>
<p><dl>
<dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a></dt>
<dd>The filename can be interpreted as a URI if this flag is set.</dd></p>
<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_MEMORY</a></dt>
<dd>The database will be opened as an in-memory database. The database
is named by the "filename" argument for the purposes of cache-sharing,
if shared cache mode is enabled, but the "filename" is otherwise ignored.
</dd></p>
<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOMUTEX</a></dt>
<dd>The new database connection will use the "multi-thread"
<a href="../threadsafe.html">threading mode</a>. This means that separate threads are allowed
to use SQLite at the same time, as long as each thread is using
a different <a href="../c3ref/sqlite3.html">database connection</a>.</p>
<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_FULLMUTEX</a></dt>
<dd>The new database connection will use the "serialized"
<a href="../threadsafe.html">threading mode</a>. This means the multiple threads can safely
attempt to use the same database connection at the same time.
(Mutexes will block any actual concurrency, but in this mode
there is no harm in trying.)</p>
<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_SHAREDCACHE</a></dt>
<dd>The database is opened <a href="../sharedcache.html">shared cache</a> enabled, overriding
the default shared cache setting provided by
<a href="../c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a>.
The <a href="../sharedcache.html#dontuse">use of shared cache mode is discouraged</a> and hence shared cache
capabilities may be omitted from many builds of SQLite. In such cases,
this option is a no-op.</p>
<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_PRIVATECACHE</a></dt>
<dd>The database is opened <a href="../sharedcache.html">shared cache</a> disabled, overriding
the default shared cache setting provided by
<a href="../c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a>.</p>
<p><a name="openexrescode"></a>
<dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXRESCODE</a></dt>
<dd>The database connection comes up in "extended result code mode".
In other words, the database behaves has if
<a href="../c3ref/extended_result_codes.html">sqlite3_extended_result_codes(db,1)</a> where called on the database
connection as soon as the connection is created. In addition to setting
the extended result code mode, this flag also causes <a href="../c3ref/open.html">sqlite3_open_v2()</a>
to return an extended result code.</dd></p>
<p><a name="opennofollow"></a>
<dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOFOLLOW</a></dt>
<dd>The database filename is not allowed to contain a symbolic link</dd>
</dl></p>
<p>If the 3rd parameter to sqlite3_open_v2() is not one of the
required combinations shown above optionally combined with other
<a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_* bits</a>
then the behavior is undefined. Historic versions of SQLite
have silently ignored surplus bits in the flags parameter to
sqlite3_open_v2(), however that behavior might not be carried through
into future versions of SQLite and so applications should not rely
upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
for sqlite3_open_v2(). The SQLITE_OPEN_EXCLUSIVE does *not* cause
the open to fail if the database already exists. The SQLITE_OPEN_EXCLUSIVE
flag is intended for use by the <a href="../c3ref/vfs.html">VFS interface</a> only, and not
by sqlite3_open_v2().</p>
<p>The fourth parameter to sqlite3_open_v2() is the name of the
<a href="../c3ref/vfs.html">sqlite3_vfs</a> object that defines the operating system interface that
the new database connection should use. If the fourth parameter is
a NULL pointer then the default <a href="../c3ref/vfs.html">sqlite3_vfs</a> object is used.</p>
<p>If the filename is ":memory:", then a private, temporary in-memory database
is created for the connection. This in-memory database will vanish when
the database connection is closed. Future versions of SQLite might
make use of additional special filenames that begin with the ":" character.
It is recommended that when a database filename actually does begin with
a ":" character you should prefix the filename with a pathname such as
"./" to avoid ambiguity.</p>
<p>If the filename is an empty string, then a private, temporary
on-disk database will be created. This private database will be
automatically deleted as soon as the database connection is closed.</p>
<p><a name="urifilenamesinsqlite3open"></a>
<h3>URI Filenames</h3></p>
<p>If <a href="../uri.html">URI filename</a> interpretation is enabled, and the filename argument
begins with "file:", then the filename is interpreted as a URI. URI
filename interpretation is enabled if the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a> flag is
set in the third argument to sqlite3_open_v2(), or if it has
been enabled globally using the <a href="../c3ref/c_config_covering_index_scan.html#sqliteconfiguri">SQLITE_CONFIG_URI</a> option with the
<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.
URI filename interpretation is turned off
by default, but future releases of SQLite might enable URI filename
interpretation by default. See "<a href="../uri.html">URI filenames</a>" for additional
information.</p>
<p>URI filenames are parsed according to RFC 3986. If the URI contains an
authority, then it must be either an empty string or the string
"localhost". If the authority is not an empty string or "localhost", an
error is returned to the caller. The fragment component of a URI, if
present, is ignored.</p>
<p>SQLite uses the path component of the URI as the name of the disk file
which contains the database. If the path begins with a '/' character,
then it is interpreted as an absolute path. If the path does not begin
with a '/' (meaning that the authority section is omitted from the URI)
then the path is interpreted as a relative path.
On windows, the first component of an absolute path
is a drive specification (e.g. "C:").</p>
<p><a name="coreuriqueryparameters"></a>
The query component of a URI may contain parameters that are interpreted
either by SQLite itself, or by a <a href="../vfs.html">custom VFS implementation</a>.
SQLite and its built-in <a href="../vfs.html">VFSes</a> interpret the
following query parameters:</p>
<p><ul>
<li> <b>vfs</b>: The "vfs" parameter may be used to specify the name of
a VFS object that provides the operating system interface that should
be used to access the database file on disk. If this option is set to
an empty string the default VFS object is used. Specifying an unknown
VFS is an error. If sqlite3_open_v2() is used and the vfs option is
present, then the VFS specified by the option takes precedence over
the value passed as the fourth parameter to sqlite3_open_v2().</p>
<p><li> <b>mode</b>: The mode parameter may be set to either "ro", "rw",
"rwc", or "memory". Attempting to set it to any other value is
an error.
If "ro" is specified, then the database is opened for read-only
access, just as if the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a> flag had been set in the
third argument to sqlite3_open_v2(). If the mode option is set to
"rw", then the database is opened for read-write (but not create)
access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
been set. Value "rwc" is equivalent to setting both
SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. If the mode option is
set to "memory" then a pure <a href="../inmemorydb.html">in-memory database</a> that never reads
or writes from disk is used. It is an error to specify a value for
the mode parameter that is less restrictive than that specified by
the flags passed in the third parameter to sqlite3_open_v2().</p>
<p><li> <b>cache</b>: The cache parameter may be set to either "shared" or
"private". Setting it to "shared" is equivalent to setting the
SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
sqlite3_open_v2(). Setting the cache parameter to "private" is
equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
If sqlite3_open_v2() is used and the "cache" parameter is present in
a URI filename, its value overrides any behavior requested by setting
SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.</p>
<p><li> <b>psow</b>: The psow parameter indicates whether or not the
<a href="../psow.html">powersafe overwrite</a> property does or does not apply to the
storage media on which the database file resides.</p>
<p><li> <b>nolock</b>: The nolock parameter is a boolean query parameter
which if set disables file locking in rollback journal modes. This
is useful for accessing a database on a filesystem that does not
support locking. Caution: Database corruption might result if two
or more processes write to the same database and any one of those
processes uses nolock=1.</p>
<p><li> <b>immutable</b>: The immutable parameter is a boolean query
parameter that indicates that the database file is stored on
read-only media. When immutable is set, SQLite assumes that the
database file cannot be changed, even by a process with higher
privilege, and so the database is opened read-only and all locking
and change detection is disabled. Caution: Setting the immutable
property on a database file that does in fact change can result
in incorrect query results and/or <a href="../rescode.html#corrupt">SQLITE_CORRUPT</a> errors.
See also: <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_IMMUTABLE</a>.</p>
<p></ul></p>
<p>Specifying an unknown parameter in the query component of a URI is not an
error. Future versions of SQLite might understand additional query
parameters. See "<a href="../uri.html#coreqp">query parameters with special meaning to SQLite</a>" for
additional information.</p>
<p><a name="urifilenameexamples"></a>
<h3>URI filename examples</h3></p>
<p><table border="1" align=center cellpadding=5>
<tr><th> URI filenames <th> Results
<tr><td> file:data.db <td>
Open the file "data.db" in the current directory.
<tr><td> file:/home/fred/data.db<br>
file:///home/fred/data.db <br>
file://localhost/home/fred/data.db <br> <td>
Open the database file "/home/fred/data.db".
<tr><td> file://darkstar/home/fred/data.db <td>
An error. "darkstar" is not a recognized authority.
<tr><td style="white-space:nowrap">
file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
<td> Windows only: Open the file "data.db" on fred's desktop on drive
C:. Note that the %20 escaping in this example is not strictly
necessary - space characters can be used literally
in URI filenames.
<tr><td> file:data.db?mode=ro&cache=private <td>
Open file "data.db" in the current directory for read-only access.
Regardless of whether or not shared-cache mode is enabled by
default, use a private cache.
<tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
that uses dot-files in place of posix advisory locking.
<tr><td> file:data.db?mode=readonly <td>
An error. "readonly" is not a valid option for the "mode" parameter.
Use "ro" instead: "file:data.db?mode=ro".
</table></p>
<p>URI hexadecimal escape sequences (%HH) are supported within the path and
query components of a URI. A hexadecimal escape sequence consists of a
percent sign - "%" - followed by exactly two hexadecimal digits
specifying an octet value. Before the path or query components of a
URI filename are interpreted, they are encoded using UTF-8 and all
hexadecimal escape sequences replaced by a single byte containing the
corresponding octet. If this process generates an invalid UTF-8 encoding,
the results are undefined.</p>
<p><b>Note to Windows users:</b> The encoding used for the filename argument
of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
codepage is currently defined. Filenames containing international
characters must be converted to UTF-8 prior to passing them into
sqlite3_open() or sqlite3_open_v2().</p>
<p><b>Note to Windows Runtime users:</b> The temporary directory must be set
prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
features that require the use of temporary files may fail.</p>
<p>See also: <a href="../c3ref/temp_directory.html">sqlite3_temp_directory</a>
</p><p>See also lists of
<a href="../c3ref/objlist.html">Objects</a>,
<a href="../c3ref/constlist.html">Constants</a>, and
<a href="../c3ref/funclist.html">Functions</a>.</p>
|
