libpqxx
7.9.0
|
The home of all libpqxx classes, functions, templates, etc. More...
Namespaces | |
internal | |
Internal items for libpqxx' own use. Do not use these yourself. | |
prepare | |
Classes | |
class | array |
An SQL array received from the database. More... | |
class | array_parser |
Low-level array parser. More... | |
class | binarystring |
Binary data corresponding to PostgreSQL's "BYTEA" binary-string type. More... | |
struct | nullness< binarystring > |
struct | string_traits< binarystring > |
String conversion traits for binarystring . More... | |
class | blob |
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 |
Base class for error-handler callbacks. More... | |
class | quiet_errorhandler |
An error handler that suppresses any previously registered error handlers. More... | |
struct | failure |
Run-time failure encountered by libpqxx, similar to std::runtime_error. More... | |
struct | broken_connection |
Exception class for lost or failed backend connection. More... | |
struct | protocol_violation |
Exception class for micommunication with the server. More... | |
struct | variable_set_to_null |
The caller attempted to set a variable to null, which is not allowed. More... | |
class | sql_error |
Exception class for failed queries. 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 it. 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 | 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 |
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... | |
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... | |
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 |
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 | 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, std::enable_if_t< std::is_enum_v< 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 |
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 | 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... | |
struct | has_generic_char_traits |
struct | has_generic_char_traits< TYPE, std::void_t< decltype(std::char_traits< TYPE >::eof)> > |
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 | connection_base = connection |
using | fieldstream = basic_fieldstream< char > |
using | ilostream = basic_ilostream< char > |
using | olostream = basic_olostream< char > |
using | lostream = basic_lostream< char > |
using | work = transaction<> |
The default transaction type. More... | |
using | read_transaction = transaction< isolation_level::read_committed, write_policy::read_only > |
Read-only transaction. 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_cv_t< std::remove_reference_t< TYPE > > |
Remove any constness, volatile, and reference-ness from a type. More... | |
template<typename CONTAINER > | |
using | value_type = strip_t< decltype(*std::begin(std::declval< CONTAINER >()))> |
The type of a container's elements. More... | |
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. More... | |
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. 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 | 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. More... | |
template<typename... T> | |
void | parse_composite (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> | |
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... | |
std::string | encrypt_password (char const user[], char const password[]) |
Encrypt a password. More... | |
std::string | encrypt_password (zview user, zview password) |
Encrypt password. More... | |
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. More... | |
template<typename T > | |
T | from_string (field const &value) |
Convert a field's value to type T . More... | |
template<> | |
std::nullptr_t | from_string< std::nullptr_t > (field const &value) |
Convert a field's value to nullptr_t . More... | |
template<> | |
std::string | to_string (field const &value) |
Convert a field to a string. More... | |
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. More... | |
template<typename ITER > | |
std::string | separated_list (std::string_view sep, ITER begin, ITER end) |
Render sequence as a string, using given separator between items. More... | |
template<typename CONTAINER > | |
auto | separated_list (std::string_view sep, CONTAINER const &c) -> typename std::enable_if<(not std::is_void< decltype(std::begin(c))>::value and not std::is_void< decltype(std::end(c))>::value), std::string >::type |
Render items in a container as a string, using given separator. More... | |
template<typename TUPLE , std::size_t INDEX = 0, typename ACCESS , typename std::enable_if<(INDEX==std::tuple_size< TUPLE >::value - 1), int >::type = 0> | |
std::string | separated_list (std::string_view, TUPLE const &t, ACCESS const &access) |
Render items in a tuple as a string, using given separator. More... | |
template<typename TUPLE , std::size_t INDEX = 0, typename 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. More... | |
template<typename TYPE > | |
TYPE | from_string (std::string_view text) |
Parse a value in postgres' text format as a TYPE. More... | |
template<> | |
std::string_view | from_string (std::string_view text) |
"Convert" a std::string_view to a std::string_view. More... | |
template<typename T > | |
void | from_string (std::string_view text, T &value) |
Attempt to convert postgres-generated string to given built-in object. More... | |
template<typename TYPE > | |
std::string | to_string (TYPE const &value) |
Convert a value to a readable string that PostgreSQL will understand. More... | |
template<typename... TYPE> | |
std::vector< std::string_view > | to_buf (char *here, char const *end, 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 | is_null (TYPE const &value) noexcept |
Is value null? More... | |
template<typename... TYPE> | |
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 > | |
constexpr format | param_format (TYPE const &) |
What's the preferred format for passing non-null parameters of this type? More... | |
template<typename TYPE > | |
zview | generic_to_buf (char *begin, char *end, TYPE const &value) |
Implement string_traits<TYPE>::to_buf by calling into_buf . More... | |
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. More... | |
template<typename TRANSACTION_CALLBACK > | |
auto | perform (TRANSACTION_CALLBACK &&callback, int attempts=3) -> std::invoke_result_t< TRANSACTION_CALLBACK > |
Simple way to execute a transaction with automatic retry. More... | |
template<typename... T> | |
constexpr void | ignore_unused (T &&...) noexcept |
Suppress compiler warning about an unused item. More... | |
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. More... | |
void | check_version () noexcept |
thread_safety_model | describe_thread_safety () |
Describe thread safety available in this build. More... | |
template<PQXX_POTENTIAL_BINARY_ARG TYPE> | |
bytes_view | binary_cast (TYPE const &data) |
Cast binary data to a type that libpqxx will recognise as binary. More... | |
template<PQXX_CHAR_SIZED_ARG CHAR, typename SIZE > | |
bytes_view | binary_cast (CHAR const *data, SIZE size) |
Construct a type that libpqxx will recognise as binary. More... | |
constexpr zview | operator""_zv (char const str[], std::size_t len) noexcept |
Support zview literals. More... | |
PQXX_DECLARE_ENUM_CONVERSION (ExecStatusType) | |
Variables | |
template<typename TYPE > | |
std::string const | type_name {internal::demangle_type_name(typeid(TYPE).name())} |
A human-readable name for a type, used in error messages and such. More... | |
template<typename 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... | |
constexpr bool | has_generic_bytes_char_traits |
constexpr oid | oid_none {0} |
The "null" oid. More... | |
The home of all libpqxx classes, functions, templates, etc.
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.
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.
using pqxx::bytes = typedef 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 pqxx::bytes_view = typedef 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.
using pqxx::connection_base = typedef connection |
using pqxx::field_size_type = typedef std::size_t |
Number of bytes in a field of database data.
using pqxx::fieldstream = typedef basic_fieldstream<char> |
field::as<...>()
or field::c_str()
. using pqxx::ilostream = typedef basic_ilostream<char> |
using pqxx::large_object_size_type = typedef int64_t |
Number of bytes in a large object.
using pqxx::lostream = typedef basic_lostream<char> |
using pqxx::olostream = typedef basic_olostream<char> |
using pqxx::read_transaction = typedef transaction<isolation_level::read_committed, write_policy::read_only> |
Read-only transaction.
using pqxx::result_difference_type = typedef int |
Difference between result sizes.
using pqxx::result_size_type = typedef int |
Number of rows in a result set.
using pqxx::row_difference_type = typedef int |
Difference between row sizes.
using pqxx::row_size_type = typedef int |
Number of fields in a row of database data.
using pqxx::strip_t = typedef std::remove_cv_t<std::remove_reference_t<TYPE> > |
Remove any constness, volatile, and reference-ness from a type.
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}
.
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.
using pqxx::work = typedef transaction<> |
The default transaction type.
|
strong |
|
strong |
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 |
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. |
|
strong |
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.
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
.
Referenced by pqxx::connection::esc_raw(), pqxx::string_traits< binarystring >::into_buf(), pqxx::connection::quote_raw(), and pqxx::transaction_base::quote_raw().
TO pqxx::check_cast | ( | FROM | value, |
std::string_view | description | ||
) |
Cast a numeric value to another type, or throw if it underflows/overflows.
Both types must be arithmetic types, and they must either be both integral or both floating-point types.
References pqxx::internal::cat2(), pqxx::internal::cmp_greater(), and ignore_unused().
|
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.
References ignore_unused(), and pqxx::internal::PQXX_VERSION_CHECK().
Referenced by pqxx::connection::connection().
char* pqxx::composite_into_buf | ( | char * | begin, |
char * | end, | ||
T const &... | fields | ||
) |
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.
References composite_size_buffer().
|
noexcept |
Estimate the buffer size needed to represent a value of a composite type.
Returns a conservative estimate.
References pqxx::internal::empty_composite_str.
Referenced by composite_into_buf().
pqxx::thread_safety_model PQXX_COLD pqxx::describe_thread_safety | ( | ) |
Describe thread safety available in this build.
References pqxx::thread_safety_model::description, pqxx::thread_safety_model::safe_kerberos, and pqxx::thread_safety_model::safe_libpq.
std::string PQXX_COLD pqxx::encrypt_password | ( | char const | user[], |
char const | password[] | ||
) |
Encrypt a password.
References pqxx::internal::pq::pqfreemem().
Referenced by encrypt_password(), and pqxx::connection::encrypt_password().
Encrypt password.
References pqxx::zview::c_str(), and encrypt_password().
std::string_view pqxx::field::as< std::string_view > | ( | ) | const |
References is_null(), and pqxx::internal::throw_null_conversion().
std::string_view pqxx::field::as< std::string_view > | ( | std::string_view const & | default_value | ) | const |
References is_null().
bool pqxx::field::to< std::string > | ( | std::string & | obj | ) | const |
References is_null().
bool pqxx::field::to< std::string > | ( | std::string & | obj, |
std::string const & | default_value | ||
) | const |
References is_null().
bool pqxx::field::to< std::string_view > | ( | std::string_view & | obj | ) | const |
References is_null().
bool pqxx::field::to< std::string_view > | ( | std::string_view & | obj, |
std::string_view const & | default_value | ||
) | const |
References is_null().
T pqxx::from_string | ( | field const & | value | ) |
Convert a field's value to type T
.
Unlike the "regular" from_string
, this knows how to deal with null values.
References pqxx::field::is_null(), pqxx::nullness< TYPE, ENABLE >::null(), pqxx::internal::throw_null_conversion(), and pqxx::field::view().
Referenced by pqxx::field::to().
TYPE pqxx::from_string | ( | std::string_view | text | ) |
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.
References pqxx::string_traits< TYPE >::from_string(), and text.
std::string_view pqxx::from_string | ( | std::string_view | text | ) |
"Convert" a std::string_view to a std::string_view.
Just returns its input.
References text.
void pqxx::from_string | ( | std::string_view | text, |
T & | value | ||
) |
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.
References text.
std::nullptr_t pqxx::from_string< std::nullptr_t > | ( | field const & | value | ) |
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.
References pqxx::field::is_null().
zview pqxx::generic_to_buf | ( | char * | begin, |
char * | end, | ||
TYPE const & | value | ||
) |
Implement string_traits<TYPE>::to_buf
by calling into_buf
.
When you specialise string_traits
for a new type, most of the time its to_buf
implementation has no special optimisation tricks and just writes its text into the buffer it receives from the caller, starting at the beginning.
In that common situation, you can implement to_buf
as just a call to generic_to_buf
. It will call into_buf
and return the right result for to_buf
.
References is_null().
Referenced by pqxx::string_traits< binarystring >::to_buf(), and pqxx::string_traits< range< TYPE > >::to_buf().
|
constexprnoexcept |
Suppress compiler warning about an unused item.
Referenced by pqxx::params::append(), check_cast(), check_version(), pqxx::stream_from::complete(), and pqxx::internal::error_string().
void pqxx::into_string | ( | TYPE const & | value, |
std::string & | out | ||
) |
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.
|
constexprnoexcept |
Is value
null?
Referenced by pqxx::params::append(), pqxx::field::as(), pqxx::field::composite_to(), pqxx::exclusive_bound< TYPE >::exclusive_bound(), field::as< std::string_view >(), field::to< std::string >(), field::to< std::string_view >(), generic_to_buf(), pqxx::inclusive_bound< TYPE >::inclusive_bound(), pqxx::field::operator==(), pqxx::connection::quote(), and pqxx::field::to().
|
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.
|
constexprnoexcept |
|
noexcept |
std:: basic_ostream<CHAR>& pqxx::operator<< | ( | std::basic_ostream< CHAR > & | s, |
field const & | value | ||
) |
Write a result field to any type of stream.
This can be convenient when writing a field to an output stream. More importantly, it lets you write a field to e.g. a stringstream
which you can then use to read, format and convert the field in ways that to() does not support.
Example: parse a field into a variable of the nonstandard "<tt>long long</tt>" type.
|
constexpr |
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.
References text.
Referenced by pqxx::params::make_c_params().
void pqxx::parse_composite | ( | pqxx::internal::encoding_group | enc, |
std::string_view | text, | ||
T &... | fields | ||
) |
Parse a string representation of a value of a composite type.
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
.
References pqxx::internal::get_glyph_scanner(), and text.
Referenced by pqxx::field::composite_to(), and parse_composite().
void pqxx::parse_composite | ( | std::string_view | text, |
T &... | fields | ||
) |
Parse a string representation of a value of a composite type.
For proper encoding support, use the composite-type support in the field
class.
References parse_composite(), and text.
auto pqxx::perform | ( | TRANSACTION_CALLBACK && | callback, |
int | attempts = 3 |
||
) | -> std::invoke_result_t<TRANSACTION_CALLBACK> |
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.
callback | Transaction code that can be called with no arguments. |
attempts | Maximum number of times to attempt performing callback. Must be greater than zero. |
pqxx::PQXX_DECLARE_ENUM_CONVERSION | ( | ExecStatusType | ) |
auto pqxx::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.
References separated_list().
std::string pqxx::separated_list | ( | std::string_view | sep, |
ITER | begin, | ||
ITER | end | ||
) |
Render sequence as a string, using given separator between items.
References separated_list().
std::string pqxx::separated_list | ( | std::string_view | sep, |
ITER | begin, | ||
ITER | end, | ||
ACCESS | access | ||
) |
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".
sep | separator string (to be placed between items) |
begin | beginning of items sequence |
end | end of items sequence |
access | functor defining how to dereference sequence elements |
References to_string().
Referenced by pqxx::connection::quote_columns(), pqxx::connection::quote_table(), and separated_list().
std::string pqxx::separated_list | ( | std::string_view | sep, |
TUPLE const & | t | ||
) |
References separated_list().
std::string pqxx::separated_list | ( | std::string_view | sep, |
TUPLE const & | t, | ||
ACCESS const & | access | ||
) |
Render items in a tuple as a string, using given separator.
References to_string().
|
noexcept |
Estimate how much buffer space is needed to represent values as a string.
The estimate may be a little pessimistic, if it saves time. It also includes room for a terminating zero after each value.
|
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.
Examples:
skip_init_ssl<pqxx::skip_init::openssl>();
skip_init_ssl<pqxx::skip_init::nothing>();
References pqxx::internal::skip_init_ssl().
std::vector<std::string_view> pqxx::to_buf | ( | char * | here, |
char const * | end, | ||
TYPE... | value | ||
) |
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.
std::string pqxx::to_string | ( | field const & | value | ) |
Convert a field to a string.
References pqxx::field::c_str().
Referenced by pqxx::connection::adorn_name(), pqxx::params::append(), pqxx::binarystring::at(), pqxx::connection::quote(), separated_list(), and pqxx::result::table_column().
std::string pqxx::to_string | ( | TYPE const & | value | ) |
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.
|
delete |
Forbidden specialisation: underlying buffer immediately goes out of scope.
|
constexpr |
Element separator between SQL array elements of this type.
|
constexpr |
Pass this to a stream_from
constructor to stream query results.
Referenced by pqxx::stream_from::query().
|
constexpr |
Pass this to a stream_from
constructor to stream table contents.
Referenced by pqxx::stream_from::raw_table().
|
constexpr |
|
constexpr |
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.
|
constexpr |
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.
|
constexpr |
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
.