pqxx::dbtransaction Class Referenceabstract
Transaction classes

Abstract base class responsible for bracketing a backend transaction. More...

`#include <dbtransaction.hxx>`

Inheritance diagram for pqxx::dbtransaction:
[legend]

## Public Member Functions

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...
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...
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...
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...
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...
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...

## Protected Member Functions

| 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 void | do_begin () override
| Sensible default implemented here: begin backend transaction. More...
virtual result | do_exec (const char Query[]) override
| Sensible default implemented here: perform query. More...
virtual void | do_commit () override=0
| To be implemented by derived class: commit backend transaction. More...
virtual void | do_abort () override
| Sensible default implemented here: abort backend transaction. 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

static std::string | fullname (const std::string &ttype, const std::string &isolation)

## Additional Inherited Members

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...
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

Abstract base class responsible for bracketing a backend transaction.

Use a dbtransaction-derived object such as "work" (transaction<>) to enclose operations on a database in a single "unit of work." This ensures that the whole series of operations either succeeds as a whole or fails completely. In no case will it leave half-finished work behind in the database.

Once processing on a transaction has succeeded and any changes should be allowed to become permanent in the database, call commit(). If something has gone wrong and the changes should be forgotten, call abort() instead. If you do neither, an implicit abort() is executed at destruction time.

It is an error to abort a transaction that has already been committed, or to commit a transaction that has already been aborted. Aborting an already aborted transaction or committing an already committed one has been allowed to make errors easier to deal with. Repeated aborts or commits have no effect after the first one.

Database transactions are not suitable for guarding long-running processes. If your transaction code becomes too long or too complex, please consider ways to break it up into smaller ones. There's no easy, general way to do this since application-specific considerations become important at this point.

The actual operations for beginning and committing/aborting the backend transaction are implemented by a derived class. The implementing concrete class must also call Begin() and End() from its constructors and destructors, respectively, and implement do_exec().

## Constructor & Destructor Documentation

## ~dbtransaction()

pqxx::dbtransaction::~dbtransaction | ( |  | ) |

virtual

## dbtransaction() [1/2]

pqxx::dbtransaction::dbtransaction | ( | connection_base & | C,
|  | const std::string & | IsolationString,
|  | readwrite_policy | rw = `read_write`
| ) |  |

protected

## dbtransaction() [2/2]

pqxx::dbtransaction::dbtransaction | ( | connection_base & | C,
|  | bool | direct = `true`,
|  | readwrite_policy | rw = `read_write`
| ) |  |

explicit protected

## Member Function Documentation

## do_abort()

void pqxx::dbtransaction::do_abort | ( |  | ) |

override protected virtual

Sensible default implemented here: abort backend transaction.

Default implementation does two things:

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

Implements pqxx::transaction_base.

## do_begin()

void pqxx::dbtransaction::do_begin | ( |  | ) |

override protected virtual

Sensible default implemented here: begin backend transaction.

Implements pqxx::transaction_base.

## do_commit()

virtual void pqxx::dbtransaction::do_commit | ( |  | ) |

override protected pure virtual

To be implemented by derived class: commit backend transaction.

Implements pqxx::transaction_base.

## do_exec()

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

override protected virtual

Sensible default implemented here: perform query.

Implements pqxx::transaction_base.

## fullname()

std::string pqxx::dbtransaction::fullname | ( | const std::string & | ttype,
|  | const std::string & | isolation
| ) |  |

static protected

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

## start_backend_transaction()

void pqxx::dbtransaction::start_backend_transaction | ( |  | ) |

protected

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

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

- dbtransaction.hxx
- dbtransaction.cxx