Loading...
Searching...
No Matches
pqxx Namespace Reference

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

## Namespaces

namespace | internal
| Internal items for libpqxx' own use. Do not use these yourself.
namespace | prepare

## Classes

struct | argument_error
| Invalid argument passed to libpqxx, similar to std::invalid_argument. More...
class | array
| An SQL array received from the database. More...
class | array_parser
| Low-level parser for C++ arrays. More...
class | basic_fieldstream
| Input stream that gets its data from a result field. More...
class | basic_ilostream
| Input stream that gets its data from a large object. More...
class | basic_lostream
| Stream that reads and writes a large object. More...
class | basic_olostream
| Output stream that writes data back to a large object. More...
class | binarystring
| Binary data corresponding to PostgreSQL's "BYTEA" binary-string type. More...
class | blob
struct | broken_connection
| Exception class for lost or failed backend connection. More...
struct | byte_char_traits
| Custom `std::char_trast` if the compiler does not provide one. More...
struct | check_violation
class | connecting
| An ongoing, non-blocking stepping stone to a connection. More...
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
class | exclusive_bound
| An exclusive boundary value to a pqxx::range. 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 | forbidden_conversion
| String traits for a forbidden type conversion. More...
struct | foreign_key_violation
struct | from_query_t
| Marker for stream_from constructors: "stream from query.". More...
struct | from_table_t
| Marker for stream_from constructors: "stream from table.". More...
struct | has_generic_char_traits
struct | has_generic_char_traits< TYPE, std::void_t< decltype(std::char_traits< TYPE >::eof)> >
struct | in_doubt_error
| "Help, I don't know whether transaction was committed successfully!" More...
class | inclusive_bound
| An inclusive boundary value to a pqxx::range. 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_bound
| An unlimited boundary value to a pqxx::range. 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
struct | notification
| An incoming notification. More...
class | notification_receiver
struct | nullness
| Traits describing a type's "null value," if any. More...
struct | nullness< binarystring >
struct | nullness< bytes >
struct | nullness< bytes_view >
struct | nullness< char * >
struct | nullness< char const * >
struct | nullness< char[N]>
struct | nullness< ENUM, std::enable_if_t< std::is_enum_v< ENUM > > >
| Nullness: Enums do not have an inherent null value. More...
struct | nullness< range< TYPE > >
| A range type does not have an innate null value. More...
struct | nullness< std::array< T, N > >
struct | nullness< std::monostate >
struct | nullness< std::nullopt_t >
struct | nullness< std::nullptr_t >
struct | nullness< std::optional< T > >
struct | nullness< std::shared_ptr< T > >
struct | nullness< std::string >
struct | nullness< std::string_view >
| There's no real null for `std::string_view`. More...
struct | nullness< std::stringstream >
struct | nullness< std::unique_ptr< T > >
struct | nullness< std::variant< T... > >
struct | nullness< std::vector< T, Args... > >
struct | nullness< T, std::enable_if_t< std::is_arithmetic_v< T > > >
| The built-in arithmetic types do not have inherent null values. More...
struct | nullness< zview >
struct | out_of_memory
class | params
| Build a parameter list for a parameterised or prepared statement. More...
class | pipeline
| Processes several queries in FIFO manner, optimized for high throughput. More...
class | placeholders
| Generate parameter placeholders for use in an SQL statement. 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 | prepped
| A string that is the name of a prepared statement. More...
struct | protocol_violation
| Exception class for micommunication with the server. More...
class | quiet_errorhandler
class | range
| A C++ equivalent to PostgreSQL's range types. More...
class | range_bound
| A range boundary value. 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 | 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
| Stream data from the database. More...
class | stream_query
class | stream_to
| Efficiently write data directly to a database table. More...
struct | string_traits
| Traits class for use in string conversions. More...
struct | string_traits< binarystring >
| String conversion traits for `binarystring`. More...
struct | string_traits< bool >
struct | string_traits< bytes >
struct | string_traits< bytes_view >
struct | string_traits< char * >
| String traits for non-const C-style string ("pointer to char"). More...
struct | string_traits< char >
| You cannot convert a `char` to/from SQL. More...
struct | string_traits< char const * >
| String traits for C-style string ("pointer to char const"). More...
struct | string_traits< char[N]>
| String traits for C-style string constant ("pointer to array of char"). More...
struct | string_traits< double >
struct | string_traits< float >
struct | string_traits< int >
struct | string_traits< long >
struct | string_traits< long double >
struct | string_traits< long long >
struct | string_traits< pqxx::internal::encoding_group >
struct | string_traits< range< TYPE > >
| String conversions for a range type. More...
struct | string_traits< short >
struct | string_traits< signed char >
| You cannot convert a `signed char` to/from SQL. More...
struct | string_traits< std::array< T, N > >
struct | string_traits< std::byte >
| You cannot convert a `std::byte` to/from SQL. More...
struct | string_traits< std::monostate >
struct | string_traits< std::nullopt_t >
struct | string_traits< std::nullptr_t >
struct | string_traits< std::optional< T > >
struct | string_traits< std::shared_ptr< T > >
struct | string_traits< std::string >
struct | string_traits< std::string_view >
| String traits for `string_view`. More...
struct | string_traits< std::stringstream >
struct | string_traits< std::unique_ptr< T, Args... > >
struct | string_traits< std::variant< T... > >
struct | string_traits< std::vector< T, Args... > >
struct | string_traits< unsigned >
struct | string_traits< unsigned char >
| You cannot convert an `unsigned char` to/from SQL. More...
struct | string_traits< unsigned long >
struct | string_traits< unsigned long long >
struct | string_traits< unsigned short >
struct | string_traits< zview >
| String traits for `zview`. 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_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 | 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_null
| Could not convert null value: target type does not support null. More...
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...
struct | variable_set_to_null
| The caller attempted to set a variable to null, which is not allowed. 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.
using | connection_base = connection
using | fieldstream = basic_fieldstream< char >
using | oid = unsigned int
| PostgreSQL database row identifier.
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.
using | result_difference_type = int
| Difference between result sizes.
using | row_size_type = int
| Number of fields in a row of database data.
using | row_difference_type = int
| Difference between row sizes.
using | field_size_type = std::size_t
| Number of bytes in a field of database data.
using | large_object_size_type = int64_t
| Number of bytes in a large object.
template<typename TYPE >
using | strip_t = std::remove_cv_t< std::remove_reference_t< TYPE > >
| Remove any constness, volatile, and reference-ness from a type.
template<typename CONTAINER >
using | value_type = strip_t< decltype(*std::begin(std::declval< CONTAINER >()))>
| The type of a container's elements.
using | bytes = std::conditional< has_generic_bytes_char_traits, std::basic_string< std::byte >, std::basic_string< std::byte, byte_char_traits > >::type
| Type alias for a container containing bytes.
using | bytes_view = std::conditional< has_generic_bytes_char_traits, std::basic_string_view< std::byte >, std::basic_string_view< std::byte, byte_char_traits > >::type
| Type alias for a view of bytes.

## 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.
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<typename... T>
void | parse_composite (pqxx::internal::encoding_group enc, std::string_view text, T &...fields)
| Parse a string representation of a value of a composite type.
template<typename... T>
void | parse_composite (std::string_view text, T &...fields)
| Parse a string representation of a value of a composite type.
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.
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.
template<skip_init... SKIP>
void | skip_init_ssl () noexcept
| Control initialisation of OpenSSL and libcrypto libraries.
std::string PQXX_LIBEXPORT | encrypt_password (char const user[], char const password[])
| Encrypt a password.
std::string | encrypt_password (zview user, zview password)
| Encrypt password.
template<>
bool | field::to< std::string > (std::string &obj) const
template<>
bool | field::to< std::string > (std::string &obj, std::string const &default_value) const
template<>
bool | field::to< std::string_view > (std::string_view &obj) const
template<>
bool | field::to< std::string_view > (std::string_view &obj, std::string_view const &default_value) const
template<>
std::string_view | field::as< std::string_view > () const
template<>
std::string_view | field::as< std::string_view > (std::string_view const &default_value) const
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.
template<typename T >
T | from_string (field const &value)
| Convert a field's value to type `T`.
template<>
std::nullptr_t | from_string< std::nullptr_t > (field const &value)
| Convert a field's value to `nullptr_t`.
template<>
PQXX_LIBEXPORT std::string | to_string (field const &value)
| Convert a field to a string.
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)
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<>
constexpr format | param_format (bytes const &)
template<>
constexpr format | param_format (bytes_view const &)
template<typename T , typename... Args>
constexpr format | param_format (std::vector< T, Args... > const &)
| We don't know how to pass array params in binary format, so pass as text.
template<typename... Args>
constexpr format | param_format (std::vector< std::byte, Args... > const &)
| A `std::vector<std::byte>` is a binary string. Other vectors are not.
template<typename T , typename... Args, Args... args>
constexpr format | param_format (std::array< T, args... > const &)
| We don't know how to pass array params in binary format, so pass as text.
template<typename... Args, Args... args>
constexpr format | param_format (std::array< std::byte, args... > const &)
| An array of `std::byte` is a binary string.
template<typename T >
std::string | to_string (T const &value)
template<>
std::string | to_string (float const &value)
template<>
std::string | to_string (double const &value)
template<>
std::string | to_string (long double const &value)
template<>
std::string | to_string (std::stringstream const &value)
template<typename T >
void | into_string (T const &value, std::string &out)
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<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.
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.
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.
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.
template<typename TUPLE , std::size_t INDEX = 0, typename std::enable_if<(INDEX<=std::tuple_size< TUPLE >::value), int >::type = 0>
std::string | separated_list (std::string_view sep, TUPLE const &t)
template<typename TYPE >
void | oops_forbidden_conversion () noexcept
| Nonexistent function to indicate a disallowed type conversion.
template<>
std::string_view | transaction_base::query_value< std::string_view > (zview query, std::string_view desc)=delete
| Forbidden specialisation: underlying buffer immediately goes out of scope.
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.
template<typename... T>
constexpr void | ignore_unused (T &&...) noexcept
| Suppress compiler warning about an unused item.
template<typename TO , typename FROM >
TO | check_cast (FROM value, std::string_view description)
| Cast a numeric value to another type, or throw if it underflows/overflows.
PQXX_PRIVATE void | check_version () noexcept
PQXX_LIBEXPORT thread_safety_model | describe_thread_safety ()
| Describe thread safety available in this build.
template<typename TYPE >
bytes_view | binary_cast (TYPE const &data)
| Cast binary data to a type that libpqxx will recognise as binary.
template<typename CHAR , typename SIZE >
bytes_view | binary_cast (CHAR const *data, SIZE size)
| Construct a type that libpqxx will recognise as binary.
constexpr zview | operator""_zv (char const str[], std::size_t len) noexcept
| Support zview literals.

## Variables

template<>
std::string_view const | type_name< ExecStatusType > { "ExecStatusType" }
template<>
constexpr bool | is_unquoted_safe< short > {true}
template<>
constexpr bool | is_unquoted_safe< unsigned short > {true}
template<>
constexpr bool | is_unquoted_safe< int > {true}
template<>
constexpr bool | is_unquoted_safe< unsigned > {true}
template<>
constexpr bool | is_unquoted_safe< long > {true}
template<>
constexpr bool | is_unquoted_safe< unsigned long > {true}
template<>
constexpr bool | is_unquoted_safe< long long > {true}
template<>
constexpr bool | is_unquoted_safe< unsigned long long > {true}
template<>
constexpr bool | is_unquoted_safe< float > {true}
template<>
constexpr bool | is_unquoted_safe< double > {true}
template<>
constexpr bool | is_unquoted_safe< long double > {true}
template<>
constexpr bool | is_unquoted_safe< bool > {true}
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.
constexpr from_table_t | from_table
| Pass this to a `stream_from` constructor to stream table contents.
constexpr from_query_t | from_query
| Pass this to a `stream_from` constructor to stream query results.
constexpr bool | has_generic_bytes_char_traits
constexpr oid | oid_none {0}
| The "null" oid.

## Detailed Description

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

Handling of SQL arrays.

Copyright (c) 2000-2024, 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-2024, 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-2024, 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-2024, 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-2024, 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-2024, 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::from_query_t

struct pqxx::from_query_t

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

Deprecated:
  Use stream_from::query() instead.

## pqxx::from_table_t

struct pqxx::from_table_t

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

Deprecated:
  Use stream_from::table() instead.

## 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:
[legend]

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::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 = false

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 = false | Is the underlying libpq build thread-safe?

## Typedef Documentation

## connection_base

using pqxx::connection_base = typedef connection

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

## fieldstream

using pqxx::fieldstream = typedef basic_fieldstream<char>

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

## strip_t

template<typename TYPE >

using pqxx::strip_t = typedef std::remove_cv_t<std::remove_reference_t<TYPE> >

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

Deprecated:
  In C++20 we'll replace this with std::remove_cvref.

## 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<typename CONTAINER >

using pqxx::value_type = typedef strip_t<decltype(*std::begin(std::declval<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.

## Enumeration Type Documentation

## format

enum class pqxx::format : int

strong

Format code: is data text or binary?

Binary-compatible with libpq's format codes.

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

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

## Function Documentation

## binary_cast() [1/2]

template<typename 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<typename TYPE >

bytes_view pqxx::binary_cast | ( | TYPE const & | data | ) |

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.

But for libpqxx to recognise your data as binary, it needs to be a `pqxx::bytes`, or a `pqxx::bytes_view`; or in C++20 or better, any contiguous block of `std::byte`.

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

Warning
  There are two things you should be aware of! First, the data must be contiguous in memory. In C++20 the compiler will enforce this, but in C++17 it's your own problem. Second, you must keep the object where you store 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
| ) |  |

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.

## check_version()

PQXX_PRIVATE void pqxx::check_version | ( |  | ) |

inline noexcept

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.

## composite_into_buf()

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.

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.

## composite_size_buffer()

template<typename... T>

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

inline noexcept

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

Returns a conservative estimate.

## encrypt_password() [1/2]

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

Encrypt a password.

Deprecated:
  Use connection::encrypt_password instead.

## encrypt_password() [2/2]

std::string pqxx::encrypt_password | ( | zview | user,
|  | zview | password
| ) |  |

inline

Encrypt password.

Deprecated:
  Use connection::encrypt_password instead.

## from_string()

template<typename T >

T pqxx::from_string | ( | field const & | value | ) |

inline

Convert a field's value to type `T`.

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

## from_string< std::nullptr_t >()

template<>

std::nullptr_t pqxx::from_string< std::nullptr_t > | ( | field const & | value | ) |

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.

## oops_forbidden_conversion()

template<typename TYPE >

void pqxx::oops_forbidden_conversion | ( |  | ) |

noexcept

Nonexistent function to indicate a disallowed type conversion.

There is no implementation for this function, so any reference to it will fail to link. The error message will mention the function name and its template argument, as a deliberate message to an application developer that their code is attempting to use a deliberately unsupported conversion.

There are some C++ types that you may want to convert to or from SQL values, but which libpqxx deliberately does not support. Take `char` for example: we define no conversions for that type because it is not inherently clear whether whether the corresponding SQL type should be a single-character string, a small integer, a raw byte value, etc. The intention could differ from one call site to the next.

If an application attempts to convert these types, we try to make sure that the compiler will issue an error involving this function name, and mention the type, as a hint as to the reason.

## operator""_zv()

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

constexpr noexcept

Support zview literals.

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

using pqxx::operator"" _zv;

## 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;
pqxx::result
Result set containing data returned by a query or command.
Definition result.hxx:92

## parse_composite() [1/2]

template<typename... T>

void pqxx::parse_composite | ( | pqxx::internal::encoding_group | enc,
|  | 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`.

## parse_composite() [2/2]

template<typename... T>

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

inline

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

Warning
  This version only works for UTF-8 and single-byte encodings.

For proper encoding support, use the composite-type support in the `field` class.

## perform()

template<typename TRANSACTION_CALLBACK >

auto pqxx::perform | ( | TRANSACTION_CALLBACK && | callback,
|  | int | attempts = `3`
| ) |  | -> std::invoke_result_t<TRANSACTION_CALLBACK>

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.

## separated_list()

template<typename ITER , typename ACCESS >

std::string pqxx::separated_list | ( | std::string_view | sep,
|  | ITER | begin,
|  | ITER | end,
|  | ACCESS | access
| ) |  |

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

## skip_init_ssl()

template<skip_init... SKIP>

void pqxx::skip_init_ssl | ( |  | ) |

inline noexcept

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>();`

## Variable Documentation

## 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_generic_bytes_char_traits

constexpr bool pqxx::has_generic_bytes_char_traits

inline constexpr

Initial value:
=
has_generic_char_traits<std::byte>::value

## type_name

template<typename TYPE >

std::string const pqxx::type_name {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`.