opening A New Database Connection

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(). Adatabase connectionhandle is usually returned in *ppDb,even if an error occurs. The only exception is that if sqlite is unable to allocate memory to hold thesqlite3object,a NULL will be written into *ppDb instead of a pointer to thesqlite3object. If the database is opened (and/or created) successfully,thenSQLITE_OKis returned. Otherwise anerror codeis returned. Thesqlite3_errmsg()orsqlite3_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 for the database will be UTF-8 if sqlite3_open() or sqlite3_open_v2() is called and UTF-16 in the native byte order if sqlite3_open16() is used.

Whether or not an error occurs when it is opened,resources associated with thedatabase connectionhandle should be released by passing it tosqlite3_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() can take one of the following three values,optionally combined with theSQLITE_OPEN_NOMUTEX,SQLITE_OPEN_FULLMUTEX,100)" rel="nofollow" target="_blank">sqlITE_OPEN_SHAREDCACHE,100)" rel="nofollow" target="_blank">sqlITE_OPEN_PRIVATECACHE,and/orSQLITE_OPEN_URIflags:

SQLITE_OPEN_READONLY

The database is opened in read-only mode. If the database does not already exist,an error is returned.

SQLITE_OPEN_READWRITE

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.

SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE

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().

If the 3rd parameter to sqlite3_open_v2() is not one of the combinations shown above optionally combined with otherSQLITE_OPEN_* bitsthen the behavior is undefined.

If theSQLITE_OPEN_NOMUTEXflag is set,then the database connection opens in the multi-threadthreading modeas long as the single-thread mode has not been set at compile-time or start-time. If theSQLITE_OPEN_FULLMUTEXflag is set then the database connection opens in the serializedthreading modeunless single-thread was prevIoUsly selected at compile-time or start-time. TheSQLITE_OPEN_SHAREDCACHEflag causes the database connection to be eligible to useshared cache mode,regardless of whether or not shared cache is enabled usingsqlite3_enable_shared_cache(). TheSQLITE_OPEN_PRIVATECACHEflag causes the database connection to not participate inshared cache modeeven if it is enabled.

The fourth parameter to sqlite3_open_v2() is the name of thesqlite3_vfsobject that defines the operating system interface that the new database connection should use. If the fourth parameter is a NULL pointer then the defaultsqlite3_vfsobject 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,temporary on-disk database will be created. This private database will be automatically deleted as soon as the database connection is closed.

URI Filenames

IfURI filenameinterpretation is enabled,and the filename argument begins with "file:",then the filename is interpreted as a URI. URI filename interpretation is enabled if theSQLITE_OPEN_URIflag is set in the fourth argument to sqlite3_open_v2(),or if it has been enabled globally using theSQLITE_CONFIG_URIoption with thesqlite3_config()method or by theSQLITE_USE_URIcompile-time option. As of sqlite version 3.7.7,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 acustom VFS implementation. sqlite interprets the following three query parameters:

• vfs: 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().
• mode: 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 theSQLITE_OPEN_READONLYflag had been set in the third argument to sqlite3_prepare_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 purein-memory databasethat 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().
• cache: 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 behavIoUr requested by setting sqlITE_OPEN_PRIVATECACHE or sqlITE_OPEN_SHAREDCACHE flag.

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 filename examples

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().