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 */ );
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 database connection 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 sqlite3 object, a NULL will be written into *ppDb instead of a pointer to the sqlite3 object. If the database is opened (and/or created) successfully, then SQLITE_OK is returned. Otherwise an error code is returned. The sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain an English language description of the error following a failure of any of the sqlite3_open() routines.
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.
Whether or not an error occurs when it is opened, resources associated with the database connection handle should be released by passing it to sqlite3_close() when it is no longer required.
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:
In addition to the required flags, the following optional flags are also supported:
If the 3rd parameter to sqlite3_open_v2() is not one of the required combinations shown above optionally combined with other SQLITE_OPEN_* bits 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 VFS interface only, and not by sqlite3_open_v2().
The fourth parameter to sqlite3_open_v2() is the name of the sqlite3_vfs 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 sqlite3_vfs object is used.
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.
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.
If URI filename 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 SQLITE_OPEN_URI flag is set in the third argument to sqlite3_open_v2(), or if it has been enabled globally using the SQLITE_CONFIG_URI option with the sqlite3_config() method or by the SQLITE_USE_URI compile-time option. URI filename interpretation is turned off by default, but future releases of SQLite might enable URI filename interpretation by default. See "URI filenames" for additional information.
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.
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:").
The query component of a URI may contain parameters that are interpreted either by SQLite itself, or by a custom VFS implementation. SQLite and its built-in VFSes interpret the following query parameters:
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 "query parameters with special meaning to SQLite" for additional information.
URI filenames | Results |
---|---|
file:data.db | Open the file "data.db" in the current directory. |
file:/home/fred/data.db file:///home/fred/data.db file://localhost/home/fred/data.db | Open the database file "/home/fred/data.db". |
file://darkstar/home/fred/data.db | An error. "darkstar" is not a recognized authority. |
file:///C:/Documents and Settings/fred/Desktop/data.db | Windows only: Open the file "data.db" on fred's desktop on drive C:. Note that the escaping in this example is not strictly necessary - space characters can be used literally in URI filenames. |
file:data.db?mode=ro&cache=private | 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. |
file:/home/fred/data.db?vfs=unix-dotfile | Open file "/home/fred/data.db". Use the special VFS "unix-dotfile" that uses dot-files in place of posix advisory locking. |
file:data.db?mode=readonly | An error. "readonly" is not a valid option for the "mode" parameter. Use "ro" instead: "file:data.db?mode=ro". |
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.
Note to Windows users: 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().
Note to Windows Runtime users: 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.
See also: sqlite3_temp_directory