Slightly slower, better-fortified version of transaction. More...
#include <robusttransaction.hxx>
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_base & | operator= (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_base & | conn () 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... | |
| 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:
- 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.
- 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.
- 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.
- 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
| using pqxx::robusttransaction< ISOLATIONLEVEL >::isolation_tag = isolation_traits<ISOLATIONLEVEL> |
Constructor & Destructor Documentation
◆ robusttransaction()
|
explicit |
Constructor.
Creates robusttransaction of given name
- Parameters
-
C Connection that this robusttransaction should live inside. Name optional human-readable name for this transaction
◆ ~robusttransaction()
|
virtualnoexcept |
The documentation for this class was generated from the following file:
