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, const std::string &Name=std::string{})
| Nest a subtransaction nested in another transaction. More...
| subtransaction (subtransaction &T, const std::string &Name=std::string{})
| Nest a subtransaction in another subtransaction. More...
virtual | ~subtransaction () noexcept
Public Member Functions inherited from pqxx::internal::transactionfocus
| transactionfocus (transaction_base &t)
| transactionfocus ()=delete
| transactionfocus (const transactionfocus &)=delete
transactionfocus & | operator= (const transactionfocus &)=delete
Public Member Functions inherited from pqxx::internal::namedclass
| namedclass (const std::string &Classname)
| namedclass (const std::string &Classname, const std::string &Name)
const std::string & | name () const noexcept
| Object name, or the empty string if no name was given. More...
const std::string & | classname () const noexcept
| Class name. More...
std::string | description () const
| Combination of class name and object name; or just class name. More...
Public Member Functions inherited from pqxx::dbtransaction
virtual | ~dbtransaction ()
Public Member Functions inherited from pqxx::transaction_base
| transaction_base ()=delete
| transaction_base (const transaction_base &)=delete
transaction_base & | operator= (const transaction_base &)=delete
virtual | ~transaction_base ()=0
void | commit ()
| Commit the transaction. More...
void | abort ()
| Abort the transaction. More...
std::string | esc (const char str[]) const
| Escape string for use as SQL string literal in this transaction. More...
std::string | esc (const char str[], size_t maxlen) const
| Escape string for use as SQL string literal in this transaction. More...
std::string | esc (const std::string &str) const
| Escape string for use as SQL string literal in this transaction. More...
std::string | esc_raw (const unsigned char data[], size_t len) const
| Escape binary data for use as SQL string literal in this transaction. More...
std::string | esc_raw (const std::string &) const
| Escape binary data for use as SQL string literal in this transaction. More...
std::string | unesc_raw (const std::string &text) const
| Unescape binary data, e.g. from a table field or notification payload. More...
std::string | unesc_raw (const char *text) const
| Unescape binary data, e.g. from a table field or notification payload. More...
template<typename T >
std::string | quote (const T &t) const
| Represent object as SQL string, including quoting & escaping. More...
std::string | quote_raw (const unsigned char str[], size_t len) const
| Binary-escape and quote a binarystring for use as an SQL constant. More...
std::string | quote_raw (const std::string &str) const
std::string | quote_name (const std::string &identifier) const
| Escape an SQL identifier for use in a query. More...
std::string | esc_like (const std::string &str, char escape_char='\\') const
| Escape string for literal LIKE match. More...
result | exec (const std::string &Query, const std::string &Desc=std::string{})
| Execute query. More...
result | exec (const std::stringstream &Query, const std::string &Desc=std::string{})
result | exec0 (const std::string &Query, const std::string &Desc=std::string{})
| Execute query, which should zero rows of data. More...
row | exec1 (const std::string &Query, const std::string &Desc=std::string{})
| Execute query returning a single row of data. More...
result | exec_n (size_t rows, const std::string &Query, const std::string &Desc=std::string{})
| Execute query, expect given number of rows. More...
template<typename ... Args>
result | exec_params (const std::string &query, Args &&...args)
| Execute an SQL statement with parameters. More...
template<typename ... Args>
row | exec_params1 (const std::string &query, Args &&... args)
template<typename ... Args>
result | exec_params0 (const std::string &query, Args &&...args)
template<typename ... Args>
result | exec_params_n (size_t rows, const std::string &query, Args &&...args)
internal::parameterized_invocation | parameterized (const std::string &query)
| Parameterize a statement. More...
template<typename ... Args>
result | exec_prepared (const std::string &statement, Args &&... args)
| Execute a prepared statement, with optional arguments. More...
template<typename ... Args>
row | exec_prepared1 (const std::string &statement, Args &&... args)
| Execute a prepared statement, and expect a single-row result. More...
template<typename ... Args>
result | exec_prepared0 (const std::string &statement, Args &&... args)
| Execute a prepared statement, and expect a result with zero rows. More...
template<typename ... Args>
result | exec_prepared_n (size_t rows, const std::string &statement, Args &&... args)
| Execute a prepared statement, expect a result with given number of rows. More...
prepare::invocation | prepared (const std::string &statement=std::string{})
| Execute prepared statement. More...
void | process_notice (const char Msg[]) const
| Have connection process warning message. More...
void | process_notice (const std::string &Msg) const
| Have connection process warning message. More...
connection_base & | conn () const
| Connection this transaction is running in. More...
void | set_variable (const std::string &Var, const std::string &Val)
| Set session variable in this connection. More...
std::string | get_variable (const std::string &)
| Get currently applicable value of variable. More...

## Additional Inherited Members

Public Types inherited from pqxx::transaction_base
using | isolation_tag = isolation_traits< read_committed >
| If nothing else is known, our isolation level is at least read_committed. More...
Protected Member Functions inherited from pqxx::internal::transactionfocus
void | register_me ()
void | unregister_me () noexcept
void | reg_pending_error (const std::string &) noexcept
bool | registered () const noexcept
Protected Member Functions inherited from pqxx::dbtransaction
| dbtransaction (connection_base &, const std::string &IsolationString, readwrite_policy rw=read_write)
| dbtransaction (connection_base &, bool direct=true, readwrite_policy rw=read_write)
void | start_backend_transaction ()
| Start a transaction on the backend and set desired isolation level. More...
virtual result | do_exec (const char Query[]) override
| Sensible default implemented here: perform query. More...
Protected Member Functions inherited from pqxx::transaction_base
| transaction_base (connection_base &c, bool direct=true)
| Create a transaction (to be called by implementation classes only) More...
void | Begin ()
| Begin transaction (to be called by implementing class) More...
void | End () noexcept
| End transaction. To be called by implementing class' destructor. More...
result | direct_exec (const char C[], int Retries=0)
| Execute query on connection directly. More...
void | reactivation_avoidance_clear () noexcept
| Forget about any reactivation-blocking resources we tried to allocate. More...
Static Protected Member Functions inherited from pqxx::dbtransaction
static std::string | fullname (const std::string &ttype, const std::string &isolation)
Protected Attributes inherited from pqxx::internal::transactionfocus
transaction_base & | m_trans
Protected Attributes inherited from pqxx::transaction_base
internal::reactivation_avoidance_counter | m_reactivation_avoidance
| Resources allocated in this transaction that make reactivation impossible. More...

## 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_base &C)
{
const string temptable = "fleetingtable";
// Since we're dealing with a temporary table here, disallow automatic
// recovery of the connection in case it breaks.
C.inhibit_reactivation(true);
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 (const undefined_table &)
{
// 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.exec("CREATE TEMP TABLE " + temptable + "(bar integer, splat varchar)");
do_lastpart(W);
}

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

## Constructor & Destructor Documentation

## subtransaction() [1/2]

pqxx::subtransaction::subtransaction | ( | dbtransaction & | T,
|  | const std::string & | Name = `std::string{}`
| ) |  |

explicit

Nest a subtransaction nested in another transaction.

References pqxx::connection_base::adorn_name(), and pqxx::transaction_base::conn().

## subtransaction() [2/2]

pqxx::subtransaction::subtransaction | ( | subtransaction & | T,
|  | const std::string & | Name = `std::string{}`
| ) |  |

explicit

Nest a subtransaction in another subtransaction.

## ~subtransaction()

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

virtual noexcept

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

- subtransaction.hxx
- subtransaction.cxx

pqxx::subtransaction::subtransaction
subtransaction(dbtransaction &T, const std::string &Name=std::string{})
Nest a subtransaction nested in another transaction.
Definition: subtransaction.cxx:23
pqxx::work
transaction<> work
The default transaction type.
Definition: transaction.hxx:107