libpqxx
7.0.7
|
The home of all libpqxx classes, functions, templates, etc. More...
Namespaces | |
internal | |
Private namespace for libpqxx's internal use; do not access. | |
prepare | |
Dedicated namespace for helper types related to prepared statements. | |
Classes | |
struct | argument_error |
Invalid argument passed to libpqxx, similar to std::invalid_argument. More... | |
class | array_parser |
Low-level array parser. More... | |
class | basic_fieldstream |
Input stream that gets its data from a result field. More... | |
class | basic_ilostream |
Input stream that gets its data from a large object. More... | |
class | basic_lostream |
Stream that reads and writes a large object. More... | |
class | basic_olostream |
Output stream that writes data back to a large object. More... | |
class | binarystring |
Binary data corresponding to PostgreSQL's "BYTEA" binary-string type. More... | |
struct | broken_connection |
Exception class for lost or failed backend connection. More... | |
struct | check_violation |
class | connection |
Connection to a database. More... | |
class | const_result_iterator |
Iterator for rows in a result. Use as result::const_iterator. More... | |
class | const_reverse_result_iterator |
Reverse iterator for result. Use as result::const_reverse_iterator. More... | |
class | const_reverse_row_iterator |
Reverse iterator for a row. Use as row::const_reverse_iterator. More... | |
class | const_row_iterator |
Iterator for fields in a row. Use as row::const_iterator. More... | |
struct | conversion_error |
Value conversion failed, e.g. when converting "Hello" to int. More... | |
struct | conversion_overrun |
Could not convert value to string: not enough buffer space. More... | |
class | cursor_base |
Common definitions for cursor types. More... | |
struct | data_exception |
Error in data provided to SQL statement. More... | |
class | dbtransaction |
Abstract transaction base class: bracket transactions on the database. More... | |
struct | deadlock_detected |
The ongoing transaction has deadlocked. Retrying it may help. More... | |
struct | disk_full |
class | errorhandler |
Base class for error-handler callbacks. More... | |
struct | failure |
Run-time failure encountered by libpqxx, similar to std::runtime_error. More... | |
struct | feature_not_supported |
Database feature not supported in current setup. More... | |
class | field |
Reference to a field in a result set. More... | |
class | field_streambuf |
struct | foreign_key_violation |
class | icursor_iterator |
Approximate istream_iterator for icursorstream. More... | |
class | icursorstream |
Simple read-only cursor represented as a stream of results. More... | |
struct | in_doubt_error |
"Help, I don't know whether transaction was committed successfully!" More... | |
struct | insufficient_privilege |
struct | insufficient_resources |
Resource shortage on the server. More... | |
struct | integrity_constraint_violation |
struct | internal_error |
Internal error in libpqxx library. More... | |
struct | invalid_cursor_name |
struct | invalid_cursor_state |
struct | invalid_sql_statement_name |
class | largeobject |
Identity of a large object. More... | |
class | largeobject_streambuf |
Streambuf to use large objects in standard I/O streams. More... | |
class | largeobjectaccess |
Accessor for large object's contents. More... | |
struct | no_null |
Nullness traits describing a type which does not have a null value. More... | |
class | nontransaction |
Simple "transaction" class offering no transactional integrity. More... | |
struct | not_null_violation |
class | notification_receiver |
struct | nullness |
Traits describing a type's "null value," if any. More... | |
struct | nullness< ENUM, std::enable_if_t< std::is_enum_v< ENUM > > > |
Nullness: Enums do not have an inherent null value. More... | |
struct | out_of_memory |
class | pipeline |
Processes several queries in FIFO manner, optimized for high throughput. More... | |
struct | plpgsql_error |
PL/pgSQL error. More... | |
struct | plpgsql_no_data_found |
struct | plpgsql_raise |
Exception raised in PL/pgSQL procedure. More... | |
struct | plpgsql_too_many_rows |
class | quiet_errorhandler |
An error handler that suppresses any previously registered error handlers. More... | |
struct | range_error |
Something is out of range, similar to std::out_of_range. More... | |
struct | restrict_violation |
class | result |
Result set containing data returned by a query or command. More... | |
class | robusttransaction |
Slightly slower, better-fortified version of transaction. More... | |
class | row |
Reference to one row in a result. More... | |
struct | serialization_failure |
Transaction failed to serialize. Please retry it. More... | |
class | sql_error |
Exception class for failed queries. More... | |
class | stateless_cursor |
"Stateless cursor" class: easy API for retrieving parts of result sets More... | |
struct | statement_completion_unknown |
We can't tell whether our last statement succeeded. More... | |
class | stream_from |
Efficiently pull data directly out of a table. More... | |
class | stream_to |
Efficiently write data directly to a database table. More... | |
struct | string_traits |
Traits class for use in string conversions. More... | |
class | subtransaction |
"Transaction" nested within another transaction More... | |
struct | syntax_error |
struct | thread_safety_model |
Descriptor of library's thread-safety model. More... | |
struct | too_many_connections |
class | transaction |
Standard back-end transaction, templatized on isolation level. More... | |
class | transaction_base |
Interface definition (and common code) for "transaction" classes. More... | |
struct | transaction_rollback |
The backend saw itself forced to roll back the ongoing transaction. More... | |
struct | undefined_column |
struct | undefined_function |
struct | undefined_table |
struct | unexpected_rows |
Query returned an unexpected number of rows. More... | |
struct | unique_violation |
struct | usage_error |
Error in usage of libpqxx library, similar to std::logic_error. More... | |
class | zview |
Marker-type wrapper: zero-terminated std::string_view . More... | |
Typedefs | |
using | connection_base = connection |
using | fieldstream = basic_fieldstream< char > |
using | ilostream = basic_ilostream< char > |
using | olostream = basic_olostream< char > |
using | lostream = basic_lostream< char > |
using | 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 = 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... | |
Enumerations | |
enum | error_verbosity : int { error_verbosity::terse = 0, error_verbosity::normal = 1, error_verbosity::verbose = 2 } |
Error verbosity levels. More... | |
enum | write_policy { write_policy::read_only, write_policy::read_write } |
Should a transaction be read-only, or read-write? More... | |
enum | isolation_level { read_committed, repeatable_read, serializable } |
Transaction isolation levels. More... | |
Functions | |
std::string | encrypt_password (char const user[], char const password[]) |
Encrypt a password. More... | |
std::string | encrypt_password (std::string const &user, std::string const &password) |
Encrypt password. More... | |
template<> | |
bool | field::to< std::string > (std::string &obj) const |
Specialization: to(string &) . More... | |
template<typename CHAR > | |
std::basic_ostream< CHAR > & | operator<< (std::basic_ostream< CHAR > &s, field const &value) |
Write a result field to any type of stream. More... | |
template<typename T > | |
T | from_string (field const &value) |
Convert a field's string contents to another type. More... | |
template<> | |
std::string | to_string (field const &value) |
Convert a field to a string. More... | |
const_result_iterator | operator+ (result::difference_type o, const_result_iterator const &i) |
const_reverse_result_iterator | operator+ (result::difference_type n, const_reverse_result_iterator const &i) |
const_row_iterator | operator+ (const_row_iterator::difference_type o, const_row_iterator const &i) |
template<typename ITER , typename ACCESS > | |
std::string | separated_list (std::string_view sep, ITER begin, ITER end, ACCESS access) |
Represent sequence of values as a string, joined by a given separator. More... | |
template<typename ITER > | |
std::string | separated_list (std::string_view sep, ITER begin, ITER end) |
Render sequence as a string, using given separator between items. More... | |
template<typename CONTAINER > | |
auto | separated_list (std::string_view sep, CONTAINER const &c) -> typename std::enable_if<(not std::is_void< decltype(std::begin(c))>::value and not std::is_void< decltype(std::end(c))>::value), std::string >::type |
Render items in a container as a string, using given separator. More... | |
template<typename TUPLE , std::size_t INDEX = 0, typename ACCESS , typename std::enable_if<(INDEX==std::tuple_size< TUPLE >::value - 1), int >::type = 0> | |
std::string | separated_list (std::string_view, TUPLE const &t, ACCESS const &access) |
Render items in a tuple as a string, using given separator. More... | |
template<typename TUPLE , std::size_t INDEX = 0, typename 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 T > | |
T | from_string (std::string_view text) |
Attempt to convert postgres-generated string to given built-in type. More... | |
template<typename T > | |
void | from_string (std::string_view text, T &value) |
Attempt to convert postgres-generated string to given built-in object. More... | |
template<typename TYPE > | |
std::string | to_string (TYPE const &value) |
Convert a value to a readable string that PostgreSQL will understand. More... | |
template<typename TYPE > | |
void | into_string (TYPE const &value, std::string &out) |
Convert a value to a readable string that PostgreSQL will understand. More... | |
template<typename TYPE > | |
bool | is_null (TYPE const &value) |
Is value null? More... | |
template<> | |
void | stream_from::extract_value< std::nullptr_t > (std::string const &line, std::nullptr_t &, std::string::size_type &here, std::string &workspace) const |
template<typename TRANSACTION_CALLBACK > | |
auto | perform (TRANSACTION_CALLBACK &&callback, int attempts=3) -> std::invoke_result_t< TRANSACTION_CALLBACK > |
Simple way to execute a transaction with automatic retry. More... | |
template<typename T > | |
void | ignore_unused (T &&) |
Suppress compiler warning about an unused item. More... | |
template<typename TO , typename FROM > | |
TO | check_cast (FROM value, char const description[]) |
Cast a numeric value to another type, or throw if it underflows/overflows. More... | |
void | check_version () |
thread_safety_model | describe_thread_safety () |
Describe thread safety available in this build. More... | |
PQXX_DECLARE_ENUM_CONVERSION (pqxx::internal::encoding_group) | |
PQXX_DECLARE_ENUM_CONVERSION (ExecStatusType) | |
Variables | |
template<typename TYPE > | |
const std::string | type_name {internal::demangle_type_name(typeid(TYPE).name())} |
A human-readable name for a type, used in error messages and such. More... | |
template<typename T > | |
constexpr bool | is_sql_array {false} |
Does this type translate to an SQL array? More... | |
template<typename T > | |
constexpr char | array_separator {','} |
Element separator between SQL array elements of this type. More... | |
constexpr oid | oid_none {0} |
The "null" oid. More... | |
The home of all libpqxx classes, functions, templates, etc.
Handling of SQL arrays.
Copyright (c) 2000-2020, 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 string encodings support
Copyright (c) 2000-2020, 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-2020, 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::connection_base = typedef connection |
using pqxx::field_size_type = typedef size_t |
Number of bytes in a field of database data.
using pqxx::fieldstream = typedef basic_fieldstream<char> |
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::work = typedef transaction<> |
The default transaction type.
|
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 |
|
strong |
TO pqxx::check_cast | ( | FROM | value, |
char const | description[] | ||
) |
Cast a numeric value to another type, or throw if it underflows/overflows.
Both types must be arithmetic types, and they must either be both integral or both floating-point types.
References ignore_unused().
void pqxx::check_version | ( | ) |
Check library version at link time.
Ensures a failure when linking an application against a radically different libpqxx version than the one against which it was compiled.
Sometimes application builds fail in unclear ways because they compile using headers from libpqxx version X, but then link against libpqxx binary version Y. A typical scenario would be one where you're building against a libpqxx which you have built yourself, but a different version is installed on the system.
The check_library_version template is declared for any library version, but only actually defined for the version of the libpqxx binary against which the code is linked.
If the library binary is a different version than the one declared in these headers, then this call will fail to link: there will be no definition for the function with these exact template parameter values. There will be a definition, but the version in the parameter values will be different.
References ignore_unused(), and pqxx::internal::PQXX_VERSION_CHECK().
Referenced by pqxx::connection::connection().
pqxx::thread_safety_model pqxx::describe_thread_safety | ( | ) |
Describe thread safety available in this build.
Various utility functions.
Copyright (c) 2000-2020, 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.
References pqxx::thread_safety_model::description, pqxx::thread_safety_model::safe_kerberos, and pqxx::thread_safety_model::safe_libpq.
std::string pqxx::encrypt_password | ( | char const | user[], |
char const | password[] | ||
) |
Encrypt a password.
Referenced by encrypt_password(), and pqxx::connection::encrypt_password().
std::string pqxx::encrypt_password | ( | std::string const & | user, |
std::string const & | password | ||
) |
Encrypt password.
References encrypt_password().
bool pqxx::field::to< std::string > | ( | std::string & | obj | ) | const |
Specialization: to(string &)
.
References is_null().
T pqxx::from_string | ( | field const & | value | ) |
Convert a field's string contents to another type.
References pqxx::field::view().
Referenced by pqxx::field::to().
T pqxx::from_string | ( | std::string_view | text | ) |
Attempt to convert postgres-generated string to given built-in 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().
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.
void pqxx::ignore_unused | ( | T && | ) |
Suppress compiler warning about an unused item.
Referenced by check_cast(), check_version(), is_null(), and pqxx::internal::TypedCopyEscaper::operator()().
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.
bool pqxx::is_null | ( | TYPE const & | value | ) |
Is value
null?
References ignore_unused(), and pqxx::nullness< TYPE, ENABLE >::is_null().
Referenced by field::to< std::string >(), pqxx::internal::TypedCopyEscaper::operator()(), pqxx::connection::quote(), and pqxx::field::to().
const_row_iterator pqxx::operator+ | ( | const_row_iterator::difference_type | o, |
const_row_iterator const & | i | ||
) |
const_reverse_result_iterator pqxx::operator+ | ( | result::difference_type | n, |
const_reverse_result_iterator const & | i | ||
) |
References pqxx::const_reverse_result_iterator::base().
const_result_iterator pqxx::operator+ | ( | result::difference_type | o, |
const_result_iterator const & | i | ||
) |
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.
References pqxx::field::c_str(), and pqxx::field::size().
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 | ) |
pqxx::PQXX_DECLARE_ENUM_CONVERSION | ( | pqxx::internal::encoding_group | ) |
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::stream_to::operator<<(), 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().
void pqxx::stream_from::extract_value< std::nullptr_t > | ( | std::string const & | line, |
std::nullptr_t & | , | ||
std::string::size_type & | here, | ||
std::string & | workspace | ||
) | const |
std::string pqxx::to_string | ( | field const & | value | ) |
Convert a field to a string.
References pqxx::field::c_str(), and pqxx::field::size().
Referenced by pqxx::connection::adorn_name(), pqxx::binarystring::at(), pqxx::result::column_name(), pqxx::result::column_table(), pqxx::result::column_type(), pqxx::transaction_base::exec_n(), pqxx::internal::for_encoding(), pqxx::pipeline::is_finished(), pqxx::internal::TypedCopyEscaper::operator()(), pqxx::connection::quote(), pqxx::largeobjectaccess::read(), pqxx::largeobject::remove(), pqxx::pipeline::retain(), separated_list(), pqxx::connection::set_client_encoding(), pqxx::icursorstream::set_stride(), pqxx::result::table_column(), pqxx::largeobject::to_file(), and pqxx::largeobjectaccess::write().
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.
|
constexpr |
Element separator between SQL array elements of this type.
|
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 |
The "null" oid.
Referenced by pqxx::result::column_table(), pqxx::result::column_type(), and pqxx::largeobject::reason().
const std::string 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
.