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(). An sqlite3* handle is usually returned in *ppDb, even if an error occurs. The only exception is 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 sqlite3* 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 acccepts two additional parameters for additional control over the new database connection. The flags parameter can be one of:

1. SQLITE_OPEN_READONLY
2. SQLITE_OPEN_READWRITE
3. SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE

The first value opens the database read-only. If the database does not previously exist, an error is returned. The second option opens the database for reading and writing if possible, or reading only if if the file is write protected. In either case the database must already exist or an error is returned. The third option opens the database for reading and writing and creates it if it does not already exist. The third options is behavior that is always used for sqlite3_open() and sqlite3_open16().

If the filename is ":memory:", then an private in-memory database is created for the connection. This in-memory database will vanish when the database connection is closed. Future version of SQLite might make use of additional special filenames that begin with the ":" character. It is recommended that when a database filename really does begin with ":" that you prefix the filename with a pathname like "./" 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:

See also lists of Objects, Constants, and Functions.