Interface definition (and common code) for "transaction" classes. More...

#include <transaction_base.hxx>

Inheritance diagram for pqxx::transaction_base:

[legend]

Public Types
using	isolation_tag = isolation_traits< read_committed >
	If nothing else is known, our isolation level is at least read_committed. More...

Public Member Functions
	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...

Parameterized statements
You'll often need parameters in the queries you execute: "select the car with this licence plate." If the parameter is a string, you need to quote it and escape any special characters inside it, or it may become a target for an SQL injection attack. If it's an integer (for example), you need to convert it to a string, but in the database's format, without locale-specific niceties like "," separators between the thousands. Parameterised statements are an easier and safer way to do this. They're like prepared statements, but for a single use. You don't need to name them, and you don't need to prepare them first. Your query will include placeholders like `$1` and $2 etc. in the places where you want the arguments to go. Then, you pass the argument values and the actual query is constructed for you. Pass the exact right number of parameters, and in the right order. The parameters in the query don't have to be neatly ordered from `$1` to `$2` to `$3` - but you must pass the argument for `$1` first, the one for `$2` second, etc. Warning Beware of "nul" bytes. Any string you pass as a parameter will end at the first char with value zero. If you pass a `std::string` that contains a zero byte, the last byte in the value will be the one just before the zero.
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...

Prepared statements
These are very similar to parameterised statements. The difference is that you prepare them in advance, giving them identifying names. You can then call them by these names, passing in the argument values appropriate for that call. You prepare a statement on the connection, using `pqxx::connection_base::prepare()`. But you then call the statement in a transaction, using the functions you see here. Never try to prepare, execute, or unprepare a prepared statement manually using direct SQL queries. Always use the functions provided by libpqxx. See Prepared statements for a full discussion. Warning Beware of "nul" bytes. Any string you pass as a parameter will end at the first char with value zero. If you pass a `std::string` that contains a zero byte, the last byte in the value will be the one just before the zero. If you need a zero byte, consider using pqxx::binarystring and/or SQL's `bytea` type.
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...

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)

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

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

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

Detailed Description

Interface definition (and common code) for "transaction" classes.

Abstract base class for all transaction types.

Member Typedef Documentation

◆ isolation_tag

using pqxx::transaction_base::isolation_tag = isolation_traits<read_committed>

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

Constructor & Destructor Documentation

◆ transaction_base() [1/3]

pqxx::transaction_base::transaction_base ( )

delete

◆ transaction_base() [2/3]

pqxx::transaction_base::transaction_base ( const transaction_base & )

delete

◆ ~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() [3/3]

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

explicitprotected

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

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

◆ direct_exec()

pqxx::result pqxx::transaction_base::direct_exec	(	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::internal::basic_transaction::basic_transaction(), pqxx::dbtransaction::do_abort(), pqxx::dbtransaction::do_begin(), pqxx::dbtransaction::do_exec(), pqxx::subtransaction::subtransaction(), pqxx::internal::basic_robusttransaction::~basic_robusttransaction(), and pqxx::nontransaction::~nontransaction().

◆ do_abort()

virtual void pqxx::transaction_base::do_abort ( )

protectedpure 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 ( )

protectedpure 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 ( )

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

protectedpure virtual

To be implemented by derived implementation class: perform query.

Implemented in pqxx::dbtransaction.

Referenced by exec().

◆ End()

void pqxx::transaction_base::End ( )

protectednoexcept

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(), commit(), and pqxx::nontransaction::~nontransaction().

◆ 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(), direct_exec(), exec_n(), 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()`
	)

◆ exec0()

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

Execute query, which should zero rows of data.

Works like exec, but fails if the result contains data. It still returns a result, however, which may contain useful metadata.

Exceptions

unexpected_rows If the query returned the wrong number of rows.

◆ exec1()

row pqxx::transaction_base::exec1	(	const std::string &	Query,
		const std::string &	Desc = `std::string()`
	)

Execute query returning a single row of data.

Works like exec, but requires the result to contain exactly one row. The row can be addressed directly, without the need to find the first row in a result set.

Exceptions

unexpected_rows If the query returned the wrong number of rows.

References pqxx::row::front().

◆ exec_n()

pqxx::result pqxx::transaction_base::exec_n	(	size_t	rows,
		const std::string &	Query,
		const std::string &	Desc = `std::string()`
	)

Execute query, expect given number of rows.

Works like exec, but checks that the number of rows is exactly what's expected.

Exceptions

unexpected_rows If the query returned the wrong number of rows.

References exec(), pqxx::result::size(), and pqxx::to_string().

◆ exec_params()

template<typename ... Args>

result pqxx::transaction_base::exec_params	(	const std::string &	query,
		Args &&...	args
	)

Execute an SQL statement with parameters.

◆ exec_params0()

template<typename ... Args>

result pqxx::transaction_base::exec_params0	(	const std::string &	query,
		Args &&...	args
	)

Exceptions

unexpected_rows if the result contains rows.

◆ exec_params1()

template<typename ... Args>

row pqxx::transaction_base::exec_params1	(	const std::string &	query,
		Args &&...	args
	)

Exceptions

unexpected_rows if the result does not consist of exactly one row.

References pqxx::row::front().

◆ exec_params_n()

template<typename ... Args>

result pqxx::transaction_base::exec_params_n	(	size_t	rows,
		const std::string &	query,
		Args &&...	args
	)

Exceptions

unexpected_rows if the result contains the wrong number of rows.

◆ exec_prepared()

template<typename ... Args>

result pqxx::transaction_base::exec_prepared	(	const std::string &	statement,
		Args &&...	args
	)

Execute a prepared statement, with optional arguments.

◆ exec_prepared0()

template<typename ... Args>

result pqxx::transaction_base::exec_prepared0	(	const std::string &	statement,
		Args &&...	args
	)

Execute a prepared statement, and expect a result with zero rows.

Exceptions

pqxx::unexpected_rows if the result contained rows.

◆ exec_prepared1()

template<typename ... Args>

row pqxx::transaction_base::exec_prepared1	(	const std::string &	statement,
		Args &&...	args
	)

Execute a prepared statement, and expect a single-row result.

Exceptions

pqxx::unexpected_rows if the result was not exactly 1 row.

References pqxx::row::front().

◆ exec_prepared_n()

template<typename ... Args>

result pqxx::transaction_base::exec_prepared_n	(	size_t	rows,
		const std::string &	statement,
		Args &&...	args
	)

Execute a prepared statement, expect a result with given number of rows.

Exceptions

pqxx::unexpected_rows if the result did not contain exactly the given number of rows.

◆ get_variable()

std::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().

◆ operator=()

transaction_base& pqxx::transaction_base::operator= ( const transaction_base & )

delete

◆ parameterized()

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

Parameterize a statement.

Deprecated:: Use exec_params instead.

References conn().

◆ prepared()

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

Execute prepared statement.

Deprecated:: Use exec_prepared instead.

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.exec_prepared("mystatement", "param1", 2, nullptr, 4);
}

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.

References conn().

◆ process_notice() [1/2]

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

Have connection process warning message.

Referenced by pqxx::internal::basic_transaction::basic_transaction(), direct_exec(), pqxx::largeobjectaccess::process_notice(), pqxx::internal::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 ( )

protectednoexcept

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. However nontransaction is an exception to this rule: in that case the set value will be kept regardless. Also, if the connection ever needs to be recovered, a value you set in a nontransaction 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

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ isolation_tag

Constructor & Destructor Documentation

◆ transaction_base() [1/3]

◆ transaction_base() [2/3]

◆ ~transaction_base()

◆ transaction_base() [3/3]

Member Function Documentation

◆ abort()

◆ Begin()

◆ commit()

◆ conn()

◆ direct_exec()

◆ do_abort()

◆ do_begin()

◆ do_commit()

◆ do_exec()

◆ End()

◆ exec() [1/2]

◆ exec() [2/2]

◆ exec0()

◆ exec1()

◆ exec_n()

◆ exec_params()

◆ exec_params0()

◆ exec_params1()

◆ exec_params_n()

◆ exec_prepared()

◆ exec_prepared0()

◆ exec_prepared1()

◆ exec_prepared_n()

◆ get_variable()

◆ operator=()

◆ parameterized()

◆ prepared()

◆ process_notice() [1/2]

◆ process_notice() [2/2]

◆ reactivation_avoidance_clear()

◆ set_variable()

Friends And Related Function Documentation

◆ pqxx::internal::gate::transaction_subtransaction

◆ pqxx::internal::gate::transaction_tablereader

◆ pqxx::internal::gate::transaction_tablewriter

◆ pqxx::internal::gate::transaction_transactionfocus

Member Data Documentation

◆ m_reactivation_avoidance