pqxx Namespace Reference

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

## Namespaces

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

## Classes

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

## Typedefs

typedef basic_connection< connect_direct > | connection
| The "standard" connection type: connect to database right now. More...
typedef basic_connection< connect_lazy > | lazyconnection
| A "lazy" connection type: connect to database only when needed. More...
typedef basic_connection< connect_async > | asyncconnection
| "Asynchronous" connection type: start connecting, but don't wait for it More...
typedef basic_connection< connect_null > | nullconnection
| A "dummy" connection type: don't connect to any database at all. More...
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. More...
typedef transaction< read_committed, read_only > | read_transaction
| Read-only transaction. More...
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. More...
std::string | escape_binary (const char bin[])
| Escape binary string for inclusion in SQL. More...
std::string | escape_binary (const char bin[], size_t len)
| Escape binary string for inclusion in SQL. More...
std::string | escape_binary (const unsigned char bin[])
| Escape binary string for inclusion in SQL. More...
std::string | escape_binary (const unsigned char bin[], size_t len)
| Escape binary string for inclusion in SQL. More...
std::string | encrypt_password (const std::string &user, const std::string &password)
| Encrypt password for given user. Requires libpq 8.2 or better. More...
template<>
bool | field::to< std::string > (std::string &Obj) const
| Specialization: `to(string &)`. More...
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. More...
template<typename T >
void | from_string (const field &F, T &Obj)
| Convert a field's string contents to another type. More...
template<>
std::string | to_string (const field &Obj)
| Convert a field to a string. More...
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. More...
template<typename T >
void | from_string (const char Str[], T &Obj, size_t)
| Conversion with known string length (for strings that may contain nuls) More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...

## Variables

const oid | oid_none = 0
| The "null" oid. More...

## Detailed Description

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

## Typedef Documentation

## fieldstream

typedef basic_fieldstream<char> pqxx::fieldstream

## ilostream

typedef basic_ilostream<char> pqxx::ilostream

## lostream

typedef basic_lostream<char> pqxx::lostream

## olostream

typedef basic_olostream<char> pqxx::olostream

## trigger

typedef notify_listener pqxx::trigger

Deprecated:
  The trigger class from libpqxx 1.x/2.x has been replaced with notification_receiver.

## tuple_difference_type

typedef signed int pqxx::tuple_difference_type

## tuple_size_type

typedef unsigned int pqxx::tuple_size_type

## Enumeration Type Documentation

## isolation_level

enum pqxx::isolation_level

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 |

## readwrite_policy

enum pqxx::readwrite_policy

Enumerator
read_only |
read_write |

## Function Documentation

## describe_thread_safety()

pqxx::thread_safety_model pqxx::describe_thread_safety | ( |  | ) |
throw | ( |
| ) |  |

Describe thread safety available in this build.

References pqxx::thread_safety_model::description, pqxx::thread_safety_model::have_safe_strerror, pqxx::thread_safety_model::safe_kerberos, pqxx::thread_safety_model::safe_libpq, pqxx::thread_safety_model::safe_query_cancel, and pqxx::thread_safety_model::safe_result_copy.

## encrypt_password()

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

Referenced by pqxx::internal::reactivation_avoidance_counter::get().

## field::to< std::string >()

template<>

bool pqxx::field::to< std::string > | ( | std::string & | Obj | ) | const

Specialization: `to(string &)`.

## from_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(), pqxx::result::table_column(), and pqxx::field::to().

## operator+() [1/3]

const_tuple_iterator pqxx::operator+ | ( | const_tuple_iterator::difference_type | o,
|  | const_tuple_iterator | i
| ) |  |

## operator+() [2/3]

const_result_iterator pqxx::operator+ | ( | result::difference_type | o,
|  | const_result_iterator | i
| ) |  |

Referenced by pqxx::const_tuple_iterator::operator>=(), and pqxx::const_result_iterator::operator>=().

## operator+() [3/3]

const_reverse_result_iterator pqxx::operator+ | ( | result::difference_type | n,
|  | const const_reverse_result_iterator & | i
| ) |  |

References pqxx::const_reverse_result_iterator::base().

## operator<<()

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().

Referenced by pqxx::tablewriter::reserve().

## separated_list()

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

  sep | separator string (to be placed between items)
  begin | beginning of items sequence
  end | end of items sequence
  access | functor defining how to dereference sequence elements

References to_string().

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

## to_string()

template<>

std::string pqxx::to_string | ( | const field & | Obj | ) |

Convert a field to a string.

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

Referenced by pqxx::connection_base::adorn_name(), pqxx::binarystring::at(), pqxx::result::at(), pqxx::internal::sql_cursor::close(), pqxx::connection_base::close(), pqxx::result::column_name(), pqxx::result::column_table(), pqxx::result::column_type(), pqxx::internal::EscapeAny(), pqxx::pipeline::is_finished(), pqxx::internal::sql_cursor::move(), pqxx::connection_base::quote(), pqxx::largeobjectaccess::read(), pqxx::largeobject::remove(), pqxx::pipeline::retain(), separated_list(), pqxx::icursorstream::set_stride(), pqxx::internal::sleep_seconds(), pqxx::result::table_column(), pqxx::largeobject::to_file(), pqxx::largeobjectaccess::write(), and pqxx::basic_robusttransaction::~basic_robusttransaction().

## Variable Documentation

## oid_none

const oid pqxx::oid_none = 0

The "null" oid.

Referenced by pqxx::result::column_table(), pqxx::result::column_type(), pqxx::largeobject::largeobject(), and pqxx::largeobject::Reason().