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
struct	argument_error
	Invalid argument passed to libpqxx, similar to std::invalid_argument. More...

class	array_parser
	Low-level array parser. 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...

struct	broken_connection
	Exception class for lost or failed backend connection. More...

struct	check_violation

class	connection
	Connection to a database. More...

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

struct	conversion_error
	Value conversion failed, e.g. when converting "Hello" to int. More...

struct	conversion_overrun
	Could not convert value to string: not enough buffer space. More...

class	cursor_base
	Common definitions for cursor types. More...

struct	data_exception
	Error in data provided to SQL statement. More...

class	dbtransaction
	Abstract transaction base class: bracket transactions on the database. More...

struct	deadlock_detected
	The ongoing transaction has deadlocked. Retrying it may help. More...

struct	disk_full

class	errorhandler
	Base class for error-handler callbacks. More...

struct	failure
	Run-time failure encountered by libpqxx, similar to std::runtime_error. More...

struct	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

struct	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...

struct	in_doubt_error
	"Help, I don't know whether transaction was committed successfully!" More...

struct	insufficient_privilege

struct	insufficient_resources
	Resource shortage on the server. More...

struct	integrity_constraint_violation

struct	internal_error
	Internal error in libpqxx library. More...

struct	invalid_cursor_name

struct	invalid_cursor_state

struct	invalid_sql_statement_name

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

struct	no_null
	Nullness traits describing a type which does not have a null value. More...

class	nontransaction
	Simple "transaction" class offering no transactional integrity. More...

struct	not_null_violation

class	notification_receiver

struct	nullness
	Traits describing a type's "null value," if any. More...

struct	nullness< ENUM, std::enable_if_t< std::is_enum_v< ENUM > > >
	Nullness: Enums do not have an inherent null value. More...

struct	out_of_memory

class	pipeline
	Processes several queries in FIFO manner, optimized for high throughput. More...

struct	plpgsql_error
	PL/pgSQL error. More...

struct	plpgsql_no_data_found

struct	plpgsql_raise
	Exception raised in PL/pgSQL procedure. More...

struct	plpgsql_too_many_rows

class	quiet_errorhandler
	An error handler that suppresses any previously registered error handlers. More...

struct	range_error
	Something is out of range, similar to std::out_of_range. More...

struct	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...

struct	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...

struct	statement_completion_unknown
	We can't tell whether our last statement succeeded. More...

class	stream_from
	Efficiently pull data directly out of a table. More...

class	stream_to
	Efficiently write data directly to a database table. More...

struct	string_traits
	Traits class for use in string conversions. More...

class	subtransaction
	"Transaction" nested within another transaction More...

struct	syntax_error

struct	thread_safety_model
	Descriptor of library's thread-safety model. More...

struct	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...

struct	transaction_rollback
	The backend saw itself forced to roll back the ongoing transaction. More...

struct	undefined_column

struct	undefined_function

struct	undefined_table

struct	unexpected_rows
	Query returned an unexpected number of rows. More...

struct	unique_violation

struct	usage_error
	Error in usage of libpqxx library, similar to std::logic_error. More...

class	zview
	Marker-type wrapper: zero-terminated `std::string_view`. More...

Typedefs
using	connection_base = connection

using	fieldstream = basic_fieldstream< char >

using	ilostream = basic_ilostream< char >

using	olostream = basic_olostream< char >

using	lostream = basic_lostream< char >

using	result_size_type = int
	Number of rows in a result set. More...

using	result_difference_type = int
	Difference between result sizes. More...

using	row_size_type = int
	Number of fields in a row of database data. More...

using	row_difference_type = int
	Difference between row sizes. More...

using	field_size_type = size_t
	Number of bytes in a field of database data. More...

using	large_object_size_type = int64_t
	Number of bytes in a large object. More...


using	work = transaction<>
	The default transaction type. More...

using	read_transaction = transaction< isolation_level::read_committed, write_policy::read_only >
	Read-only transaction. More...

Enumerations
enum	error_verbosity : int { error_verbosity::terse = 0, error_verbosity::normal = 1, error_verbosity::verbose = 2 }
	Error verbosity levels. More...

enum	write_policy { write_policy::read_only, write_policy::read_write }
	Should a transaction be read-only, or read-write? More...

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

Functions
std::string	encrypt_password (char const user[], char const password[])
	Encrypt a password. More...

std::string	encrypt_password (std::string const &user, std::string const &password)
	Encrypt password. 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, field const &value)
	Write a result field to any type of stream. More...

template<typename T >
T	from_string (field const &value)
	Convert a field's string contents to another type. More...

template<>
std::string	to_string (field const &value)
	Convert a field to a string. More...

const_result_iterator	operator+ (result::difference_type o, const_result_iterator const &i)

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

const_row_iterator	operator+ (const_row_iterator::difference_type o, const_row_iterator const &i)

template<typename ITER , typename ACCESS >
std::string	separated_list (std::string_view sep, ITER begin, ITER end, ACCESS access)
	Represent sequence of values as a string, joined by a given separator. More...

template<typename ITER >
std::string	separated_list (std::string_view sep, ITER begin, ITER end)
	Render sequence as a string, using given separator between items. More...

template<typename CONTAINER >
auto	separated_list (std::string_view sep, CONTAINER const &c) -> typename std::enable_if<(not std::is_void< decltype(std::begin(c))>::value and not std::is_void< decltype(std::end(c))>::value), std::string >::type
	Render items in a container as a string, using given separator. More...

template<typename TUPLE , std::size_t INDEX = 0, typename ACCESS , typename std::enable_if<(INDEX==std::tuple_size< TUPLE >::value - 1), int >::type = 0>
std::string	separated_list (std::string_view, TUPLE const &t, ACCESS const &access)
	Render items in a tuple as a string, using given separator. More...

template<typename TUPLE , std::size_t INDEX = 0, typename ACCESS >
std::string	separated_list (std::string_view sep, TUPLE const &t, ACCESS const &access)

template<typename TUPLE , std::size_t INDEX = 0>
std::string	separated_list (std::string_view sep, TUPLE const &t)

template<typename T >
T	from_string (std::string_view text)
	Attempt to convert postgres-generated string to given built-in type. More...

template<typename T >
void	from_string (std::string_view text, T &value)
	Attempt to convert postgres-generated string to given built-in object. More...

template<typename TYPE >
std::string	to_string (TYPE const &value)
	Convert a value to a readable string that PostgreSQL will understand. More...

template<typename TYPE >
void	into_string (TYPE const &value, std::string &out)
	Convert a value to a readable string that PostgreSQL will understand. More...

template<typename TYPE >
bool	is_null (TYPE const &value)
	Is `value` null? More...

template<>
void	stream_from::extract_value< std::nullptr_t > (std::string const &line, std::nullptr_t &, std::string::size_type &here, std::string &workspace) const

template<typename TRANSACTION_CALLBACK >
auto	perform (TRANSACTION_CALLBACK &&callback, int attempts=3) -> std::invoke_result_t< TRANSACTION_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...

template<typename TO , typename FROM >
TO	check_cast (FROM value, char const description[])
	Cast a numeric value to another type, or throw if it underflows/overflows. More...

void	check_version ()

thread_safety_model	describe_thread_safety ()
	Describe thread safety available in this build. More...

	PQXX_DECLARE_ENUM_CONVERSION (pqxx::internal::encoding_group)

	PQXX_DECLARE_ENUM_CONVERSION (ExecStatusType)

Variables
template<typename TYPE >
std::string const	type_name {internal::demangle_type_name(typeid(TYPE).name())}
	A human-readable name for a type, used in error messages and such. More...

template<typename T >
constexpr bool	is_sql_array {false}
	Does this type translate to an SQL array? More...

template<typename T >
constexpr char	array_separator {','}
	Element separator between SQL array elements of this type. More...

constexpr oid	oid_none {0}
	The "null" oid. More...

Detailed Description

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

Handling of SQL arrays.

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.

Implementation of string encodings support

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.

Implementation of the pqxx::result class and support classes.

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

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

◆ connection_base

using pqxx::connection_base = typedef connection

Deprecated:: Old base class for connection. They are now the same class.

◆ field_size_type

using pqxx::field_size_type = typedef 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 int64_t

Number of bytes in a large object.

◆ lostream

using pqxx::lostream = typedef basic_lostream<char>

◆ olostream

using pqxx::olostream = typedef basic_olostream<char>

◆ read_transaction

using pqxx::read_transaction = typedef transaction<isolation_level::read_committed, write_policy::read_only>

Read-only transaction.

◆ result_difference_type

using pqxx::result_difference_type = typedef int

Difference between result sizes.

◆ result_size_type

using pqxx::result_size_type = typedef int

Number of rows in a result set.

◆ row_difference_type

using pqxx::row_difference_type = typedef int

Difference between row sizes.

◆ row_size_type

using pqxx::row_size_type = typedef int

Number of fields in a row of database data.

◆ work

using pqxx::work = typedef transaction<>

The default transaction type.

Enumeration Type Documentation

◆ error_verbosity

enum pqxx::error_verbosity : int

strong

Error verbosity levels.

Enumerator
terse
normal
verbose

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

◆ write_policy

enum pqxx::write_policy

strong

Should a transaction be read-only, or read-write?

No, this is not an isolation level. So it really doesn't belong here. But it's not really worth a separate header.

Enumerator
read_only
read_write

Function Documentation

◆ check_cast()

template<typename TO , typename FROM >

TO pqxx::check_cast	(	FROM	value,
		char const	description[]
	)

Cast a numeric value to another type, or throw if it underflows/overflows.

Both types must be arithmetic types, and they must either be both integral or both floating-point types.

References ignore_unused().

Referenced by pqxx::connection::close(), pqxx::connection::encoding_id(), pqxx::connection::esc_like(), pqxx::largeobject_streambuf< CHAR, TRAITS >::overflow(), pqxx::pipeline::resume(), pqxx::largeobject_streambuf< CHAR, TRAITS >::underflow(), pqxx::connection::unprepare(), and pqxx::internal::wait_read().

◆ check_version()

void pqxx::check_version ( )

Check library version at link time.

Ensures a failure when linking an application against a radically different libpqxx version than the one against which it was compiled.

Sometimes application builds fail in unclear ways because they compile using headers from libpqxx version X, but then link against libpqxx binary version Y. A typical scenario would be one where you're building against a libpqxx which you have built yourself, but a different version is installed on the system.

The check_library_version template is declared for any library version, but only actually defined for the version of the libpqxx binary against which the code is linked.

If the library binary is a different version than the one declared in these headers, then this call will fail to link: there will be no definition for the function with these exact template parameter values. There will be a definition, but the version in the parameter values will be different.

References ignore_unused(), and pqxx::internal::PQXX_VERSION_CHECK().

Referenced by pqxx::connection::connection().

◆ describe_thread_safety()

pqxx::thread_safety_model pqxx::describe_thread_safety ( )

Describe thread safety available in this build.

Various utility functions.

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.

References pqxx::thread_safety_model::description, pqxx::thread_safety_model::safe_kerberos, and pqxx::thread_safety_model::safe_libpq.

◆ encrypt_password() [1/2]

std::string pqxx::encrypt_password	(	char const	user[],
		char const	password[]
	)

Encrypt a password.

Deprecated:: Use connection::encrypt_password instead.

Referenced by encrypt_password(), pqxx::connection::encrypt_password(), and pqxx::connection::set_client_encoding().

◆ encrypt_password() [2/2]

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

Encrypt password.

Deprecated:: Use connection::encrypt_password instead.

References encrypt_password().

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

template<>

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

Specialization: to(string &).

References is_null().

◆ from_string()

template<typename T >

T pqxx::from_string ( field const & value )

Convert a field's string contents to another type.

References to_string(), and pqxx::field::view().

Referenced by pqxx::field::to().

◆ ignore_unused()

template<typename T >

void pqxx::ignore_unused ( T && )

Suppress compiler warning about an unused item.

Referenced by check_cast(), check_version(), is_null(), and pqxx::internal::TypedCopyEscaper::operator()().

◆ operator+() [1/3]

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

References pqxx::const_result_iterator::operator-().

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

◆ operator+() [2/3]

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

References pqxx::const_reverse_result_iterator::base().

◆ operator+() [3/3]

const_row_iterator pqxx::operator+	(	const_row_iterator::difference_type	o,
		const_row_iterator const &	i
	)

References pqxx::const_row_iterator::operator-().

◆ operator<<()

template<typename CHAR >

std::basic_ostream<CHAR>& pqxx::operator<<	(	std::basic_ostream< CHAR > &	s,
		field const &	value
	)

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;

Referenced by pqxx::stream_to::operator!().

◆ PQXX_DECLARE_ENUM_CONVERSION() [1/2]

pqxx::PQXX_DECLARE_ENUM_CONVERSION ( ExecStatusType )

◆ PQXX_DECLARE_ENUM_CONVERSION() [2/2]

pqxx::PQXX_DECLARE_ENUM_CONVERSION ( pqxx::internal::encoding_group )

◆ stream_from::extract_value< std::nullptr_t >()

template<>

void pqxx::stream_from::extract_value< std::nullptr_t >	(	std::string const &	line,
		std::nullptr_t &	,
		std::string::size_type &	here,
		std::string &	workspace
	)		const

◆ to_string()

template<>

std::string pqxx::to_string ( field const & value )

Convert a field to a string.

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

Referenced by pqxx::connection::adorn_name(), pqxx::result::at(), pqxx::binarystring::at(), pqxx::internal::basic_robusttransaction::basic_robusttransaction(), pqxx::connection::close(), pqxx::result::column_name(), pqxx::result::column_table(), pqxx::result::column_type(), pqxx::transaction_base::exec_n(), pqxx::internal::for_encoding(), from_string(), pqxx::pipeline::is_finished(), pqxx::internal::TypedCopyEscaper::operator()(), pqxx::transaction_base::query_value(), pqxx::connection::quote(), pqxx::largeobjectaccess::read(), pqxx::largeobject::remove(), pqxx::pipeline::retain(), separated_list(), pqxx::connection::set_client_encoding(), pqxx::icursorstream::set_stride(), pqxx::result::table_column(), pqxx::largeobject::to_file(), and pqxx::largeobjectaccess::write().

Variable Documentation

◆ oid_none

constexpr oid pqxx::oid_none {0}

The "null" oid.

Referenced by pqxx::result::column_table(), pqxx::result::column_type(), pqxx::largeobject::largeobject(), pqxx::largeobject::operator>(), and pqxx::largeobject::reason().

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ connection_base

◆ field_size_type

◆ fieldstream

◆ ilostream

◆ large_object_size_type

◆ lostream

◆ olostream

◆ read_transaction

◆ result_difference_type

◆ result_size_type

◆ row_difference_type

◆ row_size_type

◆ work

Enumeration Type Documentation

◆ error_verbosity

◆ isolation_level

◆ write_policy

Function Documentation

◆ check_cast()

◆ check_version()

◆ describe_thread_safety()

◆ encrypt_password() [1/2]

◆ encrypt_password() [2/2]

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

◆ from_string()

◆ ignore_unused()

◆ operator+() [1/3]

◆ operator+() [2/3]

◆ operator+() [3/3]

◆ operator<<()

◆ PQXX_DECLARE_ENUM_CONVERSION() [1/2]

◆ PQXX_DECLARE_ENUM_CONVERSION() [2/2]

◆ stream_from::extract_value< std::nullptr_t >()

◆ to_string()

Variable Documentation

◆ oid_none