libpqxx
7.0.2
|
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 & | operator= (transaction_base const &)=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[], size_t maxlen) const |
Escape string for use as SQL string literal in this transaction. More... | |
std::string | esc (std::string const &text) const |
Escape string for use as SQL string literal in this transaction. More... | |
std::string | esc_raw (unsigned char const data[], size_t len) const |
Escape binary data for use as SQL string literal in this transaction. More... | |
std::string | esc_raw (std::string const &) const |
Escape binary data for use as SQL string literal in this transaction. More... | |
std::string | unesc_raw (std::string const &text) const |
Unescape binary data, e.g. from a table field or notification payload. More... | |
std::string | unesc_raw (char const *text) const |
Unescape binary data, e.g. from a table field or notification payload. More... | |
template<typename T > | |
std::string | quote (T const &t) const |
Represent object as SQL string, including quoting & escaping. More... | |
std::string | quote_raw (unsigned char const bin[], size_t len) const |
Binary-escape and quote a binarystring for use as an SQL constant. More... | |
std::string | quote_raw (std::string const &bin) const |
std::string | quote_name (std::string_view identifier) const |
Escape an SQL identifier for use in a query. More... | |
std::string | esc_like (std::string const &bin, char escape_char='\\') const |
Escape string for literal LIKE match. More... | |
result | exec (std::string_view query, std::string const &desc=std::string{}) |
Execute query. More... | |
result | exec (std::stringstream const &query, std::string const &desc=std::string{}) |
result | exec0 (std::string const &query, std::string const &desc=std::string{}) |
Execute query, which should zero rows of data. More... | |
row | exec1 (std::string const &query, std::string const &desc=std::string{}) |
Execute query returning a single row of data. More... | |
result | exec_n (result::size_type rows, std::string const &query, std::string const &desc=std::string{}) |
Execute query, expect given number of rows. More... | |
template<typename TYPE > | |
TYPE | query_value (std::string const &query, std::string const &desc=std::string{}) |
Execute query, expecting exactly 1 row with 1 field. More... | |
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 (std::string const &query, Args &&... args) |
Execute an SQL statement with parameters. More... | |
template<typename... Args> | |
row | exec_params1 (std::string const &query, Args &&... args) |
template<typename... Args> | |
result | exec_params0 (std::string const &query, Args &&... args) |
template<typename... Args> | |
result | exec_params_n (size_t rows, std::string const &query, Args &&... args) |
Prepared statements | |
These are very similar to parameterised statements. The difference is that you prepare them in advance, giving them identifying names. You can then call them by these names, passing in the argument values appropriate for that call. You prepare a statement on the connection, using 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 (std::string const &statement, Args &&... args) |
Execute a prepared statement, with optional arguments. More... | |
template<typename... Args> | |
result | exec_prepared (zview statement, Args &&... args) |
template<typename... Args> | |
row | exec_prepared1 (std::string const &statement, Args &&... args) |
Execute a prepared statement, and expect a single-row result. More... | |
template<typename... Args> | |
row | exec_prepared1 (zview statement, Args &&... args) |
template<typename... Args> | |
result | exec_prepared0 (std::string const &statement, Args &&... args) |
Execute a prepared statement, and expect a result with zero rows. More... | |
template<typename... Args> | |
result | exec_prepared0 (zview statement, Args &&... args) |
template<typename... Args> | |
result | exec_prepared_n (result::size_type rows, std::string const &statement, Args &&... args) |
Execute a prepared statement, expect a result with given number of rows. More... | |
template<typename... Args> | |
result | exec_prepared_n (result::size_type rows, zview statement, Args &&... args) |
![]() | |
namedclass (std::string_view classname) | |
namedclass (std::string_view classname, std::string_view name) | |
namedclass (std::string_view classname, char const name[]) | |
namedclass (std::string_view classname, std::string &&name) | |
const std::string & | name () const noexcept |
Object name, or the empty string if no name was given. More... | |
const std::string & | classname () const noexcept |
Class name. More... | |
std::string | description () const |
Combination of class name and object name; or just class name. 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 (std::string const &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... | |
transaction_base (connection &c) | |
Create a transaction (to be called by implementation classes only). More... | |
void | register_transaction () |
Register this transaction with the connection. More... | |
void | close () noexcept |
End transaction. To be called by implementing class' destructor. More... | |
virtual void | do_commit ()=0 |
To be implemented by derived implementation class: commit transaction. More... | |
virtual void | do_abort ()=0 |
To be implemented by derived implementation class: abort transaction. More... | |
result | direct_exec (std::string_view) |
Execute query on connection directly. More... | |
result | direct_exec (std::shared_ptr< std::string >) |
Interface definition (and common code) for "transaction" classes.
Abstract base class for all transaction types.
|
delete |
|
delete |
|
pure virtual |
|
explicitprotected |
Create a transaction (to be called by implementation classes only).
The optional name, if nonempty, must begin with a letter and may contain letters and digits only.
Common code and definitions for the transaction classes.
pqxx::transaction_base defines the interface for any abstract class that represents a database transaction.
Copyright (c) 2000-2020, Jeroen T. Vermeulen.
See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.
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(), and pqxx::transaction< ISOLATION, READWRITE >::~transaction().
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::raw_connection(), pqxx::largeobject::remove(), pqxx::subtransaction::subtransaction(), and pqxx::largeobject::to_file().
|
protected |
|
protected |
Execute query on connection directly.
|
protectedpure virtual |
To be implemented by derived implementation class: abort transaction.
|
protectedpure virtual |
To be implemented by derived implementation class: commit transaction.
std::string pqxx::transaction_base::esc | ( | char const | text[], |
size_t | maxlen | ||
) | const |
Escape string for use as SQL string literal in this transaction.
std::string pqxx::transaction_base::esc | ( | std::string const & | text | ) | const |
Escape string for use as SQL string literal in this transaction.
std::string pqxx::transaction_base::esc_like | ( | std::string const & | bin, |
char | escape_char = '\\' |
||
) | const |
Escape string for literal LIKE match.
std::string pqxx::transaction_base::esc_raw | ( | std::string const & | bin | ) | const |
Escape binary data for use as SQL string literal in this transaction.
std::string pqxx::transaction_base::esc_raw | ( | unsigned char const | data[], |
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.
pqxx::result pqxx::transaction_base::exec | ( | std::string_view | query, |
std::string const & | desc = std::string{} |
||
) |
Execute query.
Perform a query in this transaction.
This is one of the most important functions in libpqxx.
Most libpqxx exceptions can be thrown from here, including sql_error, broken_connection, and many sql_error subtypes such as feature_not_supported or insufficient_privilege. But any exception thrown by the C++ standard library may also occur here. All exceptions will be derived from std::exception.
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 const & | desc = std::string{} |
||
) |
result pqxx::transaction_base::exec0 | ( | std::string const & | query, |
std::string const & | desc = std::string{} |
||
) |
Execute query, which should zero rows of data.
Works like exec, but fails if the result contains data. It still returns a result, however, which may contain useful metadata.
unexpected_rows | If the query returned the wrong number of rows. |
row pqxx::transaction_base::exec1 | ( | std::string const & | query, |
std::string const & | desc = std::string{} |
||
) |
Execute query returning a single row of data.
Works like exec, but requires the result to contain exactly one row. The row can be addressed directly, without the need to find the first row in a result set.
unexpected_rows | If the query returned the wrong number of rows. |
pqxx::result pqxx::transaction_base::exec_n | ( | result::size_type | rows, |
std::string const & | query, | ||
std::string const & | desc = std::string{} |
||
) |
Execute query, expect given number of rows.
Works like exec, but checks that the number of rows is exactly what's expected.
unexpected_rows | If the query returned the wrong number of rows. |
References pqxx::result::empty(), and pqxx::to_string().
result pqxx::transaction_base::exec_params | ( | std::string const & | query, |
Args &&... | args | ||
) |
Execute an SQL statement with parameters.
result pqxx::transaction_base::exec_params0 | ( | std::string const & | query, |
Args &&... | args | ||
) |
unexpected_rows | if the result contains rows. |
row pqxx::transaction_base::exec_params1 | ( | std::string const & | 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 | ( | size_t | rows, |
std::string const & | query, | ||
Args &&... | args | ||
) |
unexpected_rows | if the result contains the wrong number of rows. |
result pqxx::transaction_base::exec_prepared | ( | std::string const & | statement, |
Args &&... | args | ||
) |
Execute a prepared statement, with optional arguments.
References pqxx::zview::c_str().
result pqxx::transaction_base::exec_prepared | ( | zview | statement, |
Args &&... | args | ||
) |
result pqxx::transaction_base::exec_prepared0 | ( | std::string const & | statement, |
Args &&... | args | ||
) |
Execute a prepared statement, and expect a result with zero rows.
pqxx::unexpected_rows | if the result contained rows. |
result pqxx::transaction_base::exec_prepared0 | ( | zview | statement, |
Args &&... | args | ||
) |
row pqxx::transaction_base::exec_prepared1 | ( | std::string const & | 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().
row pqxx::transaction_base::exec_prepared1 | ( | zview | statement, |
Args &&... | args | ||
) |
References pqxx::row::front().
result pqxx::transaction_base::exec_prepared_n | ( | result::size_type | rows, |
std::string const & | statement, | ||
Args &&... | args | ||
) |
Execute a prepared statement, expect a result with given number of rows.
pqxx::unexpected_rows | if the result did not contain exactly the given number of rows. |
result pqxx::transaction_base::exec_prepared_n | ( | result::size_type | rows, |
zview | statement, | ||
Args &&... | args | ||
) |
std::string pqxx::transaction_base::get_variable | ( | std::string_view | var | ) |
Read session variable using SQL "SHOW" command.
|
delete |
void pqxx::transaction_base::process_notice | ( | char const | msg[] | ) | const |
Have connection process a warning message.
void pqxx::transaction_base::process_notice | ( | std::string const & | msg | ) | const |
Have connection process a warning message.
TYPE pqxx::transaction_base::query_value | ( | std::string const & | query, |
std::string const & | desc = std::string{} |
||
) |
Execute query, expecting exactly 1 row with 1 field.
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 | ( | std::string const & | bin | ) | const |
std::string pqxx::transaction_base::quote_raw | ( | unsigned char const | bin[], |
size_t | len | ||
) | const |
Binary-escape and quote a binarystring for use as an SQL constant.
|
protected |
Register this transaction with the connection.
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. |
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 | ( | std::string 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.
|
friend |