1.Dd $Mdocdate$ 2.Dt SQLITE3_OPEN 3 3.Os 4.Sh NAME 5.Nm sqlite3_open , 6.Nm sqlite3_open16 , 7.Nm sqlite3_open_v2 8.Nd Opening A New Database Connection 9.Sh SYNOPSIS 10.Ft int 11.Fo sqlite3_open 12.Fa "const char *filename" 13.Fa "sqlite3 **ppDb " 14.Fc 15.Ft int 16.Fo sqlite3_open16 17.Fa "const void *filename" 18.Fa "sqlite3 **ppDb " 19.Fc 20.Ft int 21.Fo sqlite3_open_v2 22.Fa "const char *filename" 23.Fa "sqlite3 **ppDb" 24.Fa "int flags" 25.Fa "const char *zVfs " 26.Fc 27.Sh DESCRIPTION 28These routines open an SQLite database file as specified by the filename 29argument. 30The filename argument is interpreted as UTF-8 for sqlite3_open() and 31sqlite3_open_v2() and as UTF-16 in the native byte order for sqlite3_open16(). 32A database connection handle is usually returned 33in *ppDb, even if an error occurs. 34The only exception is that if SQLite is unable to allocate memory to 35hold the sqlite3 object, a NULL will be written into *ppDb instead 36of a pointer to the sqlite3 object. 37If the database is opened (and/or created) successfully, then SQLITE_OK 38is returned. 39Otherwise an error code is returned. 40The sqlite3_errmsg() or sqlite3_errmsg16() 41routines can be used to obtain an English language description of the 42error following a failure of any of the sqlite3_open() routines. 43.Pp 44The default encoding for the database will be UTF-8 if sqlite3_open() 45or sqlite3_open_v2() is called and UTF-16 in the native byte order 46if sqlite3_open16() is used. 47.Pp 48Whether or not an error occurs when it is opened, resources associated 49with the database connection handle should be released 50by passing it to sqlite3_close() when it is no longer 51required. 52.Pp 53The sqlite3_open_v2() interface works like sqlite3_open() except that 54it accepts two additional parameters for additional control over the 55new database connection. 56The flags parameter to sqlite3_open_v2() can take one of the following 57three values, optionally combined with the SQLITE_OPEN_NOMUTEX, 58SQLITE_OPEN_FULLMUTEX, SQLITE_OPEN_SHAREDCACHE, 59SQLITE_OPEN_PRIVATECACHE, and/or SQLITE_OPEN_URI 60flags: 61.Bl -tag -width Ds 62.It SQLITE_OPEN_READONLY 63The database is opened in read-only mode. 64If the database does not already exist, an error is returned. 65.It SQLITE_OPEN_READWRITE 66The database is opened for reading and writing if possible, or reading 67only if the file is write protected by the operating system. 68In either case the database must already exist, otherwise an error 69is returned. 70.It SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE 71The database is opened for reading and writing, and is created if it 72does not already exist. 73This is the behavior that is always used for sqlite3_open() and sqlite3_open16(). 74.El 75.Pp 76If the 3rd parameter to sqlite3_open_v2() is not one of the combinations 77shown above optionally combined with other SQLITE_OPEN_* bits 78then the behavior is undefined. 79.Pp 80If the SQLITE_OPEN_NOMUTEX flag is set, then the 81database connection opens in the multi-thread threading mode 82as long as the single-thread mode has not been set at compile-time 83or start-time. 84If the SQLITE_OPEN_FULLMUTEX flag is set then 85the database connection opens in the serialized threading mode 86unless single-thread was previously selected at compile-time or start-time. 87The SQLITE_OPEN_SHAREDCACHE flag causes the 88database connection to be eligible to use shared cache mode, 89regardless of whether or not shared cache is enabled using sqlite3_enable_shared_cache(). 90The SQLITE_OPEN_PRIVATECACHE flag causes the 91database connection to not participate in shared cache mode 92even if it is enabled. 93.Pp 94The fourth parameter to sqlite3_open_v2() is the name of the sqlite3_vfs 95object that defines the operating system interface that the new database 96connection should use. 97If the fourth parameter is a NULL pointer then the default sqlite3_vfs 98object is used. 99.Pp 100If the filename is ":memory:", then a private, temporary in-memory 101database is created for the connection. 102This in-memory database will vanish when the database connection is 103closed. 104Future versions of SQLite might make use of additional special filenames 105that begin with the ":" character. 106It is recommended that when a database filename actually does begin 107with a ":" character you should prefix the filename with a pathname 108such as "./" to avoid ambiguity. 109.Pp 110If the filename is an empty string, then a private, temporary on-disk 111database will be created. 112This private database will be automatically deleted as soon as the 113database connection is closed. 114.Ss URI Filenames 115If URI filename interpretation is enabled, and the filename 116argument begins with "file:", then the filename is interpreted as a 117URI. 118URI filename interpretation is enabled if the SQLITE_OPEN_URI 119flag is set in the fourth argument to sqlite3_open_v2(), or if it has 120been enabled globally using the SQLITE_CONFIG_URI 121option with the sqlite3_config() method or by the SQLITE_USE_URI 122compile-time option. 123As of SQLite version 3.7.7, URI filename interpretation is turned off 124by default, but future releases of SQLite might enable URI filename 125interpretation by default. 126See "URI filenames" for additional information. 127.Pp 128URI filenames are parsed according to RFC 3986. 129If the URI contains an authority, then it must be either an empty string 130or the string "localhost". 131If the authority is not an empty string or "localhost", an error is 132returned to the caller. 133The fragment component of a URI, if present, is ignored. 134.Pp 135SQLite uses the path component of the URI as the name of the disk file 136which contains the database. 137If the path begins with a '/' character, then it is interpreted as 138an absolute path. 139If the path does not begin with a '/' (meaning that the authority section 140is omitted from the URI) then the path is interpreted as a relative 141path. 142On windows, the first component of an absolute path is a drive specification 143(e.g. 144"C:"). 145.Pp 146The query component of a URI may contain parameters that are interpreted 147either by SQLite itself, or by a custom VFS implementation. 148SQLite interprets the following three query parameters: 149.Bl -bullet 150.It 151\fBvfs\fP: The "vfs" parameter may be used to specify the name of a VFS 152object that provides the operating system interface that should be 153used to access the database file on disk. 154If this option is set to an empty string the default VFS object is 155used. 156Specifying an unknown VFS is an error. 157If sqlite3_open_v2() is used and the vfs option is present, then the 158VFS specified by the option takes precedence over the value passed 159as the fourth parameter to sqlite3_open_v2(). 160.It 161\fBmode\fP: The mode parameter may be set to either "ro", "rw", "rwc", 162or "memory". 163Attempting to set it to any other value is an error . 164If "ro" is specified, then the database is opened for read-only access, 165just as if the SQLITE_OPEN_READONLY flag had been 166set in the third argument to sqlite3_open_v2(). 167If the mode option is set to "rw", then the database is opened for 168read-write (but not create) access, as if SQLITE_OPEN_READWRITE (but 169not SQLITE_OPEN_CREATE) had been set. 170Value "rwc" is equivalent to setting both SQLITE_OPEN_READWRITE and 171SQLITE_OPEN_CREATE. 172If the mode option is set to "memory" then a pure in-memory database 173that never reads or writes from disk is used. 174It is an error to specify a value for the mode parameter that is less 175restrictive than that specified by the flags passed in the third parameter 176to sqlite3_open_v2(). 177.It 178\fBcache\fP: The cache parameter may be set to either "shared" or "private". 179Setting it to "shared" is equivalent to setting the SQLITE_OPEN_SHAREDCACHE 180bit in the flags argument passed to sqlite3_open_v2(). 181Setting the cache parameter to "private" is equivalent to setting the 182SQLITE_OPEN_PRIVATECACHE bit. 183If sqlite3_open_v2() is used and the "cache" parameter is present in 184a URI filename, its value overrides any behavior requested by setting 185SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag. 186.El 187.Pp 188Specifying an unknown parameter in the query component of a URI is 189not an error. 190Future versions of SQLite might understand additional query parameters. 191See "query parameters with special meaning to SQLite" 192for additional information. 193.Ss URI filename examples 194<table border="1" align=center cellpadding=5> <tr><th> URI filenames 195<th> Results <tr><td> file:data.db <td> Open the file "data.db" in 196the current directory. 197<tr><td> file:/home/fred/data.db<br> file:///home/fred/data.db <br> 198file://localhost/home/fred/data.db <br> <td> Open the database file 199"/home/fred/data.db". 200<tr><td> file://darkstar/home/fred/data.db <td> An error. 201"darkstar" is not a recognized authority. 202<tr><td style="white-space:nowrap"> file:///C:/Documents%20and%20Settings/fred/Desktop/data.db 203<td> Windows only: Open the file "data.db" on fred's desktop on drive 204C:. 205Note that the %20 escaping in this example is not strictly necessary 206- space characters can be used literally in URI filenames. 207<tr><td> file:data.db?mode=ro&cache=private <td> Open file "data.db" 208in the current directory for read-only access. 209Regardless of whether or not shared-cache mode is enabled by default, 210use a private cache. 211<tr><td> file:/home/fred/data.db?vfs=unix-nolock <td> Open file "/home/fred/data.db". 212Use the special VFS "unix-nolock". 213<tr><td> file:data.db?mode=readonly <td> An error. 214"readonly" is not a valid option for the "mode" parameter. 215</table> 216.Pp 217URI hexadecimal escape sequences (%HH) are supported within the path 218and query components of a URI. 219A hexadecimal escape sequence consists of a percent sign - "%" - followed 220by exactly two hexadecimal digits specifying an octet value. 221Before the path or query components of a URI filename are interpreted, 222they are encoded using UTF-8 and all hexadecimal escape sequences replaced 223by a single byte containing the corresponding octet. 224If this process generates an invalid UTF-8 encoding, the results are 225undefined. 226.Pp 227\fBNote to Windows users:\fP The encoding used for the filename argument 228of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever 229codepage is currently defined. 230Filenames containing international characters must be converted to 231UTF-8 prior to passing them into sqlite3_open() or sqlite3_open_v2(). 232.Pp 233\fBNote to Windows Runtime users:\fP The temporary directory must be set 234prior to calling sqlite3_open() or sqlite3_open_v2(). 235Otherwise, various features that require the use of temporary files 236may fail. 237.Pp 238.Sh SEE ALSO 239.Xr sqlite3 3 , 240.Xr SQLITE_OK 3 , 241.Xr sqlite3 3 , 242.Xr sqlite3_close 3 , 243.Xr sqlite3_config 3 , 244.Xr sqlite3_enable_shared_cache 3 , 245.Xr sqlite3_errcode 3 , 246.Xr sqlite3_temp_directory 3 , 247.Xr sqlite3_vfs 3 , 248.Xr SQLITE_CONFIG_SINGLETHREAD 3 , 249.Xr SQLITE_OK 3 , 250.Xr SQLITE_OPEN_READONLY 3 251