372 lines
17 KiB
HTML
372 lines
17 KiB
HTML
<!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;
|
|
}
|
|
</script>
|
|
</div>
|
|
<!-- keywords: sqlite3_open sqlite3_open16 sqlite3_open_v2 -->
|
|
<div class=nosearch>
|
|
<a href="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.</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>.</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="opennofollow"></a>
|
|
<dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOFOLLOW</a></dt>
|
|
<dd>The database filename is not allowed to be 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.</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.
|
|
</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="objlist.html">Objects</a>,
|
|
<a href="constlist.html">Constants</a>, and
|
|
<a href="funclist.html">Functions</a>.</p>
|