pqxx::transaction_base Class Referenceabstract

`#include <transaction_base.hxx>`

Inheritance diagram for pqxx::transaction_base:

## Public Types

typedef isolation_traits< read_committed > | isolation_tag
| If nothing else is known, our isolation level is at least read_committed. More...

## Public Member Functions

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 str[], 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...
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...
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())
internal::parameterized_invocation | parameterized (const std::string &query)
| Parameterize a statement. 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...
Prepared statements
prepare::invocation | prepared (const std::string &statement=std::string())
| Execute prepared statement. More...
Error/warning output
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, const std::string &Name="")
const std::string & | name () const throw ()
const std::string & | classname () const throw ()
std::string | description () const

## Protected Member Functions

| 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 () throw ()
| End transaction. To be called by implementing class' destructor. More...
virtual void | do_begin ()=0
| To be implemented by derived implementation class: start transaction. More...
virtual result | do_exec (const char Query[])=0
| To be implemented by derived implementation class: perform query. More...
virtual void | do_commit ()=0
| To be implemented by derived implementation class: commit transaction. More...
virtual void | do_abort ()=0
| To be implemented by derived implementation class: abort transaction. More...
result | DirectExec (const char C[], int Retries=0)
| Execute query on connection directly. More...
void | reactivation_avoidance_clear () throw ()
| Forget about any reactivation-blocking resources we tried to allocate. More...

## Protected Attributes

internal::reactivation_avoidance_counter | m_reactivation_avoidance
| Resources allocated in this transaction that make reactivation impossible. More...

## Friends

class | pqxx::internal::gate::transaction_transactionfocus
class | pqxx::internal::gate::transaction_tablereader
class | pqxx::internal::gate::transaction_tablewriter
class | pqxx::internal::gate::transaction_subtransaction

## Member Typedef Documentation

## isolation_tag

typedef isolation_traits<read_committed> pqxx::transaction_base::isolation_tag

If nothing else is known, our isolation level is at least read_committed.

## Constructor & Destructor Documentation

## ~transaction_base()

pqxx::transaction_base::~transaction_base | ( |  | ) |

pure virtual

References conn(), pqxx::internal::namedclass::description(), pqxx::connection_base::process_notice(), process_notice(), and reactivation_avoidance_clear().

## transaction_base()

pqxx::transaction_base::transaction_base | ( | connection_base & | c,
|  | bool | direct = `true`
| ) |  |

explicit protected

Create a transaction (to be called by implementation classes only)

The optional name, if nonempty, must begin with a letter and may contain letters and digits only.

Parameters

  c | The connection that this transaction is to act on.
  direct | Running directly in connection context (i.e. not nested)?

References conn(), and transaction_base().

Referenced by transaction_base().

## Member Function Documentation

## abort()

void pqxx::transaction_base::abort | ( |  | ) |

Abort the transaction.

No special effort is required to call this function; it will be called implicitly when the transaction is destructed.

References pqxx::internal::namedclass::description(), do_abort(), End(), and pqxx::connection_base::process_notice().

Referenced by pqxx::dbtransaction::do_exec(), and End().

## Begin()

void pqxx::transaction_base::Begin | ( |  | ) |

protected

Begin transaction (to be called by implementing class)

Will typically be called from implementing class' constructor.

References do_begin(), End(), and pqxx::connection_base::get_notifs().

Referenced by quote_raw().

## commit()

void pqxx::transaction_base::commit | ( |  | ) |

Commit the transaction.

Unless this function is called explicitly, the transaction will not be committed (actually the nontransaction implementation breaks this rule, hence the name).

Once this function returns, the whole transaction will typically be irrevocably completed in the database. There is also, however, a minute risk that the connection to the database may be lost at just the wrong moment. In that case, libpqxx may be unable to determine whether the transaction was completed or aborted and an in_doubt_error will be thrown to make this fact known to the caller. The robusttransaction implementation takes some special precautions to reduce this risk.

References conn(), pqxx::internal::namedclass::description(), do_commit(), End(), pqxx::connection_base::is_open(), and pqxx::connection_base::process_notice().

## conn()

connection_base& pqxx::transaction_base::conn | ( |  | ) | const

Connection this transaction is running in.

Referenced by pqxx::basic_transaction::basic_transaction(), pqxx::pipeline::cancel(), commit(), DirectExec(), pqxx::dbtransaction::do_begin(), End(), esc_raw(), pqxx::prepare::invocation::exec(), pqxx::prepare::invocation::exists(), get_variable(), parameterized(), quote_raw(), pqxx::largeobject::RawConnection(), pqxx::largeobjectaccess::read(), pqxx::pipeline::resume(), set_variable(), pqxx::internal::sql_cursor::sql_cursor(), pqxx::subtransaction::subtransaction(), transaction_base(), pqxx::basic_robusttransaction::~basic_robusttransaction(), pqxx::pipeline::~pipeline(), pqxx::tablereader::~tablereader(), pqxx::tablewriter::~tablewriter(), and ~transaction_base().

## DirectExec()

pqxx::result pqxx::transaction_base::DirectExec | ( | const char | C[],
|  | int | Retries = `0`
| ) |  |

protected

Execute query on connection directly.

Parameters

  C | Query or command to execute
  Retries | Number of times to retry the query if it fails. Be extremely careful with this option; if you retry in the middle of a transaction, you may be setting up a new connection transparently and executing the latter part of the transaction without a backend transaction being active (and with the former part aborted).

References conn(), exec(), and process_notice().

Referenced by pqxx::basic_transaction::basic_transaction(), pqxx::dbtransaction::do_abort(), pqxx::dbtransaction::do_begin(), pqxx::dbtransaction::do_exec(), pqxx::subtransaction::subtransaction(), and pqxx::basic_robusttransaction::~basic_robusttransaction().

## do_abort()

virtual void pqxx::transaction_base::do_abort | ( |  | ) |

protected pure virtual

To be implemented by derived implementation class: abort transaction.

Implemented in pqxx::dbtransaction.

Referenced by abort().

## do_begin()

virtual void pqxx::transaction_base::do_begin | ( |  | ) |

protected pure virtual

To be implemented by derived implementation class: start transaction.

Implemented in pqxx::dbtransaction.

Referenced by Begin().

## do_commit()

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

protected pure virtual

To be implemented by derived implementation class: commit transaction.

Implemented in pqxx::dbtransaction.

Referenced by commit().

## do_exec()

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

protected pure virtual

To be implemented by derived implementation class: perform query.

Implemented in pqxx::dbtransaction.

Referenced by exec().

## End()

void pqxx::transaction_base::End | ( |  | ) |
throw | ( |
| ) |  |

protected

End transaction. To be called by implementing class' destructor.

References abort(), pqxx::internal::reactivation_avoidance_counter::clear(), conn(), pqxx::internal::namedclass::description(), pqxx::internal::reactivation_avoidance_counter::get(), m_reactivation_avoidance, and pqxx::connection_base::process_notice().

Referenced by abort(), Begin(), and commit().

## exec() [1/2]

pqxx::result pqxx::transaction_base::exec | ( | const std::string & | Query,
|  | const std::string & | Desc = `std::string()`
| ) |  |

Execute query.

Perform a query in this transaction.

This is one of the most important functions in libpqxx.

Most libpqxx exceptions can be thrown from here, including sql_error, broken_connection, and many sql_error subtypes such as feature_not_supported or insufficient_privilege. But any exception thrown by the C++ standard library may also occur here. All exceptions will be derived from std::exception, however, and all libpqxx-specific exception types are derived from pqxx::pqxx_exception.

Parameters

  Query | Query or command to execute
  Desc | Optional identifier for query, to help pinpoint SQL errors

Returns
  A result set describing the query's or command's result

References pqxx::internal::namedclass::description(), and do_exec().

Referenced by pqxx::internal::sql_cursor::close(), DirectExec(), pqxx::pipeline::resume(), and pqxx::internal::sql_cursor::sql_cursor().

## exec() [2/2]

result pqxx::transaction_base::exec | ( | const std::stringstream & | Query,
|  | const std::string & | Desc = `std::string()`
| ) |  |

## get_variable()

string pqxx::transaction_base::get_variable | ( | const std::string & | Var | ) |

Get currently applicable value of variable.

First consults an internal cache of variables that have been set (whether in the ongoing transaction or in the connection) using the set_variable functions. If it is not found there, the database is queried.

Warning
  Do not mix the set_variable with raw "SET" queries, and do not try to set or get variables while a pipeline or table stream is active.
  This function used to be declared as `const` but isn't anymore.

References conn().

## parameterized()

pqxx::internal::parameterized_invocation pqxx::transaction_base::parameterized | ( | const std::string & | query | ) |

Parameterize a statement.

References conn().

## prepared()

pqxx::prepare::invocation pqxx::transaction_base::prepared | ( | const std::string & | statement = `std::string()` | ) |

Execute prepared statement.

Prepared statements are defined using the connection classes' prepare() function, and continue to live on in the ongoing session regardless of the context they were defined in (unless explicitly dropped using the connection's unprepare() function). Their execution however, like other forms of query execution, requires a transaction object.

Just like param_declaration is a helper class that lets you tag parameter declarations onto the statement declaration, the invocation class returned here lets you tag parameter values onto the call:

result run_mystatement(transaction_base &T)
{
return T.prepared("mystatement")("param1")(2)()(4).exec();
}

Here, parameter 1 (written as "<tt>$1</tt>" in the statement's body) is a string that receives the value "param1"; the second parameter is an integer with the value 2; the third receives a null, making its type irrelevant; and number 4 again is an integer. The ultimate invocation of exec() is essential; if you forget this, nothing happens.

To see whether any prepared statement has been defined under a given name, use:

T.prepared("mystatement").exists()

Warning
  Do not try to execute a prepared statement manually through direct SQL statements. This is likely not to work, and even if it does, is likely to be slower than using the proper libpqxx functions. Also, libpqxx knows how to emulate prepared statements if some part of the infrastructure does not support them.
  Actual definition of the prepared statement on the backend may be deferred until its first use, which means that any errors in the prepared statement may not show up until it is executed–and perhaps abort the ongoing transaction in the process.

If you leave out the statement name, the call refers to the nameless statement instead.

## process_notice() [1/2]

void pqxx::transaction_base::process_notice | ( | const char | Msg[] | ) | const

Have connection process warning message.

Referenced by pqxx::basic_transaction::basic_transaction(), DirectExec(), pqxx::largeobjectaccess::process_notice(), pqxx::basic_robusttransaction::~basic_robusttransaction(), and ~transaction_base().

## process_notice() [2/2]

void pqxx::transaction_base::process_notice | ( | const std::string & | Msg | ) | const

Have connection process warning message.

## reactivation_avoidance_clear()

void pqxx::transaction_base::reactivation_avoidance_clear | ( |  | ) |
throw | ( |
| ) |  |

protected

Forget about any reactivation-blocking resources we tried to allocate.

Referenced by pqxx::dbtransaction::do_abort(), and ~transaction_base().

## set_variable()

void pqxx::transaction_base::set_variable | ( | const std::string & | Var,
|  | const std::string & | Val
| ) |  |

Set session variable in this connection.

The new value is typically forgotten if the transaction aborts. Known exceptions to this rule are nontransaction, and PostgreSQL versions prior to 7.3. In the case of nontransaction, the set value will be kept regardless; but in that case, if the connection ever needs to be recovered, the set value will not be restored.

Parameters

  Var | The variable to set
  Val | The new value to store in the variable

References conn().

## Friends And Related Function Documentation

## pqxx::internal::gate::transaction_subtransaction

friend class pqxx::internal::gate::transaction_subtransaction

friend

## pqxx::internal::gate::transaction_tablereader

friend class pqxx::internal::gate::transaction_tablereader

friend

## pqxx::internal::gate::transaction_tablewriter

friend class pqxx::internal::gate::transaction_tablewriter

friend

## pqxx::internal::gate::transaction_transactionfocus

friend class pqxx::internal::gate::transaction_transactionfocus

friend

## Member Data Documentation

## m_reactivation_avoidance

internal::reactivation_avoidance_counter pqxx::transaction_base::m_reactivation_avoidance

protected

Resources allocated in this transaction that make reactivation impossible.

This number may be negative!

Referenced by End(), and pqxx::subtransaction::subtransaction().

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

- transaction_base.hxx
- transaction_base.cxx