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

libpqxx 4.0.1

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | List of all members
pqxx::robusttransaction< ISOLATIONLEVEL > Class Template Reference
Transaction classes

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

`#include <robusttransaction.hxx>`

Inheritance diagram for pqxx::robusttransaction< ISOLATIONLEVEL >:

## 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_base & | conn () 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

  C | Connection that this robusttransaction should live inside.
  Name | optional 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:

- robusttransaction.hxx