libpqxx  4.0.1
pqxx Namespace Reference

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

Namespaces

namespace  internal
 Private namespace for libpqxx's internal use; do not access.
namespace  prepare
 Dedicated namespace for helper types related to prepared statements.

Classes

class  basic_connection
 The ultimate template that defines a connection type. More...
class  binarystring
class  connect_direct
 Connection policy; creates an immediate connection to a database. More...
class  connect_lazy
 Lazy connection policy; causes connection to be deferred until first use. More...
class  connect_async
 Asynchronous connection policy; connects "in the background". More...
class  connect_null
 Nonfunctional, always-down connection policy for testing/debugging purposes. More...
class  connection_base
 connection_base abstract base class; represents a connection to a database. More...
class  connectionpolicy
class  cursor_base
 Common definitions for cursor types. More...
class  stateless_cursor
 "Stateless cursor" class: easy API for retrieving parts of result sets More...
class  icursorstream
 Simple read-only cursor represented as a stream of results. More...
class  icursor_iterator
 Approximate istream_iterator for icursorstream. More...
class  dbtransaction
class  errorhandler
 Base class for error-handler callbacks. More...
class  quiet_errorhandler
 An error handler that suppresses any previously registered error handlers. More...
class  pqxx_exception
 Mixin base class to identify libpqxx-specific exception types. More...
class  failure
 Run-time failure encountered by libpqxx, similar to std::runtime_error. More...
class  broken_connection
 Exception class for lost or failed backend connection. More...
class  sql_error
 Exception class for failed queries. More...
class  in_doubt_error
 "Help, I don't know whether transaction was committed successfully!" More...
class  internal_error
 Internal error in libpqxx library. More...
class  usage_error
 Error in usage of libpqxx library, similar to std::logic_error. More...
class  argument_error
 Invalid argument passed to libpqxx, similar to std::invalid_argument. More...
class  conversion_error
class  range_error
 Something is out of range, similar to std::out_of_range. More...
class  feature_not_supported
 Database feature not supported in current setup. More...
class  data_exception
 Error in data provided to SQL statement. More...
class  integrity_constraint_violation
class  restrict_violation
class  not_null_violation
class  foreign_key_violation
class  unique_violation
class  check_violation
class  invalid_cursor_state
class  invalid_sql_statement_name
class  invalid_cursor_name
class  syntax_error
class  undefined_column
class  undefined_function
class  undefined_table
class  insufficient_privilege
class  insufficient_resources
 Resource shortage on the server. More...
class  disk_full
class  out_of_memory
class  too_many_connections
class  plpgsql_error
 PL/pgSQL error. More...
class  plpgsql_raise
 Exception raised in PL/pgSQL procedure. More...
class  plpgsql_no_data_found
class  plpgsql_too_many_rows
class  field
 Reference to a field in a result set. More...
class  field_streambuf
class  basic_fieldstream
 Input stream that gets its data from a result field. More...
struct  isolation_traits
 Traits class to describe an isolation level; primarly for libpqxx's own use. More...
class  largeobject
 Identity of a large object. More...
class  largeobjectaccess
 Accessor for large object's contents. More...
class  largeobject_streambuf
 Streambuf to use large objects in standard I/O streams. More...
class  basic_ilostream
 Input stream that gets its data from a large object. More...
class  basic_olostream
 Output stream that writes data back to a large object. More...
class  basic_lostream
 Stream that reads and writes a large object. More...
class  nontransaction
class  notification_receiver
class  notify_listener
 Obsolete notification receiver. More...
class  pipeline
 Processes several queries in FIFO manner, optimized for high throughput. More...
class  result
 Result set containing data returned by a query or command. More...
class  const_result_iterator
 Iterator for rows (tuples) in a result. Use as result::const_iterator. More...
class  const_reverse_result_iterator
 Reverse iterator for result. Use as result::const_reverse_iterator. More...
class  basic_robusttransaction
class  robusttransaction
 Slightly slower, better-fortified version of transaction. More...
struct  string_traits
 Traits class for use in string conversions. More...
struct  string_traits< const char * >
 String traits for C-style string ("pointer to const char") More...
struct  string_traits< char * >
 String traits for non-const C-style string ("pointer to char") More...
struct  string_traits< char[N]>
 String traits for C-style string constant ("array of char") More...
struct  string_traits< const char[N]>
 String traits for "array of const char.". More...
struct  string_traits< std::string >
struct  string_traits< const std::string >
struct  string_traits< std::stringstream >
class  subtransaction
 "Transaction" nested within another transaction More...
class  tablereader
class  tablestream
class  tablewriter
class  basic_transaction
class  transaction
 Standard back-end transaction, templatized on isolation level. More...
class  transaction_base
class  transactor
class  tuple
 Reference to one row in a result. More...
class  const_tuple_iterator
 Iterator for fields in a tuple. Use as tuple::const_iterator. More...
class  const_reverse_tuple_iterator
 Reverse iterator for a tuple. Use as tuple::const_reverse_iterator. More...
struct  thread_safety_model
 Descriptor of library's thread-safety model. More...
class  items
 Container of items with easy contents initialization and string rendering. More...

Typedefs

typedef basic_connection
< connect_direct
connection
 The "standard" connection type: connect to database right now.
typedef basic_connection
< connect_lazy
lazyconnection
 A "lazy" connection type: connect to database only when needed.
typedef basic_connection
< connect_async
asyncconnection
 "Asynchronous" connection type: start connecting, but don't wait for it
typedef basic_connection
< connect_null
nullconnection
 A "dummy" connection type: don't connect to any database at all.
typedef unsigned int tuple_size_type
typedef signed int tuple_difference_type
typedef basic_fieldstream< char > fieldstream
typedef basic_ilostream< char > ilostream
typedef basic_olostream< char > olostream
typedef basic_lostream< char > lostream
typedef transaction work
 Bog-standard, default transaction type.
typedef transaction
< read_committed, read_only
read_transaction
 Read-only transaction.
typedef notify_listener trigger

Enumerations

enum  readwrite_policy { read_only, read_write }
enum  isolation_level { read_committed, repeatable_read, serializable }
 Transaction isolation levels. More...

Functions

std::string escape_binary (const std::string &bin)
 Escape binary string for inclusion in SQL.
std::string escape_binary (const char bin[])
 Escape binary string for inclusion in SQL.
std::string escape_binary (const char bin[], size_t len)
 Escape binary string for inclusion in SQL.
std::string escape_binary (const unsigned char bin[])
 Escape binary string for inclusion in SQL.
std::string escape_binary (const unsigned char bin[], size_t len)
 Escape binary string for inclusion in SQL.
std::string encrypt_password (const std::string &user, const std::string &password)
 Encrypt password for given user. Requires libpq 8.2 or better.
template<>
bool field::to< std::string > (std::string &Obj) const
 Specialization: to(string &).
template<typename CHAR >
std::basic_ostream< CHAR > & operator<< (std::basic_ostream< CHAR > &S, const pqxx::field &F)
 Write a result field to any type of stream.
template<typename T >
void from_string (const field &F, T &Obj)
 Convert a field's string contents to another type.
template<>
std::string to_string (const field &Obj)
 Convert a field to a string.
const_result_iterator operator+ (result::difference_type o, const_result_iterator i)
const_reverse_result_iterator operator+ (result::difference_type n, const const_reverse_result_iterator &i)
template<typename T >
void from_string (const char Str[], T &Obj)
 Attempt to convert postgres-generated string to given built-in type.
template<typename T >
void from_string (const char Str[], T &Obj, size_t)
 Conversion with known string length (for strings that may contain nuls)
template<>
void from_string< std::string > (const char Str[], std::string &Obj, size_t len)
template<typename T >
void from_string (const std::string &Str, T &Obj)
template<typename T >
void from_string (const std::stringstream &Str, T &Obj)
template<>
void from_string (const std::string &Str, std::string &Obj)
template<typename T >
std::string to_string (const T &Obj)
 Convert built-in type to a readable string that PostgreSQL will understand.
const_tuple_iterator operator+ (const_tuple_iterator::difference_type o, const_tuple_iterator i)
thread_safety_model describe_thread_safety () throw ()
 Describe thread safety available in this build.
template<typename ITER , typename ACCESS >
std::string separated_list (const std::string &sep, ITER begin, ITER end, ACCESS access)
 Access iterators using ACCESS functor, returning separator-separated list.
template<typename ITER >
std::string separated_list (const std::string &sep, ITER begin, ITER end)
 Render sequence as a string, using given separator between items.
template<typename OBJ >
std::string separated_list (const std::string &sep, OBJ *begin, OBJ *end)
 Render array as a string, using given separator between items.
template<typename CONTAINER >
std::string separated_list (const std::string &sep, const CONTAINER &c)
 Render items in a container as a string, using given separator.

Variables

const oid oid_none = 0
 The "null" oid.

Detailed Description

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

Typedef Documentation

Deprecated:
The trigger class from libpqxx 1.x/2.x has been replaced with notification_receiver.
typedef signed int pqxx::tuple_difference_type
typedef unsigned int pqxx::tuple_size_type

Enumeration Type Documentation

Transaction isolation levels.

These are as defined in the SQL standard. But there are a few notes specific to PostgreSQL.

First, postgres does not support "read uncommitted." The lowest level you can get is "read committed," which is better. PostgreSQL is built on the MVCC paradigm, which guarantees "read committed" isolation without any additional performance overhead, so there was no point in providing the lower level.

Second, "repeatable read" also makes more isolation guarantees than the standard requires. According to the standard, this level prevents "dirty reads" and "nonrepeatable reads," but not "phantom reads." In postgres, it actually prevents all three.

Third, "serializable" is only properly supported starting at postgres 9.1. If you request "serializable" isolation on an older backend, you will get the same isolation as in "repeatable read." It's better than the "repeatable read" defined in the SQL standard, but not a complete implementation of the standard's "serializable" isolation level.

In general, a lower isolation level will allow more surprising interactions between ongoing transactions, but improve performance. A higher level gives you more protection from subtle concurrency bugs, but sometimes it may not be possible to complete your transaction without avoiding paradoxes in the data. In that case a transaction may fail, and the application will have to re-do the whole thing based on the latest state of the database.

Study the levels and design your application with the right level in mind.

Enumerator:
read_committed 
repeatable_read 
serializable 
Enumerator:
read_only 
read_write 

Function Documentation

std::string pqxx::encrypt_password ( const std::string &  user,
const std::string &  password 
)

Encrypt password for given user. Requires libpq 8.2 or better.

Use this when setting a new password for the user if password encryption is enabled. Inputs are the username the password is for, and the plaintext password.

Returns
encrypted version of the password, suitable for encrypted PostgreSQL authentication.

Thus the password for a user can be changed with:

void setpw(transaction_base &t, const string &user, const string &pw)
{
t.exec("ALTER USER " + user + " "
"PASSWORD '" + encrypt_password(user,pw) + "'");
}
Since
libpq 8.2
template<>
bool pqxx::field::to< std::string > ( std::string &  Obj) const

Specialization: to(string &).

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

Convert a field's string contents to another type.

References pqxx::field::c_str(), and pqxx::field::size().

Referenced by from_string(), pqxx::internal::sql_cursor::move(), and pqxx::field::to().

const_tuple_iterator pqxx::operator+ ( const_tuple_iterator::difference_type  o,
const_tuple_iterator  i 
)
const_result_iterator pqxx::operator+ ( result::difference_type  o,
const_result_iterator  i 
)
const_reverse_result_iterator pqxx::operator+ ( result::difference_type  n,
const const_reverse_result_iterator &  i 
)
template<typename CHAR >
std::basic_ostream<CHAR>& pqxx::operator<< ( std::basic_ostream< CHAR > &  S,
const pqxx::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 "<tt>long long</tt>" 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;

References pqxx::field::c_str(), and pqxx::field::size().

template<typename ITER , typename ACCESS >
std::string pqxx::separated_list ( const std::string &  sep,
ITER  begin,
ITER  end,
ACCESS  access 
)

Access iterators using ACCESS functor, returning separator-separated list.

Parameters
sepseparator string (to be placed between items)
beginbeginning of items sequence
endend of items sequence
accessfunctor defining how to dereference sequence elements

References to_string().

Referenced by pqxx::tablestream::columnlist(), pqxx::tablewriter::generate(), and separated_list().

Variable Documentation