libpqxx
7.3.0
|
Interface definition (and common code) for "transaction" classes. More...
#include <transaction_base.hxx>
Public Member Functions | |
transaction_base ()=delete | |
transaction_base (transaction_base const &)=delete | |
transaction_base (transaction_base &&)=delete | |
transaction_base & | operator= (transaction_base const &)=delete |
transaction_base & | operator= (transaction_base &&)=delete |
virtual | ~transaction_base ()=0 |
void | commit () |
Commit the transaction. More... | |
void | abort () |
Abort the transaction. More... | |
std::string | esc (char const text[]) const |
Escape string for use as SQL string literal in this transaction. More... | |
std::string | esc (char const text[], std::size_t maxlen) const |
Escape string for use as SQL string literal in this transaction. More... | |
std::string | esc (std::string_view text) const |
Escape string for use as SQL string literal in this transaction. More... | |
std::string | esc_raw (unsigned char const data[], std::size_t len) const |
Escape binary data for use as SQL string literal in this transaction. More... | |
std::string | esc_raw (zview) const |
Escape binary data for use as SQL string literal in this transaction. More... | |
std::string | unesc_raw (zview text) const |
Unescape binary data, e.g. from a table field or notification payload. More... | |
std::string | unesc_raw (char const *text) const |
Unescape binary data, e.g. from a table field or notification payload. More... | |
template<typename T > | |
std::string | quote (T const &t) const |
Represent object as SQL string, including quoting & escaping. More... | |
std::string | quote_raw (unsigned char const bin[], std::size_t len) const |
Binary-escape and quote a binary string for use as an SQL constant. More... | |
std::string | quote_raw (zview bin) const |
std::string | quote_name (std::string_view identifier) const |
Escape an SQL identifier for use in a query. More... | |
std::string | esc_like (std::string_view bin, char escape_char='\\') const |
Escape string for literal LIKE match. More... | |
result | exec (std::string_view query, std::string_view desc=std::string_view{}) |
Execute query. More... | |
result | exec (std::stringstream const &query, std::string_view desc=std::string_view{}) |
result | exec0 (zview query, std::string_view desc=std::string_view{}) |
Execute query, which should zero rows of data. More... | |
row | exec1 (zview query, std::string_view desc=std::string_view{}) |
Execute query returning a single row of data. More... | |
result | exec_n (result::size_type rows, zview query, std::string_view desc=std::string_view{}) |
Execute query, expect given number of rows. More... | |
template<typename TYPE > | |
TYPE | query_value (zview query, std::string_view desc=std::string_view{}) |
Execute query, expecting exactly 1 row with 1 field. More... | |
template<typename... TYPE> | |
auto | stream (std::string_view query) |
Execute a query, and loop over the results row by row. More... | |
template<> | |
zview | query_value (zview query, std::string_view desc)=delete |
Forbidden specialisation: underlying buffer immediately goes out of scope. More... | |
Parameterized statements | |
You'll often need parameters in the queries you execute: "select the car with this licence plate." If the parameter is a string, you need to quote it and escape any special characters inside it, or it may become a target for an SQL injection attack. If it's an integer (for example), you need to convert it to a string, but in the database's format, without locale-specific niceties like "," separators between the thousands. Parameterised statements are an easier and safer way to do this. They're like prepared statements, but for a single use. You don't need to name them, and you don't need to prepare them first. Your query will include placeholders like 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
| |
template<typename... Args> | |
result | exec_params (zview query, Args &&...args) |
Execute an SQL statement with parameters. More... | |
template<typename... Args> | |
row | exec_params1 (zview query, Args &&...args) |
template<typename... Args> | |
result | exec_params0 (zview query, Args &&...args) |
template<typename... Args> | |
result | exec_params_n (std::size_t rows, zview query, Args &&...args) |
Prepared statements | |
These are very similar to parameterised statements. The difference is that you prepare them in advance, giving them identifying names. You can then call them by these names, passing in the argument values appropriate for that call. You prepare a statement on the connection, using 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.
| |
template<typename... Args> | |
result | exec_prepared (zview statement, Args &&...args) |
Execute a prepared statement, with optional arguments. More... | |
template<typename... Args> | |
row | exec_prepared1 (zview statement, Args &&...args) |
Execute a prepared statement, and expect a single-row result. More... | |
template<typename... Args> | |
result | exec_prepared0 (zview statement, Args &&...args) |
Execute a prepared statement, and expect a result with zero rows. More... | |
template<typename... Args> | |
result | exec_prepared_n (result::size_type rows, zview statement, Args &&...args) |
Execute a prepared statement, expect a result with given number of rows. More... | |
Error/warning output | |
class | pqxx::internal::gate::transaction_transactionfocus |
void | process_notice (char const msg[]) const |
Have connection process a warning message. More... | |
void | process_notice (zview msg) const |
Have connection process a warning message. More... | |
connection & | conn () const |
The connection in which this transaction lives. More... | |
void | set_variable (std::string_view var, std::string_view value) |
Set session variable using SQL "SET" command. More... | |
std::string | get_variable (std::string_view) |
Read session variable using SQL "SHOW" command. More... | |
std::string_view | name () const noexcept |
Transaction name, if you passed one to the constructor; or empty string. More... | |
transaction_base (connection &c, std::string_view tname, std::shared_ptr< std::string > rollback_cmd) | |
Create a transaction (to be called by implementation classes only). More... | |
transaction_base (connection &c, std::string_view tname) | |
Create a transaction (to be called by implementation classes only). More... | |
transaction_base (connection &c) | |
Create a transaction (to be called by implementation classes only). More... | |
void | register_transaction () |
Register this transaction with the connection. More... | |
void | close () noexcept |
End transaction. To be called by implementing class' destructor. More... | |
virtual void | do_commit ()=0 |
To be implemented by derived implementation class: commit transaction. More... | |
virtual void | do_abort () |
Transaction type-specific way of aborting a transaction. More... | |
void | set_rollback_cmd (std::shared_ptr< std::string > cmd) |
Set the rollback command. More... | |
result | direct_exec (std::string_view) |
Execute query on connection directly. More... | |
result | direct_exec (std::shared_ptr< std::string >) |
Interface definition (and common code) for "transaction" classes.
Abstract base class for all transaction types.
|
delete |
|
delete |
|
delete |
|
pure virtual |
|
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.
|
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.
|
explicitprotected |
Create a transaction (to be called by implementation classes only).
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.
|
protectednoexcept |
End transaction. To be called by implementing class' destructor.
Referenced by pqxx::robusttransaction< ISOLATION >::~robusttransaction().
void pqxx::transaction_base::commit | ( | ) |
Commit the transaction.
Unless this function is called explicitly, the transaction will not be committed (actually the nontransaction implementation breaks this rule, hence the name).
Once this function returns, the whole transaction will typically be irrevocably completed in the database. There is also, however, a minute risk that the connection to the database may be lost at just the wrong moment. In that case, libpqxx may be unable to determine whether the transaction was completed or aborted and an in_doubt_error will be thrown to make this fact known to the caller. The robusttransaction implementation takes some special precautions to reduce this risk.
connection& pqxx::transaction_base::conn | ( | ) | const |
The connection in which this transaction lives.
Referenced by pqxx::largeobject::largeobject(), pqxx::largeobject::remove(), pqxx::largeobjectaccess::remove(), pqxx::subtransaction::subtransaction(), and pqxx::largeobject::to_file().
|
protected |
|
protected |
Execute query on connection directly.
Referenced by pqxx::internal::basic_transaction::basic_transaction().
|
protectedvirtual |
Transaction type-specific way of aborting a transaction.
|
protectedpure virtual |
To be implemented by derived implementation class: commit transaction.
std::string pqxx::transaction_base::esc | ( | char const | text[], |
std::size_t | maxlen | ||
) | const |
Escape string for use as SQL string literal in this transaction.
std::string pqxx::transaction_base::esc | ( | std::string_view | text | ) | const |
Escape string for use as SQL string literal in this transaction.
std::string pqxx::transaction_base::esc_like | ( | std::string_view | bin, |
char | escape_char = '\\' |
||
) | const |
Escape string for literal LIKE match.
std::string pqxx::transaction_base::esc_raw | ( | unsigned char const | data[], |
std::size_t | len | ||
) | 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, they 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.
std::string pqxx::transaction_base::esc_raw | ( | zview | bin | ) | const |
Escape binary data for use as SQL string literal in this transaction.
References pqxx::zview::c_str().
pqxx::result pqxx::transaction_base::exec | ( | std::string_view | query, |
std::string_view | desc = std::string_view{} |
||
) |
Execute query.
Perform a query in this transaction.
This is one of the most important functions in libpqxx.
Most libpqxx exceptions can be thrown from here, including sql_error, broken_connection, and many sql_error subtypes such as feature_not_supported or insufficient_privilege. But any exception thrown by the C++ standard library may also occur here. All exceptions will be derived from std::exception.
query | Query or command to execute. |
desc | Optional identifier for query, to help pinpoint SQL errors. |
result pqxx::transaction_base::exec | ( | std::stringstream const & | query, |
std::string_view | desc = std::string_view{} |
||
) |
Execute query, which should zero rows of data.
Works like exec, but fails if the result contains data. It still returns a result, however, which may contain useful metadata.
unexpected_rows | If the query returned the wrong number of rows. |
Execute query returning a single row of data.
Works like exec, but requires the result to contain exactly one row. The row can be addressed directly, without the need to find the first row in a result set.
unexpected_rows | If the query returned the wrong number of rows. |
pqxx::result pqxx::transaction_base::exec_n | ( | result::size_type | rows, |
zview | query, | ||
std::string_view | desc = std::string_view{} |
||
) |
Execute query, expect given number of rows.
Works like exec, but checks that the number of rows is exactly what's expected.
unexpected_rows | If the query returned the wrong number of rows. |
result pqxx::transaction_base::exec_params | ( | zview | query, |
Args &&... | args | ||
) |
Execute an SQL statement with parameters.
result pqxx::transaction_base::exec_params0 | ( | zview | query, |
Args &&... | args | ||
) |
unexpected_rows | if the result contains rows. |
row pqxx::transaction_base::exec_params1 | ( | zview | query, |
Args &&... | args | ||
) |
unexpected_rows | if the result does not consist of exactly one row. |
References pqxx::row::front().
result pqxx::transaction_base::exec_params_n | ( | std::size_t | rows, |
zview | query, | ||
Args &&... | args | ||
) |
unexpected_rows | if the result contains the wrong number of rows. |
result pqxx::transaction_base::exec_prepared | ( | zview | statement, |
Args &&... | args | ||
) |
Execute a prepared statement, with optional arguments.
result pqxx::transaction_base::exec_prepared0 | ( | zview | statement, |
Args &&... | args | ||
) |
Execute a prepared statement, and expect a result with zero rows.
pqxx::unexpected_rows | if the result contained rows. |
row pqxx::transaction_base::exec_prepared1 | ( | zview | statement, |
Args &&... | args | ||
) |
Execute a prepared statement, and expect a single-row result.
pqxx::unexpected_rows | if the result was not exactly 1 row. |
References pqxx::row::front().
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.
pqxx::unexpected_rows | if the result did not contain exactly the given number of rows. |
std::string pqxx::transaction_base::get_variable | ( | std::string_view | var | ) |
Read session variable using SQL "SHOW" command.
|
noexcept |
Transaction name, if you passed one to the constructor; or empty string.
|
delete |
|
delete |
void pqxx::transaction_base::process_notice | ( | char const | msg[] | ) | const |
Have connection process a warning message.
void pqxx::transaction_base::process_notice | ( | zview | msg | ) | const |
Have connection process a warning message.
Forbidden specialisation: underlying buffer immediately goes out of scope.
TYPE pqxx::transaction_base::query_value | ( | zview | query, |
std::string_view | desc = std::string_view{} |
||
) |
Execute query, expecting exactly 1 row with 1 field.
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.
std::string pqxx::transaction_base::quote_name | ( | std::string_view | identifier | ) | const |
Escape an SQL identifier for use in a query.
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.
std::string pqxx::transaction_base::quote_raw | ( | zview | bin | ) | const |
References pqxx::zview::c_str().
|
protected |
Register this transaction with the connection.
Referenced by pqxx::internal::basic_transaction::basic_transaction().
|
protected |
Set the rollback command.
void pqxx::transaction_base::set_variable | ( | std::string_view | var, |
std::string_view | value | ||
) |
Set session variable using SQL "SET" command.
The new value is typically forgotten if the transaction aborts. Not for nontransaction though: in that case the set value will be kept regardless.
var | The variable to set. |
value | The new value to store in the variable. |
auto pqxx::transaction_base::stream | ( | std::string_view | query | ) |
Execute a query, and loop over the results row by row.
Converts the rows to std::tuple
, of the column types you specify.
Use this with a range-based "for" loop. It executes the query, and directly maps the resulting rows onto a std::tuple
of the types you specify. It starts before all the data from the server is in, so if your network connection to the server breaks while you're iterating, you'll get an exception partway through.
The tuple may contain std::string_view
fields, but the strings to which they point will only remain valid until you extract the next row. After that, the memory holding the string may be overwritten or deallocated.
If any of the columns can be null, and the C++ type to which it translates does not have a null value, wrap the type in std::optional
(or if you prefer, std::shared_ptr
or std::unique_ptr
). These templates do recognise null values, and libpqxx will know how to convert to them.
The connection is in a special state until the iteration finishes. So if it does not finish due to a break
or a return
or an exception, then the entire connection becomes effectively unusable.
Querying in this way is faster than the exec()
methods for larger results (but probably slower for small ones). Also, you can start processing rows before the full result is in. Also, stream()
scales better in terms of memory usage. Where exec()
reads the entire result into memory at once, stream()
will read and process one row at at a time.
Your query executes as part of a COPY command, not as a stand-alone query, so there are limitations to what you can do in the query. It can be either a SELECT or VALUES query; or an INSERT, UPDATE, or DELETE with a RETURNING clause. See the documentation for PostgreSQL's COPY command for the details:
https://www.postgresql.org/docs/current/sql-copy.html
Iterating in this way does require each of the field types you pass to be default-constructible, copy-constructible, and assignable. These requirements may be loosened once libpqxx moves on to C++20.
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.
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.
|
friend |