pqxx::robusttransaction< ISOLATIONLEVEL > Class Template Reference

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

#include <robusttransaction.hxx>

Inheritance diagram for pqxx::robusttransaction< ISOLATIONLEVEL >:

Public Types

using isolation_tag = isolation_traits< ISOLATIONLEVEL >
- Public Types inherited from pqxx::internal::basic_robusttransaction
using isolation_tag = isolation_traits< read_committed >
 Isolation level is read_committed by default. More...
- Public Types inherited from pqxx::transaction_base
using isolation_tag = isolation_traits< read_committed >
 If nothing else is known, our isolation level is at least read_committed. More...

Public Member Functions

 robusttransaction (connection_base &C, const std::string &Name=std::string{})
 Constructor. More...
virtual ~robusttransaction () noexcept
- Public Member Functions inherited from pqxx::internal::basic_robusttransaction
virtual ~basic_robusttransaction ()=0
- Public Member Functions inherited from pqxx::dbtransaction
virtual ~dbtransaction ()
- Public Member Functions inherited from pqxx::transaction_base
 transaction_base ()=delete
 transaction_base (const transaction_base &)=delete
transaction_baseoperator= (const transaction_base &)=delete
virtual ~transaction_base ()=0
void commit ()
 Commit the transaction. More...
void abort ()
 Abort the transaction. 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{})
result exec0 (const std::string &Query, const std::string &Desc=std::string{})
 Execute query, which should zero rows of data. More...
row exec1 (const std::string &Query, const std::string &Desc=std::string{})
 Execute query returning a single row of data. More...
result exec_n (size_t rows, const std::string &Query, const std::string &Desc=std::string{})
 Execute query, expect given number of rows. More...
connection_baseconn () 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...
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 data[], 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...
std::string unesc_raw (const std::string &text) const
 Unescape binary data, e.g. from a table field or notification payload. More...
std::string unesc_raw (const char *text) const
 Unescape binary data, e.g. from a table field or notification payload. 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...
std::string esc_like (const std::string &str, char escape_char='\\') const
 Escape string for literal LIKE match. More...
template<typename ... Args>
result exec_params (const std::string &query, Args &&...args)
 Execute an SQL statement with parameters. More...
template<typename ... Args>
row exec_params1 (const std::string &query, Args &&... args)
template<typename ... Args>
result exec_params0 (const std::string &query, Args &&...args)
template<typename ... Args>
result exec_params_n (size_t rows, const std::string &query, Args &&...args)
internal::parameterized_invocation parameterized (const std::string &query)
 Parameterize a statement. More...
template<typename ... Args>
result exec_prepared (const std::string &statement, Args &&... args)
 Execute a prepared statement, with optional arguments. More...
template<typename ... Args>
row exec_prepared1 (const std::string &statement, Args &&... args)
 Execute a prepared statement, and expect a single-row result. More...
template<typename ... Args>
result exec_prepared0 (const std::string &statement, Args &&... args)
 Execute a prepared statement, and expect a result with zero rows. More...
template<typename ... Args>
result exec_prepared_n (size_t rows, const std::string &statement, Args &&... args)
 Execute a prepared statement, expect a result with given number of rows. 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...
- Public Member Functions inherited from pqxx::internal::namedclass
 namedclass (const std::string &Classname)
 namedclass (const std::string &Classname, const std::string &Name)
const std::string & name () const noexcept
 Object name, or the empty string if no name was given. More...
const std::string & classname () const noexcept
 Class name. More...
std::string description () const
 Combination of class name and object name; or just class name. More...

Additional Inherited Members

- Protected Member Functions inherited from pqxx::internal::basic_robusttransaction
 basic_robusttransaction (connection_base &C, const std::string &IsolationLevel, const std::string &table_name=std::string{})
- 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[]) override
 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 () noexcept
 End transaction. To be called by implementing class' destructor. More...
result direct_exec (const char C[], int Retries=0)
 Execute query on connection directly. More...
void reactivation_avoidance_clear () noexcept
 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::transaction_base
internal::reactivation_avoidance_counter m_reactivation_avoidance
 Resources allocated in this transaction that make reactivation impossible. More...

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

◆ isolation_tag

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

Constructor & Destructor Documentation

◆ robusttransaction()

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


Creates robusttransaction of given name

CConnection that this robusttransaction should live inside.
Nameoptional human-readable name for this transaction

◆ ~robusttransaction()

template<isolation_level ISOLATIONLEVEL = read_committed>
virtual pqxx::robusttransaction< ISOLATIONLEVEL >::~robusttransaction ( )

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