# Glom::ConnectionPoolBackends::Backend Class Reference

This hides database specific functionality from the ConnectionPool, so the ConnectionPool can be used without worrying about the actual database backend in use. More...

Inherited by Glom::ConnectionPoolBackends::Postgres, and Glom::ConnectionPoolBackends::Sqlite.

List of all members.

## Public Types

enum | InitErrors { INITERROR_NONE, INITERROR_DIRECTORY_ALREADY_EXISTS, INITERROR_COULD_NOT_CREATE_DIRECTORY, INITERROR_COULD_NOT_START_SERVER, INITERROR_OTHER }
enum | StartupErrors { STARTUPERROR_NONE, STARTUPERROR_FAILED_NO_DATA, STARTUPERROR_FAILED_NO_DATA_HAS_BACKUP_DATA, STARTUPERROR_FAILED_UNKNOWN_REASON }
typedef std::vector< sharedptr < const Field > > | type_vec_const_fields

## Public Member Functions

virtual | ~Backend ()

## Protected Types

typedef sigc::slot< void > | SlotProgress
| This callback should show UI to indicate that work is still happening.

## Protected Member Functions

bool | query_execute (const Glib::RefPtr< Gnome::Gda::Connection >& connection, const Glib::ustring& sql_query, std::auto_ptr< Glib::Error >& error)
| Helper functions for backend implementations to use, so that these don't need to worry whether glibmm was compiled with exceptions or not.
bool | set_server_operation_value (const Glib::RefPtr< Gnome::Gda::ServerOperation >& operation, const Glib::ustring& path, const Glib::ustring& value, std::auto_ptr< Glib::Error >& error)
Glib::RefPtr < Gnome::Gda::ServerOperation > | create_server_operation (const Glib::RefPtr< Gnome::Gda::ServerProvider >& provider, const Glib::RefPtr< Gnome::Gda::Connection >& connection, Gnome::Gda::ServerOperationType type, std::auto_ptr< Glib::Error >& error)
bool | perform_server_operation (const Glib::RefPtr< Gnome::Gda::ServerProvider >& provider, const Glib::RefPtr< Gnome::Gda::Connection >& connection, const Glib::RefPtr< Gnome::Gda::ServerOperation >& operation, std::auto_ptr< Glib::Error >& error)
bool | begin_transaction (const Glib::RefPtr< Gnome::Gda::Connection >& connection, const Glib::ustring& name, Gnome::Gda::TransactionIsolation level, std::auto_ptr< Glib::Error >& error)
bool | commit_transaction (const Glib::RefPtr< Gnome::Gda::Connection >& connection, const Glib::ustring& name, std::auto_ptr< Glib::Error >& error)
bool | rollback_transaction (const Glib::RefPtr< Gnome::Gda::Connection >& connection, const Glib::ustring& name, std::auto_ptr< Glib::Error >& error)
virtual Field::sql_format | get_sql_format () const =0
| This method specifies the format of values in SQL expressions.
virtual bool | supports_remote_access () const =0
| Whether the database can be accessed from remote machines, once startup() was called.
virtual Glib::ustring | get_string_find_operator () const =0
| The operator to use to compare strings in a case-independant way.
virtual const char* | get_public_schema_name () const =0
| This specifies the database schema which contains the non-internal tables.
void | set_database_directory_uri (const std::string& directory_uri)
| This specifies that Glom should start its own database server instance (if it's PostgreSQL) for this database, using the database files stored at the specified uri, or just use that file (if it's sqlite).
std::string | get_database_directory_uri () const
virtual InitErrors | initialize (const SlotProgress& slot_progress, const Glib::ustring& initial_username, const Glib::ustring& password, bool network_shared=false)
| This method is called for one-time initialization of the database storage.
virtual StartupErrors | startup (const SlotProgress& slot_progress, bool network_shared=false)
| This method is called before the backend is used otherwise.
virtual bool | cleanup (const SlotProgress& slot_progress)
| This method is called when the backend is no longer used.
virtual bool | set_network_shared (const SlotProgress& slot_progress, bool network_shared=true)
| Change the database server's configration to allow or prevent access from other users on the network.
virtual Glib::RefPtr < Gnome::Gda::Connection > | connect (const Glib::ustring& database, const Glib::ustring& username, const Glib::ustring& password, std::auto_ptr< ExceptionConnection >& error)=0
| This method is called to create a connection to the database server.
virtual bool | add_column (const Glib::RefPtr< Gnome::Gda::Connection >& connection, const Glib::ustring& table_name, const sharedptr< const Field >& field, std::auto_ptr< Glib::Error >& error)
virtual bool | drop_column (const Glib::RefPtr< Gnome::Gda::Connection >& connection, const Glib::ustring& table_name, const Glib::ustring& field_name, std::auto_ptr< Glib::Error >& error)
virtual bool | change_columns (const Glib::RefPtr< Gnome::Gda::Connection >& connection, const Glib::ustring& table_name, const type_vec_const_fields& old_fields, const type_vec_const_fields& new_fields, std::auto_ptr< Glib::Error >& error)
virtual bool | create_database (const Glib::ustring& database_name, const Glib::ustring& username, const Glib::ustring& password, std::auto_ptr< Glib::Error >& error)=0
| This method is called to create a new database on the database server.
virtual bool | save_backup (const SlotProgress& slot_progress, const Glib::ustring& username, const Glib::ustring& password, const Glib::ustring& database_name)=0
| Save a backup of the database in a tarball.
virtual bool | convert_backup (const SlotProgress& slot_progress, const std::string& base_directory_uri, const Glib::ustring& username, const Glib::ustring& password, const Glib::ustring& database_name)=0
| Use a backup of the database in a tarball to create the tables and data in an existing empty database.

## Protected Attributes

std::string | m_database_directory_uri

## Detailed Description

This hides database specific functionality from the ConnectionPool, so the ConnectionPool can be used without worrying about the actual database backend in use.

Use ConnectionPool::set_backend() to set the backend for the connectionpool to use.

## Member Typedef Documentation

typedef sigc::slot<void> Glom::ConnectionPoolBackends::Backend::SlotProgress `[protected]`

This callback should show UI to indicate that work is still happening.

For instance, a pulsing ProgressBar.

typedef std::vector<sharedptr<const Field> > Glom::ConnectionPoolBackends::Backend::type_vec_const_fields

## Member Enumeration Documentation

enum Glom::ConnectionPoolBackends::Backend::InitErrors

Enumerator:

  INITERROR_NONE |
  INITERROR_DIRECTORY_ALREADY_EXISTS |
  INITERROR_COULD_NOT_CREATE_DIRECTORY |
  INITERROR_COULD_NOT_START_SERVER |
  INITERROR_OTHER |

enum Glom::ConnectionPoolBackends::Backend::StartupErrors

Enumerator:

  STARTUPERROR_NONE |
  STARTUPERROR_FAILED_NO_DATA |
  STARTUPERROR_FAILED_NO_DATA_HAS_BACKUP_DATA |
  STARTUPERROR_FAILED_UNKNOWN_REASON |

## Constructor & Destructor Documentation

virtual Glom::ConnectionPoolBackends::Backend::~Backend | ( |  | ) | `[inline, virtual]`

## Member Function Documentation

bool Glom::ConnectionPoolBackends::Backend::add_column | ( | const Glib::RefPtr< Gnome::Gda::Connection > & | connection,
|  | const Glib::ustring & | table_name,
|  | const sharedptr< const Field >& | field,
|  | std::auto_ptr< Glib::Error > & | error |
| ) |  |  | `[protected, virtual]`

bool Glom::ConnectionPoolBackends::Backend::begin_transaction | ( | const Glib::RefPtr< Gnome::Gda::Connection > & | connection,
|  | const Glib::ustring & | name,
|  | Gnome::Gda::TransactionIsolation | level,
|  | std::auto_ptr< Glib::Error > & | error |
| ) |  |  | `[protected]`

bool Glom::ConnectionPoolBackends::Backend::change_columns | ( | const Glib::RefPtr< Gnome::Gda::Connection > & | connection,
|  | const Glib::ustring & | table_name,
|  | const type_vec_const_fields& | old_fields,
|  | const type_vec_const_fields& | new_fields,
|  | std::auto_ptr< Glib::Error > & | error |
| ) |  |  | `[protected, virtual]`

bool Glom::ConnectionPoolBackends::Backend::cleanup | ( | const SlotProgress& | slot_progress | ) | `[protected, virtual]`

This method is called when the backend is no longer used.

This can be used to shut down a self-hosted database server. There is no need to implement this function if there is no need for extra cleanup code.

Parameters:

  | slot_progress | A callback to call while the work is still happening.

bool Glom::ConnectionPoolBackends::Backend::commit_transaction | ( | const Glib::RefPtr< Gnome::Gda::Connection > & | connection,
|  | const Glib::ustring & | name,
|  | std::auto_ptr< Glib::Error > & | error |
| ) |  |  | `[protected]`

virtual Glib::RefPtr<Gnome::Gda::Connection> Glom::ConnectionPoolBackends::Backend::connect | ( | const Glib::ustring & | database,
|  | const Glib::ustring & | username,
|  | const Glib::ustring & | password,
|  | std::auto_ptr< ExceptionConnection >& | error |
| ) |  |  | `[protected, pure virtual]`

This method is called to create a connection to the database server.

There exists only the variant with an error variable as last parameter so we don't need ifdefs all over the code. This part of the API is only used by the ConnectionPool which will translate the error back into an exception in case exceptions are enabled. If this method doesn't return a connection handle then error will be non-zero (and vice versa).

virtual bool Glom::ConnectionPoolBackends::Backend::convert_backup | ( | const SlotProgress& | slot_progress,
|  | const std::string & | base_directory_uri,
|  | const Glib::ustring & | username,
|  | const Glib::ustring & | password,
|  | const Glib::ustring & | database_name |
| ) |  |  | `[protected, pure virtual]`

Use a backup of the database in a tarball to create the tables and data in an existing empty database.

The database (server) should already have the necessary groups and users. See save_backup().

Implemented in Glom::ConnectionPoolBackends::Postgres.

virtual bool Glom::ConnectionPoolBackends::Backend::create_database | ( | const Glib::ustring & | database_name,
|  | const Glib::ustring & | username,
|  | const Glib::ustring & | password,
|  | std::auto_ptr< Glib::Error > & | error |
| ) |  |  | `[protected, pure virtual]`

This method is called to create a new database on the database server.

Glib::RefPtr< Gnome::Gda::ServerOperation > Glom::ConnectionPoolBackends::Backend::create_server_operation | ( | const Glib::RefPtr< Gnome::Gda::ServerProvider > & | provider,
|  | const Glib::RefPtr< Gnome::Gda::Connection > & | connection,
|  | Gnome::Gda::ServerOperationType | type,
|  | std::auto_ptr< Glib::Error > & | error |
| ) |  |  | `[protected]`

bool Glom::ConnectionPoolBackends::Backend::drop_column | ( | const Glib::RefPtr< Gnome::Gda::Connection > & | connection,
|  | const Glib::ustring & | table_name,
|  | const Glib::ustring & | field_name,
|  | std::auto_ptr< Glib::Error > & | error |
| ) |  |  | `[protected, virtual]`

std::string Glom::ConnectionPoolBackends::Backend::get_database_directory_uri | ( |  | ) | const`[protected]`

virtual const char* Glom::ConnectionPoolBackends::Backend::get_public_schema_name | ( |  | ) | const`[protected, pure virtual]`

This specifies the database schema which contains the non-internal tables.

This is used to speedup the libgda meta store update by only updating the non-internal tables. libgda might later be able to do this without us specifying it explicitely. See #575235.

virtual Field::sql_format Glom::ConnectionPoolBackends::Backend::get_sql_format | ( |  | ) | const`[protected, pure virtual]`

This method specifies the format of values in SQL expressions.

virtual Glib::ustring Glom::ConnectionPoolBackends::Backend::get_string_find_operator | ( |  | ) | const`[protected, pure virtual]`

The operator to use to compare strings in a case-independant way.

This is backend-depandent. For example, postgres uses ILIKE but SQLite uses LIKE. TODO: Maybe we can use libgda to construct the expression, so we don't need this function.

Backend::InitErrors Glom::ConnectionPoolBackends::Backend::initialize | ( | const SlotProgress& | slot_progress,
|  | const Glib::ustring & | initial_username,
|  | const Glib::ustring & | password,
|  | bool | network_shared = `false` |
| ) |  |  | `[protected, virtual]`

This method is called for one-time initialization of the database storage.

There is no need to implement this function if the data is centrally hosted rather than hosted by Glom.

Parameters:

  | slot_progress | A callback to call while the work is still happening.
  | network_shared | Whether the database (and document) should be available to other users over the network, if possible.

bool Glom::ConnectionPoolBackends::Backend::perform_server_operation | ( | const Glib::RefPtr< Gnome::Gda::ServerProvider > & | provider,
|  | const Glib::RefPtr< Gnome::Gda::Connection > & | connection,
|  | const Glib::RefPtr< Gnome::Gda::ServerOperation > & | operation,
|  | std::auto_ptr< Glib::Error > & | error |
| ) |  |  | `[protected]`

bool Glom::ConnectionPoolBackends::Backend::query_execute | ( | const Glib::RefPtr< Gnome::Gda::Connection > & | connection,
|  | const Glib::ustring & | sql_query,
|  | std::auto_ptr< Glib::Error > & | error |
| ) |  |  | `[protected]`

Helper functions for backend implementations to use, so that these don't need to worry whether glibmm was compiled with exceptions or not.

bool Glom::ConnectionPoolBackends::Backend::rollback_transaction | ( | const Glib::RefPtr< Gnome::Gda::Connection > & | connection,
|  | const Glib::ustring & | name,
|  | std::auto_ptr< Glib::Error > & | error |
| ) |  |  | `[protected]`

virtual bool Glom::ConnectionPoolBackends::Backend::save_backup | ( | const SlotProgress& | slot_progress,
|  | const Glib::ustring & | username,
|  | const Glib::ustring & | password,
|  | const Glib::ustring & | database_name |
| ) |  |  | `[protected, pure virtual]`

Save a backup of the database in a tarball.

This backup can later be used to recreate the database, for instance with a later version of PostgreSQL.

Implemented in Glom::ConnectionPoolBackends::Postgres.

void Glom::ConnectionPoolBackends::Backend::set_database_directory_uri | ( | const std::string & | directory_uri | ) | `[protected]`

This specifies that Glom should start its own database server instance (if it's PostgreSQL) for this database, using the database files stored at the specified uri, or just use that file (if it's sqlite).

Or it can be used temporarily when calling save_backup() to provide the top-level directory path.

bool Glom::ConnectionPoolBackends::Backend::set_network_shared | ( | const SlotProgress& | slot_progress,
|  | bool | network_shared = `true` |
| ) |  |  | `[protected, virtual]`

Change the database server's configration to allow or prevent access from other users on the network.

For current backends, you may use this only before startup(), or after cleanup().

Parameters:

  | slot_progress | A callback to call while the work is still happening.
  | network_shared | Whether the database (and document) should be available to other users over the network, if possible.

bool Glom::ConnectionPoolBackends::Backend::set_server_operation_value | ( | const Glib::RefPtr< Gnome::Gda::ServerOperation > & | operation,
|  | const Glib::ustring & | path,
|  | const Glib::ustring & | value,
|  | std::auto_ptr< Glib::Error > & | error |
| ) |  |  | `[protected]`

Backend::StartupErrors Glom::ConnectionPoolBackends::Backend::startup | ( | const SlotProgress& | slot_progress,
|  | bool | network_shared = `false` |
| ) |  |  | `[protected, virtual]`

This method is called before the backend is used otherwise.

This can be used to start a self-hosted database server. There is no need to implement this function if there is no need for extra startup code.

Parameters:

  | slot_progress | A callback to call while the work is still happening.
  | network_shared | Whether the database (and document) should be available to other users over the network, if possible.

virtual bool Glom::ConnectionPoolBackends::Backend::supports_remote_access | ( |  | ) | const`[protected, pure virtual]`

Whether the database can be accessed from remote machines, once startup() was called.

## Member Data Documentation

std::string Glom::ConnectionPoolBackends::Backend::m_database_directory_uri `[protected]`

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

- connectionpool_backends/backend.h
- connectionpool_backends/backend.cc