API Reference

This section documents the C++ classes and functions that make up the Reldbase libraries. All classes reside in the reldbase namespace.

Relational types module

class Attribute

Public Functions

Attribute() = default: Construct a default attribute (empty name, type Str)

Attribute(const string name, Attr_type type = Attr_type::Str): Construct an attribute with a built-in type (default Str)

Attribute(const string name, const string &type_name): Construct an attribute with the given type name. The name may be a built-in type (e.g., “int”) or a user-defined type.

inline const string name() const

inline void set_name(const string &name)

inline bool is_builtin() const: True if the type is one of the built-in types.

string type_name() const: Return the type as a string, e.g., “int”, “float”, “str”, “bool”, or a user-defined type name

Attr_type type() const: Return the built-in type. Throws if the type is not built-in.

void set_type(Attr_type): Set the type from a built-in type.

void set_type(const string&): Set the type from a type name (built-in or user-defined)

class Rel_tuple

Public Types

using Attr_name = string

Public Functions

Rel_tuple(vector<Attribute> attribs = {}, map<Attr_name, string> vals = {})

Construct a tuple from a list of attributes and, optionally, their values (both default to empty)

Parameters:

attribs – the attributes (heading) of the tuple
vals – initial values keyed by attribute name; supplied as text, they are stored verbatim without type checking

void add_attrib(const Attribute &attr, const string &val = {})

Add an attribute to the tuple with an optional initial value

Parameters:

attr – the attribute to add; a duplicate name is rejected
val – initial value (empty string if omitted)

const string attrib(size_t n) const

Return the value of the given attribute (by index or name), or an empty string if it has not been set

Parameters:: n – zero-based index of the attribute
Returns:: the attribute’s value, or “” if unset

const string attrib(const Attr_name &name) const

Return the value of the given attribute (by index or name), or an empty string if it has not been set

Parameters:: name – name of the attribute
Returns:: the attribute’s value, or “” if unset

template<typename T> void set_attrib(const Attr_name &name, const T &value)

Set the value of an attribute given its name

The value is stringified and stored as text. The attribute’s declared type is validated against the type of value: an integer accepts integral values, a float accepts floating point (or integral) values, a bool accepts only bool, and a string or user-defined type accepts any value (stringified). A mismatch or an unknown name throws.

Parameters:

name – name of the attribute to set
value – value to store

const vector<std::pair<Attr_name, string>> heading() const

Return the heading as name/type-name pairs

Returns:: pairs of attribute name and type name

inline vector<Attribute> attribs() const

Return the attributes that make up the heading

Returns:: the attribute list (heading)

vector<Attr_name> attrib_names() const

Return the names of the attributes in the heading

Returns:: attribute names in heading order

inline size_t size() const

Return the number of attributes in the heading

Returns:: the heading size

Relational database module

class Rel_db

A relational interface to a database

Rel_db establishes and manages a connection and executes SQL statements, presenting result rows as Rel_tuple objects and parameterizing queries with Rel_tuple objects.

SQL statements have been classified into SELECT queries handled by fetchone() and fetchall(), DML statements (INSERT, UPDATE and DELETE) handled by execute() and commands (DDL and other statements) handled by execute_command().

Public Functions

Rel_db(const string &conn_string, const string &dbms = {})

Construct a Rel_db from a connection string

The connection string is passed verbatim to the selected DBMS. The DBMS is chosen based on the dbms argument; if that is empty, the RELDBASE_DBMS environment variable is consulted, and failing that “postgres” is used.

For PostgreSQL the string is a libpq connection string, either keyword=value or URI form. The “postgres://” in the URI form is part of libpq’s URI syntax, not how the DBMS is selected: “dbname=testdb” (PostgreSQL) “testdb” (bare database name) “postgres://user:pw@host:5432/testdb” (PostgreSQL URI)

The connection is attempted eagerly, but an unreachable DBMS is not fatal: the object is still constructed, connected() reports false, and last_error() holds the reason. A subsequent query or transaction method retries the connection.

An unknown DBMS is a configuration error and is thrown.

Rel_db(const Rel_db&) = delete

Rel_db &operator=(const Rel_db&) = delete

Rel_db(Rel_db&&) = delete

Rel_db &operator=(Rel_db&&) = delete

~Rel_db(): Close the database connection

const vector<Rel_tuple> fetchall(string query)

Execute a SELECT query and return rows

Parameters:: query – a SELECT query to execute
Returns:: the result rows, each as a Rel_tuple with one Attribute per column and the column value as text

const vector<Rel_tuple> fetchone(string query, Rel_tuple params)

Execute a single row SELECT query and return the row

Parameters:

query – a SELECT query with $n placeholders
params – a Rel_tuple whose heading matches the placeholders

Returns:

the result rows (0 or 1 expected)

const size_t execute(const string &stmt, Rel_tuple params)

Execute a SQL statement and return the number of affected rows

Parameters:

stmt – the SQL statement with $n placeholders
params – a Rel_tuple whose heading matches the placeholders

Returns:

the number of rows affected by the command

void execute_command(const string &cmd)

Execute a SQL command that returns no rows, with no parameters

Parameters:: cmd – the SQL command to execute

void begin(): Begin a transaction

void commit(): Commit currently open transaction

void rollback(): Roll back currently open transaction

inline const string &dbms_name() const: Return the name of the DBMS

inline const string &connection_string() const

Return the connection string used to make the connection

Note: if a password was part of the original connection string, its value is replaced by “*****”.

inline bool connected() const

Return true if the connection is established

The constructor attempts the connection, so a false result means the DBMS was unreachable at that time (or the connection has since been closed). Query and transaction methods retry.

inline const string &last_error() const

Return the error message from the last failed connection attempt

Empty when the connection was established.

const string &dbname() const

Return the name of the database in use

Only known once connected: libpq resolves an omitted dbname from PGDATABASE, or finally from the user name, so the connection string alone may not name a database. Returns “” when not connected.