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.

Classes
class	array
	An SQL array received from the database. More...
struct	string_traits< array< ELEMENT, DIMENSIONS, array_separator< ELEMENT > > >
	String traits for SQL arrays represented as pqxx::array. More...
struct	nullness< array< ELEMENT, DIMENSIONS, array_separator< ELEMENT > > >
	No-null trait for SQL arrays represented as pqxx::array. More...
struct	nullness< CONT >
	A container of nonbinary data. It has no inherent null value. More...
struct	string_traits< CONT >
	A container of nonbinary data can represent a 1-dimensional SQL array. More...
class	array_parser
	Low-level parser for C++ arrays. More...
class	blob
struct	notification
	An incoming notification. More...
class	connection
	Connection to a database. More...
class	connecting
	An ongoing, non-blocking stepping stone to a connection. More...
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
	Abstract transaction base class: bracket transactions on the database. More...
class	errorhandler
class	quiet_errorhandler
struct	failure
	Base class for all exceptions specific to libpqxx. More...
struct	broken_connection
	Exception class for lost or failed backend connection. More...
struct	version_mismatch
	Could not establish connection due to version mismatch. More...
struct	variable_set_to_null
	The caller attempted to set a variable to null, which is not allowed. More...
struct	sql_error
	Exception class for failed queries. More...
struct	protocol_violation
	Exception class for mis-communication with the server. More...
struct	in_doubt_error
	"Help, I don't know whether transaction was committed successfully!" More...
struct	transaction_rollback
	The backend saw itself forced to roll back the ongoing transaction. More...
struct	serialization_failure
	Transaction failed to serialize. Please retry the whole thing. More...
struct	statement_completion_unknown
	We can't tell whether our last statement succeeded. More...
struct	deadlock_detected
	The ongoing transaction has deadlocked. Retrying it may help. More...
struct	internal_error
	Internal error in libpqxx library. More...
struct	usage_error
	Error in usage of libpqxx library, similar to std::logic_error. More...
struct	argument_error
	Invalid argument passed to libpqxx, similar to std::invalid_argument. More...
struct	conversion_error
	Value conversion failed, e.g. when converting "Hello" to int. More...
struct	unexpected_null
	Could not convert null value: target type does not support null. More...
struct	conversion_overrun
	Could not convert value to string: not enough buffer space. More...
struct	range_error
	Something is out of range, similar to std::out_of_range. More...
struct	unexpected_rows
	Query returned an unexpected number of rows. More...
struct	feature_not_supported
	Database feature not supported in current setup. More...
struct	data_exception
	Error in data provided to SQL statement. More...
struct	integrity_constraint_violation
struct	restrict_violation
struct	not_null_violation
struct	foreign_key_violation
struct	unique_violation
struct	check_violation
struct	invalid_cursor_state
struct	invalid_sql_statement_name
struct	invalid_cursor_name
struct	syntax_error
struct	undefined_column
struct	undefined_function
struct	undefined_table
struct	insufficient_privilege
struct	insufficient_resources
	Resource shortage on the server. More...
struct	disk_full
struct	server_out_of_memory
struct	too_many_connections
struct	plpgsql_error
	PL/pgSQL error. More...
struct	plpgsql_raise
	Exception raised in PL/pgSQL procedure. More...
struct	plpgsql_no_data_found
struct	plpgsql_too_many_rows
class	field_ref
	Lightweight reference to a field in a result set. More...
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	nullness< T >
	The built-in arithmetic types do not have inherent null values. More...
struct	string_traits< short >
struct	string_traits< unsigned short >
struct	string_traits< int >
struct	string_traits< unsigned >
struct	string_traits< long >
struct	string_traits< unsigned long >
struct	string_traits< long long >
struct	string_traits< unsigned long long >
struct	string_traits< float >
struct	string_traits< double >
struct	string_traits< long double >
struct	string_traits< bool >
struct	nullness< std::optional< T > >
struct	string_traits< std::optional< T > >
struct	nullness< std::variant< T... > >
struct	string_traits< std::variant< T... > >
struct	string_traits< std::nullptr_t >
struct	string_traits< std::nullopt_t >
struct	string_traits< std::monostate >
struct	nullness< char const * >
struct	string_traits< char const * >
	String traits for C-style string ("pointer to char const"). More...
struct	nullness< char * >
struct	string_traits< char * >
	String traits for non-const C-style string ("pointer to char"). More...
struct	nullness< char[N]>
struct	string_traits< char[N]>
	String traits for C-style string constant ("pointer to array of char"). More...
struct	nullness< std::string >
struct	string_traits< std::string >
struct	nullness< std::string_view >
	There's no real null value for std::string_view. More...
struct	string_traits< std::string_view >
	String traits for string_view. More...
struct	nullness< zview >
struct	string_traits< zview >
	String traits for zview. More...
struct	nullness< std::stringstream >
struct	string_traits< std::stringstream >
struct	nullness< std::nullptr_t >
struct	nullness< std::nullopt_t >
struct	nullness< std::monostate >
struct	nullness< std::unique_ptr< T > >
struct	string_traits< std::unique_ptr< T, Args... > >
struct	nullness< std::shared_ptr< T > >
struct	string_traits< std::shared_ptr< T > >
struct	nullness< DATA >
struct	string_traits< DATA >
struct	string_traits< T >
	String traits for SQL arrays. More...
struct	string_traits< encoding_group >
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	stream_query
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
	Simple "transaction" class offering no transactional integrity. More...
class	notification_receiver
class	params
	Build a parameter list for a parameterised or prepared statement. More...
class	placeholders
	Generate parameter placeholders for use in an SQL statement. More...
class	pipeline
	Processes several queries in FIFO manner, optimized for high throughput. More...
class	prepped
	A string that is the name of a prepared statement. More...
struct	no_bound
	An unlimited boundary value to a pqxx::range. More...
class	inclusive_bound
	An inclusive boundary value to a pqxx::range. More...
class	exclusive_bound
	An exclusive boundary value to a pqxx::range. More...
class	range_bound
	A range boundary value. More...
class	range
	A C++ equivalent to PostgreSQL's range types. More...
struct	string_traits< range< TYPE > >
	String conversions for a range type. More...
struct	nullness< range< TYPE > >
	A range type does not have an innate null value. More...
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_ref
	Lightweight reference to one row in a result. More...
class	row
	Reference to one row in a result. More...
class	const_row_iterator
	Iterator for fields in a row. Use as row::const_iterator. More...
class	const_reverse_row_iterator
	Reverse iterator for a row. Use as row::const_reverse_iterator. More...
struct	nullness
	Traits describing a type's "null value," if any. More...
struct	no_null
	Nullness traits describing a type which does not have a null value. More...
struct	all_null
	Nullness traits describing a type whose values are always null. More...
struct	conversion_context
	Contextual parameters for string conversions implementations. More...
struct	string_traits
	Traits class for use in string conversions. More...
struct	forbidden_conversion
	String traits for a forbidden type conversion. More...
struct	string_traits< char >
	You cannot convert a char to/from SQL. More...
struct	string_traits< unsigned char >
	You cannot convert an unsigned char to/from SQL. More...
struct	string_traits< signed char >
	You cannot convert a signed char to/from SQL. More...
struct	string_traits< std::byte >
	You cannot convert a std::byte to/from SQL. More...
struct	nullness< ENUM >
	Nullness: Enums do not have an inherent null value. More...
class	stream_from
	Stream data from the database. More...
class	stream_to
	Efficiently write data directly to a database table. More...
class	subtransaction
	"Transaction" nested within another transaction More...
class	transaction
	transaction Standard back-end transaction, templatised on isolation level. More...
class	transaction_base
	Interface definition (and common code) for "transaction" classes. More...
class	transaction_focus
	Base class for things that monopolise a transaction's attention. More...
struct	stacktrace_placeholder
	There is no std::stacktrace on this system. Use a placeholder. More...
struct	from_table_t
	Marker for stream_from constructors: "stream from table.". More...
struct	from_query_t
	Marker for stream_from constructors: "stream from query.". More...
struct	thread_safety_model
	Descriptor of library's thread-safety model. More...
struct	byte_char_traits
	Custom std::char_trast if the compiler does not provide one. More...
class	zview
	Marker-type wrapper: zero-terminated std::string_view. More...

Typedefs
using	table_path = std::initializer_list< std::string_view >
	Representation of a PostgreSQL table path. More...
using	fieldstream = basic_fieldstream< char >
using	ilostream = basic_ilostream< char >
using	olostream = basic_olostream< char >
using	lostream = basic_lostream< char >
using	ctx = conversion_context const &
	Convenience alias: const reference to a pqxx::conversion_context. More...
using	work = transaction< isolation_level::read_committed, write_policy::read_write >
	The default transaction type. More...
using	read_transaction = transaction< isolation_level::read_committed, write_policy::read_only >
	Read-only transaction. More...
using	sl = std::source_location
	Convenience alias for std::source_location. It's just too long. More...
using	st = stacktrace_placeholder
	Placeholder for future std::stacktrace. More...
using	oid = unsigned int
	PostgreSQL database row identifier. More...
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 = std::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...
template<typename TYPE >
using	strip_t = std::remove_cvref_t< TYPE >
	Remove any constness, volatile, and reference-ness from a type. More...
template<std::ranges::range CONTAINER>
using	value_type = std::remove_cvref_t< std::ranges::range_value_t< CONTAINER > >
	The type of a container's elements. More...
using	bytes_view = std::span< std::byte const >
	Type alias for a view of bytes. More...
using	writable_bytes_view = std::span< std::byte >
	Type alias for a view of writable bytes. More...
using	bytes = std::vector< std::byte >
	Type alias for a container containing bytes. More...

Enumerations
enum	skip_init : int { nothing , openssl , crypto }
	Flags for skipping initialisation of SSL-related libraries. More...
enum class	error_verbosity : int { terse = 0 , normal = 1 , verbose = 2 }
	Error verbosity levels. More...
enum class	encoding_group {   unknown , ascii_safe , two_tier , gb18030 ,   sjis }
enum class	write_policy { read_only , read_write }
	Should a transaction be read-only, or read-write? More...
enum	isolation_level { read_committed , repeatable_read , serializable }
	Transaction isolation levels. More...
enum class	format : int { text = 0 , binary = 1 }
	Format code: is data text or binary? More...

Functions
template<>
constexpr std::string_view	name_type< ExecStatusType > () noexcept
::PGresult *	real_res (pqxx::internal::pq::PGresult *ptr) noexcept
	Cast a pqxx::internal::pq::PGresult pointer back to its real type. More...
::PGresult const *	real_res (pqxx::internal::pq::PGresult const *ptr) noexcept
	Cast a pqxx::internal::pq::PGresult pointer back to its real type. More...
int	pq_n_tuples (pqxx::internal::pq::PGresult const *ptr) noexcept
	Wrapper for PQntuples() that deals in our placeholder types. More...
template<typename... T>
void	parse_composite (ctx c, std::string_view text, T &...fields)
	Parse a string representation of a value of a composite type. More...
template<typename... T>
std::size_t	composite_size_buffer (T const &...fields) noexcept
	Estimate the buffer size needed to represent a value of a composite type. More...
template<typename... T>
zview	composite_into_buf (ctx c, std::span< char > buf, T const &...fields)
	Render a series of values as a single composite SQL value. More...
template<typename... T>
char *	composite_into_buf (char *begin, char *end, T const &...fields)
	Render a series of values as a single composite SQL value. More...
template<skip_init... SKIP>
void	skip_init_ssl () noexcept
	Control initialisation of OpenSSL and libcrypto libraries. 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, ctx c={})
	Convert a field's value to type T. More...
template<typename T >
T	from_string (field_ref const &value, ctx c={})
	Convert a field's value to type T. More...
template<>
std::nullptr_t	from_string< std::nullptr_t > (field const &value, ctx c)
	Convert a field's value to nullptr_t. More...
template<>
PQXX_LIBEXPORT std::string	to_string (field_ref const &value, ctx)
	Convert a field_ref to a string. More...
template<>
PQXX_LIBEXPORT std::string	to_string (field const &value, ctx)
	Convert a field to a string. More...
template<typename T >
constexpr format	param_format (std::optional< T > const &value)
template<typename... Args>
constexpr format	param_format (std::variant< Args... > const &value)
template<typename T >
T	from_string (std::stringstream const &text, ctx c={})
template<typename T , typename... Args>
format	param_format (std::unique_ptr< T, Args... > const &value)
template<typename T >
format	param_format (std::shared_ptr< T > const &value)
template<nonbinary_range T>
constexpr format	param_format (T const &)
	We don't know how to pass array params in binary format, so pass as text. More...
template<typename TYPE >
PQXX_INLINE_COV std::string	to_string (TYPE const &value, ctx c)
	Convert a value to a readable string that PostgreSQL will understand. More...
template<>
std::string	to_string (float const &value, ctx c)
template<>
std::string	to_string (double const &value, ctx c)
template<>
std::string	to_string (long double const &value, ctx c)
template<>
std::string	to_string (std::stringstream const &value, ctx)
template<typename T >
void	into_string (T const &value, std::string &out, ctx c={})
template<>
constexpr std::string_view	name_type< encoding_group > () noexcept
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) noexcept
template<std::forward_iterator ITER, typename ACCESS >
std::string	separated_list (std::string_view sep, ITER begin, ITER end, ACCESS access, ctx c={})
	Represent sequence of values as a string, joined by a given separator. More...
template<std::forward_iterator ITER>
std::string	separated_list (std::string_view sep, ITER begin, ITER end, ctx c={})
	Render sequence as a string, using given separator between items. More...
template<std::ranges::range CONTAINER>
std::string	separated_list (std::string_view sep, CONTAINER &&con, ctx c={})
	Render items in a container 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, ctx c={})
	Render items in a tuple as a string, using given separator. More...
template<typename TUPLE , std::size_t INDEX = 0>
std::string	separated_list (std::string_view sep, TUPLE const &t, ctx c={})
template<typename... TYPE>
constexpr std::size_t	size_buffer (TYPE const &...value) noexcept
	Estimate how much buffer space is needed to represent values as a string. More...
template<typename TYPE >
	requires (pqxx::internal::to_buf_7< TYPE > or pqxx::internal::to_buf_8< TYPE >) const eval bool supports_to_buf_8()
	Is the libpqxx 8 version of to_buf() supported for TYPE? More...
template<typename TYPE >
std::string_view	to_buf (std::span< char > buf, TYPE const &value, ctx c={})
	Represent value as SQL text, optionally using buf as storage. More...
template<typename TYPE >
std::size_t	into_buf (std::span< char > buf, TYPE const &value, ctx c={})
	Write an SQL representation of value into buf. More...
template<typename TYPE >
	requires (pqxx::internal::from_string_7< TYPE > or pqxx::internal::from_string_8< TYPE >) const eval bool supports_from_string_8()
	Is the libpqxx 8 version of from_string() supported for TYPE? More...
template<typename TYPE >
TYPE	from_string (std::string_view text, ctx c={})
	Parse a value in postgres' text format as a TYPE. More...
template<>
std::string_view	from_string (std::string_view text, ctx)
	"Convert" a std::string_view to a std::string_view. More...
template<typename T >
void	from_string (std::string_view text, T &value, ctx c={})
	Attempt to convert postgres-generated string to given built-in object. More...
template<typename TYPE >
std::string	to_string (TYPE const &value, ctx c={})
	Convert a value to a readable string that PostgreSQL will understand. More...
template<typename... TYPE>
std::vector< std::string_view >	to_buf (char *begin, char const *end, TYPE... value)
	Convert multiple values to strings inside a single buffer. More...
template<typename... TYPE>
std::vector< std::string_view >	to_buf_multi (ctx c, std::span< char > buf, TYPE... value)
	Convert multiple values to strings inside a single buffer. More...
template<typename... TYPE>
std::vector< std::string_view >	to_buf_multi (std::span< char > buf, TYPE... value)
	Convert multiple values to strings inside a single buffer. 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 >
constexpr bool	has_null () noexcept
	Does TYPE have one or more inherent null values? More...
template<typename TYPE >
constexpr bool	always_null () noexcept
	Is a value of TYPE always null? More...
template<typename TYPE >
constexpr bool	is_null (TYPE const &value) noexcept
	Is value a null? More...
template<typename TYPE >
constexpr TYPE	make_null () requires(pqxx
	Return a null value of TYPE. More...
template<typename TYPE >
constexpr format	param_format (TYPE const &)
	What's the preferred format for passing non-null parameters of this type? More...
template<typename TRANSACTION_CALLBACK >
std::invoke_result_t< TRANSACTION_CALLBACK >	perform (TRANSACTION_CALLBACK &&callback, int attempts, sl loc=sl::current())
	Simple way to execute a transaction with automatic retry. More...
template<typename TRANSACTION_CALLBACK >
std::invoke_result_t< TRANSACTION_CALLBACK >	perform (TRANSACTION_CALLBACK &&callback, sl loc=sl::current())
	Simple way to execute a transaction with automatic retry. More...
template<typename TYPE >
constexpr std::string_view	name_type () noexcept
	Return human-readable name for TYPE. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< std::string > () noexcept
	Specialisation to save on startup work & produce friendlier output. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< std::string_view > () noexcept
	Specialisation to save on startup work & produce friendlier output. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< char const * > () noexcept
template<>
constexpr PQXX_PURE std::string_view	name_type< bool > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< short > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< int > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< long > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< long long > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< unsigned short > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< unsigned > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< unsigned long > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< unsigned long long > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< float > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< double > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< long double > () noexcept
	Specialisation to save on startup work. More...
template<>
constexpr PQXX_PURE std::string_view	name_type< std::nullptr_t > () noexcept
	Specialisation to save on startup work. More...
template<typename TO , typename FROM >
TO	check_cast (FROM value, std::string_view description, sl loc=sl::current()) requires(std
	Cast a numeric value to another type, or throw if it underflows/overflows. More...
PQXX_LIBEXPORT thread_safety_model	describe_thread_safety ()
	Describe thread safety available in this build. More...
template<potential_binary TYPE>
bytes_view	binary_cast (TYPE const &data)
	Cast binary data to a type that libpqxx will recognise as binary. More...
template<char_sized CHAR, typename SIZE >
bytes_view	binary_cast (CHAR const *data, SIZE size)
	Construct a type that libpqxx will recognise as binary. More...
template<>
constexpr std::string_view	name_type< zview > () noexcept
constexpr PQXX_ZARGS zview	operator""_zv (char const str[], std::size_t len) noexcept
	Support zview literals. More...
constexpr bool	operator== (char const lhs[], pqxx::zview rhs) noexcept
	Disambiguating comparison operator: leave it to std::string_view. More...
constexpr bool	operator!= (char const lhs[], pqxx::zview rhs) noexcept
	Disambiguating comparison operator: leave it to std::string_view. More...

Variables
template<>
constexpr std::string_view	type_name< ExecStatusType > {"ExecStatusType"}
template<typename T >
concept	ZKey_ZValues
	Concept: T is a range of pairs of zero-terminated strings. More...
template<pqxx::internal::integer T>
constexpr bool	is_unquoted_safe< T > {true}
template<>
constexpr bool	is_unquoted_safe< bool > {true}
template<nonbinary_range T>
constexpr bool	is_sql_array< T > {true}
template<>
constexpr std::string_view	type_name< encoding_group > {"encoding_group"}
template<typename T >
concept	has_less = std::copy_constructible<T> and requires(T n) { n < n; }
	Concept: T supports copying, and less-than operator. More...
template<typename T >
concept	has_equal = requires(T n) { n == n; }
	Concept: T supports equality comparison. More...
template<typename TYPE >
constexpr bool	is_sql_array {false}
	Does this type translate to an SQL array? More...
template<typename TYPE >
constexpr bool	is_unquoted_safe {false}
	Can we use this type in arrays and composite types without quoting them? More...
template<typename T >
constexpr char	array_separator {','}
	Element separator between SQL array elements of this type. More...
constexpr from_table_t	from_table
	Pass this to a stream_from constructor to stream table contents. More...
constexpr from_query_t	from_query
	Pass this to a stream_from constructor to stream query results. More...
template<typename CHAR >
concept	char_sized = (sizeof(CHAR) == 1)
	A type one byte in size. More...
template<typename STRING >
concept	char_string
	Concept: Any type that we can read as a string of char. More...
template<typename RANGE >
concept	char_strings
	Concept: Anything we can iterate to get things we can read as strings. More...
template<typename DATA >
concept	potential_binary
	Concept: Anything we might want to treat as binary data. More...
template<typename T >
concept	binary
	Concept: Binary string, akin to std::string for binary data. More...
template<typename T >
concept	nonbinary_range
	A series of something that's not bytes. More...
template<typename T >
concept	not_borrowed
	Concept: A value that's not just a reference to values elsewhere. More...
template<typename E >
concept	enum_type = std::is_enum_v<E>
	Concept: A C++ enum type. More...
template<typename TYPE >
std::string const	type_name
	A human-readable name for a type, used in error messages and such. More...
constexpr oid	oid_none {0}
	The "null" oid. More...
constexpr std::string_view const	version {"8.0.1"}
	Full libpqxx version string. More...
constexpr std::string_view const	abi_version {"8.0"}
	Libpqxx ABI version string: major and minor version, but no patch. More...
constexpr int const	version_major {8}
	Major libpqxx version number. (E.g. for libpqxx 9.3.1, this will be 9.) More...
constexpr int const	version_minor {0}
	Minor libpqxx version number. (E.g. for libpqxx 9.3.1, this will be 3.) More...
constexpr int const	version_patch {1}
	Libpqxx patch version number. (E.g. for libpqxx 9.3.1, this will be 1.) More...
template<typename T >
concept	ZString
	Concept: T is a known zero-terminated string type. More...

Detailed Description

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

Handling of SQL arrays.

Copyright (c) 2000-2026, 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.

Implementation of libpqxx exception classes.

Copyright (c) 2000-2026, 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.

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

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

Copyright (c) 2000-2026, 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.

Enum type for supporting encodings in libpqxx

Copyright (c) 2000-2026, 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.

Internal string encodings support for libpqxx

Copyright (c) 2000-2026, 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.

Result loops.

Copyright (c) 2000-2026, 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.

Stream iterators.

Copyright (c) 2000-2026, 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.

Transaction focus: types which monopolise a transaction's attention.

Copyright (c) 2000-2026, 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.

---

Class Documentation

pqxx::notification

struct pqxx::notification

An incoming notification.

PostgreSQL extends SQL with a "message bus" using the LISTEN and NOTIFY commands. In libpqxx you use connection::listen() and (optionally) transaction_base::notify().

When you receive a notification for which you have been listening, your handler receives it in the form of a notification object.

Warning

These structs are meant for extremely short lifespans: the fields reference memory that may become invalid as soon as your handler has been called.

Collaboration diagram for pqxx::notification:

Class Members
int	backend_pid	Process ID of the backend that sent the notification. This can be useful in situations where a multiple clients are listening on the same channel, and also send notifications on it. In those situations, it often makes sense for a client to ignore its own incoming notifications, but handle all others on the same channel in some way. To check for that, compare this process ID to the return value of the connection's backendpid().
zview	channel	Channel name. The notification logic will only pass the notification to a handler which was registered to listen on this exact name.
connection &	conn	The connection which received the notification. There will be no backend transaction active on the connection when your handler gets called, but there may be a nontransaction. (This is a special transaction type in libpqxx which does not start a transaction on the backend.)
zview	payload	Optional payload text. If the notification did not carry a payload, the string will be empty.

pqxx::stream_query

class pqxx::stream_query

template<typename... TYPE>
class pqxx::stream_query< TYPE >

pqxx::from_table_t

struct pqxx::from_table_t

Marker for stream_from constructors: "stream from table.".

Deprecated:

Use stream_from::table() instead.

pqxx::from_query_t

struct pqxx::from_query_t

Marker for stream_from constructors: "stream from query.".

Deprecated:

Use stream_from::query() instead.

pqxx::thread_safety_model

struct pqxx::thread_safety_model

Descriptor of library's thread-safety model.

This describes what the library knows about various risks to thread-safety.

Class Members
string	description	A human-readable description of any thread-safety issues.
bool	safe_kerberos	Is Kerberos thread-safe? Warning Is currently always false. If your application uses Kerberos, all accesses to libpqxx or Kerberos must be serialized. Confine their use to a single thread, or protect it with a global lock.
bool	safe_libpq	Is the underlying libpq build thread-safe?

Typedef Documentation

bytes

using pqxx::bytes = typedef std::vector<std::byte>

Type alias for a container containing bytes.

bytes_view

using pqxx::bytes_view = typedef std::span<std::byte const>

Type alias for a view of bytes.

ctx

using pqxx::ctx = typedef conversion_context const &

Convenience alias: const reference to a pqxx::conversion_context.

Because we need to squeeze this type into lots of function signatures, it helps to have a very terse name for it.

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>

Deprecated:

Read a field using field::as<...>() or field::c_str().

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>

oid

using pqxx::oid = typedef unsigned int

PostgreSQL database row identifier.

olostream

using pqxx::olostream = typedef basic_olostream<char>

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.

sl

using pqxx::sl = typedef std::source_location

Convenience alias for std::source_location. It's just too long.

st

using pqxx::st = typedef stacktrace_placeholder

Placeholder for future std::stacktrace.

strip_t

template<typename TYPE >

using pqxx::strip_t = typedef std::remove_cvref_t<TYPE>

Remove any constness, volatile, and reference-ness from a type.

Deprecated:

Use std::remove_cvref instead.

table_path

using pqxx::table_path = typedef std::initializer_list<std::string_view>

Representation of a PostgreSQL table path.

A "table path" consists of a table name, optionally prefixed by a schema name, which in turn is optionally prefixed by a database name.

A minimal example of a table path would be {mytable}. But a table path may also take the forms {myschema,mytable} or {mydb,myschema,mytable}.

value_type

template<std::ranges::range CONTAINER>

using pqxx::value_type = typedef std::remove_cvref_t<std::ranges::range_value_t<CONTAINER> >

The type of a container's elements.

At the time of writing there's a similar thing in std::experimental, which we may or may not end up using for this.

writable_bytes_view

using pqxx::writable_bytes_view = typedef std::span<std::byte>

Type alias for a view of writable bytes.

Enumeration Type Documentation

encoding_group

enum pqxx::encoding_group

strong

The supported types of text encoding supported.

See: https://www.postgresql.org/docs/current/static/multibyte.html#CHARSET-TABLE

This enum does not name the individual supported encodings, only the various schemes for determining where in memory a character ends and a potential new one may begin. This is crucial for determining such things as where a string ends: a byte in the text may look like an ASCII quote character, but is it really the closing quote, or is it merely a byte inside a multibyte character which just happens to have the same value as the ASCII value for a quote? This is not an issue in most encodings, but it can happen in others, and can pose a real security risk.

Some functions in libpqxx need to know the type of encoding used in a given text in order to find closing quotes or field boundaries.

All supported encodings are supersets of ASCII: any byte with a value between 0 and 127 inclusive at the beginning of a character is always a simple, single-byte ASCII character.

Enumerator
unknown	Default: indeterminate encoding. All we know is it supports ASCII. This is the minimum assumption, and therefore the default. We can parse simple SQL values such as integers without knowing more about their encoding, since all supported encodings are supersets of ASCII. An integer string consists of only digits and an optional sign, so we can parse that without knowing the encoding. But, for example, a quoted string is harder because we can't know a priori whether a byte that looks like the closing quote is indeed an ASCII quote character, or just a trail byte in a multibyte character which just happens to have the same numeric value. Conversions that may run into this problem will throw an exception if the uncoding is unknown, even if the actual uncertainty about the meaning of a byte never occurs. That may seem a little pedantic, but it's better to go through the pain in testing than to risk missing the problem until your code goes into production.
ascii_safe	"ASCII-safe" encodings. This includes all single-byte encodings (such as ASCII or ISO 8859-15) but also all other encodings where there is no risk of ever confusing a byte inside a multibyte character for an ASCII character. UTF-8 is an example of an ASCII-safe encoding, as are the EUC encodings. This property makes encodings very efficient to parse: to find the next character (if any), just move to the next byte.
two_tier	Low byte is ASCII, high byte starts a 2-byte character. Both BIG5 and UHC work like this. The details vary, but we don't need to validate the input in detail; we just need to be sure that we don't mistake a byte in a multibyte character for a separate special ASCII character (or vice versa if the input ends in mid-character). UHC is, for our purposes, ASCII-safe so long as none of the characters you're looking for are ASCII letters. So in that common case, feel free to use the ascii_safe glyph scanner instead.
gb18030	Non-ASCII-safe: GB18030 for Chinese (Traditional & Simplified). This also covers older subsets such as GBK.
sjis	Non-ASCII-safe: Japanese JIS and Shift JIS.

error_verbosity

enum pqxx::error_verbosity : int

strong

Error verbosity levels.

Enumerator
terse
normal
verbose

format

enum pqxx::format : int

strong

Format code: is data text or binary?

Binary-compatible with libpq's format codes.

Why use an int for this when a single bit would be enough? Because this maps directly to the C-level values used in libpq.

Enumerator
text
binary

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

skip_init

enum pqxx::skip_init : int

Flags for skipping initialisation of SSL-related libraries.

When a running process makes its first SSL connection to a database through libpqxx, libpq automatically initialises the OpenSSL and libcrypto libraries. But there are scenarios in which you may want to suppress that.

This enum is a way to express this. Pass values of this enum to pqxx::skip_init_ssl as template arguments.

Enumerator
nothing	A do-nothing flag that does not affect anything.
openssl	Skip initialisation of OpenSSL library.
crypto	Skip initialisation of libcrypto.

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

always_null()

template<typename TYPE >

constexpr bool pqxx::always_null ( )

inlineconstexprnoexcept

Is a value of TYPE always null?

This is the case for some special types, such as std::nullopt_t.

binary_cast() [1/2]

template<char_sized CHAR, typename SIZE >

bytes_view pqxx::binary_cast	(	CHAR const *	data,
		SIZE	size
	)

Construct a type that libpqxx will recognise as binary.

Takes a data pointer and a size, without being too strict about their types, and constructs a pqxx::bytes_view pointing to the same data.

This makes it a little easier to turn binary data, in whatever form you happen to have it, into binary data as libpqxx understands it.

binary_cast() [2/2]

template<potential_binary TYPE>

bytes_view pqxx::binary_cast ( TYPE const &  data )

inline

Cast binary data to a type that libpqxx will recognise as binary.

There are many different formats for storing binary data in memory. You may have yours as a std::string, or a std::vector<uchar_t>, or one of many other types. In libpqxx we commend a container of std::byte.

For libpqxx to recognise your data as binary, we recommend using a pqxx::bytes, or a pqxx::bytes_view; but any contiguous block of std::byte should do.

Use binary_cast as a convenience helper to cast your data as a pqxx::bytes_view.

Warning

You must keep the storage holding the actual data alive for as long as you might use this function's return value.

check_cast()

template<typename TO , typename FROM >

TO pqxx::check_cast ( FROM  value, std::string_view  description, sl  loc = sl::current()  )

inline

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.

composite_into_buf() [1/2]

template<typename... T>

char* pqxx::composite_into_buf ( char *  begin, char *  end, T const &...  fields  )

inline

Render a series of values as a single composite SQL value.

composite_into_buf() [2/2]

template<typename... T>

zview pqxx::composite_into_buf ( ctx  c, std::span< char >  buf, T const &...  fields  )

inline

Render a series of values as a single composite SQL value.

You may use this as a helper while implementing your own string_traits for a composite type.

Parameters

loc	An std::source_location, so that any error messages can report this as the place where the error occurred. This is probably more useful to you than a location inside this function itself.

After writing the composite's text representation to buf, this will append a terminating zero. This facilitates usage where the resulting SQL string gets passed in as a query parameter.

composite_size_buffer()

template<typename... T>

std::size_t pqxx::composite_size_buffer ( T const &...  fields )

inlinenoexcept

Estimate the buffer size needed to represent a value of a composite type.

Returns a conservative estimate.

describe_thread_safety()

pqxx::thread_safety_model pqxx::describe_thread_safety

(

)

Describe thread safety available in this build.

from_string() [1/6]

template<typename T >

T pqxx::from_string ( field const &  value, ctx  c = {}  )

inline

Convert a field's value to type T.

Unlike the "regular" from_string, this knows how to deal with null values.

from_string() [2/6]

template<typename T >

T pqxx::from_string ( field_ref const &  value, ctx  c = {}  )

inline

Convert a field's value to type T.

Unlike the "regular" from_string, this knows how to deal with null values.

from_string() [3/6]

template<typename TYPE >

TYPE pqxx::from_string ( std::string_view  text, ctx  c = {}  )

inline

Parse a value in postgres' text format as a 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. If in some cases this behaviour should be inappropriate, convert to something bigger such as long int first and then truncate the resulting value.

Only the simplest possible conversions are supported. Fancy features like hexadecimal or octal, spurious signs, or exponent notation won't work. Whitespace is not stripped away. Only the kinds of strings that come out of PostgreSQL and out of to_string() can be converted.

from_string() [4/6]

template<>

std::string_view pqxx::from_string ( std::string_view  text, ctx    )

inline

"Convert" a std::string_view to a std::string_view.

Just returns its input.

Warning

Of course the result is only valid for as long as the original string remains valid! Never access the string referenced by the return value after the original has been destroyed.

from_string() [5/6]

template<typename T >

void pqxx::from_string ( std::string_view  text, T &  value, ctx  c = {}  )

inline

Attempt to convert postgres-generated string to given built-in object.

This is like the single-argument form of the function, except instead of returning the value, it sets value.

You may find this more convenient in that it infers the type you want from the argument you pass. But there are disadvantages: it requires an assignment operator, and it may be less efficient.

from_string() [6/6]

template<typename T >

T pqxx::from_string ( std::stringstream const &  text, ctx  c = {}  )

inline

from_string< std::nullptr_t >()

template<>

std::nullptr_t pqxx::from_string< std::nullptr_t > ( field const &  value, ctx  c  )

inline

Convert a field's value to nullptr_t.

Yes, you read that right. This conversion does nothing useful. It always returns nullptr.

Except... what if the field is not null? In that case, this throws conversion_error.

has_null()

template<typename TYPE >

constexpr bool pqxx::has_null ( )

inlineconstexprnoexcept

Does TYPE have one or more inherent null values?

Some types, such as pointers, have natural null values built in. Most types do not: an integer is never null (even if it may be zero), a C++ string is never null (even if it may be empty), and so on.

This is different from an SQL field containing a null value, but in libpqxx you can treat them pretty much the same.

into_buf()

template<typename TYPE >

std::size_t pqxx::into_buf ( std::span< char >  buf, TYPE const &  value, ctx  c = {}  )

inline

Write an SQL representation of value into buf.

This calls string_traits<TYPE>::to_buf(), but bridges some API version differences.

Returns

The number of SQL text bytes written into buf. There is no terminating zero.

into_string() [1/2]

template<typename T >

void pqxx::into_string ( T const &  value, std::string &  out, ctx  c = {}  )

inline

into_string() [2/2]

template<typename TYPE >

void pqxx::into_string ( TYPE const &  value, std::string &  out  )

inline

Convert a value to a readable string that PostgreSQL will understand.

This variant of to_string can sometimes save a bit of time in loops, by re-using a std::string for multiple conversions.

is_null()

template<typename TYPE >

constexpr bool pqxx::is_null ( TYPE const &  value )

inlineconstexprnoexcept

Is value a null?

make_null()

template<typename TYPE >

constexpr TYPE pqxx::make_null ( )

inlineconstexpr

Return a null value of TYPE.

Only available for types that have a null value.

There may be multiple null values, or even ones that look the same but which don't compare as equal, as is the case in SQL.

name_type()

template<typename TYPE >

constexpr std::string_view pqxx::name_type ( )

inlineconstexprnoexcept

Return human-readable name for TYPE.

name_type< bool >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< bool > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< char const * >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< char const * > ( )

inlineconstexprnoexcept

name_type< double >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< double > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< encoding_group >()

template<>

constexpr std::string_view pqxx::name_type< encoding_group > ( )

inlineconstexprnoexcept

name_type< ExecStatusType >()

template<>

constexpr std::string_view pqxx::name_type< ExecStatusType > ( )

inlineconstexprnoexcept

name_type< float >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< float > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< int >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< int > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< long >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< long > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< long double >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< long double > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< long long >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< long long > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< short >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< short > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< std::nullptr_t >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< std::nullptr_t > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< std::string >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< std::string > ( )

inlineconstexprnoexcept

Specialisation to save on startup work & produce friendlier output.

name_type< std::string_view >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< std::string_view > ( )

inlineconstexprnoexcept

Specialisation to save on startup work & produce friendlier output.

name_type< unsigned >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< unsigned > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< unsigned long >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< unsigned long > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< unsigned long long >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< unsigned long long > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< unsigned short >()

template<>

constexpr PQXX_PURE std::string_view pqxx::name_type< unsigned short > ( )

inlineconstexprnoexcept

Specialisation to save on startup work.

name_type< zview >()

template<>

constexpr std::string_view pqxx::name_type< zview > ( )

inlineconstexprnoexcept

operator!=()

constexpr bool pqxx::operator!= ( char const  lhs[], pqxx::zview  rhs  )

inlineconstexprnoexcept

Disambiguating comparison operator: leave it to std::string_view.

operator""_zv()

constexpr PQXX_ZARGS zview pqxx::operator""_zv ( char const  str[], std::size_t  len  )

constexprnoexcept

Support zview literals.

You can "import" this selectively into your namespace, without pulling in all of the pqxx namespace:

using pqxx::operator"" _zv;

operator+() [1/3]

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

inlinenoexcept

operator+() [2/3]

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

inline

operator+() [3/3]

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

inline

operator<<()

template<typename CHAR >

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

inline

Write a result field to any type of stream.

Deprecated:

The C++ streams library is not great to work with. In particular, error handling is easy to get wrong. So you're probably better off doing this by hand.

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;

operator==()

constexpr bool pqxx::operator== ( char const  lhs[], pqxx::zview  rhs  )

inlineconstexprnoexcept

Disambiguating comparison operator: leave it to std::string_view.

param_format() [1/6]

template<typename T >

constexpr format pqxx::param_format ( std::optional< T > const &  value )

inlineconstexpr

param_format() [2/6]

template<typename T >

format pqxx::param_format

(

std::shared_ptr< T > const &

value

)

param_format() [3/6]

template<typename T , typename... Args>

format pqxx::param_format ( std::unique_ptr< T, Args... > const &  value )

inline

param_format() [4/6]

template<typename... Args>

constexpr format pqxx::param_format ( std::variant< Args... > const &  value )

inlineconstexpr

param_format() [5/6]

template<nonbinary_range T>

constexpr format pqxx::param_format ( T const &  )

inlineconstexpr

We don't know how to pass array params in binary format, so pass as text.

A contiguous range of std::byte is a binary string; other ranges are not.

param_format() [6/6]

template<typename TYPE >

constexpr format pqxx::param_format ( TYPE const &  )

inlineconstexpr

What's the preferred format for passing non-null parameters of this type?

This affects how we pass parameters of TYPE when calling parameterised statements or prepared statements.

Generally we pass parameters in text format, but binary strings are the exception. We also pass nulls in binary format, so this function need not handle null values.

parse_composite()

template<typename... T>

void pqxx::parse_composite ( ctx  c, std::string_view  text, T &...  fields  )

inline

Parse a string representation of a value of a composite type.

Warning

This code is still experimental. Use with care.

You may use this as a helper while implementing your own string_traits for a composite type.

This function interprets text as the string representation of a value of some composite type, and sets each of fields to the respective values of its fields. The field types must be copy-assignable.

The number of fields must match the number of fields in the composite type, and there must not be any other text in the input. The function is meant to handle any value string that the backend can produce, but not necessarily every valid alternative spelling.

Fields in composite types can be null. When this happens, the C++ type of the corresponding field reference must be of a type that can handle nulls. If you are working with a type that does not have an inherent null value, such as e.g. int, consider using std::optional.

perform() [1/2]

template<typename TRANSACTION_CALLBACK >

std::invoke_result_t<TRANSACTION_CALLBACK> pqxx::perform ( TRANSACTION_CALLBACK &&  callback, int  attempts, sl  loc = sl::current()  )

inline

Simple way to execute a transaction with automatic retry.

Executes your transaction code as a callback. Repeats it until it completes normally, or it throws an error other than the few libpqxx-generated exceptions that the framework understands, or after a given number of failed attempts, or if the transaction ends in an "in-doubt" state.

(An in-doubt state is one where libpqxx cannot determine whether the server finally committed a transaction or not. This can happen if the network connection to the server is lost just while we're waiting for its reply to a "commit" statement. The server may have completed the commit, or not, but it can't tell you because there's no longer a connection.

Using this still takes a bit of care. If your callback makes use of data from the database, you'll probably have to query that data within your callback. If the attempt to perform your callback fails, and the framework tries again, you'll be in a new transaction and the data in the database may have changed under your feet.

Also be careful about changing variables or data structures from within your callback. The run may still fail, and perhaps get run again. The ideal way to do it (in most cases) is to return your result from your callback, and change your program's data state only after perform completes successfully.

Parameters

callback	Transaction code that can be called with no arguments.
attempts	Maximum number of times to attempt performing callback. Must be greater than zero.

Returns

Whatever your callback returns.

perform() [2/2]

template<typename TRANSACTION_CALLBACK >

std::invoke_result_t<TRANSACTION_CALLBACK> pqxx::perform ( TRANSACTION_CALLBACK &&  callback, sl  loc = sl::current()  )

inline

Simple way to execute a transaction with automatic retry.

Executes your transaction code as a callback. Repeats it until it completes normally, or it throws an error other than the few libpqxx-generated exceptions that the framework understands, or after a given number of failed attempts, or if the transaction ends in an "in-doubt" state.

(An in-doubt state is one where libpqxx cannot determine whether the server finally committed a transaction or not. This can happen if the network connection to the server is lost just while we're waiting for its reply to a "commit" statement. The server may have completed the commit, or not, but it can't tell you because there's no longer a connection.

Using this still takes a bit of care. If your callback makes use of data from the database, you'll probably have to query that data within your callback. If the attempt to perform your callback fails, and the framework tries again, you'll be in a new transaction and the data in the database may have changed under your feet.

Also be careful about changing variables or data structures from within your callback. The run may still fail, and perhaps get run again. The ideal way to do it (in most cases) is to return your result from your callback, and change your program's data state only after perform completes successfully.

Parameters

callback	Transaction code that can be called with no arguments.
attempts	Maximum number of times to attempt performing callback. Must be greater than zero.

Returns

Whatever your callback returns.

pq_n_tuples()

int pqxx::pq_n_tuples ( pqxx::internal::pq::PGresult const *  ptr )

inlinenoexcept

Wrapper for PQntuples() that deals in our placeholder types.

real_res() [1/2]

::PGresult* pqxx::real_res ( pqxx::internal::pq::PGresult *  ptr )

inlinenoexcept

Cast a pqxx::internal::pq::PGresult pointer back to its real type.

There's really no such thing as a pqxx::internal::pq::PGresult. It's just a placeholder we use in our headers so we can talk about this type without actually importing its definition.

It's not a forward declaration though: before we can use these pointers, we have to cast them back to their original type. This does that.

real_res() [2/2]

::PGresult const* pqxx::real_res ( pqxx::internal::pq::PGresult const *  ptr )

inlinenoexcept

Cast a pqxx::internal::pq::PGresult pointer back to its real type.

There's really no such thing as a pqxx::internal::pq::PGresult. It's just a placeholder we use in our headers so we can talk about this type without actually importing its definition.

It's not a forward declaration though: before we can use these pointers, we have to cast them back to their original type. This does that.

requires() [1/2]

template<typename TYPE >

pqxx::requires

(

pqxx::internal::from_string_7< TYPE > or pqxx::internal::from_string_8< TYPE >

)

const

Is the libpqxx 8 version of from_string() supported for TYPE?

The pqxx::string_traits specialisation for TYPE must support either the 7.x to_buf API or the 8.x one.

requires() [2/2]

template<typename TYPE >

pqxx::requires

(

pqxx::internal::to_buf_7< TYPE > or pqxx::internal::to_buf_8< TYPE >

)

const

Is the libpqxx 8 version of to_buf() supported for TYPE?

The pqxx::string_traits specialisation for TYPE must support either the 7.x to_buf API or the 8.x one.

The real reason this function exists is to make the compiler check for API compliance... and if necessary, give a helpful error message. For that, a requires is better than a static_assert(). However, we can't use it in the calling function's signature, since it requires a definition for the relevant specialisation of pqxx::string_traits before the calling function's. That complicates things.

separated_list() [1/5]

template<std::ranges::range CONTAINER>

std::string pqxx::separated_list ( std::string_view  sep, CONTAINER &&  con, ctx  c = {}  )

inline

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

separated_list() [2/5]

template<std::forward_iterator ITER, typename ACCESS >

std::string pqxx::separated_list ( std::string_view  sep, ITER  begin, ITER  end, ACCESS  access, ctx  c = {}  )

inline

Represent sequence of values as a string, joined by a given separator.

Use this to turn e.g. the numbers 1, 2, and 3 into a string "1, 2, 3".

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

separated_list() [3/5]

template<std::forward_iterator ITER>

std::string pqxx::separated_list ( std::string_view  sep, ITER  begin, ITER  end, ctx  c = {}  )

inline

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

separated_list() [4/5]

template<typename TUPLE , std::size_t INDEX = 0, typename ACCESS >

std::string pqxx::separated_list ( std::string_view  sep, TUPLE const &  t, ACCESS const &  access, ctx  c = {}  )

inline

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

separated_list() [5/5]

template<typename TUPLE , std::size_t INDEX = 0>

std::string pqxx::separated_list ( std::string_view  sep, TUPLE const &  t, ctx  c = {}  )

inline

size_buffer()

template<typename... TYPE>

constexpr std::size_t pqxx::size_buffer ( TYPE const &...  value )

inlineconstexprnoexcept

Estimate how much buffer space is needed to represent values as a string.

The estimate may be a little pessimistic, if it saves time.

skip_init_ssl()

template<skip_init... SKIP>

void pqxx::skip_init_ssl ( )

inlinenoexcept

Control initialisation of OpenSSL and libcrypto libraries.

By default, libpq initialises the openssl and libcrypto libraries when your process first opens an SSL connection to a database. But this may not be what you want: perhaps your application (or some other library it uses) already initialises one or both of these libraries.

Call this function to stop libpq from initialising one or the other of these. Pass as arguments each of the skip_init flags for which of the libraries whose initialisation you want to prevent.

Warning

Each call to this function overwrites the effects of any previous call. So if you make one call to skip OpenSSL initialisation, and then another to skip libcrypto initialisation, the first call will do nothing.

Examples:

• To let libpq initialise libcrypto but not OpenSSL: skip_init_ssl<pqxx::skip_init::openssl>();
• To let libpq know that it should not initialise either:

  skip_init_ssl<pqxx::skip_init::openssl, pqxx::skip_init::crypto>();

• To say explicitly that you want libpq to initialise both: skip_init_ssl<pqxx::skip_init::nothing>();

to_buf() [1/2]

template<typename... TYPE>

std::vector<std::string_view> pqxx::to_buf ( char *  begin, char const *  end, TYPE...  value  )

inline

Convert multiple values to strings inside a single buffer.

There must be enough room for all values, or this will throw conversion_overrun. You can obtain a conservative estimate of the buffer space required by calling size_buffer() on the values.

The std::string_view results may point into the buffer, so don't assume that they will remain valid after you destruct or move the buffer.

to_buf() [2/2]

template<typename TYPE >

std::string_view pqxx::to_buf ( std::span< char >  buf, TYPE const &  value, ctx  c = {}  )

inline

Represent value as SQL text, optionally using buf as storage.

This calls string_traits<TYPE>::to_buf(), but bridges some API version differences.

to_buf_multi() [1/2]

template<typename... TYPE>

std::vector<std::string_view> pqxx::to_buf_multi ( ctx  c, std::span< char >  buf, TYPE...  value  )

inline

Convert multiple values to strings inside a single buffer.

There must be enough room for all values, or this will throw conversion_overrun. You can obtain a conservative estimate of the buffer space required by calling size_buffer() on the values.

The std::string_view results may point into the buffer, so don't assume that they will remain valid after you destruct or move the buffer.

to_buf_multi() [2/2]

template<typename... TYPE>

std::vector<std::string_view> pqxx::to_buf_multi ( std::span< char >  buf, TYPE...  value  )

inline

Convert multiple values to strings inside a single buffer.

There must be enough room for all values, or this will throw conversion_overrun. You can obtain a conservative estimate of the buffer space required by calling size_buffer() on the values.

The std::string_view results may point into the buffer, so don't assume that they will remain valid after you destruct or move the buffer.

Warning

This version of the function does not take a pqxx::conversion_context argument. Prefer the version that does take one, and pass (insofar as possible) a pqxx::encoding_group and a std::source_location.

to_string() [1/8]

template<>

std::string pqxx::to_string ( double const &  value, ctx  c  )

inline

to_string() [2/8]

template<>

PQXX_LIBEXPORT std::string pqxx::to_string ( field const &  value, ctx    )

inline

Convert a field to a string.

to_string() [3/8]

template<>

PQXX_LIBEXPORT std::string pqxx::to_string ( field_ref const &  value, ctx    )

inline

Convert a field_ref to a string.

to_string() [4/8]

template<>

std::string pqxx::to_string ( float const &  value, ctx  c  )

inline

to_string() [5/8]

template<>

std::string pqxx::to_string ( long double const &  value, ctx  c  )

inline

to_string() [6/8]

template<>

std::string pqxx::to_string ( std::stringstream const &  value, ctx    )

inline

to_string() [7/8]

template<typename TYPE >

PQXX_INLINE_COV std::string pqxx::to_string ( TYPE const &  value, ctx  c = {}  )

inline

Convert a value to a readable string that PostgreSQL will understand.

The conversion does no special formatting, and ignores any locale settings. The resulting string will be human-readable and in a format suitable for use in SQL queries. It won't have niceties such as "thousands separators" though.

to_string() [8/8]

template<typename TYPE >

std::string pqxx::to_string ( TYPE const &  value, ctx  c = {}  )

inline

Convert a value to a readable string that PostgreSQL will understand.

The conversion does no special formatting, and ignores any locale settings. The resulting string will be human-readable and in a format suitable for use in SQL queries. It won't have niceties such as "thousands separators" though.

Variable Documentation

abi_version

constexpr std::string_view const pqxx::abi_version {"8.0"}

inlineconstexpr

Libpqxx ABI version string: major and minor version, but no patch.

For example, for libpqxx 9.3.1, this will be "9.3".

Warning

Many factors can influence the library's ABI, including compiler, compiler version, and compilation options. An ABI can also change radically during release candidate development. So don't count fully on it.

array_separator

template<typename T >

constexpr char pqxx::array_separator {','}

inlineconstexpr

Element separator between SQL array elements of this type.

binary

template<typename T >

concept pqxx::binary

Initial value:

= std::ranges::contiguous_range<T> and
                 std::same_as<std::remove_cv_t<value_type<T>>, std::byte>

Concept: Binary string, akin to std::string for binary data.

Any type that satisfies this concept can represent an SQL BYTEA value.

A binary has a begin(), end(), size(), and @data(). Each byte is a std::byte, and they must all be laid out contiguously in memory so we can reference them by a pointer.

char_sized

template<typename CHAR >

concept pqxx::char_sized = (sizeof(CHAR) == 1)

A type one byte in size.

char_string

template<typename STRING >

concept pqxx::char_string

Initial value:

= std::ranges::contiguous_range<STRING> and
                      std::same_as<std::remove_cv_t<value_type<STRING>>, char>

Concept: Any type that we can read as a string of char.

char_strings

template<typename RANGE >

concept pqxx::char_strings

Initial value:

= std::ranges::range<RANGE> and
                       char_string<std::remove_cv_t<value_type<RANGE>>>

Concept: Anything we can iterate to get things we can read as strings.

enum_type

template<typename E >

concept pqxx::enum_type = std::is_enum_v<E>

Concept: A C++ enum type.

from_query

constexpr from_query_t pqxx::from_query

constexpr

Pass this to a stream_from constructor to stream query results.

Deprecated:

Use transaction_base::stream instead of stream_from.

from_table

constexpr from_table_t pqxx::from_table

constexpr

Pass this to a stream_from constructor to stream table contents.

Deprecated:

Use transaction_base::stream instead of stream_from.

has_equal

template<typename T >

concept pqxx::has_equal = requires(T n) { n == n; }

Concept: T supports equality comparison.

has_less

template<typename T >

concept pqxx::has_less = std::copy_constructible<T> and requires(T n) { n < n; }

Concept: T supports copying, and less-than operator.

is_sql_array

template<typename TYPE >

constexpr bool pqxx::is_sql_array {false}

inlineconstexpr

Does this type translate to an SQL array?

Specialisations may override this to be true for container types.

This may not always be a black-and-white choice. For instance, a std::string is a container, but normally it translates to an SQL string, not an SQL array.

is_sql_array< T >

template<nonbinary_range T>

constexpr bool pqxx::is_sql_array< T > {true}

inlineconstexpr

is_unquoted_safe

template<typename TYPE >

constexpr bool pqxx::is_unquoted_safe< std::shared_ptr< T > > {false}

inlineconstexpr

Can we use this type in arrays and composite types without quoting them?

Define this as true only if values of TYPE can never contain any special characters that might need escaping or confuse the parsing of array or composite * types, such as commas, quotes, parentheses, braces, newlines, and so on.

When converting a value of such a type to a string in an array or a field in a composite type, we do not need to add quotes, nor escape any special characters.

This is just an optimisation, so it defaults to false to err on the side of slow correctness.

is_unquoted_safe< bool >

template<>

constexpr bool pqxx::is_unquoted_safe< bool > {true}

inlineconstexpr

is_unquoted_safe< T >

template<pqxx::internal::integer T>

constexpr bool pqxx::is_unquoted_safe< T > {true}

inlineconstexpr

nonbinary_range

template<typename T >

concept pqxx::nonbinary_range

Initial value:

=
  std::ranges::range<T> and
  not std::same_as<
    std::remove_cvref_t<std::ranges::range_reference_t<T>>, std::byte> and
  not std::same_as<
    std::remove_cvref_t<std::ranges::range_reference_t<T>>, char>

A series of something that's not bytes.

not_borrowed

template<typename T >

concept pqxx::not_borrowed

Initial value:

=
  not std::is_reference_v<T> and not std::is_pointer_v<T> and
  not std::ranges::borrowed_range<T>

Concept: A value that's not just a reference to values elsewhere.

This can be an important distinction when returning values. For example, if a function creates a std::string in a local variable, it can't then return a std::string_view referring to that string. By the time the caller gets to it, the underlying data is no longer valid.

In most cases these are decisions we make while writing code. But when converting data to a caller-selected type, there are situations where it's safe to return a view and there are situations where it's not.

oid_none

constexpr oid pqxx::oid_none {0}

constexpr

The "null" oid.

potential_binary

template<typename DATA >

concept pqxx::potential_binary

Initial value:

=
  std::ranges::contiguous_range<DATA> and char_sized<value_type<DATA>> and
  not std::is_reference_v<value_type<DATA>>

Concept: Anything we might want to treat as binary data.

type_name

template<typename TYPE >

std::string const pqxx::type_name

Initial value:

{
  pqxx::internal::demangle_type_name(typeid(TYPE).name())}

A human-readable name for a type, used in error messages and such.

Actually this may not always be very user-friendly. It uses std::type_info::name(). On gcc-like compilers we try to demangle its output. Visual Studio produces human-friendly names out of the box.

This variable is not inline. Inlining it gives rise to "memory leak" warnings from asan, the address sanitizer, possibly from use of std::type_info::name.

type_name< encoding_group >

template<>

constexpr std::string_view pqxx::type_name< encoding_group > {"encoding_group"}

inlineconstexpr

type_name< ExecStatusType >

template<>

constexpr std::string_view pqxx::type_name< ExecStatusType > {"ExecStatusType"}

inlineconstexpr

version

constexpr std::string_view const pqxx::version {"8.0.1"}

inlineconstexpr

Full libpqxx version string.

version_major

constexpr int const pqxx::version_major {8}

inlineconstexpr

Major libpqxx version number. (E.g. for libpqxx 9.3.1, this will be 9.)

version_minor

constexpr int const pqxx::version_minor {0}

inlineconstexpr

Minor libpqxx version number. (E.g. for libpqxx 9.3.1, this will be 3.)

version_patch

constexpr int const pqxx::version_patch {1}

inlineconstexpr

Libpqxx patch version number. (E.g. for libpqxx 9.3.1, this will be 1.)

For "special" versions such as pre-releases, the last component of the version string is not a simple number, and version_patch will be -1.

ZKey_ZValues

template<typename T >

concept pqxx::ZKey_ZValues

Initial value:

= std::ranges::input_range<T> and requires(T t) {
  { std::get<0>(*std::cbegin(t)) } -> ZString;
  { std::get<1>(*std::cbegin(t)) } -> ZString;
  requires(
    std::tuple_size_v<std::remove_cvref_t<decltype(*std::cbegin(t))>> == 2u);
}

Concept: T is a range of pairs of zero-terminated strings.

For example, this could be a std::map<char const *, std::string>, or a std::vector<std::pair<pqxx::zview, char const *>, or a std::array<std::array<std::string, 2>, 10>, etc.

The pairs have to be recognisable as pairs at compile time. It's not enough to pass a container of std::vector and ensure at run time that they each contain 2 elements.

ZString

template<typename T >

concept pqxx::ZString

Initial value:

=
  (std::is_convertible_v<std::remove_cvref_t<T>, char const *> or
   std::is_convertible_v<std::remove_cvref_t<T>, zview> or
   std::is_convertible_v<T, std::string const &>) and
  not std::is_convertible_v<T, std::nullptr_t>

Concept: T is a known zero-terminated string type.

There's no unified API for these string types. It's just a check for some known types. Any code that makes use of the concept will still have to support each of these individually.