Base class for marshalling data to and from PostgreSQL. More...

#include <pgsql_exchange.h>

Inheritance diagram for isc::db::PgSqlExchange:

Public Member Functions
	PgSqlExchange (const size_t num_columns=0)
	Constructor.

virtual	~PgSqlExchange ()
	Destructor.

Static Public Member Functions
static void	convertFromBytea (const PgSqlResult &r, const int row, const size_t col, std::vector< uint8_t > &value)
	Converts a column in a row in a result set to a binary bytes.

static void	convertFromBytea (const PgSqlResult &r, const int row, const size_t col, uint8_t *buffer, const size_t buffer_size, size_t &bytes_converted)
	Converts a column in a row in a result set to a binary bytes.

static time_t	convertFromDatabaseTime (const std::string &db_time_val)
	Converts time stamp from the database to a time_t.

static void	convertFromDatabaseTime (const std::string &db_time_val, boost::posix_time::ptime &conv_time)
	Converts time stamp from the database to a boost::posix::ptime.

static std::string	convertLocalToDatabaseTime (const time_t input_time)
	Converts local time_t value to a text representation in local time.

static std::string	convertToDatabaseTime (const time_t cltt, const uint32_t valid_lifetime)
	Converts lease expiration time to a text representation in local time.

static std::string	convertToDatabaseTime (const time_t input_time)
	Converts UTC time_t value to a text representation in local time.

static std::string	dumpRow (const PgSqlResult &r, int row)
	Diagnostic tool which dumps the Result row contents as a string.

static std::string	getColumnLabel (const PgSqlResult &r, const size_t col)
	Fetches the name of the column in a result set.

static void	getColumnValue (const PgSqlResult &r, const int row, const size_t col, bool &value)
	Fetches boolean text ('t' or 'f') as a bool.

static void	getColumnValue (const PgSqlResult &r, const int row, const size_t col, boost::posix_time::ptime &value)
	Fetches a timestamp column as a ptime.

static void	getColumnValue (const PgSqlResult &r, const int row, const size_t col, data::ElementPtr &value)
	Fetches a JSON column as an ElementPtr.

static void	getColumnValue (const PgSqlResult &r, const int row, const size_t col, std::string &value)
	Fetches text column value as a string.

template<typename T >
static void	getColumnValue (const PgSqlResult &r, const int row, const size_t col, T &value)
	Fetches a text column as the given value type.

static void	getColumnValue (const PgSqlResult &r, const int row, const size_t col, uint8_t &value)
	Fetches an integer text column as a uint8_t.

static isc::asiolink::IOAddress	getInetValue4 (const PgSqlResult &r, const int row, const size_t col)
	Converts a column in a row in a result set into IPv4 address.

static isc::asiolink::IOAddress	getInetValue6 (const PgSqlResult &r, const int row, const size_t col)
	Converts a column in a row in a result set into IPv6 address.

static isc::asiolink::IOAddress	getIPv6Value (const PgSqlResult &r, const int row, const size_t col)
	Converts a column in a row in a result set into IPv6 address.

static const char *	getRawColumnValue (const PgSqlResult &r, const int row, const size_t col)
	Gets a pointer to the raw column value in a result set row.

static isc::util::Triplet< uint32_t >	getTripletValue (const PgSqlResult &r, const int row, const size_t col)
	Fetches a uint32_t value into a Triplet using a single column value.

static isc::util::Triplet< uint32_t >	getTripletValue (const PgSqlResult &r, const int row, const size_t def_col, const size_t min_col, const size_t max_col)
	Fetches a uint32_t value into a Triplet using a three column values: default, minimum, and maximum.

static bool	isColumnNull (const PgSqlResult &r, const int row, const size_t col)
	Returns true if a column within a row is null.

Protected Attributes
std::vector< std::string >	columns_
	Stores text labels for columns, currently only used for logging and errors.

Detailed Description

Base class for marshalling data to and from PostgreSQL.

Provides the common functionality to set up binding information between application objects in the program and their representation in the database, and for retrieving column values from rows of a result set.

Definition at line 517 of file pgsql_exchange.h.

Constructor & Destructor Documentation

◆ PgSqlExchange()

isc::db::PgSqlExchange::PgSqlExchange ( const size_t num_columns = 0 )

inline

Constructor.

Definition at line 520 of file pgsql_exchange.h.

◆ ~PgSqlExchange()

virtual isc::db::PgSqlExchange::~PgSqlExchange ( )

inlinevirtual

Destructor.

Definition at line 523 of file pgsql_exchange.h.

Member Function Documentation

◆ convertFromBytea() [1/2]

void isc::db::PgSqlExchange::convertFromBytea	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col,
		std::vector< uint8_t > &	value
	)

static

Converts a column in a row in a result set to a binary bytes.

Method is used to convert columns stored as BYTEA into a vector of binary bytes, (uint8_t). It uses PQunescapeBytea to do the conversion.

Parameters

	r	the result set containing the query results
	row	the row number within the result set
	col	the column number within the row
[out]	value	vector to receive the converted bytes value

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 562 of file pgsql_exchange.cc.

References getColumnLabel(), getRawColumnValue(), and isc_throw.

Here is the call graph for this function:

◆ convertFromBytea() [2/2]

void isc::db::PgSqlExchange::convertFromBytea	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col,
		uint8_t *	buffer,
		const size_t	buffer_size,
		size_t &	bytes_converted
	)

static

Converts a column in a row in a result set to a binary bytes.

Method is used to convert columns stored as BYTEA into a buffer of binary bytes, (uint8_t). It uses PQunescapeBytea to do the conversion.

Parameters

	r	the result set containing the query results
	row	the row number within the result set
	col	the column number within the row
[out]	buffer	pre-allocated buffer to which the converted bytes will be stored.
	buffer_size	size of the output buffer
[out]	bytes_converted	number of bytes converted

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 530 of file pgsql_exchange.cc.

References getColumnLabel(), getRawColumnValue(), and isc_throw.

Referenced by isc::dhcp::PgSqlLease4Exchange::convertFromDatabase(), isc::dhcp::PgSqlLease6Exchange::convertFromDatabase(), and isc::db::PgSqlResultRowWorker::getBytes().

Here is the call graph for this function:

◆ convertFromDatabaseTime() [1/2]

time_t isc::db::PgSqlExchange::convertFromDatabaseTime ( const std::string & db_time_val )

static

Converts time stamp from the database to a time_t.

We're fetching timestamps as an integer string of seconds since the epoch. This method converts such a string to a time_t.

Parameters

db_time_val timestamp to be converted. This value is expected to be the number of seconds since the epoch expressed as base-10 integer string.

Returns: Converted timestamp as time_t value.

Definition at line 385 of file pgsql_exchange.cc.

References isc_throw.

Referenced by isc::dhcp::PgSqlLease4Exchange::convertFromDatabase(), isc::dhcp::PgSqlLease6Exchange::convertFromDatabase(), convertFromDatabaseTime(), and getColumnValue().

◆ convertFromDatabaseTime() [2/2]

void isc::db::PgSqlExchange::convertFromDatabaseTime	(	const std::string &	db_time_val,
		boost::posix_time::ptime &	conv_time
	)

static

Converts time stamp from the database to a boost::posix::ptime.

We're fetching timestamps as an integer string of seconds since the epoch. This method converts such a string to a boost::posix_time::ptime.

Parameters

	db_time_val	timestamp to be converted. This value is expected to be the number of seconds since the epoch expressed as base-10 integer string.
[out]	conv_time	resulting time as a ptime (UTC)

Definition at line 398 of file pgsql_exchange.cc.

References convertFromDatabaseTime().

Here is the call graph for this function:

◆ convertLocalToDatabaseTime()

std::string isc::db::PgSqlExchange::convertLocalToDatabaseTime ( const time_t input_time )

static

Converts local time_t value to a text representation in local time.

Parameters

input_time A time_t value representing time.

Returns: std::string containing stringified time.

Definition at line 350 of file pgsql_exchange.cc.

Referenced by isc::db::PsqlBindArray::addTimestamp().

◆ convertToDatabaseTime() [1/2]

std::string isc::db::PgSqlExchange::convertToDatabaseTime	(	const time_t	cltt,
		const uint32_t	valid_lifetime
	)

static

Converts lease expiration time to a text representation in local time.

The expiration time is calculated as a sum of the cltt (client last transmit time) and the valid lifetime.

The format of the output string is "%Y-%m-%d %H:%M:%S". Database table columns using this value should be typed as TIMESTAMP WITH TIME ZONE. For such columns PostgreSQL assumes input strings without timezones should be treated as in local time and are converted to UTC when stored. Likewise, these columns are automatically adjusted upon retrieval unless fetched via "extract(epoch from <column>))".

Unless we start using binary input, timestamp columns must be input as date/time strings.

Parameters

cltt	Client last transmit time
valid_lifetime	Valid lifetime

Returns: std::string containing the stringified time

Exceptions

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

Definition at line 365 of file pgsql_exchange.cc.

References convertToDatabaseTime(), isc_throw, and isc::db::DatabaseConnection::MAX_DB_TIME.

Here is the call graph for this function:

◆ convertToDatabaseTime() [2/2]

std::string isc::db::PgSqlExchange::convertToDatabaseTime ( const time_t input_time )

static

Converts UTC time_t value to a text representation in local time.

Parameters

input_time A time_t value representing time.

Returns: std::string containing stringified time.

Definition at line 337 of file pgsql_exchange.cc.

Referenced by convertToDatabaseTime(), isc::dhcp::PgSqlLease4Exchange::createBindForSend(), isc::dhcp::PgSqlLease6Exchange::createBindForSend(), isc::dhcp::PgSqlLeaseMgr::deleteLease(), isc::dhcp::PgSqlLeaseMgr::updateLease4(), and isc::dhcp::PgSqlLeaseMgr::updateLease6().

◆ dumpRow()

std::string isc::db::PgSqlExchange::dumpRow	(	const PgSqlResult &	r,
		int	row
	)

static

Diagnostic tool which dumps the Result row contents as a string.

Parameters

r	the result set containing the query results
row	the row number within the result set

Returns: A string depiction of the row contents.

Definition at line 631 of file pgsql_exchange.cc.

References isc::db::PgSqlResult::getCols(), isc::db::PgSqlResult::getColumnLabel(), getRawColumnValue(), isc::db::PgSqlResult::rowCheck(), and isc::db::PsqlBindArray::TEXT_FMT.

Referenced by isc::db::PgSqlResultRowWorker::dumpRow().

Here is the call graph for this function:

◆ getColumnLabel()

std::string isc::db::PgSqlExchange::getColumnLabel	(	const PgSqlResult &	r,
		const size_t	col
	)

static

Fetches the name of the column in a result set.

Returns the column name of the column from the result set. If the column index is out of range it will return the string "Unknown column:<index>". Note this is NOT from the list of columns defined in the exchange.

Parameters

r	the result set containing the query results
col	index of the column name to fetch

Returns: string containing the name of the column

Definition at line 626 of file pgsql_exchange.cc.

References isc::db::PgSqlResult::getColumnLabel().

Referenced by convertFromBytea(), getColumnValue(), getInetValue4(), getInetValue6(), getIPv6Value(), isc::dhcp::PgSqlLease6Exchange::getLeaseTypeColumnValue(), and getRawColumnValue().

Here is the call graph for this function:

◆ getColumnValue() [1/6]

void isc::db::PgSqlExchange::getColumnValue	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col,
		bool &	value
	)

static

Fetches boolean text ('t' or 'f') as a bool.

Parameters

	r	the result set containing the query results
	row	the row number within the result set
	col	the column number within the row
[out]	value	parameter to receive the converted value

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 430 of file pgsql_exchange.cc.

References getColumnLabel(), getRawColumnValue(), and isc_throw.

Here is the call graph for this function:

◆ getColumnValue() [2/6]

void isc::db::PgSqlExchange::getColumnValue	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col,
		boost::posix_time::ptime &	value
	)

static

Fetches a timestamp column as a ptime.

Parameters

	r	the result set containing the query results
	row	the row number within the result set
	col	the column number within the row
[out]	value	ptime parameter to receive the converted timestamp

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 460 of file pgsql_exchange.cc.

References convertFromDatabaseTime(), and getColumnValue().

Here is the call graph for this function:

◆ getColumnValue() [3/6]

void isc::db::PgSqlExchange::getColumnValue	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col,
		data::ElementPtr &	value
	)

static

Fetches a JSON column as an ElementPtr.

Parameters

	r	the result set containing the query results
	row	the row number within the result set
	col	the column number within the row
[out]	value	ElementPtr to receive the column data

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 468 of file pgsql_exchange.cc.

References isc::data::Element::fromJSON(), getColumnLabel(), getRawColumnValue(), and isc_throw.

Here is the call graph for this function:

◆ getColumnValue() [4/6]

void isc::db::PgSqlExchange::getColumnValue	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col,
		std::string &	value
	)

static

Fetches text column value as a string.

Parameters

	r	the result set containing the query results
	row	the row number within the result set
	col	the column number within the row
[out]	value	parameter to receive the string value

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 424 of file pgsql_exchange.cc.

References getRawColumnValue().

Here is the call graph for this function:

◆ getColumnValue() [5/6]

template<typename T >

static void isc::db::PgSqlExchange::getColumnValue	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col,
		T &	value
	)

inlinestatic

Fetches a text column as the given value type.

Uses boost::lexicalcast to convert the text column value into a value of type T.

Parameters

	r	the result set containing the query results
	row	the row number within the result set
	col	the column number within the row
[out]	value	parameter to receive the converted value

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 719 of file pgsql_exchange.h.

References getColumnLabel(), getRawColumnValue(), and isc_throw.

Here is the call graph for this function:

◆ getColumnValue() [6/6]

void isc::db::PgSqlExchange::getColumnValue	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col,
		uint8_t &	value
	)

static

Fetches an integer text column as a uint8_t.

Parameters

	r	the result set containing the query results
	row	the row number within the result set
	col	the column number within the row
[out]	value	parameter to receive the converted value

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 445 of file pgsql_exchange.cc.

References getColumnLabel(), getRawColumnValue(), and isc_throw.

Here is the call graph for this function:

◆ getInetValue4()

isc::asiolink::IOAddress isc::db::PgSqlExchange::getInetValue4	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col
	)

static

Converts a column in a row in a result set into IPv4 address.

This is used to fetch values from inet type columns.

Parameters

r	the result set containing the query results
row	the row number within the result set
col	the column number within the row

Returns: isc::asiolink::IOAddress containing the IPv4 address.

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 481 of file pgsql_exchange.cc.

References getColumnLabel(), getRawColumnValue(), isc_throw, and isc::asiolink::IOAddress::isV4().

Referenced by isc::db::PgSqlResultRowWorker::getInet4().

Here is the call graph for this function:

◆ getInetValue6()

isc::asiolink::IOAddress isc::db::PgSqlExchange::getInetValue6	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col
	)

static

Converts a column in a row in a result set into IPv6 address.

This is used to fetch values from inet type columns.

Parameters

r	the result set containing the query results
row	the row number within the result set
col	the column number within the row

Returns: isc::asiolink::IOAddress containing the IPv6 address.

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 499 of file pgsql_exchange.cc.

References getColumnLabel(), getRawColumnValue(), isc_throw, and isc::asiolink::IOAddress::isV6().

Referenced by isc::db::PgSqlResultRowWorker::getInet6().

Here is the call graph for this function:

◆ getIPv6Value()

isc::asiolink::IOAddress isc::db::PgSqlExchange::getIPv6Value	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col
	)

static

Converts a column in a row in a result set into IPv6 address.

This used for IPv6 columns stored as varchar.

Parameters

r	the result set containing the query results
row	the row number within the result set
col	the column number within the row

Returns: isc::asiolink::IOAddress containing the IPv6 address.

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 517 of file pgsql_exchange.cc.

References getColumnLabel(), getRawColumnValue(), and isc_throw.

Referenced by isc::dhcp::PgSqlLease6Exchange::convertFromDatabase().

Here is the call graph for this function:

◆ getRawColumnValue()

const char * isc::db::PgSqlExchange::getRawColumnValue	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col
	)

static

Gets a pointer to the raw column value in a result set row.

Given a result set, row, and column return a const char* pointer to the data value in the result set. The pointer is valid as long as the result set has not been freed. It may point to text or binary data depending on how query was structured. You should not attempt to free this pointer.

Parameters

r	the result set containing the query results
row	the row number within the result set
col	the column number within the row

Returns: a const char* pointer to the column's raw data

Exceptions

DbOperationError if the value cannot be fetched.

Definition at line 405 of file pgsql_exchange.cc.

References getColumnLabel(), isc_throw, and isc::db::PgSqlResult::rowColCheck().

Referenced by convertFromBytea(), isc::dhcp::PgSqlLease4Exchange::convertFromDatabase(), isc::dhcp::PgSqlLease6Exchange::convertFromDatabase(), dumpRow(), getColumnValue(), getInetValue4(), getInetValue6(), getIPv6Value(), and isc::db::PgSqlResultRowWorker::getRawColumnValue().

Here is the call graph for this function:

◆ getTripletValue() [1/2]

Triplet< uint32_t > isc::db::PgSqlExchange::getTripletValue	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col
	)

static

Fetches a uint32_t value into a Triplet using a single column value.

Parameters

r	the result set containing the query results
row	the row number within the result set
col	the column number within the row. If the column is null, the Triplet is returned as unspecified.

Returns: Triplet to receive the column value

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 590 of file pgsql_exchange.cc.

References getColumnValue(), and isColumnNull().

Referenced by isc::db::PgSqlResultRowWorker::getTriplet().

Here is the call graph for this function:

◆ getTripletValue() [2/2]

Triplet< uint32_t > isc::db::PgSqlExchange::getTripletValue	(	const PgSqlResult &	r,
		const int	row,
		const size_t	def_col,
		const size_t	min_col,
		const size_t	max_col
	)

static

Fetches a uint32_t value into a Triplet using a three column values: default, minimum, and maximum.

Parameters

r	the result set containing the query results
row	the row number within the result set
def_col	the column number within the row that contains the default value. If this column is null, the Triplet is returned as unspecified.
min_col	the column number within the row that contains the minimum value.
max_col	the column number within the row that contains the maximum value.

Returns: Triplet to receive the column value

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 602 of file pgsql_exchange.cc.

References getColumnValue(), and isColumnNull().

Here is the call graph for this function:

◆ isColumnNull()

bool isc::db::PgSqlExchange::isColumnNull	(	const PgSqlResult &	r,
		const int	row,
		const size_t	col
	)

static

Returns true if a column within a row is null.

Parameters

r	the result set containing the query results
row	the row number within the result set
col	the column number within the row

Returns: True if the column values in the row is NULL, false otherwise.

Definition at line 417 of file pgsql_exchange.cc.

References isc::db::PgSqlResult::rowColCheck().

Referenced by getTripletValue(), and isc::db::PgSqlResultRowWorker::isColumnNull().

Here is the call graph for this function:

Member Data Documentation

◆ columns_

std::vector<std::string> isc::db::PgSqlExchange::columns_

protected

Stores text labels for columns, currently only used for logging and errors.

Definition at line 839 of file pgsql_exchange.h.

Referenced by isc::dhcp::PgSqlLease4Exchange::PgSqlLease4Exchange(), and isc::dhcp::PgSqlLease6Exchange::PgSqlLease6Exchange().

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

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PgSqlExchange()

◆ ~PgSqlExchange()

Member Function Documentation

◆ convertFromBytea() [1/2]

◆ convertFromBytea() [2/2]

◆ convertFromDatabaseTime() [1/2]

◆ convertFromDatabaseTime() [2/2]

◆ convertLocalToDatabaseTime()

◆ convertToDatabaseTime() [1/2]

◆ convertToDatabaseTime() [2/2]

◆ dumpRow()

◆ getColumnLabel()

◆ getColumnValue() [1/6]

◆ getColumnValue() [2/6]

◆ getColumnValue() [3/6]

◆ getColumnValue() [4/6]

◆ getColumnValue() [5/6]

◆ getColumnValue() [6/6]

◆ getInetValue4()

◆ getInetValue6()

◆ getIPv6Value()

◆ getRawColumnValue()

◆ getTripletValue() [1/2]

◆ getTripletValue() [2/2]

◆ isColumnNull()

Member Data Documentation

◆ columns_