sqlite/man/sqlite3_open.3

.Dd January 24, 2024
.Dt SQLITE3_OPEN 3
.Os
.Sh NAME
.Nm sqlite3_open ,
.Nm sqlite3_open16 ,
.Nm sqlite3_open_v2
.Nd opening a new database connection
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_open
.Fa "const char *filename"
.Fa "sqlite3 **ppDb"
.Fc
.Ft int
.Fo sqlite3_open16
.Fa "const void *filename"
.Fa "sqlite3 **ppDb"
.Fc
.Ft int
.Fo sqlite3_open_v2
.Fa "const char *filename"
.Fa "sqlite3 **ppDb"
.Fa "int flags"
.Fa "const char *zVfs"
.Fc
.Sh DESCRIPTION
These routines open an SQLite database file as specified 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
.Fn sqlite3_errmsg
or
.Fn sqlite3_errmsg16
routines can be used to obtain an English language description of the
error following a failure of any of the sqlite3_open() routines.
.Pp
The default encoding will be UTF-8 for databases created using sqlite3_open()
or sqlite3_open_v2().
The default encoding for databases created using sqlite3_open16() will
be UTF-16 in the native byte order.
.Pp
Whether or not an error occurs when it is opened, resources associated
with the database connection handle should be released
by passing it to
.Fn sqlite3_close
when it is no longer required.
.Pp
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 to sqlite3_open_v2() must include, at a minimum,
one of the following three flag combinations:
.Bl -tag -width Ds
.It SQLITE_OPEN_READONLY
The database is opened in read-only mode.
If the database does not already exist, an error is returned.
.It 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.
For historical reasons, if opening in read-write mode fails due to
OS-level permissions, an attempt is made to open it in read-only mode.
.Fn sqlite3_db_readonly
can be used to determine whether the database is actually read-write.
.It SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
The database is opened for reading and writing, and is created if it
does not already exist.
This is the behavior that is always used for sqlite3_open() and sqlite3_open16().
.El
.Pp
In addition to the required flags, the following optional flags are
also supported:
.Bl -tag -width Ds
.It SQLITE_OPEN_URI
The filename can be interpreted as a URI if this flag is set.
.It SQLITE_OPEN_MEMORY
The database will be opened as an in-memory database.
The database is named by the "filename" argument for the purposes of
cache-sharing, if shared cache mode is enabled, but the "filename"
is otherwise ignored.
.It SQLITE_OPEN_NOMUTEX
The new database connection will use the "multi-thread" threading mode.
This means that separate threads are allowed to use SQLite at the same
time, as long as each thread is using a different database connection.
.It SQLITE_OPEN_FULLMUTEX
The new database connection will use the "serialized" threading mode.
This means the multiple threads can safely attempt to use the same
database connection at the same time.
(Mutexes will block any actual concurrency, but in this mode there
is no harm in trying.)
.It SQLITE_OPEN_SHAREDCACHE
The database is opened shared cache enabled, overriding
the default shared cache setting provided by
.Fn sqlite3_enable_shared_cache .
The use of shared cache mode is discouraged
and hence shared cache capabilities may be omitted from many builds
of SQLite.
In such cases, this option is a no-op.
.It SQLITE_OPEN_PRIVATECACHE
The database is opened shared cache disabled, overriding
the default shared cache setting provided by
.Fn sqlite3_enable_shared_cache .
.It SQLITE_OPEN_EXRESCODE
The database connection comes up in "extended result code mode".
In other words, the database behaves has if sqlite3_extended_result_codes(db,1)
where called on the database connection as soon as the connection is
created.
In addition to setting the extended result code mode, this flag also
causes
.Fn sqlite3_open_v2
to return an extended result code.
.It SQLITE_OPEN_NOFOLLOW
The database filename is not allowed to contain a symbolic link
.El
.Pp
If the 3rd parameter to sqlite3_open_v2() is not one of the required
combinations shown above optionally combined with other SQLITE_OPEN_* bits
then the behavior is undefined.
Historic versions of SQLite have silently ignored surplus bits in the
flags parameter to sqlite3_open_v2(), however that behavior might not
be carried through into future versions of SQLite and so applications
should not rely upon it.
Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op for
sqlite3_open_v2().
The SQLITE_OPEN_EXCLUSIVE does *not* cause the open to fail if the
database already exists.
The SQLITE_OPEN_EXCLUSIVE flag is intended for use by the VFS interface
only, and not by sqlite3_open_v2().
.Pp
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.
.Pp
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.
.Pp
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.
.Ss URI Filenames
If URI filename interpretation is enabled, and the filename
argument begins with "file:", then the filename is interpreted as a
URI.
URI filename interpretation is enabled if the SQLITE_OPEN_URI
flag is set in the third argument to sqlite3_open_v2(), or if it has
been enabled globally using the SQLITE_CONFIG_URI
option with the
.Fn sqlite3_config
method or by the SQLITE_USE_URI compile-time option.
URI filename interpretation is turned off by default, but future releases
of SQLite might enable URI filename interpretation by default.
See "URI filenames" for additional information.
.Pp
URI filenames are parsed according to RFC 3986.
If the URI contains an authority, then it must be either an empty string
or the string "localhost".
If the authority is not an empty string or "localhost", an error is
returned to the caller.
The fragment component of a URI, if present, is ignored.
.Pp
SQLite uses the path component of the URI as the name of the disk file
which contains the database.
If the path begins with a '/' character, then it is interpreted as
an absolute path.
If the path does not begin with a '/' (meaning that the authority section
is omitted from the URI) then the path is interpreted as a relative
path.
On windows, the first component of an absolute path is a drive specification
(e.g. "C:").
.Pp
The query component of a URI may contain parameters that are interpreted
either by SQLite itself, or by a custom VFS implementation.
SQLite and its built-in VFSes interpret the following query parameters:
.Bl -bullet
.It
\fBvfs\fP: The "vfs" parameter may be used to specify the name of a VFS object
that provides the operating system interface that should be used to
access the database file on disk.
If this option is set to an empty string the default VFS object is
used.
Specifying an unknown VFS is an error.
If sqlite3_open_v2() is used and the vfs option is present, then the
VFS specified by the option takes precedence over the value passed
as the fourth parameter to sqlite3_open_v2().
.It
\fBmode\fP: The mode parameter may be set to either "ro", "rw", "rwc", or
"memory".
Attempting to set it to any other value is an error.
If "ro" is specified, then the database is opened for read-only access,
just as if the SQLITE_OPEN_READONLY flag had been
set in the third argument to sqlite3_open_v2().
If the mode option is set to "rw", then the database is opened for
read-write (but not create) access, as if SQLITE_OPEN_READWRITE (but
not SQLITE_OPEN_CREATE) had been set.
Value "rwc" is equivalent to setting both SQLITE_OPEN_READWRITE and
SQLITE_OPEN_CREATE.
If the mode option is set to "memory" then a pure in-memory database
that never reads or writes from disk is used.
It is an error to specify a value for the mode parameter that is less
restrictive than that specified by the flags passed in the third parameter
to sqlite3_open_v2().
.It
\fBcache\fP: The cache parameter may be set to either "shared" or "private".
Setting it to "shared" is equivalent to setting the SQLITE_OPEN_SHAREDCACHE
bit in the flags argument passed to sqlite3_open_v2().
Setting the cache parameter to "private" is equivalent to setting the
SQLITE_OPEN_PRIVATECACHE bit.
If sqlite3_open_v2() is used and the "cache" parameter is present in
a URI filename, its value overrides any behavior requested by setting
SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
.It
\fBpsow\fP: The psow parameter indicates whether or not the powersafe overwrite
property does or does not apply to the storage media on which the database
file resides.
.It
\fBnolock\fP: The nolock parameter is a boolean query parameter which if
set disables file locking in rollback journal modes.
This is useful for accessing a database on a filesystem that does not
support locking.
Caution:  Database corruption might result if two or more processes
write to the same database and any one of those processes uses nolock=1.
.It
\fBimmutable\fP: The immutable parameter is a boolean query parameter that
indicates that the database file is stored on read-only media.
When immutable is set, SQLite assumes that the database file cannot
be changed, even by a process with higher privilege, and so the database
is opened read-only and all locking and change detection is disabled.
Caution: Setting the immutable property on a database file that does
in fact change can result in incorrect query results and/or SQLITE_CORRUPT
errors.
.El
.Pp
Specifying an unknown parameter in the query component of a URI is
not an error.
Future versions of SQLite might understand additional query parameters.
See "query parameters with special meaning to SQLite"
for additional information.
.Ss URI filename examples
.Pp
   URI filenames   Results
   file:data.db   Open the file "data.db" in the current directory.
   file:/home/fred/data.db  file:///home/fred/data.db   file://localhost/home/fred/data.db
  Open the database file "/home/fred/data.db".
   file://darkstar/home/fred/data.db   An error.
"darkstar" is not a recognized authority.
   file:///C:/Documents%20and%20Settings/fred/Desktop/data.db   Windows
only: Open the file "data.db" on fred's desktop on drive C:.
Note that the %20 escaping in this example is not strictly necessary
- space characters can be used literally in URI filenames.
   file:data.db?mode=ro&cache=private   Open file "data.db" in the current
directory for read-only access.
Regardless of whether or not shared-cache mode is enabled by default,
use a private cache.
   file:/home/fred/data.db?vfs=unix-dotfile   Open file "/home/fred/data.db".
Use the special VFS "unix-dotfile" that uses dot-files in place of
posix advisory locking.
   file:data.db?mode=readonly   An error.
"readonly" is not a valid option for the "mode" parameter.
Use "ro" instead:  "file:data.db?mode=ro".
.Pp
URI hexadecimal escape sequences (%HH) are supported within the path
and query components of a URI.
A hexadecimal escape sequence consists of a percent sign - "%" - followed
by exactly two hexadecimal digits specifying an octet value.
Before the path or query components of a URI filename are interpreted,
they are encoded using UTF-8 and all hexadecimal escape sequences replaced
by a single byte containing the corresponding octet.
If this process generates an invalid UTF-8 encoding, the results are
undefined.
.Pp
\fBNote to Windows users:\fP  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().
.Pp
\fBNote to Windows Runtime users:\fP  The temporary directory must be set
prior to calling sqlite3_open() or sqlite3_open_v2().
Otherwise, various features that require the use of temporary files
may fail.
.Pp
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 3462.
.Bd -literal
SQLITE_API int sqlite3_open(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
SQLITE_API int sqlite3_open16(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
SQLITE_API 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 */
);
.Ed
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr sqlite3_close 3 ,
.Xr sqlite3_config 3 ,
.Xr sqlite3_db_readonly 3 ,
.Xr sqlite3_enable_shared_cache 3 ,
.Xr sqlite3_errcode 3 ,
.Xr sqlite3_temp_directory 3 ,
.Xr sqlite3_vfs 3 ,
.Xr SQLITE_CONFIG_SINGLETHREAD 3 ,
.Xr SQLITE_IOCAP_ATOMIC 3 ,
.Xr SQLITE_OK 3 ,
.Xr SQLITE_OPEN_READONLY 3