GncDbiBackend< Type > Class Template Reference

Inheritance diagram for GncDbiBackend< Type >:

Public Member Functions
	GncDbiBackend (GncSqlConnection *conn, QofBook *book)
void	session_begin (QofSession *, const char *, SessionOpenMode) override
	Open the file or connect to the server. More...
void	session_end () override
void	load (QofBook *, QofBackendLoadType) override
	Load the minimal set of application data needed for the application to be operable at initial startup. More...
void	safe_sync (QofBook *) override
	Safely resave a database by renaming all of its tables, recreating everything, and then dropping the backup tables only if there were no errors. More...
bool	connected () const noexcept
void	set_dbi_error (QofBackendError error, unsigned int repeat, bool retry) noexcept
	FIXME: Just a pass-through to m_conn:
void	retry_connection (const char *msg) const noexcept
bool	exists ()
void	set_exists (bool exists)
template<>
void	session_begin (QofSession *session, const char *new_uri, SessionOpenMode mode)
	Open the file or connect to the server. More...
template<>
void	safe_sync (QofBook *book)
	Perform a sync in a way that prevents data loss on a DBI backend.
Public Member Functions inherited from GncSqlBackend
	GncSqlBackend (GncSqlConnection *conn, QofBook *book)
void	load (QofBook *, QofBackendLoadType) override
	Load the contents of an SQL database into a book. More...
void	sync (QofBook *) override
	Save the contents of a book to an SQL database. More...
void	begin (QofInstance *) override
	An object is about to be edited. More...
void	commit (QofInstance *) override
	Object editing is complete and the object should be saved. More...
void	rollback (QofInstance *) override
	Object editing has been cancelled. More...
void	connect (GncSqlConnection *conn) noexcept
	Connect the backend to a GncSqlConnection. More...
void	init_version_info () noexcept
	Initializes DB table version information. More...
bool	reset_version_info () noexcept
	Resets the version table information by removing all version table info. More...
void	finalize_version_info () noexcept
	Finalizes DB table version information. More...
GncSqlStatementPtr	create_statement_from_sql (const std::string &str) const noexcept
GncSqlResultPtr	execute_select_statement (const GncSqlStatementPtr &stmt) const noexcept
	Executes an SQL SELECT statement and returns the result rows. More...
int	execute_nonselect_statement (const GncSqlStatementPtr &stmt) const noexcept
std::string	quote_string (const std::string &) const noexcept
bool	create_table (const std::string &table_name, const EntryVec &col_table) const noexcept
	Creates a table in the database. More...
bool	create_table (const std::string &table_name, int table_version, const EntryVec &col_table) noexcept
	Creates a table in the database and sets its version. More...
void	create_tables () noexcept
	Create/update all tables in the database.
bool	create_index (const std::string &index_name, const std::string &table_name, const EntryVec &col_table) const noexcept
	Creates an index in the database. More...
bool	add_columns_to_table (const std::string &table_name, const EntryVec &col_table) const noexcept
	Adds one or more columns to an existing table. More...
void	upgrade_table (const std::string &table_name, const EntryVec &col_table) noexcept
	Upgrades a table to a new structure. More...
uint_t	get_table_version (const std::string &table_name) const noexcept
	Returns the version number for a DB table. More...
bool	set_table_version (const std::string &table_name, uint_t version) noexcept
	Registers the version for a table. More...
void	commodity_for_postload_processing (gnc_commodity *)
	Register a commodity to be committed after loading is complete. More...
GncSqlObjectBackendPtr	get_object_backend (const std::string &type) const noexcept
	Get the GncSqlObjectBackend for the indicated type. More...
bool	object_in_db (const char *table_name, QofIdTypeConst obj_name, const gpointer pObject, const EntryVec &table) const noexcept
	Checks whether an object is in the database or not. More...
bool	do_db_operation (E_DB_OPERATION op, const char *table_name, QofIdTypeConst obj_name, gpointer pObject, const EntryVec &table) const noexcept
	Performs an operation on the database. More...
bool	save_commodity (gnc_commodity *comm) noexcept
	Ensure that a commodity referenced in another object is in fact saved in the database. More...
QofBook *	book () const noexcept
void	set_loading (bool loading) noexcept
bool	pristine () const noexcept
void	update_progress (double pct) const noexcept
void	finish_progress () const noexcept
Public Member Functions inherited from QofBackend
	QofBackend (const QofBackend &)=delete
	QofBackend (const QofBackend &&)=delete
virtual void	export_coa (QofBook *)
	Extract the chart of accounts from the current database and create a new database with it. More...
void	set_error (QofBackendError err)
	Set the error value only if there isn't already an error already.
QofBackendError	get_error ()
	Retrieve the currently-stored error and clear it.
bool	check_error ()
	Report if there is an error.
void	set_message (std::string &&)
	Set a descriptive message that can be displayed to the user when there's an error.
const std::string &&	get_message ()
	Retrieve and clear the stored error message.
void	set_percentage (QofBePercentageFunc pctfn)
	Store and retrieve a backend-specific function for determining the progress in completing a long operation, for use with a progress meter.
QofBePercentageFunc	get_percentage ()
const std::string &	get_uri ()
	Retrieve the backend's storage URI.

Additional Inherited Members
Static Public Member Functions inherited from QofBackend
static bool	register_backend (const char *, const char *)
	Class methods for dynamically loading the several backends and for freeing them at shutdown.
static void	release_backends ()
Protected Attributes inherited from GncSqlBackend
GncSqlConnection *	m_conn = nullptr
	SQL connection.
QofBook *	m_book = nullptr
	The primary, main open book.
bool	m_loading
	We are performing an initial load.
bool	m_in_query
	We are processing a query.
bool	m_is_pristine_db
	Are we saving to a new pristine db?
const char *	m_time_format = nullptr
	Server-specific date-time string format.
VersionVec	m_versions
	Version number for each table.
Protected Attributes inherited from QofBackend
QofBePercentageFunc	m_percentage
std::string	m_fullpath
	Each backend resolves a fully-qualified file path. More...

Detailed Description

template<DbType Type>
class GncDbiBackend< Type >

Definition at line 88 of file gnc-backend-dbi.hpp.

Member Function Documentation

load()

template<DbType Type>

void GncDbiBackend< Type >::load ( QofBook *  , QofBackendLoadType    )

overridevirtual

Load the minimal set of application data needed for the application to be operable at initial startup.

It is assumed that the application will perform a 'run_query()' to obtain any additional data that it needs. For file-based backends, it is acceptable for the backend to return all data at load time; for SQL-based backends, it is acceptable for the backend to return no data.

Thus, for example, the old GnuCash postgres backend returned the account tree, all currencies, and the pricedb, as these were needed at startup. It did not have to return any transactions whatsoever, as these were obtained at a later stage when a user opened a register, resulting in a query being sent to the backend. The current DBI backend on the other hand loads the entire database into memory.

(Its OK to send over entities at this point, but one should be careful of the network load; also, its possible that whatever is sent is not what the user wanted anyway, which is why its better to wait for the query).

Implements QofBackend.

Definition at line 862 of file gnc-backend-dbi.cpp.

{
    g_return_if_fail (book != nullptr);

    ENTER ("dbi_be=%p, book=%p", this, book);

    if (loadType == LOAD_TYPE_INITIAL_LOAD)
    {

        // Set up table version information
        init_version_info ();
        assert (m_book == nullptr);
        create_tables();
    }

    GncSqlBackend::load(book, loadType);

    if (Type == DbType::DBI_SQLITE)
        gnc_features_set_used(book, GNC_FEATURE_SQLITE3_ISO_DATES);

    if (GNUCASH_RESAVE_VERSION > get_table_version("Gnucash"))
    {
        /* The database was loaded with an older database schema or
         * data semantics. In order to ensure consistency, the whole
         * thing needs to be saved anew. */
        set_error(ERR_SQL_DB_TOO_OLD);
    }
    else if (GNUCASH_RESAVE_VERSION < get_table_version("Gnucash-Resave"))
    {
        /* Worse, the database was created with a newer version. We
         * can't safely write to this database, so the user will have
         * to do a "save as" to make one that we can write to.
         */
        set_error(ERR_SQL_DB_TOO_NEW);
    }


    LEAVE ("");
}

safe_sync()

template<DbType Type>

void GncDbiBackend< Type >::safe_sync ( QofBook *  book )

overridevirtual

Safely resave a database by renaming all of its tables, recreating everything, and then dropping the backup tables only if there were no errors.

If there are errors, drop the new tables and restore the originals.

Parameters

book	QofBook to be saved in the database.

Implements QofBackend.

Definition at line 946 of file gnc-backend-dbi.cpp.

{
    auto conn = dynamic_cast<GncDbiSqlConnection*>(m_conn);

    g_return_if_fail (conn != nullptr);
    g_return_if_fail (book != nullptr);

    ENTER ("book=%p, primary=%p", book, m_book);
    if (!conn->begin_transaction())
    {
        LEAVE("Failed to obtain a transaction.");
        return;
    }
    if (!conn->table_operation (TableOpType::backup))
    {
        conn->rollback_transaction();
        LEAVE ("Failed to rename tables");
        return;
    }
    if (!conn->drop_indexes())
    {
        conn->rollback_transaction();
        LEAVE ("Failed to drop indexes");
        return;
    }

    sync(m_book);
    if (check_error())
    {
        conn->rollback_transaction();
        LEAVE ("Failed to create new database tables");
        return;
    }
    conn->table_operation (TableOpType::drop_backup);
    conn->commit_transaction();
    LEAVE ("book=%p", m_book);
}

session_begin() [1/2]

template<DbType Type>

void GncDbiBackend< Type >::session_begin ( QofSession *  session, const char *  new_uri, SessionOpenMode  mode  )

overridevirtual

Open the file or connect to the server.

Parameters

session	The QofSession that will control the backend.
new_uri	The location of the data store that the backend will use.
mode	The session open mode. See qof_session_begin().

Implements QofBackend.

Definition at line 637 of file gnc-backend-dbi.cpp.

{
    PairVec options;

    g_return_if_fail (session != nullptr);
    g_return_if_fail (new_uri != nullptr);

    ENTER (" ");

    /* Split the book-id
     * Format is protocol://username:password@hostname:port/dbname
     where username, password and port are optional) */
    UriStrings uri(new_uri);

    if (Type == DbType::DBI_PGSQL)
    {
        if (uri.m_portnum == 0)
            uri.m_portnum = PGSQL_DEFAULT_PORT;
        /* Postgres's SQL interface coerces identifiers to lower case, but the
         * C interface is case-sensitive. This results in a mixed-case dbname
         * being created (with a lower case name) but then dbi can't connect to
         * it. To work around this, coerce the name to lowercase first. */
        auto lcname = g_utf8_strdown (uri.dbname(), -1);
        uri.m_dbname = std::string{lcname};
        g_free(lcname);
    }
    connect(nullptr);

    bool create{mode == SESSION_NEW_STORE || mode == SESSION_NEW_OVERWRITE};
    auto conn = conn_setup(options, uri);
    if (conn == nullptr)
    {
        LEAVE("Error");
        return;
    }

    m_exists = true; //May be unset in the error handler.
    auto result = dbi_conn_connect (conn);
    if (result == 0)
    {
        if (Type == DbType::DBI_MYSQL)
            adjust_sql_options (conn);
        if(!conn_test_dbi_library(conn))
        {
            dbi_conn_close(conn);
            LEAVE("Error");
            return;
        }
        bool create = (mode == SESSION_NEW_STORE ||
                       mode == SESSION_NEW_OVERWRITE);
        if (create && save_may_clobber_data<Type>(conn, uri.quote_dbname(Type)))
        {
            if (mode == SESSION_NEW_OVERWRITE)
            {
                if (!drop_database<Type>(conn, uri))
                    return;
            }
            else
            {
                set_error (ERR_BACKEND_STORE_EXISTS);
                PWARN ("Database already exists, Might clobber it.");
                dbi_conn_close(conn);
                LEAVE("Error");
                return;
            }
            /* Drop successful. */
            m_exists = false;
        }

    }
    else if (m_exists)
    {
        PERR ("Unable to connect to database '%s'\n", uri.dbname());
        set_error (ERR_BACKEND_CANT_CONNECT);
        dbi_conn_close(conn);
        LEAVE("Error");
        return;
    }
    else if (!create)
    {
        PERR ("Database '%s' does not exist\n", uri.dbname());
        set_error(ERR_BACKEND_NO_SUCH_DB);
        std::string msg{"Database "};
        set_message(msg + uri.dbname() + " not found");
        LEAVE("Error");
        return;
    }

    if (create)
    {
        if (!m_exists &&
            !create_database(conn, uri.quote_dbname(Type).c_str()))
        {
            dbi_conn_close(conn);
            LEAVE("Error");
            return;
        }
        conn = conn_setup(options, uri);
        result = dbi_conn_connect (conn);
        if (result < 0)
        {
            PERR ("Unable to create database '%s'\n", uri.dbname());
            set_error (ERR_BACKEND_SERVER_ERR);
            dbi_conn_close(conn);
            LEAVE("Error");
            return;
        }
        if (Type == DbType::DBI_MYSQL)
            adjust_sql_options (conn);
        if (!conn_test_dbi_library(conn))
        {
            if (Type == DbType::DBI_PGSQL)
                dbi_conn_select_db (conn, "template1");
            dbi_conn_queryf (conn, "DROP DATABASE %s",
                                uri.quote_dbname(Type).c_str());
            dbi_conn_close(conn);
            return;
        }
    }

    connect(nullptr);
    try
    {
        connect(new GncDbiSqlConnection(Type, this, conn, mode));
    }
    catch (std::runtime_error& err)
    {
        return;
    }
    /* We should now have a proper session set up.
     * Let's start logging */
    auto translog_path = gnc_build_translog_path (uri.basename().c_str());
    xaccLogSetBaseName (translog_path);
    PINFO ("logpath=%s", translog_path ? translog_path : "(null)");
    g_free (translog_path);

    LEAVE (" ");
}

session_begin() [2/2]

template<>

void GncDbiBackend< DbType::DBI_SQLITE >::session_begin ( QofSession *  session, const char *  new_uri, SessionOpenMode  mode  )

virtual

Open the file or connect to the server.

Parameters

session	The QofSession that will control the backend.
new_uri	The location of the data store that the backend will use.
mode	The session open mode. See qof_session_begin().

Implements QofBackend.

Definition at line 356 of file gnc-backend-dbi.cpp.

{
    gboolean file_exists;
    PairVec options;

    g_return_if_fail (session != nullptr);
    g_return_if_fail (new_uri != nullptr);

    ENTER (" ");

    /* Remove uri type if present */
    auto path = gnc_uri_get_path (new_uri);
    std::string filepath{path};
    g_free(path);
    GFileTest ftest = static_cast<decltype (ftest)> (
        G_FILE_TEST_IS_REGULAR | G_FILE_TEST_EXISTS) ;
    file_exists = g_file_test (filepath.c_str(), ftest);
    bool create{mode == SESSION_NEW_STORE || mode == SESSION_NEW_OVERWRITE};
    if (!create && !file_exists)
    {
        set_error (ERR_FILEIO_FILE_NOT_FOUND);
        std::string msg{"Sqlite3 file "};
        set_message (msg + filepath + " not found");
        PWARN ("Sqlite3 file %s not found", filepath.c_str());
        LEAVE("Error");
        return;
    }

    if (create && file_exists)
    {
        if (mode == SESSION_NEW_OVERWRITE)
            g_unlink (filepath.c_str());
        else
        {
            set_error (ERR_BACKEND_STORE_EXISTS);
            auto msg = "Might clobber, mode not SESSION_NEW_OVERWRITE";
            PWARN ("%s", msg);
            LEAVE("Error");
            return;
        }
    }

    connect(nullptr);
    /* dbi-sqlite3 documentation says that sqlite3 doesn't take a "host" option */
    options.push_back(std::make_pair("host", "localhost"));
    auto dirname = g_path_get_dirname (filepath.c_str());
    auto basename = g_path_get_basename (filepath.c_str());
    options.push_back(std::make_pair("dbname", basename));
    options.push_back(std::make_pair("sqlite3_dbdir", dirname));
    if (basename != nullptr) g_free (basename);
    if (dirname != nullptr) g_free (dirname);
    UriStrings uri;
    auto conn = conn_setup(options, uri);
    if (conn == nullptr)
    {
        LEAVE("Error");
        return;
    }

    auto result = dbi_conn_connect (conn);

    if (result < 0)
    {
        dbi_conn_close(conn);
        PERR ("Unable to connect to %s: %d\n", new_uri, result);
        set_error (ERR_BACKEND_BAD_URL);
        LEAVE("Error");
        return;
    }

    if (!conn_test_dbi_library(conn))
    {
        if (create && !file_exists)
        {
         /* File didn't exist before, but it does now, and we don't want to
          * leave it lying around.
          */
            dbi_conn_close (conn);
            conn = nullptr;
            g_unlink (filepath.c_str());
        }
        dbi_conn_close(conn);
        LEAVE("Bad DBI Library");
        return;
    }

    try
    {
        connect(new GncDbiSqlConnection(DbType::DBI_SQLITE,
                                            this, conn, mode));
    }
    catch (std::runtime_error& err)
    {
        return;
    }

    /* We should now have a proper session set up.
     * Let's start logging */
    xaccLogSetBaseName (filepath.c_str());
    PINFO ("logpath=%s", filepath.c_str() ? filepath.c_str() : "(null)");
    LEAVE ("");
}

---

The documentation for this class was generated from the following files:

• gnc-backend-dbi.hpp
• gnc-backend-dbi.cpp