Common database connection class. More...

#include <database_connection.h>

Inheritance diagram for isc::db::DatabaseConnection:

Classes
class	EnterTest
	RAII device to set the test mode. More...

Public Types
typedef std::map< std::string, std::string >	ParameterMap
	Database configuration parameter map.

Public Member Functions
	DatabaseConnection (const ParameterMap &parameters, DbCallback callback=DbCallback())
	Constructor.

virtual	~DatabaseConnection ()
	Destructor.

void	checkUnusable ()
	Throws an exception if the connection is not usable.

bool	configuredReadOnly () const
	Convenience method checking if database should be opened with read only access.

std::string	getParameter (const std::string &name) const
	Returns value of a connection parameter.

bool	isUnusable ()
	Flag which indicates if connection is unusable.

virtual void	makeReconnectCtl (const std::string &timer_name)
	Instantiates a ReconnectCtl based on the connection's reconnect parameters.

util::ReconnectCtlPtr	reconnectCtl ()
	The reconnect settings.

Static Public Member Functions
static isc::asiolink::IOServicePtr &	getIOService ()
	Returns pointer to the IO service.

static bool	invokeDbFailedCallback (const util::ReconnectCtlPtr &db_reconnect_ctl)
	Invokes the connection's restore failed connectivity callback.

static bool	invokeDbLostCallback (const util::ReconnectCtlPtr &db_reconnect_ctl)
	Invokes the connection's lost connectivity callback.

static bool	invokeDbRecoveredCallback (const util::ReconnectCtlPtr &db_reconnect_ctl)
	Invokes the connection's restored connectivity callback.

static ParameterMap	parse (const std::string &dbaccess)
	Parse database access string.

static std::string	redactedAccessString (const ParameterMap &parameters)
	Redact database access string.

static void	setIOService (const isc::asiolink::IOServicePtr &io_service)
	Sets IO service to be used by the database backends.

static isc::data::ElementPtr	toElement (const ParameterMap &params)
	Unparse a parameter map.

static isc::data::ElementPtr	toElementDbAccessString (const std::string &dbaccess)
	Unparse an access string.

Static Public Attributes
static DbCallback	db_failed_callback_ = 0
	Optional callback function to invoke if an opened connection recovery failed.

static DbCallback	db_lost_callback_ = 0
	Optional callback function to invoke if an opened connection is lost.

static DbCallback	db_recovered_callback_ = 0
	Optional callback function to invoke if an opened connection recovery succeeded.

static const time_t	MAX_DB_TIME = 2147483647
	Defines maximum value for time that can be reliably stored.

static bool	retry_ = false
	Flag which indicates if the database connection should be retried on fail.

static bool	test_mode_ = false
	Test mode flag (default false).

Protected Member Functions
void	markUnusable ()
	Sets the unusable flag to true.

Protected Attributes
DbCallback	callback_
	The callback used to recover the connection.

Detailed Description

Common database connection class.

This class provides functions that are common for establishing connection with different types of databases; enables operations on access parameters strings. In particular, it provides a way to parse parameters in key=value format. This class is expected to be a base class for all isc::dhcp::LeaseMgr and possibly isc::dhcp::BaseHostDataSource derived classes.

Definition at line 125 of file database_connection.h.

Member Typedef Documentation

◆ ParameterMap

std::map<std::string, std::string> isc::db::DatabaseConnection::ParameterMap

Database configuration parameter map.

Definition at line 137 of file database_connection.h.

Constructor & Destructor Documentation

◆ DatabaseConnection()

isc::db::DatabaseConnection::DatabaseConnection	(	const ParameterMap &	parameters,
		DbCallback	callback = DbCallback() )

inline

Constructor.

Parameters

parameters	A data structure relating keywords and values concerned with the database.
callback	The connection recovery callback.

Definition at line 144 of file database_connection.h.

◆ ~DatabaseConnection()

virtual isc::db::DatabaseConnection::~DatabaseConnection ( )

inlinevirtual

Destructor.

Definition at line 150 of file database_connection.h.

Member Function Documentation

◆ checkUnusable()

void isc::db::DatabaseConnection::checkUnusable ( )

inline

Throws an exception if the connection is not usable.

Exceptions

DbConnectionUnusable

Definition at line 265 of file database_connection.h.

References isc_throw.

Referenced by isc::db::MySqlConnection::commit(), isc::db::PgSqlConnection::commit(), isc::db::PgSqlConnection::executePreparedStatement(), isc::db::PgSqlConnection::executeSQL(), isc::db::MySqlConnection::insertQuery(), isc::db::MySqlConnection::rollback(), isc::db::PgSqlConnection::rollback(), isc::db::MySqlConnection::selectQuery(), isc::db::MySqlConnection::startTransaction(), isc::db::PgSqlConnection::startTransaction(), and isc::db::MySqlConnection::updateDeleteQuery().

◆ configuredReadOnly()

bool isc::db::DatabaseConnection::configuredReadOnly ( ) const

Convenience method checking if database should be opened with read only access.

Returns: true if "readonly" parameter is specified and set to true; false if "readonly" parameter is not specified or it is specified and set to false.

Definition at line 132 of file database_connection.cc.

References getParameter(), and isc_throw.

Here is the call graph for this function:

◆ getIOService()

static isc::asiolink::IOServicePtr & isc::db::DatabaseConnection::getIOService ( )

inlinestatic

Returns pointer to the IO service.

Definition at line 239 of file database_connection.h.

Referenced by isc::db::MySqlConnection::ensureSchemaVersion(), and isc::db::PgSqlConnection::ensureSchemaVersion().

◆ getParameter()

std::string isc::db::DatabaseConnection::getParameter ( const std::string & name ) const

Returns value of a connection parameter.

Parameters

name	Name of the parameter which value should be returned.

Returns: Value of one of the connection parameters.

Exceptions

BadValue if parameter is not found

Definition at line 30 of file database_connection.cc.

References isc_throw.

Referenced by isc::dhcp::Memfile_LeaseMgr::Memfile_LeaseMgr(), configuredReadOnly(), isc::dhcp::Memfile_LeaseMgr::getVersion(), makeReconnectCtl(), and isc::db::MySqlConnection::openDatabase().

◆ invokeDbFailedCallback()

bool isc::db::DatabaseConnection::invokeDbFailedCallback ( const util::ReconnectCtlPtr & db_reconnect_ctl )

static

Invokes the connection's restore failed connectivity callback.

Returns: Returns the result of the callback or false if there is no callback.

Definition at line 209 of file database_connection.cc.

References db_failed_callback_.

◆ invokeDbLostCallback()

bool isc::db::DatabaseConnection::invokeDbLostCallback ( const util::ReconnectCtlPtr & db_reconnect_ctl )

static

Invokes the connection's lost connectivity callback.

Returns: Returns the result of the callback or false if there is no callback.

Definition at line 191 of file database_connection.cc.

References db_lost_callback_.

◆ invokeDbRecoveredCallback()

bool isc::db::DatabaseConnection::invokeDbRecoveredCallback ( const util::ReconnectCtlPtr & db_reconnect_ctl )

static

Invokes the connection's restored connectivity callback.

Returns: Returns the result of the callback or false if there is no callback.

Definition at line 200 of file database_connection.cc.

References db_recovered_callback_.

◆ isUnusable()

bool isc::db::DatabaseConnection::isUnusable ( )

inline

Flag which indicates if connection is unusable.

Returns: true if the connection is unusable, false otherwise

Definition at line 274 of file database_connection.h.

◆ makeReconnectCtl()

void isc::db::DatabaseConnection::makeReconnectCtl ( const std::string & timer_name )

virtual

Instantiates a ReconnectCtl based on the connection's reconnect parameters.

Parameters

timer_name of the timer used for the ReconnectCtl object.

Definition at line 151 of file database_connection.cc.

References getParameter(), and isc::util::ReconnectCtl::onFailActionFromText().

Referenced by isc::db::MySqlConnection::getVersion(), and isc::db::PgSqlConnection::getVersion().

Here is the call graph for this function:

◆ markUnusable()

void isc::db::DatabaseConnection::markUnusable ( )

inlineprotected

Sets the unusable flag to true.

Definition at line 301 of file database_connection.h.

Referenced by isc::db::MySqlConnection::checkError(), and isc::db::PgSqlConnection::checkStatementError().

◆ parse()

DatabaseConnection::ParameterMap isc::db::DatabaseConnection::parse ( const std::string & dbaccess )

static

Parse database access string.

Parses the string of "keyword=value" pairs and separates them out into the map. A value of the password parameter may include whitespace in which case it must be surrounded by apostrophes.

Parameters

dbaccess Database access string.

Returns: ParameterMap of keyword/value pairs.

Definition at line 39 of file database_connection.cc.

References isc::db::DB_LOG< log_type >::arg(), isc::db::DB_INVALID_ACCESS, isc_throw, and isc::util::str::trim().

Referenced by isc::dhcp::HostDataSourceFactory::add(), isc::cb::BaseConfigBackendMgr< ConfigBackendPoolType >::addBackend(), isc::dhcp::LeaseMgrFactory::create(), isc::dhcp::CfgDbAccess::createManagers(), isc::cb::BaseConfigBackendPool< ConfigBackendType >::del(), isc::dhcp::HostDataSourceFactory::del(), isc::process::ConfigDbInfo::setAccessString(), and toElementDbAccessString().

Here is the call graph for this function:

◆ reconnectCtl()

util::ReconnectCtlPtr isc::db::DatabaseConnection::reconnectCtl ( )

inline

The reconnect settings.

Returns: The reconnect settings.

Definition at line 161 of file database_connection.h.

Referenced by isc::db::MySqlConnection::openDatabase(), isc::db::MySqlConnection::startRecoverDbConnection(), and isc::db::PgSqlConnection::startRecoverDbConnection().

◆ redactedAccessString()

std::string isc::db::DatabaseConnection::redactedAccessString ( const ParameterMap & parameters )

static

Redact database access string.

Takes the database parameters and returns a database access string passwords replaced by asterisks. This string is used in log messages.

Parameters

parameters Database access parameters (output of "parse").

Returns: Redacted database access string.

Definition at line 104 of file database_connection.cc.

Referenced by isc::dhcp::LeaseMgrFactory::create(), isc::dhcp::CfgDbAccess::createManagers(), isc::dhcp::Memfile_LeaseMgr::factory(), and isc::process::ConfigDbInfo::redactedAccessString().

◆ setIOService()

static void isc::db::DatabaseConnection::setIOService ( const isc::asiolink::IOServicePtr & io_service )

inlinestatic

Sets IO service to be used by the database backends.

Parameters

io_service IOService object, used for all ASIO operations.

Definition at line 234 of file database_connection.h.

Referenced by isc::dhcp::ControlledDhcpv4Srv::ControlledDhcpv4Srv(), isc::dhcp::ControlledDhcpv6Srv::ControlledDhcpv6Srv(), isc::dhcp::ControlledDhcpv4Srv::~ControlledDhcpv4Srv(), and isc::dhcp::ControlledDhcpv6Srv::~ControlledDhcpv6Srv().

◆ toElement()

isc::data::ElementPtr isc::db::DatabaseConnection::toElement ( const ParameterMap & params )

static

Unparse a parameter map.

Parameters

params the parameter map to unparse

Returns: a pointer to configuration

Definition at line 218 of file database_connection.cc.

References isc::data::Element::create(), isc::data::Element::createMap(), isc::db::database_logger, isc::db::DATABASE_TO_JSON_BOOLEAN_ERROR, isc::db::DATABASE_TO_JSON_INTEGER_ERROR, isc::db::DATABASE_TO_JSON_UNKNOWN_TYPE_ERROR, and LOG_ERROR.

Referenced by toElementDbAccessString().

Here is the call graph for this function:

◆ toElementDbAccessString()

isc::data::ElementPtr isc::db::DatabaseConnection::toElementDbAccessString ( const std::string & dbaccess )

static

Unparse an access string.

Parameters

dbaccess the database access string

Returns: a pointer to configuration

Definition at line 275 of file database_connection.cc.

References parse(), and toElement().

Referenced by isc::dhcp::CfgHostDbAccess::toElement(), isc::dhcp::CfgLeaseDbAccess::toElement(), and isc::process::ConfigDbInfo::toElement().

Here is the call graph for this function:

Member Data Documentation

◆ callback_

DbCallback isc::db::DatabaseConnection::callback_

protected

The callback used to recover the connection.

Definition at line 315 of file database_connection.h.

Referenced by isc::db::MySqlConnection::startRecoverDbConnection(), and isc::db::PgSqlConnection::startRecoverDbConnection().

◆ db_failed_callback_

DbCallback isc::db::DatabaseConnection::db_failed_callback_ = 0

static

Optional callback function to invoke if an opened connection recovery failed.

Definition at line 253 of file database_connection.h.

Referenced by isc::dhcp::ControlledDhcpv4Srv::~ControlledDhcpv4Srv(), isc::dhcp::ControlledDhcpv6Srv::~ControlledDhcpv6Srv(), invokeDbFailedCallback(), isc::dhcp::ControlledDhcpv4Srv::processConfig(), and isc::dhcp::ControlledDhcpv6Srv::processConfig().

◆ db_lost_callback_

DbCallback isc::db::DatabaseConnection::db_lost_callback_ = 0

static

Optional callback function to invoke if an opened connection is lost.

Definition at line 245 of file database_connection.h.

Referenced by isc::dhcp::ControlledDhcpv4Srv::~ControlledDhcpv4Srv(), isc::dhcp::ControlledDhcpv6Srv::~ControlledDhcpv6Srv(), invokeDbLostCallback(), isc::dhcp::ControlledDhcpv4Srv::processConfig(), and isc::dhcp::ControlledDhcpv6Srv::processConfig().

◆ db_recovered_callback_

DbCallback isc::db::DatabaseConnection::db_recovered_callback_ = 0

static

Optional callback function to invoke if an opened connection recovery succeeded.

Definition at line 249 of file database_connection.h.

Referenced by isc::dhcp::ControlledDhcpv4Srv::~ControlledDhcpv4Srv(), isc::dhcp::ControlledDhcpv6Srv::~ControlledDhcpv6Srv(), invokeDbRecoveredCallback(), isc::dhcp::ControlledDhcpv4Srv::processConfig(), and isc::dhcp::ControlledDhcpv6Srv::processConfig().

◆ MAX_DB_TIME

const time_t isc::db::DatabaseConnection::MAX_DB_TIME = 2147483647

static

Defines maximum value for time that can be reliably stored.

Todo: : Is this common for MySQL and Postgres? Maybe we should have specific values for each backend?

If I'm still alive I'll be too old to care. You fix it.

Definition at line 134 of file database_connection.h.

Referenced by isc::db::PsqlBindArray::addTimestamp(), isc::db::MySqlBinding::convertToDatabaseTime(), and isc::db::PgSqlExchange::convertToDatabaseTime().

◆ retry_

bool isc::db::DatabaseConnection::retry_ = false

static

Flag which indicates if the database connection should be retried on fail.

Allow the first database connection attempt to fail and start recovery. Sequential tries invoked by the dbReconnect callback should not start yet another database connection attempt.

Definition at line 261 of file database_connection.h.

Referenced by isc::db::DbConnectionInitWithRetry::DbConnectionInitWithRetry(), isc::db::DbConnectionInitWithRetry::~DbConnectionInitWithRetry(), and isc::db::MySqlConnection::openDatabase().

◆ test_mode_

bool isc::db::DatabaseConnection::test_mode_ = false

static

Test mode flag (default false).

Definition at line 279 of file database_connection.h.

Referenced by isc::db::DatabaseConnection::EnterTest::EnterTest(), isc::db::DatabaseConnection::EnterTest::~EnterTest(), isc::db::MySqlConnection::ensureSchemaVersion(), and isc::db::PgSqlConnection::ensureSchemaVersion().

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ ParameterMap

Constructor & Destructor Documentation

◆ DatabaseConnection()

◆ ~DatabaseConnection()

Member Function Documentation

◆ checkUnusable()

◆ configuredReadOnly()

◆ getIOService()

◆ getParameter()

◆ invokeDbFailedCallback()

◆ invokeDbLostCallback()

◆ invokeDbRecoveredCallback()

◆ isUnusable()

◆ makeReconnectCtl()

◆ markUnusable()

◆ parse()

◆ reconnectCtl()

◆ redactedAccessString()

◆ setIOService()

◆ toElement()

◆ toElementDbAccessString()

Member Data Documentation

◆ callback_

◆ db_failed_callback_

◆ db_lost_callback_

◆ db_recovered_callback_

◆ MAX_DB_TIME

◆ retry_

◆ test_mode_