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

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

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`
	)

explicitprotected

Member Function Documentation

◆ do_abort()

void pqxx::dbtransaction::do_abort ( )

overrideprotectedvirtual

Sensible default implemented here: abort backend transaction.

Default implementation does two things:

Clears the "connection reactivation avoidance counter"
Executes a ROLLBACK statement

Implements pqxx::transaction_base.

References pqxx::transaction_base::direct_exec(), pqxx::transaction_base::reactivation_avoidance_clear(), and pqxx::internal::sql_rollback_work.

Referenced by pqxx::internal::basic_robusttransaction::~basic_robusttransaction().

◆ do_begin()

void pqxx::dbtransaction::do_begin ( )

overrideprotectedvirtual

Sensible default implemented here: begin backend transaction.

Implements pqxx::transaction_base.

References pqxx::transaction_base::conn(), and pqxx::transaction_base::direct_exec().

Referenced by pqxx::internal::basic_robusttransaction::~basic_robusttransaction().

◆ do_commit()

virtual void pqxx::dbtransaction::do_commit ( )

overrideprotectedpure 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[] )

overrideprotectedvirtual

Sensible default implemented here: perform query.

Implements pqxx::transaction_base.

References pqxx::transaction_base::abort(), and pqxx::transaction_base::direct_exec().

◆ fullname()

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

staticprotected

◆ 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

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~dbtransaction()

◆ dbtransaction() [1/2]

◆ dbtransaction() [2/2]

Member Function Documentation

◆ do_abort()

◆ do_begin()

◆ do_commit()

◆ do_exec()

◆ fullname()

◆ start_backend_transaction()