Classes
class	pqxx::dbtransaction
	Abstract transaction base class: bracket transactions on the database. More...

class	pqxx::nontransaction
	Simple "transaction" class offering no transactional integrity. More...

class	pqxx::subtransaction
	"Transaction" nested within another transaction More...

class	pqxx::transaction_base
	Interface definition (and common code) for "transaction" classes. More...

Detailed Description

All database access goes through instances of these classes. In libpqxx you can't execute SQL directly on the connection object; that all happens only on a transaction object. If you don't actually want to start a transaction on the server, there's a nontransaction class which operates in autocommit, i.e. without a transaction.

(Why do you always need a transaction object? It ended up being the cleaner choice in terms of interface design. It avoids a bunch of API maladies: duplicating API between classes, messy inheritance, inviting mistakes by making the transaction afterthought, and so on.)

Like most other things in libpqxx, transactions follow RAII principles. Creating a transaction object starts the transaction on the backend (if appropriate), and to destroying one ends the transaction. But there's one extra step: if you want to make the transaction's changes permanent, you need to commit it before you destroy it. If you destroy the transaction object without committing, or if you call its abort() member function, then any transaction type (other than nontransaction) will roll back its changes to the database instead.

There is a choice of transaction types. To start with you'll probably want to use work, represents a regular, vanilla transaction with the default isolation level.

All the actual transaction functionality, including all the functions for executing SQL statements, lives in the abstract transaction_base class. It defines the API for each type of transaction. You create a transaction, you use it by calling transaction_base member functions, and then you either commit or (in the case of failure) abort. If you destroy your transaction object without doing either, it automatically aborts.

Once you're done with your transaction, you can start a new one using the same connection. But there can be only one main transaction going on on a connection at any given time. (You can have more "nested" transactions, but I'm not counting those as "main" transactions here. See below.)

The concrete transaction types, all derived from transaction_base, are:

First and foremost, the plain transaction template. Template parameters let you select isolation level, and whether it should be read-only. Two aliases are usually more convenient: work is a regular, run-of-the-mill default transaction. read_transaction is a read-only transaction that will not let you modify the database.

Then there's nontransaction. This one runs in autocommit, meaning that we don't start any transaction at all. (Technically in this mode each SQL command runs in its own little transaction, hence the term "autocommit." There is no way to "undo" an SQL statement in this kind of transaction.) Autocommit is sometimes a bit faster, and sometimes a bit slower. Mainly you'll use it for specific operations that cannot be done inside a database transaction, such as some kinds of schema changes.

And then ther's robusttransaction to help you deal with those painful situations where you don't know for sure whether a transaction actually succeeded. This can happen if you lose your network connection to the database just while you're trying to commit your transaction, before you receive word about the outcome. You can re-connect and find out, but what if the server is still executing the commit?

You could say that robusttransaction is not more robust, exactly, but it goes to some extra effort to try and figure these situations out and give you clarity. Extra effort does actually mean more things that can go wrong, and it may be a litte slower, so investigate carefully before using this transaction class.

All of the transaction types that actually begin and commit/abort on the database itself are derived from dbtransaction, which can be a useful type if your code needs a reference to such a transaction but doesn't need to enforce a particular one. These types are transaction, work, read_transaction, and robusttransaction.

Finally, there's subtransaction. This one is not at all like the others: it can only exist inside a dbtransaction. (Which includes subtransaction itself: you can nest them freely.) You can only operate on the "innermost" active subtransaction at any given time, until you either commit or abort it. Subtransactions are built on savepoints in the database; these are efficient to a point but do consume some server resources. So use them when they make sense, e.g. to try an SQL statement but continue your main transation if it fails. But don't create them in enormous numbers, or performance may start to suffer.

Class Documentation

◆ pqxx::dbtransaction

class pqxx::dbtransaction

Abstract transaction base class: bracket transactions on the database.

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 is allowed, to make error handling easier. 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, consider ways to break it up into smaller ones. Unfortunately there is no universal recipe for this.

The actual operations for committing/aborting the backend transaction are implemented by a derived class. The implementing concrete class must also call close from its destructor.

Inheritance diagram for pqxx::dbtransaction:

Collaboration diagram for pqxx::dbtransaction:

Protected Member Functions
	dbtransaction (connection &cx)
	Begin transaction.

	dbtransaction (connection &cx, std::string_view tname)
	Begin transaction.

	dbtransaction (connection &cx, std::string_view tname, std::shared_ptr< std::string > rollback_cmd)
	Begin transaction.

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

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

	transaction_base (connection &cx)
	Create a transaction (to be called by implementation classes only).

void	register_transaction ()
	Register this transaction with the connection.

void	close () noexcept
	End transaction. To be called by implementing class' destructor.

virtual void	do_commit ()=0
	To be implemented by derived implementation class: commit transaction.

virtual void	do_abort ()
	Transaction type-specific way of aborting a transaction.

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

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

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

Additional Inherited Members
Public Member Functions inherited from pqxx::transaction_base
	transaction_base (transaction_base const &)=delete

	transaction_base (transaction_base &&)=delete

transaction_base &	operator= (transaction_base const &)=delete

transaction_base &	operator= (transaction_base &&)=delete

void	commit ()
	Commit the transaction.

void	abort ()
	Abort the transaction.

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

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

std::string	unesc_raw (zview text) const
	Unescape binary data, e.g. from a `bytea` field.

bytes	unesc_bin (zview text)
	Unescape binary data, e.g. from a `bytea` field.

std::string	unesc_raw (char const *text) const
	Unescape binary data, e.g. from a `bytea` field.

bytes	unesc_bin (char const text[])
	Unescape binary data, e.g. from a `bytea` field.

template<typename T >
std::string	quote (T const &t) const
	Represent object as SQL string, including quoting & escaping.

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.

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

std::string	quote_name (std::string_view identifier) const
	Escape an SQL identifier for use in a query.

std::string	esc_like (std::string_view bin, char escape_char='\\') const
	Escape string for literal LIKE match.

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

result	exec (std::string_view query, std::string_view desc)
	Execute a command.

result	exec (std::string_view query, params parms)

result	exec (std::string_view query)
	Execute a command.

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

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

result	exec0 (zview query)
	Execute command, which should return zero rows of data.

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

row	exec1 (zview query)
	Execute command returning a single row of data.

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

result	exec_n (result::size_type rows, zview query)
	Execute command, expect given number of rows.

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

template<typename TYPE >
TYPE	query_value (zview query)
	Perform query, expecting exactly 1 row with 1 field, and convert it.

template<typename... TYPE>
std::tuple< TYPE... >	query1 (zview query)
	Perform query returning exactly one row, and convert its fields.

template<typename... TYPE>
std::optional< std::tuple< TYPE... > >	query01 (zview query)
	Query at most one row of data, and if there is one, convert it.

template<typename... TYPE>
auto	stream (std::string_view query) &
	Execute a query, in streaming fashion; loop over the results row by row.

template<typename... TYPE>
auto	stream (std::string_view query, params parms) &
	Execute a query, in streaming fashion; loop over the results row by row.

template<typename CALLABLE >
auto	for_stream (std::string_view query, CALLABLE &&func)
	Perform a streaming query, and for each result row, call `func`.

template<typename CALLABLE >
auto	for_each (std::string_view query, CALLABLE &&func)

template<typename... TYPE>
auto	query (zview query)
	Execute query, read full results, then iterate rows of data.

template<typename... TYPE>
auto	query_n (result::size_type rows, zview query)
	Perform query, expect given number of rows, iterate results.

template<typename CALLABLE >
void	for_query (zview query, CALLABLE &&func)
	Execute a query, load the full result, and perform `func` for each row.

template<typename... Args>
result	exec_params (std::string_view query, Args &&...args)
	Execute an SQL statement with parameters.

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)

template<typename... Args>
result	exec_params_n (result::size_type rows, zview query, Args &&...args)

template<typename... TYPE>
auto	query (zview query, params const &parms)
	Execute parameterised query, read full results, iterate rows of data.

template<typename... TYPE>
auto	query_n (result::size_type rows, zview query, params const &parms)

template<typename TYPE >
TYPE	query_value (zview query, params const &parms)
	Perform query, expecting exactly 1 row with 1 field, and convert it.

template<typename... TYPE>
std::tuple< TYPE... >	query1 (zview query, params const &parms)
	Perform query returning exactly one row, and convert its fields.

template<typename... TYPE>
std::optional< std::tuple< TYPE... > >	query01 (zview query, params const &parms)
	Query at most one row of data, and if there is one, convert it.

template<typename CALLABLE >
void	for_query (zview query, CALLABLE &&func, params const &parms)
	Execute a query, load the full result, and perform `func` for each row.

void	notify (std::string_view channel, std::string_view payload={})
	Send a notification.

template<typename... Args>
result	exec_prepared (zview statement, Args &&...args)
	Execute a prepared statement, with optional arguments.

result	exec (prepped statement)
	Execute a prepared statement taking no parameters.

template<typename... TYPE>
auto	query (prepped statement, params const &parms={})
	Execute prepared statement, read full results, iterate rows of data.

template<typename TYPE >
TYPE	query_value (prepped statement, params const &parms={})
	Perform prepared statement returning exactly 1 value.

template<typename CALLABLE >
void	for_query (prepped statement, CALLABLE &&func, params const &parms={})
	Execute prepared statement, load result, perform `func` for each row.

result	exec (prepped statement, params const &parms)
	Execute a prepared statement with parameters.

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

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

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.

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

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

constexpr connection &	conn () const noexcept
	The connection in which this transaction lives.

void	set_variable (std::string_view var, std::string_view value)
	Set session variable using SQL "SET" command.

std::string	get_variable (std::string_view)
	Read session variable using SQL "SHOW" command.

std::string_view	name () const &noexcept
	Transaction name, if you passed one to the constructor; or empty string.

◆ pqxx::nontransaction

class pqxx::nontransaction

Simple "transaction" class offering no transactional integrity.

nontransaction, like transaction or any other transaction_base-derived class, provides access to a database through a connection. Unlike its siblings, however, nontransaction does not maintain any kind of transactional integrity. This may be useful eg. for read-only access to the database that does not require a consistent, atomic view on its data; or for operations that are not allowed within a backend transaction, such as creating tables.

For queries that update the database, however, a real transaction is likely to be faster unless the transaction consists of only a single record update.

Also, you can keep a nontransaction open for as long as you like. Actual back-end transactions are limited in lifespan, and will sometimes fail just because they took too long to execute or were left idle for too long. This will not happen with a nontransaction (although the connection may still time out, e.g. when the network is unavailable for a very long time).

Any query executed in a nontransaction is committed immediately, and neither commit() nor abort() has any effect as far as the database is concerned. Just like other transaction types, however, the nontransaction remains attached to the pqxx::connection until you commit, abort, or destroy it. Just like a regular transaction, it is a transaction_focus, of which no more than one can be active for any given connection at any given time.

Database features that require a backend transaction, such as cursors or large objects, will not work in a nontransaction.

Inheritance diagram for pqxx::nontransaction:

Collaboration diagram for pqxx::nontransaction:

Public Member Functions
	nontransaction (connection &cx, std::string_view tname=""sv)
	Constructor.

Public Member Functions inherited from pqxx::transaction_base
	transaction_base (transaction_base const &)=delete

	transaction_base (transaction_base &&)=delete

transaction_base &	operator= (transaction_base const &)=delete

transaction_base &	operator= (transaction_base &&)=delete

void	commit ()
	Commit the transaction.

void	abort ()
	Abort the transaction.

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

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

std::string	unesc_raw (zview text) const
	Unescape binary data, e.g. from a `bytea` field.

bytes	unesc_bin (zview text)
	Unescape binary data, e.g. from a `bytea` field.

std::string	unesc_raw (char const *text) const
	Unescape binary data, e.g. from a `bytea` field.

bytes	unesc_bin (char const text[])
	Unescape binary data, e.g. from a `bytea` field.

template<typename T >
std::string	quote (T const &t) const
	Represent object as SQL string, including quoting & escaping.

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.

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

std::string	quote_name (std::string_view identifier) const
	Escape an SQL identifier for use in a query.

std::string	esc_like (std::string_view bin, char escape_char='\\') const
	Escape string for literal LIKE match.

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

result	exec (std::string_view query, std::string_view desc)
	Execute a command.

result	exec (std::string_view query, params parms)

result	exec (std::string_view query)
	Execute a command.

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

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

result	exec0 (zview query)
	Execute command, which should return zero rows of data.

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

row	exec1 (zview query)
	Execute command returning a single row of data.

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

result	exec_n (result::size_type rows, zview query)
	Execute command, expect given number of rows.

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

template<typename TYPE >
TYPE	query_value (zview query)
	Perform query, expecting exactly 1 row with 1 field, and convert it.

template<typename... TYPE>
std::tuple< TYPE... >	query1 (zview query)
	Perform query returning exactly one row, and convert its fields.

template<typename... TYPE>
std::optional< std::tuple< TYPE... > >	query01 (zview query)
	Query at most one row of data, and if there is one, convert it.

template<typename... TYPE>
auto	stream (std::string_view query) &
	Execute a query, in streaming fashion; loop over the results row by row.

template<typename... TYPE>
auto	stream (std::string_view query, params parms) &
	Execute a query, in streaming fashion; loop over the results row by row.

template<typename CALLABLE >
auto	for_stream (std::string_view query, CALLABLE &&func)
	Perform a streaming query, and for each result row, call `func`.

template<typename CALLABLE >
auto	for_each (std::string_view query, CALLABLE &&func)

template<typename... TYPE>
auto	query (zview query)
	Execute query, read full results, then iterate rows of data.

template<typename... TYPE>
auto	query_n (result::size_type rows, zview query)
	Perform query, expect given number of rows, iterate results.

template<typename CALLABLE >
void	for_query (zview query, CALLABLE &&func)
	Execute a query, load the full result, and perform `func` for each row.

template<typename... Args>
result	exec_params (std::string_view query, Args &&...args)
	Execute an SQL statement with parameters.

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)

template<typename... Args>
result	exec_params_n (result::size_type rows, zview query, Args &&...args)

template<typename... TYPE>
auto	query (zview query, params const &parms)
	Execute parameterised query, read full results, iterate rows of data.

template<typename... TYPE>
auto	query_n (result::size_type rows, zview query, params const &parms)

template<typename TYPE >
TYPE	query_value (zview query, params const &parms)
	Perform query, expecting exactly 1 row with 1 field, and convert it.

template<typename... TYPE>
std::tuple< TYPE... >	query1 (zview query, params const &parms)
	Perform query returning exactly one row, and convert its fields.

template<typename... TYPE>
std::optional< std::tuple< TYPE... > >	query01 (zview query, params const &parms)
	Query at most one row of data, and if there is one, convert it.

template<typename CALLABLE >
void	for_query (zview query, CALLABLE &&func, params const &parms)
	Execute a query, load the full result, and perform `func` for each row.

void	notify (std::string_view channel, std::string_view payload={})
	Send a notification.

template<typename... Args>
result	exec_prepared (zview statement, Args &&...args)
	Execute a prepared statement, with optional arguments.

result	exec (prepped statement)
	Execute a prepared statement taking no parameters.

template<typename... TYPE>
auto	query (prepped statement, params const &parms={})
	Execute prepared statement, read full results, iterate rows of data.

template<typename TYPE >
TYPE	query_value (prepped statement, params const &parms={})
	Perform prepared statement returning exactly 1 value.

template<typename CALLABLE >
void	for_query (prepped statement, CALLABLE &&func, params const &parms={})
	Execute prepared statement, load result, perform `func` for each row.

result	exec (prepped statement, params const &parms)
	Execute a prepared statement with parameters.

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

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

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.

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

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

constexpr connection &	conn () const noexcept
	The connection in which this transaction lives.

void	set_variable (std::string_view var, std::string_view value)
	Set session variable using SQL "SET" command.

std::string	get_variable (std::string_view)
	Read session variable using SQL "SHOW" command.

std::string_view	name () const &noexcept
	Transaction name, if you passed one to the constructor; or empty string.

Additional Inherited Members
Protected Member Functions inherited from pqxx::transaction_base
	transaction_base (connection &cx, std::string_view tname, std::shared_ptr< std::string > rollback_cmd)
	Create a transaction (to be called by implementation classes only).

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

	transaction_base (connection &cx)
	Create a transaction (to be called by implementation classes only).

void	register_transaction ()
	Register this transaction with the connection.

void	close () noexcept
	End transaction. To be called by implementing class' destructor.

virtual void	do_abort ()
	Transaction type-specific way of aborting a transaction.

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

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

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

Constructor & Destructor Documentation

◆ nontransaction()

pqxx::nontransaction::nontransaction	(	connection &	cx,
		std::string_view	tname = `""sv`
	)

inline

Constructor.

Create a "dummy" transaction.

Parameters

cx	Connection in which this "transaction" will operate.
tname	Optional tname for the transaction, beginning with a letter and containing only letters and digits.

◆ pqxx::subtransaction

class pqxx::subtransaction

"Transaction" nested within another transaction

A subtransaction can be executed inside a backend transaction, or inside another subtransaction. This can be useful when, for example, statements in a transaction may harmlessly fail and you don't want them to abort the entire transaction. Here's an example of how a temporary table may be dropped before re-creating it, without failing if the table did not exist:

void do_job(connection &cx)
{
  string const temptable = "fleetingtable";
 
  work tx(cx, "do_job");
  do_firstpart(tx);
 
  // Attempt to delete our temporary table if it already existed.
  try
  {
    subtransaction S(tx, "droptemp");
    S.exec0("DROP TABLE " + temptable);
    S.commit();
  }
  catch (undefined_table const &)
  {
    // Table did not exist.  Which is what we were hoping to achieve anyway.
    // Carry on without regrets.
  }
 
  // S may have gone into a failed state and been destroyed, but the
  // upper-level transaction tx is still fine.  We can continue to use it.
  tx.exec0("CREATE TEMP TABLE " + temptable + "(bar integer, splat
varchar)");
 
  do_lastpart(tx);
}

(This is just an example. If you really wanted to do drop a table without an error if it doesn't exist, you'd use DROP TABLE IF EXISTS.)

There are no isolation levels inside a transaction. They are not needed because all actions within the same backend transaction are always performed sequentially anyway.

Warning: While the subtransaction is "live," you cannot execute queries or open streams etc. on its parent transaction. A transaction can have at most one object of a type derived from pqxx::transaction_focus active on it at a time.

Inheritance diagram for pqxx::subtransaction:

Collaboration diagram for pqxx::subtransaction:

Public Member Functions
	subtransaction (dbtransaction &t, std::string_view tname=""sv)
	Nest a subtransaction nested in another transaction.

	subtransaction (subtransaction &t, std::string_view name=""sv)
	Nest a subtransaction in another subtransaction.

Public Member Functions inherited from pqxx::transaction_focus
	transaction_focus (transaction_base &t, std::string_view cname, std::string_view oname)

	transaction_focus (transaction_base &t, std::string_view cname, std::string &&oname)

	transaction_focus (transaction_base &t, std::string_view cname)

	transaction_focus (transaction_focus const &)=delete

transaction_focus &	operator= (transaction_focus const &)=delete

constexpr std::string_view	classname () const noexcept
	Class name, for human consumption.

std::string_view	name () const &noexcept
	Name for this object, if the caller passed one; empty string otherwise.

std::string	description () const

	transaction_focus (transaction_focus &&other)

transaction_focus &	operator= (transaction_focus &&other)

Public Member Functions inherited from pqxx::transaction_base
	transaction_base (transaction_base const &)=delete

	transaction_base (transaction_base &&)=delete

transaction_base &	operator= (transaction_base const &)=delete

transaction_base &	operator= (transaction_base &&)=delete

void	commit ()
	Commit the transaction.

void	abort ()
	Abort the transaction.

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

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

std::string	unesc_raw (zview text) const
	Unescape binary data, e.g. from a `bytea` field.

bytes	unesc_bin (zview text)
	Unescape binary data, e.g. from a `bytea` field.

std::string	unesc_raw (char const *text) const
	Unescape binary data, e.g. from a `bytea` field.

bytes	unesc_bin (char const text[])
	Unescape binary data, e.g. from a `bytea` field.

template<typename T >
std::string	quote (T const &t) const
	Represent object as SQL string, including quoting & escaping.

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.

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

std::string	quote_name (std::string_view identifier) const
	Escape an SQL identifier for use in a query.

std::string	esc_like (std::string_view bin, char escape_char='\\') const
	Escape string for literal LIKE match.

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

result	exec (std::string_view query, std::string_view desc)
	Execute a command.

result	exec (std::string_view query, params parms)

result	exec (std::string_view query)
	Execute a command.

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

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

result	exec0 (zview query)
	Execute command, which should return zero rows of data.

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

row	exec1 (zview query)
	Execute command returning a single row of data.

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

result	exec_n (result::size_type rows, zview query)
	Execute command, expect given number of rows.

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

template<typename TYPE >
TYPE	query_value (zview query)
	Perform query, expecting exactly 1 row with 1 field, and convert it.

template<typename... TYPE>
std::tuple< TYPE... >	query1 (zview query)
	Perform query returning exactly one row, and convert its fields.

template<typename... TYPE>
std::optional< std::tuple< TYPE... > >	query01 (zview query)
	Query at most one row of data, and if there is one, convert it.

template<typename... TYPE>
auto	stream (std::string_view query) &
	Execute a query, in streaming fashion; loop over the results row by row.

template<typename... TYPE>
auto	stream (std::string_view query, params parms) &
	Execute a query, in streaming fashion; loop over the results row by row.

template<typename CALLABLE >
auto	for_stream (std::string_view query, CALLABLE &&func)
	Perform a streaming query, and for each result row, call `func`.

template<typename CALLABLE >
auto	for_each (std::string_view query, CALLABLE &&func)

template<typename... TYPE>
auto	query (zview query)
	Execute query, read full results, then iterate rows of data.

template<typename... TYPE>
auto	query_n (result::size_type rows, zview query)
	Perform query, expect given number of rows, iterate results.

template<typename CALLABLE >
void	for_query (zview query, CALLABLE &&func)
	Execute a query, load the full result, and perform `func` for each row.

template<typename... Args>
result	exec_params (std::string_view query, Args &&...args)
	Execute an SQL statement with parameters.

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)

template<typename... Args>
result	exec_params_n (result::size_type rows, zview query, Args &&...args)

template<typename... TYPE>
auto	query (zview query, params const &parms)
	Execute parameterised query, read full results, iterate rows of data.

template<typename... TYPE>
auto	query_n (result::size_type rows, zview query, params const &parms)

template<typename TYPE >
TYPE	query_value (zview query, params const &parms)
	Perform query, expecting exactly 1 row with 1 field, and convert it.

template<typename... TYPE>
std::tuple< TYPE... >	query1 (zview query, params const &parms)
	Perform query returning exactly one row, and convert its fields.

template<typename... TYPE>
std::optional< std::tuple< TYPE... > >	query01 (zview query, params const &parms)
	Query at most one row of data, and if there is one, convert it.

template<typename CALLABLE >
void	for_query (zview query, CALLABLE &&func, params const &parms)
	Execute a query, load the full result, and perform `func` for each row.

void	notify (std::string_view channel, std::string_view payload={})
	Send a notification.

template<typename... Args>
result	exec_prepared (zview statement, Args &&...args)
	Execute a prepared statement, with optional arguments.

result	exec (prepped statement)
	Execute a prepared statement taking no parameters.

template<typename... TYPE>
auto	query (prepped statement, params const &parms={})
	Execute prepared statement, read full results, iterate rows of data.

template<typename TYPE >
TYPE	query_value (prepped statement, params const &parms={})
	Perform prepared statement returning exactly 1 value.

template<typename CALLABLE >
void	for_query (prepped statement, CALLABLE &&func, params const &parms={})
	Execute prepared statement, load result, perform `func` for each row.

result	exec (prepped statement, params const &parms)
	Execute a prepared statement with parameters.

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

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

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.

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

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

constexpr connection &	conn () const noexcept
	The connection in which this transaction lives.

void	set_variable (std::string_view var, std::string_view value)
	Set session variable using SQL "SET" command.

std::string	get_variable (std::string_view)
	Read session variable using SQL "SHOW" command.

std::string_view	name () const &noexcept
	Transaction name, if you passed one to the constructor; or empty string.

Additional Inherited Members
Protected Member Functions inherited from pqxx::transaction_focus
void	register_me ()

void	unregister_me () noexcept

void	reg_pending_error (std::string const &) noexcept

bool	registered () const noexcept

Protected Member Functions inherited from pqxx::dbtransaction
	dbtransaction (connection &cx)
	Begin transaction.

	dbtransaction (connection &cx, std::string_view tname)
	Begin transaction.

	dbtransaction (connection &cx, std::string_view tname, std::shared_ptr< std::string > rollback_cmd)
	Begin transaction.

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

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

	transaction_base (connection &cx)
	Create a transaction (to be called by implementation classes only).

void	register_transaction ()
	Register this transaction with the connection.

void	close () noexcept
	End transaction. To be called by implementing class' destructor.

virtual void	do_abort ()
	Transaction type-specific way of aborting a transaction.

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

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

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

Protected Attributes inherited from pqxx::transaction_focus
transaction_base *	m_trans

◆ pqxx::transaction_base

class pqxx::transaction_base

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

Abstract base class for all transaction types.

Inheritance diagram for pqxx::transaction_base:

Public Member Functions
	transaction_base (transaction_base const &)=delete

	transaction_base (transaction_base &&)=delete

transaction_base &	operator= (transaction_base const &)=delete

transaction_base &	operator= (transaction_base &&)=delete

void	commit ()
	Commit the transaction.

void	abort ()
	Abort the transaction.

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

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

std::string	unesc_raw (zview text) const
	Unescape binary data, e.g. from a `bytea` field.

bytes	unesc_bin (zview text)
	Unescape binary data, e.g. from a `bytea` field.

std::string	unesc_raw (char const *text) const
	Unescape binary data, e.g. from a `bytea` field.

bytes	unesc_bin (char const text[])
	Unescape binary data, e.g. from a `bytea` field.

template<typename T >
std::string	quote (T const &t) const
	Represent object as SQL string, including quoting & escaping.

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.

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

std::string	quote_name (std::string_view identifier) const
	Escape an SQL identifier for use in a query.

std::string	esc_like (std::string_view bin, char escape_char='\\') const
	Escape string for literal LIKE match.

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

Command execution
There are many functions for executing (or "performing") a command (or "query"). This is the most fundamental thing you can do in libpqxx, and it always starts at 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 throw are derived from std::exception. Most of the differences between the query execution functions are in how they return the query's results. The "query" functions run your query, wait for it to complete, and load all of the results into memory on the client side. You can then access rows of result data, converted to C++ types that you request. The "stream" functions execute your query in a completely different way. Called streaming queries, these don't support quite the full range of SQL queries, and they're a bit slower to start. But they are significantly faster for queries that return larger numbers of rows. They don't load the entire result set, so you can start processing data as soon as the first row of data comes in from the database. This can This can save you a lot of time. Processing itself may also be faster. And of course, it also means you don't need enough memory to hold the entire result set, just the row you're working on. The "exec" functions are a more low-level interface. Most of them return a pqxx::result object. This is an object that contains all information abouut the query's result: the data itself, but also the number of rows in the result, the column names, the number of rows that your query may have modified, and so on.
result	exec (std::string_view query, std::string_view desc)
	Execute a command.

result	exec (std::string_view query, params parms)

result	exec (std::string_view query)
	Execute a command.

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

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

result	exec0 (zview query)
	Execute command, which should return zero rows of data.

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

row	exec1 (zview query)
	Execute command returning a single row of data.

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

result	exec_n (result::size_type rows, zview query)
	Execute command, expect given number of rows.

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

template<typename TYPE >
TYPE	query_value (zview query)
	Perform query, expecting exactly 1 row with 1 field, and convert it.

template<typename... TYPE>
std::tuple< TYPE... >	query1 (zview query)
	Perform query returning exactly one row, and convert its fields.

template<typename... TYPE>
std::optional< std::tuple< TYPE... > >	query01 (zview query)
	Query at most one row of data, and if there is one, convert it.

template<typename... TYPE>
auto	stream (std::string_view query) &
	Execute a query, in streaming fashion; loop over the results row by row.

template<typename... TYPE>
auto	stream (std::string_view query, params parms) &
	Execute a query, in streaming fashion; loop over the results row by row.

template<typename CALLABLE >
auto	for_stream (std::string_view query, CALLABLE &&func)
	Perform a streaming query, and for each result row, call `func`.

template<typename CALLABLE >
auto	for_each (std::string_view query, CALLABLE &&func)

template<typename... TYPE>
auto	query (zview query)
	Execute query, read full results, then iterate rows of data.

template<typename... TYPE>
auto	query_n (result::size_type rows, zview query)
	Perform query, expect given number of rows, iterate results.

template<typename CALLABLE >
void	for_query (zview query, CALLABLE &&func)
	Execute a query, load the full result, and perform `func` for each row.

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 such as "," 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 (std::string_view query, Args &&...args)
	Execute an SQL statement with parameters.

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)

template<typename... Args>
result	exec_params_n (result::size_type rows, zview query, Args &&...args)

template<typename... TYPE>
auto	query (zview query, params const &parms)
	Execute parameterised query, read full results, iterate rows of data.

template<typename... TYPE>
auto	query_n (result::size_type rows, zview query, params const &parms)

template<typename TYPE >
TYPE	query_value (zview query, params const &parms)
	Perform query, expecting exactly 1 row with 1 field, and convert it.

template<typename... TYPE>
std::tuple< TYPE... >	query1 (zview query, params const &parms)
	Perform query returning exactly one row, and convert its fields.

template<typename... TYPE>
std::optional< std::tuple< TYPE... > >	query01 (zview query, params const &parms)
	Query at most one row of data, and if there is one, convert it.

template<typename CALLABLE >
void	for_query (zview query, CALLABLE &&func, params const &parms)
	Execute a query, load the full result, and perform `func` for each row.

void	notify (std::string_view channel, std::string_view payload={})
	Send a notification.

template<typename... Args>
result	exec_prepared (zview statement, Args &&...args)
	Execute a prepared statement, with optional arguments.

result	exec (prepped statement)
	Execute a prepared statement taking no parameters.

template<typename... TYPE>
auto	query (prepped statement, params const &parms={})
	Execute prepared statement, read full results, iterate rows of data.

template<typename TYPE >
TYPE	query_value (prepped statement, params const &parms={})
	Perform prepared statement returning exactly 1 value.

template<typename CALLABLE >
void	for_query (prepped statement, CALLABLE &&func, params const &parms={})
	Execute prepared statement, load result, perform `func` for each row.

result	exec (prepped statement, params const &parms)
	Execute a prepared statement with parameters.

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

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

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.

Error/warning output
class	pqxx::internal::gate::transaction_transaction_focus

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

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

constexpr connection &	conn () const noexcept
	The connection in which this transaction lives.

void	set_variable (std::string_view var, std::string_view value)
	Set session variable using SQL "SET" command.

std::string	get_variable (std::string_view)
	Read session variable using SQL "SHOW" command.

std::string_view	name () const &noexcept
	Transaction name, if you passed one to the constructor; or empty string.

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

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

	transaction_base (connection &cx)
	Create a transaction (to be called by implementation classes only).

void	register_transaction ()
	Register this transaction with the connection.

void	close () noexcept
	End transaction. To be called by implementing class' destructor.

virtual void	do_commit ()=0
	To be implemented by derived implementation class: commit transaction.

virtual void	do_abort ()
	Transaction type-specific way of aborting a transaction.

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

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

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

Constructor & Destructor Documentation

◆ transaction_base() [1/2]

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

inlineprotected

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() [2/2]

pqxx::transaction_base::transaction_base	(	connection &	cx,
		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.

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.

◆ commit()

void pqxx::transaction_base::commit ( )

Commit the transaction.

Make the effects of this transaction definite. If you destroy a transaction without invoking its commit() first, that will implicitly abort it. (For the nontransaction class though, "commit" and "abort" really don't do anything, hence its name.)

There is, however, a minute risk that you might lose your connection to the database at just the wrong moment here. In that case, libpqxx may be unable to determine whether the database was able to complete the transaction, or had to roll it back. In that scenario, commit() will throw an in_doubt_error. There is a different transaction class called robusttransaction which takes some special precautions to reduce this risk.

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

◆ esc_raw()

template<typename... ARGS>

auto pqxx::transaction_base::esc_raw ( ARGS &&... args ) const

inline

Escape binary data for use as SQL string literal in this transaction.

Raw, binary data is treated differently from regular strings. Binary strings are never interpreted as text, so they may safely include byte values or byte sequences that don't happen to represent valid characters in the character encoding being used.

The binary string does not stop at the first zero byte, as is the case with textual strings. Instead, it may contain zero bytes anywhere. If it happens to contain bytes that look like quote characters, or other things that can disrupt their use in SQL queries, they will be replaced with special escape sequences.

◆ exec() [1/3]

result pqxx::transaction_base::exec ( std::string_view query )

inline

Execute a command.

Parameters

query Query or command to execute.

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

◆ exec() [2/3]

pqxx::result pqxx::transaction_base::exec	(	std::string_view	query,
		std::string_view	desc
	)

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.

◆ exec() [3/3]

result pqxx::transaction_base::exec	(	std::stringstream const &	query,
		std::string_view	desc
	)

inline

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() [1/2]

result pqxx::transaction_base::exec0 ( zview query )

inline

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.

◆ exec0() [2/2]

result pqxx::transaction_base::exec0	(	zview	query,
		std::string_view	desc
	)

inline

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.

◆ exec1() [1/2]

row pqxx::transaction_base::exec1 ( zview query )

inline

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.

◆ exec1() [2/2]

row pqxx::transaction_base::exec1	(	zview	query,
		std::string_view	desc
	)

inline

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.

◆ exec_n() [1/2]

result pqxx::transaction_base::exec_n	(	result::size_type	rows,
		zview	query
	)

inline

Execute command, expect given number of rows.

Works like exec, but checks that the result has exactly the expected number of rows.

Exceptions

unexpected_rows If the query returned the wrong number of rows.

◆ exec_n() [2/2]

pqxx::result pqxx::transaction_base::exec_n	(	result::size_type	rows,
		zview	query,
		std::string_view	desc
	)

Execute command, expect given number of rows.

Works like exec, but checks that the result has exactly the expected number of rows.

Exceptions

unexpected_rows If the query returned the wrong number of rows.

◆ exec_params()

template<typename... Args>

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

inline

Execute an SQL statement with parameters.

This is like calling exec(), except it will substitute the first parameter after query (the first in args) for a $1 in the query, the next one for $2, etc.

◆ exec_params0()

template<typename... Args>

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

inline

Exceptions

unexpected_rows if the result contains rows.

◆ exec_params1()

template<typename... Args>

row pqxx::transaction_base::exec_params1	(	zview	query,
		Args &&...	args
	)

inline

Exceptions

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

◆ exec_params_n() [1/2]

template<typename... Args>

result pqxx::transaction_base::exec_params_n	(	result::size_type	rows,
		zview	query,
		Args &&...	args
	)

inline

Exceptions

unexpected_rows if the result contains the wrong number of rows.

◆ exec_params_n() [2/2]

template<typename... Args>

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

inline

Exceptions

unexpected_rows if the result contains the wrong number of rows.

◆ exec_prepared0()

template<typename... Args>

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

inline

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
	)

inline

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

Exceptions

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

◆ exec_prepared_n()

template<typename... Args>

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

inline

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.

◆ for_query() [1/3]

template<typename CALLABLE >

void pqxx::transaction_base::for_query	(	prepped	statement,
		CALLABLE &&	func,
		params const &	parms = `{}`
	)

inline

Execute prepared statement, load result, perform func for each row.

This is just like for_query(zview), but using a prepared statement.

◆ for_query() [2/3]

template<typename CALLABLE >

void pqxx::transaction_base::for_query	(	zview	query,
		CALLABLE &&	func
	)

inline

Execute a query, load the full result, and perform func for each row.

Converts each row to data types matching func's parameter types. The number of columns in the result set must match the number of parameters.

This is a lot like for_stream(). The differences are:

It can execute some unusual queries that for_stream() can't.
The exec functions are faster for small results, but slower for large results.

◆ for_query() [3/3]

template<typename CALLABLE >

void pqxx::transaction_base::for_query	(	zview	query,
		CALLABLE &&	func,
		params const &	parms
	)

inline

Execute a query, load the full result, and perform func for each row.

The query may use parameters. So for example, the query may contain $1 to denote the first parameter value in parms, and so on.

Converts each row to data types matching func's parameter types. The number of columns in the result set must match the number of parameters.

This is a lot like for_stream(). The differences are:

It can execute some unusual queries that for_stream() can't.
The exec functions are faster for small results, but slower for large results.

◆ for_stream()

template<typename CALLABLE >

auto pqxx::transaction_base::for_stream	(	std::string_view	query,
		CALLABLE &&	func
	)

inline

Perform a streaming query, and for each result row, call func.

Here, func can be a function, a std::function, a lambda, or an object that supports the function call operator. Of course func must have an unambiguous signature; it can't be overloaded or generic.

The for_stream function executes query in a stream similar to stream. Every time a row of data comes in from the server, it converts the row's fields to the types of func's respective parameters, and calls func with those values.

This will not work for all queries, but straightforward SELECT and UPDATE ... RETURNING queries should work. Consult the documentation for pqxx::internal::stream_query and PostgreSQL's underlying COPY command for the full details.

Streaming a query like this is likely to be slower than the exec() functions for small result sets, but faster for larger result sets. So if performance matters, you'll want to use for_stream if you query large amounts of data, but not if you do lots of queries with small outputs.

However, the transaction and the connection are in a special state while the iteration is ongoing. If func throws an exception, or the iteration fails in some way, the only way out is to destroy the transaction and the connection.

Each of the parameter types must have a conversion from PostgreSQL's text format defined. To define conversions for additional types, see Supporting additional data types.

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

◆ notify()

void pqxx::transaction_base::notify	(	std::string_view	channel,
		std::string_view	payload = `{}`
	)

Send a notification.

Convenience shorthand for executing a "NOTIFY" command. Most of the logic for handling incoming notifications is in pqxx::connection (particularly pqxx::connection::listen), but outgoing notifications happen here.

Unless this transaction is a nontransaction, the actual notification only goes out once the outer transaction is committed.

Parameters

channel	Name of the "channel" on which clients will need to be listening in order to receive this notification.
payload	Optional argument string which any listeners will also receive. If you leave this out, they will receive an empty string as the payload.

◆ query() [1/3]

template<typename... TYPE>

auto pqxx::transaction_base::query	(	prepped	statement,
		params const &	parms = `{}`
	)

inline

Execute prepared statement, read full results, iterate rows of data.

Like query(zview), but using a prepared statement.

Returns: Something you can iterate using "range `for`" syntax. The actual type details may change.

◆ query() [2/3]

template<typename... TYPE>

auto pqxx::transaction_base::query ( zview query )

inline

Execute query, read full results, then iterate rows of data.

Converts each row of the result to a std::tuple of the types you pass as template arguments. (The number of template arguments must match the number of columns in the query's result.)

Example:

for (
    auto [name, salary] :
        tx.query<std::string_view, int>(
            "SELECT name, salary FROM employee"
        )
)
    std::cout << name << " earns " << salary << ".\n";

You can't normally convert a field value to std::string_view, but this is one of the places where you can. The underlying string to which the string_view points exists only for the duration of the one iteration. After that, the buffer that holds the actual string may have disappeared, or it may contain a new string value.

If you expect a lot of rows from your query, it's probably faster to use transaction_base::stream() instead. Or if you need to access metadata of the result, such as the number of rows in the result, or the number of rows that your query updates, then you'll need to use transaction_base::exec() instead.

Returns: Something you can iterate using "range `for`" syntax. The actual type details may change.

◆ query() [3/3]

template<typename... TYPE>

auto pqxx::transaction_base::query	(	zview	query,
		params const &	parms
	)

inline

Execute parameterised query, read full results, iterate rows of data.

Like query, but the query can contain parameters.

Converts each row of the result to a std::tuple of the types you pass as template arguments. (The number of template arguments must match the number of columns in the query's result.)

Example:

for (
    auto [name, salary] :
        tx.query<std::string_view, int>(
            "SELECT name, salary FROM employee"
        )
)
    std::cout << name << " earns " << salary << ".\n";

You can't normally convert a field value to std::string_view, but this is one of the places where you can. The underlying string to which the string_view points exists only for the duration of the one iteration. After that, the buffer that holds the actual string may have disappeared, or it may contain a new string value.

If you expect a lot of rows from your query, it's probably faster to use transaction_base::stream() instead. Or if you need to access metadata of the result, such as the number of rows in the result, or the number of rows that your query updates, then you'll need to use transaction_base::exec() instead.

Returns: Something you can iterate using "range `for`" syntax. The actual type details may change.

◆ query01() [1/2]

template<typename... TYPE>

std::optional< std::tuple< TYPE... > > pqxx::transaction_base::query01 ( zview query )

inline

Query at most one row of data, and if there is one, convert it.

If the query produced a row of data, this converts it to a tuple of the C++ types you specify. Otherwise, this returns no tuple.

Exceptions

unexpected_rows	If the query returned more than 1 row.
usage_error	If the number of columns in the result does not match the number of fields in the tuple.

◆ query01() [2/2]

template<typename... TYPE>

std::optional< std::tuple< TYPE... > > pqxx::transaction_base::query01	(	zview	query,
		params const &	parms
	)

inline

Query at most one row of data, and if there is one, convert it.

If the query produced a row of data, this converts it to a tuple of the C++ types you specify. Otherwise, this returns no tuple.

Exceptions

unexpected_rows	If the query returned more than 1 row.
usage_error	If the number of columns in the result does not match the number of fields in the tuple.

◆ query1() [1/2]

template<typename... TYPE>

std::tuple< TYPE... > pqxx::transaction_base::query1 ( zview query )

inline

Perform query returning exactly one row, and convert its fields.

This is a convenient way of querying one row's worth of data, and converting its fields to a tuple of the C++-side types you specify.

Exceptions

unexpected_rows	If the query did not return exactly 1 row.
usage_error	If the number of columns in the result does not match the number of fields in the tuple.

◆ query1() [2/2]

template<typename... TYPE>

std::tuple< TYPE... > pqxx::transaction_base::query1	(	zview	query,
		params const &	parms
	)

inline

Perform query returning exactly one row, and convert its fields.

This is a convenient way of querying one row's worth of data, and converting its fields to a tuple of the C++-side types you specify.

Exceptions

unexpected_rows	If the query did not return exactly 1 row.
usage_error	If the number of columns in the result does not match the number of fields in the tuple.

◆ query_n()

template<typename... TYPE>

auto pqxx::transaction_base::query_n	(	result::size_type	rows,
		zview	query,
		params const &	parms
	)

inline

Perform query parameterised, expect given number of rows, iterate results. Works like query, but checks that the result has exactly the expected number of rows.

Exceptions

unexpected_rows If the query returned the wrong number of rows.

Returns: Something you can iterate using "range `for`" syntax. The actual type details may change.

◆ query_value() [1/4]

template<typename TYPE >

TYPE pqxx::transaction_base::query_value	(	prepped	statement,
		params const &	parms = `{}`
	)

inline

Perform prepared statement returning exactly 1 value.

This is just like query_value(zview), but using a prepared statement.

◆ query_value() [2/4]

template<typename TYPE >

TYPE pqxx::transaction_base::query_value ( zview query )

inline

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.

Exceptions

unexpected_rows	If the query did not return exactly 1 row.
usage_error	If the row did not contain exactly 1 field.

◆ query_value() [3/4]

template<typename TYPE >

TYPE pqxx::transaction_base::query_value	(	zview	query,
		params const &	parms
	)

inline

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.

Exceptions

unexpected_rows	If the query did not return exactly 1 row.
usage_error	If the row did not contain exactly 1 field.

◆ query_value() [4/4]

template<typename TYPE >

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

inline

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.

◆ quote()

template<typename T >

std::string pqxx::transaction_base::quote ( T const & t ) const

inline

Represent object as SQL string, including quoting & escaping.

Nulls are recognized and represented as SQL nulls.

◆ set_variable()

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

Set session variable using SQL "SET" command.

Deprecated:: To set a transaction-local variable, execute an SQL SET command. To set a session variable, use the connection's set_session_var function.

Warning: When setting a string value, you must make sure that the string is "safe." If you call quote() on the string, it will return a safely escaped and quoted version for use as an SQL literal.; This function 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. This can be any SQL expression.

◆ stream() [1/2]

template<typename... TYPE>

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

inline

Execute a query, in streaming fashion; 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. Unlike with the "exec" functions, processing can start before all the data from the server is in.

Streaming is also documented in Streams.

The column types must all be types that have conversions from PostgreSQL's text format defined. Many built-in types such as int or std::string have pre-defined conversions; if you want to define your own conversions for additional types, see Supporting additional data types.

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 you're translating it does not have a null value, wrap the type in a std::optional<> (or if you prefer, a std::shared_ptr<> or a std::unique_ptr). These templates do support null values, and libpqxx will know how to convert to them.

The stream lives entirely within the lifetime of the transaction. Make sure you complete the stream before you destroy the transaction. Until the stream has finished, the transaction and the connection are in a special state where they cannot be used for anything else.

Warning: If the stream fails, you will have to destroy the transaction and the connection. If this is a problem, use the "exec" functions instead.

Streaming your query is likely to be faster than the exec() methods for larger results (but slower for small results), and start useful processing sooner. Also, stream() scales better in terms of memory usage: it only needs to keep the current row in memory. The "exec" functions read the entire result into memory at once.

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

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

◆ stream() [2/2]

template<typename... TYPE>

auto pqxx::transaction_base::stream	(	std::string_view	query,
		params	parms
	)		&

inline

Execute a query, in streaming fashion; loop over the results row by row.

Like stream(std::string_view), but with parameters.

◆ unesc_bin() [1/2]

bytes pqxx::transaction_base::unesc_bin ( char const text[] )

inline

Unescape binary data, e.g. from a bytea field.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

◆ unesc_bin() [2/2]

bytes pqxx::transaction_base::unesc_bin ( zview text )

inline

Unescape binary data, e.g. from a bytea field.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

◆ unesc_raw() [1/2]

std::string pqxx::transaction_base::unesc_raw ( char const * text ) const

inline

Unescape binary data, e.g. from a bytea field.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

◆ unesc_raw() [2/2]

std::string pqxx::transaction_base::unesc_raw ( zview text ) const

inline

Unescape binary data, e.g. from a bytea field.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

Classes

Detailed Description

Class Documentation

◆ pqxx::dbtransaction

Protected Member Functions

Additional Inherited Members

◆ pqxx::nontransaction

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ nontransaction()

◆ pqxx::subtransaction

Public Member Functions

Additional Inherited Members

◆ pqxx::transaction_base

Public Member Functions

Error/warning output

Constructor & Destructor Documentation

◆ transaction_base() [1/2]

◆ transaction_base() [2/2]

Member Function Documentation

◆ abort()

◆ commit()

◆ do_abort()

◆ esc_raw()

◆ exec() [1/3]

◆ exec() [2/3]

◆ exec() [3/3]

◆ exec0() [1/2]

◆ exec0() [2/2]

◆ exec1() [1/2]

◆ exec1() [2/2]

◆ exec_n() [1/2]

◆ exec_n() [2/2]

◆ exec_params()

◆ exec_params0()

◆ exec_params1()

◆ exec_params_n() [1/2]

◆ exec_params_n() [2/2]

◆ exec_prepared0()

◆ exec_prepared1()

◆ exec_prepared_n()

◆ for_query() [1/3]

◆ for_query() [2/3]

◆ for_query() [3/3]

◆ for_stream()

◆ get_variable()

◆ notify()

◆ query() [1/3]

◆ query() [2/3]

◆ query() [3/3]

◆ query01() [1/2]

◆ query01() [2/2]

◆ query1() [1/2]

◆ query1() [2/2]

◆ query_n()

◆ query_value() [1/4]

◆ query_value() [2/4]

◆ query_value() [3/4]

◆ query_value() [4/4]

◆ quote()

◆ set_variable()

◆ stream() [1/2]

◆ stream() [2/2]

◆ unesc_bin() [1/2]

◆ unesc_bin() [2/2]

◆ unesc_raw() [1/2]

◆ unesc_raw() [2/2]