Kea  2.3.5-git
isc::db::PgSqlExchange Class Reference

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 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. More...
 
static time_t convertFromDatabaseTime (const std::string &db_time_val)
 Converts time stamp from the database to a time_t. More...
 
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. More...
 
static std::string convertLocalToDatabaseTime (const time_t input_time)
 Converts local time_t value to a text representation in local time. More...
 
static std::string convertToDatabaseTime (const time_t input_time)
 Converts UTC 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 void getColumnValue (const PgSqlResult &r, const int row, const size_t col, boost::posix_time::ptime &value)
 Fetches a timestamp column as a ptime. More...
 
static void getColumnValue (const PgSqlResult &r, const int row, const size_t col, data::ElementPtr &value)
 Fetches a JSON column as an ElementPtr. More...
 
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. More...
 
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. 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 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. More...
 
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. 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 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.

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

+ Here is the call graph for this function:

Member Function Documentation

◆ convertFromBytea() [1/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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
[out]bufferpre-allocated buffer to which the converted bytes will be stored.
buffer_sizesize of the output buffer
[out]bytes_convertednumber of bytes converted
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 530 of file pgsql_exchange.cc.

References isc_throw.

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

◆ convertFromBytea() [2/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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
[out]valuevector to receive the converted bytes value
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 562 of file pgsql_exchange.cc.

References isc_throw.

◆ 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_valtimestamp 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.

◆ 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_valtimestamp to be converted. This value is expected to be the number of seconds since the epoch expressed as base-10 integer string.
[out]conv_timeresulting time as a ptime (UTC)

Definition at line 398 of file pgsql_exchange.cc.

◆ 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_timeA time_t value representing time.
Returns
std::string containing stringified time.

Definition at line 350 of file pgsql_exchange.cc.

◆ convertToDatabaseTime() [1/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_timeA time_t value representing time.
Returns
std::string containing stringified time.

Definition at line 337 of file pgsql_exchange.cc.

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

◆ convertToDatabaseTime() [2/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
clttClient last transmit time
valid_lifetimeValid lifetime
Returns
std::string containing the stringified time
Exceptions
isc::BadValueif 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 isc_throw.

◆ 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
rthe result set containing the query results
rowthe 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::util::str::format(), isc::db::PgSqlResult::getCols(), isc::db::PgSqlResult::getColumnLabel(), and isc::db::PgSqlResult::rowCheck().

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
rthe result set containing the query results
colindex 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().

+ 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,
std::string &  value 
)
static

Fetches text column value as a string.

Parameters
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
[out]valueparameter to receive the string value
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 424 of file pgsql_exchange.cc.

Referenced by isc::dhcp::PgSqlHostDataSourceImpl::addStatement(), isc::dhcp::PgSqlLeaseMgr::deleteExpiredReclaimedLeases6(), isc::db::PgSqlResultRowWorker::getBigInt(), isc::db::PgSqlResultRowWorker::getBool(), isc::db::PgSqlResultRowWorker::getColumnValue(), isc::db::PgSqlResultRowWorker::getDouble(), isc::db::PgSqlResultRowWorker::getInt(), isc::db::PgSqlResultRowWorker::getSmallInt(), isc::db::PgSqlResultRowWorker::getString(), and isc::db::PgSqlConnection::getVersion().

◆ getColumnValue() [2/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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
[out]valueparameter to receive the converted value
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 430 of file pgsql_exchange.cc.

References isc_throw.

◆ getColumnValue() [3/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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
[out]valueparameter to receive the converted value
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 445 of file pgsql_exchange.cc.

References isc_throw, and isc::Exception::what().

+ Here is the call graph for this function:

◆ getColumnValue() [4/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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
[out]valueparameter to receive the converted value
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 719 of file pgsql_exchange.h.

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

+ Here is the call graph for this function:

◆ getColumnValue() [5/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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
[out]valueptime parameter to receive the converted timestamp
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 460 of file pgsql_exchange.cc.

◆ getColumnValue() [6/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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
[out]valueElementPtr to receive the column data
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 468 of file pgsql_exchange.cc.

References isc_throw, and isc::Exception::what().

+ 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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
Returns
isc::asiolink::IOAddress containing the IPv4 address.
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 481 of file pgsql_exchange.cc.

References isc_throw, isc::asiolink::IOAddress::isV4(), and isc::Exception::what().

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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
Returns
isc::asiolink::IOAddress containing the IPv6 address.
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 499 of file pgsql_exchange.cc.

References isc_throw, isc::asiolink::IOAddress::isV6(), and isc::Exception::what().

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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
Returns
isc::asiolink::IOAddress containing the IPv6 address.
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 517 of file pgsql_exchange.cc.

References isc_throw, and isc::Exception::what().

+ 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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row
Returns
a const char* pointer to the column's raw data
Exceptions
DbOperationErrorif the value cannot be fetched.

Definition at line 405 of file pgsql_exchange.cc.

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

Referenced by 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
rthe result set containing the query results
rowthe row number within the result set
colthe column number within the row. If the column is null, the Triplet is returned as unspecified.
Returns
Triplet to receive the column value
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 590 of file pgsql_exchange.cc.

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

◆ 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
rthe result set containing the query results
rowthe row number within the result set
def_colthe column number within the row that contains the default value. If this column is null, the Triplet is returned as unspecified.
min_colthe column number within the row that contains the minimum value.
max_colthe column number within the row that contains the maximum value.
Returns
Triplet to receive the column value
Exceptions
DbOperationErrorif the value cannot be fetched or is invalid.

Definition at line 602 of file pgsql_exchange.cc.

◆ 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
rthe result set containing the query results
rowthe row number within the result set
colthe 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 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.


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