Chapter 12. quince_postgresql

Table of Contents

The quince_postgresql::database constructor
Basic conversions
Default mappers

The quince_postgresql library's application program interface (API) is very small, because almost all calls into quince_postgresql are made by quince, not by application code.

In fact, application code only mentions one of quince_postgresql's entry-points: the quince_postgresql::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_postgresql::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_postgresql functions that are not part of its API.

With that in mind, I present the complete API of quince_postgresql: the quince_postgresql::database constructor.

It is available via:

#include <quince_postgresql/database.h>

and its prototype is:

    const std::string &host,
    const std::string &user,
    const std::string &password,
    const std::string &db_name = "",
    const std::string &default_schema = "",
    const std::string &port = "",
    const boost::optional<isolation_level> level = boost::none,
    boost::optional<const quince::mapping_customization &> customization_for_db = boost::none

Most of the arguments are information that quince_postgresql will use each time it creates a connection to the database:

  • host is the domain name of the host running the PostgreSQL server.
  • user is the PostgreSQL user name to use when logging in to the PostgreSQL server.
  • password is the password to use if the server demands password authentication.
  • db_name is the name of the database to connect to. If empty, it defaults to the user name.
  • default_schema, if nonempty, is a PostgreSQL schema name that will be set as the SQL search path for each connection. Any quince table object with a one-part name will be taken as referring to a table in that schema.
  • port is the TCP port number to connect to, given as a string of decimal digits, e.g. "1234". If empty, it defaults to "5432" (the standard default port for PostgreSQL).

If level is supplied, it contains a quince_postgresql::isolation_level:

enum class isolation_level {
    serializable, repeatable_read, read_committed, read_uncommitted

Then all transactions will have the corresponding characteristic (SERIALIZABLE, REPEATABLE READ, READ COMMITTED or READ UNCOMMITTED), which are explained here. If you don't supply an isolation_level, then quince_postgresql doesn't supply one to PostgreSQL, and it uses READ COMMITTED by default.

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_postgresql library is complete.