class DatabaseInterface
#include "ucdb.h"
Overview
The abstract DatabaseInterface class provides a unified interface to different SQL type database implementations. Client code can obtain a pointer to a DatabaseInterface, and use it to execute SQL statements, without having to worry about the underlying implementation.
Virtual Methods
sql_exec(std::string query)
Executes an sql_query, and returns the results in a UniversalContainer. Successful SQL queries that return sets of rows, such as a select statements will return an array type container. Members of this array will be map type containers, whose members correspond to the columns of the SQL statement. SQL statements that do not return sets of rows, or which fail, will return a map with the members status_code and message. If the operation was successful the #boolean_value meta-data key will be set to true ensuring that a boolean evaluation of container will be true. status_code will be zero and message will be "success". If the sql operations failed, #boolean_value will be false so that a boolean evaluation of the container will be false, and status_code and message will be set to the error code and corresponding message defined by the underlying implementation.
start_transaction(void)
Starts a new transaction on the database. Returns true on success and false on failure. The DatabaseInterface base class provides a default implementation that simply executes the relevant sql. Implementations that do not need to provide additional semantics may inherit this implementation.
commit(void)
Commits a transaction on the database. Returns true on success and false on failure. The DatabaseInterface base class provides a default implementation that simply executes the relevant sql. Implementations that do not need to provide additional semantics may inherit this implementation.
rollback(void)
Rolls back a transaction on the database. Returns true on success and false on failure. The DatabaseInterface base class provides a default implementation that simply executes the relevant sql. Implementations that do not need to provide additional semantics may inherit this implementation.
UniversalContainer get_db_info(void)
This method returns a map type UniversalContainer that describes the underlying implementation and the details of the database. The only key guaranteed to be present in this map is database_type, which is a string identifying the underlying implementation. In general, the other key value pairs in the map will describe information that the underlying implementation needs to connect to the database.
Specific Implementations
class SQLiteDatabase
#include "ucsqlite.h"
Overview
The SQLiteDatabase class implements the DatabaseInterface class for SQLite3 databases. SQLite provides a simple, in process, file based SQL implementation.
Constructors
SQLiteDatabase(std::string filename)
SQLiteDatabase(char* filename)
These methods construct a new SQLiteDatabase instance based on the provided filename. If there an error occurs opening the file an exception of type UniversalContainer is thrown, with the key code set to uce_DB_Connection. When objects created with these constructors go out of scope, the sqlite connection is cleaned up.
SQLiteDatabase(sqlite3* db)
This constructor creates a new instance based on an existing sqlite3 handle. Unlike the other constructors, the resulting objects do not own the underlying database handle and so when these objects go out of scope they do not clean up the connection.
Implementation Specific Methods
sqlite3* get_db_handle(void)
This method returns the underlying database connection used by the object. This allows for connection parameters to be adjusted and other routines in the databases native library used with the class.
MySQLDatabase
#include "ucmysql.h"
Overview
This class provides an implementation of DatabaseInterface the connects to an underlying mysql database.
Constructors
MySQLDatabase(const char* hostname = NULL, const char* username = NULL, const char* password = NULL, const char* = db_name, unsigned port = 0, const char* socket = NULL, unsigned flags = 0)
MySQLDatabase(UniversalContainer)
The first constructor creates a new instance of MySQLDatabase by passing the provided parameters to the mysql function mysql_real_connection. The second constructor users examines the provided UniversalContainer for keys matching the parameters names of the first constructor, and uses those values to call mysql_real_setup when creating the database instance. The container is then cloned to provide the basis for the information returned from future get_db_info calls. When objects created with these constructors go out of scope, the sqlite connection is cleaned up.
MySQLDatabase(MYSQL* db)
This constructor creates a new instance based on an existing mysql handle. Unlike the other constructors, the resulting objects do not own the underlying database handle and so when these objects go out of scope they do not clean up the connection.
Implementation Specific Methods
MYSQL* get_db_handle(void)
This method returns the underlying database connection used by the object. This allows for connection parameters to be adjusted and other routines in the databases native library used with the class.