1.Dd December 19, 2018 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 will be UTF-8 for databases created using sqlite3_open() 45or sqlite3_open_v2(). 46The default encoding for databases created using sqlite3_open16() will 47be UTF-16 in the native byte order. 48.Pp 49Whether or not an error occurs when it is opened, resources associated 50with the database connection handle should be released 51by passing it to sqlite3_close() when it is no longer 52required. 53.Pp 54The sqlite3_open_v2() interface works like sqlite3_open() except that 55it accepts two additional parameters for additional control over the 56new database connection. 57The flags parameter to sqlite3_open_v2() can take one of the following 58three values, optionally combined with the SQLITE_OPEN_NOMUTEX, 59SQLITE_OPEN_FULLMUTEX, SQLITE_OPEN_SHAREDCACHE, 60SQLITE_OPEN_PRIVATECACHE, and/or SQLITE_OPEN_URI 61flags: 62.Bl -tag -width Ds 63.It SQLITE_OPEN_READONLY 64The database is opened in read-only mode. 65If the database does not already exist, an error is returned. 66.It SQLITE_OPEN_READWRITE 67The database is opened for reading and writing if possible, or reading 68only if the file is write protected by the operating system. 69In either case the database must already exist, otherwise an error 70is returned. 71.It SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE 72The database is opened for reading and writing, and is created if it 73does not already exist. 74This is the behavior that is always used for sqlite3_open() and sqlite3_open16(). 75.El 76.Pp 77If the 3rd parameter to sqlite3_open_v2() is not one of the combinations 78shown above optionally combined with other SQLITE_OPEN_* bits 79then the behavior is undefined. 80.Pp 81If the SQLITE_OPEN_NOMUTEX flag is set, then the 82database connection opens in the multi-thread threading mode 83as long as the single-thread mode has not been set at compile-time 84or start-time. 85If the SQLITE_OPEN_FULLMUTEX flag is set then 86the database connection opens in the serialized threading mode 87unless single-thread was previously selected at compile-time or start-time. 88The SQLITE_OPEN_SHAREDCACHE flag causes the 89database connection to be eligible to use shared cache mode, 90regardless of whether or not shared cache is enabled using sqlite3_enable_shared_cache(). 91The SQLITE_OPEN_PRIVATECACHE flag causes the 92database connection to not participate in shared cache mode 93even if it is enabled. 94.Pp 95The fourth parameter to sqlite3_open_v2() is the name of the sqlite3_vfs 96object that defines the operating system interface that the new database 97connection should use. 98If the fourth parameter is a NULL pointer then the default sqlite3_vfs 99object is used. 100.Pp 101If the filename is ":memory:", then a private, temporary in-memory 102database is created for the connection. 103This in-memory database will vanish when the database connection is 104closed. 105Future versions of SQLite might make use of additional special filenames 106that begin with the ":" character. 107It is recommended that when a database filename actually does begin 108with a ":" character you should prefix the filename with a pathname 109such as "./" to avoid ambiguity. 110.Pp 111If the filename is an empty string, then a private, temporary on-disk 112database will be created. 113This private database will be automatically deleted as soon as the 114database connection is closed. 115.Ss URI Filenames 116If URI filename interpretation is enabled, and the filename 117argument begins with "file:", then the filename is interpreted as a 118URI. 119URI filename interpretation is enabled if the SQLITE_OPEN_URI 120flag is set in the third argument to sqlite3_open_v2(), or if it has 121been enabled globally using the SQLITE_CONFIG_URI 122option with the sqlite3_config() method or by the SQLITE_USE_URI 123compile-time option. 124URI filename interpretation is turned off by default, but future releases 125of SQLite might enable URI filename interpretation 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 and its built-in VFSes interpret the following 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.It 187\fBpsow\fP: The psow parameter indicates whether or not the powersafe overwrite 188property does or does not apply to the storage media on which the database 189file resides. 190.It 191\fBnolock\fP: The nolock parameter is a boolean query parameter which if 192set disables file locking in rollback journal modes. 193This is useful for accessing a database on a filesystem that does not 194support locking. 195Caution: Database corruption might result if two or more processes 196write to the same database and any one of those processes uses nolock=1. 197.It 198\fBimmutable\fP: The immutable parameter is a boolean query parameter that 199indicates that the database file is stored on read-only media. 200When immutable is set, SQLite assumes that the database file cannot 201be changed, even by a process with higher privilege, and so the database 202is opened read-only and all locking and change detection is disabled. 203Caution: Setting the immutable property on a database file that does 204in fact change can result in incorrect query results and/or SQLITE_CORRUPT 205errors. 206.El 207.Pp 208Specifying an unknown parameter in the query component of a URI is 209not an error. 210Future versions of SQLite might understand additional query parameters. 211See "query parameters with special meaning to SQLite" 212for additional information. 213.Ss URI filename examples 214<table border="1" align=center cellpadding=5> <tr><th> URI filenames 215<th> Results <tr><td> file:data.db <td> Open the file "data.db" in 216the current directory. 217<tr><td> file:/home/fred/data.db<br> file:///home/fred/data.db <br> 218file://localhost/home/fred/data.db <br> <td> Open the database file 219"/home/fred/data.db". 220<tr><td> file://darkstar/home/fred/data.db <td> An error. 221"darkstar" is not a recognized authority. 222<tr><td style="white-space:nowrap"> file:///C:/Documents%20and%20Settings/fred/Desktop/data.db 223<td> Windows only: Open the file "data.db" on fred's desktop on drive 224C:. 225Note that the %20 escaping in this example is not strictly necessary 226- space characters can be used literally in URI filenames. 227<tr><td> file:data.db?mode=ro&cache=private <td> Open file "data.db" 228in the current directory for read-only access. 229Regardless of whether or not shared-cache mode is enabled by default, 230use a private cache. 231<tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td> Open file "/home/fred/data.db". 232Use the special VFS "unix-dotfile" that uses dot-files in place of 233posix advisory locking. 234<tr><td> file:data.db?mode=readonly <td> An error. 235"readonly" is not a valid option for the "mode" parameter. 236</table> 237.Pp 238URI hexadecimal escape sequences (%HH) are supported within the path 239and query components of a URI. 240A hexadecimal escape sequence consists of a percent sign - "%" - followed 241by exactly two hexadecimal digits specifying an octet value. 242Before the path or query components of a URI filename are interpreted, 243they are encoded using UTF-8 and all hexadecimal escape sequences replaced 244by a single byte containing the corresponding octet. 245If this process generates an invalid UTF-8 encoding, the results are 246undefined. 247.Pp 248\fBNote to Windows users:\fP The encoding used for the filename argument 249of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever 250codepage is currently defined. 251Filenames containing international characters must be converted to 252UTF-8 prior to passing them into sqlite3_open() or sqlite3_open_v2(). 253.Pp 254\fBNote to Windows Runtime users:\fP The temporary directory must be set 255prior to calling sqlite3_open() or sqlite3_open_v2(). 256Otherwise, various features that require the use of temporary files 257may fail. 258.Pp 259.Sh SEE ALSO 260.Xr sqlite3 3 , 261.Xr sqlite3_close 3 , 262.Xr sqlite3_config 3 , 263.Xr sqlite3_enable_shared_cache 3 , 264.Xr sqlite3_errcode 3 , 265.Xr sqlite3_temp_directory 3 , 266.Xr sqlite3_vfs 3 , 267.Xr SQLITE_CONFIG_SINGLETHREAD 3 , 268.Xr SQLITE_OK 3 , 269.Xr SQLITE_IOCAP_ATOMIC 3 , 270.Xr SQLITE_OK 3 , 271.Xr SQLITE_OPEN_READONLY 3 272