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

#include <transaction_base.hxx>

Inheritance diagram for pqxx::transaction_base:

[legend]

Public Member Functions
	transaction_base ()=delete

	transaction_base (transaction_base const &)=delete

	transaction_base (transaction_base &&)=delete

transaction_base &	operator= (transaction_base const &)=delete

transaction_base &	operator= (transaction_base &&)=delete

virtual	~transaction_base ()=0

void	commit ()
	Commit the transaction. More...

void	abort ()
	Abort the transaction. 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_view	name () const noexcept
	Transaction name, if you passed one to the constructor; or empty string. More...

template<>
zview	query_value (zview query, std::string_view desc)=delete
	Forbidden specialisation: underlying buffer immediately goes out of scope. More...


template<typename... ARGS>
auto	esc (ARGS &&...args) const
	Escape string for use as SQL string literal in this transaction. More...

template<typename... ARGS>
auto	esc_raw (ARGS &&...args) const
	Escape binary data for use as SQL string literal in this transaction. More...

std::string	unesc_raw (zview text) const
	Unescape binary data, e.g. from a table field or notification payload. More...

std::basic_string< std::byte >	unesc_bin (zview text)
	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...

std::basic_string< std::byte >	unesc_bin (char const text[])
	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 (binarystring const &t) const

std::string	quote_raw (unsigned char const bin[], std::size_t len) const
	Binary-escape and quote a binary string for use as an SQL constant. More...

std::string	quote_raw (zview bin) const
	Binary-escape and quote a binary string for use as an SQL constant. More...

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_view bin, char escape_char='\\') const
	Escape string for literal LIKE match. More...

Command execution
There are many functions for executing (or "performing") a command (or "query"). This is the most fundamental thing you can do with the library, and you always do it from a transaction class. Command execution can throw many types of exception, 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 you will see libpqxx are derived from std::exception. One unusual feature in libpqxx is that you can give your query a name or description. This does not mean anything to the database, but sometimes it can help libpqxx produce more helpful error messages, making problems in your code easier to debug.
result	exec (std::string_view query, std::string_view desc=std::string_view{})
	Execute a command. More...

result	exec (std::stringstream const &query, std::string_view desc=std::string_view{})
	Execute a command. More...

result	exec0 (zview query, std::string_view desc=std::string_view{})
	Execute command, which should return zero rows of data. More...

row	exec1 (zview query, std::string_view desc=std::string_view{})
	Execute command returning a single row of data. More...

result	exec_n (result::size_type rows, zview query, std::string_view desc=std::string_view{})
	Execute command, expect given number of rows. More...

template<typename TYPE >
TYPE	query_value (zview query, std::string_view desc=std::string_view{})
	Perform query, expecting exactly 1 row with 1 field, and convert it. More...

template<typename... TYPE>
auto	stream (std::string_view query)
	Execute a query, and loop over the results row by row. 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 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 (zview query, Args &&...args)
	Execute an SQL statement with parameters. More...

template<typename... Args>
row	exec_params1 (zview query, Args &&...args)

template<typename... Args>
result	exec_params0 (zview query, Args &&...args)

template<typename... Args>
result	exec_params_n (std::size_t rows, zview 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 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, you're dealing with binary strings, not regular strings. Represent binary strings on the SQL side as `BYTEA` (or as large objects). On the C++ side, use types like `std::basic_string<std::byte>` or `std::basic_string_view<std::byte>` or (in C++20) `std::vector<std::byte>`. Also, consider large objects on the SQL side and `blob` on the C++ side.
template<typename... Args>
result	exec_prepared (zview statement, Args &&...args)
	Execute a prepared statement, with optional arguments. More...

template<typename... Args>
row	exec_prepared1 (zview statement, Args &&...args)
	Execute a prepared statement, and expect a single-row result. More...

template<typename... Args>
result	exec_prepared0 (zview statement, Args &&...args)
	Execute a prepared statement, and expect a result with zero rows. More...

template<typename... Args>
result	exec_prepared_n (result::size_type rows, zview statement, Args &&...args)
	Execute a prepared statement, expect a result with given number of rows. More...

Error/warning output
void	process_notice (char const msg[]) const
	Have connection process a warning message. More...

void	process_notice (zview msg) const
	Have connection process a warning message. More...

Protected Member Functions
	transaction_base (connection &c, std::string_view tname, std::shared_ptr< std::string > rollback_cmd)
	Create a transaction (to be called by implementation classes only). More...

	transaction_base (connection &c, std::string_view tname)
	Create a transaction (to be called by implementation classes only). More...

	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 ()
	Transaction type-specific way of aborting a transaction. More...

void	set_rollback_cmd (std::shared_ptr< std::string > cmd)
	Set the rollback command. More...

result	direct_exec (std::string_view, std::string_view desc=""sv)
	Execute query on connection directly. More...

result	direct_exec (std::shared_ptr< std::string >, std::string_view desc=""sv)

Friends
class	pqxx::internal::gate::transaction_transaction_focus

Detailed Description

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

Abstract base class for all transaction types.

Constructor & Destructor Documentation

◆ transaction_base() [1/6]

pqxx::transaction_base::transaction_base ( )

delete

◆ transaction_base() [2/6]

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

delete

◆ transaction_base() [3/6]

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

delete

◆ ~transaction_base()

pqxx::transaction_base::~transaction_base ( )

pure virtual

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

◆ transaction_base() [4/6]

pqxx::transaction_base::transaction_base	(	connection &	c,
		std::string_view	tname,
		std::shared_ptr< std::string >	rollback_cmd
	)

protected

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

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

◆ transaction_base() [5/6]

pqxx::transaction_base::transaction_base	(	connection &	c,
		std::string_view	tname
	)

protected

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

Its rollback command will be "ROLLBACK".

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

◆ transaction_base() [6/6]

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

explicitprotected

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

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(), 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(), pqxx::internal::check_unique_register(), pqxx::internal::check_unique_unregister(), pqxx::transaction_focus::classname(), conn(), and pqxx::transaction_focus::name().

Referenced by abort(), commit(), and pqxx::subtransaction::~subtransaction().

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

◆ conn()

connection& pqxx::transaction_base::conn ( ) const

◆ direct_exec() [1/2]

pqxx::result pqxx::transaction_base::direct_exec	(	std::string_view	cmd,
		std::string_view	desc = `""sv`
	)

protected

Execute query on connection directly.

References conn().

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

◆ direct_exec() [2/2]

pqxx::result pqxx::transaction_base::direct_exec	(	std::shared_ptr< std::string >	cmd,
		std::string_view	desc = `""sv`
	)

protected

References conn(), pqxx::internal::describe_object(), name(), and process_notice().

◆ do_abort()

void pqxx::transaction_base::do_abort ( )

protectedvirtual

Transaction type-specific way of aborting a transaction.

Warning: This will become "final", since this function can be called from the implementing class destructor.

References direct_exec().

Referenced by abort(), and pqxx::internal::basic_robusttransaction::basic_robusttransaction().

◆ 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_view	desc = `std::string_view{}`
	)

Execute a command.

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

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

◆ exec() [2/2]

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

Execute a command.

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.

◆ exec0()

result pqxx::transaction_base::exec0	(	zview	query,
		std::string_view	desc = `std::string_view{}`
	)

Execute command, which should return 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.

Referenced by pqxx::stream_from::stream_from().

◆ exec1()

row pqxx::transaction_base::exec1	(	zview	query,
		std::string_view	desc = `std::string_view{}`
	)

Execute command 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,
		zview	query,
		std::string_view	desc = `std::string_view{}`
	)

Execute command, 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(), and exec().

◆ exec_params()

template<typename... Args>

result pqxx::transaction_base::exec_params	(	zview	query,
		Args &&...	args
	)

Execute an SQL statement with parameters.

◆ exec_params0()

template<typename... Args>

result pqxx::transaction_base::exec_params0	(	zview	query,
		Args &&...	args
	)

Exceptions

unexpected_rows if the result contains rows.

◆ exec_params1()

template<typename... Args>

row pqxx::transaction_base::exec_params1	(	zview	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	(	std::size_t	rows,
		zview	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	(	zview	statement,
		Args &&...	args
	)

Execute a prepared statement, with optional arguments.

References pqxx::params::make_c_params().

◆ exec_prepared0()

template<typename... Args>

result pqxx::transaction_base::exec_prepared0	(	zview	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	(	zview	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	(	result::size_type	rows,
		zview	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 ( 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().

◆ name()

std::string_view pqxx::transaction_base::name ( ) const

noexcept

Transaction name, if you passed one to the constructor; or empty string.

Referenced by pqxx::internal::basic_robusttransaction::basic_robusttransaction(), pqxx::internal::basic_transaction::basic_transaction(), pqxx::connection::close(), and direct_exec().

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

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

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 ( zview msg ) const

Have connection process a warning message.

◆ query_value() [1/2]

template<typename TYPE >

TYPE pqxx::transaction_base::query_value	(	zview	query,
		std::string_view	desc = `std::string_view{}`
	)

Perform query, expecting exactly 1 row with 1 field, and convert it.

This is convenience shorthand for querying exactly one value from the database. It returns that value, converted to the type you specify.

◆ query_value() [2/2]

template<>

zview pqxx::transaction_base::query_value	(	zview	query,
		std::string_view	desc
	)

delete

Forbidden specialisation: underlying buffer immediately goes out of scope.

◆ 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_rollback_cmd()

void pqxx::transaction_base::set_rollback_cmd ( std::shared_ptr< std::string > cmd )

protected

Set the rollback command.

Referenced by pqxx::subtransaction::subtransaction().

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

◆ stream()

template<typename... TYPE>

auto pqxx::transaction_base::stream ( std::string_view query )

Execute a query, and loop over the results row by row.

Converts the rows to std::tuple, of the column types you specify.

Use this with a range-based "for" loop. It executes the query, and directly maps the resulting rows onto a std::tuple of the types you specify. It starts before all the data from the server is in, so if your network connection to the server breaks while you're iterating, you'll get an exception partway through.

The stream lives entirely within the lifetime of the transaction. Make sure you destroy the stream before you destroy the transaction. Also, either iterate the stream all the way to the end, or destroy first the stream and then the transaction without touching either in any other way. Until the stream has finished, the transaction is in a special state where it cannot execute queries.

As a special case, tuple may contain std::string_view fields, but the strings to which they point will only remain valid until you extract the next row. After that, the memory holding the string may be overwritten or deallocated.

If any of the columns can be null, and the C++ type to which it translates does not have a null value, wrap the type in std::optional (or if you prefer, std::shared_ptr or std::unique_ptr). These templates do recognise null values, and libpqxx will know how to convert to them.

The connection is in a special state until the iteration finishes. So if it does not finish due to a break or a return or an exception, then the entire connection becomes effectively unusable.

Querying in this way is faster than the exec() methods for larger results (but probably slower for small ones). Also, you can start processing rows before the full result is in. Also, stream() scales better in terms of memory usage. Where exec() reads the entire result into memory at once, stream() will read and process one row at at a time.

Your query executes as part of a COPY command, not as a stand-alone query, so there are limitations to what you can do in the query. It can be either a SELECT or VALUES query; or an INSERT, UPDATE, or DELETE with a RETURNING clause. See the documentation for PostgreSQL's COPY command for the details:

https://www.postgresql.org/docs/current/sql-copy.html

Iterating in this way does require each of the field types you pass to be default-constructible, copy-constructible, and assignable. These requirements may be loosened once libpqxx moves on to C++20.

References pqxx::params::make_c_params(), and pqxx::stream_from::query().

Friends And Related Function Documentation

◆ pqxx::internal::gate::transaction_transaction_focus

friend class pqxx::internal::gate::transaction_transaction_focus

friend

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

transaction_base.hxx
transaction_base.cxx

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ transaction_base() [1/6]

◆ transaction_base() [2/6]

◆ transaction_base() [3/6]

◆ ~transaction_base()

◆ transaction_base() [4/6]

◆ transaction_base() [5/6]

◆ transaction_base() [6/6]

Member Function Documentation

◆ abort()

◆ close()

◆ commit()

◆ conn()

◆ direct_exec() [1/2]

◆ direct_exec() [2/2]

◆ do_abort()

◆ do_commit()

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

◆ name()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ process_notice() [1/2]

◆ process_notice() [2/2]

◆ query_value() [1/2]

◆ query_value() [2/2]

◆ register_transaction()

◆ set_rollback_cmd()

◆ set_variable()

◆ stream()

Friends And Related Function Documentation

◆ pqxx::internal::gate::transaction_transaction_focus