libpqxx  4.0.1
pqxx::robusttransaction< ISOLATIONLEVEL > Class Template Reference

Slightly slower, better-fortified version of transaction. More...

#include <robusttransaction.hxx>

Inheritance diagram for pqxx::robusttransaction< ISOLATIONLEVEL >:
pqxx::basic_robusttransaction pqxx::dbtransaction pqxx::transaction_base pqxx::internal::namedclass

Public Types

typedef isolation_traits
< ISOLATIONLEVEL > 
isolation_tag
- Public Types inherited from pqxx::basic_robusttransaction
typedef isolation_traits
< read_committed
isolation_tag
 Isolation level is read_committed by default.

Public Member Functions

 robusttransaction (connection_base &C, const std::string &Name=std::string())
 Constructor.
virtual ~robusttransaction () throw ()
- Public Member Functions inherited from pqxx::basic_robusttransaction
virtual ~basic_robusttransaction ()=0
- 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.
void abort ()
 Abort the transaction.
std::string esc (const char str[]) const
 Escape string for use as SQL string literal in this transaction.
std::string esc (const char str[], size_t maxlen) const
 Escape string for use as SQL string literal in this transaction.
std::string esc (const std::string &str) const
 Escape string for use as SQL string literal in this transaction.
std::string esc_raw (const unsigned char str[], size_t len) const
 Escape binary data for use as SQL string literal in this transaction.
std::string esc_raw (const std::string &) const
 Escape binary data for use as SQL string literal in this transaction.
template<typename T >
std::string quote (const T &t) const
 Represent object as SQL string, including quoting & escaping.
std::string quote_raw (const unsigned char str[], size_t len) const
 Binary-escape and quote a binarystring for use as an SQL constant.
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.
result exec (const std::string &Query, const std::string &Desc=std::string())
 Execute query.
result exec (const std::stringstream &Query, const std::string &Desc=std::string())
internal::parameterized_invocation parameterized (const std::string &query)
 Parameterize a statement.
connection_baseconn () const
 Connection this transaction is running in.
void set_variable (const std::string &Var, const std::string &Val)
 Set session variable in this connection.
std::string get_variable (const std::string &)
 Get currently applicable value of variable.
prepare::invocation prepared (const std::string &statement=std::string())
 Execute prepared statement.
void process_notice (const char Msg[]) const
 Have connection process warning message.
void process_notice (const std::string &Msg) const
 Have connection process warning message.
- 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

Additional Inherited Members

- Protected Member Functions inherited from pqxx::basic_robusttransaction
 basic_robusttransaction (connection_base &C, const std::string &IsolationLevel, const std::string &table_name=std::string())
- 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::transaction_base
internal::reactivation_avoidance_counter m_reactivation_avoidance
 Resources allocated in this transaction that make reactivation impossible.

Detailed Description

template<isolation_level ISOLATIONLEVEL = read_committed>
class pqxx::robusttransaction< ISOLATIONLEVEL >

Slightly slower, better-fortified version of transaction.

robusttransaction is similar to transaction, but spends more effort (and performance!) to deal with the hopefully rare case that the connection to the backend is lost just as the current transaction is being committed. In this case, there is no way to determine whether the backend managed to commit the transaction before noticing the loss of connection.

In such cases, this class tries to reconnect to the database and figure out what happened. It will need to store and manage some information (pretty much a user-level transaction log) in the back-end for each and every transaction just on the off chance that this problem might occur. This service level was made optional since you may not want to pay this overhead where it is not necessary. Certainly the use of this class makes no sense for local connections, or for transactions that read the database but never modify it, or for noncritical database manipulations.

Besides being slower, it's theoretically possible that robusttransaction actually fails more instead of less often than a normal transaction. This is due to the added work and complexity. What robusttransaction tries to achieve is to be more deterministic, not more successful per se.

When a user first uses a robusttransaction in a database, the class will attempt to create a log table there to keep vital transaction-related state information in. This table, located in that same database, will be called pqxxlog_*user*, where user is the PostgreSQL username for that user. If the log table can not be created, the transaction fails immediately.

If the user does not have permission to create the log table, the database administrator may create one for him beforehand, and give ownership (or at least full insert/update rights) to the user. The table must contain two non-unique fields (which will never be null): "name" (of text type, varchar(256) by default) and "date" (of timestamp type). Older versions of robusttransaction also added a unique "id" field; this field is now obsolete and the log table's implicit oids are used instead. The log tables' names may be made configurable in a future version of libpqxx.

The transaction log table contains records describing unfinished transactions, i.e. ones that have been started but not, as far as the client knows, committed or aborted. This can mean any of the following:

  1. The transaction is in progress. Since backend transactions can't run for extended periods of time, this can only be the case if the log record's timestamp (compared to the server's clock) is not very old, provided of course that the server's system clock hasn't just made a radical jump.
  2. The client's connection to the server was lost, just when the client was committing the transaction, and the client so far has not been able to re-establish the connection to verify whether the transaction was actually completed or rolled back by the server. This is a serious (and luckily a rare) condition and requires manual inspection of the database to determine what happened. The robusttransaction will emit clear and specific warnings to this effect, and will identify the log record describing the transaction in question.
  3. The transaction was completed (either by commit or by rollback), but the client's connection was durably lost just as it tried to clean up the log record. Again, robusttransaction will emit a clear and specific warning to tell you about this and request that the record be deleted as soon as possible.
  4. The client has gone offline at any time while in one of the preceding states. This also requires manual intervention, but the client obviously is not able to issue a warning.

It is safe to drop a log table when it is not in use (ie., it is empty or all records in it represent states 2-4 above). Each robusttransaction will attempt to recreate the table at its next time of use.

Member Typedef Documentation

template<isolation_level ISOLATIONLEVEL = read_committed>
typedef isolation_traits<ISOLATIONLEVEL> pqxx::robusttransaction< ISOLATIONLEVEL >::isolation_tag

Constructor & Destructor Documentation

template<isolation_level ISOLATIONLEVEL = read_committed>
pqxx::robusttransaction< ISOLATIONLEVEL >::robusttransaction ( connection_base C,
const std::string &  Name = std::string() 
)
explicit

Constructor.

Creates robusttransaction of given name

Parameters
CConnection that this robusttransaction should live inside.
Nameoptional human-readable name for this transaction
template<isolation_level ISOLATIONLEVEL = read_committed>
virtual pqxx::robusttransaction< ISOLATIONLEVEL >::~robusttransaction ( ) throw ()
virtual

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