libpqxx
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  array_parser
 Low-level array parser. More...
 
class  basic_connection
 Base-class template for all libpqxx connection types. 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  binarystring
 Binary data corresponding to PostgreSQL's "BYTEA" binary-string type. More...
 
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 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_row_iterator
 Reverse iterator for a row. Use as row::const_reverse_iterator. More...
 
class  const_row_iterator
 Iterator for fields in a row. Use as row::const_iterator. More...
 
class  conversion_error
 Value conversion failed, e.g. when converting "Hello" to int. More...
 
class  cursor_base
 Common definitions for cursor types. More...
 
class  data_exception
 Error in data provided to SQL statement. More...
 
class  dbtransaction
 Abstract base class responsible for bracketing a backend transaction. More...
 
class  deadlock_detected
 The ongoing transaction has deadlocked. Retrying it may help. More...
 
class  disk_full
 
struct  enum_traits
 Helper class for defining enum conversions. More...
 
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  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
 Simple "transaction" class offering no transactional integrity. More...
 
class  not_null_violation
 
class  notification_receiver
 
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  row
 Reference to one row in a result. More...
 
class  serialization_failure
 Transaction failed to serialize. Please retry it. 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...
 
class  statement_completion_unknown
 We can't tell whether our last statement succeeded. 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 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
 Interface definition (and common code) for "transaction" classes. More...
 
class  transaction_rollback
 The backend saw itself forced to roll back the ongoing transaction. More...
 
class  transactor
 
class  undefined_column
 
class  undefined_function
 
class  undefined_table
 
class  unexpected_rows
 Query returned an unexpected number of rows. More...
 
class  unique_violation
 
class  usage_error
 Error in usage of libpqxx library, similar to std::logic_error. More...
 

Typedefs

using connection = basic_connection< connect_direct >
 The "standard" connection type: connect to database right now. More...
 
using lazyconnection = basic_connection< connect_lazy >
 A "lazy" connection type: connect to database only when needed. More...
 
using asyncconnection = basic_connection< connect_async >
 "Asynchronous" connection type: start connecting, but don't wait for it More...
 
using nullconnection = basic_connection< connect_null >
 A "dummy" connection type: don't connect to any database at all. More...
 
using fieldstream = basic_fieldstream< char >
 
using ilostream = basic_ilostream< char >
 
using olostream = basic_olostream< char >
 
using lostream = basic_lostream< char >
 
using result_size_type = unsigned long
 Number of rows in a result set. More...
 
using result_difference_type = signed long
 Difference between result sizes. More...
 
using row_size_type = unsigned int
 Number of fields in a row of database data. More...
 
using row_difference_type = signed int
 Difference between row sizes. More...
 
using field_size_type = std::size_t
 Number of bytes in a field of database data. More...
 
using large_object_size_type = long
 Number of bytes in a large object. (Unusual: it's signed.) More...
 
using work = transaction<>
 The default transaction type. More...
 
using read_transaction = transaction< read_committed, read_only >
 Read-only transaction. More...
 

Enumerations

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

Functions

std::string encrypt_password (const std::string &user, const std::string &password)
 Encrypt password for given user. 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 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)
 
const_row_iterator operator+ (const_row_iterator::difference_type o, const_row_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...
 
template<typename TRANSACTION_CALLBACK >
auto perform (const TRANSACTION_CALLBACK &callback, int attempts=3) -> decltype(callback())
 Simple way to execute a transaction with automatic retry. More...
 
template<typename T >
void ignore_unused (T)
 Suppress compiler warning about an unused item. More...
 
thread_safety_model describe_thread_safety () noexcept
 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)
 Represent sequence of values as a separated string. 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 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

constexpr oid oid_none = 0
 The "null" oid. More...
 

Detailed Description

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

Handling of SQL arrays.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/field instead.

Copyright (c) 2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::basic_connection class template.

Instantiations of basic_connection bring connections and policies together.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/basic_connection instead.

Copyright (c) 2006-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Representation for raw, binary data.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/binarystring instead.

Copyright (c) 2003-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::connection and pqxx::lazyconnection classes.

Different ways of setting up a backend connection.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/connection instead.

Copyright (c) 2001-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::connection_base abstract base class.

pqxx::connection_base encapsulates a frontend to backend connection

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/connection_base instead.

Copyright (c) 2001-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the connection policy classes.

Interface for defining connection policies DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/connection instead.

Copyright (c) 2005-2017, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the iterator/container-style cursor classes.

C++-style wrappers for SQL cursors

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/cursor instead.

Copyright (c) 2004-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::dbtransaction abstract base class.

pqxx::dbransaction defines a real transaction on the database.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/dbtransaction instead.

Copyright (c) 2004-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::errorhandler class.

pqxx::errorhandler handlers errors and warnings in a database session.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/connection_base instead.

Copyright (c) 2012-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of libpqxx exception classes.

pqxx::sql_error, pqxx::broken_connection, pqxx::in_doubt_error, ...

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/except instead.

Copyright (c) 2003-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definitions for the pqxx::field class.

pqxx::field refers to a field in a query result.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/field instead.

Copyright (c) 2001-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definitions of transaction isolation levels.

Policies and traits describing SQL transaction isolation levels

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/isolation instead.

Copyright (c) 2003-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Large Objects interface.

Allows access to large objects directly, or through I/O streams.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/largeobject instead.

Copyright (c) 2003-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::nontransaction class.

pqxx::nontransaction provides nontransactional database access

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/nontransaction instead.

Copyright (c) 2002-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::notification_receiver functor interface.

pqxx::notification_receiver handles incoming notifications.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/notification instead.

Copyright (c) 2011-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::pipeline class.

Throughput-optimized query manager

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/pipeline instead.

Copyright (c) 2003-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Helper classes for defining and executing prepared statements.

See the connection_base hierarchy for more about prepared statements.

Copyright (c) 2006-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definitions for the pqxx::result class and support classes.

pqxx::result represents the set of result rows from a database query.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/result instead.

Copyright (c) 2001-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::robusttransaction class.

pqxx::robusttransaction is a slower but safer transaction class.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/robusttransaction instead.

Copyright (c) 2002-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

String conversion definitions.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/stringconv instead.

Copyright (c) 2008-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::subtransaction class.

pqxx::subtransaction is a nested transaction, i.e. one within a transaction.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/subtransaction instead.

Copyright (c) 2005-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::tablereader class.

pqxx::tablereader enables optimized batch reads from a database table.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/tablereader instead.

Copyright (c) 2001-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::tablestream class.

pqxx::tablestream provides optimized batch access to a database table.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/tablestream instead.

Copyright (c) 2001-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::tablewriter class.

pqxx::tablewriter enables optimized batch updates to a database table.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/tablewriter.hxx instead.

Copyright (c) 2001-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Definition of the pqxx::transaction class. pqxx::transaction represents a standard database transaction.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/transaction instead.

Copyright (c) 2001-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Common code and definitions for the transaction classes.

pqxx::transaction_base defines the interface for any abstract class that represents a database transaction.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/transaction_base instead.

Copyright (c) 2001-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Basic type aliases and forward declarations.

Copyright (c) 2018, Jeroen T. Vermeulen

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Various utility definitions for libpqxx.

DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/util instead.

Copyright (c) 2001-2018, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Typedef Documentation

◆ field_size_type

using pqxx::field_size_type = typedef std::size_t

Number of bytes in a field of database data.

◆ fieldstream

using pqxx::fieldstream = typedef basic_fieldstream<char>

◆ ilostream

using pqxx::ilostream = typedef basic_ilostream<char>

◆ large_object_size_type

using pqxx::large_object_size_type = typedef long

Number of bytes in a large object. (Unusual: it's signed.)

◆ lostream

using pqxx::lostream = typedef basic_lostream<char>

◆ olostream

using pqxx::olostream = typedef basic_olostream<char>

◆ read_transaction

Read-only transaction.

◆ result_difference_type

using pqxx::result_difference_type = typedef signed long

Difference between result sizes.

◆ result_size_type

using pqxx::result_size_type = typedef unsigned long

Number of rows in a result set.

◆ row_difference_type

using pqxx::row_difference_type = typedef signed int

Difference between row sizes.

◆ row_size_type

using pqxx::row_size_type = typedef unsigned int

Number of fields in a row of database data.

◆ work

using pqxx::work = typedef transaction<>

The default transaction type.

Enumeration Type Documentation

◆ 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. (If you want to retry your code in that situation, have a look at the transactor framework.)

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

Enumerator
read_committed 
repeatable_read 
serializable 

◆ readwrite_policy

Enumerator
read_only 
read_write 

Function Documentation

◆ describe_thread_safety()

pqxx::thread_safety_model pqxx::describe_thread_safety ( )
noexcept

◆ encrypt_password()

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

Encrypt password for given user.

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) + "'");
}

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(), pqxx::field::size(), and to_string().

Referenced by from_string(), pqxx::result::table_column(), and pqxx::field::to().

◆ ignore_unused()

template<typename T >
void pqxx::ignore_unused ( )

Suppress compiler warning about an unused item.

Referenced by pqxx::connection_base::connection_base().

◆ operator+() [1/3]

◆ operator+() [2/3]

◆ operator+() [3/3]

◆ operator<<()

template<typename CHAR >
std::basic_ostream<CHAR>& pqxx::operator<< ( std::basic_ostream< CHAR > &  S,
const 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().

◆ to_string()

Variable Documentation

◆ oid_none