pqxx::transaction_base Class Referenceabstract
Transaction classes

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.
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 table field or notification payload.
std::basic_string< std::byte > | unesc_bin (zview text)
| Unescape binary data, e.g. from a table field or notification payload.
std::string | unesc_raw (char const *text) const
| Unescape binary data, e.g. from a table field or notification payload.
std::basic_string< std::byte > | unesc_bin (char const text[])
| Unescape binary data, e.g. from a table field or notification payload.
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 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.

Some of these functions also give you the option to specify how many rows of data you expect to get: `exec0()` reports a failure if the query returns any rows of data at all, `exec1()` expects a single row of data (and so returns a pqxx::row rather than a pqxx::result), `exec_n()` lets you specify the number of rows you expect, and so on.

result | exec (std::string_view query, std::string_view desc)
| Execute a command.
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, and 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 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.
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.
  Passing the wrong number of parameters to a prepared or parameterised statement will break the connection. The usual exception that occurs in this situation is pqxx::protocol_violation. It's a subclass of pqxx::broken_connection, but where `broken_connection` usually indicates a networking problem, `protocol_violation` indicates that the communication with the server has deviated from protocol. Once something like that happens, communication is broken and there is nothing for it but to discard the connection. A networking problem is usually worth retrying, but a protocol violation is not. The same violation will probably just happen again.

template<typename... Args>
result | exec_prepared (zview statement, Args &&...args)
| Execute a prepared statement, with optional arguments.
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 &c, std::string_view tname, std::shared_ptr< std::string > rollback_cmd)
| Create a transaction (to be called by implementation classes only).
| transaction_base (connection &c, std::string_view tname)
| Create a transaction (to be called by implementation classes only).
| transaction_base (connection &c)
| 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)

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

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

explicit protected

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.

## close()

void pqxx::transaction_base::close | ( |  | ) |

protected noexcept

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

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

## conn()

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

constexpr noexcept

The connection in which this transaction lives.

Referenced by pqxx::blob::create(), pqxx::blob::from_buf(), pqxx::largeobject::largeobject(), pqxx::largeobject::largeobject(), pqxx::largeobject::raw_connection(), pqxx::blob::remove(), pqxx::stream_from::table(), and pqxx::largeobject::to_file().

## direct_exec() [1/2]

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

protected

## direct_exec() [2/2]

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

protected

Execute query on connection directly.

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

## do_abort()

void pqxx::transaction_base::do_abort | ( |  | ) |

protected virtual

Transaction type-specific way of aborting a transaction.

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

## do_commit()

virtual void pqxx::transaction_base::do_commit | ( |  | ) |

protected pure virtual

To be implemented by derived implementation class: commit transaction.

## esc_like()

std::string pqxx::transaction_base::esc_like | ( | std::string_view | bin,
|  | char | escape_char = `'\\'`
| ) |  | const

Escape string for literal LIKE match.

## esc_raw()

template<typename... ARGS>

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

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

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

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

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

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(), and pqxx::stream_from::stream_from().

## exec1() [1/2]

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

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

## exec1() [2/2]

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

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

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

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 | ( | zview | query,
|  | Args &&... | args
| ) |  |

Execute an SQL statement with parameters.

References pqxx::params::make_c_params().

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

## for_each()

template<typename CALLABLE >

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

## for_query()

template<typename CALLABLE >

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

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:

1. It can execute some unusual queries that for_stream() can't.
2. 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
| ) |  |

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.

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

## name()

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

noexcept

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

## operator=() [1/2]

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

delete

## operator=() [2/2]

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

delete

## process_notice() [1/2]

void pqxx::transaction_base::process_notice | ( | char const | msg[] | ) | const

Have connection process a warning message.

## process_notice() [2/2]

void pqxx::transaction_base::process_notice | ( | zview | msg | ) | const

Have connection process a warning message.

## query()

template<typename... TYPE>

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

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";
pqxx::transaction_base::query
auto query(zview query)
Execute query, read full results, then iterate rows of data.
Definition transaction_base.hxx:587
pqxx::transaction_base::name
std::string_view name() const &noexcept
Transaction name, if you passed one to the constructor; or empty string.
Definition transaction_base.hxx:811

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

template<typename... TYPE>

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

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

template<typename... TYPE>

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

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

Perform query, 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/3]

template<typename TYPE >

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

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

template<typename TYPE >

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

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

template<>

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

delete

Forbidden specialisation: underlying buffer immediately goes out of scope.

## quote() [1/2]

std::string pqxx::transaction_base::quote | ( | binarystring const & | t | ) | const

References pqxx::binarystring::bytes_view().

## quote() [2/2]

template<typename T >

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

Represent object as SQL string, including quoting & escaping.

Nulls are recognized and represented as SQL nulls.

## quote_name()

std::string pqxx::transaction_base::quote_name | ( | std::string_view | identifier | ) | const

Escape an SQL identifier for use in a query.

Referenced by pqxx::stream_from::stream_from(), and pqxx::stream_to::stream_to().

## quote_raw() [1/2]

std::string pqxx::transaction_base::quote_raw | ( | unsigned char const | bin[],
|  | std::size_t | len
| ) |  | const

Binary-escape and quote a binary string for use as an SQL constant.

References pqxx::binary_cast().

## quote_raw() [2/2]

std::string PQXX_COLD pqxx::transaction_base::quote_raw | ( | zview | bin | ) | const

Binary-escape and quote a binary string for use as an SQL constant.

References pqxx::binary_cast().

## register_transaction()

void pqxx::transaction_base::register_transaction | ( |  | ) |

protected

Register this transaction with the connection.

Referenced by pqxx::internal::basic_transaction::basic_transaction(), pqxx::internal::basic_transaction::basic_transaction(), and 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.

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

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

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.

## unesc_bin() [1/2]

std::basic_string< std::byte > pqxx::transaction_base::unesc_bin | ( | char const | text[] | ) |

Unescape binary data, e.g. from a table field or notification payload.

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

References pqxx::text.

## unesc_bin() [2/2]

std::basic_string< std::byte > pqxx::transaction_base::unesc_bin | ( | zview | text | ) |

Unescape binary data, e.g. from a table field or notification payload.

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

References pqxx::text.

## unesc_raw() [1/2]

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

Unescape binary data, e.g. from a table field or notification payload.

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

References pqxx::text.

## unesc_raw() [2/2]

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

Unescape binary data, e.g. from a table field or notification payload.

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

References pqxx::text.

## Friends And Related Symbol 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