xref: /netbsd-src/external/public-domain/sqlite/man/sqlite3_open.3 (revision 82d56013d7b633d116a93943de88e08335357a7c)
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