Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## SQLite C Interface

## 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 whose name is given 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.

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 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 can take one of the following three values, optionally combined with the SQLITE_OPEN_NOMUTEX flag:

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 creates it 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 or one of the combinations shown above combined with the SQLITE_OPEN_NOMUTEX flag, then the behavior is undefined.

If the SQLITE_OPEN_NOMUTEX flag is set, then mutexes on the opened database connection are disabled and the appliation must insure that access to the database connection and its associated prepared statements is serialized. The SQLITE_OPEN_NOMUTEX flag is the default behavior is SQLite is configured using the SQLITE_CONFIG_MULTITHREAD or SQLITE_CONFIG_SINGLETHREAD options to sqlite3_config(). The SQLITE_OPEN_NOMUTEX flag only makes a difference when SQLite is in its default SQLITE_CONFIG_SERIALIZED mode.

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.

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.

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

### Invariants:

H12701 | The sqlite3_open(), sqlite3_open16(), and sqlite3_open_v2() interfaces create a new database connection associated with the database file given in their first parameter.
H12702 | 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().
H12703 | A successful invocation of sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2() writes a pointer to a new database connection into *ppDb.
H12704 | The sqlite3_open(), sqlite3_open16(), and sqlite3_open_v2() interfaces return SQLITE_OK upon success, or an appropriate error code on failure.
H12706 | The default text encoding for a new database created using sqlite3_open() or sqlite3_open_v2() will be UTF-8.
H12707 | The default text encoding for a new database created using sqlite3_open16() will be UTF-16.
H12709 | The sqlite3_open(F,D) interface is equivalent to sqlite3_open_v2(F,D,G,0) where the G parameter is SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE.
H12711 | If the G parameter to sqlite3_open_v2(F,D,G,V) contains the bit value SQLITE_OPEN_READONLY then the database is opened for reading only.
H12712 | If the G parameter to sqlite3_open_v2(F,D,G,V) contains the bit value SQLITE_OPEN_READWRITE then the database is opened reading and writing if possible, or for reading only if the file is write protected by the operating system.
H12713 | If the G parameter to sqlite3_open_v2(F,D,G,V) omits the bit value SQLITE_OPEN_CREATE and the database does not previously exist, an error is returned.
H12714 | If the G parameter to sqlite3_open_v2(F,D,G,V) contains the bit value SQLITE_OPEN_CREATE and the database does not previously exist, then an attempt is made to create and initialize the database.
H12717 | If the filename argument to sqlite3_open(), sqlite3_open16(), or sqlite3_open_v2() is ":memory:", then an private, ephemeral, in-memory database is created for the connection. (TODO: Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required in sqlite3_open_v2()?)
H12719 | If the filename is NULL or an empty string, then a private, ephemeral on-disk database will be created. (TODO: Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required in sqlite3_open_v2()?)
H12721 | The database connection created by sqlite3_open_v2(F,D,G,V) will use the sqlite3_vfs object identified by the V parameter, or the default sqlite3_vfs object if V is a NULL pointer.
H12723 | Two database connections will share a common cache if both were opened with the same VFS while shared cache mode was enabled and if both filenames compare equal using memcmp() after having been processed by the xFullPathname method of the VFS.

See also lists of Objects, Constants, and Functions.

This page last modified 2008/08/11 17:57:43 UTC