pqxx::subtransaction Class Reference

"Transaction" nested within another transaction More...

#include <subtransaction.hxx>

Inheritance diagram for pqxx::subtransaction:

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...
Public Member Functions inherited from pqxx::internal::transactionfocus
	transactionfocus (transaction_base &t)
Public Member Functions inherited from pqxx::internal::namedclass
	namedclass (const std::string &Classname, const std::string &Name="")
const std::string &	name () const throw ()
const std::string &	classname () const throw ()
std::string	description () const
Public Member Functions inherited from pqxx::dbtransaction
virtual	~dbtransaction ()
Public Member Functions inherited from pqxx::transaction_base
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 str[], 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...
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...
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())
internal::parameterized_invocation	parameterized (const std::string &query)
	Parameterize a statement. 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...
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...

Additional Inherited Members
Public Types inherited from pqxx::transaction_base
typedef isolation_traits< read_committed >	isolation_tag
	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 () throw ()
void	reg_pending_error (const std::string &) throw ()
bool	registered () const throw ()
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[])
	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 () throw ()
	End transaction. To be called by implementing class' destructor. More...
result	DirectExec (const char C[], int Retries=0)
	Execute query on connection directly. More...
void	reactivation_avoidance_clear () throw ()
	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.exec("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.

subtransaction() [2/2]

pqxx::subtransaction::subtransaction ( subtransaction &  T, const std::string &  Name = std::string()  )

explicit

Nest a subtransaction in another subtransaction.

References pqxx::connection_base::cap_nested_transactions, pqxx::internal::reactivation_avoidance_counter::clear(), pqxx::transaction_base::conn(), pqxx::transaction_base::DirectExec(), pqxx::internal::reactivation_avoidance_counter::get(), pqxx::transaction_base::m_reactivation_avoidance, pqxx::internal::namedclass::name(), and pqxx::connection_base::supports().

---

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

• subtransaction.hxx
• subtransaction.cxx