libpqxx  v4.0-1
C++ library for PostgreSQL
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
pqxx::subtransaction Class Reference

"Transaction" nested within another transaction More...

#include <subtransaction.hxx>

Inheritance diagram for pqxx::subtransaction:
Collaboration diagram for pqxx::subtransaction:

Public Types

typedef isolation_traits
< read_committed
isolation_tag
 If nothing else is known, our isolation level is at least read_committed. More...
 

Public Member Functions

 subtransaction (dbtransaction &T, const PGSTD::string &Name=PGSTD::string())
 Nest a subtransaction nested in another transaction. More...
 
 subtransaction (subtransaction &T, const PGSTD::string &Name=PGSTD::string())
 Nest a subtransaction in another subtransaction. More...
 
void abort ()
 Abort the transaction. More...
 
const PGSTD::string & classname () const throw ()
 
void commit ()
 Commit the transaction. More...
 
connection_baseconn () const
 Connection this transaction is running in. More...
 
PGSTD::string description () const
 
PGSTD::string esc (const char str[]) const
 Escape string for use as SQL string literal in this transaction. More...
 
PGSTD::string esc (const char str[], size_t maxlen) const
 Escape string for use as SQL string literal in this transaction. More...
 
PGSTD::string esc (const PGSTD::string &str) const
 Escape string for use as SQL string literal in this transaction. More...
 
PGSTD::string esc_raw (const unsigned char str[], size_t len) const
 Escape binary data for use as SQL string literal in this transaction. More...
 
PGSTD::string esc_raw (const PGSTD::string &) const
 Escape binary data for use as SQL string literal in this transaction. More...
 
result exec (const PGSTD::string &Query, const PGSTD::string &Desc=PGSTD::string())
 Execute query. More...
 
result exec (const PGSTD::stringstream &Query, const PGSTD::string &Desc=PGSTD::string())
 
PGSTD::string get_variable (const PGSTD::string &)
 Get currently applicable value of variable. More...
 
const PGSTD::string & name () const throw ()
 
internal::parameterized_invocation parameterized (const PGSTD::string &query)
 Parameterize a statement. More...
 
template<typename T >
PGSTD::string quote (const T &t) const
 Represent object as SQL string, including quoting & escaping. More...
 
PGSTD::string quote_name (const PGSTD::string &identifier) const
 Escape an SQL identifier for use in a query. More...
 
PGSTD::string quote_raw (const unsigned char str[], size_t len) const
 Binary-escape and quote a binarystring for use as an SQL constant. More...
 
PGSTD::string quote_raw (const PGSTD::string &str) const
 
void set_variable (const PGSTD::string &Var, const PGSTD::string &Val)
 Set session variable in this connection. More...
 
Prepared statements
prepare::invocation prepared (const PGSTD::string &statement=PGSTD::string())
 Execute prepared statement. More...
 
Error/warning output
void process_notice (const char Msg[]) const
 Have connection process warning message. More...
 
void process_notice (const PGSTD::string &Msg) const
 Have connection process warning message. More...
 

Protected Member Functions

void Begin ()
 Begin transaction (to be called by implementing class) More...
 
result DirectExec (const char C[], int Retries=0)
 Execute query on connection directly. More...
 
virtual result do_exec (const char Query[])
 Sensible default implemented here: perform query. More...
 
void End () throw ()
 End transaction. To be called by implementing class' destructor. More...
 
void reactivation_avoidance_clear () throw ()
 Forget about any reactivation-blocking resources we tried to allocate. More...
 
void reg_pending_error (const PGSTD::string &) throw ()
 
void register_me ()
 
bool registered () const throw ()
 
void start_backend_transaction ()
 Start a transaction on the backend and set desired isolation level. More...
 
void unregister_me () throw ()
 

Static Protected Member Functions

static PGSTD::string fullname (const PGSTD::string &ttype, const PGSTD::string &isolation)
 

Protected Attributes

internal::reactivation_avoidance_counter m_reactivation_avoidance
 Resources allocated in this transaction that make reactivation impossible. More...
 
transaction_basem_Trans
 

Private Member Functions

void check_backendsupport () const
 
virtual void do_abort ()
 Sensible default implemented here: abort backend transaction. More...
 
virtual void do_begin ()
 Sensible default implemented here: begin backend transaction. More...
 
virtual void do_commit ()
 To be implemented by derived class: commit backend transaction. More...
 

Private Attributes

dbtransactionm_parent
 

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.

Member Typedef Documentation

If nothing else is known, our isolation level is at least read_committed.

Constructor & Destructor Documentation

pqxx::subtransaction::subtransaction ( dbtransaction T,
const PGSTD::string &  Name = PGSTD::string() 
)
explicit

Nest a subtransaction nested in another transaction.

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

Nest a subtransaction in another subtransaction.

Member Function Documentation

void pqxx::transaction_base::abort ( )
inherited

Abort the transaction.

No special effort is required to call this function; it will be called implicitly when the transaction is destructed.

void pqxx::transaction_base::Begin ( )
protectedinherited

Begin transaction (to be called by implementing class)

Will typically be called from implementing class' constructor.

Referenced by pqxx::transaction< ISOLATIONLEVEL, READWRITE >::transaction().

Here is the caller graph for this function:

void pqxx::subtransaction::check_backendsupport ( ) const
private
const PGSTD::string& pqxx::internal::namedclass::classname ( ) const throw ()
inlineinherited
void pqxx::transaction_base::commit ( )
inherited

Commit the transaction.

Unless this function is called explicitly, the transaction will not be committed (actually the nontransaction implementation breaks this rule, hence the name).

Once this function returns, the whole transaction will typically be irrevocably completed in the database. There is also, however, a minute risk that the connection to the database may be lost at just the wrong moment. In that case, libpqxx may be unable to determine whether the transaction was completed or aborted and an in_doubt_error will be thrown to make this fact known to the caller. The robusttransaction implementation takes some special precautions to reduce this risk.

connection_base& pqxx::transaction_base::conn ( ) const
inlineinherited

Connection this transaction is running in.

Referenced by pqxx::transaction< ISOLATIONLEVEL, READWRITE >::~transaction().

Here is the caller graph for this function:

PGSTD::string pqxx::internal::namedclass::description ( ) const
inherited
result pqxx::transaction_base::DirectExec ( const char  C[],
int  Retries = 0 
)
protectedinherited

Execute query on connection directly.

Parameters
CQuery or command to execute
RetriesNumber of times to retry the query if it fails. Be extremely careful with this option; if you retry in the middle of a transaction, you may be setting up a new connection transparently and executing the latter part of the transaction without a backend transaction being active (and with the former part aborted).
virtual void pqxx::subtransaction::do_abort ( )
privatevirtual

Sensible default implemented here: abort backend transaction.

Default implementation does two things:

  1. Clears the "connection reactivation avoidance counter"
  2. Executes a ROLLBACK statement

Reimplemented from pqxx::dbtransaction.

virtual void pqxx::subtransaction::do_begin ( )
privatevirtual

Sensible default implemented here: begin backend transaction.

Reimplemented from pqxx::dbtransaction.

virtual void pqxx::subtransaction::do_commit ( )
privatevirtual

To be implemented by derived class: commit backend transaction.

Implements pqxx::dbtransaction.

virtual result pqxx::dbtransaction::do_exec ( const char  Query[])
protectedvirtualinherited

Sensible default implemented here: perform query.

Implements pqxx::transaction_base.

void pqxx::transaction_base::End ( ) throw ()
protectedinherited

End transaction. To be called by implementing class' destructor.

Referenced by pqxx::transaction< ISOLATIONLEVEL, READWRITE >::~transaction().

Here is the caller graph for this function:

result pqxx::transaction_base::exec ( const PGSTD::string &  Query,
const PGSTD::string &  Desc = PGSTD::string() 
)
inherited

Execute query.

Perform a query in this transaction.

This is one of the most important functions in libpqxx.

Most libpqxx exceptions can be thrown from here, including sql_error, broken_connection, and many sql_error subtypes such as feature_not_supported or insufficient_privilege. But any exception thrown by the C++ standard library may also occur here. All exceptions will be derived from std::exception, however, and all libpqxx-specific exception types are derived from pqxx::pqxx_exception.

Parameters
QueryQuery or command to execute
DescOptional identifier for query, to help pinpoint SQL errors
Returns
A result set describing the query's or command's result
result pqxx::transaction_base::exec ( const PGSTD::stringstream &  Query,
const PGSTD::string &  Desc = PGSTD::string() 
)
inlineinherited

References pqxx::transaction_base::exec().

Referenced by pqxx::transaction_base::exec().

Here is the call graph for this function:

Here is the caller graph for this function:

static PGSTD::string pqxx::dbtransaction::fullname ( const PGSTD::string &  ttype,
const PGSTD::string &  isolation 
)
staticprotectedinherited
PGSTD::string pqxx::transaction_base::get_variable ( const PGSTD::string &  )
inherited

Get currently applicable value of variable.

First consults an internal cache of variables that have been set (whether in the ongoing transaction or in the connection) using the set_variable functions. If it is not found there, the database is queried.

Warning
Do not mix the set_variable with raw "SET" queries, and do not try to set or get variables while a pipeline or table stream is active.
This function used to be declared as const but isn't anymore.
const PGSTD::string& pqxx::internal::namedclass::name ( ) const throw ()
inlineinherited
internal::parameterized_invocation pqxx::transaction_base::parameterized ( const PGSTD::string &  query)
inherited

Parameterize a statement.

prepare::invocation pqxx::transaction_base::prepared ( const PGSTD::string &  statement = PGSTD::string())
inherited

Execute prepared statement.

Prepared statements are defined using the connection classes' prepare() function, and continue to live on in the ongoing session regardless of the context they were defined in (unless explicitly dropped using the connection's unprepare() function). Their execution however, like other forms of query execution, requires a transaction object.

Just like param_declaration is a helper class that lets you tag parameter declarations onto the statement declaration, the invocation class returned here lets you tag parameter values onto the call:

result run_mystatement(transaction_base &T)
{
return T.prepared("mystatement")("param1")(2)()(4).exec();
}

Here, parameter 1 (written as "<tt>$1</tt>" in the statement's body) is a string that receives the value "param1"; the second parameter is an integer with the value 2; the third receives a null, making its type irrelevant; and number 4 again is an integer. The ultimate invocation of exec() is essential; if you forget this, nothing happens.

To see whether any prepared statement has been defined under a given name, use:

T.prepared("mystatement").exists()
Warning
Do not try to execute a prepared statement manually through direct SQL statements. This is likely not to work, and even if it does, is likely to be slower than using the proper libpqxx functions. Also, libpqxx knows how to emulate prepared statements if some part of the infrastructure does not support them.
Actual definition of the prepared statement on the backend may be deferred until its first use, which means that any errors in the prepared statement may not show up until it is executed–and perhaps abort the ongoing transaction in the process.

If you leave out the statement name, the call refers to the nameless statement instead.

void pqxx::transaction_base::process_notice ( const char  Msg[]) const
inlineinherited

Have connection process warning message.

void pqxx::transaction_base::process_notice ( const PGSTD::string &  Msg) const
inlineinherited

Have connection process warning message.

void pqxx::transaction_base::reactivation_avoidance_clear ( ) throw ()
inlineprotectedinherited

Forget about any reactivation-blocking resources we tried to allocate.

References pqxx::result::clear().

Here is the call graph for this function:

void pqxx::internal::transactionfocus::reg_pending_error ( const PGSTD::string &  ) throw ()
protectedinherited
void pqxx::internal::transactionfocus::register_me ( )
protectedinherited
bool pqxx::internal::transactionfocus::registered ( ) const throw ()
inlineprotectedinherited
void pqxx::transaction_base::set_variable ( const PGSTD::string &  Var,
const PGSTD::string &  Val 
)
inherited

Set session variable in this connection.

The new value is typically forgotten if the transaction aborts. Known exceptions to this rule are nontransaction, and PostgreSQL versions prior to 7.3. In the case of nontransaction, the set value will be kept regardless; but in that case, if the connection ever needs to be recovered, the set value will not be restored.

Parameters
VarThe variable to set
ValThe new value to store in the variable
void pqxx::dbtransaction::start_backend_transaction ( )
protectedinherited

Start a transaction on the backend and set desired isolation level.

void pqxx::internal::transactionfocus::unregister_me ( ) throw ()
protectedinherited

Member Data Documentation

dbtransaction& pqxx::subtransaction::m_parent
private
internal::reactivation_avoidance_counter pqxx::transaction_base::m_reactivation_avoidance
protectedinherited

Resources allocated in this transaction that make reactivation impossible.

This number may be negative!

transaction_base& pqxx::internal::transactionfocus::m_Trans
protectedinherited

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