pqxx::subtransaction Class Reference
Transaction classes

"Transaction" nested within another transaction More...

`#include <subtransaction.hxx>`

Inheritance diagram for pqxx::subtransaction:
[legend]

## Public Member Functions

| subtransaction (dbtransaction &t, std::string_view tname=""sv)
| Nest a subtransaction nested in another transaction.
| subtransaction (subtransaction &t, std::string_view name=""sv)
| Nest a subtransaction in another subtransaction.
virtual | ~subtransaction () noexcept override
Public Member Functions inherited from pqxx::transaction_focus
| transaction_focus (transaction_base &t, std::string_view cname, std::string_view oname)
| transaction_focus (transaction_base &t, std::string_view cname, std::string &&oname)
| transaction_focus (transaction_base &t, std::string_view cname)
| transaction_focus ()=delete
| transaction_focus (transaction_focus const &)=delete
transaction_focus & | operator= (transaction_focus const &)=delete
constexpr std::string_view | classname () const noexcept
| Class name, for human consumption.
std::string_view | name () const &noexcept
| Name for this object, if the caller passed one; empty string otherwise.
std::string | description () const
| transaction_focus (transaction_focus &&other)
transaction_focus & | operator= (transaction_focus &&other)
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_focus
void | register_me ()
void | unregister_me () noexcept
void | reg_pending_error (std::string const &) noexcept
bool | registered () const noexcept
Protected Member Functions inherited from pqxx::dbtransaction
| dbtransaction (connection &c)
| Begin transaction.
| dbtransaction (connection &c, std::string_view tname)
| Begin transaction.
| dbtransaction (connection &c, std::string_view tname, std::shared_ptr< std::string > rollback_cmd)
| Begin transaction.
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)
Protected Attributes inherited from pqxx::transaction_focus
transaction_base * | m_trans

## Detailed Description

"Transaction" nested within another transaction

A subtransaction can be executed inside a backend transaction, or inside another subtransaction. This can be useful when, for example, statements in a transaction may harmlessly fail and you don't want them to abort the entire transaction. Here's an example of how a temporary table may be dropped before re-creating it, without failing if the table did not exist:

void do_job(connection &C)
{
string const temptable = "fleetingtable";
work W(C, "do_job");
do_firstpart(W);
// Attempt to delete our temporary table if it already existed.
try
{
subtransaction S(W, "droptemp");
S.exec0("DROP TABLE " + temptable);
S.commit();
}
catch (undefined_table const &)
{
// Table did not exist. Which is what we were hoping to achieve anyway.
// Carry on without regrets.
}
// S may have gone into a failed state and been destroyed, but the
// upper-level transaction W is still fine. We can continue to use it.
W.exec0("CREATE TEMP TABLE " + temptable + "(bar integer, splat
varchar)");
do_lastpart(W);
}
pqxx::connection
Connection to a database.
Definition connection.hxx:253
pqxx::undefined_table
Definition except.hxx:616
pqxx::subtransaction
"Transaction" nested within another transaction
Definition subtransaction.hxx:78

(This is just an example. If you really wanted to do drop a table without an error if it doesn't exist, you'd use DROP TABLE IF EXISTS.)

There are no isolation levels inside a transaction. They are not needed because all actions within the same backend transaction are always performed sequentially anyway.

Warning
  While the subtransaction is "live," you cannot execute queries or open streams etc. on its parent transaction. A transaction can have at most one object of a type derived from pqxx::transaction_focus active on it at a time.

## Constructor & Destructor Documentation

## subtransaction() [1/2]

pqxx::subtransaction::subtransaction | ( | dbtransaction & | t,
|  | std::string_view | tname = `""sv`
| ) |  |

explicit

Nest a subtransaction nested in another transaction.

## subtransaction() [2/2]

pqxx::subtransaction::subtransaction | ( | subtransaction & | t,
|  | std::string_view | name = `""sv`
| ) |  |

explicit

Nest a subtransaction in another subtransaction.

## ~subtransaction()

pqxx::subtransaction::~subtransaction | ( |  | ) |

override virtual noexcept

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

- subtransaction.hxx
- subtransaction.cxx