pqxx::subtransaction Class Reference

"Transaction" nested within another transaction More...

#include <subtransaction.hxx>

Inheritance diagram for pqxx::subtransaction:

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

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

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

overridevirtualnoexcept

---

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

• subtransaction.hxx
• subtransaction.cxx