pqxx Namespace Reference

The home of all libpqxx classes, functions, templates, etc. More...

Classes
class	pqxx::binarystring
	Reveals "unescaped" version of PostgreSQL bytea string. More...
class	pqxx::cachedresult
class	pqxx::connection
	Connection class; represents an immediate connection to a database. More...
class	pqxx::lazyconnection
	Lazy connection class; represents a deferred connection to a database. More...
class	pqxx::asyncconnection
	Asynchronous connection class; connects "in the background". More...
class	pqxx::nullconnection
	Nonfunctional, always-null connection class for debugging purposes. More...
struct	pqxx::noticer
	Base class for user-definable error/warning message processor. More...
class	pqxx::connection_base
	connection_base abstract base class; represents a connection to a database. More...
class	pqxx::Cursor
	SQL cursor class. More...
struct	pqxx::Cursor::unknown_position
	Exception thrown when cursor position is requested, but is unknown. More...
class	pqxx::cursor_base
	Common definitions for cursor types. More...
class	pqxx::icursorstream
	Simple read-only cursor represented as a stream of results. More...
class	pqxx::icursor_iterator
	Approximate istream_iterator for icursorstream. More...
class	pqxx::dbtransaction
	Abstract base class responsible for bracketing a backend transaction. More...
class	pqxx::broken_connection
	Exception class for lost backend connection. More...
class	pqxx::sql_error
	Exception class for failed queries. More...
class	pqxx::in_doubt_error
	"Help, I don't know whether transaction was committed successfully!" More...
struct	pqxx::isolation_traits< LEVEL >
	Traits class to describe an isolation level; primarly for libpqxx's own use. More...
class	pqxx::largeobject
	Identity of a large object. More...
class	pqxx::largeobjectaccess
	Accessor for large object's contents. More...
class	pqxx::largeobject_streambuf< CHAR, TRAITS >
	Streambuf to use large objects in standard I/O streams. More...
class	pqxx::basic_ilostream< CHAR, TRAITS >
	Input stream that gets its data from a large object. More...
class	pqxx::basic_olostream< CHAR, TRAITS >
	Output stream that writes data back to a large object. More...
class	pqxx::basic_lostream< CHAR, TRAITS >
	Stream that reads and writes a large object. More...
class	pqxx::nontransaction
	Simple "transaction" class offering no transactional integrity. More...
class	pqxx::pipeline
	Processes several queries in FIFO manner, optimized for high throughput. More...
class	pqxx::pipeline::Query
class	pqxx::result
	Query or command result set. More...
class	pqxx::result::tuple
	Reference to one row in a result. More...
class	pqxx::result::field
	Reference to a field in a result set. More...
class	pqxx::result::const_iterator
	Iterator for rows (tuples) in a query result set. More...
class	pqxx::result::const_reverse_iterator
class	pqxx::result::const_fielditerator
class	pqxx::result::const_reverse_fielditerator
class	pqxx::field_streambuf< CHAR, TRAITS >
class	pqxx::basic_fieldstream< CHAR, TRAITS >
	Input stream that gets its data from a result field. More...
class	pqxx::basic_robusttransaction
class	pqxx::robusttransaction< ISOLATIONLEVEL >
	Slightly slower, better-fortified version of transaction. More...
class	pqxx::tablereader
	Efficiently pull data directly out of a table. More...
class	pqxx::tablestream
	Base class for streaming data to/from database tables. More...
class	pqxx::tablewriter
	Efficiently write data directly to a database table. More...
class	pqxx::basic_transaction
class	pqxx::transaction< ISOLATIONLEVEL >
	Standard back-end transaction, templatized on isolation level. More...
class	pqxx::transaction_base
	Interface definition (and common code) for "transaction" classes. More...
class	pqxx::transactor< TRANSACTION >
	Wrapper for transactions that automatically restarts them on failure. More...
class	pqxx::trigger
	"Observer" base class for trigger notifications. More...
class	pqxx::items< T, CONT >
	Container of items with easy contents initialization and string rendering. More...
Typedefs
typedef cachedresult	CachedResult
typedef connection	Connection
typedef lazyconnection	LazyConnection
typedef connection_base	ConnectionItf
typedef largeobject	LargeObject
typedef largeobjectaccess	LargeObjectAccess
typedef basic_ilostream< char >	ilostream
typedef basic_olostream< char >	olostream
typedef basic_lostream< char >	lostream
typedef nontransaction	NonTransaction
typedef binarystring	BinaryString
typedef result	Result
typedef basic_fieldstream< char >	fieldstream
typedef robusttransaction< read_committed >	RobustTransaction
typedef tablereader	TableReader
typedef tablestream	TableStream
typedef tablewriter	TableWriter
typedef transaction< read_committed >	Transaction
typedef transaction	work
	Bog-standard, default transaction type.
typedef transaction_base	TransactionItf
typedef transactor< transaction< read_committed > >	Transactor
typedef trigger	Trigger
typedef PQXXPQ::Oid	oid
	PostgreSQL row identifier type.
Enumerations
enum	isolation_level { read_committed, serializable }
	Transaction isolation levels; PostgreSQL doesn't implement all SQL levels. More...
Functions
PGSTD::string PQXX_LIBEXPORT	escape_binary (const PGSTD::string &bin)
	Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT	escape_binary (const char bin[])
	Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT	escape_binary (const char bin[], size_t len)
	Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT	escape_binary (const unsigned char bin[])
	Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT	escape_binary (const unsigned char bin[], size_t len)
	Escape binary string for inclusion in SQL.
template<typename STREAM>
STREAM &	operator<< (STREAM &S, const pqxx::result::field &F)
	Write a result field to any type of stream.
template<typename T>
void	from_string (const result::field &F, T &Obj)
	Convert a field's string contents to another type.
template<>
PGSTD::string	to_string (const result::field &Obj)
	Convert a field to a string.
result::const_iterator	operator+ (result::const_iterator::difference_type o, result::const_iterator i)
result::const_reverse_iterator	operator+ (result::const_reverse_iterator::difference_type n, const result::const_reverse_iterator &i)
result::const_fielditerator	operator+ (result::const_fielditerator::difference_type o, result::const_fielditerator i)
template<typename T>
void	error_unsupported_type_in_string_conversion (T)
	Dummy name, used by libpqxx in deliberate link errors.
template<typename T>
PGSTD::string	error_ambiguous_string_conversion (T)
	Dummy name, used to generate meaningful link errors.
template<typename T>
void	from_string (const char Str[], T &Obj)
	Attempt to convert postgres-generated string to given built-in type.
template<>
void	from_string (const char Str[], long &)
template<>
void	from_string (const char Str[], unsigned long &)
template<>
void	from_string (const char Str[], int &)
template<>
void	from_string (const char Str[], unsigned int &)
template<>
void	from_string (const char Str[], short &)
template<>
void	from_string (const char Str[], unsigned short &)
template<>
void	from_string (const char Str[], float &)
template<>
void	from_string (const char Str[], double &)
template<>
void	from_string (const char Str[], bool &)
template<>
void	from_string (const char Str[], PGSTD::string &Obj)
template<>
void	from_string (const char Str[], PGSTD::stringstream &Obj)
template<typename T>
void	from_string (const PGSTD::string &Str, T &Obj)
template<typename T>
void	from_string (const PGSTD::stringstream &Str, T &Obj)
template<>
void	from_string (const PGSTD::string &Str, PGSTD::string &Obj)
template<>
void	from_string (const PGSTD::string &, const char &Obj)
template<>
void	from_string (const PGSTD::string &, const signed char &Obj)
template<>
void	from_string (const PGSTD::string &, const unsigned char &Obj)
template<typename T>
PGSTD::string	to_string (const T &)
	Convert built-in type to a readable string that PostgreSQL will understand.
template<>
PGSTD::string	to_string (const short &)
template<>
PGSTD::string	to_string (const unsigned short &)
template<>
PGSTD::string	to_string (const int &)
template<>
PGSTD::string	to_string (const unsigned int &)
template<>
PGSTD::string	to_string (const long &)
template<>
PGSTD::string	to_string (const unsigned long &)
template<>
PGSTD::string	to_string (const float &)
template<>
PGSTD::string	to_string (const double &)
template<>
PGSTD::string	to_string (const bool &)
PGSTD::string	to_string (const char Obj[])
PGSTD::string	to_string (const PGSTD::stringstream &Obj)
PGSTD::string	to_string (const PGSTD::string &Obj)
template<>
PGSTD::string	to_string (const char &)
template<>
PGSTD::string	to_string (const signed char &Obj)
template<>
PGSTD::string	to_string (const unsigned char &Obj)
template<typename ITER>
PGSTD::string	separated_list (const PGSTD::string &sep, ITER begin, ITER end)
	Render items list as a string, using given separator between items.
template<typename CONTAINER>
PGSTD::string	separated_list (const PGSTD::string &sep, const CONTAINER &c)
	Render items in a container as a string, using given separator.
template<typename T>
PGSTD::string	ToString (const T &Obj)
	Convert object of built-in type to string.
template<>
PGSTD::string	ToString (const PGSTD::string &Obj)
template<>
PGSTD::string	ToString (const char *const &Obj)
template<>
PGSTD::string	ToString (char *const &Obj)
template<>
PGSTD::string	ToString (const unsigned char *const &Obj)
template<>
PGSTD::string	ToString (const bool &Obj)
template<>
PGSTD::string	ToString (const short &Obj)
template<>
PGSTD::string	ToString (const unsigned short &Obj)
template<typename T>
void	FromString (const char Str[], T &Obj)
	Convert string to object of built-in type.
template<>
void	FromString (const char Str[], PGSTD::string &Obj)
template<>
void	FromString (const char Str[], const char *&Obj)
template<>
void	FromString (const char Str[], const unsigned char *&Obj)
template<>
void	FromString (const char Str[], bool &Obj)
PGSTD::string	sqlesc (const char str[])
	Escape nul-terminated string for inclusion in SQL strings.
PGSTD::string	sqlesc (const char str[], size_t maxlen)
	Escape string for inclusion in SQL strings.
PGSTD::string	sqlesc (const PGSTD::string &)
	Escape string for inclusion in SQL strings.
template<typename T>
PGSTD::string	Quote (const T &Obj, bool EmptyIsNull)
	Quote string for use in SQL.
template<>
PGSTD::string	Quote (const PGSTD::string &Obj, bool EmptyIsNull)
	std::string version, on which the other versions are built
template<>
PGSTD::string	Quote (const char *const &Obj, bool EmptyIsNull)
	Special case for const char *, accepting null pointer as null value.
template<int LEN>
PGSTD::string	Quote (const char(&Obj)[LEN], bool EmptyIsNull)
	Specialization for string constants.
template<typename T>
PGSTD::string	Quote (T Obj)
	Quote string for use in SQL.
Variables
const oid	oid_none = 0
	The "null" oid.

---

Detailed Description

The home of all libpqxx classes, functions, templates, etc.

---

Typedef Documentation

typedef binarystring pqxx::BinaryString

Deprecated: For compatibility with old BinaryString class

typedef cachedresult pqxx::CachedResult

Deprecated: For compatibility with the old CachedResult class

typedef connection pqxx::Connection

Deprecated: For compatibility with old Connection class

typedef connection_base pqxx::ConnectionItf

What is now connection_base used to be called ConnectionItf. This was changed to convey its role in a way more consistent with the C++ standard library.

typedef basic_fieldstream<char> pqxx::fieldstream

typedef basic_ilostream<char> pqxx::ilostream

typedef largeobject pqxx::LargeObject

Deprecated: For compatibility with old LargeObject class

typedef largeobjectaccess pqxx::LargeObjectAccess

Deprecated: For compatibility with old LargeObjectAccess class

typedef lazyconnection pqxx::LazyConnection

Deprecated: For compatibility with old LazyConnection class

typedef basic_lostream<char> pqxx::lostream

typedef nontransaction pqxx::NonTransaction

Deprecated: For compatibility with the old NonTransaction class

typedef PQXXPQ::Oid pqxx::oid

PostgreSQL row identifier type.

typedef basic_olostream<char> pqxx::olostream

typedef result pqxx::Result

Deprecated: For compatibility with old Result class

typedef robusttransaction<read_committed> pqxx::RobustTransaction

Deprecated: For compatibility with old RobustTransaction class

typedef tablereader pqxx::TableReader

Deprecated: For compatibility with the old TableReader class

typedef tablestream pqxx::TableStream

Deprecated: For compatibility with the old TableStream class

typedef tablewriter pqxx::TableWriter

Deprecated: For compatibility with the old TableWriter class

typedef transaction<read_committed> pqxx::Transaction

Deprecated: Compatibility with the old Transaction class

typedef transaction_base pqxx::TransactionItf

What is now transaction_base used to be called TransactionItf. This was changed to convey its role in a way more consistent with the C++ standard library.

typedef transactor<transaction<read_committed> > pqxx::Transactor

Deprecated: For compatibility with the old Transactor class

typedef trigger pqxx::Trigger

Deprecated: For compatibility with the old Trigger class

typedef transaction pqxx::work

Bog-standard, default transaction type.

---

Enumeration Type Documentation

enum isolation_level

Transaction isolation levels; PostgreSQL doesn't implement all SQL levels. The only levels implemented in postgres are read_committed and serializable; SQL also defines read_uncommitted and repeatable_read. Unless you're bent on using nasty tricks to communicate between ongoing transactions and such, you won't really need isolation levels for anything except performance optimization. In that case, you can safely emulate read_uncommitted by using read_committed and repeatable_read by using serializable. In general, serializable is the safest choice. Enumeration values: read_committed  serializable

---

Function Documentation

template<typename T> PGSTD::string error_ambiguous_string_conversion (  T   )

Dummy name, used to generate meaningful link errors. If you get a link error naming this function, this means that your program includes a string conversion involving a signed or unsigned char type. The problem with such conversions is that they are ambiguous: do you want to treat the char type as a small numeric type, or as a character type like plain char?

template<typename T> void error_unsupported_type_in_string_conversion (  T   )

Dummy name, used by libpqxx in deliberate link errors. If you get an error involving this function while building your program, this means that the program contains an unsupported string conversion. In other words, the program tries to convert an object to a string, or a string to an object, of a type for which libpqxx does not implement this conversion. A notable example is "long long," which is supported by many compilers but does not exist in Standard C++. In the case of "long long" and similar types, if your implementation of the standard C++ library supports it, you may use a stringstream to perform the conversion. For other types, you may have to write the conversion routine yourself.

string pqxx::escape_binary (  const unsigned char  bin[], size_t  len )

Escape binary string for inclusion in SQL.

string pqxx::escape_binary (  const unsigned char  bin[]  )

Escape binary string for inclusion in SQL.

string pqxx::escape_binary (  const char  bin[], size_t  len )

Escape binary string for inclusion in SQL.

string pqxx::escape_binary (  const char  bin[]  )

Escape binary string for inclusion in SQL.

string pqxx::escape_binary (  const PGSTD::string &  bin  )

Escape binary string for inclusion in SQL.

template<> void from_string (  const PGSTD::string &  , const unsigned char &  Obj )

template<> void from_string (  const PGSTD::string &  , const signed char &  Obj )

template<> void from_string (  const PGSTD::string &  , const char &  Obj )

template<> void from_string (  const PGSTD::string &  Str, PGSTD::string &  Obj )

template<typename T> void from_string (  const PGSTD::stringstream &  Str, T &  Obj )

template<typename T> void from_string (  const PGSTD::string &  Str, T &  Obj )

template<> void from_string (  const char  Str[], PGSTD::stringstream &  Obj )

template<> void from_string (  const char  Str[], PGSTD::string &  Obj )

template<> void pqxx::from_string (  const char  Str[], bool &  )

template<> void pqxx::from_string (  const char  Str[], double &  )

template<> void pqxx::from_string (  const char  Str[], float &  )

template<> void pqxx::from_string (  const char  Str[], unsigned short &  )

template<> void pqxx::from_string (  const char  Str[], short &  )

template<> void pqxx::from_string (  const char  Str[], unsigned int &  )

template<> void pqxx::from_string (  const char  Str[], int &  )

template<> void pqxx::from_string (  const char  Str[], unsigned long &  )

template<> void pqxx::from_string (  const char  Str[], long &  )

template<typename T> void from_string (  const char  Str[], T &  Obj )

Attempt to convert postgres-generated string to given built-in type. If the form of the value found in the string does not match the expected type, e.g. if a decimal point is found when converting to an integer type, the conversion fails. Overflows (e.g. converting "9999999999" to a 16-bit C++ type) are also treated as errors. Only the simplest possible conversions are supported. No fancy features such as hexadecimal or octal, spurious signs, or exponent notation will work. No whitespace is stripped away. Only the kinds of strings that come out of PostgreSQL and out of to_string() can be converted.

template<typename T> void from_string (  const result::field &  F, T &  Obj )

Convert a field's string contents to another type.

template<> void FromString (  const char  Str[], bool &  Obj )

template<> void FromString (  const char  Str[], const unsigned char *&  Obj )

template<> void FromString (  const char  Str[], const char *&  Obj )

template<> void FromString (  const char  Str[], PGSTD::string &  Obj )

template<typename T> void FromString (  const char  Str[], T &  Obj )

Convert string to object of built-in type. Deprecated: Use the stricter, safer from_string instead. Warning: The conversion is done using the currently active locale, whereas PostgreSQL delivers values in the "default" (C) locale. This means that if you intend to use this function from a locale that doesn't understand the data types in question (particularly numeric types like float and int) in default C format, you'll need to switch back to the C locale before the call. This problem does not exist with the newer from_string function template.

result::const_fielditerator operator+ (  result::const_fielditerator::difference_type  o, result::const_fielditerator  i )

result::const_reverse_iterator operator+ (  result::const_reverse_iterator::difference_type  n, const result::const_reverse_iterator &  i )

result::const_iterator operator+ (  result::const_iterator::difference_type  o, result::const_iterator  i )

template<typename STREAM> STREAM& operator<< (  STREAM &  S, const pqxx::result::field &  F )

Write a result field to any type of stream. This can be convenient when writing a field to an output stream. More importantly, it lets you write a field to e.g. a stringstream which you can then use to read, format and convert the field in ways that to() does not support. Example: parse a field into a variable of the nonstandard "long long" type. extern result R; long long L; stringstream S; // Write field's string into S S << R[0][0]; // Parse contents of S into L S >> L;

template<typename T> PGSTD::string Quote (  T  Obj  )

Quote string for use in SQL. This version of the function never generates null values. Deprecated: Use sqlesc instead.

template<int LEN> PGSTD::string Quote (  const char &  Obj[LEN], bool  EmptyIsNull )

Specialization for string constants. This specialization is a little complicated, because string constants are of the type char[], not of type const char * as one might expect. Note that the size of the array is part of the type, for which reason we need it in our template here.

template<> PGSTD::string Quote (  const char *const &  Obj, bool  EmptyIsNull )

Special case for const char *, accepting null pointer as null value. Deprecated: Use sqlesc instead.

template<> PGSTD::string Quote (  const PGSTD::string &  Obj, bool  EmptyIsNull )

std::string version, on which the other versions are built Deprecated: Use sqlesc instead.

template<typename T> PGSTD::string pqxx::Quote (  const T &  Obj, bool  EmptyIsNull )

Quote string for use in SQL. Generate SQL-quoted version of string. If EmptyIsNull is set, an empty string will generate the null value rather than an empty string. Deprecated: Use sqlesc instead.

template<typename CONTAINER> PGSTD::string separated_list (  const PGSTD::string &  sep, const CONTAINER &  c )

Render items in a container as a string, using given separator.

template<typename ITER> PGSTD::string separated_list (  const PGSTD::string &  sep, ITER  begin, ITER  end )

Render items list as a string, using given separator between items.

string pqxx::sqlesc (  const PGSTD::string &   )

Escape string for inclusion in SQL strings. This function differs from similar ones based on libpq in that it handles embedded nul bytes correctly. Unlike its predecessor Quote(), this function does not add SQL-style single quotes around the result string; nor does it recognize and generate nulls.

string pqxx::sqlesc (  const char  str[], size_t  maxlen )

Escape string for inclusion in SQL strings. Reads and escapes input string. The string is terminated by either a nul character or the given byte length, whichever comes first. Parameters: str  optionally zero-terminated character string maxlen  largest possible length of input string, not including optional terminating nul character. Unlike its predecessor Quote(), this function does not add SQL-style single quotes around the result string; nor does it recognize and generate nulls.

string pqxx::sqlesc (  const char  str[]  )

Escape nul-terminated string for inclusion in SQL strings. Use this to sanitize strings that may contain characters like backslashes or quotes. You'll want to do this for all data received from outside your application that gets used in SQL--otherwise an attacker might crack your code by feeding it some string containing e.g. a closing quote followed by SQL commands you did not intend to execute. Unlike its predecessor Quote(), this function does not add SQL-style single quotes around the result string; nor does it recognize and generate nulls.

template<> PGSTD::string to_string (  const unsigned char &  Obj  )

template<> PGSTD::string to_string (  const signed char &  Obj  )

template<> string pqxx::to_string (  const char &   )

PGSTD::string to_string (  const PGSTD::string &  Obj  )

PGSTD::string to_string (  const PGSTD::stringstream &  Obj  )

PGSTD::string to_string (  const char  Obj[]  )

template<> string pqxx::to_string (  const bool &   )

template<> string pqxx::to_string (  const double &   )

template<> string pqxx::to_string (  const float &   )

template<> string pqxx::to_string (  const unsigned long &   )

template<> string pqxx::to_string (  const long &   )

template<> string pqxx::to_string (  const unsigned int &   )

template<> string pqxx::to_string (  const int &   )

template<> string pqxx::to_string (  const unsigned short &   )

template<> string pqxx::to_string (  const short &   )

template<typename T> PGSTD::string to_string (  const T &   )

Convert built-in type to a readable string that PostgreSQL will understand. No special formatting is done, and any locale settings are ignored. The resulting string will be human-readable and in a format suitable for use in SQL queries.

template<> PGSTD::string to_string (  const result::field &  Obj  )

Convert a field to a string.

template<> PGSTD::string ToString (  const unsigned short &  Obj  )

template<> PGSTD::string ToString (  const short &  Obj  )

template<> PGSTD::string ToString (  const bool &  Obj  )

template<> PGSTD::string ToString (  const unsigned char *const &  Obj  )

template<> PGSTD::string ToString (  char *const &  Obj  )

template<> PGSTD::string ToString (  const char *const &  Obj  )

template<> PGSTD::string ToString (  const PGSTD::string &  Obj  )

template<typename T> PGSTD::string ToString (  const T &  Obj  )

Convert object of built-in type to string. Deprecated: Use the newer, rewritten to_string instead. Warning: The conversion is done using the currently active locale, whereas PostgreSQL expects values in the "default" (C) locale. This means that if you intend to use this function from a locale that renders the data types in question (particularly numeric types like float and int) differently from the C default, you'll need to switch back to the C locale before the call. This problem does not exist with the newer to_string function template.

---

Variable Documentation

const oid pqxx::oid_none = 0

The "null" oid.

---