libpqxx
7.7.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 (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... | |
constexpr connection & | conn () const noexcept |
The connection in which this transaction lives. More... | |
void | set_variable (std::string_view var, std::string_view value) |
Set session variable using SQL "SET" command. More... | |
std::string | get_variable (std::string_view) |
Read session variable using SQL "SHOW" command. More... | |
std::string_view | name () const &noexcept |
Transaction name, if you passed one to the constructor; or empty string. More... | |
template<> | |
zview | query_value (zview query, std::string_view desc)=delete |
Forbidden specialisation: underlying buffer immediately goes out of scope. More... | |
template<typename... ARGS> | |
auto | esc (ARGS &&...args) const |
Escape string for use as SQL string literal in this transaction. More... | |
template<typename... ARGS> | |
auto | esc_raw (ARGS &&...args) const |
Escape binary data for use as SQL string literal in this transaction. More... | |
std::string | unesc_raw (zview text) const |
Unescape binary data, e.g. from a table field or notification payload. More... | |
std::basic_string< std::byte > | unesc_bin (zview text) |
Unescape binary data, e.g. from a table field or notification payload. More... | |
std::string | unesc_raw (char const *text) const |
Unescape binary data, e.g. from a table field or notification payload. More... | |
std::basic_string< std::byte > | unesc_bin (char const text[]) |
Unescape binary data, e.g. from a table field or notification payload. More... | |
template<typename T > | |
std::string | quote (T const &t) const |
Represent object as SQL string, including quoting & escaping. More... | |
std::string | quote (binarystring const &t) const |
std::string | quote_raw (unsigned char const bin[], std::size_t len) const |
Binary-escape and quote a binary string for use as an SQL constant. More... | |
std::string | quote_raw (zview bin) const |
Binary-escape and quote a binary string for use as an SQL constant. More... | |
std::string | quote_name (std::string_view identifier) const |
Escape an SQL identifier for use in a query. More... | |
std::string | esc_like (std::string_view bin, char escape_char='\\') const |
Escape string for literal LIKE match. More... | |
Command execution | |
There are many functions for executing (or "performing") a command (or "query"). This is the most fundamental thing you can do with the library, and you always do it from a transaction class. Command execution can throw many types of exception, including sql_error, broken_connection, and many sql_error subtypes such as feature_not_supported or insufficient_privilege. But any exception thrown by the C++ standard library may also occur here. All exceptions you will see libpqxx are derived from std::exception. One unusual feature in libpqxx is that you can give your query a name or description. This does not mean anything to the database, but sometimes it can help libpqxx produce more helpful error messages, making problems in your code easier to debug. | |
result | exec (std::string_view query, std::string_view desc=std::string_view{}) |
Execute a command. More... | |
result | exec (std::stringstream const &query, std::string_view desc=std::string_view{}) |
Execute a command. More... | |
result | exec0 (zview query, std::string_view desc=std::string_view{}) |
Execute command, which should return zero rows of data. More... | |
row | exec1 (zview query, std::string_view desc=std::string_view{}) |
Execute command returning a single row of data. More... | |
result | exec_n (result::size_type rows, zview query, std::string_view desc=std::string_view{}) |
Execute command, expect given number of rows. More... | |
template<typename TYPE > | |
TYPE | query_value (zview query, std::string_view desc=std::string_view{}) |
Perform query, expecting exactly 1 row with 1 field, and convert it. More... | |
template<typename... TYPE> | |
auto | stream (std::string_view query) & |
Execute a query, and loop over the results row by row. More... | |
Parameterized statements | |
You'll often need parameters in the queries you execute: "select the car with this licence plate." If the parameter is a string, you need to quote it and escape any special characters inside it, or it may become a target for an SQL injection attack. If it's an integer (for example), you need to convert it to a string, but in the database's format, without locale-specific niceties like "," separators between the thousands. Parameterised statements are an easier and safer way to do this. They're like prepared statements, but for a single use. You don't need to name them, and you don't need to prepare them first. Your query will include placeholders like 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 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.
| |
template<typename... Args> | |
result | exec_prepared (zview statement, Args &&...args) |
Execute a prepared statement, with optional arguments. More... | |
template<typename... Args> | |
row | exec_prepared1 (zview statement, Args &&...args) |
Execute a prepared statement, and expect a single-row result. More... | |
template<typename... Args> | |
result | exec_prepared0 (zview statement, Args &&...args) |
Execute a prepared statement, and expect a result with zero rows. More... | |
template<typename... Args> | |
result | exec_prepared_n (result::size_type rows, zview statement, Args &&...args) |
Execute a prepared statement, expect a result with given number of rows. More... | |
Error/warning output | |
void | process_notice (char const msg[]) const |
Have connection process a warning message. More... | |
void | process_notice (zview msg) const |
Have connection process a warning message. More... | |
Protected Member Functions | |
transaction_base (connection &c, std::string_view tname, std::shared_ptr< std::string > rollback_cmd) | |
Create a transaction (to be called by implementation classes only). More... | |
transaction_base (connection &c, std::string_view tname) | |
Create a transaction (to be called by implementation classes only). More... | |
transaction_base (connection &c) | |
Create a transaction (to be called by implementation classes only). More... | |
void | register_transaction () |
Register this transaction with the connection. More... | |
void | close () noexcept |
End transaction. To be called by implementing class' destructor. More... | |
virtual void | do_commit ()=0 |
To be implemented by derived implementation class: commit transaction. More... | |
virtual void | do_abort () |
Transaction type-specific way of aborting a transaction. More... | |
void | set_rollback_cmd (std::shared_ptr< std::string > cmd) |
Set the rollback command. More... | |
result | direct_exec (std::string_view, std::string_view desc=""sv) |
Execute query on connection directly. More... | |
result | direct_exec (std::shared_ptr< std::string >, std::string_view desc=""sv) |
Friends | |
class | pqxx::internal::gate::transaction_transaction_focus |
Interface definition (and common code) for "transaction" classes.
Abstract base class for all transaction types.
|
delete |
|
delete |
|
delete |
|
pure virtual |
References conn(), pqxx::connection::process_notice(), and process_notice().
|
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.
References close(), do_abort(), and pqxx::connection::process_notice().
Referenced by close().
|
protectednoexcept |
End transaction. To be called by implementing class' destructor.
References abort(), pqxx::internal::check_unique_register(), pqxx::internal::check_unique_unregister(), pqxx::transaction_focus::classname(), conn(), and pqxx::transaction_focus::name().
Referenced by abort(), commit(), and pqxx::subtransaction::~subtransaction().
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.
References close(), pqxx::transaction_focus::description(), do_commit(), pqxx::connection::is_open(), and pqxx::connection::process_notice().
|
noexcept |
The connection in which this transaction lives.
Referenced by pqxx::internal::basic_robusttransaction::basic_robusttransaction(), pqxx::internal::basic_transaction::basic_transaction(), pqxx::pipeline::cancel(), close(), pqxx::blob::create(), direct_exec(), exec_n(), pqxx::blob::from_buf(), pqxx::stream_from::get_raw_line(), get_variable(), pqxx::largeobject::largeobject(), pqxx::stream_to::operator<<(), quote_raw(), pqxx::largeobject::raw_connection(), register_transaction(), pqxx::blob::remove(), pqxx::largeobject::remove(), pqxx::pipeline::resume(), set_variable(), pqxx::stream_from::stream_from(), pqxx::subtransaction::subtransaction(), pqxx::stream_to::table(), pqxx::stream_from::table(), pqxx::largeobjectaccess::tell(), pqxx::largeobject::to_file(), pqxx::blob::write(), and ~transaction_base().
|
protected |
Execute query on connection directly.
References conn().
Referenced by pqxx::internal::basic_robusttransaction::basic_robusttransaction(), pqxx::internal::basic_transaction::basic_transaction(), do_abort(), exec(), pqxx::subtransaction::subtransaction(), and pqxx::subtransaction::~subtransaction().
|
protected |
References conn(), pqxx::internal::describe_object(), name(), and process_notice().
|
protectedvirtual |
Transaction type-specific way of aborting a transaction.
References direct_exec().
Referenced by abort(), and pqxx::internal::basic_robusttransaction::basic_robusttransaction().
|
protectedpure virtual |
To be implemented by derived implementation class: commit transaction.
Referenced by commit().
pqxx::result pqxx::transaction_base::exec | ( | std::string_view | query, |
std::string_view | desc = std::string_view{} |
||
) |
Execute a command.
query | Query or command to execute. |
desc | Optional identifier for query, to help pinpoint SQL errors. |
References direct_exec().
Referenced by exec_n(), and pqxx::pipeline::resume().
result pqxx::transaction_base::exec | ( | std::stringstream const & | query, |
std::string_view | desc = std::string_view{} |
||
) |
Execute a command.
query | Query or command to execute. |
desc | Optional identifier for query, to help pinpoint SQL errors. |
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.
unexpected_rows | If the query returned the wrong number of rows. |
Referenced by pqxx::stream_from::stream_from().
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.
unexpected_rows | If the query returned the wrong number of rows. |
References pqxx::row::front().
pqxx::result pqxx::transaction_base::exec_n | ( | result::size_type | rows, |
zview | query, | ||
std::string_view | desc = std::string_view{} |
||
) |
Execute command, expect given number of rows.
Works like exec, but checks that the result has exactly the expected number of rows.
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.
References pqxx::params::make_c_params().
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.
Start a block of deprecated code which may call other deprecated code.
Most compilers will emit warnings when deprecated code is invoked from non-deprecated code. But some compilers (notably gcc) will always emit the warning, even when the calling code is also deprecated.
This header starts a block where those warnings are suppressed. It can be included inside a code block.
Always match the #include with a closing #include of "ignore-deprecated-post.hxx". To avoid mistakes, keep the enclosed area as small as possible.
End a code block started by "ignore-deprecated-pre.hxx".
References conn(), and pqxx::connection::get_variable().
|
noexcept |
Transaction name, if you passed one to the constructor; or empty string.
Referenced by pqxx::internal::basic_robusttransaction::basic_robusttransaction(), pqxx::internal::basic_transaction::basic_transaction(), pqxx::connection::close(), and direct_exec().
|
delete |
|
delete |
void pqxx::transaction_base::process_notice | ( | char const | msg[] | ) | const |
Have connection process a warning message.
Referenced by pqxx::internal::basic_transaction::basic_transaction(), direct_exec(), pqxx::largeobjectaccess::process_notice(), and ~transaction_base().
void pqxx::transaction_base::process_notice | ( | zview | msg | ) | const |
Have connection process a warning message.
TYPE pqxx::transaction_base::query_value | ( | zview | query, |
std::string_view | desc = std::string_view{} |
||
) |
Perform query, expecting exactly 1 row with 1 field, and convert it.
This is convenience shorthand for querying exactly one value from the database. It returns that value, converted to the type you specify.
Forbidden specialisation: underlying buffer immediately goes out of scope.
|
protected |
Register this transaction with the connection.
References conn().
Referenced by pqxx::internal::basic_transaction::basic_transaction().
|
protected |
Set the rollback command.
Referenced by pqxx::subtransaction::subtransaction().
void pqxx::transaction_base::set_variable | ( | std::string_view | var, |
std::string_view | value | ||
) |
Set session variable using SQL "SET" command.
SET
command. To set a session variable, use the connection's set_session_var function.var | The variable to set. |
value | The new value to store in the variable. This can be any SQL expression. |
Start a block of deprecated code which may call other deprecated code.
Most compilers will emit warnings when deprecated code is invoked from non-deprecated code. But some compilers (notably gcc) will always emit the warning, even when the calling code is also deprecated.
This header starts a block where those warnings are suppressed. It can be included inside a code block.
Always match the #include with a closing #include of "ignore-deprecated-post.hxx". To avoid mistakes, keep the enclosed area as small as possible.
End a code block started by "ignore-deprecated-pre.hxx".
References conn(), and pqxx::connection::set_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 stream lives entirely within the lifetime of the transaction. Make sure you destroy the stream before you destroy the transaction. Also, either iterate the stream all the way to the end, or destroy first the stream and then the transaction without touching either in any other way. Until the stream has finished, the transaction is in a special state where it cannot execute queries.
As a special case, tuple may contain std::string_view
fields, but the strings to which they point will only remain valid until you extract the next row. After that, the memory holding the string may be overwritten or deallocated.
If any of the columns can be null, and the C++ type to which it translates does not have a null value, wrap the type in std::optional
(or if you prefer, std::shared_ptr
or std::unique_ptr)
. These templates do recognise null values, and libpqxx will know how to convert to them.
The connection is in a special state until the iteration finishes. So if it does not finish due to a break
or a return
or an exception, then the entire connection becomes effectively unusable.
Querying in this way is faster than the exec()
methods for larger results (but probably slower for small ones). Also, you can start processing rows before the full result is in. Also, stream()
scales better in terms of memory usage. Where exec() reads the entire result into memory at once, stream()
will read and process one row at at a time.
Your query executes as part of a COPY command, not as a stand-alone query, so there are limitations to what you can do in the query. It can be either a SELECT or VALUES query; or an INSERT, UPDATE, or DELETE with a RETURNING clause. See the documentation for PostgreSQL's COPY command for the details:
https://www.postgresql.org/docs/current/sql-copy.html
Iterating in this way does require each of the field types you pass to be default-constructible, copy-constructible, and assignable. These requirements may be loosened once libpqxx moves on to C++20.
References pqxx::params::make_c_params(), and pqxx::stream_from::query().
|
friend |