pqxx::nontransaction Class Referencefinal
Transaction classes

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

`#include <nontransaction.hxx>`

Inheritance diagram for pqxx::nontransaction:
[legend]

## Public Member Functions

| nontransaction (connection &c, std::string_view tname=""sv)
| Constructor.
virtual | ~nontransaction () override
Public Member Functions inherited from pqxx::transaction_base
| transaction_base ()=delete
| transaction_base (transaction_base const &)=delete
| transaction_base (transaction_base &&)=delete
transaction_base & | operator= (transaction_base const &)=delete
transaction_base & | operator= (transaction_base &&)=delete
virtual | ~transaction_base ()=0
void | commit ()
| Commit the transaction.
void | abort ()
| Abort the transaction.
template<typename... ARGS>
auto | esc (ARGS &&...args) const
| Escape string for use as SQL string literal in this transaction.
template<typename... ARGS>
auto | esc_raw (ARGS &&...args) const
| Escape binary data for use as SQL string literal in this transaction.
std::string | unesc_raw (zview text) const
| Unescape binary data, e.g. from a table field or notification payload.
std::basic_string< std::byte > | unesc_bin (zview text)
| Unescape binary data, e.g. from a table field or notification payload.
std::string | unesc_raw (char const *text) const
| Unescape binary data, e.g. from a table field or notification payload.
std::basic_string< std::byte > | unesc_bin (char const text[])
| Unescape binary data, e.g. from a table field or notification payload.
template<typename T >
std::string | quote (T const &t) const
| Represent object as SQL string, including quoting & escaping.
std::string | quote (binarystring const &t) const
std::string | quote_raw (unsigned char const bin[], std::size_t len) const
| Binary-escape and quote a binary string for use as an SQL constant.
std::string | quote_raw (zview bin) const
| Binary-escape and quote a binary string for use as an SQL constant.
std::string | quote_name (std::string_view identifier) const
| Escape an SQL identifier for use in a query.
std::string | esc_like (std::string_view bin, char escape_char='\\') const
| Escape string for literal LIKE match.
template<>
zview | query_value (zview query, std::string_view desc)=delete
| Forbidden specialisation: underlying buffer immediately goes out of scope.
result | exec (std::string_view query, std::string_view desc)
| Execute a command.
result | exec (std::string_view query)
| Execute a command.
result | exec (std::stringstream const &query, std::string_view desc)
| Execute a command.
result | exec0 (zview query, std::string_view desc)
| Execute command, which should return zero rows of data.
result | exec0 (zview query)
| Execute command, which should return zero rows of data.
row | exec1 (zview query, std::string_view desc)
| Execute command returning a single row of data.
row | exec1 (zview query)
| Execute command returning a single row of data.
result | exec_n (result::size_type rows, zview query, std::string_view desc)
| Execute command, expect given number of rows.
result | exec_n (result::size_type rows, zview query)
| Execute command, expect given number of rows.
template<typename TYPE >
TYPE | query_value (zview query, std::string_view desc)
| Perform query, expecting exactly 1 row with 1 field, and convert it.
template<typename TYPE >
TYPE | query_value (zview query)
| Perform query, expecting exactly 1 row with 1 field, and convert it.
template<typename... TYPE>
std::tuple< TYPE... > | query1 (zview query)
| Perform query returning exactly one row, and convert its fields.
template<typename... TYPE>
std::optional< std::tuple< TYPE... > > | query01 (zview query)
| Query at most one row of data, and if there is one, convert it.
template<typename... TYPE>
auto | stream (std::string_view query) &
| Execute a query, and loop over the results row by row.
template<typename CALLABLE >
auto | for_stream (std::string_view query, CALLABLE &&func)
| Perform a streaming query, and for each result row, call `func`.
template<typename CALLABLE >
auto | for_each (std::string_view query, CALLABLE &&func)
template<typename... TYPE>
auto | query (zview query)
| Execute query, read full results, then iterate rows of data.
template<typename... TYPE>
auto | query_n (result::size_type rows, zview query)
| Perform query, expect given number of rows, iterate results.
template<typename CALLABLE >
void | for_query (zview query, CALLABLE &&func)
| Execute a query, load the full result, and perform `func` for each row.
template<typename... Args>
result | exec_params (zview query, Args &&...args)
| Execute an SQL statement with parameters.
template<typename... Args>
row | exec_params1 (zview query, Args &&...args)
template<typename... Args>
result | exec_params0 (zview query, Args &&...args)
template<typename... Args>
result | exec_params_n (std::size_t rows, zview query, Args &&...args)
template<typename... Args>
result | exec_prepared (zview statement, Args &&...args)
| Execute a prepared statement, with optional arguments.
template<typename... Args>
row | exec_prepared1 (zview statement, Args &&...args)
| Execute a prepared statement, and expect a single-row result.
template<typename... Args>
result | exec_prepared0 (zview statement, Args &&...args)
| Execute a prepared statement, and expect a result with zero rows.
template<typename... Args>
result | exec_prepared_n (result::size_type rows, zview statement, Args &&...args)
| Execute a prepared statement, expect a result with given number of rows.
void | process_notice (char const msg[]) const
| Have connection process a warning message.
void | process_notice (zview msg) const
| Have connection process a warning message.
constexpr connection & | conn () const noexcept
| The connection in which this transaction lives.
void | set_variable (std::string_view var, std::string_view value)
| Set session variable using SQL "SET" command.
std::string | get_variable (std::string_view)
| Read session variable using SQL "SHOW" command.
std::string_view | name () const &noexcept
| Transaction name, if you passed one to the constructor; or empty string.

## Additional Inherited Members

Protected Member Functions inherited from pqxx::transaction_base
| transaction_base (connection &c, std::string_view tname, std::shared_ptr< std::string > rollback_cmd)
| Create a transaction (to be called by implementation classes only).
| transaction_base (connection &c, std::string_view tname)
| Create a transaction (to be called by implementation classes only).
| transaction_base (connection &c)
| Create a transaction (to be called by implementation classes only).
void | register_transaction ()
| Register this transaction with the connection.
void | close () noexcept
| End transaction. To be called by implementing class' destructor.
virtual void | do_abort ()
| Transaction type-specific way of aborting a transaction.
void | set_rollback_cmd (std::shared_ptr< std::string > cmd)
| Set the rollback command.
result | direct_exec (std::string_view, std::string_view desc=""sv)
| Execute query on connection directly.
result | direct_exec (std::shared_ptr< std::string >, std::string_view desc=""sv)

## Detailed Description

Simple "transaction" class offering no transactional integrity.

nontransaction, like transaction or any other transaction_base-derived class, provides access to a database through a connection. Unlike its siblings, however, nontransaction does not maintain any kind of transactional integrity. This may be useful eg. for read-only access to the database that does not require a consistent, atomic view on its data; or for operations that are not allowed within a backend transaction, such as creating tables.

For queries that update the database, however, a real transaction is likely to be faster unless the transaction consists of only a single record update.

Also, you can keep a nontransaction open for as long as you like. Actual back-end transactions are limited in lifespan, and will sometimes fail just because they took too long to execute or were left idle for too long. This will not happen with a nontransaction (although the connection may still time out, e.g. when the network is unavailable for a very long time).

Any query executed in a nontransaction is committed immediately, and neither commit() nor abort() has any effect.

Database features that require a backend transaction, such as cursors or large objects, will not work in a nontransaction.

## Constructor & Destructor Documentation

## nontransaction()

pqxx::nontransaction::nontransaction | ( | connection & | c,
|  | std::string_view | tname = `""sv`
| ) |  |

Constructor.

Create a "dummy" transaction.

Parameters

  c | Connection in which this "transaction" will operate.
  tname | Optional tname for the transaction, beginning with a letter and containing only letters and digits.

## ~nontransaction()

virtual pqxx::nontransaction::~nontransaction | ( |  | ) |

override virtual

The documentation for this class was generated from the following file:

- nontransaction.hxx