Table of Contents
The quince_sqlite library's
application program interface (API) is very small,
because almost all calls into quince_sqlite
are made by quince, not by application code.
In fact, application code only mentions one of quince_sqlite's
entry-points: the quince_sqlite::database
constructor. After that, the application asks quince
to create tables, it asks quince to build and execute
queries, manipulate data, etc. All the while, behind the scenes, references
to the quince_sqlite::database object are being passed via
constructors from tables to queries to value mappers, and so on, so quince
always knows which backend library to use, and it makes frequent use of
quince_sqlite functions that are not part of its API.
With that in mind, I present the complete API of quince_sqlite: the quince_sqlite::database constructor.
It is available via:
#include <quince_sqlite/database.h>
and its prototype is:
database( std::string filename, bool may_write = true, bool mutex = true, bool share_cache = true, boost::optional<std::string> vfs_module_name = boost::none, boost::optional<const quince::mapping_customization &> customization_for_db = boost::none, const std::map<std::string, boost::filesystem::path> &attachable_database_filenames = std::map<std::string, boost::filesystem::path>() );
Most of the arguments are information that quince_sqlite will use each time it creates a connection to the database:
filename is the UTF-8
name of the file that holds that database.
may_write is true,
then the database is opened for writing if the operating system allows
it. In any case it is opened for reading, if the operating system allows
it.
mutex is true, then
the connection opens in the serialized threading
mode; otherwise it opens in the multi-thread threading mode.
share_cache is true
then the connection can used shared
cache mode, otherwise it does not participate in shared cache
mode.
vfs_module_name,
if supplied, it is the name of an sqlite_vfs object that defines
the the OS interface that the new connection will use. If it is not
supplied then sqlite provides a default sqlite_vfs
object.
filename_map
is a map to translate attached database names, as used as the first part
of two-part quince table names, into the
names of actual files that hold those databases. Any name that cannot be
found in the table will be used as the filename without any translation.
customization_for_db is
used to deploy custom mappings throughout the database, as described here.
If you are setting custom mappings for the database, or if you intend to add custom mappings for any tables in the database, then you need to read the rest of this chapter. Otherwise your study of the quince_sqlite library is complete.