Common MySQL Connector Pool. More...

#include <mysql_connection.h>

Inheritance diagram for isc::db::MySqlConnection:

Public Types
typedef std::function< void(MySqlBindingCollection &)>	ConsumeResultFun
	Function invoked to process fetched row. More...

Public Types inherited from isc::db::DatabaseConnection
typedef boost::function< bool(ReconnectCtlPtr db_retry)>	DbLostCallback
	Defines a callback prototype for propogating events upward. More...

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

Public Member Functions
	MySqlConnection (const ParameterMap &parameters)
	Constructor. More...

virtual	~MySqlConnection ()
	Destructor. More...

template<typename StatementIndex >
void	checkError (const int status, const StatementIndex &index, const char *what) const
	Check Error and Throw Exception. More...

void	clearStatements ()
	Clears prepared statements and text statements. More...

void	commit ()
	Commit Transactions. More...

template<typename StatementIndex >
void	insertQuery (const StatementIndex &index, const MySqlBindingCollection &in_bindings)
	Executes INSERT prepared statement. More...

void	openDatabase ()
	Open Database. More...

void	prepareStatement (uint32_t index, const char *text)
	Prepare Single Statement. More...

void	prepareStatements (const TaggedStatement start_statement, const TaggedStatement end_statement)
	Prepare statements. More...

void	rollback ()
	Rollback Transactions. More...

template<typename StatementIndex >
void	selectQuery (const StatementIndex &index, const MySqlBindingCollection &in_bindings, MySqlBindingCollection &out_bindings, ConsumeResultFun process_result)
	Executes SELECT query using prepared statement. More...

void	startTransaction ()
	Starts Transaction. More...

template<typename StatementIndex >
uint64_t	updateDeleteQuery (const StatementIndex &index, const MySqlBindingCollection &in_bindings)
	Executes UPDATE or DELETE prepared statement and returns the number of affected rows. More...

Public Member Functions inherited from isc::db::DatabaseConnection
	DatabaseConnection (const ParameterMap &parameters)
	Constructor. More...

virtual	~DatabaseConnection ()
	Destructor. More...

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

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

bool	invokeDbLostCallback () const
	Invokes the connection's lost connectivity callback. More...

virtual ReconnectCtlPtr	makeReconnectCtl () const
	Instantiates a ReconnectCtl based on the connection's reconnect parameters. More...

Static Public Member Functions

static void	convertToDatabaseTime (const time_t input_time, MYSQL_TIME &output_time)
	Convert time_t value to database time. More...

static void	convertToDatabaseTime (const time_t cltt, const uint32_t valid_lifetime, MYSQL_TIME &expire)
	Convert Lease Time to Database Times. More...

static void	convertFromDatabaseTime (const MYSQL_TIME &expire, uint32_t valid_lifetime, time_t &cltt)
	Convert Database Time to Lease Times. More...

Static Public Member Functions inherited from isc::db::DatabaseConnection
static ParameterMap	parse (const std::string &dbaccess)
	Parse database access string. More...

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

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

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

Public Attributes
MySqlHolder	mysql_
	MySQL connection handle. More...

std::vector< MYSQL_STMT * >	statements_
	Prepared statements. More...

std::vector< std::string >	text_statements_
	Raw text of statements. More...

Additional Inherited Members
Static Public Attributes inherited from isc::db::DatabaseConnection
static DbLostCallback	db_lost_callback = 0
	Optional call back function to invoke if a successfully open connection subsequently fails. More...

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

Detailed Description

Common MySQL Connector Pool.

This class provides common operations for MySQL database connection used by both MySqlLeaseMgr and MySqlHostDataSource. It manages connecting to the database and preparing compiled statements. Its fields are public, because they are used (both set and retrieved) in classes that use instances of MySqlConnection.

Definition at line 191 of file mysql_connection.h.

Member Typedef Documentation

◆ ConsumeResultFun

typedef std::function<void(MySqlBindingCollection&)> isc::db::MySqlConnection::ConsumeResultFun

Function invoked to process fetched row.

Definition at line 195 of file mysql_connection.h.

Constructor & Destructor Documentation

◆ MySqlConnection()

isc::db::MySqlConnection::MySqlConnection ( const ParameterMap & parameters )

inline

Constructor.

Initialize MySqlConnection object with parameters needed for connection.

Definition at line 200 of file mysql_connection.h.

◆ ~MySqlConnection()

isc::db::MySqlConnection::~MySqlConnection ( )

virtual

Destructor.

Definition at line 268 of file mysql_connection.cc.

References statements_, and text_statements_.

Member Function Documentation

◆ checkError()

template<typename StatementIndex >

void isc::db::MySqlConnection::checkError	(	const int	status,
		const StatementIndex &	index,
		const char *	what
	)		const

inline

Check Error and Throw Exception.

Virtually all MySQL functions return a status which, if non-zero, indicates an error. This function centralizes the error checking code.

It is used to determine whether or not the function succeeded, and in the event of failures, decide whether or not those failures are recoverable.

If the error is recoverable, the function will throw a DbOperationError. If the error is deemed unrecoverable, such as a loss of connectivity with the server, the function will call invokeDbLostCallback(). If the invocation returns false then either there is no callback registered or the callback has elected not to attempt to reconnect, and exit(-1) is called;

If the invocation returns true, this indicates the calling layer will attempt recovery, and the function throws a DbOperationError to allow the caller to error handle the failed db access attempt.

Parameters

status	Status code: non-zero implies an error
index	Index of statement that caused the error
what	High-level description of the error

Template Parameters

Enumeration representing index of a statement to which an error pertains.

Exceptions

isc::db::DbOperationError An operation on the open database has failed.

Definition at line 529 of file mysql_connection.h.

References DB_LOG_ERROR, isc::db::DatabaseConnection::invokeDbLostCallback(), isc_throw, mysql_, isc::db::MYSQL_FATAL_ERROR, and text_statements_.

Referenced by isc::dhcp::MySqlHostDataSourceImpl::checkError(), insertQuery(), selectQuery(), and updateDeleteQuery().

Here is the call graph for this function:

◆ clearStatements()

void isc::db::MySqlConnection::clearStatements ( )

Clears prepared statements and text statements.

Definition at line 262 of file mysql_connection.cc.

References statements_, and text_statements_.

◆ commit()

void isc::db::MySqlConnection::commit ( )

Commit Transactions.

Commits all pending database operations. On databases that don't support transactions, this is a no-op.

Exceptions

DbOperationError If the commit failed.

Definition at line 324 of file mysql_connection.cc.

References isc::db::DB_DBG_TRACE_DETAIL, DB_LOG_DEBUG, isc_throw, mysql_, and isc::db::MYSQL_COMMIT.

Referenced by isc::db::MySqlTransaction::commit(), and isc::dhcp::MySqlHostDataSource::commit().

◆ convertFromDatabaseTime()

void isc::db::MySqlConnection::convertFromDatabaseTime	(	const MYSQL_TIME &	expire,
		uint32_t	valid_lifetime,
		time_t &	cltt
	)

static

Convert Database Time to Lease Times.

Within the database, time is stored as "expire" (time of expiry of the lease) and valid lifetime. In the DHCP server, the information is stored client last transmit time and valid lifetime. These are related by the equation:

client last transmit time = expire - valid_lifetime

This method converts from the times in the database into times able to be inserted into the lease object.

Parameters

expire	Reference to MYSQL_TIME object from where the expiry time of the lease is taken.
valid_lifetime	lifetime of the lease.
cltt	Reference to location where client last transmit time is put.

Definition at line 306 of file mysql_connection.cc.

References isc::db::MySqlBinding::convertFromDatabaseTime().

Here is the call graph for this function:

◆ convertToDatabaseTime() [1/2]

void isc::db::MySqlConnection::convertToDatabaseTime	(	const time_t	cltt,
		const uint32_t	valid_lifetime,
		MYSQL_TIME &	expire
	)

static

Convert Lease Time to Database Times.

Within the DHCP servers, times are stored as client last transmit time and valid lifetime. In the database, the information is stored as valid lifetime and "expire" (time of expiry of the lease). They are related by the equation:

expire = client last transmit time + valid lifetime

This method converts from the times in the lease object into times able to be added to the database.

Parameters

cltt	Client last transmit time
valid_lifetime	Valid lifetime
expire	Reference to MYSQL_TIME object where the expiry time of the lease will be put.

Exceptions

isc::BadValue if the sum of the calculated expiration time is greater than the value of LeaseMgr::MAX_DB_TIME.

Definition at line 299 of file mysql_connection.cc.

References isc::db::MySqlBinding::convertToDatabaseTime().

Here is the call graph for this function:

◆ convertToDatabaseTime() [2/2]

void isc::db::MySqlConnection::convertToDatabaseTime	(	const time_t	input_time,
		MYSQL_TIME &	output_time
	)

static

Convert time_t value to database time.

The following methods are used to convert between times and time intervals stored in the Lease object, and the times stored in the database. The reason for the difference is because in the DHCP server, the cltt (Client Time Since Last Transmission) is the natural data; in the lease file - which may be read by the user - it is the expiry time of the lease.

Parameters

input_time	A time_t value representing time.
output_time	Reference to MYSQL_TIME object where converted time will be put.

Definition at line 293 of file mysql_connection.cc.

References isc::db::MySqlBinding::convertToDatabaseTime().

Here is the call graph for this function:

◆ insertQuery()

template<typename StatementIndex >

void isc::db::MySqlConnection::insertQuery	(	const StatementIndex &	index,
		const MySqlBindingCollection &	in_bindings
	)

inline

Executes INSERT prepared statement.

The statement index must point to an existing prepared statement associated with the connection. The in_bindings size must match the number of placeholders in the prepared statement.

This method executes prepared statement using provided bindings to insert data into the database.

Template Parameters

StatementIndex Type of the statement index enum.

Parameters

index	Index of the query to be executed.
in_bindings	Input bindings holding values to substitue placeholders in the query.

Definition at line 421 of file mysql_connection.h.

References checkError(), isc_throw, mysql_, and statements_.

Here is the call graph for this function:

◆ openDatabase()

void isc::db::MySqlConnection::openDatabase ( )

Open Database.

Opens the database using the information supplied in the parameters passed to the constructor.

Exceptions

NoDatabaseName	Mandatory database name not given
DbOpenError	Error opening the database

Definition at line 52 of file mysql_connection.cc.

References isc::db::DatabaseConnection::getParameter(), isc_throw, isc::db::MLM_FALSE, mysql_, and isc::db::MYSQL_DEFAULT_CONNECTION_TIMEOUT.

Referenced by isc::dhcp::MySqlHostDataSourceImpl::MySqlHostDataSourceImpl(), and isc::dhcp::MySqlLeaseMgr::MySqlLeaseMgr().

Here is the call graph for this function:

◆ prepareStatement()

void isc::db::MySqlConnection::prepareStatement	(	uint32_t	index,
		const char *	text
	)

Prepare Single Statement.

Creates a prepared statement from the text given and adds it to the statements_ vector at the given index.

Parameters

index	Index into the statements_ vector into which the text should be placed. The vector must be big enough for the index to be valid, else an exception will be thrown.
text	Text of the SQL statement to be prepared.

Exceptions

isc::db::DbOperationError	An operation on the open database has failed.
isc::InvalidParameter	'index' is not valid for the vector.

Definition at line 222 of file mysql_connection.cc.

References isc_throw, mysql_, statements_, and text_statements_.

Referenced by prepareStatements().

◆ prepareStatements()

void isc::db::MySqlConnection::prepareStatements	(	const TaggedStatement *	start_statement,
		const TaggedStatement *	end_statement
	)

Prepare statements.

Creates the prepared statements for all of the SQL statements used by the MySQL backend.

Parameters

start_statement	Pointer to the first statement in range of the statements to be compiled.
end_statement	Pointer to the statement marking end of the range of statements to be compiled. This last statement is not compiled.

Exceptions

isc::db::DbOperationError	An operation on the open database has failed.
isc::InvalidParameter	'index' is not valid for the vector. This represents an internal error within the code.

Definition at line 247 of file mysql_connection.cc.

References prepareStatement(), statements_, and text_statements_.

Referenced by isc::dhcp::MySqlHostDataSourceImpl::MySqlHostDataSourceImpl(), and isc::dhcp::MySqlLeaseMgr::MySqlLeaseMgr().

Here is the call graph for this function:

◆ rollback()

void isc::db::MySqlConnection::rollback ( )

Rollback Transactions.

Rolls back all pending database operations. On databases that don't support transactions, this is a no-op.

Exceptions

DbOperationError If the rollback failed.

Definition at line 333 of file mysql_connection.cc.

References isc::db::DB_DBG_TRACE_DETAIL, DB_LOG_DEBUG, isc_throw, mysql_, and isc::db::MYSQL_ROLLBACK.

Referenced by isc::dhcp::MySqlHostDataSource::rollback(), and isc::db::MySqlTransaction::~MySqlTransaction().

◆ selectQuery()

template<typename StatementIndex >

void isc::db::MySqlConnection::selectQuery	(	const StatementIndex &	index,
		const MySqlBindingCollection &	in_bindings,
		MySqlBindingCollection &	out_bindings,
		ConsumeResultFun	process_result
	)

inline

Executes SELECT query using prepared statement.

The statement index must point to an existing prepared statement associated with the connection. The in_bindings size must match the number of placeholders in the prepared statement. The size of the out_bindings must match the number of selected columns. The output bindings must be created and must encapsulate values of the appropriate type, e.g. string, uint32_t etc.

This method executes prepared statement using provided bindings and calls process_result function for each returned row. The process_result function is implemented by the caller and should gather and store each returned row in an external data structure prior to returning because the values in the out_bindings will be overwritten by the values of the next returned row when this function is called again.

Template Parameters

StatementIndex Type of the statement index enum.

Parameters

	index	Index of the query to be executed.
	in_bindings	Input bindings holding values to substitue placeholders in the query.
[out]	out_bindings	Output bindings where retrieved data will be stored.
	process_result	Pointer to the function to be invoked for each retrieved row. This function consumes the retrieved data from the output bindings.

Definition at line 343 of file mysql_connection.h.

References checkError(), isc_throw, isc::db::MLM_MYSQL_FETCH_FAILURE, isc::db::MLM_MYSQL_FETCH_SUCCESS, statements_, text_statements_, and isc::Exception::what().

Here is the call graph for this function:

◆ startTransaction()

void isc::db::MySqlConnection::startTransaction ( )

Starts Transaction.

Definition at line 312 of file mysql_connection.cc.

References isc::db::DB_DBG_TRACE_DETAIL, DB_LOG_DEBUG, isc_throw, mysql_, and isc::db::MYSQL_START_TRANSACTION.

Referenced by isc::db::MySqlTransaction::MySqlTransaction().

◆ updateDeleteQuery()

template<typename StatementIndex >

uint64_t isc::db::MySqlConnection::updateDeleteQuery	(	const StatementIndex &	index,
		const MySqlBindingCollection &	in_bindings
	)

inline

Executes UPDATE or DELETE prepared statement and returns the number of affected rows.

The statement index must point to an existing prepared statement associated with the connection. The in_bindings size must match the number of placeholders in the prepared statement.

Template Parameters

StatementIndex Type of the statement index enum.

Parameters

index	Index of the query to be executed.
in_bindings	Input bindings holding values to substitue placeholders in the query.

Returns: Number of affected rows.

Definition at line 459 of file mysql_connection.h.

References checkError(), and statements_.

Here is the call graph for this function:

Member Data Documentation

◆ mysql_

MySqlHolder isc::db::MySqlConnection::mysql_

MySQL connection handle.

This field is public, because it is used heavily from MySqlConnection and will be from MySqlHostDataSource.

Definition at line 586 of file mysql_connection.h.

Referenced by isc::dhcp::MySqlHostDataSource::add(), isc::dhcp::MySqlHostDataSourceImpl::addStatement(), checkError(), commit(), isc::dhcp::MySqlLeaseMgr::commit(), isc::dhcp::MySqlLeaseMgr::getVersion(), isc::dhcp::MySqlHostDataSourceImpl::getVersion(), insertQuery(), isc::dhcp::MySqlHostDataSourceImpl::MySqlHostDataSourceImpl(), isc::dhcp::MySqlLeaseMgr::MySqlLeaseMgr(), openDatabase(), prepareStatement(), rollback(), isc::dhcp::MySqlLeaseMgr::rollback(), and startTransaction().

◆ statements_

std::vector<MYSQL_STMT*> isc::db::MySqlConnection::statements_

Prepared statements.

This field is public, because it is used heavily from MySqlConnection and will be from MySqlHostDataSource.

Definition at line 574 of file mysql_connection.h.

Referenced by isc::dhcp::MySqlHostDataSourceImpl::addStatement(), clearStatements(), isc::dhcp::MySqlHostDataSourceImpl::delStatement(), isc::dhcp::MySqlHostDataSourceImpl::getHostCollection(), insertQuery(), prepareStatement(), prepareStatements(), selectQuery(), updateDeleteQuery(), ~MySqlConnection(), and isc::dhcp::MySqlHostDataSourceImpl::~MySqlHostDataSourceImpl().

◆ text_statements_

std::vector<std::string> isc::db::MySqlConnection::text_statements_

Raw text of statements.

This field is public, because it is used heavily from MySqlConnection and will be from MySqlHostDataSource.

Definition at line 580 of file mysql_connection.h.

Referenced by checkError(), clearStatements(), isc::dhcp::MySqlHostDataSourceImpl::getHostCollection(), prepareStatement(), prepareStatements(), selectQuery(), and ~MySqlConnection().

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

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ConsumeResultFun

Constructor & Destructor Documentation

◆ MySqlConnection()

◆ ~MySqlConnection()

Member Function Documentation

◆ checkError()

◆ clearStatements()

◆ commit()

◆ convertFromDatabaseTime()

◆ convertToDatabaseTime() [1/2]

◆ convertToDatabaseTime() [2/2]

◆ insertQuery()

◆ openDatabase()

◆ prepareStatement()

◆ prepareStatements()

◆ rollback()

◆ selectQuery()

◆ startTransaction()

◆ updateDeleteQuery()

Member Data Documentation

◆ mysql_

◆ statements_

◆ text_statements_