Chapter 13. quince_sqlite

Table of Contents

The quince_sqlite::database constructor
Basic conversions
Default mappers

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:

    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.
  • If 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.
  • If mutex is true, then the connection opens in the serialized threading mode; otherwise it opens in the multi-thread threading mode.
  • If share_cache is true then the connection can used shared cache mode, otherwise it does not participate in shared cache mode.
  • If 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.