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. More...

virtual	~PgSqlExchange ()
	Destructor. More...

Static Public Member Functions
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. More...

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

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

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

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

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

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

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

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. More...

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. More...

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. More...

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. More...

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

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

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 200 of file pgsql_exchange.h.

Constructor & Destructor Documentation

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

inline

Constructor.

Definition at line 203 of file pgsql_exchange.h.

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

inlinevirtual

Destructor.

Definition at line 206 of file pgsql_exchange.h.

Member Function Documentation

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 value

Exceptions

DbOperationError if the value cannot be fetched or is invalid.

Definition at line 231 of file pgsql_exchange.cc.

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

Here is the call graph for this function:

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 int 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 150 of file pgsql_exchange.cc.

References isc_throw.

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

static

Converts 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 121 of file pgsql_exchange.cc.

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

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 130 of file pgsql_exchange.cc.

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

Here is the call graph for this function:

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 268 of file pgsql_exchange.cc.

References isc::util::str::format(), isc::db::PgSqlResult::getCols(), isc::db::PgSqlResult::getColumnLabel(), getRawColumnValue(), and isc::db::PgSqlResult::rowCheck().

Here is the call graph for this function:

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 263 of file pgsql_exchange.cc.

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

Referenced by convertFromBytea(), getColumnValue(), getIPv6Value(), and getRawColumnValue().

Here is the call graph for this function:

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 182 of file pgsql_exchange.cc.

References getRawColumnValue().

Referenced by isc::dhcp::PgSqlHostDataSourceImpl::addStatement(), and isc::db::PgSqlConnection::getVersion().

Here is the call graph for this function:

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 188 of file pgsql_exchange.cc.

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

Here is the call graph for this function:

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 203 of file pgsql_exchange.cc.

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

Here is the call graph for this function:

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 352 of file pgsql_exchange.h.

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

Here is the call graph for this function:

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.

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 218 of file pgsql_exchange.cc.

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

Here is the call graph for this function:

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