pqxx::transaction_base Class Reference

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

#include <transaction_base.hxx>

Inheritance diagram for pqxx::transaction_base:

Public Member Functions
	transaction_base ()=delete
	transaction_base (transaction_base const &)=delete
transaction_base &	operator= (transaction_base const &)=delete
virtual	~transaction_base ()=0
void	commit ()
	Commit the transaction. More...
void	abort ()
	Abort the transaction. More...
result	exec (std::string_view query, std::string const &desc=std::string{})
	Execute query. More...
result	exec (std::stringstream const &query, std::string const &desc=std::string{})
result	exec0 (std::string const &query, std::string const &desc=std::string{})
	Execute query, which should zero rows of data. More...
row	exec1 (std::string const &query, std::string const &desc=std::string{})
	Execute query returning a single row of data. More...
result	exec_n (result::size_type rows, std::string const &query, std::string const &desc=std::string{})
	Execute query, expect given number of rows. More...
template<typename TYPE >
TYPE	query_value (std::string const &query, std::string const &desc=std::string{})
	Execute query, expecting exactly 1 row with 1 field. More...
connection &	conn () const
	The connection in which this transaction lives. More...
void	set_variable (std::string_view var, std::string_view value)
	Set session variable using SQL "SET" command. More...
std::string	get_variable (std::string_view)
	Read session variable using SQL "SHOW" command. More...
std::string	esc (char const text[]) const
	Escape string for use as SQL string literal in this transaction. More...
std::string	esc (char const text[], size_t maxlen) const
	Escape string for use as SQL string literal in this transaction. More...
std::string	esc (std::string const &text) const
	Escape string for use as SQL string literal in this transaction. More...
std::string	esc (std::string_view text) const
	Escape string for use as SQL string literal in this transaction. More...
std::string	esc_raw (unsigned char const data[], size_t len) const
	Escape binary data for use as SQL string literal in this transaction. More...
std::string	esc_raw (std::string const &) const
	Escape binary data for use as SQL string literal in this transaction. More...
std::string	unesc_raw (std::string const &text) const
	Unescape binary data, e.g. from a table field or notification payload. More...
std::string	unesc_raw (char const *text) const
	Unescape binary data, e.g. from a table field or notification payload. More...
template<typename T >
std::string	quote (T const &t) const
	Represent object as SQL string, including quoting & escaping. More...
std::string	quote_raw (unsigned char const bin[], size_t len) const
	Binary-escape and quote a binarystring for use as an SQL constant. More...
std::string	quote_raw (std::string const &bin) const
std::string	quote_name (std::string_view identifier) const
	Escape an SQL identifier for use in a query. More...
std::string	esc_like (std::string const &bin, char escape_char='\\') const
	Escape string for literal LIKE match. 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 (std::string const &query, Args &&... args)
	Execute an SQL statement with parameters. More...
template<typename... Args>
row	exec_params1 (std::string const &query, Args &&... args)
template<typename... Args>
result	exec_params0 (std::string const &query, Args &&... args)
template<typename... Args>
result	exec_params_n (size_t rows, std::string const &query, Args &&... args)
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::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 when you also use the libpqxx equivalents. For any given statement, either prepare, manage, and execute it through the dedicated libpqxx functions; or do it all directly in SQL. Don't mix the two, or the code may get confused. 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 (std::string const &statement, Args &&... args)
	Execute a prepared statement, with optional arguments. More...
template<typename... Args>
result	exec_prepared (zview statement, Args &&... args)
template<typename... Args>
row	exec_prepared1 (std::string const &statement, Args &&... args)
	Execute a prepared statement, and expect a single-row result. More...
template<typename... Args>
row	exec_prepared1 (zview statement, Args &&... args)
template<typename... Args>
result	exec_prepared0 (std::string const &statement, Args &&... args)
	Execute a prepared statement, and expect a result with zero rows. More...
template<typename... Args>
result	exec_prepared0 (zview statement, Args &&... args)
template<typename... Args>
result	exec_prepared_n (result::size_type rows, std::string const &statement, Args &&... args)
	Execute a prepared statement, expect a result with given number of rows. More...
template<typename... Args>
result	exec_prepared_n (result::size_type rows, zview statement, Args &&... args)
Error/warning output
void	process_notice (char const msg[]) const
	Have connection process a warning message. More...
void	process_notice (std::string const &msg) const
	Have connection process a warning message. More...
Public Member Functions inherited from pqxx::internal::namedclass
	namedclass (std::string_view classname)
	namedclass (std::string_view classname, std::string_view name)
	namedclass (std::string_view classname, char const name[])
	namedclass (std::string_view classname, std::string &&name)
std::string const &	name () const noexcept
	Object name, or the empty string if no name was given. More...
std::string const &	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 &c)
	Create a transaction (to be called by implementation classes only). More...
void	register_transaction ()
	Register this transaction with the connection. More...
void	close () noexcept
	End transaction. To be called by implementing class' destructor. 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 (std::string_view)
	Execute query on connection directly. More...
result	direct_exec (std::shared_ptr< std::string >)

Friends
class	pqxx::internal::gate::transaction_transactionfocus

Detailed Description

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

Abstract base class for all transaction types.

Constructor & Destructor Documentation

transaction_base() [1/3]

pqxx::transaction_base::transaction_base ( )

delete

transaction_base() [2/3]

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

delete

~transaction_base()

pqxx::transaction_base::~transaction_base ( )

pure virtual

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

transaction_base() [3/3]

pqxx::transaction_base::transaction_base ( connection &  c )

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.

Common code and definitions for the transaction classes.

pqxx::transaction_base defines the interface for any abstract class that represents a database transaction.

Copyright (c) 2000-2020, Jeroen T. Vermeulen.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

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 close(), pqxx::internal::namedclass::description(), do_abort(), and pqxx::connection::process_notice().

Referenced by close().

close()

void pqxx::transaction_base::close ( )

protectednoexcept

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

References abort(), conn(), pqxx::internal::namedclass::description(), and pqxx::connection::process_notice().

Referenced by abort(), and commit().

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 close(), pqxx::internal::namedclass::description(), do_commit(), pqxx::connection::is_open(), and pqxx::connection::process_notice().

Referenced by pqxx::internal::basic_transaction::basic_transaction().

conn()

connection& pqxx::transaction_base::conn

(

)

const

The connection in which this transaction lives.

Referenced by pqxx::internal::basic_robusttransaction::basic_robusttransaction(), pqxx::internal::basic_transaction::basic_transaction(), pqxx::pipeline::cancel(), close(), pqxx::stream_to::complete(), direct_exec(), esc_raw(), exec_n(), pqxx::stream_from::get_raw_line(), get_variable(), quote_raw(), pqxx::largeobject::raw_connection(), register_transaction(), pqxx::largeobject::remove(), pqxx::pipeline::resume(), set_variable(), pqxx::subtransaction::subtransaction(), pqxx::largeobjectaccess::tell(), pqxx::largeobject::to_file(), pqxx::stream_to::~stream_to(), and ~transaction_base().

direct_exec() [1/2]

pqxx::result pqxx::transaction_base::direct_exec ( std::string_view  c )

protected

Execute query on connection directly.

References conn().

Referenced by pqxx::internal::basic_robusttransaction::basic_robusttransaction(), pqxx::internal::basic_transaction::basic_transaction(), exec(), and pqxx::subtransaction::subtransaction().

direct_exec() [2/2]

pqxx::result pqxx::transaction_base::direct_exec ( std::shared_ptr< std::string >  c )

protected

References conn(), and process_notice().

do_abort()

virtual void pqxx::transaction_base::do_abort ( )

protectedpure virtual

To be implemented by derived implementation class: abort transaction.

Referenced by abort().

do_commit()

virtual void pqxx::transaction_base::do_commit ( )

protectedpure virtual

To be implemented by derived implementation class: commit transaction.

Referenced by commit().

exec() [1/2]

pqxx::result pqxx::transaction_base::exec	(	std::string_view	query,
		std::string const &	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.

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

Referenced by exec_n(), and pqxx::pipeline::resume().

exec() [2/2]

result pqxx::transaction_base::exec	(	std::stringstream const &	query,
		std::string const &	desc = std::string{}
	)

exec0()

result pqxx::transaction_base::exec0	(	std::string const &	query,
		std::string const &	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	(	std::string const &	query,
		std::string const &	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	(	result::size_type	rows,
		std::string const &	query,
		std::string const &	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 conn(), pqxx::result::empty(), exec(), and pqxx::to_string().

exec_params()

template<typename... Args>

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

Execute an SQL statement with parameters.

exec_params0()

template<typename... Args>

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

Exceptions

unexpected_rows

if the result contains rows.

exec_params1()

template<typename... Args>

row pqxx::transaction_base::exec_params1	(	std::string const &	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,
		std::string const &	query,
		Args &&...	args
	)

Exceptions

unexpected_rows

if the result contains the wrong number of rows.

exec_prepared() [1/2]

template<typename... Args>

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

Execute a prepared statement, with optional arguments.

References pqxx::zview::c_str().

exec_prepared() [2/2]

template<typename... Args>

result pqxx::transaction_base::exec_prepared	(	zview	statement,
		Args &&...	args
	)

exec_prepared0() [1/2]

template<typename... Args>

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

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

Exceptions

pqxx::unexpected_rows

if the result contained rows.

exec_prepared0() [2/2]

template<typename... Args>

result pqxx::transaction_base::exec_prepared0	(	zview	statement,
		Args &&...	args
	)

exec_prepared1() [1/2]

template<typename... Args>

row pqxx::transaction_base::exec_prepared1	(	std::string const &	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_prepared1() [2/2]

template<typename... Args>

row pqxx::transaction_base::exec_prepared1	(	zview	statement,
		Args &&...	args
	)

References pqxx::row::front().

exec_prepared_n() [1/2]

template<typename... Args>

result pqxx::transaction_base::exec_prepared_n	(	result::size_type	rows,
		std::string const &	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.

exec_prepared_n() [2/2]

template<typename... Args>

result pqxx::transaction_base::exec_prepared_n	(	result::size_type	rows,
		zview	statement,
		Args &&...	args
	)

get_variable()

std::string pqxx::transaction_base::get_variable

(

std::string_view

var

)

Read session variable using SQL "SHOW" command.

Warning

This executes SQL. Do not try to set or get variables while a pipeline or table stream is active.

References conn(), and pqxx::connection::get_variable().

operator=()

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

delete

process_notice() [1/2]

void pqxx::transaction_base::process_notice

(

char const

msg[]

)

const

Have connection process a warning message.

Referenced by pqxx::internal::basic_transaction::basic_transaction(), direct_exec(), pqxx::largeobjectaccess::process_notice(), and ~transaction_base().

process_notice() [2/2]

void pqxx::transaction_base::process_notice

(

std::string const &

msg

)

const

Have connection process a warning message.

query_value()

template<typename TYPE >

TYPE pqxx::transaction_base::query_value	(	std::string const &	query,
		std::string const &	desc = std::string{}
	)

Execute query, expecting exactly 1 row with 1 field.

References pqxx::to_string().

register_transaction()

void pqxx::transaction_base::register_transaction ( )

protected

Register this transaction with the connection.

References conn().

Referenced by pqxx::internal::basic_transaction::basic_transaction().

set_variable()

void pqxx::transaction_base::set_variable	(	std::string_view	var,
		std::string_view	value
	)

Set session variable using SQL "SET" command.

The new value is typically forgotten if the transaction aborts. Not for nontransaction though: in that case the set value will be kept regardless.

Warning

This executes SQL. Do not try to set or get variables while a pipeline or table stream is active.

Parameters

var	The variable to set.
value	The new value to store in the variable.

References conn(), and pqxx::connection::set_variable().

Friends And Related Function Documentation

pqxx::internal::gate::transaction_transactionfocus

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

friend

---

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

• transaction_base.hxx
• transaction_base.cxx